aggrega serve
aggrega serve runs Aggrega as a long-running compiler-as-service daemon for IDE integration. It speaks JSON-RPC 2.0 over stdin/stdout and holds catalog-resolver, parse-cache, and diagnostic state across requests, so editor operations get sub-second feedback instead of paying the full catalog-load cost on every keystroke.
The daemon is normally spawned as a subprocess by an editor extension, not run by hand. A VS Code extension is the reference client; other editors can integrate by speaking the same protocol.
The protocol
The wire protocol is JSON-RPC 2.0 with Content-Length framing, under the aggrega/ method namespace. It is intentionally not the Language Server Protocol — Aggrega has domain operations (an IR-graph query, a cache-invalidation signal) that LSP has no analogue for. An editor extension translates between the editor’s LSP requests and these aggrega/* methods; LSP-shaped position, range, and location values are reused where they fit.
Two methods keep their protocol-standard $/ names rather than being renamed into the aggrega/ namespace, because both are transport concerns that carry no Aggrega meaning and a client already speaking the protocol handles them with nothing added: $/cancelRequest, which stops a request the client no longer wants an answer to, and $/progress, which is how the daemon reports a long operation while it runs. Both are described below.
🔴 Every request below carries workspaceRoot, the absolute path of the workspace it acts on, and it is not repeated per method. Three do not, because their subject is not a workspace: aggrega/initialize, aggrega/getSchema and aggrega/scaffoldEntity — except that aggrega/scaffoldEntity writing or listing a runnable example does name one. See Every request names the workspace it is about for what a request naming none gets, and Declaring the workspace you want diagnostics pushed for for where pushed diagnostics go.
The field-by-field shapes are published as a schema, and the wire-shape reference is where to read them. That page states every method’s parameter object, every result and every notification payload — each field with its type, whether it is required, and what it carries — together with three properties that hold across the whole surface rather than per method: the two fields every request admits beyond the ones its own method declares, which are workspaceRoot above and the workDoneToken of Watching a long operation; that a params object carrying a key its method does not accept is refused, with the accepted set named in the refusal; and where an absent collection reaches the wire as a null rather than as an empty one. It is generated from that schema, so it moves when the contract moves.
This page carries the protocol, that one carries the shapes, and they are meant to be read together. Here: the framing, what each method is for, how far it reaches, what it writes, which refusals it raises and why, the error codes and what to do about each. There: what to put on the wire, key by key. So the list below names each method and says what asking it means, and the field list for the request you are composing is in the reference beside it.
Requests:
aggrega/initialize— handshake. Negotiates the position encoding (the server prefers UTF-8, then UTF-16, then UTF-32, and defaults to UTF-16), receives the workspace you declare for pushed diagnostics, and reports that workspace’s root, the configuration layer its settings resolved from, and the marker that resolved it. The reply also carriesversion, the version of the binary answering: the same valueaggrega versionreports for that binary. It describes the process that is running, so once the file the daemon was started from has been replaced — a rebuild to the same path, say —versionstill names the running daemon while asking the file names its replacement; read it here when the question is which version you are talking to.workspaceRootis optional and it declares a workspace rather than acting on one — see Declaring the workspace you want diagnostics pushed for. Sendcapabilities.window.workDoneProgress: trueto say your client can handle progress notifications; the reply’scapabilities.workDoneProgressechoes that, and the field is absent for a client that declared nothing. See Watching a long operation.aggrega/validate— validate a file’s content; returns diagnostics.releaseis a path relative to the workspace root naming the Release to validate against — the same valueaggrega/irGraphtakes, and the same valueaggrega build --releasetakes when run from the root. It is optional, and it selects how far the answer reaches: name a Release and the checks that need one run against it — a catalog entity is checked as a single entity in that Release’s terms, and any other document against that Release’s dependency closure; omit it and the answer covers what the document can be held to on its own, and carriescheckedto say so. A value that is present but malformed is refused either way — an absolute path, or one resolving outside the workspace root, is rejected rather than resolved. See Live validation.aggrega/diagnostics— return the findings held for a file. If a validation of that same file is running when the request arrives, the answer waits for it and reports what it found, so the reply is never a clean bill of health for a file the daemon is in the middle of finding problems in. See Asking for diagnostics while a validation is running.aggrega/hover— hover content for the entity at a position.releaseis optional and answers in that Release’s terms — see Answering in one Release’s terms.aggrega/completion— completion candidates at a position. Where the cursor names an entity by kind — a component’stype, a Feature attachment’stype, anextends:value, a Recipe’s or FeatureRecipe’simplements:— the candidates are the names of that kind your workspace’s own documents declare and, for a Component or a Feature, the names your configuredcatalog_dirsdeclare as well, each offered once and in name order. A workspace that takes its Components and Features from a catalog is therefore offered them, not only what it authored itself. Recipes and FeatureRecipes, offered at a Manifest mapping’s value, come from the workspace’s own documents. An entity only the artifact cache or a registry holds is not offered: answering a completion never fetches.releaseis optional and answers in that Release’s terms — see Answering in one Release’s terms.aggrega/resolve— resolve the entity referenced at a position (go-to-definition).releaseis optional and answers in that Release’s terms — see Answering in one Release’s terms.aggrega/findReferences/aggrega/findImplementations. Each takes an optionalreleaseand answers in that Release’s terms — see Answering in one Release’s terms.aggrega/irGraph— the compiled IR graph for a Release, for editor introspection.releaseis a path relative to the workspace root, naming a Release inside it — the same valueaggrega build --releasetakes when run from the root. Any other form is refused with the standard invalid-params error naming what to send instead: an absolute path, a path that resolves outside the workspace root — whether it climbs out as written or leads out through a link, to the file or to a directory on the way — and an empty value are all rejected rather than resolved, so a request never reports on a file the workspace does not hold. A Release your workspace configuration names, asbuild.authoring_releaseor as a key ofworkspace.releases, is one the workspace holds wherever its file sits, so a link inside the workspace leading to it is accepted, asaggrega/releaseCandidateslists it. A catalog directory the Release reads that cannot be walked — one that is there and cannot be read, say — is refused asaggrega inspectrefuses it, before anything else is read: the error is1004entity-not-resolvable, its message is the report the command line prints for that directory, on one line ([CATALOG_ERROR] <directory>: catalog load: …), and no graph is drawn over the directories that remain. A directory the workspace configuration lists that is not a directory — nothing exists there, say — is refused the same way and at the same moment,1004entity-not-resolvable, its message the refusal every command gives it, naming the entry, the configuration file and line listing it and the setting (Where local entities are read from). A catalog directory holding a link that leads out of the directory its reads must stay inside — a document or a directory linked from elsewhere, beneath a catalog directory inside the workspace or beneath one the configuration names outside it — is refused the same way and at the same moment, with1004and the condition’s own sentence naming the link and where it leads: nothing is read through such a link, and a graph drawn without it could resolve another entity of the same name in its place. So is a link leading out among the documents beside the Release, where the Release names its Aggregate or its Manifest by identity. A file the Release, its Manifest or a Release it extends names by a path —aggregate:,manifest:,extends:or a parameters$import:— that leads out of the workspace, as written or through a link, is refused with the condition’s own sentence (fatal-halts.md §“A reference to another file leads out of the directory it must stay inside”), the error’s data placing it on the key in the Release that led to the file, and nothing is read from that file; a Release the configuration names outside the workspace is held the same way to the directory holding it, so a path it or a Release its chain leads to writes that leaves that directory is refused too. Note thataggrega/releaseCandidatesanswers with absolute paths, so a client feeding one surface from the other converts between the two. That this parameter refuses a spelling the per-documentfileanduriparameters accept is deliberate, and Which spellings a parameter you send accepts says what decides it. The graph withholds every value an author declared sensitive, exactly as--ir-graphwithholds it on the command line: each is replaced by the markeraggrega-inspect“Machine-readable output” describes, and everything else is carried as the compiler recorded it.unredacted: trueasks for those values in the clear — the protocol’s spelling of the command line’s--unredacted, and the one way to ask; absent orfalse, the answer withholds them. Whatever the answer reaches then carries the values in the clear, so a client asks for them only where the person using it has.aggrega/build— compile a Release and write its artifacts into the workspace’s output directory, the same directoryaggrega buildwrites to when run from the workspace root.releasecarries the same contract as above. It renders with every gate on, so a divergence a command-line build would halt on halts here too. A catalog directory the Release reads that cannot be walked — one that is there and cannot be read, say — is refused asaggrega buildrefuses it, before anything is written: no artifact, and no lockfile whereautoPullis set. So is a directory the workspace configuration lists that is not a directory, in the wordsaggrega buildrefuses it in (Where local entities are read from). The refusal is the oneaggrega/irGraphgives for the same directory,1004entity-not-resolvable with the command line’s report on one line, and a link leading out of a catalog directory’s reads, or out of the documents beside the Release, is refused asaggrega/irGraphrefuses it, with nothing written. The answer names theoutputDirectoryit wrote to and thefilesit wrote, each relative to that directory and sorted, alongside anynoticesthe run raised; findings that carry a document position travel onaggrega/publishDiagnosticsinstead. A Release that refuses while it renders is answered with that refusal in the compiler’s words, every cause included, and the refusal is published where it points — see A refusal raised while rendering. WhereautoPullwas set, the answer also carriesdependencyResolution, the same reportaggrega/resolveDependenciesanswers with, so a client that filled dependencies as part of the build reads what was pinned without asking again — and where this build’s resolution took each reference from, a fact about that run which the lockfile does not record. Each notice carries theclassof the surface that raised it —deprecation,catalog,catalog-lint,extends,release-composition, ordependency-resolutionfor a line the dependency resolution below raised — and an emptyclasswhere the daemon has no name for that surface, which a client renders as the baretextrather than guessing at a nearest match. The files the write finds in the output directory, or in a directory beneath it that it wrote a file into or passed through, that this build did not write are left where they are and named in one notice after the run’s own, under an emptyclass, in the sentenceaggrega buildprints its warning in — see Files the build did not write;filesnever names them.outputParentsays where inside the workspace the artifacts go, and its name is the whole of what it means: it is the directory the output directory is created inside, so sendingdocswrites the artifacts todocs/distrather than intodocsitself — exactly what a build run indocsat a terminal produces. Omit it and the build writes where one run at the workspace root writes. It reads differently from theoutputDirthe other writing requests here take, and deliberately so: those name the directory written into, this one names that directory’s parent, and the two carry different names because they are different things. It is still a destination inside the workspace, so an absolute value, one climbing out of the root, and one leading out of it through a link — a linked directory outside the root, or a directory not made yet beneath one — are refused rather than resolved. The output directory created inside it, and every file the build writes there, are held to the workspace as well: where one of them leads out of the workspace through a link, the build is refused with1004and the condition’s own sentence naming the link and where it leads, and nothing is cleared or written.autoPullresolves the Release’s dependencies before rendering, the same resolutionaggrega/resolveDependenciesperforms, and is off unless a request asks for it, matching the command line’s own default; without it a Release that has no lockfile is refused with the lockfile-absent error naming what to run. WithautoPullset this request reaches registries and writes the lockfile — see Reaching a registry, and writing. A request that resolves first still renders the Release once: finding out which remote references a Release consumes is itself a render, so the resolution has already rendered what the build is about, and the build is answered from that render rather than repeating it.policyInputnames a directory inside the workspace, relative to its root, into which the build also writes the payload each governance role hands a plugin attached there — the filesaggrega build --policy-inputwrites, by the same names — whether the build finishes or stops; the answer’snoticesthen say how many were written and name each role written no file for, under an emptyclass. On a request that fails, the files written are on disk and that account is not in the reply: the error envelope carries the refusal alone. It is a destination, so an absolute value or one climbing out of the workspace is refused before anything runs.aggrega/buildPreview— report what a build of the Release would write, writing none of it.releasecarries the same contract as above. It runs the same computationaggrega/buildruns, under the same gates, so a Release either would refuse on both or is reported by both — which is what makes the choice between them a choice about the output rather than about the strictness. A catalog directory the Release reads that cannot be walked, or that holds a link leading out of the directory its reads must stay inside, is refused the same way, before anything is rendered, and so is a directory the workspace configuration lists that is not a directory, as onaggrega/build. The answer carriesfiles, the output-relative names a build would emit, sorted, alongside anynotices; there is nooutputDirectory, because nothing was written anywhere to name. A Release that refuses while it renders is answered and published exactly asaggrega/buildanswers and publishes it. It refusesautoPullwith an invalid-params error naming what to send instead: filling dependencies writes the lockfile, and this request writes no lockfile. It reaches no registry.policyInputis the one write it makes, and only when sent: it writes the governance payloads into that directory exactly asaggrega/builddoes — the filesaggrega build --dry-run --policy-inputwrites — leaving the output directory and the lockfile untouched, with the same account in thenoticesand the same bound: on a request that fails, the files written are on disk and the account is not in the reply.aggrega/resolveDependencies— resolve the Release’s catalog and source dependencies into the cache, pin the external inputs its render consumes into the content-addressed store, and write its lockfile.releaseis a path relative to the workspace root, the same valueaggrega/irGraphtakes and refused in the same shapes.upgradediscards the recorded pins and re-resolves, floating each dependency to the highest available version;targetsnarrows that to the entity references it names, holding every other pin.verifychecks the recorded resolution against the one this request would perform without it, honouring the recorded pins the same way, and writes no lockfile, plugin trust record orentity.lock— the cache is read and filled as it would be without it — answeringverified: trueand thetoolchainthe lockfile records.verifyis refused as invalid params besideupgrade, besidetargets, and besidepinSourceswhichever value it carries, before anything is resolved or any progress is reported: an upgrade drops the pins a verify exists to honour, named targets are re-resolved only by an upgrade, andpinSourcesdecides whether a resolution records the pins anentity.lockis missing or refuses over them, neither of which a comparison that writes noentity.lockdoes. The command line and the assistant tool refuse the same pairs. The answer names thelockfileit wrote or compared against and every reference it pinned, inentities,librariesandplugins, each entry carrying theversionit resolved to and itssource— where this run took the reference from, in the wordaggrega pull --detailprints for the same resolution:fetched-fresh,cache-reuse,local,in-binaryorexternal— alongsidesourceArtifacts,trustedPlugins,externalInputs— how many external inputs the lockfile pins once the run is done, counting both the ones carried forward and the ones this run discovered — and anynoticesthe resolution raised. 🔴 A successful answer does not by itself mean the external-input pinning is complete. Where the run pinned every dependency but could not finish working out which external inputs the Release consumes, it answersincompleteExternalInputssaying what stopped the discovery, and it still answers as a success — the dependency pins are complete and on disk, so reporting the whole request as failed would tell you to redo work that is already correct. Read that field before treating a lockfile as fully pinned: it is absent when nothing was left undiscovered, so its presence is the signal. There is no catalog-directory parameter: the search stack is the one the workspace configures. This is the session’s one pinning request for a Release, and it is where external inputs are pinned too — which URLs a render consumes follows from what it renders, so this request renders the Release to find out, and a build request is then served from what it recorded. A Recipe or FeatureRecipe the Release builds whoseentity.lockrecords no pin for an input the entity reads refuses the request, namingaggrega pinand each input left unrecorded;pinSources: trueruns that pin step over those entities instead, writing theentity.lockbeside each — the same stepaggrega/pinruns, writing the same bytes. Absent,pinSourcesfollows the workspace’spin_sources_at_pull; sent, it overrides that setting in both directions, sofalserefuses even in a workspace configured to pin. This request reaches registries and writes — see Reaching a registry, and writing.aggrega/pin— record, in theentity.lockbeside a Recipe or FeatureRecipe, the content pin for every input the entity reads from outside its own document: a remote source whose coordinates are written out in full, a file an artifacts entry imports, and each file a local source contributes to what a publication of the entity carries. It is the same stepaggrega pinruns at a terminal, and it writes the same bytes.entityis required and is a path relative to the workspace root naming the entity document, refused in the same three shapesreleaseis. No Release is named: a remote source whose coordinates carry no template names one artifact for every Release that uses the entity, so nothing a Release supplies is needed to pin it, while a remote source whose coordinates come from a template is pinned per Release byaggrega/resolveDependencies; a local source written as a template contributes every file in the entity’s directory, and each of those is pinned here.dryRunresolves the inputs and answers with the lock the step would write ascontent, writing nothing beside the entity; the content cache still fills. The answer carriesentity,kind,nameandpinnable— false for a kind that reads nothing a lock records, in which case nothing beside the entity was touched and every other field is absent — and otherwise thelockit wrote,changed(false when the lock already recorded every pin and was left byte-identical),removedwhere the entity now reads nothing a lock records and its lock was deleted, andpins, one entry per class of pin with the count the lock holds. The entity file itself is never written. This writes beside the entity, inside the workspace, and reaches the hosts the entity’s sources name — see Reaching a registry, and writing.aggrega/cacheStatus— what the on-disk caches hold: one entry per cached element with its size and, where it has one, its content digest, grouped by class. Takes the workspace and nothing else. Each class carries areach—workspacefor the artifact cache under this workspace’s own cache directory,machinefor the compiled-module, plugin-describe and documentation-bundle stores every project on the machine shares — andscopenames the machine-wide classes directly. It writes nothing. See Reaching a registry, and writing for why the reach is on an answer that changes nothing.aggrega/cachePrune,aggrega/cacheEvict,aggrega/cacheClear— reclaim cached content. A prune removes what no workspace lockfile references; an eviction trims the compiled-module store tomaxSize, a byte quantity spelled as the command line spells it (5GiB,512MiB, or a byte count); a clear wipes every cache this session addresses. Each answer names what it removed, with each removal carrying thereachof the class it came from, and each carriesscope. Each answer also names what it left in place because another process had it open — Windows refuses to remove an open file, and the operation goes on with the rest rather than failing: a prune or an eviction lists those entries inheldOpen, and a clear counts, for each cache it emptied, the files it left inheldOpenFilesand their size inheldOpenBytes. Elsewhere the list is empty and the counts are zero, and a later run can reclaim what was left. These reach beyond the workspace — see Reaching a registry, and writing.aggrega/registryList— the registries this workspace is configured to reach: each entry’s host, optional alias, whether it is the default, its trust posture as discrete fields, and whether a credential for that host is present. Takes the workspace and nothing else. It contacts no registry. The credential state reports presence only — never the credential, never its shape, and never whether the registry would accept it, which would take a network round trip a listing does not make — and it is read from the machine-wide credential store, whichcredentialStateIsMachineWidesays outright.aggrega/search— search the local index of the configured registries. Every field narrows and every one is optional, so an empty params object asks for everything the index holds. It contacts no network: the index is the offline snapshot written under this workspace’s own cache directory. The reported version is the one a resolution would take — a version whose retraction carries a signature this workspace trusts is excluded and named inretracted— and the answer carries its own provenance:indexesgives each searched registry’s snapshot age,stalemarks one worth refreshing, andmissingIndexHostsnames configured registries with no local index, whose contents are therefore absent from the answer.aggrega/registryAdd— register a registry and its signature trust policy.hostis required; everything else shapes the policy or the write target.keyPathandtrustedRootname files: an absolute value — a file picked in a dialog, say — is read where it names; a relative one names a file inside the workspace, resolved against the workspace root rather than against the directory the daemon runs in, and one climbing out of the root or leading out of it through a link is refused with the invalid-params error before anything is read or written. A relativetrustedRootis recorded as the file it names in the workspace, so the entry names that file whichever directory a later verification runs in.fetchTrustdefaults to true when the key is absent, matching the command line, and takes the registry’s own advertised policy on first contact;trustin the answer says what happened — the policy was pinned, the registry advertised none (and, withunreachablebeside that, could not be reached at all), the official hub’s built-in baseline was pinned in its place, or no fetch was attempted. The registration is the oneaggrega registry addperforms: the same fetch under the same network posture, writing the same entry byte for byte. In an offline workspace the fetch is refused before anything is dialled, so the registry is never asked, and a registry other than the official hub is refused unless the request suppliesidentitiesorkeyPath, which register exactly what was sent and make no fetch: the error’s message is the sentence the command line prints, preceded by the condition’s short codeE0310— as the message of every refusal of this request that names a condition opens with its short code — and nothing is written. The official hub is still written on its built-in baseline, answered withtrust.baselinetrue andtrust.reasonsaying the hub was not asked for its trust policy because the workspace is offline — the reason the command line’s notice opens with — and with nonotAdvertised, because the hub was never asked. This writes the global configuration by default — see Reaching a registry, and writing.aggrega/registryRemove— drop a registry’s entry, addressed by host or friendly alias. A token matching nothing is refused rather than answered as a success over an unchanged configuration. This writes the global configuration by default — see Reaching a registry, and writing.aggrega/logout— remove the stored credential for a registry, the same removalaggrega logoutperforms at a terminal.registryis required and names the registry host as you authenticated to it; there is no friendly alias to resolve here, because the credential store is keyed by the address a client authenticates to rather than by anything a configuration names, so a host no workspace configures may still have a credential you can remove. A host the store holds no credential for is removed successfully and nothing is rewritten — a caller that asked for a host to have no credential has got what it asked for, so that is an answer rather than an error, and it is what the terminal command does too. The answer carriesregistryandscope. It carries no part of the credential in any form, and it reports nothing about whether one had been there: establishing that would take a second read of the store nobody asked for, so askaggrega/registryListwhen presence is the question. It contacts no registry — removing a stored credential is a local act, and whether that registry would have accepted the credential is not asked. This changes the credential store every project on the machine shares — see Reaching a registry, and writing.aggrega/registryUpdate— refresh the local searchable indexaggrega/searchreads. An absentregistryrefreshes every configured one; naming one refreshes only that registry.upgradere-reads every repository in full, comparing nothing with the index already written; a refresh without it already re-reads whatever changed. The answer carries each host’s record count, the repositories it could not read — each with areasonopening with the kind of the read’s last failure where it has one —readsRetried, how many of its reads the registry refused or dropped in passing and were asked again, each counted once and zero included, the deprecation markers it met, theerrorof a host that failed — withunreachablebeside it where that registry could not be reached — andindexRoot, the directory under this workspace’s own cache the indexes were written to. This reaches every registry it refreshes — see Reaching a registry, and writing.aggrega/publishEntity— bundle a catalog entity and publish it to a registry.entityis a path relative to the workspace root naming the document to publish, refused in the same three shapesreleaseis — absent, absolute, or resolving outside the root. A Plugin entity also needsplugin, the same kind of path, naming the executable published inside the entity’s own manifest.registryis the destination and defaults to the workspace’s configured one.dryRuncomputes the bundle and the digest a publication of it would land, and contacts no registry. Omittingsignfollows the destination registry’s own policy, which is what the command line does when its flag is absent, while sending it is the caller’s choice — and neither relaxes the refusal, because a registry or workspace policy that requires a signature refuses an unsigned publication whatever the field says.pinSources: trueruns the entity author’s pin step on the entity before it is bundled, so theentity.lockthe step writes beside it is part of what is published — the same stepaggrega/pinruns. It runs before any refusal that judges the entity’s content — a signing policy, the immutability guard — so a publication refused there still leaves the lock written; a refusal about the request itself, such as an offline workspace or no destination, comes first and pins nothing, and so does the refusal of an entity that shares its directory with another entity, which the step must not write a lock into. Absent, it follows the workspace’spin_sources_at_push; sent, it overrides that setting in both directions. UnderdryRunthe step reports the lock it would write and writes nothing. A publication that does not run the step refuses a Recipe or FeatureRecipe whoseentity.lockrecords no pin for an input it reads, or one the input no longer matches, before anything is bundled — underdryRunas well — namingaggrega pin,pinSources, andpin_sources_at_push; it is the refusalaggrega/resolveDependenciesraises over the same lock. The answer carriesreference,tag,kind,mediaType, thesizepair, the publisheddigest— underdryRun, the digest that publication would land, the oneaggrega push --dry-runprints —signed,alreadyPublished,dryRunandreach;pin— the same answeraggrega/pingives — where the step ran; andwholeDirectorySourcewhere the entity’s local source is written as a template, naming that source as authored. Such a source picks 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, and this field is how a caller learns that it did — on a dry run as well. It also carrieswindowsUnusableEntrieswhere the archive the publication carries holds entries Windows cannot hold as written — a path with a part named after a device, such asCON,AUXorNUL, in any letter case and whatever extension follows, or a part ending in a full stop or a space — naming each, the entity document’s own file name first, then the files it carries; it is absent where there is none, which includes an entity published as its document alone.aggregarunning on Windows refuses to unpack such an entry, so a Windows workspace cannot use the version. These are the entriesaggrega pushwarns about, and a request that asked to be reported on reads the same warning lines among the publication’s progress; neither refuses anything, so the publication goes ahead or is refused exactly as it would be without them, underdryRunas well. This writes to a registry and reaches past this machine, and with the pin step it also writes beside the entity — see Reaching a registry, and writing.aggrega/publishArtifact— publish a standalone data artifact, such as a documentation bundle.fileis a path relative to the workspace root, carrying the same contract, and its bytes are published verbatim: no entity envelope is parsed and no kind is dispatched on.nameandtagname what it is published as, and both are required.mediaTypedefaults to the documentation-bundle type. The answer carriesreference,tag,mediaType, thesizepair, the publisheddigest,alreadyPublished,dryRunandreach. It signs nothing — a published artifact is signed afterwards by reference withaggrega/signArtifacts, which needs only the reference this answer reports. This writes to a registry and reaches past this machine — see Reaching a registry, and writing.aggrega/signArtifacts— sign already-published artifacts and attach each signature.referencescarries one or more registry addresses rather than paths, so they take no workspace-relative contract; an empty list, or an empty entry in it, is refused. One identity serves the whole batch and is resolved before any reference is signed, so a batch with no credential available at all refuses at the start rather than partway through. So does a batch whose references would need different credentials: a request names no key, so that is the workspace’s configuration naming a held key for one reference’s registry and none, or another key, for a second’s — nothing is signed, and the refusal names the registries on each side, as References signed together need different signing credentials describes. Signing a reference nothing published is refused rather than attached to nothing, and a reference already carrying a signature its registry’s trust policy verifies is left as it is and counted as signed, asaggrega signdescribes.jobs, which is optional, is how many references are signed at once: absent, they are signed one after another, and a value below 1 is refused with the invalid-params error before any reference is read. Each reference is still signed exactly as it would be alone, asaggrega signdescribes, and the progress the request reports and the answer both keep the order the references were given. The answer carriessigned, each entry naming areferenceand the publisheddigestits signature commits to, alongsidereach; a batch in which any reference failed is answered as a failure naming each one rather than as a result with a short list. This writes to a registry and reaches past this machine — see Reaching a registry, and writing.aggrega/deprecateArtifact— attach a signed deprecation marker to an already-published artifact. Send either a singlereferencewith itsseverityandreason, orfromnaming a batch file relative to the workspace root — sending both is refused. The content fields are required rather than prompted for: nobody is watching this stream, so a request missing one is refused naming what to send. They belong to the singlereferenceonly: a batch file carries each marker’s content in its own entries, so aseverity,reason,replacementormessagesent besidefromis refused as an invalid parameter naming each one sent, rather than ignored. The same keyless inputs the two signing requests take apply here, because the marker is signed by its own digest, and a batch file’s entries are held to one credential exactly as a signing batch’s references are. The answer carriesmarked, each entry naming thereferencewithdrawn, itsseverity, theissuedOnstamp and the marker’s own manifestdigest— the marker is attached as an untagged referrer of the artifact it withdraws, so nothing else addresses it — alongsidereach. This writes to a registry and reaches past this machine — see Reaching a registry, and writing.aggrega/catalogIndex— the entity index: thekind,name,apiVersion,description,labels, source file andoriginof every entity in the workspace the request named. Takes the workspace and, optionally,release: the set is a property of that workspace root and the catalog directories it configures, or, withrelease, of the directories the configuration gives that Release — see Answering in one Release’s terms. It spans both places an entity comes from — the Aggrega documents under the workspace root, and the Features the configured catalog directories carry — because this is the surface a client joins against when it needs an entity’s descriptive fields, and an index that knew only one of the two would leave part of every candidate list unresolvable. A workspace document counts as an entity when it declares both akind:and ametadata.nameand declares noapiVersionbelonging to another project’s group, so YAML that happens to sit in the tree — a chart’s values file, a CI configuration, a rendered Kubernetes manifest — is skipped rather than listed. A document declaring noapiVersionat all is reported: it is an Aggrega document with a field missing, and seeing it listed is how you find out it is there to fix. See How an entity is addressed for whatoriginand an emptyfilemean. No document behind a link leading out of the workspace root is read: a directory outside the root is not searched, and a file outside it is not read whatever it declares, so an entity your editor shows under such a link is not listed as the workspace’s own — nor offered byaggrega/attachCandidatesoraggrega/connectionCandidates, which read the same documents, even while your editor has that document open. That holds whatever the document declares. The one exception is a Release your workspace configuration names — asbuild.authoring_release, or as a key ofworkspace.releases, judged by the file the link leads to, so naming the link or that file counts alike — which is read, from the file the link leads to, listed at the link’s own place, asaggrega/releaseCandidateslists it, and not named; a file one of those settings names that declares anything other than a Release is not listed, and its link is named. The configured catalog directories are how a workspace reads other entities kept elsewhere, so a link to a directory the configuration lists undercatalog_dirs— for the workspace or for a Release — is not searched as the workspace’s own documents are and not named either: the configuration has reached it, and its Features are listed from the catalog, as every configured catalog directory’s are. The Features listed from the catalog directories never include one behind a link leading out of the directory a catalog directory’s reads must stay inside — the workspace, for a catalog directory inside it, or the directory itself, for one the configuration names outside it — so an entity the answer names as behind a link it did not read is never listed beside that name as well. The answer names each such link inunreadLinkedDirs, for a link to a directory, andunreadLinkedFiles, for a link whose own name ends in.yamlor.ymland that leads to a file — relative to the root, where the link sits, in the order the workspace is searched — so a client can say why. A link the search leaves out, by its name, by where it sits or by a.gitignore, is not named, and in an answer in a Release’s terms neither is one under a catalog directory only other Releases read. A link beneath a catalog directory outside the workspace has no place relative to the root to be named at, and is not named. Both are always present, and empty when there is no such link. Where the workspace’s own configuration file, or the CI-owned overlay beside it, is itself a link leading out of the workspace, that file is named inunreadLinkedFileshowever the search treats it, and the index is the workspace’s own read with nothing configured — no catalog directory is read for it, and an index in a Release’s terms is refused; see Workspace root and active Release.aggrega/entityDefinition— what the named entity resolves to: itskind, its ownnameandversion, itsdescriptionandpublishScopewhere it has them, thefileit was declared in, theauthoredLengthof the authored text behind it, and itsdefinitionas a YAML document with inheritance already applied.fileis reported for every kind, as a path you can open — relative to the workspace root for a document inside it, absolute for one outside, per How a reported path is spelled. It is empty in one case: an entity resolved from a registry has no authored document on this machine to name.authoredLengthanswers a different question — how much authored text the resolution retained — and only an Aggregate is served with any, so read the two separately rather than as a pair.nameis an entity’s identity, written the way one entity references another, and it may carry a version suffix. This is the only request here that starts from a name rather than from a cursor, so it is what to ask when you already know which entity you mean.releaseis optional and resolves the name in that Release’s terms — see Answering in one Release’s terms. A name that resolves to nothing is refused rather than answered with an empty document; see Telling the two by-name refusals apart.namemay instead be a registry reference —oci://<host>/<repository>:<tag>, or@<digest>in place of:<tag>— and the answer is then the entity published at that coordinate, read from its registry, withpublishednaming what was read; see Asking about a coordinate.aggrega/releaseClosure— a Release’s dependency closure: which entities it reaches and at which resolved versions, inentities,librariesandplugins, alongside theaggregateandmanifestidentities its two pointers resolved to, anymappingDiagnosticsthe resolution raised, and thedeprecationsrecorded against what it reached — in its lockfile and in the plugin trust record beside it, so a withdrawn plugin attached in a verdict role is named as a withdrawn pinned reference is.releaseis a path relative to the workspace root naming a Release inside it, the same valueaggrega/irGraphtakes and refused in the same shapes, and it requires a lockfile for the same reason. Nothing is rendered. Its entries name nosource: they say what the Release depends on, not what one run did, which is whataggrega/resolveDependenciesreports. See A closure is not the graph, because a client already receiving the graph does not have this.aggrega/attachCandidates— which Features may attach to a node: the ones whose declared applicability the node’s labels satisfy. Send exactly one coordinate.nodenames a workspace document by itsmetadata.name;graphNodenames a node on the compiled graph ofrelease, by the id that graph keys it under;labelscarries a label set outright and names nothing, for a client that already holds one. The response repeats the coordinate it answered for — empty when there was none to repeat — carriesnodeLabels, the label pairs the match was evaluated against,labelSourcesaying which kind of label set those are, and each candidate as thekind,name, source file andoriginthat address it. Carrying the labels back is what makes the answer auditable from itself: a client can explain why a Feature was offered without forming its own idea of the node’s labels, which is how a client’s answer and the compiler’s come apart. For a graph node, the Features on offer are the ones that node’s Release reaches. BesidegraphNode,connectionnames one connection that node’s component draws — itssocketandalias— and the answer then also carriesslots, each slot that connection’s socket declares with the Features that may fill it, ornoSlotReasonwhere none may be filled. See What an attach-candidate response tells you.aggrega/connectionCandidates— what the named entity may connect to.nodeis an entity’smetadata.name, the same coordinateaggrega/attachCandidatestakes under that name. See What a connection-candidate response tells you below, because the two halves of the answer are not equally complete and the response says which is which.aggrega/insertionPoint— where in an authored document a new entry under a named container belongs, expressed so a client applies it without parsing the document itself.filenames a document the workspace carries, relative to the workspace root, absolute, or as itsfile://address; a document outside the root, as written or through a link leading out of it — to the file, or to a directory on the way — is refused whichever spelling names it, and whether or not you hold a copy of it;containeris the structural path from the document root to the container the entry goes inside, each element a mapping key or a sequence position written in decimal. You supply that path — the daemon reads the document’s own structure and never works out where something belongs from what it is called. See What an insertion-point response tells you, because the position on its own is not enough to apply the edit.aggrega/attachmentContainer— which document a Feature attachment for a node belongs in, and which container inside it.graphNodenames a node on the compiled graph ofrelease, by the id that graph keys it under, and both are required: a node id is a key of one Release’s graph and means nothing without it. The answer carriesnode,fileandcontainer— a list of segments in exactly the shapeaggrega/insertionPointtakes, so the pair composes with nothing to work out in between. For an attachment on one connection the node’s component draws, addconnectionwith itssocket,aliasanddocument—aggregateorrelease— and the answer names that connection’s ownfeaturescontainer in that document. See What an attachment-container response tells you, becausefileis part of the answer rather than something you already know.aggrega/connectionAtPosition— which connection’s entry a position in an Aggregate or a Release falls inside, answered in the terms the two requests above take a connection in.filenames the document the wayaggrega/insertionPointnames one, and it is read from what the session holds for it first;positionis the place in it, alineand acharactercounted from zero in the session’s encoding;releasenames the Release whose compiled graph records the connections, and it is required for a position in the Aggregate too, because a graph node and a connection exist only on a compiled graph. The answer carriesgraphNodeandconnection— itssocket, itsaliasand thedocumentthe position was read in — to hand toaggrega/attachCandidatesandaggrega/attachmentContainerunchanged, ornoConnectionReasonwhere no connection is written there. See What a connection-at-position response tells you.aggrega/editDocument— apply one bounded structured edit to an authored document, preserving every byte it does not touch. It is the other half of the two locating methods above: those say where an entry belongs and leave you to compose and apply it, this composes and applies one.editnames which of four —add-component,attach-feature,wire-edge,set-value— and a value outside them is refused rather than interpreted;nodeis the structural path from the document root, a list of segments in exactly the shapeaggrega/insertionPointtakes;nameis the key the entry is written under andvaluewhat it carries, whose meaning follows fromedit;socketis read forwire-edgeand ignored otherwise.dryRundoes everything the plain request does except write, answering with the edited document ascontent, for a client that puts the result in front of the author first; nothing is created under it andwrittenis empty.filenames the document relative to the workspace root or by its absolute path, and a document outside the root — as written, or through a link leading out of it, to the file or to a directory on the way — is refused with nothing read or written. This writes the document you name, inside the workspace — it resolves no dependency, reaches no registry and touches no network under either delivery, and the write is gated on the composed document validating against its own kind’s schema. See What a document-edit response tells you, because the default is the write and a refusal leaves the file byte-for-byte as it was.aggrega/releaseCandidates— the Release documents of the workspace the request named, as absolute paths. Takes the workspace and nothing else: the set is a property of that workspace root. Membership is decided by document kind — the file’skind:isRelease— and not by filename, so a Release named without a conventional prefix is offered and a file merely named like one is not. This is what an editor’s “which Release?” picker should list, because it is the same set the active-Release cascade below chooses from. The answer also carrieslockfiles, which maps each listed Release — keyed by exactly the stringreleaseslists it under — to the absolute path of its lockfile; it is always present, and an empty object when the workspace holds no Release. It carriesunreadLinkedDirstoo, naming — relative to the root, where the link sits — each link that stands where the listing would read a directory and leads to a directory outside the workspace root: no directory outside the root is searched, so a Release your editor shows inside one is not listed, and this field is what lets a picker say why. A link to a directory your workspace configuration lists undercatalog_dirsis not named: the configuration has reached it, as a catalog directory rather than as a place Releases are kept. It is always present, and empty when there is no such link. Beside it,unreadLinkedFilesnames the same way each link whose own name ends in.yamlor.ymland that leads to a file outside the workspace root: no such file is read, whatever it holds, so a Release reached only through one of these links is not listed, and the single-Release step of the cascade below does not count it. The exception is a file your workspace configuration names as a Release — asbuild.authoring_release, or as a key ofworkspace.releases, judged by the file the link leads to, so naming the link or that file counts alike — which is read and listed at the link’s own place, and not named, provided it declares a Release; one that declares anything else is not listed, and its link is named. It is always present, and empty when there is no such link. Where the workspace’s own configuration file, or the CI-owned overlay beside it, is itself a link leading out of the workspace, that file is named here however the search treats it, and the listing is read with nothing configured, so a Release the configuration would have named through a link is not listed; see Workspace root and active Release. See Where a Release’s lockfile is.aggrega/activeRelease— which Release the workspace the request named points at, as an absolute path in areleasefield, for a client deciding what to select by default. Takes the workspace and nothing else. The field is always present, and an empty value means the workspace points at none — a successful answer rather than an error, so a client that refreshes this on every daemon restart is not made to treat an ordinary workspace as a failure. When the value is empty the answer also carriesreason, a one-line summary of what the cascade looked for, andtrace, the per-step account of it; both are omitted when a Release resolved. When a Release resolved, the answer carrieslockfileinstead, the absolute path of that Release’s lockfile, which is omitted when none did. The Release it names need not be oneaggrega/releaseCandidateslists — a marker may name a Release in a directory that listing leaves out, such asvendor/, or one named without a YAML extension — so this answer is where a client reads the default Release’s lockfile. See Where a Release’s lockfile is. Ask for it rather than working the answer out from one of the cascade’s inputs: an input the cascade did not end up using names a different Release than the one it chose. The answer is computed when you ask, so asking again after writing a marker, editing the configuration or adding a Release file reports the new answer rather than the workspace as it stood when the daemon started.aggrega/setActiveRelease— records a Release as the default of the workspace the request named, by writing that workspace’s.aggrega/active-releasemarker, and answers exactly asaggrega/activeReleaseanswers once the marker is written. Takes the workspace andrelease: a path relative to the workspace root naming a Release inside it, held to the contractaggrega/irGraph’sreleaseis held to — an absolute path, one climbing out of the workspace and an empty value are refused, and so is one leading out through a link unless your workspace configuration names that Release. The marker is one line naming the Release relative to the root, the form the cascade below reads. It is written inside the workspace and nowhere else: where.aggrega, or the marker itself, is a link leading out of the workspace — whether or not the place it leads to exists yet — the request is refused with the invalid-params error, its message the condition’s own sentence with its short code ahead of it,E0320: …(fatal-halts.md §“A path the operation writes leads through a link out of the directory it must stay inside”), naming the link and where it leads, and nothing is written; a link that stays inside the workspace is written through. The answer names what the cascade settles on rather than echoing what you sent, and the two differ wherebuild.authoring_releasenames a Release, since the configuration outranks the marker. Record a default this way rather than writing the file yourself, so that where the marker lands is judged by the rule every file the product writes in the workspace is held to — see The workspace boundary.aggrega/effectiveConfiguration— the configuration in force for the workspace the request named, and the layer each setting came from. Takes the workspace and nothing else: the answer is a property of that workspace.layerslists the config files and environment overrides that contributed, lowest precedence first;settingscarries each attributed setting as its dotted name, its effective value, and thesourcethat determined it. Asourceis spelled exactly as the matching entry inlayers, so the two join directly. See What the effective-configuration response covers for which layer asourcenames and the bounds on what a row means.aggrega/configInit— seed a working configuration by registering a registry and its signature trust policy, so a fresh machine can pull and verify signed artifacts without editing YAML by hand.registryis optional and an absent value seeds the official hub, the same defaultaggrega config initcarries; the answer’shostnames whichever was used.globalandworkspaceare the write-target overrides and sending both is refused. It refuses rather than overwrite an existing configuration file, naming the file — sendforceto proceed anyway, which merges the registry entry into what is already there and preserves the other settings.dryRundoes everything the plain request does except write, answering with the seeded configuration ascontent, for a client that puts the document in front of the author before it is saved; nothing is created under it andwrittenis false. The existing-file refusal applies underdryRuntoo, so sendforcealongside it to be answered with the merge an overwriting write would produce. In an offline workspace only the official hub can be seeded: this request takes no identities or key, so any other registry is refused exactly asaggrega/registryAddrefuses it, short code and sentence included, and is added through that request with a policy supplied by hand instead. The answer carrieshost,scope,trustandwritten, andexisted, true where the configuration file was already there — so the registry entry is merged into it rather than a new file created — and absent where the file is created. This writes the global configuration by default — see Reaching a registry, and writing.aggrega/configCapture— freeze the effective build-critical configuration into this workspace’s own configuration file, so the workspace builds the same without the machine’s global configuration underneath it. Takes no write target: freezing exists to make one workspace self-contained, so it always writes that workspace’s file.allPluginswidens the frozen set from the sockets that determine the rendered output — the provider bindings and the label-transform governance attachments — to every plugin socket, adding the verdict governance and linter gates and the import socket. The answer carriesconfigFile,workspaceRoot,captured,socketsandcatalogDirs. See What a configuration write leaves behind, because the answer names a document that now exists and a client’s next act is opening it.aggrega/skillsInstall— write the Aggrega skill built into this binary into the skill folder of each assistant the request names, the same installationaggrega skills installperforms at a terminal.agentslists the assistants by identifier, the identifiersaggrega/skillsListreports; an identifier given twice is installed once, and where several of the named assistants read one shared folder the skill is written there once. A project installation requires it. Aglobalrequest naming none installs for the assistants found on this machine, asaggrega skills install --globaldoes with no--agent— each one whose configuration folder is in the home directory, or whose command is on thePATHof the daemon’s environment — and is refused with nothing written where none is found; nothing is prompted for, andinstallednames the assistants it wrote for. Withoutglobalthe skill lands in each assistant’s project folder inside the workspace the request names, never in the directory the daemon was started in; withglobal: trueit lands in each assistant’s per-user folder under the home directory the daemon’s environment names (HOME, orUSERPROFILEon Windows). Every target is checked before anything is written, so a refusal leaves every folder as it was: an identifier no skill folder is known for is refused naming it and the identifiers there are, and a file at a target that does not carry the comment line every written copy of the skill carries is refused naming its path. A copy carrying that line — one an earlier installation wrote, or one taken from the published skills repository — is replaced, which is how a neweraggregabrings the skill up to its own version. A project folder reached through a link leading out of the workspace is refused with nothing written, as every write the daemon makes in a workspace is — see The workspace boundary. The answer carriesskill,installed— one entry per folder written, in the order the assistants were named, each with theagentsthat read it, the absolutefolderandreplaced— andscope. Withglobalthis writes folders every project on the machine reads — see Reaching a registry, and writing.aggrega/skillsList— the skills this binary ships and every assistantaggrega/skillsInstallcan write them for, the listingaggrega skills listprints. Takes the workspace and nothing else, and reads nothing from it.skillscarries each skill’snameanddescription;agentscarries each assistant’sid,name,projectFolder— relative to a project’s root, which on this surface is the workspace a request names — anduserFolder, relative to the home directory, both separated by slashes, ordered by identifier. It writes nothing and reaches nothing.aggrega/pluginAdd— search the configured registry for a plugin of a named type and add it to the configuration.typeandqueryare both required:typeis one ofprovider,governance,linter,importerandcli, andqueryis matched against the plugin names of that type and must resolve to exactly one, so a query matching several is refused with the candidates rather than resolved arbitrarily.capabilitynames the capability aproviderbinding serves and is required there;rolenames agovernanceattachment’s role —label-transform,ir-verdictorrender-verdict— and is required there; each is read for its own type alone and refused on any other, because a field that silently did nothing would read as though it had worked.acceptCapabilitiesis required forcliand confirms that plugin’s declared capabilities: the terminal command obtains that decision by asking, and this surface has nobody to ask, so the caller obtains it and sends it.globalandworkspaceare the write-target overrides and sending both is refused.dryRundoes everything the plain request does except write, answering with the resulting configuration ascontent; nothing is created or modified andwrittenis false. The registry is still searched and the version still resolved, because the identity in that content is the identity a write would have pinned.dryRunis refused on theclitype, rather than ignored: what a command-extension addition records is the content digest of the bytes it verified, which is a record the compiler maintains rather than content anyone edits, and the addition caches those bytes as it goes — so it is written rather than handed back. The version is pinned for you — the query resolves to one plugin, and the version it names as<name>:<version>, or else its highest published version, is written into the entry; a named version a retraction this workspace trusts has withdrawn is pinned all the same and the answer carrieswithdrawn: true. This reaches a registry, and acli-type addition naming neither scope writes the global configuration — see Reaching a registry, and writing. See What a plugin change tells you.aggrega/pluginRemove— drop a configured plugin’s entry so it no longer participates.typeis the same set an addition takes, andqueryidentifies the entry: the plugin’s short name, its pinned reference, or — forprovider— the capability the binding serves. Both are required.globalandworkspaceare the same write-target overrides, refused together in the same way. A query matching no entry is refused rather than answered as a success over an unchanged configuration, so a caller is never told a plugin stopped participating when it did not, and a typo never removes a different plugin. It contacts no registry: a removal operates on the configuration text alone. Acli-type removal naming neither scope writes the global configuration — see Reaching a registry, and writing. See What a plugin change tells you.aggrega/pluginSync— align a Plugin entity’s machine-owned records with its module: the host-function set derived from the module’s own imports, and the command mirror read from the module’s self-report. Neither record is authored by hand, because both are ground truth in the module. Both fields are required and neither has a default — the records are derived from the module, so an alignment naming none has nothing to align to — and both are paths relative to the workspace root, refused when absolute or resolving outside it, as written or through a link. Only those two blocks change: every other byte carries through verbatim, comments and blank lines and quoting style included, and a file already recording what the module implies is left byte-identical and reported as unchanged. This writes the entity file you name, inside the workspace, and it contacts no registry. See What a plugin change tells you.aggrega/pluginGenCatalog— generate one Plugin entity per selected guest, merging the contract fields derived from the guest’s self-report with an authored per-plugin overlay.fromEmbeddedandpluginare the two selection modes and exactly one applies: every guest this binary carries, or one module at a path you name; naming both, or naming neither, is refused rather than resolved.overlayis required, and it is a directory of overlays underfromEmbeddedor a single overlay file underplugin— an overlay is matched to a guest by identity when there are several, and there is nothing to match when there is one.outputDiris required under both deliveries, anddryRundoes not excuse it: a dry run changes where the content goes, not which file it is content for, so each returned document still names the path it is for and that path is composed from this directory. The three paths here are not judged alike, and the split follows what the generation does with each.pluginandoverlayare read, and both are files you selected — a module lands under whatever directory its toolchain builds into, and its overlay is authored beside it — so each may be absolute and is read where it actually is.outputDiris written to, so it is relative to the workspace root and refused when absolute or resolving outside it, as written or through a link — a directory not made yet beneath a linked directory leading out is refused as that directory is. Re-running over unchanged inputs produces byte-identical entities. This writes the generated entities underoutputDir, inside the workspace, unlessdryRunasks for them as content instead. See What a plugin change tells you.aggrega/getSchema— the JSON Schema for an entity or contract kind, read from the copy compiled into the running binary.kindis the lowercase-hyphenated schema token —component,aggregate,release,recipe,ir,wasm-provider, and so on — and it is optional, because it selects which of two questions you are asking. Name a kind and the response carrieskindandschema, the schema as a JSON document rather than as a string holding one. Name none and the response carrieskindsandentityKindsinstead: which kinds you may name, at two widths.kindsis every token this binary can be asked for, in the same orderaggrega get-schema --listprints them.entityKindsis the narrower set an author writes a document of, each entry carrying thekindtoken to send back, thedocumentKindvalue that goes in the document’s ownkind:field, andacceptedBy, which says whether single-entity validation, publication and inspection by name accept a document of that kind. See Which kinds you may offer an author before you build a chooser from either. The schema answer and the enumeration are never combined, so which question was answered is readable from the response. A token no schema answers to is refused with the whole valid set in the message, so a typo is corrected without a second call. It takes nothing from the workspace, contacts no registry and writes nothing, so it answers in a workspace holding nothing at all — which is what makes it usable for wiring an editor’s schema association against the binary the editor is actually driving, rather than against whichever copy of the schemas is installed elsewhere.aggrega/scaffoldEntity— a starter document for an entity kind: exactly the fields that kind’s schema requires, with the fixedapiVersionandkindfilled in and a placeholder everywhere a value is needed.kindis required and is the lowercase-hyphenated schema token —component,aggregate,release,recipe,manifest,feature, and so on;aggrega/getSchemawith nokindreports which tokens you may send, and a token no schema answers to is refused with that set in the message so a typo is corrected without a second call. A client offering the author a choice of kind reads that method’sentityKinds, which is the set of kinds a document can be written of.nameis optional and seedsmetadata.namefor kinds whose schema requires one. The response carrieskindandskeleton. See What a scaffold response gives you, because the answer is a document to write and not a document that was written. The skeleton is derived from the same schemaaggrega/getSchemareports, so the two answer from one source. Sentexampleinstead ofkind, it writes one of the documentation’s runnable examples into a new directory of the workspace, asaggrega scaffold --exampledoes at a terminal; sentlist: truealone, it answers with every example there is and writes nothing. Both forms need the workspace, so a request for either names it inworkspaceRootand one naming none is refused.dirnames the new directory relative to the workspace root, and defaults to the example’s name; an absolute value, or one resolving outside the root — as written, or through a link — is refused before anything is read, and a directory that holds anything is refused and left as it is. The answer to a list carriesexamples, each with itsname,levelandsummary; the answer to a write carriesexample,dir,files— each file written, relative todir—next, the commands the example’s page gives for building it, absent where it gives none, andversion, the documentation version the example was read from. Fields of two forms sent together —kindwithexample,listwithexampleorkind,namewithexampleorlist, ordirwithoutexample— are refused before anything is read, in the words the assistant tool refuses them in. A write acquires the documentation bundle where the machine holds no copy the workspace’s own signature check admits, and writes inside the workspace — see Reaching a registry, and writing.aggrega/import— turn a foreign source description into draft Aggrega authoring files, the same conversionaggrega importperforms at a terminal.sourceis required and names the file or the directory to convert, either as an absolute path or relative to the workspace root — a description exported by another tool sits wherever you saved it, so this one is read where it actually is rather than only inside the workspace. A directory is read asaggrega importreads one: into the files of it the importer’s declared file patterns select, the workspace’s build output folderdist/left out, and held to itself wherever it lies, so no link inside it is followed out of it.outputDiris optional and names the directory the drafts go in, and it does not carry that contract: it is written to, so it is a path inside the workspace and an absolute value, or one resolving outside the root — as written, or through a link, a directory not made yet beneath one included — is refused. Omit it and the drafts go beneath the workspace root, whereaggrega importwrites them when it names no destination — underdryRunas well.formatnames the source format explicitly; omit it and the format is recognised by the signatures the importers declare — the workspace catalog’s and the compiler’s core importers’ alike — and a source none recognises, or importers of more than one format recognise, is refused asking forformatrather than guessed at.targetnames a provider capability, such ascomposeorhelm— the word a Recipe’sspec.capabilitybinds to — and drafts, beside the importer’s drafts, the Manifest the drafted Release builds against for that provider, exactly asaggrega import --targetdoes:manifest.yaml, mapping each component type and feature type the drafts need — the types of a catalog Aggregate the drafted one composes included — to the Recipe or feature recipe of that capability the workspace’s catalog offers for it, by its capability-qualified name with no version: the one there is, or among several the one named after the type. The Release’sspec.manifestis set to it; a type with none, or with several and none so named, is left unmapped with awarnfinding naming it, and a mapping an importer drafted itself is kept where the catalog offers it for that type and capability and dropped with awarnfinding otherwise. Atargetno Recipe in the catalog binds to is refused before the importer runs, naming it and the capabilities the catalog’s Recipes bind to, and nothing is written; omit it and no Manifest is drafted — except undersync, which drafts for the target the record of the earlier import names. A core importer the machine does not hold yet is fetched by the first import that needs it — see What an import response tells you.dryRundoes everything the plain request does except write, answering with the drafts as content, for a client that puts them in front of the author first; nothing is created under it andwrittenis empty.syncbrings what an earlier import drafted inoutputDirup to date with the source, changing only what the import wrote, asaggrega import --syncdoes; without it, a request whose drafts would be written over an Aggregate already there is refused. The answer carriesformat,outputDir,written,files,drift,diagnostics,decisionsandhalted. See What an import response tells you, because a source the importer could not fully convert is a successful answer rather than an error.aggrega/explainError— what the compiler declares about the condition a code names, and the published entries that teach the authoring fix.codeis required and takes either of a condition’s identifiers: the short code a diagnostic carries inshortCode, or the descriptive one incode. It is the expansion of a code the diagnostics on this wire already carry, and it is the same answeraggrega explainprints at a terminal. The answer always carries the condition —shortCode,codeandmessage— because that much is declared inside the binary and needs no network;entriescarries the published walk-through, andnotesays why it is missing where it is. This acquires the documentation bundle where the machine holds no copy the workspace’s own signature check admits — see Reaching a registry, and writing. See Expanding a code a diagnostic carried.aggrega/invalidate— a cache-invalidation signal from the editor’s file watcher.
Notifications:
$/cancelRequest— client to server: stop the in-flight request sent under that id. The daemon cancels that request’s work; an operation observes the cancellation at its next step boundary rather than instantly, so work already under way runs on for a moment. Cancelling an id nothing is running is a safe no-op.$/progress— server to client: what a long operation is doing while it does it, on the token the request asked to be reported on. Sent only for a request that carried one. See Watching a long operation.aggrega/shutdown— begin a cooperative drain: in-flight requests finish, new requests are refused, then the daemon exits.aggrega/publishDiagnostics— a server-pushed diagnostic set (used for lockfile-drift warnings and at-startup state). Each entry carries asourcenaming which of the daemon’s diagnostic layers raised it:aggregafor a finding about the authored documents,aggrega-buildfor an advisory a build raised — every advisory it raised, which is the same setaggrega buildprints — andaggrega-lintfor a publishing-conventions finding, the same findingsaggrega lintprints. The field is always present on every entry, so a client can group them rather than showing one undifferentiated list, and never has to tell an absent source apart from one of the layers. A frame is sent for a file only when its set differs from the one this client was last told about, so a request that recomputes the same findings sends nothing; a file’s first frame, and a frame that empties a file’s set, are both differences and are always sent.
Asking the process itself to stop reaches the daemon on the same terms. An interrupt from a terminal, or a termination request from a supervisor or a container runtime, begins the drain aggrega/shutdown begins: in-flight requests finish, new requests are refused, then the daemon exits. A second request ends the process at once. A client that spawns the daemon can stop it either way, and one that stops it over the wire and one that signals it get the same drain.
Live validation
On each aggrega/validate the daemon validates the editor buffer against the document’s schema and returns diagnostics pointed at the offending key — the same verdict a build would give, on unsaved content. A request that sends no content asks about the file as it is on disk; a content sent empty is an empty buffer, not a request for the file. A file sent without its content must be one the workspace carries and one that can be read — a file outside the workspace, one reached through a link leading out of it, or one that is not there is refused with the invalid-params code. Catalog entities, Aggregates, Manifests, and Releases are recognized by their apiVersion and kind. The two documents that carry no such header — the .aggrega-config.yaml workspace config and the lockfile of the Release the request named — are recognized by filename instead, so a junk or misshapen key in either one also squiggles live. Files that are not Aggrega documents — Helm chart templates, Compose files, Kubernetes manifests, and other ecosystems’ .lock files such as Cargo.lock or flake.lock — receive no diagnostics; the daemon never reports on foreign files.
A placeholder still owed is named at its key, with what it takes. A catalog entity of a kind aggrega validate checks as a single entity is also read for the required values it leaves as an empty string, by the reading that command applies, so the daemon names every placeholder the command names for the same bytes. Each placeholder is one entry: its message says the key is a placeholder still owed, its suggest says what the value takes, and its keyPath carries the key’s dotted path. The entry takes the place of the schema’s own finding for that empty value, and every other finding on the document is reported as the schema check reports it. A placeholder the schema admits empty is named too, although the schema check reports nothing about it — a drafted Recipe’s or FeatureRecipe’s capability and implements are the ones you will meet. Where the schema check refuses the document as well, each entry carries that check’s code, E0215, and where it accepts the document the entries carry no code: the same identifiers the command’s report carries for those bytes. An entry is drawn at the key holding the empty value, on the line the command names it at — even a key whose own name contains a dot, such as the component.aggrega.ai/type label, where a finding the schema check reports on that key is drawn at the key that encloses it — and keyPath names the key in full. This holds whether or not the request names a Release, because it is a question the document answers by itself, and a document still owing a value is not yet one the publishing conventions are asked about: that layer is cleared for it, as it is for a document whose shape the schema refuses.
Each request names the Release it is about, and the daemon keeps none of its own. The semantic checks resolve that Release’s dependency closure and read that Release’s lockfile for its pins — or, for a catalog entity, read the catalog directories that Release builds with, as the next paragraph describes — so two requests naming two Releases are answered about the Release each one named. Nothing carries over between them: there is no selected Release to change, and changing which Release you validate against is a different value on the next request rather than anything the daemon has to be told to forget.
A catalog entity named with a Release is checked as a single entity, in that Release’s terms. A file holding a Component, a Feature, a Recipe, a FeatureRecipe or a Plugin, sent with a release, gets the check aggrega validate <path> --release <release> runs, over the editor’s unsaved buffer: its references — the Component a Recipe implements, a library a pillar refers to — resolve through the catalog directories the workspace configuration gives that Release, so one file can be clean in the terms of the Release that builds with it and fail in the terms of a Release whose directories do not hold what it refers to. That is the verdict the command line and the validate tool of aggrega mcp give for the same entity beside the same Release, and like theirs it walks no closure and reads no lockfile. A blocking finding is one error entry in the check’s own words and carrying its codes, drawn on the key it names in the entity and, where it names none, on the entity’s kind: key, as What a diagnostic entry carries describes — unless a build already reports that fault on the file, in which case the build’s entry is the one report; an advisory the check raises while reading the catalog is a warning entry ahead of it; a clean check over directories that are all there answers no entry. A failed assertion — one that calls fail, in the Recipe or in the Component it implements — is not a blocking finding here but a warning entry, in the check’s words and carrying its codes, closed by the sentence A Release must satisfy this assertion before a build of it can pass., and drawn where the blocking finding would be: a Recipe’s assertion on that assertion’s own key under assertions, a Component’s on the Recipe’s kind: key. Like a blocking finding, it gives way to a build’s entry reporting the same fault on the file. The check builds the entity around placeholders and schema defaults rather than the values a Release sets, so it cannot tell an assertion waiting on a Release from one that is broken, and leaves the verdict to a build, which reports the same assertion as an error (a failed assertion is a warning). A directory the workspace configuration lists for the Release that is not a directory — nothing exists there, say — is not checked past: the file carries one error entry instead of the check’s verdict, the refusal every command gives that directory, naming the entry, the configuration file and line listing it and the setting (Where local entities are read from). A release naming no file, or naming a directory, is answered on the file with the sentence the command line refuses it with, rather than checked in the workspace’s terms. What a build of one cannot stand in for is judged as the command line judges it, and what the command line sets aside or does not check answers no entry here — see what single-entity correctness does not check, and, for a Recipe whose template reads a value only a topology edge or an attached credential delivers, single-entity correctness. The Release’s own Aggregate, a Manifest, a Release and a library are not checked one at a time, because the single-entity check does not take those kinds; they keep the closure’s checks above. A buffer holding Workload content is read as YAML that is not an Aggrega document, because that content is written inside a Recipe’s or a FeatureRecipe’s workload: field and is checked there, where it sits; the command line and the validate tool, handed a Workload file by path, check its shape on its own.
Naming a Release is optional, and the answer says which of the two you asked for. Name one and you get everything above. Name none and you get the checks a document answers for by itself — whether it parses, whether its own shape is admissible, and, for a catalog entity of a kind validated as a single entity, which placeholders it still owes — with no Release resolved, no closure walked and no lockfile read; the reply then carries checked: "document". Name a Release and that key is absent, because that answer is the method’s full verdict and has nothing to qualify.
Read the key rather than inferring from the diagnostics, because the two answers can look identical. A well-formed document validated without a Release replies with an empty diagnostic list, which is exactly what a clean full verdict replies with, so checked is the only thing separating “nothing is wrong” from “nothing that needs a Release was looked at”. One consequence follows from the same rule: a lockfile is recognized by its correlation to the Release the request named, so a request naming none recognizes no lockfile and reports nothing on one.
A workspace that holds no Release is answered rather than refused, and that is what keeps the rest of the daemon usable there. Validation is what seeds the parse cache every other file operation reads, so a catalog-only repository, a single-Aggregate scaffold or a scratch directory still gets hover, completion, go-to-definition, references, implementations and cached diagnostics. Refusing instead would take all of them with it, in exactly the workspaces where a client has no Release to name.
What a diagnostic entry carries
Each entry positions itself with line and column, both 1-based in the position encoding negotiated at the handshake, and adds end_line and end_column when it spans a whole token. message is the text a client shows the user, severity classifies it, and source names which of the daemon’s layers raised it, as described above.
The layers answer different questions about one file, so an entry from each can stand on the same line without either being a duplicate of the other: one says the deployment is not correct, another that the entity is not publishable. A client that showed them as one list would report a single problem twice, and reading source is what separates them.
Where an entry sits depends on what it is about, not on which layer raised it. A finding about something the author wrote is positioned on the key they wrote it under, so the editor draws it where the edit belongs. A finding about the shape of the deployed topology names a component and a delivery key rather than a line — those are coordinates in the deployed topology, not in the document — so it is drawn on the document’s kind: key and names its coordinates in the message instead. Both kinds reach the aggrega-build layer, because a build raises both. A refusal a build raised while it rendered reaches that layer too, on the document the refusal itself points at — a Workload that does not satisfy its checks on its Recipe’s workload key, a Recipe’s failing assertion on that assertion’s own key, an entry the composition of the graph refuses on the key the Release or the Aggregate wrote it under, and each finding of a refusal that joins several on its own document and key — and, where it points at no document, on the Aggregate’s kind: key; A refusal raised while rendering describes it. So a client places every entry by its own line and column and never infers a position from the layer.
A finding that names no key the document holds is drawn on the key that names the document. A finding a document’s own checks raise about what it says, the single-entity check’s finding, and an advisory or a refusal a build raises are each drawn on the key they name; where they name none, or a key the document does not hold, they are drawn on the document’s kind: key, or on its metadata.name where it declares no kind:, and at the head of the file only where the document declares neither or does not parse. A document commonly opens with a comment — every catalog file carries a licence header — and an entry drawn on its first line would sit on that comment and read as a fault in it, while the document’s own identity is a line its author wrote. An entry about something other than what the document says is placed at the head of the file: a Dependencies: entry about the Release’s dependencies, a stage that stopped without naming anything in the document, a drifted lockfile, a reference a render had to decline, a Release that did not load — and so is an aggrega-lint entry whose rule computed no line. Where a position is stated rather than drawn, a finding naming no key still has none: the error answer of a refusal that names no key carries the document alone in its data.
Which document an entry is published on follows from the same rule. A validation naming a Release answers that Release’s Aggregate, the Release itself, the document of each module the Aggregate imports, and the Manifest the Release names. A finding positioned in the Release — a refusal of an entry the Release writes on one of a component’s connections, of the sizing it gives that connection, of an attachment it fills or sizes there, of a connection it wires, of a Feature only the Release attaches to a component or to a boundary, or of the infra it gives an attachment — is published when the Release document is validated, on the key in the Release that wrote it, and on the Aggregate not at all. A finding positioned in a module’s own document — a refusal of what one of the module’s components declares, of a socket its attachments wire, of its values or of the values on its own connections — is published when that module’s document is validated, on the key there that wrote it, and on the Aggregate not at all. A finding about the Manifest’s mapping table — an entry mapping a type to a Recipe or FeatureRecipe that does not implement it, an entry whose version pin does not parse, or a mapped type whose extends chain cannot be followed — is published when that Manifest is validated, on the key of the mapping entry it is about, and on the Aggregate not at all; where the Manifest’s open text does not write that entry — an entry it inherits through its own extends, or one an unsaved edit removed — the finding is published at the first line of the Manifest. Every other finding the validation of that Release raises is published on the Aggregate: the dependency-level findings that name no document of your workspace — a withdrawn reference or plugin, a catalog Component or Feature whose extends chain does not resolve or whose schema is invalid, a gate plugin the trust record does not match, a component instance no mapping resolves, a Recipe or FeatureRecipe whose provider cannot render an input kind it declares, and the schema-pillar-overlap and narrowing-on-extend advisories — among them. So a finding about what the operator wrote appears while the Release is open, one about what a module declares while that module is open, and one about a mapping while the Manifest is open, whichever stage of the build raised it; an editor that validates every open document against the Release shows each there. A Release whose dependencies cannot be resolved at all raises none of those findings, and the failure to resolve them is one entry at the head of the Release’s own document and of every other document validated against it that the daemon recognizes, as Live validation describes, and does not check as a single entity — its Aggregate, its Manifest, a library, another Release, the workspace configuration — prefixed Dependencies: and carrying the resolution’s own account of what stopped it. On the Release’s own document the entry is that account and nothing more. On every other document it first says that the document is checked against that Release and names the Release as a request names it — Dependencies: this document is checked against the Release <release>, whose dependencies cannot be resolved: followed by the account — because nothing in that document says which Release it was checked against: an editor that checks every open document against the one Release selected puts the entry on documents that have nothing to do with that Release, and the name is what tells you the selection is the cause. A file the daemon does not recognize carries no such entry, whatever the Release named with it.
An answer carries every layer standing on the file, however far the validation got. The aggrega/validate answer is the file’s whole current state: what this validation found, the aggrega-build entries a build, a preview or a graph request published on the file, and its publishing-conventions findings, each under its own source. A validation that stops at the buffer — one that does not parse, or a document whose envelope the schema refuses — answers the same way: it reports its own finding and leaves every build entry on the file standing, because it learned nothing about the build. So a client can replace what it holds for the file, layer by layer, from any answer.
One fault is reported once. A document’s own validation and a build can find the same fault in it: the single-entity check renders a Recipe a build renders too, the validation composes the graph a build composes, and a Release whose dependencies do not resolve fails both. While a build reports such a fault on a document, that document’s validation does not report it a second time: an aggrega entry naming the same condition — the same code — as a build’s refusal on the same document, placed at the same span or at no key of its own — drawn where an entry naming no key is drawn, or at the head of the file — is left out of every answer and every publication for that document, and the build’s report stands alone. The build’s report is the refusal’s entry on the aggrega-build layer; or, for aggrega/build, aggrega/buildPreview or aggrega/irGraph refused with 1004 because a dependency does not resolve, that answer itself — which nothing publishes — on the document its data.file names, else its data.lockfile, else the Release the request named, the latest such answer for a Release being the one that counts. The validation keeps what it found: once no build reports the fault — the next run publishes the layer without it, the next build, preview or graph answer for that Release is anything else, or a client connects that was answered no such 1004 — the document’s own entry is reported again, and where no build has run nothing is left out. An aggrega entry placed at a key no build refusal sits at stays, even when it names the same condition, because it can be a second fault of that kind the build has not reported.
code is a stable, machine-matchable code for what the entry reports, so a client can branch on it without matching the message text. One key carries the code whoever assigned it, and source tells you which kind you are holding, because the layers name things from different vocabularies.
- On an
aggregaentry — a finding about the authored documents — the code is the string the condition is registered under, written as the declaring package and then the rule in kebab-case. It is the same value a Go consumer reads withCodeOf, whose form and matchable surface are described in the error-sentinels reference. - On an
aggrega-buildentry — an advisory a build raised — the code is whatever the raising site assigned, and this layer carries advisories from two different vocabularies because a build raises advisories about two different kinds of thing. An advisory about the shape of the deployed topology carries a class code, such asunsupported-field, assigned wherever it was raised, whether that is a rendering plugin or the render itself; a class code names a class of advisory rather than a registered condition, so it has no row in the sentinel reference, and the warnings reference describes theunsupported-fieldclass and the flag that silences it. An advisory about the authored documents — a name one edit from a declared one, a parameter nothing reads — carries the string its condition is registered under, in the same form anaggregaentry does and with a row in the sentinel reference. Either way the code names what the finding is and not who found it, so a single class reaches you under one code however many places raise it, and reading the code rather than the layer is what tells you which of the two you are holding. The refusal a build stopped on while rendering is the one entry here that is not an advisory, and it carries the string its condition is registered under in the same way. - On an
aggrega-lintentry — a publishing-conventions finding — the code is the finding’s identity: the identity of the rule that produced it, or, for a finding that names no rule — which a linter of your own may report under a code of its own — that code. It is the identifieraggrega lintprints on the finding’s row, after the short code where there is one, and the valueaggrega lint --output jsoncarries for that same finding, asruleId, or ascodefor a finding that names no rule. One finding keeps one identity across the surfaces, so a client that groups or suppresses a rule in the editor groups and suppresses the same rule in the terminal. Each rule of the publishing-linter rule set Aggrega declares is registered as a condition under that identity, so it is listed in the table of every condition under the short codeaggrega lintprints at the head of the same finding’s row andaggrega lint --output jsoncarries on it asshortCode. A rule from a linter of your own that Aggrega does not declare names no registered condition, and neither does a finding that names no rule, even where its own code spells the identity of a rule Aggrega declares — so neither is listed there. The rules are described in theaggrega lintreference.
Whichever the layer, the key answers one question — what is this, in terms a machine can match — so an editor extension that highlights, groups, or suppresses one class of finding keys on the code, and keeps working when the wording of a message changes.
Note which object carries which: this is a string on a diagnostic entry, distinct from the numeric code on a JSON-RPC error envelope described under Error codes below. A response carries one or the other, never both in one place.
The key is omitted where nothing that produced the entry assigned a code, and every kind has that case. A buffer no YAML parser will read reports the parser’s own text and no code, because no condition of Aggrega’s own stands behind it; a stage that reports a failure without naming a condition likewise has none to report; and an advisory whose raiser assigned no code arrives without one. So treat code as optional, the same way end_line and end_column are, and branch on it only when it is present. A code is what a diagnostic reports and never what selects one: no request takes a code, and writing one back into your own code gives you a string rather than a way to match.
The identifier a program matches, and the one a person quotes
A condition carries two identifiers, and they are for two different readers. code is the one above: qualified and hyphenated, so a program branching on it reads as what it means. shortCode is the letter E and four digits — E0164 — and it is the one a person can read out, type into a search box, or paste into an issue. Both name the same condition and neither is short for the other.
Which one to reach for follows from who is reading. Match on code in your extension; put shortCode in front of the author. An extension that showed only code leaves a reader holding an identifier meant for a program, and one that matched on shortCode is matching on a number that says nothing about the condition. That division is why both travel rather than one.
codeDescription is where the condition is published, carried as { "href": … }, which is the protocol’s own structure for a reference to open for more about a diagnostic. A protocol-aware editor turns it into a “learn more” affordance without being taught anything about Aggrega, and no client needs a copy of the explanations. The address resolves to the published list of every condition, where the entry for a shortCode names the condition and carries on to the walk-through of the authoring fix.
The prose itself is not on the entry, and that is deliberate. A diagnostic is emitted on every edit, so an explanation travelling on each one would republish the same paragraphs on every keystroke to a reader who has usually already read them. A client that wants the text asks for it once, with aggrega/explainError below; a client that can follow a link needs neither.
Both keys are present exactly when the entry names a registered condition, and absent together otherwise. What decides them is what stands behind the entry rather than which layer published it, so read the keys rather than the layer:
- An entry naming a registered condition carries all three.
shortCoderesolves, and the reference resolves to the list it resolves in. - An entry whose code names a class carries
codealone. A render advisory’s class, and the identity of a conventions finding from a linter of your own — a rule Aggrega does not declare, or the code a finding that names no rule carries — are real identifiers you can group and suppress on, and neither is a registered condition — so there is no number to quote and nothing at the address that describes them. A reference sent anyway would be a link that opens a page not about the reader’s problem, which is why none is sent. This is the ordinary shape on theaggrega-buildlayer, though a build advisory that does name a registered condition carries all three like any other. On theaggrega-lintlayer the ordinary shape is the full set: a rule of the publishing-linter rule set Aggrega declares is a registered condition, so its finding carries the sameshortCodethataggrega lintprints at the head of the finding’s row, and the reference beside it. - An entry naming nothing carries no identifier at all.
So the three cases are distinguishable from the keys alone: no code means nothing to name, a code with no shortCode beside it means an identifier that resolves no further, and the full set means an identifier with somewhere to read about it. Treat the two new keys as optional the same way code is, and offer a reader something to open only where codeDescription arrived.
Expanding a code a diagnostic carried
aggrega/explainError turns either of a condition’s identifiers into what the compiler declares about it and the published entries that teach the authoring fix. It is the same expansion aggrega explain performs at a terminal and the explain-error tool performs for an assistant, and all three answer from one place, so a code expanded here and the same code expanded there are one answer rather than three that happen to agree.
code is required and takes either identifier — the shortCode a diagnostic carried, or the code beside it — because a client holding one of them has no way to obtain the other without asking. An empty value is refused naming what to send.
The answer always carries shortCode, code and message: the condition’s two identifiers and the sentence every diagnostic naming it opens with. Those are declared inside the binary, so they arrive with no network and no cache, which is what lets a workspace holding no documentation still be answered. reference is the same address a diagnostic’s codeDescription carries, for a client that would rather send its reader to the documentation than render prose.
entries carries the published walk-through, each entry as the heading that opens it and the body beneath, in the order the documentation itself pairs them with the condition. It is omitted where the walk-through could not be added, and note then says why: the published page documents no entry for this condition yet, or this workspace cannot read the documentation — the machine holds no copy, or only one the workspace’s signature check refuses. Either way the condition above it stands — the answer is not a failure, and a client shows what arrived and the note beside it. entries and note never both arrive.
A code nothing resolves is refused rather than answered with a condition whose every field is empty, and each refusal says which it is: a code no condition is registered under, a number that named a condition once and never names another, or a code this binary does not declare where the published list could not be read at all — the last leaves both repairs open, since a list published for a different version may name a condition this binary does not declare.
The documentation is read from the bundle cached for the workspace the request names, acquired on first use when it is absent, which is the one thing this request reaches a registry for — see Reaching a registry, and writing. Nothing is written to the workspace. No validation triggers it: an expansion happens because a request asked for it, so a registry is never reached while a document is being validated or inspected.
Publishing conventions, on request and on every edit
The daemon answers two different questions about a catalog entity, and they are the questions aggrega validate and aggrega lint answer in the terminal: whether the deployment is correct, and whether the entity is publishable by the catalog’s conventions. A validation always answers the first. It answers the second only when you ask for it.
aggrega/lint asks for it outright. Send entity for one catalog entity, release for every entity that Release’s dependency closure reaches, or neither to check every entity under the configured catalog directories — the three scopes the command has. Sending both entity and release names two different subjects and is refused. The answer carries checked, the number of entity documents the run covered, and files, the findings grouped by the document each concerns and ordered by path, each file’s entries in the diagnostic shape described above. halted says whether the run’s own verdict refuses publication.
Sending neither checks the whole catalog the way aggrega lint does with no argument. A workspace whose configuration gives no Release catalog directories of its own is checked once, over its own directories, and the answer is the one described above. A workspace that names Releases under workspace.releases is checked once for each Release in it, over the directories that Release reads, and never over all of them together — so catalog variants kept side by side, one per Release, are each checked in the terms of the Release that reads them. The answer then also carries passes, one entry per pass: releases, the Releases it was run for, each relative to the workspace root, with Releases that read the same directories sharing one entry; catalogDirs, the directories it read, spelled as files spells a path, and empty for a Release that reads none, which is reported rather than failing the others; and that pass’s own counts and files, which are what say which Release a finding was found for. checked, the counts and files around them cover every pass together, so a client that does not read passes still reads the whole run. A run where no pass has a directory to read is refused rather than answered as a clean catalog.
Set prePublish alongside entity to compare that entity against its previously published version and classify the proposed version bump against it. That is the one mode here that reaches a registry, and it runs because the request named it: what admits an operation that reaches out is that a caller asked for it. It is meaningful with entity alone, so prePublish with no entity is refused.
aggrega/lint publishes nothing into the session. It answers about the subject it was given, and writing its findings into the editor’s problem list would replace what a validation published for files the request never covered. Nothing is written to disk under any mode.
serve.lint_on_validate runs the same rules on every validation, and it is off unless you turn it on. Turn it on in .aggrega-config.yaml, in the workspace whose entities you want the advice about:
serve: lint_on_validate: trueThere is no flag for it, because the question it answers is about a workspace’s own content and the person who has that question is the one authoring the workspace rather than whoever launched the daemon. With it on, a validation of a catalog entity also publishes the conventions findings under the aggrega-lint source; with it off — the default — a validation reports the correctness layers alone and no conventions finding reaches you. An editor session says nothing about whether an entity is publishable until you ask for that layer.
Three things hold on that layer whatever the key says. Only the mode that reads local content runs, so no registry is consulted, nothing is fetched and nothing is written; the pre-publication comparison is reached by sending aggrega/lint with prePublish, never by a validation, because a check running on every edit is exactly where a registry must not be reached. The rules are evaluated against the buffer the request carried rather than the file on disk, so a name you correct stops being reported before you save. And the findings are advisory — a document that draws them still validates, and its Release still resolves and renders — so it adds a layer and never a refusal.
The key gates that layer and nothing else. aggrega/lint answers whatever it is asked under either value, because a caller sending it has asked for the check by name.
Only the kinds that get published to a catalog are checked, because that is what the conventions are about. Documents that are not catalog content — an Aggregate and a Release among them — are passed over, and so is YAML that is not an Aggrega document at all. That is what keeps a session quiet about the documents an author spends most of their time in.
How a reported path is spelled
When an answer names a document the daemon located for you, one rule decides how that path is spelled: relative to the workspace root when the document is inside it, and the absolute path when it is not. That covers the file on an entity identity, the file on an entity definition, and the file each group in a lint answer is keyed by. Both spellings are paths you can open — the first against the root you named, the second as it stands — and neither is ever left empty on account of where the document sits.
The second half of the rule is what a configured catalog directory needs. A workspace may point at catalog directories anywhere on the machine, and a document in one is as real as a document under the root. The absolute path is what names it, and it is the same spelling aggrega lint and a halting diagnostic print for that file at a terminal — so one file has one name whichever surface you asked. What you will not be given is a path climbing above the root, which would name different files depending on where it were read from.
Which spelling you were handed is readable from the value: anything your platform reads as an absolute path is the second form, and anything else is relative to the workspace root. You need not test it in order to open the file — joining a relative one onto the root and opening an absolute one as it stands both work — but a client grouping by workspace document can tell the two apart without asking.
What this rule does not reach. A path you send is governed by that request’s own contract, stated with the request above and usually stricter: a destination is refused unless it is relative to the workspace root and resolves inside it, its links included. The aggrega/publishDiagnostics notification carries its file absolutely in every case, inside the root and out, because that value is the identifier you match against your own open documents rather than a coordinate in the workspace — your editor resolves it as a filesystem path. aggrega/releaseCandidates and aggrega/activeRelease name every Release and lockfile by its absolute path, as their own entries above say. And aggrega/irGraph carries the compiled graph as the compiler recorded it — withholding only the values an author declared sensitive — so any path recorded inside it is the one the compiler recorded, in the form the graph’s own contract fixes, rather than one this protocol composed for you.
Which spellings a parameter you send accepts
What a path names — not which method carries it — decides which spellings that parameter accepts. Each request’s own entry above states the contract for the parameters it takes; what follows is the contrast between them, and why it is a contrast rather than an inconsistency you have to memorise per method.
A parameter naming a document you already hold may be spelled any of three ways: relative to the workspace root, absolute, or as the file:// address a language-server client sends for an open document. That is the file or uri of aggrega/validate, aggrega/diagnostics, aggrega/invalidate, aggrega/hover, aggrega/completion, aggrega/resolve, aggrega/findReferences, aggrega/findImplementations, aggrega/insertionPoint and aggrega/connectionAtPosition. All three name one document and are answered alike, because each is reduced to one canonical spelling at the request boundary before anything reads it — so a document you validated under its path is found under its address, and the other way round, and which spelling you send changes nothing about the answer. An address is read as the path it names, its percent-escapes decoded, when its authority is empty or localhost; one naming another machine is read as that machine’s network share on a system that opens a document there that way, and names nothing the daemon can open anywhere else. An address that also carries a query, a fragment, credentials or a port names nothing the daemon can open either. A value that does not open with file://, whatever its letter case, is never read as an address, and the file-not-validated refusal names the value you sent, whichever spelling it was. Of these, aggrega/insertionPoint and aggrega/connectionAtPosition are the two that read the document from disk where you hold no copy of it, and they answer only for a document inside the workspace: one outside the root — as written, or through a link leading out of it, to the file or to a directory on the way — is refused whichever of the three spellings names it, and a document inside the root is answered in all three. The other eight read nothing from disk at the path they name — aggrega/validate takes the document’s bytes from content, and the rest answer from what was validated — so they answer for a document wherever you hold it, inside the workspace or not, and no link they name is followed to read a file. A parameter naming a document you selected from outside the workspace is the same case for the same reason: aggrega/import’s source is read where it actually is, as its own entry says. Both are exceptions to the workspace boundary by class — a document the client holds open, and a file a person picked — and The workspace boundary says why each is one.
A parameter by which the daemon must locate a document inside the workspace takes a workspace-relative path and nothing else. release is the one to know — on aggrega/irGraph, and under the same contract wherever else it appears — and an absolute value is refused with the invalid-params error, which states the contract and then names the specific fault. The requests that write inside the workspace hold their destinations to that same contract, each as its own entry says. Every such path is then judged by where it leads, by one rule whether the request reads it or writes it — the definition of inside The workspace boundary states — and a path leading out is refused with that request’s own error, quoting the value as you sent it, with nothing read or written: a link to a file outside and a link to a directory on the way alike, and a path not made yet beneath a linked directory leading out, which is refused for the link rather than written to, or looked for outside and reported missing. That covers every path a request names for the daemon to read — release wherever it appears, aggrega/lint’s entity, and the publication requests’ entity, plugin, file and from — so a request cannot read through a link a file the workspace’s own listings leave out, and every destination: the directories a generation, an import and a build write into, the entity aggrega/pin writes its lock beside, the entity file and the module aggrega/pluginSync reads and rewrites, and the document aggrega/editDocument edits. A release naming a Release your workspace configuration names is the one exception, as aggrega/irGraph’s entry says.
The two differ because the faults differ. A parameter naming a document you already hold leaves one question only — which document — so reducing your spelling to the canonical one loses nothing, and accepting each costs you nothing either. A parameter that selects a document out of the workspace is not in that position: in the path libraries a client is likely to be using, joining an absolute value onto a root yields that absolute value rather than an error. So a value quietly repaired would have the daemon read — and report findings against — a path the workspace never held, and you would be told about a file that does not exist. Refusing is the answer rather than repairing, because a daemon that repaired such a value would leave every client sending one believing the contract was optional.
How an entity is addressed
Every entity a response names is addressed the same way: kind, name and file. Join on those three against aggrega/catalogIndex for anything you want to display: it is the surface that carries an entity’s full descriptive set — apiVersion, description and labels — so a response that only needs to name an entity reports the three addressing keys and leaves the describing to one place. A by-name lookup such as aggrega/entityDefinition repeats the few descriptive fields its own answer is about; the index remains the surface to join against when you want the set.
Where a response can name entities from more than one place, each identity carries origin beside those three keys. aggrega/catalogIndex and aggrega/attachCandidates both do, because their entities come from the workspace documents and from the configured catalog directories. A response drawing on one place only reports the three keys and no origin, since a key with one possible value tells you nothing — every entity such a response names is a workspace document, and its file is a workspace-relative path you can open. So read origin where it is present rather than requiring it everywhere; the three keys are what you join on either way.
origin belongs to a response that lists entities, where telling the populations apart is the reader’s problem. A by-name answer such as aggrega/entityDefinition carries none: it names the one entity the name resolved to, so there are no populations to separate. Its own bullet above says when its file is empty; do not read that emptiness through the origin values below, which describe a listing.
origin says where the daemon read the entity from, and it is what makes file readable.
workspace— an Aggrega document under the workspace root.fileis its path relative to that root, which is a path your client can open.catalog— an entity resolved from the configured catalog directories.fileis empty on this listing, and thenameis the whole address. It is empty because the listing reports what the catalog lookup enumerated, which is an identity rather than a document, so the entry carries no path to report — not a path that was withheld for where it sits. Askaggrega/entityDefinitionfor the same name when you want the document: that request resolves the entity and reports itsfileunder the rule above, so a catalog directory outside the workspace root is named by its absolute path there.nameis the coordinate an Aggregate, a Recipe and the catalog lookup all use anyway.
Read the two together rather than testing file alone. An empty file on its own could not tell you whether the entity has no workspace path or whether one was simply not reported; origin answers that directly.
Where a Feature is reachable both ways — the workspace root is itself one of the configured catalog directories, which is a common layout — it is reported once, as the workspace document, because that is the copy whose file you can open.
What an attach-candidate response tells you
aggrega/attachCandidates answers a single question — which Features does this label set admit — and offers three ways to say which label set you mean. Send exactly one coordinate; sending two, or none, is refused rather than ranked.
{node} addresses a workspace document by its metadata.name and needs nothing else. The match is evaluated against the labels that document declares at metadata.labels, and the response reports labelSource: "declared".
{graphNode, release} addresses a node on a compiled graph. graphNode is the id the graph keys the node under — the same id you read from aggrega/irGraph, including the qualified form a node contributed by a sub-aggregate carries. release is a path relative to the workspace root, naming the Release whose graph to build, the same value aggrega/irGraph takes. The match is evaluated against the node’s finalised labels, and the response reports labelSource: "resolved".
{labels} carries the label set itself and addresses nothing. It is the shape underneath the other two: the match is a function of a label set and the Features on offer, so a client that already holds a label set has nothing to name and nothing to wait for. Send a JSON object of label pairs; the response reports labelSource: "supplied" and an empty node, because this request addressed none. An empty object is a coordinate — it asks about a node carrying no labels — while omitting the key entirely, or sending null, addresses nothing and is refused.
The two name coordinates are separate because their identifier spaces overlap. A graph node id and a document’s metadata.name can be the same string while naming different things, so one parameter carrying both would be ambiguous, and a daemon that guessed which space you meant would sometimes answer confidently for the wrong subject. Saying which question you are asking is what removes the ambiguity.
labelSource tells you how far the answer reaches, and the three values are not interchangeable. declared is a match over what one document says about itself, which is what a read over source can see. resolved is a match over the labels the node actually ends up with, which is what a build evaluates applicability against — so a resolved answer is a statement about what a build would decide, and a declared answer is not. supplied says the daemon read no labels at all and matched what you sent; how strong that answer is depends entirely on where your label set came from.
Which is why a client holding a graph should send {labels} rather than a name. A node’s finalised labels are the labels of the component type it resolves to, not of a document that happens to share its id, and a label-transform attachment may then add to, change or remove them — so the labels deciding a node’s applicability need not be the labels any one document declares. A client drawing a graph already has that set from aggrega/irGraph; passing it back reaches the same answer the {graphNode, release} coordinate gives, without rebuilding the graph to get it. Pass back a set the daemon itself reported — a node’s from aggrega/irGraph, an entity’s from aggrega/catalogIndex — and your idea of a node’s labels cannot drift from the daemon’s, because the set never left its own answer. Assemble one yourself and you are asking a hypothetical, which is answered honestly and is not a statement about any node the workspace holds.
Candidates come from the workspace and from the catalog. A workspace that keeps its Features in a catalog rather than in its own tree has no local Feature at all, and its candidates are entirely origin: "catalog". For a graph node, both are read in that node’s Release’s terms: the catalog Features are the ones the catalog directories the workspace configuration gives that Release declare, and the workspace’s own documents are offered less any under a catalog directory only other Releases read. A workspace keeping a variant of a Feature per Release therefore offers each Release’s graph its own variant and never another’s, while a Feature written beside the catalogs, under no catalog directory at all, is offered for every Release. {node} and {labels} name no Release, so they draw on every workspace document and on the workspace’s own catalog_dirs. A Feature that declares no applicability at all is a candidate for every node — an absent declaration states no requirement — while one whose declaration cannot be read is a candidate for none, because treating an unreadable selector as satisfied would let a typo widen what you offer.
A name that does not resolve is an error, not an empty list. Those two answers mean different things: an empty candidates array says this node has nothing that may attach to it, and reporting a mistyped name that way would present a typo as a settled answer. The refusal names the space it searched, so you know whether to look for a workspace document or a graph node. {labels} has no such hazard — there is no name to have typed wrongly — so a label set nothing admits comes back as a successful response carrying an empty array, and a request the daemon cannot read is still refused before any matching runs.
The graph-node coordinate needs a lockfile; the other two do not. Building a graph means resolving what the Release reaches, so that path refuses with the lockfile-absent error when none has been generated, naming the command to run — the same precondition aggrega/irGraph carries, for the same reason. Addressing a workspace document builds no graph, and supplying a label set builds nothing at all, so both answer on a workspace nobody has prepared yet.
It reports and never creates. The method mutates nothing, writes nothing, and creates no attachment. Composing and applying any edit is the editor’s, which is where the buffer and the undo history are.
What it resolves depends on the coordinate, and the three are not the same. {node} resolves nothing and reaches no registry or network — the candidates come from the workspace and from the catalog directories, both already on disk. {labels} resolves less still: it looks nothing up, because there is nothing to look up. {graphNode, release} builds the Release’s graph, so it resolves that Release’s dependency closure the same way aggrega/irGraph does: from the local catalog directories and the artifact cache first, and from the configured registry for an entity neither of those carries. All three answer offline for a workspace whose entities are all local; only the graph-node coordinate can go looking further.
Asking about a connection
A connection a component draws can carry attachments of its own, filling the slots its socket declares on the consuming Component — a credential the component presents to whatever the connection reaches, say. Send connection beside {graphNode, release} to ask what may go there: socket is the dependency socket the connection is wired through and alias the name it carries within that socket, both exactly as the author wrote them. A connection exists only on a compiled graph, so connection beside node or labels is refused, as is a connection naming no socket or no alias, or one the node does not draw.
The answer is the graph-node answer plus the connection’s slots. candidates keeps its meaning — the Features that may attach to the node itself — and slots is added, one entry per slot the socket declares, in the order the Component declares them:
slot— the name an attachment filling it is written under in the connection’sfeatures.selector,required,inject,sensitiveanddescription— the slot exactly as the Component declares it on the socket, empty or false where it declares nothing.selectoris the constraint the candidates were narrowed by, so you can explain a candidate, or its absence, from the answer alone.candidates— the Features that may fill this slot on this connection. A build holds such an attachment to two rules, and both are applied: the Feature’s declared applicability against the node’s finalised labels, which every attachment the node carries is held to, and the slot’sselectoragainst the Feature’s own labels. So a slot’s candidates are always among the node’s, narrowed by the selector. A Feature whose labels the selector cannot be evaluated against is not offered, because a build refuses rather than admits it.
Where no slot may be filled, slots is an empty list and noSlotReason says why. Read the reason rather than taking an empty list for “no Feature matched” — that would be a different answer, and the reason is what tells them apart:
feature-created-connection— a Feature drew the connection, from its own dependency block. An attachment is written only on a connection a component or the Release draws, so nothing goes here whatever the socket declares.ad-hoc-socket— the socket is one the Component does not declare. The author named it, which is legal, and an undeclared socket declares no slot.no-slot-declared— the Component declares the socket with no slot on it.
noSlotReason is absent wherever a slot exists, and slots and noSlotReason are both absent from an answer to a request that named no connection — so a request that names no connection is answered with neither field.
document is accepted and changes nothing here. The slots are the socket’s and the candidates the Features’, the same whichever document an attachment is written in; where it goes is aggrega/attachmentContainer’s answer. A value other than aggregate or release is still refused, because a value accepted and ignored reads to its sender as one that was honoured.
What a connection-candidate response tells you
aggrega/connectionCandidates answers two questions at once, and only one of them has a complete answer. Reading the response as a single filtered list gets the other one wrong.
Each reported socket carries targets — the workspace-local Components whose declared labels satisfy the label constraint that socket declares over what may satisfy it — plus the selector those targets were computed from, the required flag the socket declares, and declaration. targets is always an array, empty rather than absent, so a socket nothing satisfies is still reported as a socket the entity declares.
The target half is complete. The set is decided by evaluating the socket’s declared constraint against a candidate’s declared labels, the same evaluation a build performs, so what you offer is what the same constraint admits during a build. A socket declaring no constraint leaves its targets unconstrained and reports every Component — that is the constraint language’s meaning for an empty selector, not an error.
The socket half is open, and declaration plus adHocSocketsAccepted are how you tell. An Aggregate’s author owns its topology and may wire a socket the component’s catalog entity never declared, so the sockets an entity declares are a helpful starting set and not the set of legal socket names. Present them as suggestions, not as the only choices — a picker that only offered declared sockets would tell the author their freedom is narrower than it is.
declarationisdeclaredwhen the addressed entity lists the socket in itsusesSchema, andad-hocwhen it does not. These are the same two values an edge carries in the IR graph, so one vocabulary answers “where did this socket come from” wherever you meet the question.adHocSocketsAcceptedreports whether the addressed entity’s surface accepts a socket its own declaration does not list. It is not always true: a Component’s own dependency surface accepts one, and a Feature’s attachment surface does not, because an attachment participates in the topology the attached Feature declares rather than authoring its own. An ad-hoc socket on a surface that does not accept one is reported with no targets, because no connection through it would build.
Naming a socket in the request scopes the answer to that one socket, and it is the only way to ask about a socket the entity does not declare — an undeclared socket appears in no declaration to enumerate. Omit it to get every socket the entity declares, in the order they are authored.
What it reports is a match over declared labels. A build evaluates a socket’s constraint against the finalised labels of the node at the far end of the edge, and those are the labels of the component type that node resolves to, after any label-transform attachment has had its say — not necessarily the labels of the document you named. So a positive answer here is not a promise about what a build will decide — the same bound aggrega/attachCandidates carries under its declared label source.
It reports and never creates. The method resolves nothing, reaches no registry or network, and writes nothing: it creates no edge and proposes no text. Composing and applying the edit is the editor’s, which is where the buffer and the undo history are.
For the entity identities in targets — kind, name and file — join against aggrega/catalogIndex as described in How an entity is addressed. The describing fields are reported there and deliberately not repeated here, so this response carries no second copy of them to fall out of step. Targets are workspace Components, so every one has a file you can open and none carries an origin: this response draws on a single place, and the join is on the three keys.
What an attachment-container response tells you
aggrega/attachmentContainer sits between the candidate requests above and the insertion point below. Those say what may attach to a node; this says which container an attachment for it belongs in, and in which document; the next says where in that document’s bytes the text goes.
Ask for the container rather than composing it. A node’s id and the subsystem path enclosing it are both written with dots between their parts, and a dot is a legal character in a name an author types — so from outside the document there is no way to tell a structural dot from one inside a name. A client that assembled the path itself would produce something that reads correctly and addresses a key nobody wrote, and the edit that followed would create that key rather than being refused. The compiler composed both paths, so the compiler is what takes them apart.
A node id carries no trace of its enclosing subsystem at all. A component authored inside subsystems.billing.subsystems.payments is keyed on the graph as ledger, exactly as a top-level component would be, so there is nothing in the id for a client to work from however carefully it splits.
The answer is three fields.
noderepeats the node the answer is about, so a client with several requests outstanding pairs each answer with its question without keeping an order of its own.fileis the document the node was authored in, workspace-relative. It is part of the answer rather than something you already know: a node an imported module contributed was authored in that module’s own document under the name the module gave it, so both the file and the last segment of the container differ from anything the request named.containeris the structural path from that document’s root, as a list of segments —["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]. Each level of an enclosing subsystem sits under thesubsystemskey again, which is how the document spells it. A component the author wrote at the top level names["spec", "components", "checkout", "features"]instead, because the scope such a component is compiled into is not one any file contains.
It is a list of segments and never a joined string, and that is the point of the shape. A joined path would have to be split again by whoever received it, which is the ambiguity above reintroduced one call later. Pass the list to aggrega/insertionPoint as its container unchanged.
It reads structure and never meaning. The answer is derived from the document the node was authored in, the scope it sits in, and the name the author typed. Nothing is read out of what a component is called, what type it carries or what any label says.
It reports and never writes. The method mutates nothing and writes nothing to any document. It creates no attachment, composes no text and applies no edit; it does not rule on what may attach, which is aggrega/attachCandidates.
A request naming a node the graph does not carry is refused rather than answered. Node ids are the graph’s own keys — read them from the graph aggrega/irGraph returns — and a node an imported module contributed carries a qualified id. A node the graph records no document for is refused too: where an attachment belongs is a fact about a document, so a node with no document has no answer rather than an empty one.
It requires a lockfile, for the same reason aggrega/irGraph does: naming the container means building the Release’s graph, and a graph built from bytes nothing vouches for would be reported exactly like one that was checked.
An attachment on a connection
Send connection beside {graphNode, release} — its socket, its alias and its document — and the answer names the features container on that connection’s own entry instead of the node’s. document is required here, because either document may hold an attachment on a connection the Aggregate drew: the developer writes one on the connection’s entry in the Aggregate, the operator on the Release’s per-edge entry for it.
aggregatenames the connection’s entry in the document the node was authored in —["spec", "components", "gateway", "uses", "models", "gpt", "features"]for a top-level component, with each enclosing subsystem spelled level by level as above. A connection the Release drew has no entry in the Aggregate, so it is refused there.releasenames the per-edge entry under the Release’s own entry for the node —["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"]— whether or not the Release writes that per-edge entry yet. Where it does not,aggrega/insertionPointreports the keys still to write inmissingContainerKeys.fileis then the Release document. A Release that writes no entry for the node at all is refused: where the node is placed is the operator’s to write, and the answer does not decide it.
A connection a Feature drew is refused in either document, for the reason feature-created-connection gives above. The node, the socket and the alias are matched exactly as written, and a connection the node does not draw is refused rather than answered with a path. Every other property above holds unchanged: the answer is a list of segments, it reads structure and never meaning, and it writes nothing.
What a connection-at-position response tells you
aggrega/connectionAtPosition is the step before the two connection requests above, for a client holding a place in a document rather than a node on a graph — a cursor on a connection’s entry, say. It answers which connection is written there, in the coordinates those requests take, and stops.
The answer is one of two halves, never both.
graphNodeandconnection— the node whose component draws the connection, by the id the compiled graph keys it under, and the connection by itssocketandalias, withdocumentnaming the document the position was read in:aggregatefor the Aggregate or a module it imports,releasefor the Release. PassgraphNode, the samereleaseandconnectiontoaggrega/attachCandidatesfor the slots the connection’s socket declares, and toaggrega/attachmentContainerfor where an attachment on it goes; the container it names sits inside the very entry the position fell in.noConnectionReason— why no connection is reported. The set is closed:no-connection-entry— the position is on no entry an attachment is written in. A connection written as a list of targets (db: [store]) and one a Feature’s own dependency block draws carry no such entry, so a position on either answers this too.feature-created-connection— the position is on the Release’s entry for a connection a Feature drew, which carries no attachment for the reason the slot answer gives above. A Release writes such an entry where a Feature’s dependency block draws through a socket the consuming Component declares too; the entry builds whether it configures nothing or sets the connection’s per-edgeinfra.unknown-connection— the position is on an entry the Release writes for a connection the compiled graph does not carry. A Release that builds can hold one — for instance an entry under an alias nothing draws that configures nothing (notarget, noinfra, nofeatures), or an entry for a component anactive:toggle switched off, whose connections leave the build with it.
Which entries count. In the Aggregate, every connection a component draws, at its entry under the connection’s alias in the document the component was authored in — for a component an imported module contributes, that module’s own document. In the Release, every per-edge entry it writes, whether the entry draws its connection or configures one the Aggregate drew. Where each entry sits is what the compiled graph records, so whether a key is a connection is never worked out from what it is called. A component an active: toggle switched off is not in the compiled graph, so its own entries in the Aggregate answer no-connection-entry, while the Release’s entry for one of its connections answers unknown-connection.
A position anywhere inside an entry is inside it. The entry runs from its alias key through the last line indented under it, so a position on the alias, on its target, or inside its features is answered for that connection, and the innermost entry wins where entries nest. A position on a socket’s own key, above the aliases written under it, is inside none of them — whether the socket holds one alias or several — and so is a position in the indentation before an alias key.
Which document is which follows from the Release. The Release’s own file is read for the entries it writes; any other file is read for the entries the graph records components as authored in. A document the Release’s graph reads nothing from answers no-connection-entry at every position.
It reports and never writes, and it reads the document the way aggrega/insertionPoint does: from the session’s copy first and the disk otherwise, inside the workspace, with the same refusals for a document that is outside it, unreadable, or not well-formed YAML. It requires a lockfile, for the reason aggrega/attachmentContainer does, and builds the graph with nothing rendered.
What an insertion-point response tells you
aggrega/insertionPoint is the counterpart to the two candidate requests above. Those say what may attach or connect; this says where the text for it belongs in one particular document. It answers and stops there.
You name the container; the daemon locates it. container is a structural path from the document root — ["spec", "components", "web", "features"] — and it is your statement of where an entry of this kind belongs in a document of this kind. The daemon does not derive that path from what an entity is called, what type it carries, or what it appears to mean. It reads the bytes the author wrote and reports which segments of the path this document already has, the columns its entries sit at, and the last line its innermost block reaches. So knowing which key stays with the caller, and knowing where that key’s entries go in this file comes from here.
For a Feature attachment on a node of a compiled graph, the caller does not have to know that key by itself: ask aggrega/attachmentContainer for the document and the container, and pass both here unchanged.
The answer is a zero-width position plus what you have to write around it. file is the document, workspace-relative. container repeats the path you asked about, so a client with several requests outstanding pairs each answer with its question without keeping an order of its own. position inserts rather than replaces: nothing already in the document is overwritten or shifted.
precededByLineBreak— begin the text you write with a line break. The position sits at the end of the line the new entry follows, which is in range whether or not the file ends in a newline and disturbs no byte already written. It is false only for a document carrying nothing to sit after, where you write from the start of the file.missingContainerKeys— the segments of the container path this document does not carry yet, outermost first. Each has to be written as a key of its own before the entry can go inside the innermost one. It is empty where the whole path is already there.entryIndent— the column the entry’s own first line starts at, counted in spaces from the start of the line.indentStep— how much further each nesting level is indented.indentStepMeasured— whether that 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.entryShape—mappingorsequence, read off what the container already holds, andunknownwhere the container is not there yet or holds nothing.unknownis not a failure: the document has not said what shape its entries take, so that choice is yours.
Applying it. Write a line break where precededByLineBreak is set. Then one line per missingContainerKeys entry, outermost first, each being the key followed by a colon — the first indented at entryIndent minus indentStep times the number of missing keys, and each next one indentStep further. Then the entry itself, indented at entryIndent. Where missingContainerKeys is empty the entry is the only line you write.
Read missingContainerKeys even when you expect the container to be there. A position applied without the keys that have to precede it produces a document that no longer parses, which is the one failure this answer must not read as absent.
position counts from zero, unlike a diagnostic’s. Both line and character are 0-based, matching the LSP-shaped position values this protocol reuses, while the line and column on a diagnostic entry are 1-based as described under What a diagnostic entry carries. A client feeding one surface from the other converts between them.
positionEncoding names the units character is measured in, and it is the encoding negotiated at the handshake. It is reported on the answer rather than left implicit because a position whose units the caller has to guess is a position it cannot apply: offsets measured one way and applied into a buffer measured another corrupt the document at the first character outside ASCII.
A request that does not address a place an entry can go is refused rather than answered. Each of these is a state of the request rather than of the workspace, so it comes back with the standard invalid-params code and a retry changes nothing until file or container changes.
- The document was not named, is not inside the workspace, could not be read, or is not well-formed YAML — a document with no structure has no position to report.
- The container path names nothing: it carries no segments, or one of its segments is empty.
- The path runs through a value the document carries as a scalar. Nothing can be appended inside a scalar, and replacing it would be a rewrite rather than an insertion.
- The path reaches a collection the author wrote in flow style. Appending an entry to one rewrites bytes the author already wrote rather than adding a line, which is an edit and not a position.
- The path addresses a block sequence with something that is not one of its indices. A sequence’s entries are addressed by position, so a name reaches nothing in one and no entry can be created to carry that name.
It reads the buffer the editor is holding, not only the file on disk. The daemon’s parse cache is consulted first, so a position is reported against unsaved content where there is some, and against the file itself where the cache carries nothing for it.
It reports and never writes. The method mutates nothing, resolves nothing, reaches no registry or network, and writes nothing to any document. It does not compose the text of an entry and it does not apply one. Composing and applying the edit is the editor’s, which is where the buffer and the undo history are.
What a document-edit response tells you
aggrega/editDocument is the other half of the pair above: those say where an entry belongs and leave you to compose and apply it; this composes and applies one, and it writes. Both stay available, because a client holding an unsaved buffer and a client editing what is on disk want different halves — an editor with its own undo history places the text itself, while a client that would rather the file be edited than be told where to edit it sends this.
One call applies one edit, and the set of edits is closed. edit names which one: add-component adds a component instance under a components container, attach-feature attaches a Feature to a node, wire-edge wires a connection inside one of a node’s dependency sockets, and set-value sets one value on a node. There is no edit that deletes, replaces a block you already wrote, reorders anything, or writes bytes you supply verbatim — so this is not a file writer wearing a narrower name, and a value outside the four is refused rather than interpreted. The refusal lists what you may name.
You name the node as a structural path, exactly as the two requests above take one. node is the breadcrumb from the document root — ["spec", "components", "web"] — and the container the entry goes in follows from edit. For add-component the path names the components container itself, because the entry being added is the node. name is the key the entry is written under: the instance name, the attachment’s name, the connection’s alias, or the value’s key. value is what that entry carries, and what it means follows from edit — the entity the entry requests, the node a connection points at, or the scalar a value is set to. socket is read for wire-edge and ignored otherwise.
A path rather than a name, for the reason the locating request takes one: a name would have to be searched for, and a name appearing at two levels would leave the compiler deciding which one you meant. So a client that knows which node it is editing says so, and a client that does not knows it has a question to answer before editing anything.
Every byte the edit does not touch survives. The document is parsed only to locate the container and the line its block ends at; the entry is rendered and spliced at the line level. Comments, blank lines, quoting style, folded and literal scalars, template expressions and the trailing-newline shape all carry through unchanged, and the nesting step is measured from the document’s own indentation rather than imposed — so an entry lands in the style you are already writing in. The same request against the same document produces the same bytes, so a client may compare two runs and a review reads one edit as one diff.
The result must be a document you could have typed, and that is what the write is gated on. The composed document is validated against its own kind’s schema and reaches disk only if that passes. A request that would produce something the authoring schema refuses comes back as E0275 — the edit was refused because the resulting document would not be valid, and nothing was written — carrying the property the schema would not admit and where. The file is left byte-for-byte as it was, so a refused edit is indistinguishable from one never attempted and you can retry a corrected request against the document you started with. That is also why no rule is restated here: asking a Release document to carry a developer value is refused by the same schema that would refuse the hand-typed document.
What is semantically admissible is not decided here. Whether a dependency socket is one the producer declares, or whether a Feature’s applicability is satisfied, belongs to the resolution a build performs, each with its own reporting. So you may name a connection this request has never heard of, and an Aggregate may author a socket its catalog entity does not pre-declare; what may be consumed across a socket stays the producer’s to declare. Run aggrega/validate naming a Release, or ask for the graph, when that is the question.
The answer names what landed and what reached disk, and they are different questions. content carries the document the edit produced under both deliveries. written names the file that reached disk, and is empty under dryRun. container is the structural path of the container the entry landed in, so you can locate what you just added without re-deriving that rule. createdContainers names the segments this edit wrote because the document did not carry them, outermost first — empty in the ordinary case where the whole path was already there, and reading it is how you tell an entry added inside an existing block from one that brought its own block into being. file and edit echo what you sent, so a client with several requests outstanding pairs each answer with its question. written, container and createdContainers are always arrays, empty rather than absent.
Under dryRun nothing is created. written is empty, content carries the document a write would have produced, and the file is untouched — so an editor can put the result in front of the author to save, amend or discard. The default is the write, because the operation’s product is an edited document and a surface that produces one owes it: a request that says nothing about delivery edits the file.
Everything else a write does, a dry run does. The composed document is validated against its own kind’s schema either way, so an edit a write would refuse is refused under dryRun too, naming the same property — which means the error you get from a dry run is the error the write would have given you.
An entry that is already there, carrying what you asked for, is a no-op — the document comes back unchanged and nothing is written. An entry of that name carrying something else is refused rather than replaced, because replacing what an author wrote is not one of the four edits.
After a write the daemon re-reads the document. What it was holding for that file is dropped and its workspace-level view is reset, so the next validation, hover, completion or graph request is answered from the bytes the edit produced rather than from the version it replaced. The edit itself reads the file on disk and not the buffer you are holding — unlike the locating request above, which consults unsaved content first. That is deliberate: writing from an unsaved buffer would put content the author had not saved onto the page under the guise of applying one entry. Save the buffer, then edit.
A request that does not address a place an entry can go is refused rather than answered, with the standard invalid-params code, and a retry changes nothing until the request changes. The document was not named, is not inside the workspace, could not be read, is not well-formed YAML, or declares no kind whose schema the result could be checked against; edit was not named or is not one of the four; node names nothing, or one of its segments is empty; no name was given; wire-edge named no socket; set-value was given a mapping or a sequence where a scalar belongs; the node path reaches a scalar or a sequence, or a collection written in flow style, where adding a line would rewrite bytes already on the page; or the node path reaches nothing in the document.
It resolves no dependency, reaches no registry and touches no network under either delivery.
What the effective-configuration response covers
aggrega/effectiveConfiguration answers two questions: what configuration applies in this session, and which layer decided each setting. It is the same answer aggrega config show --origin prints, computed once and reported on both surfaces, so the two cannot disagree about where a setting came from.
A source is one of four shapes. A config file’s absolute path — the global file a daemon started as aggrega --config <file> serve reads included, named as the path it was given; an environment variable behind an env: prefix, such as env:AGGREGA_SIGNING_REQUIRED; a global flag typed on the command line that started the daemon, named as the flag, such as --offline for a daemon started as aggrega --offline serve; or (built-in defaults) for a setting no layer sets. The first three appear verbatim in layers. The defaults do not, because the defaults are not a layer that contributed — they are what applies where no layer spoke.
A setting is attributed to the highest-precedence layer that sets it, whatever value that layer writes. A config file writing the built-in default, or restating a value a file beneath it already sets, is the file named: it is the one holding the value in place. A file sets a setting by carrying its key, a list’s _append companion included, and an environment variable by being exported with a non-empty value. The configuration file your pipeline owns is never named for a key it ignores. aggrega config show --origin reports under the same rule.
Every setting the configuration schema declares is accounted for, though not with a row of its own for each. A list’s additive _append companion is reported on the row of the list it adds to, so a layer that contributes only through the companion is named on that list’s row and the companion carries no row. A setting inside a list’s entries — a registry’s trust policy, a plugin attachment’s inputs — is covered by that list’s row.
Two further bounds, each of which makes an answer coarser than it looks.
- A list or map setting is attributed as a whole, to the highest-precedence layer that sets it. Per-entry attribution is not tracked, so a list assembled from two layers reports only the higher-precedence one, and an entry contributed by a lower layer is not distinguishable from one the higher layer wrote.
- The signing requirement is attributed to the first layer that turned it on, not the last that mentioned it. That setting composes so that any layer switching it on wins and no later layer can switch it off, so the first layer to turn it on is the one that made the effective value what it is. A layer writing
required: falseturns nothing on, so where every layer that mentions it writesfalsethe setting reports(built-in defaults).
Every reported value is the resolution taken when that workspace was first named. Editing a config file does not change a value here; restarting the daemon does. That is deliberate — the values are the configuration every other request about that workspace is answered under, which is what makes them comparable with the root and configuration layer the handshake reported for it. A client showing configuration alongside a file the user is editing should say which of the two it is showing.
The layer attribution is worked out when you ask, against the files as they stand. So a config file edited afterwards can move a source while the value beside it stays as it was resolved. The two halves answer different questions — what is in force, and which layer decided it — and only the first is fixed. Restart the daemon to bring them back into step.
It reports and never writes. The method changes no configuration, creates no file, and resolves nothing from a registry or the network.
Single-layer file contents are not served here. The command line can print one layer’s own bytes verbatim, comments and formatting preserved; this method reports the resolution rather than the bytes. A client wanting a layer’s text has the path in layers and can open it.
What a configuration write leaves behind
aggrega/configInit and aggrega/configCapture both produce a configuration document, and both write it. The answer names the file; opening it is your next act, not a substitute for the write. Neither hands you content to place yourself unless you ask for that outright, because a capability whose product is a document that was never written is a different capability wearing the same name.
The two differ in how far they reach, and each answer says which. Read it before you show the result.
- Seeding writes the configuration shared across every workspace on the machine, by default. A registry and the identities you trust on it are usually the same wherever you work, so that is where the entry goes unless the request sends
workspace: true.scopecarries theconfigFilethat was written andmachineWidesaying whether it is the shared one — derived from the file the write resolved to rather than from what the request asked for, so an answer cannot describe a machine-wide change as a local one. - Freezing never reaches past the workspace. It takes no write target and no override: its whole purpose is to make one project self-contained, so it always writes that project’s own
.aggrega-config.yaml. That is why its answer carriesconfigFileandworkspaceRootand claims no scope — there is no reach to state.
Seeding refuses rather than overwrite. A configuration file that already exists is left untouched and the refusal names it, because seeding is for a configuration that does not exist yet while the shared write it delegates to merges by design. Send force to write anyway; the registry entry is merged into what is already there and the other settings are preserved. A refused request changes nothing at all.
trust says what the registry’s advertised policy did, as separate outcomes rather than as prose. pinned means the registry advertised a policy and it was taken, with identities counting them. notAdvertised means the registry was asked and advertised none, which is not a failure — the seeding proceeds, and reason says what the endpoint did. A registry that could not be reached is reported that way too, since no policy came back and the seeding proceeds alike, and carries unreachable beside it where the failure itself shows the registry was never 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. A registry that answered — with a not-found, or with an error status — never carries unreachable, so read that key rather than the words of reason to tell a registry that publishes no policy from one that was never asked. baseline means the official hub’s built-in baseline was pinned because no advertised policy was taken, with reason saying why; the entry carries a policy, so there is nothing to pin by hand. The two keys answer different questions, so a hub that was asked and advertised nothing carries both, and a hub in an offline workspace — never asked — carries baseline alone, with reason saying the workspace is offline. Any other registry that advertises nothing carries notAdvertised alone, is seeded with no policy, and the advice that follows is to pin identities by hand; offline it is refused rather than answered. skipped means no fetch was attempted. A client that treated anything but pinned as an error would report a working configuration as broken.
Under dryRun nothing is created. written is false, content carries the document a write would have produced, and the file that content is for is scope.configFile. No directory is made and no file is touched, so an editor can put the text in front of the author and let them save, amend or discard it.
A dry run differs from a write in exactly one respect — it does not write — so every refusal a write performs it performs too. The existing-file refusal is the one that matters here: dryRun over a configuration file that already exists is refused, naming the file, exactly as a write is. That is what makes the response usable as a predicate — if the dry run refuses, the write would have refused, for the same reason and with the same message. Send force alongside dryRun to be answered instead with the merge an overwriting write would produce, still writing nothing. The registry is contacted for its advertised trust policy under either delivery, because the policy in that content is the policy a write would have pinned.
What a freeze reports is what it wrote, not a description of it. sockets lists each plugin socket that was frozen with the attachments frozen there; catalogDirs carries the catalog directories. Both are always arrays, empty rather than absent.
socketandfieldare not the same string, and the difference is not cosmetic.socketnames the socket the attachments are bound at;fieldis the key they were written under in the file. They differ for the provider socket alone, which is written under a plural key — so usefieldwhen you point a reader at a line in the document andsocketwhen you name the socket itself.- Each attachment carries
uri,capability,functionandrole, present only where the attachment has one. They name the attachment rather than reproducing all of it: an attachment’s optional attachment-time inputs are frozen into the file verbatim and are not repeated in the answer. The file is the authoritative copy. captured: falseis a success. A project whose configuration a build does not participate in has nothing build-critical to freeze, so the file is left as it stands and both lists come back empty. Treating that as an error reports a healthy workspace as broken.
The default freezes only what determines the output bytes — the provider bindings, and the governance attachments that transform labels. The verdict governance and linter gates and the import socket are left out, because they are meant to vary between environments and freezing them would carry one environment’s gates into every checkout. allPlugins: true widens the set to every plugin socket. Membership is per attachment, not per socket, so a governance socket carrying one label-transform attachment and one verdict attachment contributes only the first under the default.
Every value is frozen at its effective value — what resolves with the machine’s configuration and the project’s own merged together — so a binding that today comes only from the machine’s configuration is written into the project and travels with it. Machine-wide tooling settings, a registry’s trust policy among them, are not build-critical and stay where they are. Freezing twice over an unchanged configuration rewrites the same bytes, so a client may offer it freely: a second call leaves the document a reader is holding exactly as it was.
What a plugin change tells you
The four plugin requests all write by default, and they divide by what they write: two change a configuration file, and two produce documents in the workspace. Two of them — the addition and the generation — take dryRun, which does everything else the request does and writes nothing. Read the answer’s own account of where the change landed rather than inferring it from the request — for one of them, the request saying nothing about scope means the widest reach.
An addition and a removal both carry scope, and it is derived from the file the write resolved to. configFile is that file, machineWide says whether it is the one every workspace on this machine resolves through, and workspaceRoot names the workspace this session was opened over, so a workspace-scoped answer says which workspace it was. machineWide is read off the resolved file rather than off what the request asked for, which is what stops an answer describing a machine-wide change as a local one.
🔴 A cli-type addition naming neither global nor workspace registers the command machine-wide. A command extension is machine-wide tooling, so with no override it is written into the global configuration file every workspace on this machine resolves through — and the command it registers is then a top-level aggrega command for every project on that machine, including projects nobody in this session has named. A provider, governance, linter or importer addition is the other way round: those shape one project’s build, so with no override they go to that project’s own .aggrega-config.yaml. A removal follows the same rule for the same types. Send workspace: true to keep a command extension local, or global: true to push any of the others out to the shared file; sending both is refused. The scope on the answer is the authoritative statement either way, and a client should show it before acting on the result.
An addition names what landed, and exactly one of three fields says what kind of thing it was. type echoes the type the entry was added for, and then: identity carries the bare version-pinned entity identity for a governance, linter or importer attachment; uri carries the plugin’s oci:// artifact address, alongside the capability it now serves, for a provider binding; and reference carries the pinned reference whose commands were registered for a cli install. So a caller reads which kind of attachment landed off the answer rather than re-deriving it from the type it sent. A removal echoes type and query beside its scope and nothing else — there is nothing further to report about an entry that is gone.
An addition also carries written and, under dryRun, content. written is what a client branches on: true names a configuration file now on disk that the client can open, and under dryRun it is false and content carries the configuration document the write would have produced instead. The two are never both meaningful, and the file content is for is scope.configFile, so nothing in the answer carries a second copy of that path — which matters here, because a global attachment’s file is the one every workspace on this machine resolves through.
A plugin with no published version is refused rather than attached unpinned. An addition resolves the query to one plugin and pins its highest published version, so the entry it writes carries a version. A plugin whose repository publishes no conforming version is refused naming it, and a version a retraction this workspace trusts has withdrawn is passed over in favour of the next one down.
A version the query names is pinned even when it has been withdrawn, and withdrawn says so. A query written as <name>:<version> pins that version rather than the latest — on every type but provider, which is bound by name alone and refuses a version — and naming a version is the override: where a retraction this workspace trusts has withdrawn it, it is pinned all the same, and the answer carries withdrawn: true — the fact aggrega plugin add states as a retraction: line on the terminal. withdrawn is absent on every other answer, so its presence is the whole signal — and its absence is not a statement that the version is not withdrawn. Where the withdrawal markers of a named version could not be read, withdrawn is absent and retraction carries unscreened, saying why, as it does for an addition naming no version that meets the same failure; an addition naming no version reports what the withdrawal check concluded about the version it chose in retraction instead.
An alignment reports whether it changed anything, and that is the field to act on. changed separates a write from an alignment that found the records already correct: an unchanged file was left byte-identical, so a client holding that document has nothing to reload, and running the request twice reports no change the second time. entity names the file, hostFunctions carries the derived set, and commands carries the mirror as values rather than as the line a terminal prints — each entry a name, an optional description, and flags, each flag carrying its name and its optional shorthand, description, type and default. The write is atomic, so a client reading that file while the alignment runs never observes a partial document.
A generation fills exactly one half of its answer, and the answer’s own dryRun says which. Under the default the entities are written and notices carries what the generation said about the writes it performed. Under dryRun nothing is created or modified: documents carries each generated entity as the path it is for and its content, so a client can put them in its own document model, where they are visible before they are saved and can be amended or discarded. The two halves are never both filled, so which delivery ran is readable from the response rather than from what was asked for.
Where a plugin request WRITES is always inside the workspace that request named; what it READS is decided per field. An absolute destination, one climbing out of the root, and one leading out of it through a link are refused rather than resolved — so a generation cannot create entities in a tree your session was never opened over, whatever it sends. A path a request only reads is a separate question, answered field by field rather than by one rule over all of them: aggrega/pluginGenCatalog reads a module and its overlay from wherever you selected them, because a module you built sits under your toolchain’s output directory and refusing to read it there would refuse the operation its whole purpose. aggrega/pluginSync reads its two paths inside the workspace, because that request is about a file the workspace already carries. The locating requests above accept an absolute path for a different reason again — a document the client already holds open, named by whatever spelling it holds.
A request missing something the operation needs is refused naming the field to send. An addition or a removal without type or query; a provider addition without capability, or a governance one without role; a cli addition without acceptCapabilities; an alignment without entity or plugin; a generation naming both selection modes or neither, or missing overlay or outputDir. Each comes back with the standard invalid-params code, and a retry changes nothing until the request changes. A removal whose query matches no entry is refused too, naming the type, the query and the file it looked in — that one is a state of the configuration rather than of the request, so the thing to correct may be either.
Nothing is prompted for, and the one decision a person would have been asked for arrives as a field instead. The terminal command asks whoever is watching whether they accept a command-extension plugin’s declared capabilities. Nobody is watching this stream, so acceptCapabilities is the caller’s to obtain and send, and a request that does not carry it is refused with what to send named rather than installing on a consent nobody gave. A daemon that was started without the means to install a command extension refuses a cli addition outright, rather than reporting a success that installed nothing.
Which kinds you may offer an author
aggrega/getSchema with no kind answers which kinds you may name, and it answers at two widths because a client needs a different one for a different job. Read the one you are asking.
kinds is every token the binary answers to. entityKinds is the set an author writes a document of. The wide list holds the intermediate representation, the lockfile, the workspace configuration and the plugin socket contracts alongside the kinds you author — real schemas, each of them, but not documents anybody writes a file of. So the wide list is the one to wire an editor’s schema association from, and the narrow one is the one to build a chooser from. A chooser built from the wide list offers values no authoring schema accepts, and the author meets the refusal only after picking one.
The narrow set is narrower than the entity kinds as well, and no schema tells you which ones. A platform-owned kind whose content is written inside another kind’s document is not a document to offer an author to start. Workload is such a kind: workload content is written in a Recipe’s or a FeatureRecipe’s workload: field, either inline or from a file that field imports, so there is no workload document to address on its own — see the Workload authoring surface for where that content goes. Its schema fixes apiVersion and kind exactly as an authored kind’s schema does, because that is what lets the content be validated where it sits; the fixed values identify the content and do not make it addressable. So they are no signal that a kind is one to draft. entityKinds carries the answer, and nothing in the schema bytes does.
Each entityKinds entry carries both spellings a client needs, and neither is derivable from the other. kind is the lowercase-hyphenated token — send it back as kind to this method or to aggrega/scaffoldEntity. documentKind is the value the document itself carries in its top-level kind: field. The two differ in more than case for a kind whose name is more than one word: nothing you can do to featurerecipe arrives at FeatureRecipe. Take each from the entry rather than deriving one from the other, and there is no mapping left for the client to keep.
Each entry also says which operations accept a document of its kind, so a control offering those operations on a document offers only the ones that do not refuse it for its kind. acceptedBy carries three booleans, each present on every entry, and each is about a document of the kind named on its own — by its path, or by its name for inspection — with nothing else sent beside it. singleEntityValidation is whether aggrega validate <path> checks a document of the kind, rather than refusing it and naming the whole-catalog or Release scope that checks it instead. publication is whether aggrega/publishEntity naming the document alone publishes it: a Plugin is false, because its publication also binds the executable a request names in plugin, so a request naming only the document is refused; a Manifest and a Release are false because neither kind is published. inspectionByName is whether aggrega/entityDefinition resolves a name to an entity of the kind, the name sent as it is written where one entity references another — a Plugin as <pluginType>/<name>, and a Recipe or a FeatureRecipe as <capability>/<name>, or by its name alone where only one capability declares that name. A true says the operation does not refuse the document for being of that kind; it can still refuse a particular document for what the document says.
Hold no list of your own. Which kinds exist is a property of the binary you are talking to, so a list written into a client agrees on the day it is written and stops agreeing the day a kind is added — and what the author sees then is their kind missing from the one control that was meant to offer it. Ask, and the answer follows the binary.
Both halves arrive together, and only when you name no kind. A request naming a kind answers with that kind’s schema and carries neither list, so which question you asked is readable from the response. A token no schema answers to is refused with the whole valid set in the message, under the standard invalid-params code, so a typo is a request to correct rather than something to ask a person about.
It answers in a workspace holding nothing. The vocabulary is compiled into the binary, so this needs no document, no lockfile and no catalog — which is the workspace an author starting their first document is sitting in.
What a scaffold response gives you
This section is about drafting. The method’s other form writes a runnable example, and its answer is described with the method above.
aggrega/scaffoldEntity hands back text. skeleton is YAML for the kind you named: every field that kind’s schema requires, in the order the schema declares them. A field the schema pins to a single fixed value arrives filled in — apiVersion and kind are the ones you will notice — metadata.name carries the name you sent, and every other required value arrives as a placeholder typed to what the schema declares there: an empty string, a zero, a false, an empty list, an empty mapping. kind repeats the token the document was derived for, so a client with several requests outstanding attributes an answer from the answer itself rather than keeping a correlation of its own.
It writes nothing, and that is the part to design around. The method creates no file, chooses no path and touches no directory. What you receive is a document to write, not a document that was written — so an editor puts the text into a new unsaved buffer the author can read, edit or discard, and the moment a new file reaches disk stays where the buffer and the undo history are. No other request takes this document and puts it somewhere on your behalf; deciding where a new document lives is the editor’s.
It resolves nothing, and it needs nothing of the workspace. The document is derived from the schemas the binary carries, so the method reaches no registry and no network, consults no catalog and reads no file. It answers the same way in every workspace, including an empty directory with no Aggrega document in it yet — which is exactly the workspace an author starting their first document is sitting in, and where most other methods here would first want a document or a lockfile.
The same request gives the same bytes wherever it is asked. The document is produced by one computation shared with the other surfaces that offer this capability, so an editor and an assistant asked for the same kind and the same name show the author the same starting text.
The skeleton carries the fields its kind requires, and it is not a finished document. It carries the required fields and nothing else: an optional field you want is one you add, and every placeholder is a value still owed. Fill the placeholders in, then run aggrega/validate on the buffer. For a catalog entity of a kind aggrega validate checks as a single entity, that method names every placeholder still owed, each at its key with what it takes, by the same reading the command applies to the saved file — a placeholder the schema admits empty included, a drafted Recipe’s or FeatureRecipe’s capability and implements being the ones you will meet. For any other kind it holds the buffer to its kind’s schema, so a placeholder the schema refuses empty — a version, say — comes back as that schema’s finding, and one the schema admits empty draws none. Live validation describes the entry each placeholder arrives as.
What an import response tells you
aggrega/import converts a source written for another tool into draft Aggrega documents, and it writes them — unlike the scaffold above, which hands you text. written names each file that reached disk, relative to outputDir; files carries every file the request writes with its content, whether or not it was written — every draft the importer produced, then the record of what the import wrote, or under sync what the sync changes. The two answer different questions, so read the one you are asking: what is now on disk, or what was produced.
You choose where the drafts go, or leave it to the workspace root. outputDir is optional, as aggrega import --output-dir and the assistant’s import tool’s output_dir are: a request naming none drafts beneath the workspace root — where aggrega import writes when it is given no destination, wherever it runs — and a request naming one drafts there. A named directory is a path inside the workspace, and a relative value resolves against the workspace root rather than against a directory the daemon happens to be sitting in. The source you convert is the other case and is not confined this way: you selected that file or directory, so it is read wherever it is, and reading it there does not move where the drafts land. The directory is created if it does not exist. Under dryRun nothing is written, and each draft still names the path it is for, relative to the outputDir the response names — the directory you sent, or the workspace root.
A request never writes over an Aggregate already in outputDir. An Aggregate is the document an author goes on editing once it is drafted, so a request one of whose drafts would land on a file that reads as an Aggregate is refused, naming the draft and where the Aggregate sits, and nothing at all is written — under dryRun as well, since a dry run refuses what the write refuses. Send sync to bring it up to date with the source instead, or name another outputDir to draft beside it. Every other file already at a drafted path is written over, and a file an earlier import drafted that this one does not draft is left where it is. Every request that drafts anything also writes .aggrega-import.json in outputDir, the record of what the import wrote — the target it was sent, where it was sent one, the catalog snapshot it read, where it read one, and each drafted file and, in a drafted Aggregate or Release, each key at every depth, with a digest of the text written there, any other drafted file recorded whole — and files and written carry it after the drafts. It is JSON, so nothing that reads the workspace’s YAML documents reads it; sync, like aggrega import --sync, reads it to bring the drafts up to date with their source. A sync sent no target drafts for the target the record names, so it drafts the Manifest the earlier import drafted; one sent a target drafts for it, and the record then names it. A recorded target no Recipe in the catalog binds to is refused as a sent one is, the refusal saying the target is the recorded one. Because a drafted Release is recorded key by key, the environment its author writes where the import left a comment for it is a key the author wrote, and a sync leaves it byte for byte.
Send sync to bring what an earlier import drafted in outputDir up to date with the source, changing only what the import wrote. Each part is judged three ways — what the record says the import last wrote there, what is on disk, and what the source drafts now. A part the source left as the import last wrote it stays exactly as it is on disk, whether or not an author edited it. A part the source changed is written anew, a part it dropped is removed — a drafted file deleted whole — and a part it gained is added beside the parts the draft names around it, each only where what is on disk is what the import last wrote and holds nothing an author added. Everything else stays byte for byte: a key an author added anywhere — a parameter, a Feature, under a drafted Component instance too, another Component — a comment not written directly above a drafted key, and every file the record does not list. A sync into a directory holding no record and nothing at its drafted paths writes the whole draft, as a request without sync does.
drift is what a sync brought up to date, and it is the answer to “has the source moved”. It lists each part the sync changed — or, under dryRun, each part it would change — in the order the draft names them, each as change (added, removed or changed), file, the drafted file it is in, relative to outputDir, and key, the keys leading to it in a drafted Aggregate or Release as a list, so a key holding a full stop stays one entry; key is empty where the part is the whole file, which is how a drafted file the sync deletes is named. aggrega import prints the same entries on standard error as <change> <key> in <file> or <change> <file>, and its exit status under --sync --dry-run says whether the source drifted; this surface has no exit status, so send sync with dryRun and read whether drift is empty. drift is an empty list for a request that is not a sync, for a sync in step with its source, and for a sync whose importer could not finish. Under sync, files carries each drafted file the sync changes, with the content it gives it, then the record where that changes too, and written names those that reached disk — so a sync in step answers both as empty lists. A drafted file the sync deletes is named in drift and in neither list: its removed entry, with an empty key, is the answer’s one account of it, under dryRun naming the file a write would delete.
A sync never rewrites what an author wrote, and refuses instead. A sync that would change or remove a part an author edited, add a part where an author already wrote one, or remove a part holding something an author added is refused, naming each such part and why on a line of its own, in the words aggrega import --sync uses — <file> <key>: <why>, or <file>: <why> for a whole file — and nothing is written; a comment written directly above a drafted key edits that key. A sync over an Aggregate no record lists is refused naming the Aggregate and the record, as is one whose record cannot be read, since without the record its parts cannot be told from an author’s. Both refusals come back as the invalid-params error, under dryRun as well, and name sync. Reconcile each part named by hand, or put back what the import wrote there, and send the request again.
🔴 halted: true is not an error, and treating it as one is the mistake to design against. An importer that could not convert everything still drafts what it could: the response carries those drafts, written names them, and diagnostics says what was left out. That is the most useful answer the operation gives, and it arrives as a result rather than as a failure precisely so you can show the author both halves. Under sync the same answer writes nothing — files, written and drift are empty — because a partial draft would read as a source that dropped every part the importer did not reach. A source the importer could not read at all is a different case and does come back as an error.
Each diagnostic carries severity and message, plus code where the importer assigned one. Branch on code when you want to react to a specific condition and show message to the reader; severity is drawn from the same set every plugin socket reports in — halt, warn, info — so halted is a summary of the entries rather than a separate judgement. files, written, drift, diagnostics and decisions are always arrays, empty rather than absent.
decisions says where the import guessed. It carries one entry per source node the importer mapped, in the importer’s order and exactly as the importer reported it: sourceNode, the node’s id, type and paramsSummary; candidates, each catalog Component the importer weighed for it as componentName, score, tier and signals — what each of its signals contributed, under table, category, domainLabels, shape and name; chosen, the target it chose, the mode it wrote it in — a reference to an existing Component or a draft — and the choice’s tier; rationale, why; and swapHint, how to choose differently. candidates is absent where the importer weighed none, chosen where it made no choice, and rationale and swapHint where it wrote none. Every value is the importer’s own — how it scores a candidate and where its tiers fall are its choices — so show an entry as its account of the mapping rather than as a verdict. The decisions arrive under dryRun and with halted true alike: a partial import’s guesses are exactly what an author reviewing it needs, and an importer that reports none answers an empty list. Where you show them as text, aggrega import already words one decision as mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>, the score being the best candidate’s.
The format is recognised from the source unless you name it. Recognition uses the signatures the importers declare — the workspace catalog’s and the compiler’s core importers’ alike — which each importer’s Plugin entity records — the syntax a source is read in, the file names a signature applies to, and the paths the parsed tree must or must not carry — so the daemon itself knows no format and a new importer’s format is recognised with nothing else changed. Detection reads only the source you sent — of a directory, only the files a signature’s file patterns select — and no network, parsing each file it reads through the parser the workspace’s catalog serves for a syntax — or, for a syntax the catalog serves no parser for, the one the compiler itself carries — once for each syntax a signature applying to its name reads it in; the importer then reads the source through the same parser. A signature declaring no file pattern applies to the file you sent whatever it is called, and to no file of a directory; the Langflow, Flowise and n8n importers’ signatures are of that kind and read JSON, and the Dify importer’s reads YAML, so recognising a file you sent on its own reads it as JSON and as YAML, which needs no parser in the workspace’s catalog: the compiler carries a JSON and a YAML parser, and one the catalog serves is used in its place. A source no signature matches is refused asking for format and naming the formats the importers advertise — or, for a directory, asking for one of its files sent on its own or a format whose importer declares file patterns, naming only those — under the condition No importer recognises the source; a source signatures of more than one format match is refused naming them, under the condition More than one importer recognises the source. Each refusal’s data carries its condition’s code and shortCode, so a client asks for the format on the code rather than on the words. Neither is guessed at, because a guessed format resolves the wrong importer and produces confident nonsense. format in the response is the one that was used, detected or named, so a client that omitted it learns what it got.
A directory you send is read into the files its importer names, and one it cannot read is an error. Where source names a directory, the importer is handed the files of it that the file patterns its signatures declare select, the workspace’s build output folder dist/ left out, each named by its path inside the directory, in sorted order, beside the files its plugins.importer entry names under with.sources. An importer declaring no file patterns, a directory holding no file they select, a directory file and a with.sources file of one name, and a link among the files the import would read, or to a directory, that leads out of the directory each come back as an error carrying the condition’s code, with nothing written.
Which importer runs is the workspace’s decision, not the request’s. The format resolves to the importer that advertises it among the workspace’s catalog plugins and the compiler’s core importers — the one a plugins.importer entry in the workspace configuration attaches, where it attaches one of them — so a request cannot select a module or point at one on disk. A format no importer advertises is refused naming the format, and a format two importers advertise with neither attached — a core importer and an importer of another name the catalog holds for the same format among them — is refused as ambiguous rather than resolved arbitrarily.
A core importer the machine does not hold yet is fetched once, by the first import that needs it. It comes from the workspace’s default registry, held to the module the compiler’s release publishes and verified as a pull verifies a plugin it fetches — its signature under that registry’s trust policy, and the host functions it uses — and it is kept in the workspace’s content cache, which is the only thing written for it: no lockfile, and no record of trusted plugins. Every later import reads it from there and reaches no registry. A module that does not verify is an error carrying its condition’s code, and nothing is kept; one that cannot be fetched — the workspace is offline, its registry cannot be reached, or the registry does not hold it — is an error under A plugin’s .wasm is not on this machine, naming the importer, its version and what puts its module on the machine. The request itself names no registry, and an import with every importer and the catalog it reads on the machine reaches no network at all.
Where the workspace names no catalog folder, the import reads the catalog its default registry publishes. A workspace whose workspace.catalog_dirs, AGGREGA_CATALOG_DIRS and root name no catalog folder reads the standard-library catalog as one signed snapshot, at catalog/snapshot on its default registry. A snapshot is fetched once: its signature is verified under that registry’s trust policy, and it is kept in the workspace’s content cache and read there as a catalog folder, held to its digest, with no registry asked for it again. Which snapshot a request reads: with upgrade, the newest; otherwise the one the record in outputDir names, fetched by its digest where the machine does not hold it; otherwise the one the workspace last fetched as the newest; otherwise the newest. The record the import writes names the snapshot it read, by its digest, so a later request into the same outputDir reads the same catalog. Under the offline posture a request that would have to fetch a snapshot is an error under The workspace is offline and the step needs the network, naming what to run, and upgrade is refused whatever the machine holds, since only the registry can say which snapshot is the newest. A registry that publishes no snapshot leaves the import with no catalog, and a warn entry in diagnostics says so. A workspace that names a catalog folder imports against it and fetches no snapshot, and upgrade changes nothing there.
Under dryRun nothing is created. written is empty, files carries the same files a write would have produced — with sync, the files the sync would write, beside the drift it would bring up to date — and no directory is made — so an editor can put them in front of the author to save, amend or discard. Everything else a write does is done: the same importer runs over the same source and reports the same diagnostics, so a source a write would refuse is refused here too. A core importer or a catalog snapshot fetched under dryRun is kept in the content cache as it is under a write, because acquiring what the import runs on is part of running it rather than of placing the drafts.
A path the importer returns is held inside outputDir. The drafts’ paths come from the importer rather than from you, so a path climbing out of the output directory is refused and nothing is written at all — not even the drafts whose paths were fine. The refusal names the offending path, which is what tells you it is the importer to correct rather than your request.
Which question each entity request answers
Four requests here will tell you about an entity, and they are not interchangeable. Picking between them is a question of what you are holding when you ask.
You are holding a cursor. aggrega/hover and aggrega/resolve take a file and a position and work out which entity is meant from what is written there. They cover the reference shapes a document actually contains — an extends value, a component or feature type, a Recipe’s implements, a Manifest’s recipe references, a Release’s two path pointers, a uses target, and an entity’s own metadata.name. Reach for these when the user’s cursor is the coordinate: the user is reading a document and wants to know what a reference points at.
You are holding a name. aggrega/entityDefinition takes the identity outright. Nothing has to be open, no position is involved, and the entity does not have to be mentioned anywhere the client can find. Reach for it when the user typed a name, picked one out of a list, or followed something your own client already knows the identity of — a hover requires you to first find somewhere the name is written, which is work you do not have to do.
You are holding nothing yet. aggrega/catalogIndex enumerates what the workspace holds, with the descriptive fields for each entity. Reach for it to populate a picker, then feed a chosen name to aggrega/entityDefinition.
You are holding a Release. aggrega/releaseClosure answers about a Release rather than about one entity, and it is the section below.
The definition a by-name request returns is the entity as resolved, not as any one file declares it. A Component or Feature that extends a base comes back carrying that base’s contract, which appears nowhere in the document that declares its name — so the answer is about what the entity is, and reading the file yourself would not give you the same thing.
It arrives as a YAML document rather than as structure inside the response, and that is deliberate: a schema pillar has several authoring shapes — content written out, a reference to a shared document, or the marker saying the content comes from a base — and the document reproduces whichever one resolution arrived at, in the author’s own key order. Parse it as a document if you need its fields; show it as it stands if you are putting it in a panel.
Telling the two by-name refusals apart
A name that resolves to nothing is refused rather than answered with an empty document, because an empty answer would report a typo as an entity with nothing to say about itself. There are two ways a name resolves to nothing, they call for different things from the reader, and you tell them apart by what the error’s data carries, not by reading the message:
- No
fileindata. Nothing in the workspace declares that name and no catalog tier resolves it. This is almost always the request to correct — a typo, or a name from a catalog this workspace does not have on its search path. - A
fileindata. A workspace document does declare that name, and the catalog still resolved nothing for it. The entity is written down and something refused it, which is a state of the workspace a person repairs. Where exactly one document the catalog read and refused declares that name — the usual cause — the message leads with that refusal, stated once: its category and short code, the document by the path it is reported at, and what is wrong with it, such as the line and the constraint it violates; then it notes that the file was skipped at load, and lists any other file the load refused. Otherwise the message names the declaring document, lists the files the load refused, and says where this workspace reads local entities from and what to change so the document is read — the account it leaves out where a refused document declares the name, because that document already sits where the catalog reads.
Both carry the entity-not-resolvable code, so branch on the presence of file rather than on the code.
Asking about a coordinate
You are holding a registry reference. Send it as the name of aggrega/entityDefinition, and the answer is the entity published at that coordinate, in the same result shape a name gets plus published, filled from what was published rather than from what a catalog resolved:
definitionis the entity document exactly as it was published. A coordinate whose entity was published with the files it declares carries an archive, and the document is unpacked from it; one whose entity declares no file carries its document unchanged, and a Plugin’s entity is read from its manifest rather than from the executable published with it. No inheritance is applied.authoredLengthis that document’s length, because the definition here is an authored document rather than a rendering of a resolved one.fileis empty, because an entity read from a registry has no document on this machine to name.publishScopeis omitted: you already hold the coordinate, which is where the entity is published.publishedis what was read, and it is present on this answer and on no by-name one: thereference;archive, whether its bytes were an archive the document was unpacked from —falsewhere the coordinate held the document itself; themediaTypethe manifest declares; and that manifest’smanifestDigest, which you can send after@in place of the tag to read the same bytes again exactly.
The request reaches the registry the reference names, with the credentials of the user this daemon runs as and this workspace’s network posture, so an offline workspace refuses it. The fetched bytes are checked against the digest the artifact’s own manifest records for them and against nothing else — no signature is verified and no withdrawal is reported — and nothing is written. A reference that cannot be read is refused with entity-not-resolvable, and the message opens with the short code of the condition that says why — the same conditions aggrega inspect reports — and ends with what to do about it. A reference that names no repository, or neither a tag nor a digest, is a malformed request and is refused as invalid params.
A closure is not the graph
aggrega/irGraph and aggrega/releaseClosure are derived from the same resolution of the same Release and answer different questions. A client already receiving the graph can reasonably assume it has this one too, and it does not.
The graph says what the Release deploys — its nodes, the boundaries they sit in, what is wired to what, and the values and attachments each node carries. It is the picture.
The closure says what was pulled in to build it, and at which versions. Every entity the Release reaches, whether or not it became a node; the shared documents those entities draw on; and the plugins that shape the output. It is the bill of materials.
Neither is recoverable from the other. An entity can be reached without ever appearing as a node — the Recipe a Manifest maps a component type to is reached by every build and is a node in none of them — and a node does not carry the version its type resolved to. So a reader asking “why did this version move?”, “what would changing this shared document affect?”, or “what does this Release actually depend on?” is asking for the closure, and a reader asking “what does this Release deploy?” is asking for the graph.
What the closure request does not do. It renders nothing and it publishes none of what it finds. In particular it raises no drift warning and no render advisory: those belong to the request that asked for them, and publishing replaces a whole diagnostic layer, so a listing that published would erase what the graph request had already put in front of the user. Ask for the graph when you want the drift verdict. The one thing it does publish is not a finding of its own: a request that finds the lockfile gone withdraws the drift warning standing on it, whichever request it is — see Lockfile awareness.
It requires a lockfile, like the graph does. The versions the listing reports are the ones this Release resolved to, and a workspace nobody has prepared has not resolved them yet. A listing produced without one would report what the catalog happens to hold today, which is a different question from what this Release depends on. The refusal names the lockfile and the Release, so a client can offer aggrega pull --release <release> directly.
kind on a closure entry is present only where it is known. A reference is collected from a position in a document, and some positions say what kind they point at while others do not. The field is reported where the reference site recorded one and omitted where it did not, rather than guessed from the shape of the name. It is reported as the word an author writes at the head of a document, which is the same word every surface reporting a closure uses for the same entry.
The same word asks for the same document elsewhere. aggrega inspect <release> --closure answers this question at the command line, and the release mode of the describe tool answers it over the assistant tool protocol. All three run one resolution over the Release, so they cannot come to disagree about what a Release depends on. See aggrega inspect “The dependency closure”.
Cache model
Operations are cache-driven: call aggrega/validate for a file before hover / completion / resolve / diagnostics on it. That seeding call does not need a Release — a validation naming none still parses the buffer and populates the cache — so these operations work in a workspace that has no Release to name. The parse cache is checked against each file’s on-disk modification time on every read, so external edits (an editor save, a git checkout) are picked up automatically — the editor’s aggrega/invalidate is an optimization, not a correctness requirement.
The cache belongs to the workspace that seeded it. A file validated under one workspace is cached for that workspace, so the same path asked about under another is reported as not yet validated rather than answered from the first one’s entry. That is what keeps a question about a second workspace from either answering wrongly or costing the first its warm state — and aggrega/invalidate likewise clears only the workspace it names.
Asking for diagnostics while a validation is running
A validation seeds two things about a file — the parse it hands to the other operations, and the findings it reports — and it seeds them a moment apart. aggrega/diagnostics is the one request that reads both: it needs the parse to know the file is one it can answer about, and it answers out of the findings. So a request arriving between those two moments would be deciding it can answer while there is nothing yet to answer with.
It waits instead. Send aggrega/diagnostics for a file that is being validated right now and the reply arrives when that validation finishes, carrying what it found. There is one correct answer for the file whatever the timing, and that is the answer you get — it is never an empty list for a file whose validation is about to report errors, which is the one wrong answer a client cannot recover from, because nothing prompts you to ask again about a file you were told is clean. The other position-based operations — hover, completion, resolve, findReferences, findImplementations — read the parse and answer from the parse, so they have nothing to wait for and never wait.
Two things end the wait early, and both are ones you already have. $/cancelRequest for that request’s id stops it, and a cooperative aggrega/shutdown stops it. Neither needs anything extra on the request.
And the wait is bounded. If the validation has not finished within the daemon’s budget for it, the request is refused with the validation-in-flight code rather than answered emptily — see Error codes. That refusal means the work you are waiting for is genuinely under way, so the thing to do is ask again shortly; it is not a signal to send another validation, which would add work and answer nothing.
A daemon running requests one at a time answers them in arrival order, so nothing overlaps and no wait ever happens. A daemon running them concurrently answers the same questions the same way, and the wait is what makes that true: the answer you get is the answer a serial ordering would have given you.
Sizes in an answer
An answer that reports a byte quantity reports it twice: as the number, and as the same quantity
written out. The written field is the numeric field’s name with Text appended — size and
sizeText, totalSize and totalSizeText, reclaimedBytes and reclaimedBytesText, and so on
through every answer that carries a size.
Display the written form and compute with the number. The point of sending both is that a client
never has to spell a size itself: the daemon writes it with the same formatter the command line uses,
so aggrega cache status and aggrega/cacheStatus show a given cache identically, down to the
rounding. A client that composed its own text would drift from that the first time it disagreed about
a boundary.
The written form uses binary units — 512 B, 1.0 KiB, 5.0 MiB, 3.0 GiB — which is the same
vocabulary aggrega/cacheEvict accepts in maxSize, so a size read out of one answer can be sent
back in the next request without being rewritten. Above bytes the text carries one decimal place, so
it names the quantity as a reader wants to see it rather than to the byte; when you need the exact
count, that is what the numeric field is for.
Where the number is optional the text is optional with it, and the two are never half-present: the
plugin size on a publish answer carries pluginSize and pluginSizeText together or carries
neither.
Every request names the workspace it is about
Send workspaceRoot on every request: the absolute path of the workspace root that request acts
on. The daemon holds no workspace of its own and remembers none between requests, so what a request
is answered about is the workspace it named and nothing else. Two requests naming two workspaces get
two answers, and neither can see the other’s entities, Releases, cached parses or diagnostics.
A request that names none is refused with the standard invalid-params error naming the parameter, and so is an empty value, which states no workspace and is answered as a missing one. Two other shapes are refused for the same reason, each named in the message: a relative path, because a workspace root has nothing to be relative to; and a path that is not an existing directory, because a workspace is a tree.
Three requests need no workspaceRoot, and each because its subject is not a workspace.
aggrega/getSchema and aggrega/scaffoldEntity answer from the schemas compiled into the running
binary, so a workspace contributes nothing to either — which is what lets both answer in a directory
nobody has prepared. aggrega/initialize is the third, and it is where you declare a workspace
rather than act on one. aggrega/scaffoldEntity’s other form, writing or listing the documentation’s
runnable examples, does act on a workspace, and a request for it names one like any other.
Each workspace’s cached state is kept separately, and naming a second one costs the first
nothing. The catalog index, the parse cache and the diagnostics of a workspace belong to that
workspace, so a question asked about somewhere else does not evict what an editor has been
accumulating for the folder someone has open. Two spellings of one root are one workspace, so a
path carrying an interior . or a doubled separator reaches the same warm state as its plain form.
Declaring the workspace you want diagnostics pushed for
Diagnostics travel two ways: you ask for them, or the daemon pushes them. The daemon pushes only for the workspace you declared at the handshake. Every other request answers with its findings in its own response and pushes nothing.
Declare it by sending workspaceRoot on aggrega/initialize. That is the whole of what the
declaration does — it does not anchor anything, and no later request is answered against it.
The reason to confine it is what a pushed diagnostic is for. Pushing is what keeps an editor’s problem list current while someone types, and it is exactly the wrong thing to do with an answer nobody asked to see: without the rule, a question asked about a second workspace — by another tool sharing the daemon, say — would fill a reader’s problem list with findings about files they never opened. Confining the push keeps one caller’s question out of another caller’s problem list.
The field is optional, and the three things you can mean by it are distinguishable:
| what you send | where pushes go | what the handshake reports |
|---|---|---|
| nothing | the workspace the process was launched over | that workspace |
| a workspace root | that workspace | that workspace |
| the empty string | nowhere — no diagnostic is ever pushed | an empty root |
Sending nothing leaves pushes on the workspace the process was launched over, so a client that declares nothing receives the diagnostics for that workspace. Sending the empty string is the honest declaration for a caller that is not an editor and has no problem list to keep in sync: every finding still reaches it, on the response to the request that produced it.
A declared workspace is resolved exactly as a request-named one is, so a declaration naming a relative path, or a path that is not a directory, is refused at the handshake rather than leaving pushes pointed somewhere unexpected.
Workspace root and active Release
The daemon resolves each workspace a request names the same way every aggrega command resolves one, and Configuration carries what anchors a root and in what order. Two consequences matter to a client. A .aggrega-config.yaml without a workspace: block does not anchor: it still contributes its settings, but a bare settings file cannot turn every parent directory into a workspace root. And when nothing anchors, the working directory is used — the daemon starts and operations simply resolve nothing, rather than refusing to run.
The process is also launched over a workspace, from --workspace-root or by walking up from its working directory, and that resolution does two things and no others: it sizes the worker pool, which is a property of the process rather than of any request, and it is the default declaration for pushed diagnostics. No request is answered against it.
Configuration is likewise the same cascade every command reads, and Configuration is where it is described. What the daemon adds is only that each workspace’s reading of it is taken once, when that workspace is first named, and reused for every later request about it. A configuration file that cascade would read and that is a link leading out of the workspace — the workspace’s own .aggrega-config.yaml, or the CI-owned overlay beside it — is not read, here as at a terminal, and nothing else that file would have configured is read in its place. What differs from a terminal is what still answers. The daemon launched over such a workspace starts, and says so once on its error stream; a request naming one is answered as follows either way. aggrega/releaseCandidates and aggrega/catalogIndex — the two requests that list what a workspace holds — answer it, read with nothing configured: the workspace’s own documents are listed, no catalog directory is read, and the held file is named in unreadLinkedFiles, whether or not the search met it. That name is how a client tells that the workspace’s configuration leads outside it. Every other request naming the workspace — a build, a graph, a validation, the default Release, the effective configuration, a write, and aggrega/catalogIndex in a Release’s terms — is decided by that configuration, so it is refused with the invalid-params error carrying E0321 — read-leads-out-of-workspace in the error’s data — and the sentence naming the link and where it leads. The handshake answers for such a workspace too, reporting defaults as its configSource, since no configuration file contributed anything the listings answer with. Remove the link, or make it lead to a file inside the workspace, and the next request reads the configuration. Beneath the project’s files sits the global layer: the file --config names on the command line that started the daemon, for every workspace it serves; otherwise the file the AGGREGA_CONFIG environment variable names when it is set; and otherwise the default location — on Windows aggrega\config.yaml inside the directory the APPDATA environment variable names, and elsewhere aggrega/config.yaml inside the directory XDG_CONFIG_HOME names, falling back to ~/.config/aggrega/config.yaml — loaded when present. Built-in defaults sit under that.
Operations that act on a Release take one as a parameter; the daemon selects none of its own. A workspace still declares which Release it points at, and a four-step cascade reads that declaration: the build.authoring_release config field, then an .aggrega/active-release marker file, then a single-Release-in-the-workspace heuristic, then an Aggregate-only fallback. A marker you write therefore takes precedence over the heuristic, and a marker naming a Release that cannot be loaded falls through to the heuristic rather than to the fallback. A marker naming a Release outside the workspace — by an absolute path, by a path climbing out of the root, or through a link leading out of it — is not read, unless your workspace configuration names that Release as build.authoring_release or as a key of workspace.releases: the configuration is the way to reach a Release kept outside the workspace, and the marker is not. The cascade then moves on exactly as it does for a marker it cannot load, and where it settles on nothing, trace says why on the marker’s line and reason in its sentence about the marker.
aggrega/activeRelease reports what that cascade chooses, and it is a suggestion for a client rather than a setting the daemon acts on. Ask the daemon rather than reading the cascade’s inputs yourself: the config field and the marker file are two of four inputs, so whichever one you read names the workspace’s choice only when it happens to be the input that won. A marker naming a Release that cannot be loaded is the clearest case — the cascade chooses a different Release entirely, and a reader of the marker would report the one that failed.
The cascade runs when you ask and not before, which has two consequences worth relying on. The handshake stays fast whatever the size of the tree, because it does not wait for the workspace walk. And the answer tracks the workspace: write a marker — with aggrega/setActiveRelease, which answers with the new choice itself — edit the config, add or remove a Release file, then ask again, and you get the new answer from the same daemon. Changing which Release you work on never requires restarting the daemon — a client sends a different release on its next request.
The operations that search the whole workspace rather than one buffer — completion, hover, resolve, findReferences and findImplementations — enumerate the YAML under the workspace root, and that enumeration honours .gitignore. Every .gitignore from the workspace root down to the file’s own directory contributes, with the nearest one winning, so a YAML file your repository ignores is not offered as a completion candidate and is not reported as a definition or a reference. A .gitignore that is a link leading out of the workspace is not read, so a file elsewhere on the machine never decides which of the workspace’s documents are searched. Vendored trees and generated output therefore stay out of cross-file results without any separate exclusion setting to maintain — and a document you expect to be found but have ignored will not appear, which is the one case worth checking when a reference seems to be missing. The Components and Features completion also offers from your configured catalog_dirs are a different reading: they come from those directories as configured — the same directories a build of a Release reads when the configuration gives that Release none of its own, or, for a request naming a Release, that Release’s own — so a catalog directory’s entities are offered whether or not a .gitignore covers it — except an entity behind a link leading out of the directory a catalog directory’s reads must stay inside, which is not read and not offered.
A request that names a Release reads that Release’s catalog directories, which are the ones a build of it at a terminal reads: its own, where the workspace configuration gives it some under workspace.releases, and the workspace’s catalog_dirs otherwise. That covers aggrega/build, aggrega/buildPreview, aggrega/irGraph, aggrega/releaseClosure, aggrega/resolveDependencies, aggrega/validate and aggrega/lint naming a Release, aggrega/attachCandidates and aggrega/attachmentContainer addressed to a node of a Release’s graph, and aggrega/connectionAtPosition, and the requests the next section lists when they name one. So one session answers every Release in a workspace that keeps a catalog variant per Release, each from its own variant, with nothing sent beyond the Release’s path. A request that concerns no single Release — aggrega/catalogIndex, aggrega/entityDefinition, completion, hover and resolve naming no Release, and aggrega/attachCandidates addressed to an entity or a label set — reads the workspace’s catalog_dirs. aggrega/lint naming neither an entity nor a Release is the exception in a workspace that names Releases under workspace.releases: there it checks the whole catalog once for each Release, each pass over that Release’s directories, as Publishing conventions, on request and on every edit describes. See Giving a Release its own catalog directories.
Answering in one Release’s terms
aggrega/catalogIndex, aggrega/entityDefinition and the five requests that start from a cursor — aggrega/hover, aggrega/resolve, aggrega/completion, aggrega/findReferences and aggrega/findImplementations — concern no single Release, and each takes an optional release that makes it concern one. It is a path relative to the workspace root, held to the same contract the other Release-taking requests hold it to; a value that names no Release file, or names a directory, is refused rather than answered in the workspace’s terms while reading as the Release’s.
What a Release reaches, for every request here: the workspace documents under the catalog directories its stack reads, and every workspace document under no catalog directory at all — a Release, its Aggregate and its Manifest written beside the catalogs. A workspace document under a catalog directory only other Releases read is not part of its answer: not listed, not resolved, not offered. That is what keeps variants of one entity, kept side by side for different Releases, from being conflated.
- The listing. Naming a Release lists the entities that Release sees. The Features listed are the ones that Release’s catalog directories declare, and a workspace document under a catalog directory only other Releases read is left out — so a workspace keeping a variant of one entity per Release lists the one variant that Release builds with, rather than every variant side by side. A document under no catalog directory at all, such as a Release, its Aggregate and its Manifest written beside the catalogs, belongs to every Release’s listing.
- A lookup by name. Naming a Release resolves the name through that Release’s catalog directories, so a name several variants declare resolves to the variant that Release builds with. A name its directories do not resolve is refused with an account naming that Release’s entry under
workspace.releases, since that entry is what the lookup read. A registry reference takes no Release, and is refused with one: it is read from the registry that publishes it, whichever Release is named. - Hover and go-to-definition. Naming a Release, the reference at the cursor is first resolved through that Release’s catalog directories, in the order the workspace configuration gives them — the same resolution a lookup by name in that Release’s terms performs — so the entity shown, and the document opened, is the variant those directories resolve it to, even where a workspace document elsewhere declares the same name. Only where no document under those directories answers for it are the workspace documents that Release reaches searched. Naming none, the order is the other way round: the workspace documents are searched first, so a reference a workspace document answers keeps that answer, and the workspace’s own
catalog_dirsare consulted only where no document declares the name — which is what finds an entity that only a configured catalog directory holds, including one outside the workspace tree. Where the editor holds an unsaved copy of the document a Release’s directories resolve to, and that copy still declares the name, the answer is read from the copy, so a position lands on the line the editor shows. - Completion. Naming a Release, the names offered are those the workspace documents that Release reaches declare, together with the Components and Features that Release’s catalog directories declare.
- References and implementations. Naming a Release, a location in a workspace document that Release does not reach is not reported, so a variant kept for another Release is never listed as this one’s reference or implementation.
- What may attach to a graph node.
aggrega/attachCandidatesaddressed to a node of a Release’s graph is always in that Release’s terms — see What an attach-candidate response tells you.
Naming none answers over the workspace’s own catalog directories, as the paragraph above describes.
Reaching a registry, and writing
Most requests here answer from the workspace and from what is already cached, and write nothing. A named few do more, and they divide along two independent axes: what a request reaches, and how far what it changes carries.
The requests that go out to a registry divide into the ones that read and the ones that publish.
aggrega/resolveDependencies fetches what a Release needs, and
aggrega/build joins it when — and only when — its autoPull field asks it to resolve
dependencies first, in which case it reaches a registry and writes the lockfile before it renders;
aggrega/registryUpdate walks every configured registry to rebuild the local search index;
aggrega/pluginAdd searches the configured registry for the plugin a request names and reads its
published versions to pin one; aggrega/registryAdd asks the registry it registers for the trust
policy that registry advertises, unless the request declines the fetch or supplies a policy of its
own, and aggrega/configInit asks the registry it is seeding for the same; aggrega/explainError acquires the documentation bundle it reads
a condition’s walk-through from, once, where the cache every project on the machine shares holds no copy the
workspace’s own signature check admits — see aggrega explain;
aggrega/scaffoldEntity sent example or list acquires the same bundle on the same terms, and a
write then writes the example into a new directory of the workspace;
aggrega/import fetches a core importer from the workspace’s default registry, once, where the
machine does not hold it yet, and, in a workspace that names no catalog folder, the published
catalog snapshot it reads — see What an import response tells you; and
aggrega/entityDefinition reads the entity a registry reference names when one is sent as its name,
writing nothing.
aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts and
aggrega/deprecateArtifact write to one — bytes, a signature, or a withdrawal marker. A request
reaches a registry only when it was sent to do that: a listing reports what the configuration pins, a
search reads an offline snapshot, and a publication asked for with dryRun computes what it would
send and contacts nobody.
The rule is about when an operation runs, not about which surface runs it. An operation that
fetches or writes runs because a request named it, and never as a side effect of validating a
document, inspecting a graph or listing a workspace’s entities. So an editor that validates on every
keystroke reaches no network and rewrites no lockfile, while a “resolve dependencies” action the user
clicks does exactly what aggrega pull does — the same resolution, behind both surfaces, writing a
byte-identical lockfile and filling the same artifact cache.
Nothing is prompted for. Nobody is watching this stream, so identity is resolved from a supplied or ambient credential source and never by asking. Where the terminal command would have put a question to a person — a registry that needs credentials, a capability more than one provider plugin serves, the text a withdrawal is to carry — the request fails with a message naming what to supply rather than blocking on an answer that will never arrive. A refusal leaves the workspace exactly as it was: no lockfile is written and no partial record is left behind, and a publication that could not resolve a credential refuses before any bytes reach the registry.
Some changes reach past this workspace, and the answer says which
A request names one workspace, so an answer with nothing to say about its own reach reads as being about that workspace. For several of these requests that reading would be wrong, so each one carries its scope and a client should show it before acting on the result.
Publishing, signing and withdrawing reach past the machine entirely, which is the widest reach anything here has. The other writes below change what this machine resolves; these change what everyone resolving from that registry does. Published bytes are what every consumer of that registry gets, and re-publishing different content over a tag is refused rather than offered, so no request here takes a publication back — the answer is to publish a new version. A signature and a withdrawal marker are attached as siblings of the artifact rather than replacing it, so the bytes themselves are untouched; but anyone who fetches the artifact afterwards fetches them too, and neither can be recalled from anyone who already has it. A withdrawal is the sharpest of the three to read wrongly: the version stays fetchable, while a retraction a workspace trusts takes it out of what a resolution there will choose.
Signing uses credentials, and where they come from is worth knowing before you wire a client.
Keyless signing resolves an identity token, in order, from identityToken on the request, then
AGGREGA_IDENTITY_TOKEN in the daemon’s environment, then the ambient GitHub Actions OIDC endpoint
where one is reachable, then SIGSTORE_ID_TOKEN. When none of those yields a token the operation
refuses and names what to send; it never opens a browser, because there is nobody to look at it.
Keyed signing is the offline alternative, and a request names no key path: what a request reads
is located inside the workspace it named, and a private key is never kept inside a workspace, so the
key comes from the signing: block of that workspace’s own configuration instead. See
aggrega sign for the two signing modes and what each contacts.
Every one of the four answers carries reach, holding registries — every registry host the call
addressed, each named once, in the order the call first addressed it, so a signing batch or a batch
file whose references span registries names each of them — and beyondThisMachine, which is derived
from what the call actually attached rather than from what it asked for: true exactly when it uploaded
content or attached a signature, a publication date or a deprecation marker, and false for a dry run
and for a call that found everything it would have attached already there — a publication run again
over a version that is already complete, or a signing batch whose every reference already carried a
signature that verifies. A dry run still names the destination it would have addressed. Show it
before acting on the result.
Registering or removing a registry writes the configuration shared across every workspace on the
machine, by default. A registry and the identities you trust on it are usually the same wherever
you work, so that is where the entry goes unless the request sends workspace: true. The consequence
is worth stating plainly: aggrega/registryAdd and aggrega/registryRemove change what every
project on that machine resolves through, including projects nobody in this session has named. Both
answers carry scope, with the configFile that was written and machineWide saying whether it is
the shared one. Removal is the sharper of the two, because re-adding is not the same act — the trust
policy that was pinned is gone, and a later registration pins whatever the registry advertises then.
Seeding a configuration writes that same shared file by default, and for the same reason. aggrega/configInit registers a registry and its trust policy, which is machine-wide tooling, so with no override it writes the configuration every project on the machine resolves through — and it reaches that registry once to read the policy it advertises. Its answer carries the same scope pair the two registry methods carry. It differs from them in one way worth relying on: it refuses rather than overwrite an existing configuration file, so it cannot replace a configuration somebody is working from unless the request sends force. Freezing is the opposite case: aggrega/configCapture takes no override at all, always writes the project’s own configuration file and reaches no registry, so nothing it does is visible to another project. See What a configuration write leaves behind.
🔴 Adding or removing a command-extension plugin writes that same shared file by default, and this is the one to read closely. aggrega/pluginAdd and aggrega/pluginRemove take a type, and the type decides where the write goes with no override sent. A provider, governance, linter or importer entry shapes one project’s build, so it goes to that project’s own configuration. A cli entry is machine-wide tooling, so an addition of type cli naming neither global nor workspace registers the command in the global configuration file every workspace on this machine resolves through — the command becomes a top-level aggrega command for every project on that machine, including projects nobody in this session has named, and taking it back is a separate removal rather than an undo. Send workspace: true to keep it local. Both answers carry scope, with the configFile that was written and machineWide saying whether it is the shared one, derived from the file the write resolved to. An addition also reaches the registry it searched, so it is on both axes at once. See What a plugin change tells you.
The other two plugin requests write only inside the workspace. aggrega/pluginSync writes the Plugin entity file the request names, and aggrega/pluginGenCatalog writes the generated entities under the outputDir the request names — both inside the workspace the request named, both refusing a destination that is absolute or resolves outside it, and neither visible to another project. aggrega/pluginGenCatalog reads its module and overlay from wherever you selected them, which does not widen where it writes: the two are resolved by different rules, so a generation may read a module you built anywhere while the entities it produces still land inside the workspace. aggrega/pluginGenCatalog under dryRun writes nothing at all and hands the content back instead.
Pinning an entity writes only inside the workspace too, and reaches the hosts its sources name. aggrega/pin writes the entity.lock beside the entity the request names, which is a path inside the workspace, and fills the workspace’s content cache with the sources it fetched; nothing it writes is visible to another project. It reaches out to resolve each remote source the entity names — a chart repository, a Git host, a URL — which is the same reach aggrega/resolveDependencies has for the sources a Release consumes. aggrega/resolveDependencies and aggrega/publishEntity sent pinSources run this same step, so each of them writes beside the entities it pins as well; a publication that pins therefore reaches the workspace as well as the registry. A publication that does not pin writes nothing beside the entity, and still reaches those hosts: comparing the lock with what the step would record means fetching each remote source the entity writes out in full.
Installing the assistant skill stays inside the workspace unless the request sends global. aggrega/skillsInstall writes each named assistant’s project skill folder inside the workspace the request named, and nothing it writes there is visible to another project; its answer’s scope carries machineWide false. With global: true it writes each assistant’s per-user folder under the home directory instead, which that assistant reads in every project on the machine, and machineWide is true. Either way it reaches no registry and no network.
Removing a stored credential reaches wider than anything else here that stops at this machine. aggrega/logout changes the credential store, and that store is shared not only by every project on the machine but by every other tool authenticating to the same registries — so a credential removed through a session is gone for all of them, and aggrega/registryList will report it absent in every other workspace too. Its answer carries scope with machineWide, which is always true: this store has no workspace-scoped form to resolve to, so there is no override to send and nothing for a request to opt into. scope deliberately names no file, unlike the configuration writes above. The store delegates to whatever credential helper or OS keychain the machine has configured, so the removal is frequently served by something that is not a file at all, and naming a path would point you at a location the removal did not necessarily touch.
Removal is not the reverse of authenticating, and a client should not offer it as one. This surface removes a credential and does not acquire one: getting a credential back means authenticating again with aggrega login at a terminal, because storing one takes a secret typed by a person and nobody is watching this stream. So a “log out” a client offers is one-way from here. What separates the two is whether the operation has to obtain something from whoever is driving it — a removal carries its one value in the request, while acquiring a credential does not — and not whether a person is involved, since a person chose both.
Reclaiming cache content reaches past the workspace too. The compiled-module and plugin-describe
stores are shared by every project on the machine, so aggrega/cachePrune, aggrega/cacheEvict and
aggrega/cacheClear can remove content another project depends on. Each removal carries the reach
of the class it came from, and each answer carries scope.machineWideClasses. aggrega/cacheStatus
carries the same reach on every class even though it changes nothing, because a client deciding
whether to reclaim needs it before it acts.
Refreshing the search index is the other way round. aggrega/registryUpdate reaches every
configured registry, and what it writes lands under this workspace’s own configured cache directory —
so it changes nothing another project resolves through. indexRoot in the answer names that
directory.
A partial refresh answers rather than failing. A request naming one registry whose refresh failed
is an error, because there is no answer to give. A request refreshing every configured registry
succeeds even where some of them, or all, failed: the ones refreshed were indexed and written,
failed names the rest, and each host carries its own error. Read failed rather than the presence
of an error.
Whether a registry could be reached is a key, not a reading of the message. A host that failed
carries unreachable: true where the registry was never 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 — and the refusal of a request naming one registry carries the same key in its data.
A registry that was reached and failed, with a listing that repeated itself or an error status,
carries neither, and its error, or the refusal’s message, says what it answered. The key is read
from the failure itself, so it does not turn on how this machine’s resolver words a failure, and it
is set only where the failure shows the registry was never reached: a failure that shows nothing
either way, such as a time limit that ran out with no record of which step it interrupted, is
reported without it. Name a registry as not reached on the key, and show the error as the reason.
The command line reports that same walk as a non-zero exit, and which reader you are decides what
that exit is worth. For a person at a terminal it is not the whole account: aggrega registry update
prints how many of the selected registries it indexed, what each one found, which ones it did not
index, and where the index was written — so the summary says what happened and the exit status says
only whether all of it succeeded. For a script it is the whole account, because that command offers no
structured output mode, so its exit status is the only machine-readable verdict available. That is why
the two surfaces answer the same partial walk differently and both are right: this one hands a
structured caller failed and succeeds, while the command line has one bit to spend and spends it on
“was any registry missed”.
Watching a long operation
Most requests here answer from what is already on disk and answer at once. A few do real work first — resolve a Release’s dependencies, pin its external inputs, publish, sign, withdraw — and the caller waits. Those report what they are doing while they do it, and it is opt-in per request.
Opting in takes two steps, in this order.
- Declare the capability at the handshake, and wait for the reply. Send
capabilities.window.workDoneProgress: trueonaggrega/initialize. Do not send anything else until that reply has arrived: requests are serviced concurrently, so a request written before the handshake answered can be running alongside the handshake that was to negotiate for it. Every client already owes the protocol that ordering; this is one more thing that depends on it. - Put a token in the request’s params. Add
workDoneTokento the params of the request you want reported on. The value is yours to choose — a string or a number — and it is what ties the notifications to that call. Mint a fresh one per call.
The notification. Each one is $/progress with params.token set to your token and params.value carrying one payload:
value.kind | carries | when |
|---|---|---|
begin | title — what is happening, in a phrase you can put in front of a reader | once, when the work starts |
report | message — one line of the operation’s own account of itself | any number of times, as the operation writes them |
end | nothing beyond the kind | once, when the work is over |
Correlate on the token, never on the request id. A notification carries no id — it is not a response to anything — and the token is the only thing in it that points back at your call. That is deliberate: in many clients the request id belongs to the transport and never reaches the code that issued the call, whereas the token is a value that code already holds.
A report carries the compiler’s own text. The message is one line the operation wrote as it worked, passed through with its surrounding whitespace removed and nothing else changed — not re-worded, not summarised, not re-composed — and a line the operation wrote blank is dropped rather than reported as an empty message. So a client shows what it is given as it stands. It is the same property the response’s own diagnostics have: one condition keeps one wording however many surfaces report it.
A step the operation waits on is a report too. As the operation enters a step it waits on — reading a registry, fetching an artifact, compiling a plugin — a report carries the step’s name, in the words the command line shows beside its spinner for the same step. Only steps entered between the begin and the end are reported.
One line of output is one report. An operation that writes several lines at once produces one notification per line, and a line the operation writes in pieces is reported once it is complete — so a message is never half a sentence.
There is no fraction and no percentage, and that is not an omission awaiting work. The operations that report here work through a set whose size is not known when the work starts — how many references a resolution walks, how many layers a publication uploads — so any fraction would be invented. Draw an indeterminate indicator and show the latest message.
Frames arrive before the response and never after it. A begin arrives once the work has actually started, so a request refused on its params — a path that is absolute, a missing required field — produces no notification at all, only its error. The end arrives before the response, and whether the operation succeeded is on the response rather than repeated in the end.
Stopping the work is a separate notification. Send $/cancelRequest with the id you sent the request under. The token plays no part in cancelling, and cancelling does not suppress the frames already sent.
Which requests report, and what to expect of the rest
Exactly these report: aggrega/resolveDependencies, aggrega/pin, aggrega/publishEntity, aggrega/publishArtifact, aggrega/signArtifacts, aggrega/deprecateArtifact.
Two things are true of every one of them, and both are why it is on the list: it reaches a registry or a remote URL on your behalf, so how long it takes is set by something outside the machine; and it already writes its own account of itself as it goes — the account a person watching a terminal reads. So reporting hands you that same account rather than a second one composed for the wire, and nothing about what the operation does had to change to produce it.
Every other request accepts a token and sends nothing. Sending one is harmless rather than an error: it is accepted, no notification arrives, and the answer is exactly the answer you would have got without it. So a client may attach a token to whatever it likes and simply draw nothing when nothing comes.
🔴 Do not read the silence as “this one is instant.” Most of the rest do answer from what is already on disk — a validation, a hover, a completion, a graph, a cache listing, a configuration read — but not all of them: refreshing a registry index, adding a plugin, a pre-publication check, and the first expansion of a code on a machine holding no documentation the workspace may read all reach a registry, and compiling a Release is real work. Those take as long as they take and report nothing today. Show an indeterminate indicator for any request you are prepared to wait on, and treat notifications as detail you get when it is available rather than as the thing that tells you work is under way.
Two refusals
Both are invalid-params errors and both name what to do, because a token that quietly did nothing would leave you watching for a stream that was never coming.
- A token from a session that declared no
window.workDoneProgresscapability is refused, naming the capability to declare. Declare it at the handshake, or leave the token out. - A token that is neither a string nor a number is refused, naming the two shapes. An absent token, and an explicit
null, are not refusals — both mean you asked for no report.
Lockfile awareness
The daemon checks a lockfile for drift on each aggrega/irGraph, against the Release that request named, surfacing drift as a non-blocking warning. The warning names the command that rewrites that lockfile with the Release in it, spelled as the request sent it — aggrega pull --release followed by the release you sent, which is how it is written at a terminal in the workspace root. aggrega/irGraph requires a lockfile to be present. There is no separate check at startup: a request says which Release it is about, so the verdict is computed for that Release when it is asked for rather than once for one Release chosen in advance.
A drift warning goes when its lockfile goes. The warning is published on the lockfile it was raised against, and a lockfile that is no longer there has no pins left to have drifted — the command the warning names would write a new file rather than repair the old one. So every request that finds the lockfile missing withdraws the warning before it refuses with the lockfile-absent error: aggrega/irGraph, aggrega/releaseClosure, aggrega/build, aggrega/buildPreview, aggrega/attachCandidates and aggrega/attachmentContainer asked about a graph node, and aggrega/connectionAtPosition. The withdrawal arrives as an aggrega/publishDiagnostics notification for the lockfile carrying an empty list, ahead of the refusal. It comes from whichever of those requests learns of the deletion first, so a client that reports the deletion and then asks for anything about that Release has the warning cleared without asking for the graph specifically. A lockfile that is still present and still drifted keeps its warning through every one of those requests. aggrega/invalidate naming the lockfile drops what the daemon holds for it but sends nothing; the request that follows is what tells the client. And a lockfile the daemon cannot even examine — one whose directory it may not read, say — withdraws nothing, because it may still be there and the warning may still be true.
aggrega/build and aggrega/buildPreview require one too, and they hold the Release to it rather than warning — they render under the posture of a surface that emits an artifact, so a lockfile that no longer matches what the Release resolves to halts them where it would only warn an inspection. A Release with no lockfile is refused with the lockfile-absent error. The exception is a build whose autoPull field asks it to resolve dependencies first: that build writes the lockfile and then renders against what it wrote, and a lockfile produced that way is not drift-checked a second time, because the resolution that wrote it ran the same check against it before writing it and writes no lockfile that check refuses.
A lockfile that exists but records no digest for a plugin does not stop the graph — an absent lockfile does. Those are two conditions and only the second one refuses. aggrega/irGraph does not hold the bytes it resolves to their recorded digests: a pin it cannot verify is reported rather than refused, and the graph is drawn with the finding on the Problems panel, since an editor that declines to draw the graph leaves the reader with nothing where a report leaves them something to act on. Elsewhere the plugin runs too, with a warning saying nothing checked its bytes. What aggrega/irGraph refuses is the missing lockfile: it stops before it resolves anything and answers with the lockfile-absent error, naming the lockfile it looked for and the Release, so a client can offer aggrega pull --release <release> directly — or send aggrega/resolveDependencies for that Release and write the lockfile without leaving the session. Keeping the two apart matters, because a drawn graph is a picture a reader then reasons about, and one built from bytes nothing checked is drawn exactly like one that was checked, with the finding sitting somewhere the reader is not looking. So a graph is not a verdict on the bytes behind it — aggrega/build and aggrega/buildPreview are the surfaces that hold a Release to its recorded digests, halting where the inspection reports.
aggrega/validate, when a request names a Release, reads that Release’s lockfile for its pins and its deprecation notices only — and reads none for a catalog entity it checks as a single entity, as the command line reads none. It does not hold the plugins it runs to the recorded digests, and it does not rebuild the transform-plugin attachment set from the lockfile — it validates against the workspace configuration as it stands in front of you, which is what an editor has to do while you are editing that configuration. aggrega validate and aggrega build do both, and remain the authoritative surfaces for a verdict about a committed workspace.
Its deprecation notices cover both places a withdrawal is recorded. A marker on a pinned reference is in the lockfile; a marker on a plugin attached in a role that returns an accept-or-reject verdict — a plugins.governance attachment at ir-verdict or render-verdict, or a plugins.linter attachment — is in the plugin trust record beside it, so the validation reads both and names each withdrawn reference and each withdrawn plugin as a warning at the head of the Aggregate, in the words aggrega build prints. A notice changes no verdict. A trust record that is there and cannot be read is reported as an error in place of the validation, rather than read as one that records nothing. aggrega/releaseClosure reports the same set in its deprecations.
Where a Release’s lockfile is
Every answer that names a Release names its lockfile too, so a client never works the path out. aggrega/activeRelease carries it as lockfile beside release, aggrega/releaseCandidates as the lockfiles map beside releases, and the lockfile-absent error as lockfile in its data. Each is the file aggrega pull --release <release> writes and aggrega build reads, and the file every request above checks for — so a client that watches a Release’s lockfile, to notice it being written, rewritten or deleted, watches the file the daemon means. The lockfile sits beside its Release and takes the Release’s name with a .yaml or .yml extension replaced by .lock; a Release named with any other extension keeps its whole name, so the lockfile of release.rel is release.rel.lock. Read the path off the answer rather than composing it from that description, and the two cannot come apart.
The external references a render asks for
A render can ask for content from a remote URL — a chart’s values schema with a remote reference, for example. External inputs are frozen for every render this daemon performs in answer to a request that only asked to be told something. A reference the Release’s lockfile pins is served from the content-addressed store, which is a read of content already on disk rather than a fetch, and it is checked against what the lockfile records before its bytes are served — so a render here sees what a build sees, and raises the advisories a build raises. A reference the lockfile does not pin is declined rather than fetched: acquiring one would reach a network and write a blob into the store, and a session does neither on a request that only asked to be told something. That is the rule under Reaching a registry, and writing read from the render’s side, and it holds however such a render was reached.
The request that exists to pin is the exception, and it is the same exception the registry rule already carries. aggrega/resolveDependencies is asked to acquire, so the render it performs to discover which references this Release consumes reaches the network and writes what it pins — which is what makes its result a lockfile rather than a report. No render a graph or a build request performs for itself does any of that.
A build asked to resolve first is answered from that very render, which is why it renders the Release once. The resolution has already rendered what the build is about, against the pins it just wrote and under the gates a build runs, so the build presents that render rather than performing a second one — and the acquisition still belongs to the resolution rather than to the build. Only a render that finished is used that way: where a resolution pinned its dependencies but could not finish discovering the external references, the build renders for itself against the pins that did land, and an unpinned reference is declined and reported there exactly as it is on a build that resolved nothing.
Declining is reported rather than absorbed, because nothing about a result says which reference was missing from it. With the providers this binary carries, the provider that asked for the reference hands the refusal back, so a render that reached a declined reference does not complete. Each declined reference therefore arrives as its own entry on the aggrega-build layer, naming the reference and the command that pins it: aggrega pull --release <release>, or aggrega/resolveDependencies for the same work without leaving the session. The entries are advisory rather than a refusal — the graph is still returned, the same standing the drift warning above has — and they are attributed to the Aggregate at the head of the file, because a reference a render asked for names no key an author wrote. They travel in the same publication as the render’s own advisories, which replaces that layer whole, so a reference you go on to pin stops being reported without anything having to clear it. A fully-pinned render says nothing about any of this. See What a diagnostic entry carries for the shape each entry takes.
On aggrega/irGraph this depends on the rendering stage running at all. The graph request skips the render unless --build-on-inspect, or the serve.build_on_inspect key it overrides, turns it on; with the dial off nothing asks for an external reference and there is nothing to decline. Turning it on is what brings both the render’s own advisories and these into an editor session.
Where a session differs from the same freeze at the command line. aggrega build freezes external inputs for a dry run as well, and an unpinned reference behaves the same way on both surfaces: it is reported as a finding naming the reference, and the render then halts, because the provider that asked for it hands the refusal back. What differs is the refetch. At the command line a pinned reference whose stored copy has gone missing is fetched again by its recorded digest; the render that answers a graph or a build request refetches nothing, because that render reaches no network, so it cannot go back for a pinned reference the store no longer holds — and such a reference is not among the declines described above, which name what the lockfile does not pin. Asking a session to pin is what recovers it: the requests named above reach the network and put the missing bytes back. See aggrega pull for what pinning fetches and records.
What a refused run still tells you
A request that refuses answers with an error envelope, and the findings the run had already made do not travel inside that envelope — the envelope carries no result body at all. They reach you the way they reach you on a run that finished: as a diagnostic publication on the aggrega-build layer, described under What a diagnostic entry carries. So a client handling a refusal reads the envelope for what to change and its problems surface for what the run found, and neither stands in for the other. A refusal raised while rendering is the one refusal that is also a finding about what an author wrote, so it reaches both, as the next section describes.
That publication happens whether or not the run reached its end. A run that stops partway still found everything ahead of the point it stopped, and a reader who lost those findings would have to run again to see them — so the advisories are published from what the run reached, and the refusal is returned afterwards. It is the same set at the same fidelity, positioned on the same authoring keys: a refusal does not demote a finding to a sentence. The declined external references travel in that same publication, for the same reason and by the same route.
What bounds it is how far the run got, not what the layer can carry. A refusal from one of the checks that run before the compiler starts — the Release’s closure could not be resolved, the Manifest maps a type onto a recipe that does not implement it, the lockfile no longer matches what the Release resolves to, a pinned entry in the cache no longer matches the digest recorded for it and no catalog directory holds the pinned bytes — has no advisories to publish, because none had been raised yet. The layer then carries nothing rather than something stale; and a run that did not get as far as naming a document publishes nothing at all, leaving whatever is already on your problems surface exactly as it was rather than clearing entries it learned nothing about.
A refusal raised while rendering
A Release the compiler refuses while it renders — a Workload naming a slot its Component does not declare, an assertion that fails, a template that cannot be evaluated, a realization short of what it must provide — is reported where it points and in the compiler’s words, on every request that renders it: aggrega/build, aggrega/buildPreview, and aggrega/irGraph with the rendering stage turned on. The answer is an error envelope with the -32603 code, whose message is the refusal with every cause beneath it, in the words the command line prints for the same build: the node being rendered, then what in it refused, each cause after the one it explains — led, where the refusal names a registered condition, by that condition’s short code, as every refusal naming one is. Its data names the document the refusal points at as file, and the span of the key there as line, column, end_line and end_column, beside the condition’s code and shortCode; a refusal naming no key, or one the document does not hold, carries file alone, and one that points at no document names the Release’s Aggregate.
The same refusal is published on the aggrega-build layer, on that document, at that key, as an entry of severity error carrying the refusal’s own keyPath and the envelope’s message without the short code ahead of it, and — where the refusal names a registered condition — that condition’s code, shortCode and codeDescription, the short code travelling in its own field there. It travels in the one publication that carries the advisories the run raised before it stopped, so it replaces the layer as they do: the next run of the Release that renders publishes the layer without it, and the document it sat on is published empty, which is what clears it from your problems surface.
Where a refusal points is what the refusal itself names, and no finer. A Workload’s checks judge the document its template produced, and a template can write lines no author wrote — a loop, a condition, a text imported from a file or a library — so a line of the rendered Workload does not map to a line of the Recipe. A refusal about a Workload is therefore placed on the Recipe’s workload key, and the paths it names inside the rendered document stay in its message. A failing assertion is placed on its own key under assertions in the Recipe or FeatureRecipe that declares it; an assertion a Component or a Feature declares is raised before any document is in hand to name, and is placed on the Aggregate’s kind: key. A refusal from a step that names a document but no key is placed on that document’s kind: key.
A refusal that joins several findings is published finding by finding. The composition of the graph the render works from refuses with every violation it found in one refusal — an entry naming a target nothing answers to, two connections of one component given one alias — and the command line prints each as a diagnostic of its own, under its own head. Here each is its own entry on the aggrega-build layer, on the document and at the key that finding names — the Release where the Release wrote it, the Aggregate where the Aggregate did — in its own words and with its own codes. The answer’s message carries every finding, and its data names where the first one points.
A value an author declared sensitive is withheld here exactly as the command line withholds it. The refusal’s text is the text the compiler raised, nothing on this surface rewords it, and the compiler withholds a declared value where the refusal is raised — <redacted> in its place — so this answer, this entry and the terminal carry it in the same words; what a refusal says about a declared value states how, and which refusals sit outside it.
A refusal from a gate that runs before the render is not this. The checks listed above answer as What a refused run still tells you describes. An assertion a Component or a Feature declares, and a refusal over the composed graph, sit between the two: each is raised before the render, by every request that resolves a Release’s graph, so aggrega/irGraph answers and publishes it as above with the rendering stage off as well; aggrega/releaseClosure, aggrega/attachCandidates and aggrega/attachmentContainer asked about a graph node, and aggrega/connectionAtPosition, answer it with the same envelope and publish nothing, because they own no problems surface.
Error codes
Responses use the standard JSON-RPC error codes plus an application-level range in the 1xxx band. An editor client can branch on the code without parsing the message.
1001file-not-validated — the daemon holds nothing for the file, as it now stands, that the request can answer from: no parse of it, or, foraggrega/diagnostics, no parse of it or nothing held for the file that is a validation’s answer for the text the daemon now holds. Sendaggrega/validatefor it and ask again.1003lockfile-absent — the Release the request named has no lockfile, and the operation asked for needs one.1004entity-not-resolvable — the name matched no entity in any catalog tier, nor in the Release the request named; or the registry reference sent as the name could not be read as an entity, and the message names the condition that says why; or the Release’s lockfile is a link leading out of the workspace, which is refused before anything reads it, withdatanaming the lockfile and the Release and the message opening with the condition’s short code,E0321— see the workspace boundary.1005shutting-down — the daemon is draining after a shutdown notification and refuses new requests. Do not retry against the same subprocess.1006validation-in-flight — a validation of the file is running and did not finish within the budget the waiting request allowed it. Ask again shortly and send nothing.
1002 is not allocated, and it is available for the next condition that needs a code.
File-not-validated and validation-in-flight report opposite states, and the action each calls for is the opposite too. File-not-validated means the daemon holds nothing for the file, as it now stands, that the request can answer from — no parse of it, or, for aggrega/diagnostics, no parse of it or nothing held for the file that is a validation’s answer for the text the daemon now holds: send aggrega/validate and ask again. A validation cancelled partway leaves a file there, because it stores nothing and what an earlier validation found about different text is not an answer for the text the daemon now holds; an earlier answer still stands while the text is the one it checked. Findings the daemon pushes about a file it read from disk itself — a lockfile that drifted, a Release that does not load — are not a validation of the text you hold, so they do not answer this request either. Two validations of different texts sent close together can also leave you here, where the one whose text the daemon kept finished first: the request is refused although that text was checked, and validating again answers it. It is stated in terms of the parse rather than of the file because a buffer no parser will read is in exactly that position — the validation ran and reported what it found, and there is still no parse to answer from. Validation-in-flight means a validation of it is running and did not finish within the budget the waiting request allowed it: ask again shortly and send nothing, because the state you need is already on its way and a second validation would only add work. Reading the two as one condition leads a client to send a validation in the case where sending one is the wrong move. The two bands mean different things to a client: a 1xxx code names a state of the workspace the user can act on — validate the file, generate the lockfile — while a standard code such as invalid-params names a malformed request, which the client corrects rather than the user. A release value that is present but malformed — absolute, or resolving outside the workspace root — falls in the second band: the workspace is not in a state the user has to repair, the request is. Omitting release is in neither band, because it is not an error at all; it selects the narrower of the two answers described under Live validation.
An error may carry a data object, and every key in it names one thing and only that thing. file is the source document the failure is about — the document being validated, the Release whose load failed, the workspace document that declares a name nothing resolved, or the document a refusal raised while rendering points at — and it is what any accompanying line and column locate a position within. Those two are themselves optional: a failure about a whole document carries file alone. lockfile is a lockfile. release is the Release the error is about, spelled the way the request named it, so a client can compose aggrega pull --release <release> without parsing it back out of the message. unreachable says the registry a refused request named could not be reached: a refused index refresh naming one registry carries it, read from the failure itself, and a registry that answered leaves it absent. Every key is optional and present only when the daemon has that value in hand; none stands in for another, so what a key points at never depends on the code beside it.
code and shortCode in data name the condition a refusal reports, on every refusal that reports a registered one, whatever its numeric code: the descriptive code a program branches on and the short code a person quotes, the same two identifiers, under the same names, that a diagnostic entry carries for the same condition, and listed in the table of every condition. Branch on code. The numeric code names the state of the request and stays what it is for many conditions — a build refused because a catalog link leads out and a build refused because a name resolves to nothing are both 1004 — and the message is prose that may be reworded, so neither tells one condition from another. Invalid-params is one such shared code: a request naming a workspace whose configuration file leads out of it draws it too, and there read-leads-out-of-workspace says the fault is the workspace’s layout, which a person repairs, rather than the request. A refusal reporting no registered condition carries neither key, and the two are present together or not at all. The message of a refusal naming a condition opens with its short code, E0321: …, once, which is the form a person reading it meets on every such refusal; a refusal whose message already opens with a bracketed head carrying the code — the one-line report of a catalog document the load refused — is not given it again.
The account of how the workspace’s Release cascade ran travels on the aggrega/activeRelease answer, in its trace field, rather than on an error: a workspace that points at no Release is an ordinary state rather than a failed request. It is diagnostic prose written for a person to read, not a structure to parse. Show it as it stands — write it to a log, or into a panel the user can open — and do not match patterns against it, lift values out of it, or branch on the labels it uses: its wording, its layout and those labels track the cascade itself and change whenever the cascade does. A client that passes the text through keeps working across such a change; one that has learned its shape breaks on it.
See also
- ../schema/other/serve-wire.md — the message shapes this protocol exchanges, generated from the published schema: every method’s parameter object, every result and every notification payload, field by field.
- ./aggrega-build.md — the build command, whose compiler pipeline, gates and dependency resolution
aggrega/buildruns as well, so the two surfaces write one output tree rather than two. - ./aggrega-version.md — the version command an editor extension uses to check daemon compatibility.
- ./aggrega-pull.md — the lockfile the daemon’s drift surface reads.
- ./aggrega-lint.md — the publishing conventions the daemon reports on request, and on every validation once
serve.lint_on_validateis on.
Synopsis
aggrega serve [flags]Description
Run the Aggrega compiler as a long-running service. The daemonreads JSON-RPC 2.0 messages from stdin and writes responses to stdoutunder the aggrega/ method namespace. State (parsed YAML, diagnostics,resolved catalog) holds across requests so IDE clients can issue manycheap operations without re-paying per-invocation startup cost.
The daemon resolves its workspace root through the same path everyaggrega command uses: --workspace-root when set (used as-is, validatedto exist as a directory), otherwise discovery walking upward from thecurrent working directory. A directory anchors the workspace when itholds a .aggrega-config.yaml carrying a workspace: block, or — as afallback — any of .aggrega/, aggregate*.yaml, release*.yaml,manifest*.yaml.
Configuration is the cascade composition of the .aggrega-config.yamlfiles from the workspace root down to the working directory (neareroverrides farther), beneath which the global config file — the one--config names, else the one the AGGREGA_CONFIG environment variablenames, else the default location when a file is there — and thebuilt-in defaults apply.
The daemon honors the aggrega/shutdown JSON-RPC notification for acooperative cross-platform exit: the daemon completes the in-flighthandler if any, refuses new requests with code 1005, and exitscleanly within a 2-second drain budget.
Asking the process itself to stop — an interrupt from the terminal, ora termination request from a supervisor or container runtime — takesthe same path on the same terms: the first request drains the daemonand it exits cleanly, and a second ends the process at once.Flags
| Flag | Default | Description |
|---|---|---|
--build-on-inspect | false | Run the artifact-rendering stage while inspecting an IR graph, so the advisories aggrega build raises while rendering also appear as editor problems. It adds none of the checks a build halts on. Nothing is written to disk: no rendered artifacts, no output directory, no lockfile. Off by default, matching aggrega inspect, which raises no such advisory either. When set, overrides the serve.build_on_inspect config key. |