Skip to content
AggregaAggrega
Select language: English

Aggrega Background Daemon Wire Protocol schema

Generated reference. Do not edit by hand — regenerate from the published JSON Schema.

Schema id: https://aggrega.ai/schemas/serve-wire-v1beta1.schema.json

The message shapes exchanged with a background compiler daemon started by aggrega serve. A client opens a session over that daemon with the handshake, and the session is what scopes the settings and the workspace the conversation was opened over; the daemon is the process that answers a request, sends a notification and holds what it has read. The protocol is JSON-RPC 2.0 over standard input and output, each message framed by a Content-Length header; this document describes the message bodies and neither the framing nor the transport. A body is one of four things: a request the client sends, a notification the client sends, a notification the daemon sends, or the response the daemon returns for a request. Three properties of the surface decide how the shapes below are written. First, every request admits two fields beyond the ones its own method declares — workspaceRoot, naming the workspace the request acts on, and workDoneToken, the caller-minted value progress is reported under — so both appear on every request params object here, including the three methods whose subject is not a workspace: aggrega/getSchema and aggrega/scaffoldEntity accept workspaceRoot and ignore it, and aggrega/initialize reads it as the workspace the session declares. Second, the daemon refuses a request params object carrying a field the method does not accept, naming what it does accept, so every params object here is closed at its top level; a nested object inside a request is not closed, because the check reads only the outermost field names. Third, a result is composed by the daemon rather than supplied by a caller, so result objects are closed at every level whose shape is fixed, and open only where the value is opaque JSON the daemon carries through without reading. One consequence of the daemon’s encoding is visible on the wire and is described rather than tidied away: a collection the daemon does not mark optional is emitted as null when it has no value to report and as an empty collection when the value it reports is empty, so both forms are admitted wherever that applies.

One of the following shapes

  • Request
  • ClientNotification
  • DaemonNotification
  • SuccessResponse
  • ErrorResponse

Definitions

ProtocolVersion

The JSON-RPC version every message carries. Only 2.0 is spoken.

Type: const "2.0"

Constant: "2.0"

RequestId

The caller’s identifier for a request, echoed on the response that answers it. A message carrying no identifier is a notification and is never answered.

Type: string or number

ProgressToken

A value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.

Type: string or number

WorkspaceRootSubject

The absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.

Type: string

WorkspaceRootAccepted

The absolute path of a workspace. This method’s subject is not a workspace — it answers from what the binary itself carries — so the field is accepted and not read. It is admitted because a client may send it uniformly on every request without having to know which methods consult it.

Type: string

RequestMethod

Every method a request may name. The set is closed: a request naming anything else is answered with a method-not-found error.

Type: string (enum)

Allowed values: "aggrega/activeRelease", "aggrega/attachCandidates", "aggrega/attachmentContainer", "aggrega/build", "aggrega/buildPreview", "aggrega/cacheClear", "aggrega/cacheEvict", "aggrega/cachePrune", "aggrega/cacheStatus", "aggrega/catalogIndex", "aggrega/completion", "aggrega/configCapture", "aggrega/configInit", "aggrega/connectionAtPosition", "aggrega/connectionCandidates", "aggrega/deprecateArtifact", "aggrega/diagnostics", "aggrega/editDocument", "aggrega/effectiveConfiguration", "aggrega/entityDefinition", "aggrega/explainError", "aggrega/findImplementations", "aggrega/findReferences", "aggrega/getSchema", "aggrega/hover", "aggrega/import", "aggrega/initialize", "aggrega/insertionPoint", "aggrega/invalidate", "aggrega/irGraph", "aggrega/lint", "aggrega/logout", "aggrega/pin", "aggrega/pluginAdd", "aggrega/pluginGenCatalog", "aggrega/pluginRemove", "aggrega/pluginSync", "aggrega/publishArtifact", "aggrega/publishEntity", "aggrega/registryAdd", "aggrega/registryList", "aggrega/registryRemove", "aggrega/registryUpdate", "aggrega/releaseCandidates", "aggrega/releaseClosure", "aggrega/resolve", "aggrega/resolveDependencies", "aggrega/scaffoldEntity", "aggrega/search", "aggrega/setActiveRelease", "aggrega/signArtifacts", "aggrega/skillsInstall", "aggrega/skillsList", "aggrega/validate"

ClientNotificationMethod

Every method a client notification may name. The set is closed, and neither notification is answered.

Type: string (enum)

Allowed values: "$/cancelRequest", "aggrega/shutdown"

DaemonNotificationMethod

Every method a notification the daemon sends may name. The set is closed.

Type: string (enum)

Allowed values: "$/progress", "aggrega/publishDiagnostics"

Request

A request the client sends and the daemon answers. The method names what is being asked; the params object carries that method’s own fields plus the two every method admits. A request that omits params entirely is read as one whose fields are all absent.

PropertyTypeRequiredDescription
jsonrpcProtocolVersionyesThe JSON-RPC version every message carries. Only 2.0 is spoken.
idRequestIdyesThe caller’s identifier for a request, echoed on the response that answers it. A message carrying no identifier is a notification and is never answered.
methodRequestMethodyesEvery method a request may name. The set is closed: a request naming anything else is answered with a method-not-found error.
paramsobjectno

Additional properties are not permitted.

params for each method:

methodparamsRequired
"aggrega/initialize"InitializeParamsno
"aggrega/validate"ValidateParamsno
"aggrega/invalidate"InvalidateParamsno
"aggrega/diagnostics"DiagnosticsParamsno
"aggrega/irGraph"IrGraphParamsno
"aggrega/build"BuildParamsno
"aggrega/buildPreview"BuildPreviewParamsno
"aggrega/entityDefinition"EntityDefinitionParamsno
"aggrega/releaseClosure"ReleaseClosureParamsno
"aggrega/resolveDependencies"ResolveDependenciesParamsno
"aggrega/pin"PinParamsno
"aggrega/cacheStatus"WorkspaceAndProgressParamsno
"aggrega/cachePrune"WorkspaceAndProgressParamsno
"aggrega/cacheEvict"CacheEvictParamsno
"aggrega/cacheClear"WorkspaceAndProgressParamsno
"aggrega/registryList"WorkspaceAndProgressParamsno
"aggrega/search"SearchParamsno
"aggrega/registryAdd"RegistryAddParamsno
"aggrega/registryRemove"RegistryRemoveParamsno
"aggrega/registryUpdate"RegistryUpdateParamsno
"aggrega/logout"LogoutParamsno
"aggrega/publishEntity"PublishEntityParamsno
"aggrega/publishArtifact"PublishArtifactParamsno
"aggrega/signArtifacts"SignArtifactsParamsno
"aggrega/deprecateArtifact"DeprecateArtifactParamsno
"aggrega/resolve"ResolveParamsno
"aggrega/findReferences"FindReferencesParamsno
"aggrega/findImplementations"FindImplementationsParamsno
"aggrega/hover"HoverParamsno
"aggrega/completion"CompletionParamsno
"aggrega/catalogIndex"CatalogIndexParamsno
"aggrega/attachCandidates"AttachCandidatesParamsno
"aggrega/connectionCandidates"ConnectionCandidatesParamsno
"aggrega/insertionPoint"InsertionPointParamsno
"aggrega/attachmentContainer"AttachmentContainerParamsno
"aggrega/connectionAtPosition"ConnectionAtPositionParamsno
"aggrega/releaseCandidates"WorkspaceAndProgressParamsno
"aggrega/activeRelease"WorkspaceAndProgressParamsno
"aggrega/setActiveRelease"SetActiveReleaseParamsno
"aggrega/editDocument"EditDocumentParamsno
"aggrega/effectiveConfiguration"WorkspaceAndProgressParamsno
"aggrega/configInit"ConfigInitParamsno
"aggrega/configCapture"ConfigCaptureParamsno
"aggrega/import"ImportParamsno
"aggrega/scaffoldEntity"ScaffoldEntityParamsno
"aggrega/lint"LintParamsno
"aggrega/pluginAdd"PluginAddParamsno
"aggrega/pluginRemove"PluginRemoveParamsno
"aggrega/pluginSync"PluginSyncParamsno
"aggrega/pluginGenCatalog"PluginGenCatalogParamsno
"aggrega/explainError"ExplainErrorParamsno
"aggrega/getSchema"GetSchemaParamsno
"aggrega/skillsInstall"SkillsInstallParamsno
"aggrega/skillsList"WorkspaceAndProgressParamsno

ClientNotification

A notification the client sends. It carries no identifier and is never answered.

PropertyTypeRequiredDescription
jsonrpcProtocolVersionyesThe JSON-RPC version every message carries. Only 2.0 is spoken.
methodClientNotificationMethodyesEvery method a client notification may name. The set is closed, and neither notification is answered.
paramsobjectno

Additional properties are not permitted.

params for each method:

methodparamsRequired
"$/cancelRequest"CancelRequestParamsyes
"aggrega/shutdown"ShutdownParamsno

DaemonNotification

A notification the daemon sends. It carries no identifier and is never answered.

PropertyTypeRequiredDescription
jsonrpcProtocolVersionyesThe JSON-RPC version every message carries. Only 2.0 is spoken.
methodDaemonNotificationMethodyesEvery method a notification the daemon sends may name. The set is closed.
paramsobjectyes

Additional properties are not permitted.

params for each method:

methodparamsRequired
"$/progress"ProgressParamsyes
"aggrega/publishDiagnostics"PublishDiagnosticsParamsyes

CancelRequestParams

Asks the daemon to abandon a request already in flight, naming it by the identifier the request carried. A request already finished, or never sent, is silently nothing to cancel.

PropertyTypeRequiredDescription
idRequestIdyesThe caller’s identifier for a request, echoed on the response that answers it. A message carrying no identifier is a notification and is never answered.

Additional properties are not permitted.

ShutdownParams

Asks the daemon to stop accepting work and finish what it has already taken. The notification carries no fields, and the notification itself is usually sent with no params object at all. A second one abandons the work still in flight instead of waiting for it.

This object declares no fixed properties and permits none.

ProgressParams

One report of work in progress, sent only for a request that minted a progress token in a session that declared it could receive them.

PropertyTypeRequiredDescription
tokenProgressTokenyesA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
valueProgressBegin or ProgressReport or ProgressEndyesThe report itself. One opening report, then any number of lines, then one closing report.

Additional properties are not permitted.

ProgressBegin

Opens a report, saying what has started in the terms the operation itself uses.

PropertyTypeRequiredDescription
kindconst “begin”yesMarks this payload as the opening of a report. Constant: "begin"
titlestringyesWhat has started.

Additional properties are not permitted.

ProgressReport

One line of the operation’s own account of itself. It carries no fraction: the operations that report here work through a set whose size is not known when the work starts, so a fraction would have to be invented.

PropertyTypeRequiredDescription
kindconst “report”yesMarks this payload as one line of an open report. Constant: "report"
messagestringyesOne line of the operation’s own output, with surrounding whitespace removed.

Additional properties are not permitted.

ProgressEnd

Closes a report. It carries nothing beyond the kind, because the outcome travels on the response the caller is already waiting for.

PropertyTypeRequiredDescription
kindconst “end”yesMarks this payload as the close of a report. Constant: "end"

Additional properties are not permitted.

PublishDiagnosticsParams

The findings for one file, pushed by the daemon when a validation produced them for a document other than the one the request named.

PropertyTypeRequiredDescription
filestringyesThe file the findings are about.
diagnosticsDiagnostic[] or nullyesThe findings, in the order they were produced.

Additional properties are not permitted.

SuccessResponse

The answer to a request that succeeded, carrying the identifier of the request it answers. A response carries no method, so which result shape applies is fixed by the request the identifier belongs to rather than by anything in the response itself.

PropertyTypeRequiredDescription
jsonrpcProtocolVersionyesThe JSON-RPC version every message carries. Only 2.0 is spoken.
idRequestIdyesThe caller’s identifier for a request, echoed on the response that answers it. A message carrying no identifier is a notification and is never answered.
resultInitializeResult or ValidateResult or InvalidateResult or DiagnosticsResult or IrGraphResult or BuildResult or BuildPreviewResult or EntityDefinitionResult or ReleaseClosureResult or ResolveDependenciesResult or PinResult or CacheStatusResult or CachePruneResult or CacheEvictResult or CacheClearResult or RegistryListResult or SearchResult or RegistryAddResult or RegistryRemoveResult or RegistryUpdateResult or LogoutResult or PublishEntityResult or PublishArtifactResult or SignArtifactsResult or DeprecateArtifactResult or ResolveResult or FindReferencesResult or FindImplementationsResult or HoverResult or CompletionResult or CatalogIndexResult or AttachCandidatesResult or ConnectionCandidatesResult or InsertionPointResult or AttachmentContainerResult or ConnectionAtPositionResult or ReleaseCandidatesResult or ActiveReleaseResult or EditDocumentResult or EffectiveConfigurationResult or ConfigInitResult or ConfigCaptureResult or ImportResult or ScaffoldEntityResult or LintResult or PluginAddResult or PluginRemoveResult or PluginSyncResult or PluginGenCatalogResult or ExplainErrorResult or GetSchemaResult or SkillsInstallResult or SkillsListResultyesThe answer, in the shape the method that was asked returns.

Additional properties are not permitted.

ErrorResponse

The answer to a request that was refused or failed, carrying the identifier of the request it answers.

PropertyTypeRequiredDescription
jsonrpcProtocolVersionyesThe JSON-RPC version every message carries. Only 2.0 is spoken.
idRequestIdyesThe caller’s identifier for a request, echoed on the response that answers it. A message carrying no identifier is a notification and is never answered.
errorErrorObjectyesWhat went wrong: a code a client may branch on, a message written for a person to read, and — where the condition has one — the artifacts and source position the message refers to.

Additional properties are not permitted.

ErrorObject

What went wrong: a code a client may branch on, a message written for a person to read, and — where the condition has one — the artifacts and source position the message refers to.

PropertyTypeRequiredDescription
codeErrorCodeyesThe condition the answer reports. The negative codes are the protocol’s own reserved set; the four-digit codes are conditions this daemon raises, each naming a state a client can act on. The set is closed.
messagestringyesWhat went wrong, in prose. It is the same wording the same condition carries on every other surface that reports it.
dataErrorDatanoThe artifacts and source position the message refers to, carried structurally so a client need not read them back out of the prose. Every field is optional and a condition populates only what it has in hand; no field stands in for another, so a client learns what it received from the field it read rather than from the code beside it.

Additional properties are not permitted.

ErrorCode

The condition the answer reports. The negative codes are the protocol’s own reserved set; the four-digit codes are conditions this daemon raises, each naming a state a client can act on. The set is closed.

Type: const -32700 or const -32600 or const -32601 or const -32602 or const -32603 or const 1001 or const 1003 or const 1004 or const 1005 or const 1006

Allowed values:

  • -32700 — The message could not be parsed as JSON.
  • -32600 — The message parsed but is not a well-formed request.
  • -32601 — No method of that name exists.
  • -32602 — The params the request carried are not admissible: a field the method does not accept, a field of the wrong type, or a value the method refuses.
  • -32603 — The daemon failed while doing the work.
  • 1001 — The daemon holds no reading of the file and is producing none. The client seeds one by asking for a validation, then retries.
  • 1003 — The lockfile for the Release the request named is absent, and the operation needs one.
  • 1004 — The entity the request named could not be resolved from the catalog or from the Release the request named.
  • 1005 — The daemon is shutting down and is refusing new work. The client does not retry against the same daemon.
  • 1006 — A validation of the file is running now and did not finish within the budget the waiting request allowed. The client waits and asks again, sending nothing in the meantime.

ErrorData

The artifacts and source position the message refers to, carried structurally so a client need not read them back out of the prose. Every field is optional and a condition populates only what it has in hand; no field stands in for another, so a client learns what it received from the field it read rather than from the code beside it.

PropertyTypeRequiredDescription
filestringnoThe source document the position fields locate — the document being checked, or the Release whose load failed.
lineintegernoThe line the condition refers to, counted from one.
columnintegernoThe column the condition refers to, counted from one.
end_lineintegernoThe line one past the end of the token the condition refers to. Absent where the token has no recoverable end, in which case a client renders the position as a point.
end_columnintegernoThe column one past the end of the token the condition refers to.
releasestringnoThe Release the condition refers to, spelled the way the request named it, so a client can compose the remedy without reassembling it.
lockfilestringnoThe lockfile a lockfile-scoped condition is about: the path that was looked for and not found, or could not be read.
unreachablebooleannoWhether the refusal is a registry the request named that could not be reached: its name did not resolve, a connection to it was refused or could not be opened, or a secure connection to it could not be established. It is read from the failure itself rather than from the message, and it is set only where the failure shows the registry was never reached. A refused index refresh naming one registry carries it; a registry that answered, whatever it answered, leaves it absent.
codestringnoThe descriptive name of the condition the refusal names, stable across releases: the same value a diagnostic reporting that condition carries in its own code. It is what a client branches on, rather than on the message or on the numeric code beside it, which names the state of the request and stays what it is for every condition. Present exactly when the refusal names a registered condition, and absent when it names none.
shortCodestringnoThe condition’s short code, the letter E and four digits: the form a reader quotes and looks up, and the one that opens the message of a refusal naming a condition. Present exactly when code is.

Additional properties are not permitted.

Diagnostic

One finding about one document: where it is, how serious it is, what it says, and the quotable code that names the condition it reports.

PropertyTypeRequiredDescription
lineintegeryesThe line the finding is about, counted from one.
columnintegeryesThe column the finding is about, counted from one.
severityconst “error” or const “warning” or const “info”yesHow serious the finding is. Allowed values: "error" — The finding is a fault. A plugin finding of halt severity is reported at this tier. "warning" — The finding is reported and is not a fault. A plugin finding of warn severity is reported at this tier. "info" — The finding is information, as a plugin finding of info severity is.
messagestringyesWhat the finding says, in prose.
codestringnoThe condition’s descriptive name, stable across releases and quotable in a suppression.
shortCodestringnoThe condition’s short code, the form that opens a halting diagnostic.
codeDescriptionCodeDescriptionnoWhere the condition the finding names is explained.
classificationstringnoHow the finding was reached, where the condition distinguishes that.
suggeststringnoThe spelling the finding proposes, where the condition can name one — a near-miss on an identifier, for instance.
keyPathstringnoThe path through the document to the key the finding is about.
sourcestringyesWhat produced the finding.
end_lineintegernoThe line one past the end of the token the finding is about, so a client can render the whole token rather than a single character. Absent for a token spanning several lines.
end_columnintegernoThe column one past the end of the token the finding is about.

Additional properties are not permitted.

CodeDescription

Where the condition the finding names is explained.

PropertyTypeRequiredDescription
hrefstringyesThe published address at which the condition is explained.

Additional properties are not permitted.

Position

A place in a document: a line and a character offset within it, both counted from zero. The offset is measured in the units of the encoding the session settled on when it was opened, which is UTF-16 unless the client asked for another.

PropertyTypeRequiredDescription
lineintegeryesThe line, counted from zero.
characterintegeryesThe offset within the line, counted from zero, in the units of the encoding the session settled on.

Additional properties are not permitted.

Range

A span between two places in a document.

PropertyTypeRequiredDescription
startPositionyesA place in a document: a line and a character offset within it, both counted from zero. The offset is measured in the units of the encoding the session settled on when it was opened, which is UTF-16 unless the client asked for another.
endPositionyesA place in a document: a line and a character offset within it, both counted from zero. The offset is measured in the units of the encoding the session settled on when it was opened, which is UTF-16 unless the client asked for another.

Additional properties are not permitted.

Location

A span in a named document.

PropertyTypeRequiredDescription
uristringyesThe document the span is in, addressed as a URI.
rangeRangeyesA span between two places in a document.

Additional properties are not permitted.

WorkspaceAndProgressParams

The params object of a method that declares no fields of its own. It still admits the two fields every request admits: the workspace it acts on, and a progress token.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.

Additional properties are not permitted.

InitializeParams

Opens a session over a workspace and states what the client can handle. This is the one method on which workspaceRoot is a declaration rather than a subject: absent, empty and a path are three different things, and a session opened with no path is one the client has not yet pointed at a workspace.

PropertyTypeRequiredDescription
capabilitiesClientCapabilitiesnoWhat the client can handle. Unstated is taken as unsupported. Unknown members are ignored rather than refused, so a client may state a capability this daemon does not yet read.
workspaceRootstringnoThe absolute path of the workspace to open. Absent leaves the session with no workspace; an empty string is a path the client supplied and is not the same as sending none.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.

Additional properties are not permitted.

ClientCapabilities

What the client can handle. Unstated is taken as unsupported. Unknown members are ignored rather than refused, so a client may state a capability this daemon does not yet read.

PropertyTypeRequiredDescription
generalobjectnoCapabilities that are not tied to one kind of answer.
windowobjectnoCapabilities about what the client can show while work is under way.

Additional properties are permitted.

ClientCapabilities.general

Capabilities that are not tied to one kind of answer.

PropertyTypeRequiredDescription
positionEncodingsstring[]noThe position encodings the client can read, best first.

Additional properties are permitted.

ClientCapabilities.window

Capabilities about what the client can show while work is under way.

PropertyTypeRequiredDescription
workDoneProgressbooleannoWhether the client can receive progress notifications. A request that mints a progress token in a session which did not declare this is refused.

Additional properties are permitted.

ValidateParams

Checks the workspace, or one document in it, and answers with the findings.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
filestringnoThe document to check. Absent checks what the workspace holds.
contentstringnoThe document’s text as the client currently holds it, for checking a buffer that has not been saved. Absent reads the bytes on disk.
releasestringnoThe Release to check against, as a path relative to the workspace root.

Additional properties are not permitted.

InvalidateParams

Tells the daemon that a document it holds a reading of has changed, so the next answer about it is computed from the new bytes.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
filestringnoThe document that changed.
granularitystringnoHow much of what the daemon holds to drop: file drops what it holds for the named document only; workspace, the default and what any other value is read as, also drops what it holds for the whole workspace.

Additional properties are not permitted.

DiagnosticsParams

Answers with the findings the daemon already holds for a document, without checking it again.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
filestringnoThe document to report on. The daemon must already hold a reading of it.

Additional properties are not permitted.

IrGraphParams

Answers with the resolved graph a Release compiles to, without rendering it.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
releasestringnoThe Release to resolve, as a path relative to the workspace root. An absolute path is refused.
unredactedbooleannoWhether to answer with the values an author declared sensitive in the clear. Absent or false, each of them is withheld from the graph and a marker naming why stands in its place, as the command line’s graph output withholds them; true answers with the graph as the Release compiles to it, those values included.

Additional properties are not permitted.

BuildParams

Compiles a Release and writes the rendered artifacts into the workspace.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
releasestringnoThe Release to build, as a path relative to the workspace root. An absolute path is refused.
outputParentstringnoThe directory the output directory is created inside, as a path relative to the workspace root. The artifacts land in the output directory beneath it, laid out as they are beneath the workspace root when nothing is named — so this names the output directory’s parent and never the output directory itself. Absent, or empty, writes the output directory beneath the workspace root, as aggrega build does wherever it is run from. An absolute path, or one that climbs out of the workspace, is refused.
autoPullbooleannoWhether to resolve the Release’s dependencies first. Asking for it reaches the configured registries and writes the lockfile; unasked, the build reaches no registry.
policyInputstringnoThe directory to write, beside the artifacts, the payload each governance role hands a plugin attached there, as a path relative to the workspace root — the files aggrega build --policy-input writes, by the same names, written whether the build finishes or stops. The answer’s notices say how many were written and name each role written no file for. On a request that fails, the files written are on disk and that account is not in the reply: the error carries the refusal alone. Absent writes none. An absolute path, or one that climbs out of the workspace, is refused.

Additional properties are not permitted.

BuildPreviewParams

Compiles a Release and reports what writing the artifacts would have produced, writing none of them. It declines the dependency-resolution field the writing build takes, because a request that writes nothing cannot fill a lockfile.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
releasestringnoThe Release to compile, as a path relative to the workspace root.
autoPullbooleannoAccepted on the wire and refused by the method: this request writes nothing, so it cannot fill a lockfile and remain what it says it is.
policyInputstringnoThe directory to write the payload each governance role hands a plugin attached there into, as a path relative to the workspace root — the files aggrega build --dry-run --policy-input writes, by the same names. Sent, they are the one thing this request writes; the output directory and the lockfile are left untouched. The answer’s notices say how many were written and name each role written no file for. On a request that fails, the files written are on disk and that account is not in the reply: the error carries the refusal alone. An absolute path, or one that climbs out of the workspace, is refused.

Additional properties are not permitted.

EntityDefinitionParams

Answers with what one entity name resolves to and where the document defining it lives.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
namestringnoThe entity to resolve, by name — or a registry reference, oci://<host>/<repository>:<tag> or @<digest> in place of :<tag>, to read the entity published at that coordinate.
releasestringnoThe Release to resolve the name in the terms of, as a path relative to the workspace root. The name is then resolved through the catalog directories the workspace configuration gives that Release, so a name several variants in one workspace declare, one per Release, resolves to the variant that Release builds with, and a name it does not resolve is refused with an account naming that Release’s entry under workspace.releases. Absent, the name is resolved over the workspace’s own catalog directories. A registry reference takes no Release and is refused with one, as is a value that names no Release file.

Additional properties are not permitted.

CatalogIndexParams

Answers with the entities the workspace holds: every entity its documents declare, and the Features its catalog directories declare.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
releasestringnoThe Release to list the entities in the terms of, as a path relative to the workspace root. The Features are then the ones the catalog directories the workspace configuration gives that Release declare, and a document under a catalog directory only other Releases read is left out, so a workspace keeping variants of one entity side by side, one per Release, is listed with the variant that Release builds with. Absent, the listing is the workspace’s own. A value that names no Release file is refused.

Additional properties are not permitted.

ReleaseClosureParams

Answers with everything a Release depends on, as resolution reached it.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
releasestringnoThe Release to inspect, as a path relative to the workspace root.

Additional properties are not permitted.

ResolveDependenciesParams

Resolves a Release’s dependencies, pinning them in the lockfile and acquiring the external inputs its render consumes. It reaches the configured registries and it writes.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
releasestringnoThe Release to resolve, as a path relative to the workspace root.
upgradebooleannoWhether to re-resolve within the declared ranges rather than honouring what the lockfile already pins.
targetsstring[]noThe references to re-resolve, leaving the rest pinned as they are. Empty resolves everything.
verifybooleannoWhether to compare the recorded lockfile against the resolution this request would perform without it, honouring the pins that request would honour, instead of writing it. A verify writes no lockfile, plugin trust record or entity.lock; the content cache is read and filled as that resolution would read and fill it. Drift, and a missing lockfile, fail the request. It cannot be combined with upgrade, targets or pinSources, whichever value pinSources carries: a request sending one of them beside it is refused as invalid params before anything is resolved.
pinSourcesbooleannoWhether to run the pin step aggrega/pin runs over the Recipes and FeatureRecipes the Release builds from the workspace’s catalog directories, writing the entity.lock beside each, rather than refusing the request over one whose lock does not record a pin an input needs. Absent follows the workspace’s pin_sources_at_pull; either value overrides that setting for this request.

Additional properties are not permitted.

PinParams

Records, in the entity.lock beside a Recipe or FeatureRecipe, the content pin for every input the entity reads from outside its own document. No Release is named: an input whose identity the entity writes out in full names one artifact for every Release that uses the entity, so nothing a Release supplies is needed to pin it. It reaches the hosts the entity’s sources name and it writes beside the entity; the entity document itself is never written.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
entitystringnoThe entity document to pin, as a path relative to the workspace root.
dryRunbooleannoWhether to answer with the lock the step would write rather than writing it. The inputs are still resolved, so the content cache still fills.

Additional properties are not permitted.

CacheEvictParams

Reclaims cached content until what remains fits under a size the request names.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
maxSizestringnoThe size to reclaim down to, written the way a person writes one — for instance 500MB.

Additional properties are not permitted.

SearchParams

Searches what the configured registries’ local indexes offer. It reads the index already on disk and contacts no registry.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
querystringnoThe text to match against a record’s name and description.
kindsstring[]noThe entity kinds to keep. Empty keeps every kind.
selectorstringnoA label selector the kept records must satisfy.
capabilitiesstring[]noThe capabilities a kept plugin record must declare.
pluginTypestringnoThe plugin type to keep.
registrystringnoThe one registry host to search. Absent searches every configured host.
limitintegernoThe most records to answer with.
includeRetractedbooleannoWhether to keep versions a published marker has deprecated.

Additional properties are not permitted.

RegistryAddParams

Registers a registry and the trust policy resolution applies to what it serves. It writes the machine-wide configuration file unless the request asks otherwise, so every workspace on the machine resolves through the entry.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
hoststringnoThe registry host to register.
namestringnoA friendly alias that resolves to the host.
identitiesstring[]noThe signing identities trusted for what this registry serves.
keyPathstringnoThe path of a public key to trust, for a registry signed with one rather than with a keyless identity.
trustedRootstringnoThe path of the trust anchor to verify signatures against.
requireSignaturesbooleannoWhether an artifact from this registry must carry a verified signature. Absent states nothing and leaves the resolved default in place.
advisorybooleannoWhether a failed verification is reported rather than halting.
fetchTrustbooleannoWhether to read the trust policy the registry advertises and pin it. Absent states nothing and leaves the resolved default in place.
globalbooleannoWrite the machine-wide configuration file, which is this method’s own default.
workspacebooleannoWrite this workspace’s own configuration file instead of the machine-wide one.

Additional properties are not permitted.

RegistryRemoveParams

Removes a registered registry. It writes the machine-wide configuration file unless the request asks otherwise.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
registrystringnoThe registry to remove, by host or by alias.
globalbooleannoWrite the machine-wide configuration file, which is this method’s own default.
workspacebooleannoWrite this workspace’s own configuration file instead of the machine-wide one.

Additional properties are not permitted.

RegistryUpdateParams

Refreshes the local index a search reads, reaching the registry to do it. What it writes is the index under this workspace’s own configured cache directory. A registry needing a credential no ambient source carries is refused with the credential named, rather than prompted for.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
registrystringnoThe one registry to refresh. Absent refreshes every configured host.
upgradebooleannoWhether to rebuild the index rather than adding to what it already holds.

Additional properties are not permitted.

LogoutParams

Removes a stored registry credential. The store is shared by every project on the machine, and the answer says so.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
registrystringnoThe registry whose stored credential to remove.

Additional properties are not permitted.

PublishEntityParams

Publishes an entity to a registry. What it lands is what every consumer of that registry resolves, and a published version cannot be recalled from anyone who already fetched it. Nothing is prompted for: identity resolves from what the request supplied or what the environment already carries.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
entitystringnoThe entity document to publish, as a path relative to the workspace root.
registrystringnoThe registry to publish to. Absent uses the configured default.
dryRunbooleannoWhether to report what publishing would land without landing it.
signbooleannoWhether to sign what is published. Absent states nothing and leaves the resolved default in place.
pluginstringnoThe plugin module to publish alongside a Plugin entity.
fulcioUrlstringnoThe certificate authority to obtain a signing certificate from.
rekorUrlstringnoThe transparency log to record the signature in.
timestampUrlstringnoThe timestamp authority to countersign with.
identityTokenstringnoThe identity token to sign with, supplied by the caller rather than obtained at a terminal.
pinSourcesbooleannoWhether to run the pin step aggrega/pin runs on the entity before it is bundled, so the entity.lock the step writes beside it is part of what is published. The step runs ahead of every refusal that judges the entity, and under dryRun it reports the lock it would write and writes nothing. Absent follows the workspace’s pin_sources_at_push; either value overrides that setting for this request.

Additional properties are not permitted.

PublishArtifactParams

Publishes an arbitrary file to a registry under a name and tag the request gives it.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
filestringnoThe file to publish, as a path relative to the workspace root.
namestringnoThe repository name to publish under.
tagstringnoThe tag to publish under.
mediaTypestringnoThe media type to record for the published bytes.
registrystringnoThe registry to publish to. Absent uses the configured default.
dryRunbooleannoWhether to report what publishing would land without landing it.

Additional properties are not permitted.

SignArtifactsParams

Signs what is already published. A signature cannot be recalled from anyone who already fetched it.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
referencesstring[]noThe published references to sign.
fulcioUrlstringnoThe certificate authority to obtain a signing certificate from.
rekorUrlstringnoThe transparency log to record the signature in.
timestampUrlstringnoThe timestamp authority to countersign with.
identityTokenstringnoThe identity token to sign with, supplied by the caller rather than obtained at a terminal.
jobsintegernoHow many references are signed at once. Absent signs one after another. Each reference is still signed exactly as it would be alone — when keyless, with its own certificate and its own transparency-log entry — and the answer keeps the order the references were given. Minimum: 1.

Additional properties are not permitted.

DeprecateArtifactParams

Marks a published version as deprecated, so resolution can report or decline it. The marker is itself published and signed. A request sends either one reference with its content, or a batch file whose entries carry their own — never both, and never content beside the batch file.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
referencestringnoThe published reference to mark. An alternative to from: a request carrying both is refused.
severityconst “warning” or const “error” or const “retracted”noHow strongly the marker speaks — whether resolution reports the version or declines it. Required with reference; refused beside from, whose batch file carries each marker’s own. Allowed values: "warning" — Deprecated, at the milder of the two advisory tiers: still selected when a version is chosen. "error" — Deprecated, at the stronger of the two advisory tiers: still selected when a version is chosen. "retracted" — Withdrawn: excluded when a version is chosen.
reasonstringnoWhy the version is deprecated. Required with reference; refused beside from, whose batch file carries each marker’s own.
replacementstringnoThe reference to use instead. Refused beside from, whose batch file carries each marker’s own.
messagestringnoWhat a consumer meeting the marker is told. Refused beside from, whose batch file carries each marker’s own.
fromstringnoA batch file of withdrawal entries, as a path relative to the workspace root, attaching one marker per entry. Each entry carries its own reference, severity and reason, and optionally a replacement and a message. An alternative to reference: a request carrying both, or carrying a severity, reason, replacement or message beside it, is refused.
fulcioUrlstringnoThe certificate authority to obtain a signing certificate from.
rekorUrlstringnoThe transparency log to record the signature in.
timestampUrlstringnoThe timestamp authority to countersign with.
identityTokenstringnoThe identity token to sign with, supplied by the caller rather than obtained at a terminal.

Additional properties are not permitted.

ResolveParams

Answers where the thing under the cursor is defined.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
uristringnoThe document the cursor is in.
positionPositionnoA place in a document: a line and a character offset within it, both counted from zero. The offset is measured in the units of the encoding the session settled on when it was opened, which is UTF-16 unless the client asked for another.
releasestringnoThe Release to answer in the terms of, as a path relative to the workspace root. The definition is then the document the reference resolves to through the catalog directories the workspace configuration gives that Release, in that order, so a name several variants in one workspace declare, one per Release, goes to that Release’s variant; where those directories declare no such entity, the workspace’s documents are searched, leaving out any under one of the workspace’s catalog directories the Release does not read. Absent, the workspace’s documents are searched first and the workspace’s own catalog directories only where no document declares the name. A value that names no Release file is refused.

Additional properties are not permitted.

FindReferencesParams

Answers where the thing under the cursor is referred to.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
uristringnoThe document the cursor is in.
positionPositionnoA place in a document: a line and a character offset within it, both counted from zero. The offset is measured in the units of the encoding the session settled on when it was opened, which is UTF-16 unless the client asked for another.
releasestringnoThe Release to answer in the terms of, as a path relative to the workspace root. A reference made in a document under one of the workspace’s catalog directories that the Release does not read is then not reported, so variants a workspace keeps side by side, one per Release, are never reported as one another’s references. Absent, every workspace document is searched. A value that names no Release file is refused.

Additional properties are not permitted.

FindImplementationsParams

Answers which documents implement the thing under the cursor.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
uristringnoThe document the cursor is in.
positionPositionnoA place in a document: a line and a character offset within it, both counted from zero. The offset is measured in the units of the encoding the session settled on when it was opened, which is UTF-16 unless the client asked for another.
releasestringnoThe Release to answer in the terms of, as a path relative to the workspace root. A document under one of the workspace’s catalog directories that the Release does not read is then not reported, so a variant another Release builds with is never listed among this Release’s. Absent, every workspace document is searched. A value that names no Release file is refused.

Additional properties are not permitted.

HoverParams

Answers with what to show about the thing under the cursor.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
uristringnoThe document the cursor is in.
positionPositionnoA place in a document: a line and a character offset within it, both counted from zero. The offset is measured in the units of the encoding the session settled on when it was opened, which is UTF-16 unless the client asked for another.
releasestringnoThe Release to answer in the terms of, as a path relative to the workspace root. The entity shown is then the one the reference resolves to through the catalog directories the workspace configuration gives that Release, in that order; where those directories declare no such entity, the workspace’s documents are searched, leaving out any under one of the workspace’s catalog directories the Release does not read. Absent, the workspace’s documents are searched first and the workspace’s own catalog directories only where no document declares the name. A value that names no Release file is refused.

Additional properties are not permitted.

CompletionParams

Answers with what may be written at the cursor.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
uristringnoThe document the cursor is in.
positionPositionnoA place in a document: a line and a character offset within it, both counted from zero. The offset is measured in the units of the encoding the session settled on when it was opened, which is UTF-16 unless the client asked for another.
contextCompletionContextnoWhat caused the request, where the client tracks it.
releasestringnoThe Release to answer in the terms of, as a path relative to the workspace root. The names offered are then those the workspace’s documents declare, less the documents under one of the workspace’s catalog directories that the Release does not read, together with the Components and Features the catalog directories the workspace configuration gives that Release declare. Absent, they are the workspace’s documents and the Components and Features its own catalog directories declare. A value that names no Release file is refused.

Additional properties are not permitted.

CompletionContext

What caused the request, where the client tracks it.

PropertyTypeRequiredDescription
triggerKindintegernoWhy completion was asked for.
triggerCharacterstringnoThe character that caused it, where a character did.

Additional properties are permitted.

AttachCandidatesParams

Answers which Features may be attached to an entity, judged against that entity’s labels, and, for one connection a graph node’s component draws, which may fill each slot the connection’s socket declares.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
nodestringnoThe entity to judge candidates against, by name, read from what the workspace documents declare.
graphNodestringnoThe graph node to judge candidates against, whose labels are the finalised set the build itself evaluates applicability with. An answer computed over this says what the build will do.
releasestringnoThe Release whose graph the node belongs to, as a path relative to the workspace root. The candidates are then drawn in that Release’s terms: the Features the catalog directories the workspace configuration gives that Release declare, and the workspace’s documents less any under one of the workspace’s catalog directories the Release does not read, so a Feature kept for another Release is never offered for a node of this one’s graph.
labelsmap of stringnoLabels to judge against directly, in place of reading them from an entity or a graph node.
connectionConnectionCoordinatenoOne connection drawn by the component of the node graphNode names, to answer for as well as for that node: the answer then also carries slots, each slot the connection’s socket declares with the Features that may fill it, or noSlotReason where no slot may be filled. It is sent only with graphNode and release, because a connection exists only on a compiled graph; sent with node or labels it is refused. The candidates beside it keep their meaning, the Features that may attach to the node itself. Its document is accepted and does not change this answer: the slots are the socket’s and the candidates the Features’, the same whichever document an attachment is written in.

Additional properties are not permitted.

ConnectionCandidatesParams

Answers which entities a socket on an entity may be wired to.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
nodestringnoThe entity whose sockets are being asked about.
socketstringnoThe one socket to answer for. Absent answers for every socket the entity declares.

Additional properties are not permitted.

InsertionPointParams

Answers where in a document a new entry under a named container belongs, leaving composing and applying the entry to the caller that owns the buffer.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
filestringnoThe document to answer about.
containerstring[]noThe path through the document to the container the entry belongs under.

Additional properties are not permitted.

AttachmentContainerParams

Answers which document, and where in it, an attachment on a graph node, or on one connection its component draws, belongs.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
graphNodestringnoThe graph node the attachment is for.
releasestringnoThe Release whose graph the node belongs to, as a path relative to the workspace root.
connectionConnectionCoordinatenoOne connection the graph node’s component draws, when the attachment is for that connection rather than for the node: the answer then names the connection’s own features container in the document its document field names, a field required here. In the Aggregate, that is the connection’s entry in the document the node was authored in, refused for a connection the Release drew, which the Aggregate holds no entry for. In the Release, it is the per-edge entry under the Release’s own entry for the node, whether or not the Release writes one for that connection yet, refused where the Release writes no entry for the node. A connection a Feature drew is refused in either document, because an attachment is written only on a connection a component or the Release draws.

Additional properties are not permitted.

ConnectionAtPositionParams

Answers which connection’s entry a position in an Aggregate or a Release falls inside: the graph node and the connection, in the terms the candidacy and container requests take them, or why no connection is written there. The entries are the ones an attachment is written in — the entry a component draws a connection with, under the connection’s alias, in the document the component was authored in, and every per-edge entry the Release writes — each where the compiled graph records it, so whether a key is a connection is never read from what it is called.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
filestringnoThe document the position is in: the Release, or a document the Release’s graph records components as authored in — its Aggregate, or the document of a module that Aggregate imports. It is read from what the session holds for it first, and from disk otherwise.
positionPositionnoA place in a document: a line and a character offset within it, both counted from zero. The offset is measured in the units of the encoding the session settled on when it was opened, which is UTF-16 unless the client asked for another.
releasestringnoThe Release whose compiled graph records the connections, as a path relative to the workspace root. It is required for a position in the Aggregate too, because a graph node and a connection exist only on a compiled graph.

Additional properties are not permitted.

ConnectionCoordinate

One connection a graph node’s component draws, addressed by the socket it is wired through and the alias it carries in that socket, and the document an attachment on it is written in. A connection carries attachments filling the slots its socket declares, and either the Aggregate or the Release may write them.

PropertyTypeRequiredDescription
socketstringyesThe dependency socket the connection is wired through.
aliasstringyesThe name the connection carries within its socket.
documentconst “aggregate” or const “release”noThe document an attachment on the connection is written in. The set is closed, and a value outside it is refused. Allowed values: "aggregate" — The Aggregate, where the developer writes an attachment on the connection’s entry. "release" — The Release, where the operator writes an attachment on the per-edge entry for the connection.

Additional properties are permitted.

SetActiveReleaseParams

Records a Release as the workspace’s default by writing a marker in the .aggrega directory: the choice aggrega/activeRelease reports reads that marker after the configuration’s authoring Release. The marker is written inside the workspace and nowhere else: where the .aggrega directory or the marker is a link leading out of the workspace, whether or not the place it leads to exists yet, the write is refused naming the link and nothing is written. The answer is the one aggrega/activeRelease gives once the marker is written, so it names a different Release where the configuration’s authoring Release outranks the marker.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
releasestringnoThe Release to record, as a path relative to the workspace root. An absolute path, and one climbing out of the workspace, are refused; so is one leading out of it through a link, unless the workspace configuration names that Release.

Additional properties are not permitted.

EditDocumentParams

Applies one bounded edit to a document the workspace carries: one entry added under one container, or one scalar set. The composed document is checked against its kind’s schema and reaches disk only if that passes, so this cannot write what the authoring schema refuses. A refused edit leaves the file byte-for-byte as it was.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
filestringnoThe document to edit.
editconst “add-component” or const “attach-feature” or const “wire-edge” or const “set-value”noWhich edit to apply. Allowed values: "add-component" — Adds a component instance under a components container: name is the instance name, value the Component it requests. "attach-feature" — Attaches a Feature to the node the request names: name is the attachment’s instance name, value the Feature it requests. "wire-edge" — Wires a dependency connection from the node the request names, inside socket: name is the alias the connection is addressed by, value the node it points at. "set-value" — Sets one value on the node the request names: name is the value’s key, value a scalar.
nodestring[]noThe path through the document to the entry being edited.
socketstringnoThe socket the edit is about, for an edit that wires one.
namestringnoThe name the edit writes.
valueanynoThe value the edit writes, in whatever shape the edit takes.
dryRunbooleannoWhether to answer with the composed document rather than writing it.

Additional properties are not permitted.

ConfigInitParams

Seeds a configuration document. It writes the machine-wide file by default, since a registry and the identities trusted on it are machine-wide tooling. It reaches the named registry to read the trust policy it advertises; a registry advertising nothing is reported as such and the seeding proceeds, on the built-in baseline for the official hub and on no policy for any other registry.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
registrystringnoThe registry to seed the configuration for.
forcebooleannoWhether to overwrite a configuration document that already exists.
globalbooleannoWrite the machine-wide configuration file, which is this method’s own default.
workspacebooleannoWrite this workspace’s own configuration file instead of the machine-wide one.
dryRunbooleannoWhether to answer with the document’s content rather than writing it, for a client that keeps its own document model.

Additional properties are not permitted.

ConfigCaptureParams

Freezes the resolved configuration into this workspace’s own document, so the workspace is self-contained. It always writes that workspace’s file and reaches nothing outside it.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
allPluginsbooleannoWhether to freeze every attached plugin rather than only the ones the workspace itself configured.

Additional properties are not permitted.

ImportParams

Converts a foreign source description into draft authoring documents, and writes beside them .aggrega-import.json, the record of what the import wrote — the target it was given, where it was given one, the catalog snapshot it read, where it read one, each drafted file, and each key of a drafted Aggregate or Release at every depth — which a later sync reads. A source it could not fully convert is an answer rather than a failure: the drafts it did produce are written and the findings say what it could not convert — except under sync, which writes nothing from a conversion that stopped.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
sourcestringnoThe file or the directory to convert, as an absolute path or one relative to the workspace root; a request without one is refused. It is read where it is, inside the workspace or not, and a directory is read into the files of it the importer’s declared file patterns select.
outputDirstringnoThe directory under the workspace to write the drafts into, relative to the workspace root; an absolute value, or one leading out of the workspace as written or through a link, is refused. Absent writes beneath the workspace root, where the same conversion run at a terminal naming no destination writes. Every drafted path is relative to the directory the answer names as outputDir, under dryRun as well.
formatstringnoThe source format. Absent lets the conversion determine it.
targetstringnoA provider capability, such as compose or helm — the word a Recipe’s spec.capability binds to — to draft a Manifest for beside the drafts, as manifest.yaml: each component type and feature type the drafts need, the types of a catalog Aggregate the drafted one composes included, is mapped to the Recipe or feature recipe of that capability the workspace’s catalog offers for it — the one there is, or among several the one named after the type — a type with none, or with several and none so named, is left unmapped with a warning finding naming it, a mapping an importer drafted itself is kept where the catalog offers it for that type and capability and dropped with a warning finding otherwise, and the drafted Release’s spec.manifest is set to the Manifest. A capability no Recipe in the catalog binds to is refused before the conversion runs, and nothing is written. Absent drafts no Manifest, except under sync, which drafts for the target the record of the earlier import names; a sync naming a target drafts for it, and the record then names it.
dryRunbooleannoWhether to answer with the content of every file the request would write rather than writing it. Every other behaviour is the write’s, so a request the write would refuse is refused under it too; with sync, it answers with what the sync would write and every part that would drift.
syncbooleannoWhether to bring what an earlier import drafted beneath outputDir up to date with the source, rather than writing the draft whole. Only what the import wrote changes, as the record beside the drafts lists it: a part the source left alone stays as it is on disk, edited or not; a part the source changed, dropped or gained is written anew, removed — a drafted file deleted whole — or added, where what is on disk is what the import last wrote; and everything else, a key an author added — the environment a drafted Release leaves for its author among them — or a comment not written directly above a drafted key, stays byte for byte. A sync that would change or remove what an author edited or added, or add a part where an author already wrote one, is refused naming each part, and so is a sync over an Aggregate no record lists; nothing is written either way. Without it, a request whose drafts would be written over an Aggregate already in outputDir is refused, under dryRun too.
upgradebooleannoWhether to fetch the newest catalog snapshot the workspace’s default registry publishes and import against it, holding it from then on in place of the one the workspace holds or the one the record beside the drafts names; it changes nothing where the workspace names a catalog folder, and is refused offline.
answersstringnoThe answers file the values the drafts leave empty that no source can hold are read from and written to, relative to the workspace root; an absolute value, or one leading out of the workspace as written or through a link, is refused. It holds, under each drafted file’s path, the key path inside that document and its answer, and the answers are written into the drafts. Absent reads the one the record beside the drafts names, or else import-answers.yaml beside the source file or inside the source directory. A secret’s answer names where the secret comes from — a variable name, ${NAME}, or the name of a Kubernetes Secret — and anything else is refused with nothing written. Nothing is asked: each value still owed is an entry of the answer’s owed and a warning finding naming the drafted file, the key and what it is, its answer is sent as answered, and where the drafts are written the last finding says how many are owed and where. Where the drafts include a Release, owe nothing and the conversion finished, its dependencies are then pulled, writing its lockfile, and a pull that fails closes the findings saying why, the drafts written; offline nothing is pulled and a finding names the pull to run. An answer for a key these drafts do not leave empty is kept in the file and not applied, so one answers file serves every target.
answeredImportAnswered[]noAnswers for values the answer’s owed listed, each naming the drafted file and the keys as owed named them. Each is judged, kept in the answers file and written into the drafts exactly as an answer typed at a terminal is: a secret’s answer names where the secret comes from — a variable name, ${NAME}, or the name of a Kubernetes Secret — and one that does not is neither kept nor written, its value staying owed with the reason as its secretAdvice. A value the answers file already answers is answered from the file; an empty answer, or one naming a value the drafts do not owe, is not applied. Send it with sync once the drafts are written, since a request that is not a sync is refused over an Aggregate already in outputDir. Under dryRun, which keeps no answer, and under a sync whose conversion stopped, which writes nothing, no answer sent is applied.

Additional properties are not permitted.

ScaffoldEntityParams

Drafts a starter document for an entity kind, or writes one of the documentation’s runnable examples into a new directory of the workspace, or lists them. Drafting derives the skeleton from the schema set the binary carries, so nothing is read from a workspace and nothing is written — the answer is text, and where it goes is the client’s. Writing an example writes the new directory and nothing else, and the examples are read from the signed documentation bundle published for the binary’s version, or the newest published before it where none is, verified against the workspace’s signature policy before it is kept or read: a bundle that does not verify is refused, and offline only a copy already cached is read. A request sending the fields of two forms together — kind with example or list, list with example, name with example or list, dir without example — is refused before anything is read.

PropertyTypeRequiredDescription
workspaceRootstringnoThe absolute path of the workspace. Drafting does not read it. Writing or listing an example requires it: the workspace’s configuration decides where the documentation is fetched from and which signatures it must carry, and an example is written inside it.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
kindstringnoThe entity kind to draft, named by its lowercase token, such as component, aggregate, release, recipe or featurerecipe — the token aggrega/getSchema lists for it.
namestringnoThe name to write into the drafted document. Sent only with kind.
examplestringnoThe runnable example to write, by the name the list of examples gives it. Sent instead of kind.
listbooleannoWhether to answer with every runnable example the documentation publishes, writing nothing. Sent without example and without kind.
dirstringnoThe new directory to write the example into, relative to the workspace root; absent writes it into a directory named after the example there. It must not exist yet or must be empty: one holding anything is refused and left as it is, and an absolute value, or one leading out of the workspace as written or through a link, is refused before anything is read. Sent only with example.

Additional properties are not permitted.

LintParams

Checks catalog publishing conventions over one entity, over everything a Release’s closure reaches, or over everything under the configured catalog directories. Nothing is written under any mode. Naming neither an entity nor a Release checks the whole catalog: in a workspace whose configuration gives no Release catalog directories of its own, once over the workspace’s directories; in a workspace that names Releases under workspace.releases, once for each Release over the directories that Release reads, never over all of them together.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
entitystringnoThe one entity document to check.
releasestringnoThe Release whose closure to check, as a path relative to the workspace root.
prePublishbooleannoWhether to compare each entity against its previously published version, which reaches the configured registries.

Additional properties are not permitted.

PluginAddParams

Attaches a plugin to a socket the workspace configures. It reaches a registry to resolve the query to one plugin and to pin a version. The one decision a terminal would obtain — accepting a command-extension plugin’s declared capabilities — arrives as a field here, so the client asks whoever is driving it and this surface never waits on a prompt.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
typestringnoThe socket the plugin attaches to.
querystringnoWhat to resolve to one plugin.
capabilitystringnoThe capability the attachment is for, where the socket carries several.
rolestringnoThe role the attachment runs in, which fixes what it may emit.
globalbooleannoWrite the machine-wide configuration file.
workspacebooleannoWrite this workspace’s own configuration file.
acceptCapabilitiesbooleannoWhether the caller accepts the capabilities a command-extension plugin declares.
dryRunbooleannoWhether to answer with the configuration document’s content rather than writing it.

Additional properties are not permitted.

PluginRemoveParams

Detaches a plugin from a socket the workspace configures.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
typestringnoThe socket the plugin is attached to.
querystringnoWhich attachment to remove.
globalbooleannoWrite the machine-wide configuration file.
workspacebooleannoWrite this workspace’s own configuration file.

Additional properties are not permitted.

PluginSyncParams

Aligns a Plugin entity’s machine-owned records with the module it points at. It rewrites those records and carries every other byte of the document through unchanged.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
entitystringnoThe Plugin entity document to align.
pluginstringnoThe plugin module to read the records from.

Additional properties are not permitted.

PluginGenCatalogParams

Generates Plugin catalog documents from a plugin’s own declared metadata plus an authored overlay. Regenerating over unchanged inputs produces byte-identical documents.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
fromEmbeddedbooleannoWhether to read the metadata from the plugins the binary already carries.
pluginstringnoThe plugin module to read the metadata from.
outputDirstringnoThe directory under the workspace to write the documents into.
overlaystringnoThe authored document whose content is merged over the generated metadata.
dryRunbooleannoWhether to answer with the documents’ content rather than writing them.

Additional properties are not permitted.

ExplainErrorParams

Expands a code a finding carried into what the compiler declares about that condition and the published entries that teach the authoring fix. It acquires the published documentation when the workspace has no copy; one it cannot acquire still answers what the binary declares, and says why the prose is missing.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
codestringnoThe condition to expand, named by either the code a finding carried or its short code.

Additional properties are not permitted.

GetSchemaParams

Answers with a kind’s schema, or — when no kind is named — with which kinds can be named. It answers for the running binary rather than for whichever copy is installed elsewhere, so it needs no workspace and reads none.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootAcceptednoThe absolute path of a workspace. This method’s subject is not a workspace — it answers from what the binary itself carries — so the field is accepted and not read. It is admitted because a client may send it uniformly on every request without having to know which methods consult it.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
kindstringnoThe kind whose schema to answer with. Absent answers with the kinds that can be named instead.

Additional properties are not permitted.

SkillsInstallParams

Writes the assistant skill built into the binary into the skill folder of each assistant the request names or, for a global request naming none, each assistant found on this machine. Without global it writes each assistant’s project folder inside the workspace the request names, and every path it would write there is held to that workspace; with global it writes each assistant’s per-user folder under the home directory. Every target is checked before anything is written, so a refusal leaves every folder as it was.

PropertyTypeRequiredDescription
workspaceRootWorkspaceRootSubjectyesThe absolute path of the workspace this request acts on. It is the request’s subject: the daemon resolves it before the method runs, and a request that omits it or spells it as anything other than a string is refused.
workDoneTokenProgressTokennoA value the caller mints so it can match progress notifications to the call that asked for them. It is echoed back on every notification unchanged, so a caller may compare it to the value it sent. It is accepted on every request, and a request that sends one in a session which declared no progress capability is refused.
agentsstring[]noThe assistants to install the skill for, by the identifiers the listing reports. A project request naming none is refused. A global request naming none installs the skill for the assistants found on this machine, each one whose configuration folder is in the home directory or whose command is on the PATH, and is refused with nothing written where none is found. An identifier no skill folder is known for is refused, by name, and an identifier given twice is installed once.
globalbooleannoWrite each assistant’s per-user skill folder under the home directory, which it reads in every project, instead of its project folder in the workspace.

Additional properties are not permitted.

ServerCapabilities

What the daemon will do in this session, settled against what the client said it can handle.

PropertyTypeRequiredDescription
positionEncodingstringyesThe encoding every position in this session is expressed in.
workDoneProgressbooleannoWhether the daemon will send progress notifications in this session. Present only where the client declared it can receive them.

Additional properties are not permitted.

ClosureEntity

One entity a Release depends on, at the version resolution settled.

PropertyTypeRequiredDescription
uristringyesThe reference the entity resolves from.
versionstringyesThe version that was settled on.
kindstringnoThe entity kind.
sourcestringnoWhere the run that produced this entry took the entity from, in the same word aggrega pull --detail prints for it: fetched-fresh (fetched from a registry during that run), cache-reuse (a copy already in the cache, reused without fetching), local (found on the local filesystem, such as a catalog directory), in-binary (the copy inside the compiler binary), or external (the Release’s own Aggregate or Manifest, read from the file or entry the Release names rather than resolved as one of its dependencies; an Aggregate the run fetched from a registry is fetched-fresh instead). Present on the entries of a dependency resolution’s report, where it describes what that run did on this machine, and absent from a listing of a Release’s resolved dependencies, which describes what the Release depends on. The lockfile records no source. Omitted for an entity whose source the run did not record.

Additional properties are not permitted.

ToolchainCorePlugin

One plugin the compiler itself carries, and the version of it that was used.

PropertyTypeRequiredDescription
pluginstringyesThe plugin’s reference.
versionstringyesThe version that was used.

Additional properties are not permitted.

ToolchainReport

The compiler that resolved, and the plugins it carries.

PropertyTypeRequiredDescription
compilerVersionstringyesThe compiler version that resolved.
corePluginsToolchainCorePlugin[]noThe plugins the compiler carries, with the version of each that was used.

Additional properties are not permitted.

DependencyResolutionReport

What a dependency resolution pinned and acquired.

PropertyTypeRequiredDescription
lockfilestringyesThe lockfile the resolution wrote, or the one a verify compared against.
verifiedbooleannoWhether the request was a verify, which compared the recorded lockfile and wrote no lockfile, plugin trust record or entity.lock.
entitiesClosureEntity[] or nullyesThe entities the resolution pinned, or a verify compared.
librariesClosureEntity[] or nullyesThe libraries the resolution pinned, or a verify compared.
pluginsClosureEntity[] or nullyesThe plugins the resolution pinned, or a verify compared.
sourceArtifactsintegeryesHow many source artifacts were acquired.
trustedPluginsintegeryesHow many of the pinned plugins carried a verified signature.
toolchainToolchainReportnoThe compiler that resolved, and the plugins it carries.
externalInputsintegeryesHow many external inputs the render consumes were acquired.
incompleteExternalInputsstringnoWhich external inputs could not be acquired, where some could not be.

Additional properties are not permitted.

BuildNotice

One thing the build wants the caller to know, which is neither a finding about a document nor a failure.

PropertyTypeRequiredDescription
classstringyesWhat kind of notice this is.
textstringyesWhat the notice says.

Additional properties are not permitted.

CacheScope

How far a cache answer reaches. Two of the cache classes are shared by every project on the machine, so every cache answer names which ones it touched — a session opened over one workspace would otherwise be read as reporting only about that workspace.

PropertyTypeRequiredDescription
machineWideClassesstring[] or nullyesThe cache classes this answer touched that are shared across every project on the machine.
workspaceRootstringyesThe workspace the request named.

Additional properties are not permitted.

CacheElement

One thing a cache holds.

PropertyTypeRequiredDescription
labelstringyesWhat the entry is of.
sizeintegeryesHow many bytes it occupies.
sizeTextstringyesThe same size written the way a person reads one.
digeststringnoThe content digest the entry is keyed under, where it has one.
notestringnoAnything else worth saying about the entry.

Additional properties are not permitted.

CacheClass

One cache the daemon reports on.

PropertyTypeRequiredDescription
namestringyesWhich cache this is.
reachstringyesWhether the cache belongs to this workspace or is shared across the machine.
prunablebooleanyesWhether reclaiming this cache is something the daemon will do.
elementsCacheElement[] or nullyesWhat the cache holds.

Additional properties are not permitted.

CacheProvenance

Which identities a cached artifact was acquired under, and how widely it is shared.

PropertyTypeRequiredDescription
identitiesstring[] or nullyesThe identities the artifact is attributed to.
sharedByintegernoHow many holders share the artifact.

Additional properties are not permitted.

CacheRemoval

One thing a reclamation removed — or, in a list of what it left in place, one thing it would have removed.

PropertyTypeRequiredDescription
classstringyesWhich cache it belongs to.
labelstringyesWhat it is.
reachstringyesWhether that cache belongs to this workspace or is shared across the machine.
sizeintegeryesHow many bytes it occupies, or occupied before it was removed.
sizeTextstringyesThe same size written the way a person reads one.

Additional properties are not permitted.

CacheShortfall

What a reclamation left behind, and what would reclaim it, so a caller reading a smaller figure than it expected learns why rather than inferring it.

PropertyTypeRequiredDescription
classstringyesWhich cache holds what was left.
countintegeryesHow many entries were left.
sizeintegeryesHow many bytes they occupy.
sizeTextstringyesThe same size written the way a person reads one.
reachstringyesWhether that cache belongs to this workspace or is shared across the machine.
reclaimedBystring[] or nullyesWhat would reclaim them.

Additional properties are not permitted.

CacheCleared

One cache a clearing emptied.

PropertyTypeRequiredDescription
classstringyesWhich cache was emptied.
reachstringyesWhether it belongs to this workspace or is shared across the machine.
sizeintegeryesHow many bytes were reclaimed from it.
sizeTextstringyesThe same size written the way a person reads one.
heldOpenFilesintegeryesHow many files the clearing left in this cache because another process had them open. Only Windows refuses to remove an open file, so everywhere else this is zero. A later clearing removes them once that process has finished with them.
heldOpenBytesintegeryesHow many bytes those files occupy. They are not counted in size, which is what the clearing reclaimed.
heldOpenBytesTextstringyesThe same figure written the way a person reads one.

Additional properties are not permitted.

ConfigWriteScope

Which configuration document was written and how far it reaches. A request names one workspace, so an answer that said nothing would be read as being about that workspace — and for a machine-wide write that reading is wrong.

PropertyTypeRequiredDescription
configFilestringyesThe document that was written.
machineWidebooleanyesWhether that document is the one every workspace on the machine resolves through.
workspaceRootstringyesThe workspace the request named.

Additional properties are not permitted.

PluginWriteScope

Which configuration document a plugin change was written into and how far it reaches. The command-extension socket’s own default is the machine-wide document, so every answer says which one it wrote.

PropertyTypeRequiredDescription
configFilestringyesThe document that was written.
machineWidebooleanyesWhether that document is the one every workspace on the machine resolves through.
workspaceRootstringyesThe workspace the request named.

Additional properties are not permitted.

CredentialStoreScope

How far a credential change reaches. The store is shared by every project on the machine and by every other tool addressing the same registries, so the answer reports that rather than leaving a session-scoped reading to be inferred.

PropertyTypeRequiredDescription
machineWidebooleanyesWhether the store the change touched is shared across the machine.
workspaceRootstringyesThe workspace the request named.

Additional properties are not permitted.

SkillFolderScope

How far a skill installation reaches. A request names one workspace, so an answer that said nothing would be read as being about that workspace — and for the per-user folders, which an assistant reads in every project, that reading is wrong.

PropertyTypeRequiredDescription
machineWidebooleanyesWhether the folders written are the per-user ones under the home directory, which the assistant reads in every project on the machine.
workspaceRootstringyesThe workspace the request named.

Additional properties are not permitted.

PublicationReach

How far a publication reached. These answers reach beyond this machine entirely — what they attach is what every consumer of that registry resolves — so each names every registry it addressed and whether the call attached anything there.

PropertyTypeRequiredDescription
registriesstring[]yesEvery registry host the call addressed, each named once, in the order the call first addressed it. A single-reference call names one; a dry run names the destination it would have addressed.
beyondThisMachinebooleanyesWhether the call attached anything a registry now serves to others: uploaded content, a signature, a publication date or a deprecation marker. False on a dry run, and on a call that found everything it would have attached already there — a publication run again over a complete version, or a signing batch whose every reference already carried a signature that verifies.

Additional properties are not permitted.

WorkspaceEntityRef

One entity, by kind and name, with the document that declares it.

PropertyTypeRequiredDescription
kindstringyesThe entity kind.
namestringyesThe entity name.
filestringyesThe document declaring it, as a path relative to the workspace root.

Additional properties are not permitted.

SourcedEntityRef

One entity, with where it was read from. A workspace document reports its workspace-relative path; an entity resolved from the configured catalog directories reports an empty path, because the only path it has would mean nothing to a client. The origin says which of the two it is, rather than leaving an empty path to be read as a field nobody filled in.

PropertyTypeRequiredDescription
kindstringyesThe entity kind.
namestringyesThe entity name.
filestringyesThe document declaring it, as a path relative to the workspace root, or empty where it came from the configured catalog directories.
originstringyesWhere the entity was read from.

Additional properties are not permitted.

SocketCandidacy

One socket on an entity, and what may be wired into it.

PropertyTypeRequiredDescription
socketstringyesThe socket’s name.
declarationstringyesWhere the socket is declared.
selectorstringyesThe label selector a target must satisfy.
requiredbooleanyesWhether the socket must be wired for the build to proceed.
targetsWorkspaceEntityRef[] or nullyesThe entities that may be wired into it.

Additional properties are not permitted.

SlotCandidacy

One slot a connection’s socket declares, as the consuming Component declares it on the socket, and the Features that may fill it on that connection.

PropertyTypeRequiredDescription
slotstringyesThe slot’s name, which is the key an attachment filling it is written under in the connection’s features.
selectorstringyesThe label selector a Feature filling the slot must satisfy with its own labels. Empty where the slot declares none, which admits any Feature.
requiredbooleanyesWhether every connection wired through the socket must fill the slot for the build to proceed.
injectstring[]yesThe delivery mechanisms the slot permits for what fills it, in the order the Component declares them. Empty where it declares none.
sensitivebooleanyesWhether the slot declares that what fills it handles secret material. It marks the attachment filling it and refuses nothing.
descriptionstringyesWhat the Component says the slot is for. Empty where it says nothing.
candidatesSourcedEntityRef[]yesEach Feature that may fill the slot on this connection: one whose declared applicability the graph node’s labels satisfy, which every attachment the node carries is held to, and whose own labels satisfy the slot’s selector. A Feature whose applicability or whose labels cannot be read against the selector is not offered, because a build refuses rather than admits it.

Additional properties are not permitted.

CatalogEntity

One entity the workspace index holds.

PropertyTypeRequiredDescription
kindstringyesThe entity kind.
namestringyesThe entity name.
apiVersionstringyesThe schema version the document declares.
descriptionstringyesWhat the document says the entity is for.
labelsmap of string or nullyesThe labels the document declares.
filestringyesThe document declaring it, as a path relative to the workspace root.
originstringyesWhere the entity was read from.

Additional properties are not permitted.

CompletionItem

One thing that may be written at the cursor.

PropertyTypeRequiredDescription
labelstringyesThe text to write.
kindintegernoWhat sort of thing it is, so a client can choose an icon for it.
detailstringnoA short qualifier shown beside the label.
documentationstringnoWhat the thing is, at length.
sortTextstringnoThe value to order by, where it differs from the label.

Additional properties are not permitted.

MarkupContent

Text to show, and how it is marked up.

PropertyTypeRequiredDescription
kindstringyesHow the text is marked up.
valuestringyesThe text.

Additional properties are not permitted.

EntityKindDescriptor

One kind an author writes a document of, pairing the token a request names with the kind the document itself declares, and saying which operations accept a document of that kind.

PropertyTypeRequiredDescription
kindstringyesThe lowercase token a request names, such as component or featurerecipe.
documentKindstringyesThe kind the document’s own header declares.
acceptedByEntityKindAcceptanceyesWhich operations accept a document of this kind named on its own — by its path, or by its name for inspection — with nothing else sent beside it. A member is true when that operation does not refuse a document for being of this kind; a document it accepts may still be refused for what the document says.

Additional properties are not permitted.

EntityKindAcceptance

For one kind an author writes, whether each operation accepts a document of that kind named on its own. Every member is present on every entry, so false is a statement rather than an omission.

PropertyTypeRequiredDescription
singleEntityValidationbooleanyesWhether the single-entity scope of aggrega validate — the command given one document’s path — checks a document of this kind. A kind it refuses is checked by the whole-catalog scope or by the Release scope instead.
publicationbooleanyesWhether aggrega/publishEntity naming the document alone publishes a document of this kind. A kind whose publication also binds an executable named beside the document — a Plugin — is false, because a request naming the document alone is refused for it; a Manifest and a Release are false because neither kind is published.
inspectionByNamebooleanyesWhether aggrega/entityDefinition resolves a name to an entity of this kind, the name sent as it is written where one entity references another.

Additional properties are not permitted.

RegistryTrust

The trust policy resolution applies to what a registry serves.

PropertyTypeRequiredDescription
signaturesRequiredbooleanyesWhether an artifact from this registry must carry a verified signature.
verificationSkippedbooleannoWhether verification is being skipped.
advisorybooleannoWhether a failed verification is reported rather than halting.
anchorstringnoThe trust anchor signatures are verified against.
keylessIdentitiesintegernoHow many signing identities are trusted for this registry.

Additional properties are not permitted.

Registry

One configured registry. No field here carries credential material, its length, its shape, or any rendering of it — presence is the whole of what is reported, which is what makes the value safe to paste into an issue.

PropertyTypeRequiredDescription
hoststringyesThe registry host, which is its identity.
namestringnoThe friendly alias that resolves to the host, where one is configured.
defaultbooleanyesWhether this is the registry an operation with no registry named addresses.
authStatestringyesWhether a credential for this host is present in the machine-wide store. It is reported even when empty, so a caller can tell ‘no credential is present’ from ‘the listing did not look’.
trustRegistryTrustyesThe trust policy resolution applies to what a registry serves.

Additional properties are not permitted.

TrustFetchOutcome

What reading a registry’s advertised trust policy did. The outcomes are kept apart because they mean different things: the advertised policy was taken, the registry advertised nothing — which is not a failure — the built-in baseline was pinned in its place, or no read was attempted. Where nothing was advertised, whether the registry could be reached at all is stated beside it.

PropertyTypeRequiredDescription
pinnedbooleanyesWhether the advertised policy was taken.
notAdvertisedbooleannoWhether the registry was asked and advertised no policy, in which case the operation proceeds on what the request stated. A registry the offline posture kept from being asked is never reported this way. A registry that could not be reached is reported this way too, since no policy came back from it, and carries unreachable beside it; read unreachable to tell the two apart.
unreachablebooleannoWhether the registry could not be reached when its advertised policy was asked for: its name did not resolve, a connection to it was refused or could not be opened, or a secure connection to it could not be established. It is read from the failure itself rather than from reason, it stands beside notAdvertised, and it is set only where the failure shows the registry was never reached; a registry that answered — with no policy, or with a failure — leaves it absent.
baselinebooleannoWhether the built-in baseline was pinned because no advertised policy was taken, which only the official hub carries. It stands beside notAdvertised where the hub was asked and advertised nothing, and alone where the offline posture kept the hub from being asked.
skippedbooleannoWhether no read was attempted, because a stated policy overrode it or the request asked for none.
identitiesintegernoHow many signing identities the advertised policy carried.
reasonstringnoWhy the advertised policy was not taken: what the registry’s endpoint did, or the offline refusal that kept it from being asked.

Additional properties are not permitted.

SkippedRepo

One repository the index walk passed over, and why.

PropertyTypeRequiredDescription
repostringyesThe repository that was passed over.
reasonstringyesWhy it was passed over.

Additional properties are not permitted.

DeprecationNote

One deprecation marker the index walk met, and what it did with it. A marker that was honoured and one that was present and declined are reported on the same footing, so recording many does not pass in silence while declining one announces itself.

PropertyTypeRequiredDescription
repostringyesThe repository the marker is on.
versionstringyesThe version the marker covers.
recordedbooleanyesWhether the marker’s own signature verified, and the index therefore carries it.
severityconst “warning” or const “error” or const “retracted”noHow strongly the marker speaks. Allowed values: "warning" — Deprecated, at the milder of the two advisory tiers: still selected when a version is chosen. "error" — Deprecated, at the stronger of the two advisory tiers: still selected when a version is chosen. "retracted" — Withdrawn: excluded when a version is chosen.
reasonstringnoWhy the version is deprecated.

Additional properties are not permitted.

HostUpdate

What an index refresh did for one registry.

PropertyTypeRequiredDescription
hoststringyesThe registry host that was refreshed.
indexedintegeryesHow many records were written.
deprecationsExaminedbooleanyesWhether the walk looked for deprecation markers at all. It is separate from the count because ‘this registry published none’ and ‘this run had no basis to judge one’ are different facts.
deprecationsRecordedintegeryesHow many markers were honoured.
skippedSkippedRepo[] or nullyesThe repositories the walk passed over.
deprecationsDeprecationNote[] or nullyesThe markers the walk met.
readsRetriedintegeryesHow many of the walk’s reads the registry refused or dropped in passing and were asked again, each read counted once however many attempts it took and whether or not it then succeeded; zero where none was. A walk whose reads all succeeded in the end lists no repository under skipped, so this count is what says how close it came to leaving one out. Minimum: 0.
errorstringnoWhat failed for this host, so a walk over several reports which of them failed without the caller correlating anything.
unreachablebooleannoWhether this registry could not be reached: its name did not resolve, a connection to it was refused or could not be opened, or a secure connection to it could not be established. It is read from the failure itself rather than from error, it is set only beside error, and only where the failure shows the registry was never reached; a registry that answered, whatever it answered, leaves it absent.

Additional properties are not permitted.

PublishedVersion

One version the index holds for a reference: the manifest digest its tag resolved to when the index was built; where the trust policy the index was built under verified the version’s own signature, the signer it verified as; and, where anything records it, when the version was published, with the source that says so. The signer is absent for a version with no signature, for one none of whose signatures verified, and where that policy pins neither a public key nor a trusted identity or switches signature verification off. None of those is a basis for naming a signer, and its absence says nothing more. The publication date is absent where the publication stated none and no keyless signature that policy verified records one.

PropertyTypeRequiredDescription
versionstringyesThe version, as its tag names it.
manifestDigeststringyesThe digest of the manifest the version’s tag resolved to when the index was built, which addresses the version by the bytes it names rather than by its tag.
signerVerifiedSignaturenoA signature that verified against a registry’s trust policy: how it verified, the signer it verified as, and the digest of the signature bundle that verified.
publishedAtstringnoWhen the version was published, as an RFC 3339 timestamp in UTC to the second. Where it came from is publishedAtSource, and the two are present together or not at all.
publishedAtSourceconst “transparency-log” or const “publisher”noWhere publishedAt came from, so a time a transparency log attests is never mistaken for one the publisher states. The set is closed. Allowed values: "transparency-log" — The time a transparency log recorded the version’s keyless signature, which the trust policy the index was built under verified along with the log’s signed promise of that time. For a version signed as it was published, it is the publication; for one signed afterwards, it is when that signature was made. "publisher" — The time the publication stated beside what it published, from the publishing machine’s own clock. Nothing attests it. A publication states one where its signature carries no attested time: a keyed signature, or none. Where several are attached, the earliest is taken.

Additional properties are not permitted.

VerifiedSignature

A signature that verified against a registry’s trust policy: how it verified, the signer it verified as, and the digest of the signature bundle that verified.

PropertyTypeRequiredDescription
bundleDigeststringyesThe digest of the signature bundle that verified, as sha256: followed by 64 lowercase hex characters.
identitystringnoThe signer the signature verified as: for a keyless signature, the identity the signing certificate was issued for, which is its subject alternative name; for a keyed signature, keyed:sha256: followed by the lowercase hex SHA-256 of the pinned public key’s PEM text.
issuerstringnoThe OIDC issuer recorded in the signing certificate, for a keyless signature. It is absent for a keyed signature.
modeconst “keyless” or const “keyed”yesHow the signature verified. The set is closed. Allowed values: "keyless" — Against a signing certificate whose identity and issuer match one the policy trusts, which chains to the trust root the policy pins or, where it pins none, to the public-good Sigstore root, and whose signature a transparency log records. "keyed" — Against the public key the policy pins.

Additional properties are not permitted.

RegistrySearchRecord

One record a search matched, as the local index holds it, plus which of its versions a published marker has deprecated.

PropertyTypeRequiredDescription
uristringyesThe reference the record resolves from.
namestringyesThe entity name.
versionstringyesThe version the record is keyed at.
versionsstring[]noEvery version the index holds for this reference.
kindstringnoThe entity kind.
descriptionstringnoWhat the entity is for.
categorystringnoThe category the entity is published under.
labelsmap of stringnoThe labels the entity declares.
pluginTypestringnoThe socket a plugin record attaches to.
capabilitiesstring[]noThe capabilities a plugin record declares.
manifestDigeststringnoThe digest of the published manifest.
listingDigeststringnoThe digest of the listing the record was read from.
deprecationsobject[]noThe deprecation markers the index carries for this reference, each with the version it covers and the verified marker itself.
publishedPublishedVersion[]noEvery version the index holds for this reference, in the same order as versions, each with the manifest digest its tag resolved to when the index was built, where the trust policy the index was built under verified that version’s own signature its verified signer, and where anything records it its publication date and that date’s source. A version recorded with no signer carries no signature that policy verified, and nothing more is said about it. Only manifests, signature attachments and publication-date attachments are read from the registry to record this; no entity’s content is fetched.
retractedstring[]noThe versions a published marker has deprecated.

Additional properties are not permitted.

RegistrySearchIndex

One searched host’s freshness.

PropertyTypeRequiredDescription
hoststringyesThe host whose index was searched.
lastUpdatedstringnoWhen the index was last refreshed. It is absent rather than zero when the snapshot carries no time, so a caller can tell ‘not recorded’ from the epoch.

Additional properties are not permitted.

EffectiveConfigurationSetting

One resolved setting, and which document it came from.

PropertyTypeRequiredDescription
fieldstringyesThe setting.
valuestringyesThe value that was resolved.
sourcestringyesWhere the value came from.

Additional properties are not permitted.

ImportedFile

One file an import writes: a draft document, or the record of what the import wrote.

PropertyTypeRequiredDescription
pathstringyesWhere the file belongs, as a path relative to the answer’s outputDir.
contentstringyesThe file’s text.

Additional properties are not permitted.

ImportDrift

One part a sync brought up to date with the source, or under dryRun would.

PropertyTypeRequiredDescription
changestringyesHow the part drifted: added, for a part the source gained; removed, for one it dropped; or changed, for one it changed.
filestringyesThe drafted file the part is in, as a path relative to the answer’s outputDir.
keystring[]yesThe keys leading to the part from the top of a drafted Aggregate or Release, one entry per key, so a key holding a full stop stays one entry. Empty where the part is the whole file.

Additional properties are not permitted.

ImportOwed

One value the drafts still leave empty that no source could supply and no answer did.

PropertyTypeRequiredDescription
filestringyesThe drafted file the value is in, as a path relative to the answer’s outputDir.
keystring[]yesThe keys leading to the value from the top of that document, one entry per key, so a key holding a full stop stays one entry. An answer sent as answered names the value by these keys.
questionstringyesWhat the value is: its schema’s description, or else the comment the draft writes above its key, or else what its schema says it takes.
sensitivebooleanyesWhether the value is a secret’s, whose answer names where the secret comes from and never holds the secret itself.
secretAdvicestringnoPresent on a secret’s value: what its answer must be, in the sentence a person answering it at a terminal is shown — or, where the answer sent for it as answered was refused, why it was refused.

Additional properties are not permitted.

ImportAnswered

One answer for a value the answer’s owed listed.

PropertyTypeRequiredDescription
filestringyesThe drafted file the value is in, as owed names it.
keystring[]yesThe keys leading to the value, as owed names them.
answerstringyesThe answer. An empty one leaves the value owed.

Additional properties are not permitted.

ImportDiagnostic

One thing a conversion could not convert. These are the conversion’s most useful output, so they are reported in full rather than reduced to a verdict.

PropertyTypeRequiredDescription
severitystringyesHow serious it is.
messagestringyesWhat could not be converted.
codestringnoThe condition’s quotable name, where it has one.

Additional properties are not permitted.

ImportDecision

How a conversion mapped one source node: the catalog Components the importer weighed, the one it chose, why, and how to swap the choice.

PropertyTypeRequiredDescription
sourceNodeDecisionSourceNodeyesThe source node a mapping decision is about.
candidatesImportCandidate[]noThe catalog Components the importer weighed for the node, each with its score. Absent where it weighed none.
chosenDecisionChoicenoWhat the importer chose for a source node. Absent from a decision where it made no choice.
rationalestringnoWhy the importer made the choice, in its own words. Absent where it wrote none.
swapHintstringnoHow to swap the choice for an alternative, in the importer’s own words. Absent where it wrote none.

Additional properties are not permitted.

DecisionSourceNode

The source node a mapping decision is about.

PropertyTypeRequiredDescription
idstringyesThe node’s identifier in the source.
typestringyesThe node’s type, as the source names it.
paramsSummarystringyesA summary of the node’s parameters, for showing beside the decision.

Additional properties are not permitted.

ImportCandidate

One catalog Component the importer weighed for a source node.

PropertyTypeRequiredDescription
componentNamestringyesThe Component’s name.
scorenumberyesHow well the Component matches the node, as the importer scored it.
tierstringyesThe match tier the score falls in.
signalsCandidateSignalsyesWhat each of the importer’s signals contributed to a candidate’s score.

Additional properties are not permitted.

CandidateSignals

What each of the importer’s signals contributed to a candidate’s score.

PropertyTypeRequiredDescription
tablenumberyesThe contribution of the mapping-table signal.
categorynumberyesThe contribution of the category signal.
domainLabelsnumberyesThe contribution of the domain-labels signal.
shapenumberyesThe contribution of the shape signal.
namenumberyesThe contribution of the name signal.

Additional properties are not permitted.

DecisionChoice

What the importer chose for a source node. Absent from a decision where it made no choice.

PropertyTypeRequiredDescription
targetstringyesThe name of the Component chosen: an existing catalog Component, or the one drafted for the node.
modestringyesHow the choice is written: as a reference to an existing Component, or as a newly drafted one.
tierstringyesThe match tier of the choice.

Additional properties are not permitted.

LintFileFindings

What a convention check found in one document.

PropertyTypeRequiredDescription
filestringyesThe document.
diagnosticsDiagnostic[] or nullyesThe findings in it.

Additional properties are not permitted.

PluginRetractionExclusion

One version that was available and not chosen.

PropertyTypeRequiredDescription
versionstringyesThe version that was passed over.
reasonstringnoWhy it was passed over.

Additional properties are not permitted.

PluginRetractionProvenance

Where the knowledge of what is deprecated came from.

PropertyTypeRequiredDescription
sourcestringyesWhat was consulted.
lastUpdatedstringnoWhen that was last refreshed.

Additional properties are not permitted.

PluginRetraction

How a deprecation marker shaped which plugin version was pinned.

PropertyTypeRequiredDescription
referencestringyesThe reference the versions belong to.
selectedstringnoThe version that was pinned.
excludedPluginRetractionExclusion[]noThe versions that were available and passed over.
unscreenedstringnoWhat could not be screened against a marker, and why.
provenancePluginRetractionProvenancenoWhere the knowledge of what is deprecated came from.

Additional properties are not permitted.

PluginGeneratedDocument

One catalog document a generation produced.

PropertyTypeRequiredDescription
pathstringyesWhere the document belongs, as a path relative to the workspace root.
contentstringyesThe document’s text.

Additional properties are not permitted.

PluginCommandFlag

One flag a plugin declares on a command it contributes.

PropertyTypeRequiredDescription
namestringyesThe flag’s long name.
shorthandstringnoThe flag’s single-character alias, where it has one.
descriptionstringnoThe flag’s one-line help text.
typestringnoThe flag’s value type.
defaultstringnoThe value used when the flag is not passed.

Additional properties are not permitted.

PluginCLICommand

One top-level command verb a plugin contributes.

PropertyTypeRequiredDescription
namestringyesThe command verb.
descriptionstringnoThe command’s one-line help text.
flagsPluginCommandFlag[]noThe command’s flags, in declared order.

Additional properties are not permitted.

ConfigCapturedAttachment

One attachment a freeze wrote into this workspace’s own configuration.

PropertyTypeRequiredDescription
uristringnoThe reference the attachment resolves from.
capabilitystringnoThe capability the attachment is for.
functionstringnoThe export the attachment is dispatched to.
rolestringnoThe role the attachment runs in, which fixes what it may emit.

Additional properties are not permitted.

ConfigCapturedSocket

One socket a freeze wrote, with the attachments it froze onto it.

PropertyTypeRequiredDescription
socketstringyesThe socket.
fieldstringyesThe configuration field the socket is written under.
attachmentsConfigCapturedAttachment[] or nullyesThe attachments that were frozen onto it.

Additional properties are not permitted.

ExplainErrorEntry

One published passage teaching the authoring fix for a condition.

PropertyTypeRequiredDescription
headingstringyesThe passage’s heading.
bodystringyesThe passage.

Additional properties are not permitted.

SignedArtifact

One published artifact a signing covered.

PropertyTypeRequiredDescription
referencestringyesThe reference that was signed.
digeststringyesThe digest of what was signed.

Additional properties are not permitted.

DeprecationMarked

One published version a deprecation marked.

PropertyTypeRequiredDescription
referencestringyesThe reference that was marked.
severityconst “warning” or const “error” or const “retracted”yesHow strongly the marker speaks. Allowed values: "warning" — Deprecated, at the milder of the two advisory tiers: still selected when a version is chosen. "error" — Deprecated, at the stronger of the two advisory tiers: still selected when a version is chosen. "retracted" — Withdrawn: excluded when a version is chosen.
issuedOnstringyesWhen the marker was issued.
digeststringyesThe digest of the marker that was published.

Additional properties are not permitted.

InitializeResult

What the session settled on for this client, and which configuration layer it resolved from.

PropertyTypeRequiredDescription
capabilitiesServerCapabilitiesyesWhat the daemon will do in this session, settled against what the client said it can handle.
workspaceRootstringyesThe workspace the session opened over.
configSourcestringyesWhich configuration layer the session resolved its settings from.
workspaceMarkerstringnoThe file that identified the workspace root, where one did.
versionstringyesThe version of the binary answering this session: the same value aggrega version reports for that binary. It describes the running process, so once the file the daemon was started from has been replaced, this still names the version that is running while asking the file names the version that replaced it.

Additional properties are not permitted.

ValidateResult

What checking found, and how much was checked.

PropertyTypeRequiredDescription
diagnosticsDiagnostic[] or nullyesThe findings. It is null rather than an empty list when the check found nothing.
checkedstringnoHow much was checked — one document, or what the workspace holds.

Additional properties are not permitted.

InvalidateResult

Whether the daemon was holding anything about the document to drop.

PropertyTypeRequiredDescription
invalidatedbooleanyesWhether anything was dropped.

Additional properties are not permitted.

DiagnosticsResult

The findings the daemon already holds for the document.

PropertyTypeRequiredDescription
diagnosticsDiagnostic[] or nullyesThe findings. It is null rather than an empty list when there are none.

Additional properties are not permitted.

IrGraphResult

The resolved graph a Release compiles to.

PropertyTypeRequiredDescription
graphanyyesThe graph document. The values an author declared sensitive are withheld from it unless the request asked for them with unredacted; everything else is carried through as the compiler emitted it. Its own shape is the graph’s published contract and is not restated here.

Additional properties are not permitted.

BuildResult

What a build wrote.

PropertyTypeRequiredDescription
outputDirectorystringyesThe directory the artifacts were written into.
filesstring[] or nullyesThe artifacts that were written, as paths relative to the output directory.
noticesBuildNotice[]noAnything the build wants the caller to know that is neither a finding nor a failure.
dependencyResolutionDependencyResolutionReportnoWhat a dependency resolution pinned and acquired.

Additional properties are not permitted.

BuildPreviewResult

What a build would have written. Nothing was written, so there is no output directory to name.

PropertyTypeRequiredDescription
filesstring[] or nullyesThe artifacts writing would have produced.
noticesBuildNotice[]noAnything the compile wants the caller to know that is neither a finding nor a failure.

Additional properties are not permitted.

EntityDefinitionResult

What an entity name resolves to, and the document defining it. An answer read from a registry reference carries published, and an answer the catalog resolved by name never does.

PropertyTypeRequiredDescription
kindstringyesThe entity kind.
namestringyesThe entity name.
versionstringyesThe version that was resolved.
descriptionstringnoWhat the document says the entity is for.
publishScopestringnoHow widely the entity is published.
filestringyesThe document defining it.
authoredLengthintegeryesHow many bytes the authored document holds, so a client can tell an authored document from a resolved rendering of one.
definitionstringyesThe definition’s text.
publishedPublishedArtifactnoWhat a registry reference read: the coordinate, how it held the entity, and the manifest it was read through. Every field is present wherever this is.

Additional properties are not permitted.

PublishedArtifact

What a registry reference read: the coordinate, how it held the entity, and the manifest it was read through. Every field is present wherever this is.

PropertyTypeRequiredDescription
referencestringyesThe registry reference that was read.
archivebooleanyesWhether the coordinate’s bytes were an archive the entity document was unpacked from. False where the coordinate held the entity document itself.
mediaTypestringyesThe artifact type the manifest declares.
manifestDigeststringyesThe digest of the manifest the entity was read through — the value to name after @ to read the same bytes again exactly.

Additional properties are not permitted.

ReleaseClosureResult

Everything a Release depends on, as resolution reached it. It reports the closure rather than the graph derived from it: a different document about the same Release.

PropertyTypeRequiredDescription
releasestringyesThe Release that was inspected.
aggregatestringyesThe Aggregate it deploys.
manifeststringyesThe Manifest it resolves through.
environmentstringyesThe environment it names.
entitiesClosureEntity[] or nullyesThe entities the closure reaches.
librariesClosureEntity[] or nullyesThe libraries the closure reaches.
pluginsClosureEntity[] or nullyesThe plugins the closure reaches.
mappingDiagnosticsstring[] or nullyesWhat resolving the Manifest’s mappings had to say.
deprecationsstring[] or nullyesThe deprecation markers the closure met.

Additional properties are not permitted.

ResolveDependenciesResult

What a dependency resolution pinned and acquired, plus anything it wants the caller to know. The report’s own fields are carried directly on this answer rather than nested under a member of it.

PropertyTypeRequiredDescription
lockfilestringyesThe lockfile the resolution wrote, or the one a verify compared against.
verifiedbooleannoWhether the request was a verify, which compared the recorded lockfile and wrote no lockfile, plugin trust record or entity.lock.
entitiesClosureEntity[] or nullyesThe entities the resolution pinned, or a verify compared.
librariesClosureEntity[] or nullyesThe libraries the resolution pinned, or a verify compared.
pluginsClosureEntity[] or nullyesThe plugins the resolution pinned, or a verify compared.
sourceArtifactsintegeryesHow many source artifacts were acquired.
trustedPluginsintegeryesHow many of the pinned plugins carried a verified signature.
toolchainToolchainReportnoThe compiler that resolved, and the plugins it carries.
externalInputsintegeryesHow many external inputs the render consumes were acquired.
incompleteExternalInputsstringnoWhich external inputs could not be acquired, where some could not be.
noticesstring[]noAnything the resolution wants the caller to know.

Additional properties are not permitted.

PinResult

What the pin step did to the lock beside an entity, or would do on a dry run. It is the answer to aggrega/pin, and a publication that ran the step carries it as its pin.

PropertyTypeRequiredDescription
entitystringyesThe entity document the step read, as a path relative to the workspace root.
kindstringyesThe entity’s kind, as its document declares it.
namestringyesThe entity’s name, as its document declares it.
pinnablebooleanyesWhether an entity of this kind reads anything a lock records a pin for, which a Recipe and a FeatureRecipe do. Where it is false nothing beside the entity was touched, changed is false, and lock, removed, pins and content are absent.
lockstringnoThe lock the step wrote, or would write, as a path relative to the workspace root.
changedbooleanyesWhether the lock moved, or would move on a dry run. False where the lock already recorded every pin the entity needs and was left byte-identical.
removedbooleannoWhether the move is a removal: the entity reads nothing a lock records a pin for, so no lock is left beside it.
dryRunbooleannoWhether this reports what the step would do rather than what it did.
pinsPinClassCount[]noHow many pins of each class the lock holds after the step, or would hold after a dry run. Every class the lock can hold is listed, a class with no pin included.
contentstringnoThe lock a dry run would write. Absent where the lock would be left as it is or removed, and on every answer that is not a dry run.

Additional properties are not permitted.

PinClassCount

How many pins of one class a lock holds.

PropertyTypeRequiredDescription
classstringyesThe class of pin, in the words a refusal naming a missing one uses — remote source or imported file, for instance.
pinsintegeryesHow many pins of that class the lock holds.

Additional properties are not permitted.

CacheStatusResult

What the caches serving this workspace hold.

PropertyTypeRequiredDescription
classesCacheClass[] or nullyesEach cache and what it holds.
provenanceCacheProvenance[] or nullyesWhich identities the cached artifacts were acquired under.
totalCountintegeryesHow many entries the caches hold in total.
totalSizeintegeryesHow many bytes they occupy in total.
totalSizeTextstringyesThe same total written the way a person reads one.
scopeCacheScopeyesHow far a cache answer reaches. Two of the cache classes are shared by every project on the machine, so every cache answer names which ones it touched — a session opened over one workspace would otherwise be read as reporting only about that workspace.

Additional properties are not permitted.

CachePruneResult

What a reclamation removed, what it kept, and what it could not reclaim.

PropertyTypeRequiredDescription
removedCacheRemoval[] or nullyesWhat was removed.
heldOpenCacheRemoval[] or nullyesWhat the prune would have removed but left in place because another process had it open. Only Windows refuses to remove an open file, so everywhere else this is empty. These entries are counted as neither removed nor kept, none of their bytes count as reclaimed, and a later prune reclaims them; an entry that is a directory may already have lost the files in it that were not open.
retainedCountintegeryesHow many entries were kept.
reclaimedBytesintegeryesHow many bytes were reclaimed.
reclaimedBytesTextstringyesThe same figure written the way a person reads one.
unattributedCountintegeryesHow many entries no holder claims.
unattributedSizeintegeryesHow many bytes those occupy.
unattributedSizeTextstringyesThe same figure written the way a person reads one.
notPruneEligibleCacheShortfall[] or nullyesWhat was left behind, and what would reclaim it.
scopeCacheScopeyesHow far a cache answer reaches. Two of the cache classes are shared by every project on the machine, so every cache answer names which ones it touched — a session opened over one workspace would otherwise be read as reporting only about that workspace.

Additional properties are not permitted.

CacheEvictResult

What reclaiming down to a size removed, and what remains.

PropertyTypeRequiredDescription
withinCapBeforebooleanyesWhether what was held already fitted under the size, so nothing needed removing.
removedCacheRemoval[] or nullyesWhat was removed.
heldOpenCacheRemoval[] or nullyesWhat the reclaiming would have removed but left in place because another process had it open; it went on to the next-oldest entry instead. Only Windows refuses to remove an open file, so everywhere else this is empty. These entries still count toward the bytes that remain, and a later reclaiming can remove them.
totalBeforeintegeryesHow many bytes were held before.
totalBeforeTextstringyesThe same figure written the way a person reads one.
reclaimedBytesintegeryesHow many bytes were reclaimed.
reclaimedBytesTextstringyesThe same figure written the way a person reads one.
remainingBytesintegeryesHow many bytes remain.
remainingBytesTextstringyesThe same figure written the way a person reads one.
capBytesintegeryesThe size that was reclaimed down to, in bytes.
capBytesTextstringyesThe same size written the way a person reads one.
scopeCacheScopeyesHow far a cache answer reaches. Two of the cache classes are shared by every project on the machine, so every cache answer names which ones it touched — a session opened over one workspace would otherwise be read as reporting only about that workspace.

Additional properties are not permitted.

CacheClearResult

What emptying the caches reclaimed.

PropertyTypeRequiredDescription
clearedCacheCleared[] or nullyesEach cache that was emptied.
reclaimedBytesintegeryesHow many bytes were reclaimed.
reclaimedBytesTextstringyesThe same figure written the way a person reads one.
scopeCacheScopeyesHow far a cache answer reaches. Two of the cache classes are shared by every project on the machine, so every cache answer names which ones it touched — a session opened over one workspace would otherwise be read as reporting only about that workspace.

Additional properties are not permitted.

RegistryListResult

The registries this workspace resolves through.

PropertyTypeRequiredDescription
registriesRegistry[] or nullyesEach configured registry.
credentialStateIsMachineWidebooleanyesWhether the credential presence reported for each registry is a machine-wide fact rather than a workspace one. It is reported so a session-scoped answer is not read as denying the wider reach.

Additional properties are not permitted.

SearchResult

What the local registry indexes offered for the search.

PropertyTypeRequiredDescription
recordsRegistrySearchRecord[] or nullyesThe records that matched.
indexesRegistrySearchIndex[] or nullyesEach searched host and when its index was last refreshed.
missingIndexHostsstring[] or nullyesThe configured hosts with no local index to search, so a short answer is explained rather than left to be inferred.
stalebooleanyesWhether any searched index is old enough to be worth refreshing.
registriesConfiguredbooleanyesWhether any registry is configured at all, which distinguishes ‘nothing matched’ from ‘nothing was searched’.

Additional properties are not permitted.

RegistryAddResult

What registering a registry wrote, where, and what it read from the registry itself.

PropertyTypeRequiredDescription
hoststringyesThe host the entry is keyed under, which is not always the spelling the request used.
scopeConfigWriteScopeyesWhich configuration document was written and how far it reaches. A request names one workspace, so an answer that said nothing would be read as being about that workspace — and for a machine-wide write that reading is wrong.
trustTrustFetchOutcomeyesWhat reading a registry’s advertised trust policy did. The outcomes are kept apart because they mean different things: the advertised policy was taken, the registry advertised nothing — which is not a failure — the built-in baseline was pinned in its place, or no read was attempted. Where nothing was advertised, whether the registry could be reached at all is stated beside it.

Additional properties are not permitted.

RegistryRemoveResult

What removing a registry wrote, and where.

PropertyTypeRequiredDescription
hoststringyesThe host whose entry was removed.
scopeConfigWriteScopeyesWhich configuration document was written and how far it reaches. A request names one workspace, so an answer that said nothing would be read as being about that workspace — and for a machine-wide write that reading is wrong.

Additional properties are not permitted.

RegistryUpdateResult

What refreshing the local indexes did, per host.

PropertyTypeRequiredDescription
hostsHostUpdate[] or nullyesWhat the refresh did for each host.
failedstring[] or nullyesThe hosts the refresh could not complete.
indexRootstringyesThe directory the indexes were written under.
registriesConfiguredbooleanyesWhether any registry is configured at all.
reachedRegistriesbooleanyesAlways true on this answer: refreshing the indexes goes out to the registries themselves, where listing them and searching answer from configuration and from a local index. Whether a given registry was in fact reached is stated on its own entry in hosts, by unreachable.

Additional properties are not permitted.

LogoutResult

Which stored credential was removed, and how far the store reaches.

PropertyTypeRequiredDescription
registrystringyesThe registry whose credential was removed.
scopeCredentialStoreScopeyesHow far a credential change reaches. The store is shared by every project on the machine and by every other tool addressing the same registries, so the answer reports that rather than leaving a session-scoped reading to be inferred.

Additional properties are not permitted.

PublishEntityResult

What publishing an entity landed, and where. A publication that ran the pin step first also carries what that step did, as pin, which is absent where the step did not run.

PropertyTypeRequiredDescription
referencestringyesThe reference the entity was published under.
tagstringyesThe tag it was published under.
kindstringyesThe entity kind that was published.
mediaTypestringyesThe media type recorded for the published bytes.
sizeintegeryesHow many bytes were published.
sizeTextstringyesThe same size written the way a person reads one.
pluginSizeintegernoHow many bytes the plugin module published alongside a Plugin entity occupies.
pluginSizeTextstringnoThe same size written the way a person reads one.
digeststringyesThe digest of what was published. On a dry run, the digest a publication of the same content would land, computed from the content alone: the one aggrega push --dry-run prints.
signedbooleanyesWhether this publication attached a signature: the one it made before publishing, or, on a version already published, one the version lacked.
alreadyPublishedbooleanyesWhether the same bytes were already there, so no content was uploaded. Only what that publication still lacked was attached beside it: its publication date and, where this publication signs, its signature; signed says whether a signature was.
dryRunbooleanyesWhether this reports what publishing would have landed rather than what it did.
reachPublicationReachyesHow far a publication reached. These answers reach beyond this machine entirely — what they attach is what every consumer of that registry resolves — so each names every registry it addressed and whether the call attached anything there.
pinPinResultnoWhat the pin step did to the lock beside an entity, or would do on a dry run. It is the answer to aggrega/pin, and a publication that ran the step carries it as its pin.
wholeDirectorySourcestringnoThe entity’s local source as authored, present when it is written as a template. Such a source names its directory only once a Release fills the template in, so the publication carries every file in the entity’s directory rather than only the files the entity names. Absent where it carries only those files.
windowsUnusableEntriesstring[]noThe entries of the published archive whose path holds a part Windows cannot hold as written — a name Windows reserves for a device, such as CON, AUX or NUL, in any letter case and whatever extension follows, or a part ending in a full stop or a space — the entity document’s own file name first, then the files it carries. A workspace on Windows refuses to unpack them, so it cannot use the version; the publication goes ahead or stops exactly as it would without them. Absent where there is none, which includes an entity published as its document alone.

Additional properties are not permitted.

PublishArtifactResult

What publishing a file landed, and where.

PropertyTypeRequiredDescription
referencestringyesThe reference the file was published under.
tagstringyesThe tag it was published under.
mediaTypestringyesThe media type recorded for the published bytes.
sizeintegeryesHow many bytes were published.
sizeTextstringyesThe same size written the way a person reads one.
digeststringyesThe digest of what was published.
alreadyPublishedbooleanyesWhether the same bytes were already there, so no content was uploaded. A publication date was attached beside it only where the artifact lacked one.
dryRunbooleanyesWhether this reports what publishing would have landed rather than what it did.
reachPublicationReachyesHow far a publication reached. These answers reach beyond this machine entirely — what they attach is what every consumer of that registry resolves — so each names every registry it addressed and whether the call attached anything there.

Additional properties are not permitted.

SignArtifactsResult

What was signed, and where the signatures landed.

PropertyTypeRequiredDescription
signedSignedArtifact[] or nullyesEach reference that was signed.
reachPublicationReachyesHow far a publication reached. These answers reach beyond this machine entirely — what they attach is what every consumer of that registry resolves — so each names every registry it addressed and whether the call attached anything there.

Additional properties are not permitted.

DeprecateArtifactResult

What was marked deprecated, and where the markers landed.

PropertyTypeRequiredDescription
markedDeprecationMarked[] or nullyesEach version that was marked.
reachPublicationReachyesHow far a publication reached. These answers reach beyond this machine entirely — what they attach is what every consumer of that registry resolves — so each names every registry it addressed and whether the call attached anything there.

Additional properties are not permitted.

ResolveResult

Where the thing under the cursor is defined.

PropertyTypeRequiredDescription
locationnull or LocationyesWhere it is defined. It is null where nothing under the cursor resolves to a definition.

Additional properties are not permitted.

FindReferencesResult

Where the thing under the cursor is referred to.

PropertyTypeRequiredDescription
locationsLocation[] or nullyesEach place it is referred to.

Additional properties are not permitted.

FindImplementationsResult

Which documents implement the thing under the cursor.

PropertyTypeRequiredDescription
locationsLocation[] or nullyesEach place it is implemented.

Additional properties are not permitted.

HoverResult

What to show about the thing under the cursor.

PropertyTypeRequiredDescription
contentsnull or MarkupContentyesWhat to show. It is null where there is nothing to say about what is under the cursor.

Additional properties are not permitted.

CompletionResult

What may be written at the cursor.

PropertyTypeRequiredDescription
itemsCompletionItem[] or nullyesEach thing that may be written.

Additional properties are not permitted.

CatalogIndexResult

Every entity the workspace index holds, and the links leading out of the workspace, to directories and to files, that were not read for it.

PropertyTypeRequiredDescription
entitiesCatalogEntity[] or nullyesEach entity.
unreadLinkedDirsstring[]yesEach link under the workspace root that leads to a directory outside it, named relative to the root where the link itself sits, in the order the workspace is searched. No directory outside the root is searched, so no document behind one of these links is among entities as the workspace’s own, and a client listing entities can say why. Not named: a link to a directory inside the root, which is searched, or left out, where it actually sits; a link wherever a directory would be left out, whether by where it sits, by its name or by a .gitignore; a link that cannot be resolved, because it leads nowhere or round a loop; and, in an answer given in a Release’s terms, a link under a catalog directory only other Releases read. Empty when the workspace holds none.
unreadLinkedFilesstring[]yesEach link under the workspace root that is named like a YAML file, its own name ending in .yaml or .yml, and leads to a file outside the root, named relative to the root where the link itself sits, in the order the workspace is searched. Such a file is not read for the index, whatever it declares, so the entity it declares is not among entities as the workspace’s own, and a client listing entities can say why; the configured catalog directories are how entities outside the workspace are read. Not named: a link to a file that the workspace configuration names as a Release, as build.authoring_release or as a key of workspace.releases, and that declares one, which is read and listed in entities at the link’s own place; a link to a file inside the root, which is read at the link’s own place; a link a .gitignore leaves out, or one inside a directory the search leaves out; a link that leads to no file, whether to a directory, which unreadLinkedDirs names where it leads out of the root, or nowhere, or round a loop; and, in an answer given in a Release’s terms, a link under a catalog directory only other Releases read. A workspace configuration file that is a link leading out of the workspace, its own .aggrega-config.yaml or the CI-owned overlay beside it, is named whether or not the search met it, after the links the search named: the workspace’s configuration is then not read at all, this answer is the workspace’s own index read with nothing configured, so no catalog directory is read for it, and every request the configuration decides, an index in a Release’s terms included, is refused for that workspace with the read hold’s condition. Empty when the workspace holds none.

Additional properties are not permitted.

AttachCandidatesResult

Which Features may be attached to the entity, and the labels they were judged against; and, for a connection the request named, the slots its socket declares with the Features that may fill each.

PropertyTypeRequiredDescription
nodestringyesThe entity the candidates were judged for.
nodeLabelsmap of string or nullyesThe labels the judgement was made against.
labelSourcestringyesWhich label set was used, which is not cosmetic: a document’s declared labels are what a reading of the source can see, while a graph node’s are the finalised set the build itself judges against. An answer computed over the second is a statement about what the build will do.
candidatesSourcedEntityRef[] or nullyesEach Feature that may be attached.
slotsSlotCandidacy[]noPresent only when the request named a connection: each slot the connection’s socket declares, in the order the Component declares them, with the Features that may fill it. Empty when no slot may be filled on the connection, and noSlotReason then says why — which a client reads rather than taking an empty list for slots no Feature matched.
noSlotReasonconst “feature-created-connection” or const “ad-hoc-socket” or const “no-slot-declared”noPresent only when the request named a connection and no slot may be filled on it: why nothing may attach there. Absent wherever the socket declares a slot. The set is closed. Allowed values: "feature-created-connection" — A Feature drew the connection, and an attachment is written only on a connection a component or the Release draws. "ad-hoc-socket" — The socket is one the Component does not declare, so it declares no slot for a connection to fill. "no-slot-declared" — The Component declares the socket and declares no slot on it.

Additional properties are not permitted.

ConnectionCandidatesResult

Which entities each socket on the entity may be wired to.

PropertyTypeRequiredDescription
nodestringyesThe entity whose sockets these are.
adHocSocketsAcceptedbooleanyesWhether a socket the entity’s own definition does not pre-declare may still be authored.
socketsSocketCandidacy[] or nullyesEach socket and what may be wired into it.

Additional properties are not permitted.

InsertionPointResult

Where in the document a new entry under the named container belongs, and what a client needs in order to write it there: the point itself, whether a line break has to open the text, the container keys that are still missing, and the indentation each line takes.

PropertyTypeRequiredDescription
filestringyesThe document.
containerstring[] or nullyesThe path through the document to the container.
positionEncodingstringyesThe encoding the positions in this answer are expressed in.
positionPositionyesA place in a document: a line and a character offset within it, both counted from zero. The offset is measured in the units of the encoding the session settled on when it was opened, which is UTF-16 unless the client asked for another.
precededByLineBreakbooleanyesWhether the text written at the position has to begin with a line break, because the position sits at the end of a line the document already carries. It is false only where the document carries nothing for the entry to follow.
missingContainerKeysstring[] or nullyesThe container path’s segments the document does not carry yet, outermost first. Each has to be written as a key of its own, indented one step further than the one before it, before the entry can go inside the innermost one. It is null where the whole path is already there.
entryIndentintegeryesThe column the entry’s own first line starts at, counted in spaces from the start of the line.
indentStepintegeryesHow much further each nesting level is indented.
indentStepMeasuredbooleanyesWhether the step was measured from this document’s own nesting. Where it is false the document exhibits no nesting to measure and the step is a fallback, so a client that would rather impose its own knows it is free to.
entryShapeconst “mapping” or const “sequence” or const “unknown”yesThe shape the container carries its entries in, which is what decides how the entry’s own text is composed. It is read off the container the document already carries and is never inferred from what the container is called. The set is closed. Allowed values: "mapping" — The container is a block mapping, so an entry appended to it is a key and its value. "sequence" — The container is a block sequence, so an entry appended to it is a dash and its value. "unknown" — The document does not carry the container, or carries it with nothing in it, so which shape an entry takes is the client’s to decide.

Additional properties are not permitted.

AttachmentContainerResult

Which document, and where in it, an attachment on the graph node, or on the connection the request named, belongs.

PropertyTypeRequiredDescription
nodestringyesThe graph node the attachment is for.
filestringyesThe document the attachment belongs in.
containerstring[] or nullyesThe path through that document to where it belongs.

Additional properties are not permitted.

ConnectionAtPositionResult

The connection whose entry the position falls inside, or why none is reported. Exactly one half is present: graphNode and connection together, or noConnectionReason alone. A position anywhere inside an entry — on its alias, its target or its attachments — is inside that entry, the innermost one where entries nest; a position on a socket’s own key, above the entries written under it, is inside none.

PropertyTypeRequiredDescription
graphNodestringnoThe id of the node whose component draws the connection, as the compiled graph keys it — the value the candidacy and container requests take as graphNode.
connectionConnectionCoordinatenoThe connection, by its socket and its alias, with document naming the document the position was read in — the value the candidacy and container requests take as connection.
noConnectionReasonconst “no-connection-entry” or const “feature-created-connection” or const “unknown-connection”noPresent only where no connection is reported: why. The set is closed. Allowed values: "no-connection-entry" — The position is on no entry an attachment is written in: neither a connection a component draws, written under its alias, nor a per-edge entry in the Release. A connection written as a list of targets, and one a Feature’s own block draws, carry no such entry. "feature-created-connection" — The position is on the Release’s entry for a connection a Feature drew, and an attachment is written only on a connection a component or the Release draws. "unknown-connection" — The position is on an entry the Release writes for a connection the compiled graph does not carry.

Additional properties are not permitted.

ReleaseCandidatesResult

The Releases the workspace holds, and the links leading out of it, to directories and to files, that were not read for them.

PropertyTypeRequiredDescription
releasesstring[] or nullyesEach Release document.
lockfilesmap of stringyesThe lockfile of each Release listed, keyed by the Release exactly as it is listed. Each is the file a pull writes for that Release and a build reads, so a client reads where it lives rather than working it out. Empty when the workspace holds no Release.
unreadLinkedDirsstring[]yesEach link under the workspace root that leads to a directory outside it, named relative to the root where the link itself sits, in the order the workspace is searched. No directory outside the root is searched, so a Release reached only through one of these links is not in releases, and a client offering Releases can say why. Not named: a link to a directory inside the root, which is searched, or left out, where it actually sits; a link wherever a directory would be left out, whether by where it sits or by its name; and a link that cannot be resolved, because it leads nowhere or round a loop. Empty when the workspace holds none.
unreadLinkedFilesstring[]yesEach link under the workspace root that is named like a YAML file, its own name ending in .yaml or .yml, and leads to a file outside the root, named relative to the root where the link itself sits, in the order the workspace is searched. Such a file is not read, so a Release reached only through one of these links is not in releases, and a client offering Releases can say why. Whether a file is a Release is not known without reading it, so each such link is named whatever the file holds. Not named: a link to a file the workspace configuration names as a Release, as build.authoring_release or as a key of workspace.releases, which is read and listed in releases at the link’s own place; a link to a file inside the root, which is read; a link inside a directory the search leaves out; and a link that leads to no file, whether to a directory, which unreadLinkedDirs names where it leads out of the root, or nowhere, or round a loop. A workspace configuration file that is a link leading out of the workspace, its own .aggrega-config.yaml or the CI-owned overlay beside it, is named whether or not the search met it, after the links the search named: the workspace’s configuration is then not read at all, this answer is read with nothing configured, so no Release the configuration names through a link is listed, and every request the configuration decides is refused for that workspace with the read hold’s condition. Empty when the workspace holds none.

Additional properties are not permitted.

ActiveReleaseResult

Which Release a client should act on by default. A workspace pointing at no Release is an ordinary state rather than a failure, so it is reported here with an account of how the choice was attempted rather than raised as an error.

PropertyTypeRequiredDescription
releasestringyesThe Release that was settled on, or empty where none was.
lockfilestringnoThe lockfile of the Release that was settled on: the file a pull writes for it and a build reads. Absent where no Release was settled on.
reasonstringnoWhy no Release was settled on.
tracestringnoEach step of the choice and what it found, so a caller can see which one would have settled it.

Additional properties are not permitted.

EditDocumentResult

What the edit wrote, and where. After a write the daemon’s reading of the document is dropped, so the next answer about it is computed from the bytes the edit produced.

PropertyTypeRequiredDescription
filestringyesThe document that was edited.
editstringyesWhich edit was applied.
containerstring[] or nullyesThe path through the document to where the edit landed.
createdContainersstring[] or nullyesThe containers the edit had to create on the way.
writtenstring[] or nullyesThe documents that were written.
contentstringyesThe composed document, for a request that asked to be shown the result rather than have it written.

Additional properties are not permitted.

EffectiveConfigurationResult

The configuration the workspace resolved, and which document each setting came from.

PropertyTypeRequiredDescription
layersstring[] or nullyesThe configuration documents that were merged, in the order they were merged.
settingsEffectiveConfigurationSetting[] or nullyesEach resolved setting and where it came from.

Additional properties are not permitted.

ConfigInitResult

What seeding a configuration wrote, where, and what it read from the registry.

PropertyTypeRequiredDescription
hoststringyesThe registry the configuration was seeded for.
scopeConfigWriteScopeyesWhich configuration document was written and how far it reaches. A request names one workspace, so an answer that said nothing would be read as being about that workspace — and for a machine-wide write that reading is wrong.
trustTrustFetchOutcomeyesWhat reading a registry’s advertised trust policy did. The outcomes are kept apart because they mean different things: the advertised policy was taken, the registry advertised nothing — which is not a failure — the built-in baseline was pinned in its place, or no read was attempted. Where nothing was advertised, whether the registry could be reached at all is stated beside it.
writtenbooleanyesWhether the document was written, as against handed back for the caller to place.
existedbooleannoPresent and true when the document was already there, so the registry entry was merged into it rather than a new document created. Only a request sending force proceeds over an existing document, so it is absent from every answer to one that did not.
contentstringnoThe document’s text, for a request that asked to be shown it rather than have it written.

Additional properties are not permitted.

ConfigCaptureResult

What freezing the resolved configuration wrote into this workspace’s own document.

PropertyTypeRequiredDescription
configFilestringyesThe document that was written. It is always this workspace’s own, since the whole purpose is to make one workspace self-contained.
workspaceRootstringyesThe workspace the request named.
capturedbooleanyesWhether anything was frozen.
socketsConfigCapturedSocket[] or nullyesEach socket that was frozen, with its attachments.
catalogDirsstring[] or nullyesThe catalog directories that were frozen.

Additional properties are not permitted.

ImportResult

What converting a foreign source produced, and what it could not convert.

PropertyTypeRequiredDescription
formatstringyesThe source format that was converted.
outputDirstringyesThe directory every path in the answer is relative to, and the one the files were written into.
writtenstring[] or nullyesEach file that reached disk, in the order written: the drafts, then the record of what the import wrote. Under sync, only the drafts the sync changed and the record where it changed. Empty under dryRun.
filesImportedFile[] or nullyesEach file the request writes, with its text, under dryRun and without it: every draft, then the record of what the import wrote. Under sync, each draft the sync changes, with its new text, then the record where that changes too, so a sync in step answers an empty list.
driftImportDrift[]yesEach part a sync brought up to date with the source, or under dryRun would, in the order the draft names them; a drafted file the sync deletes is one of them, removed with no keys. An empty list for a request that is not a sync, for a sync in step, and for a sync whose conversion stopped, which writes nothing.
diagnosticsImportDiagnostic[] or nullyesWhat could not be converted.
decisionsImportDecision[]yesHow the importer mapped each source node, in the importer’s order and exactly as it reported it: what tells you where the conversion guessed. Carried under both deliveries and whether or not the conversion stopped, and an empty list for an importer that reports none.
owedImportOwed[]noEach value the drafts still leave empty that no source could supply and no answer did, in the order the drafts are written — the values the warning findings name. Every answer carries it, an empty list where the drafts owe nothing.
haltedbooleanyesWhether the conversion stopped rather than finishing with findings.

Additional properties are not permitted.

ScaffoldEntityResult

The drafted starter document, the list of runnable examples, or the example written — each form answering with its own fields and leaving the others absent.

PropertyTypeRequiredDescription
kindstringnoThe entity kind that was drafted. Present on a draft.
skeletonstringnoThe drafted document’s text. Present on a draft.
examplesScaffoldExample[]noEvery runnable example the documentation publishes, each once, in name order. Present on a list that found any.
examplestringnoThe example that was written. Present on a write.
dirstringnoThe directory the example was written into, relative to the workspace root, as the request named it or, where it named none, as the example’s name. Present on a write.
filesstring[]noEach file written, relative to dir and slash-separated, in the order the documentation carries them. Present on a write.
nextstring[]noThe commands the example’s page gives for building it, line by line as the page writes them, comments included: the first shell block under its Build heading. Absent where the page gives none.
versionstringnoThe version of the documentation the example was read from: the binary’s own where one is published for it, otherwise the newest published before it. Present on a write.

Additional properties are not permitted.

ScaffoldExample

One runnable example the documentation publishes.

PropertyTypeRequiredDescription
namestringyesThe example’s name, which a request sends as example to write it.
levelstringyesThe level the example’s page declares for it.
summarystringyesThe first sentence of the example’s page.

Additional properties are not permitted.

LintResult

What the convention check found, counted by severity and listed per document. A whole-catalog check that ran once for each Release also carries passes; the counts and files then cover every pass together.

PropertyTypeRequiredDescription
entitystringnoThe one entity that was checked, where the request named one.
releasestringnoThe Release whose closure was checked, where the request named one.
checkedintegeryesHow many documents were checked. Where the check ran once for each Release, the sum over the passes: a document two passes read is counted in each.
findingsintegeryesHow many findings there are in total.
errorsintegeryesHow many of them are errors.
warningsintegeryesHow many of them are warnings.
infosintegeryesHow many of them are informational.
filesLintFileFindings[] or nullyesThe findings, per document.
haltedbooleanyesWhether the check stopped rather than finishing with findings.
passesLintPass[] or nullnoThe whole-catalog check one pass at a time, present only where it ran once for each Release because the workspace names Releases under workspace.releases. Each pass says which Releases its findings were found for. Absent for a workspace that names none, which is checked once over its own directories, and for a check of one entity or of a Release’s closure.

Additional properties are not permitted.

LintPass

One pass of a whole-catalog convention check in a workspace that gives its Releases catalog directories of their own: the Releases it was run for, the directories it read, and what it found there.

PropertyTypeRequiredDescription
releasesstring[] or nullyesThe Releases the pass was run for, each as a path relative to the workspace root. Releases that read the same catalog directories share one pass.
catalogDirsstring[] or nullyesThe catalog directories the pass read, in the order they are searched, each relative to the workspace root where it lies inside it. Empty where its Releases read no catalog directory, so the pass checked nothing and failed none of the others.
checkedintegeryesHow many documents the pass checked.
findingsintegeryesHow many findings the pass found.
errorsintegeryesHow many of them are errors.
warningsintegeryesHow many of them are warnings.
infosintegeryesHow many of them are informational.
filesLintFileFindings[] or nullyesThe pass’s findings, per document.

Additional properties are not permitted.

PluginAddResult

What attaching a plugin wrote, where, and which version it pinned.

PropertyTypeRequiredDescription
typestringyesThe socket the plugin was attached to.
identitystringnoThe identity the attachment resolved to.
uristringnoThe reference the attachment resolves from.
capabilitystringnoThe capability the attachment is for.
referencestringnoThe pinned reference, version included.
scopePluginWriteScopeyesWhich configuration document a plugin change was written into and how far it reaches. The command-extension socket’s own default is the machine-wide document, so every answer says which one it wrote.
writtenbooleanyesWhether the configuration document was written, as against handed back for the caller to place.
contentstringnoThe configuration document’s text, for a request that asked to be shown it rather than have it written.
retractionPluginRetractionnoHow a deprecation marker shaped which plugin version was pinned.
withdrawnbooleannoTrue when the query named the version that was pinned and a retraction this workspace trusts has withdrawn that version. A named version is pinned all the same, because naming it is the override. Absent otherwise, and absence does not mean the version is not withdrawn: where the withdrawal markers of a named version could not be read, retraction.unscreened says why, and with no version named, the latest published version is chosen and retraction reports what the withdrawal check concluded about that choice.

Additional properties are not permitted.

PluginRemoveResult

What detaching a plugin wrote, and where.

PropertyTypeRequiredDescription
typestringyesThe socket the plugin was attached to.
querystringyesWhich attachment was removed.
scopePluginWriteScopeyesWhich configuration document a plugin change was written into and how far it reaches. The command-extension socket’s own default is the machine-wide document, so every answer says which one it wrote.

Additional properties are not permitted.

PluginSyncResult

What aligning a Plugin entity’s machine-owned records with its module changed.

PropertyTypeRequiredDescription
entitystringyesThe Plugin entity document that was aligned.
hostFunctionsstring[] or nullyesThe host functions the module declares it needs.
commandsPluginCLICommand[] or nullyesThe commands the module contributes.
changedbooleanyesWhether anything in the document actually moved.

Additional properties are not permitted.

PluginGenCatalogResult

The catalog documents a generation produced.

PropertyTypeRequiredDescription
documentsPluginGeneratedDocument[]noEach generated document and its text.
noticesstringnoAnything the generation wants the caller to know.
dryRunbooleanyesWhether the documents were handed back rather than written.

Additional properties are not permitted.

ExplainErrorResult

What the compiler declares about a condition, and the published passages teaching the authoring fix.

PropertyTypeRequiredDescription
shortCodestringyesThe condition’s short code.
codestringyesThe condition’s descriptive name.
messagestringyesWhat the condition says when it is raised.
entriesExplainErrorEntry[]noThe published passages teaching the fix.
referencestringyesThe published address at which the condition is explained.
notestringnoWhy the published passages are missing, where they could not be acquired. What the binary itself declares is still answered.

Additional properties are not permitted.

GetSchemaResult

A kind’s schema, or — where the request named none — which kinds can be named. The two widths ride on one answer rather than on two methods, because ‘what may I name’ and ‘which of those does an author write documents of’ are the same question at two widths, and two answers would have to be kept in agreement.

PropertyTypeRequiredDescription
kindstringnoThe kind the schema is for.
schemaanynoThe schema itself, carried through as the binary holds it.
kindsstring[]noEvery token this binary answers to.
entityKindsEntityKindDescriptor[]noThe narrower set an author writes a document of, each pairing the token a request names with the kind the document’s own header declares.

Additional properties are not permitted.

SkillsInstallResult

What installing the assistant skill wrote, and where.

PropertyTypeRequiredDescription
skillstringyesThe skill that was written.
installedSkillsInstalledFolder[]yesEach skill folder written, in the order the request named the assistants. Assistants reading one shared folder share one entry, because the skill is written there once.
scopeSkillFolderScopeyesHow far a skill installation reaches. A request names one workspace, so an answer that said nothing would be read as being about that workspace — and for the per-user folders, which an assistant reads in every project, that reading is wrong.

Additional properties are not permitted.

SkillsInstalledFolder

One skill folder an installation wrote.

PropertyTypeRequiredDescription
agentsstring[]yesThe identifiers of the named assistants that read this folder, in the order the request named them.
folderstringyesThe skill’s folder, as an absolute path.
replacedbooleanyesWhether a copy carrying the comment line every written copy of the skill carries — one an earlier installation wrote, or one taken from the published skills repository — was there and has been replaced. A file there without that line is refused rather than replaced.

Additional properties are not permitted.

SkillsListResult

The skills the binary ships and every assistant an installation can write them for. Nothing is written and nothing is reached.

PropertyTypeRequiredDescription
skillsSkillsListedSkill[]yesEach skill the binary ships, in a fixed order.
agentsSkillsListedAgent[]yesEach assistant an installation knows a skill folder for, ordered by identifier.

Additional properties are not permitted.

SkillsListedSkill

One skill the binary ships.

PropertyTypeRequiredDescription
namestringyesThe skill’s name, which is also the name of the folder an installation writes.
descriptionstringyesWhen an assistant uses the skill, as the skill itself declares it.

Additional properties are not permitted.

SkillsListedAgent

One assistant an installation can write a skill for, with the two folders it reads skills from.

PropertyTypeRequiredDescription
idstringyesThe identifier a request names the assistant by.
namestringyesThe assistant’s own name.
projectFolderstringyesThe folder, relative to a project’s root and separated by slashes, that the assistant reads a project’s skills from. A project installation writes the skill’s folder inside it, in the workspace the request names.
userFolderstringyesThe folder, relative to the home directory and separated by slashes, that the assistant reads the user’s own skills from in every project. An installation with global writes the skill’s folder inside it.

Additional properties are not permitted.