Skip to content
AggregaAggrega
Select language: English

aggrega pull

aggrega pull resolves all of a Release’s dependencies and writes a lockfile that pins every dependency to an exact version and content digest. A subsequent aggrega build uses what the lockfile pins, verifies it, and halts naming anything it needs that is not pinned there — so builds are reproducible and offline-capable.

Everything a build consumes is pinned at this one moment. The catalog entities, the source artifacts a Recipe points a provider at, and the remote documents a provider asks for while it renders are resolved by the same command and recorded in the same lockfile write. aggrega pull is the step that touches the network; build does not. That is the whole of the rule, and the rest of this page is what follows from it.

What it does

aggrega pull resolves three kinds of dependency in one pass:

  • Catalog entities — the Components, Features, Recipes, FeatureRecipes, schema and mapping libraries, and Wasm plugins the Release references, resolved transitively (through extends:, implements:, aggregate:, Feature attachments, and library $import: / $ref: sites) and fetched from the registry when not already local.
  • Source artifacts — the remote source: that an individual Recipe or FeatureRecipe points a provider at: a Helm chart (OCI or classic HTTPS) or a Compose fragment over HTTPS. Each is fetched, cached, and pinned.
  • External inputs — the remote documents a provider asks the host for while it renders, such as a $ref in a chart’s values.schema.json that points at a URL. Each is fetched, stored under its content digest, and pinned.

Two of the three are read out of the documents you authored. The third is not: external inputs are found by rendering the Release, which is why this command renders one. Running the command needs none of that — How the resolution finds external inputs carries it in full, along with what the render costs, what happens when it cannot complete, and how a build that fills its own lockfile relates to it.

A catalog entity named without a registry is fetched through the workspace’s default_registry, and a repository path the default carries is where it is fetched from. With default_registry: ghcr.io/acme, core/api-server is fetched from ghcr.io/acme/component/core/api-server — where aggrega push publishes it through the same default — and its signature is looked for there. The path is location only: the signature a pull requires, the keys and identities it trusts, and the credential it presents are the ones kept for the host, so the registries entry for ghcr.io governs every path on that host. The lockfile records such an entity by its identity, version and digests, as it records one fetched from a host alone. The spelling of a path is set out in how a registry host is written.

It writes the result to <release-stem>.lock next to the Release. A workspace that attaches a plugin returning an accept-or-reject verdict also gets a second file in that directory — the plugin trust record.

A pull asked to pin writes one more kind of file. Beside each Recipe and FeatureRecipe in your catalog directories that imports an artifact file, points at a remote source: you wrote out in full, or reads a source: beside it, sits an entity.lock recording what that content digested to. Recording it is the entity author’s step, aggrega pin, and by default a pull does not do it: it holds each such entity’s lock to what the step would record, and halts where a pin is missing. aggrega pull --pin-sources, or a workspace that sets pin_sources_at_pull: true, runs the step instead — and then a pull’s effect reaches further than the directory the Release sits in, though the entity files you authored are never written to. The entity lock describes that file, and Previewing what a pull would write shows the whole set for your workspace before anything moves.

A pull refused because a reference resolved to nothing says where local entities are read from, wherever it runs. The refusal carries the workspace’s own account of the directories it read local entities from and what to change so the entity is read — the note Where local entities are read from shows — and it carries it from this command, from a build that resolves its dependencies first, from the pull tool of aggrega mcp and from an editor’s dependency resolution alike, because the resolution all of them run composes it. The pull tool’s refusal also names the condition’s short code and its descriptive code, as a terminal prints the short code at the head of the refusal. A file in those directories that declares an Aggrega apiVersion — a line starting, unindented, with apiVersion: and a value beginning aggrega.ai/ — and could not be loaded, one that does not parse as YAML, say, is named in the same refusal, among the catalog files skipped at load, with the parser’s own reason: such a file may be the one declaring the entity the reference names, and nothing can be read from it to say which entity it declares. A YAML file declaring another apiVersion, or none, is not an Aggrega document and is never named there.

The lockfile

The lockfile pins each dependency to its URI, resolved version, and content digest. It has sections for catalog entities, schema and mapping libraries (each carrying back-pointers to the Components and Features that consume it), Wasm plugins, source artifacts, external inputs (each keyed by URL and carrying the plugins that asked for it), and the Release files themselves. The file is written in a canonical, deterministic form.

An entity is recorded by what a publication of it carries. The digest in an entity’s row covers its document and every file it names beside it — a Recipe’s or FeatureRecipe’s local source:, each file an $import: names, the entity.lock beside it, each schema file a Component or Feature imports — the same set aggrega push publishes. Each file contributes its path and its bytes, and nothing else does: not how an archive was compressed, not a timestamp, not a permission bit, the execute bit included. An entity that names no file is recorded as that one document. So the same entity records the same digest whether it was read from your catalog directory or fetched from a registry, and a lockfile committed from one checkout verifies on another checkout of the same commit whatever its umask, and whether or not that checkout’s system records which files are executable. A chart edited under a Recipe, a file added to a source it declares and a changed entity.lock each change the digest; a script whose execute bit flipped, and a note beside the entity that nothing names, do not. The Aggregate and the Manifest the Release names are recorded the same way, each as its one document. A library is recorded by the digest of its bytes, which is its document wherever it is read from.

Every Recipe and FeatureRecipe the Manifest binds is a row, whichever tier binds it. A realization the Manifest’s name tier chooses for one instance or one attachment is acquired and recorded exactly as one its type tier chooses for every instance of a type, and its row’s referenced_from names the entry that binds it — manifest.spec.mappings.components.name.<instance> or manifest.spec.mappings.features.name.<attachment>. A build holds it to that row, so a lockfile that does not record it halts the build, naming the realization and that entry. See Flat URI mapping for the two tiers.

A connection’s attachments are dependencies exactly as a component’s own are. The Feature an attachment on a connection names — written on a component’s uses: entry in the Aggregate, or on a connection entry in the Release — is acquired and recorded like the Feature of an attachment written on the component itself, and its row’s referenced_from names the connection entry the author wrote, ending .uses.<socket>.<alias>.features.<slot>.type. The realization the Manifest binds to it is a row too, whether features.type binds it or features.name keyed by the attachment’s name, <alias>.<slot>. A build holds both to their rows: a lockfile without one halts the build naming the reference and the entry that asks for it, and a Feature whose content changed since the pull halts it naming both digests. See the Aggregate’s connection entry for the attachment itself.

A base a Component or Feature extends is a row, whether or not anything else names it. The pull follows each extends: to the end of its chain and records every base under its own kind, its row’s referenced_from naming the extending entity’s spec.extends — component(<name>:<version>).spec.extends. A build reads the base from that row, so a Manifest maps a wrapper’s own type and needs no line for its base. A base that no catalog directory, cache or registry holds is reported where the chain is merged — see An extends: chain cannot be assembled.

The Release is recorded by its content, not only by its name. Everything the Release asks for — which chart version a source resolves to, which components land in which boundary — is resolved from what the file holds, so release_documents records the digest of the Release and of each Release it extends, alongside release, which names it. Edit the Release after pulling and the next build halts before anything renders, naming the file you edited and telling you to pull again; a plain aggrega pull --release <release> records the edit while honouring every other pin. The digest covers the file’s bytes as they are, so a comment or whitespace change counts too, exactly as it does for the Aggregate and the Manifest. A file the Release imports through parameters is not recorded this way.

A pull looks for a deprecation marker on every artifact whose signature it checks, and says what it found. A marker whose own signature verifies against a signer the pull honors — the artifact’s own signer, or an identity in the registry’s trusted_deprecation_identities — is recorded, and announced with its severity and the signer of the marker. A marker the pull found and could not honor — unreadable, unsigned, signed by someone the policy does not trust, or carrying a signature that could not be checked — is reported as marker present but not honored, with the reason, and is not recorded. A lookup that could not finish — the pull could not open the artifact’s registry, or the listing of what is attached to it did not answer — is reported as marker lookup did not complete, with the reason, and records nothing, because the pull learned nothing about whether a marker exists. Under a registry whose own trust policy requires a signature for the artifact’s kind and is not advisory, either of those two halts the pull instead of being reported. An artifact carrying no marker produces no line, and where signature verification is switched off, for the workspace or for the artifact’s registry, no marker is looked for.

Commit <release-stem>.lock alongside the Release, the way you commit any pinned-dependency manifest. A lockfile diff shows reviewers exactly which dependency versions and digests changed; a library digest change names the consumers it affects.

What a given pull did — whether each entity was fetched fresh from a registry (fetched-fresh), reused a cache slot (cache-reuse), found in a local catalog (local), served from the copy inside the compiler binary (in-binary), or was external (external: the Release’s own Aggregate or Manifest, read from the file or entry the Release names rather than resolved as one of its dependencies; an Aggregate the pull fetched from a registry is fetched-fresh instead) — is a transient pull-event diagnostic printed to stdout by --detail, and it is never written to the lockfile. Which source served an entity depends on the pulling machine’s local state, so persisting it would break the lockfile’s byte-identity across machines. It reports what this pull did, which is unrecoverable afterward (a freshly-pulled entity is cached by the next run); for the post-pull resolution state of a Release’s dependencies, use aggrega inspect.

The entity lock

A Recipe or FeatureRecipe can depend on bytes outside its own document: a chart or fragment fetched from a remote source:, a file an artifacts entry — or an entry of a Recipe’s boundary.artifacts — brings in with $import, or the files of a source: that names a directory or a file beside it. What each of those digested to is recorded in a file named entity.lock, in the same directory as the entity file. The entity file you wrote is never written to; what was derived lives beside it. The entity lock schema describes the file field by field.

Who writes it. One step writes it: aggrega pin, which the entity’s author runs, needs no Release, and records every class of pin the lock holds. aggrega pull --pin-sources and aggrega push --pin-sources run that same step on the author’s behalf and write the same bytes. A pull that was not asked to pin writes no lock at all: over each Recipe and FeatureRecipe the Release builds from your catalog directories, it compares what the step would record with what the lock holds, and halts where a pin is missing or no longer matches its input, naming the entity, each input and its class, and aggrega pin. A local source’s files are held to their pins as one set: a lock that records none of them halts the pull, and so does a file added, changed or removed since the pin. The workspace key pin_sources_at_pull makes pinning every pull’s default, and --pin-sources=false restores the halt for one run. Pinning is an authoring duty, so a halt on a consumer’s first pull means the entity’s publisher never pinned it; the consumer’s remedy is that key rather than a hand edit of someone else’s directory. aggrega pin sets this out in full.

What it holds. Three lists, each row naming one input:

  • sourceDigests — one row for each remote source: whose coordinates you wrote out in full, with no template in its kind, url, chart, module_subdir, version or ref. The row carries the source’s kind and url, its chart or module_subdir where it has one, the version it resolved to — for a git source, the commit its ref named — and the content digest of the fetched archive, plus the manifest digest for a chart fetched over OCI.
  • artifactDigests — one row for each artifacts or boundary.artifacts entry supplied by a file imported with $import, naming the entry and the digest of the file’s bytes. An artifacts entry is named by its key, and a boundary.artifacts entry as boundary/<key>, so an entry of each block written under one key is pinned apart.
  • localSourceDigests — one row for each file a source: naming a directory or a file beside the entity contributes to what a publication of the entity carries, naming the file’s path beside the entity and the digest of its bytes. Nothing is fetched for such a source; its files are digested as they stand. A source written as a template contributes every file in the entity’s directory, so each of those has a row.

What it does not hold:

  • A remote source whose coordinates are filled in from a template — a version read from .infra, for instance. Which artifact it names is decided by each Release that uses the entity, so each version it resolves to is pinned in that Release’s lockfile, and nothing about it is written beside the entity.
  • An inline artifacts or boundary.artifacts entry, which is part of the entity file, and an entry taken from an ArtifactLibrary, whose content is pinned by the library version the lockfile records.

An entity with nothing to pin gets no entity.lock, and the step, run over an entity which no longer needs one, removes it.

Commit it beside the entity. Every Recipe and FeatureRecipe uses the same file name, and the directory it sits in says which entity it belongs to, so the lock travels with that directory. It carries no timestamp and its rows are kept in a fixed order, so the step over unchanged inputs leaves it byte-identical, and a diff over it names the source, the imported file or the local source’s file that moved. A directory holds one lock, so the step refuses a Recipe or FeatureRecipe with any other entity beside it — every kind has a directory of its own except Aggregate, Release and Manifest — and a pull asked to pin refuses such an entity before anything is resolved; One entity per directory sets the rule out. A pull that does not pin writes nothing beside an entity and does not judge its directory.

aggrega build holds your files to it. A build reads the lock and makes three comparisons:

  • Each imported file is digested again and compared with its row, a boundary.artifacts file exactly as an artifacts file. A file edited after it was pinned halts the build with [CATALOG_ERROR E0026], naming the artifact as its row names it, the imported file and both digests.
  • A local source’s files are digested again and compared with their rows, as one set, before the provider reads the source. A file edited, added or removed since the pin halts the build with E0305 under the component instance whose source it is, naming each such file and both digests; a file beside the entity that the source does not contribute is not compared. A lock that records no row for a local source leaves nothing to compare, as A local source no longer matches the pins recorded beside its Recipe describes.
  • Each source row is compared with the digest the Release’s lockfile records for the same source. A disagreement halts the build with [FETCH_ERROR E0135], naming the lock and both digests. The two files are written by two resolutions of the same source — the pin step’s and the pull’s — so they disagree when those resolutions got different bytes, or when one of the two files was edited. Different bytes under one version is what an upstream that re-published a version looks like.

A lockfile written before the change halts first, and a pull names the file. The lockfile records the entity by what it carries, and the lock and every file these comparisons read are part of that, so a build — or aggrega pull --verify — holding a lockfile written before an imported file, a local source’s file or the lock itself moved halts before any of the three comparisons runs: The lockfile no longer matches what the release resolves to, naming the entity and both digests. A plain aggrega pull then names the file, because it holds the lock to what the pin step would record and refuses the input whose pin no longer matches: An entity reads an input the lock beside it records no pin for.

Where the lockfile has no record of the entity’s own content, the three comparisons are what a build meets. A Recipe or FeatureRecipe the Manifest names by a reference that is also the name of a Component or Feature the Release reaches has no entry of its own: the lockfile’s entry for that reference records the Component or Feature, so nothing in the lockfile moves when the Recipe’s files do, and a build and a verifying pull report the moved file with the code above. The source-row comparison is also what a build meets when the lockfile’s source_artifacts entry is the record that changed while the lock beside the entity did not.

Answering the halt. If you changed the imported file on purpose, run aggrega pin on the entity: the step records the file’s new digest, and the next build accepts it. If you did not, restore the file. A local source that moved takes the same two answers: pin the entity again, or restore the files the halt names. For a source row that disagrees with the lockfile, restore entity.lock from version control, or run aggrega pin on the entity to rewrite it.

aggrega pull --verify checks it too. A verifying pull makes the same three comparisons over the locks beside the Recipes and FeatureRecipes the Release reaches in your catalog directories, reports every pin a build would refuse under the same code and in the same words, exits non-zero if there is one, and writes no lock.

Where no lock is compared. A Recipe or FeatureRecipe resolved from a registry rather than from one of your catalog directories has no lock a build reads; its sources are held to the Release’s lockfile alone. And a source written at a git ref: is recorded in the lock at the commit that ref resolved to, while a build looks for the source’s pin at the version the entity names, so that row is never compared — by a build or by a verifying pull. The lockfile still pins the commit, and every build verifies the cached archive against it.

The plugin trust record

Some plugins the workspace attaches never shape the rendered output. A plugins.governance attachment in an ir-verdict or render-verdict role, and every plugins.linter attachment, return an accept-or-reject verdict and nothing else — no bytes of theirs reach an artifact. So they are not part of what a build reproduces byte-for-byte, and the lockfile, which pins exactly that, is the wrong place for them.

Their identities go in a second committed file instead: plugins-trust.yaml, beside the lockfile. It carries one entry per such plugin, recording the plugin’s identity coordinate, the version selected for it, and the content digest of the resolved artifact — plus the signature pull verified for that artifact, where it verified one, and, when the publisher has deprecated that artifact since publishing it, the marker pull found and verified. The plugin trust record schema describes the file field by field.

Commit plugins-trust.yaml alongside the lockfile, for the reason you commit the lockfile: a record kept outside version control is one nobody can review and nothing can compare against. Committed, it is one shared statement of which plugin each of those attachments resolved to, and a diff over it names the identity that changed.

The file appears only when there is something to record. A workspace that attaches no verdict-returning plugin resolves no such identity, so pull writes no file and says nothing about one — an absence, not a missing file. When pull does create it, it names the file it created and tells you to commit it. A later pull adds an identity the record does not yet hold and leaves every identity already recorded exactly as it is.

Every change to this file is announced, and nothing else is. A pull that moves the record prints one line per entry that moved, naming the plugin and which change it was: an identity recorded for the first time, an identity adopted in place of the one held (naming both, so you can see what was swapped), a deprecation recorded against the artifact an entry already names, a deprecation cleared from one, a signature recorded against or cleared from one, or the entry dropped. The creation line above is separate and is about the file rather than about an entry, so a first resolution says both: this file is new and must be committed, and these are the identities it now holds.

A pull that leaves the record exactly as it was says nothing about it. So a line about this file means the committed file has moved and its diff is worth reading — which matters here more than it does for the lockfile. Everything the lockfile pins is also part of what a build reproduces byte-for-byte, so a change there has a second place to show up; a verdict plugin’s identity has none. This file is the only place a swapped gate is written down.

aggrega pull --dry-run announces none of this, because it changes nothing. It lists the record among the files it would write instead, as Previewing what a pull would write describes.

A deprecation is added to an entry the record already holds, and that is not the same as rewriting it. If a publisher deprecates a plugin you already trust, the next aggrega pull records the marker on that plugin’s existing entry — the coordinate, the version and the digest are untouched, because the artifact has not moved and nothing new is being adopted. So a plain pull can add a deprecation block, and only an explicit upgrade ever changes an identity. A marker is recorded only against the artifact the entry already names, and no pull chases one that has stopped being published: a recorded marker leaves only with the entry that carried it, which means either when that entry is dropped, or when an explicit upgrade re-resolves the plugin and finds no marker on the bytes the entry already records.

The verified signature is recorded on an entry the same way, and every pull answers it afresh. Pull verifies the signature of each of these plugins against its registry’s trust policy on every run — a plugin a registry serves is fetched by its version each time, since nothing pins it — and records what it verified on the plugin’s entry, again without touching the identity: the mode, the signer that matched, and the digest of the signature bundle it cached, the same signature a lockfile entry carries. Unlike a marker, the answer replaces what the entry held, and where pull verified no signature — the plugin carries none and none is required, or skip_signature_verification or an advisory registry admitted it — the entry records none. The signature bundle it verified is cached again too, and a cached copy that no longer matches its digest is rewritten. So an entry that lost its signature, an entry carrying a signature copied from another plugin’s, an entry whose cached signature bundle was removed or altered, or a record deleted or written before a signature was recorded, is repaired by the next plain aggrega pull. A build holds each such plugin to that fact: see The plugin trust record on the build page.

A resolved identity that disagrees with the recorded one halts the pull. A recorded entry names both a version and a digest, so either moving is the same event: the plugin that would run is not the plugin the record was reviewed for. The diagnostic names the plugin, what the record holds, and what this resolution reported, on both axes at once — and pull stops without touching the record, so the reviewed identity is still there to compare against. It halts on the version alone (a re-publish whose bytes did not change) exactly as it halts on the digest alone (a re-push at the same version).

aggrega pull --verify makes the same comparison. It writes none of the files a pull commits, so it adopts nothing; it reports whether those files still describe what a pull would resolve today, and the record is one of them. It holds each entry’s signature to the one the pull’s own verification of the plugin gives as well, and reports an entry whose signature a pull would record, replace or clear — and a plugin the record holds no entry for where a build refuses it for recording no signature — as It compares the recorded signatures, in both files describes.

To adopt a new identity, ask for it by name: aggrega pull --upgrade --release <release> <plugin>, naming the plugin as your .aggrega-config.yaml attachment names it, without any version suffix. That re-resolves that one plugin and rewrites its entry, leaving every other pinned dependency and every other recorded identity untouched — and it works even though the plugin has no lockfile pin, because a named target may also name one of those attachments. A bare aggrega pull --upgrade, which re-resolves every dependency, re-resolves and rewrites every recorded identity too. So does aggrega build --upgrade, which runs a bare full-refresh pull and has no way to name a single target.

To remove an identity, ask for that by name too. Detaching a plugin from .aggrega-config.yaml does not clear its entry, and that is deliberate: a plain aggrega pull never removes one. Run aggrega pull --upgrade --release <release> <plugin>, naming the plugin as the record names it — its identity coordinate, which is the string the halt below prints — and the entry is dropped, leaving every other pinned dependency and every other recorded identity untouched. A bare aggrega pull --upgrade drops every entry no verdict attachment names any more, in the same pass that re-resolves everything else.

Dropping the last entry leaves the file in place and empty rather than deleting it. An empty record holds nothing, so it pins nothing and halts nothing — the same as no record at all — and keeping the file means the removal shows up in its diff as a removal.

A record that does not satisfy its schema halts every command that reads it — a build, a release-scoped lint, and a pull, including a pull that has nothing of its own to record. An emptied record and a damaged one are deliberately different: emptying is how the last entry is removed, and an emptied record stays silent, while a file whose contents no longer parse is a fault rather than an empty record — reading it as empty would make truncating the file a way to switch the comparison off. Restore it from version control to get the reviewed identities back.

A plugin served from the copy inside the compiler binary is not recorded. Pull records what it acquired — fetched from a registry, or read from the cache — and nothing is acquired from the binary: those bytes are identified by the compiler version that carries them, so there is no resolution of their own to record. Attaching a plugin the binary already carries therefore produces no entry for it. That is the record staying about acquired artifacts, not a resolution that failed.

A build, a release-scoped lint and a release-scoped validation hold the workspace configuration to the record. Before any of those attachments runs, aggrega build, aggrega lint --release and aggrega validate --release — and the same operations reached through aggrega serve and aggrega mcp — compare the verdict attachments the configuration names against the entries the record holds. A plugin whose resolved artifact digest is not the recorded one is refused rather than run. A record entry that no configured verdict attachment accounts for halts the run: a gate that was reviewed and is now absent leaves output indistinguishable from output that gate approved, which is exactly what someone reading the output cannot see. The halt names the plugin and offers the two remedies that differ by what you meant — attach the plugin again if the removal was a mistake, or run the explicit upgrade above if it was intended — and it prints that upgrade ready to run. The reverse direction — an attachment the record does not yet hold — is the first sighting described above, and neither comparison halts on it; the signature requirement is the one hold an attachment with no entry does not escape. The same three surfaces hold each plugin they read from the cache to the signature its entry records, when they load it, as the build page describes for a build. The whole-catalog and single-entity lint scopes consult no record.

A validation is held to the record because it runs the same checks a build runs. aggrega validate --release reaches every check aggrega build reaches short of writing the artifacts, gate plugins included — that is what makes “this validates” mean the same as “this builds” — so the identity of the plugin it runs is compared against the record exactly as a build’s is. aggrega validate’s other scopes are not held to it: validating the whole catalog, a single entity, or a plugin binary does not read the workspace’s plugin attachments at all, so no verdict plugin runs in them and there is nothing for a record to hold.

Holding a configuration to the record establishes presence and identity, and nothing beyond them. It establishes that every gate the record names is still attached, and that each one runs from the artifact recorded for it. It does not establish that a gate which ran returned a verdict at all, and one case of that is caught nowhere: an attachment whose function names an export the plugin does declare, which is not the verdict export its socket reads, and whose output carries no top-level field outside the shape that socket expects — the empty object being the simplest — runs, returns nothing to reject on, and lets the build through. Its output is indistinguishable from an approving gate’s, and no comparison against the record can notice it, because nothing about the record is wrong: the plugin that ran is exactly the one recorded, and it simply ran nothing. Two neighbouring cases do halt, so the bound is not wider than it reads — a function naming an export the plugin does not declare is refused when the plugin is loaded, and an output carrying a top-level field the socket’s shape does not declare is refused rather than read as a verdict list that happens to be empty. So a recorded identity is not on its own sufficient for a gate to have judged anything.

The recorded digest governs the plugins the workspace resolves from the cache aggrega pull populates, and nothing it resolves another way. That is the resolution a verdict attachment normally takes — nothing pins it in the lockfile, so its bytes come from the cache, and that read is where the resolved digest is compared against the recorded one. A verdict plugin the workspace resolves some other way never reaches that read, and is governed by whatever governs the way it did resolve rather than by the record: bytes served from the copy inside the compiler binary are identified by the compiler version carrying them, a .wasm sitting beside its catalog entity is a file in your own catalog directory, an explicit filesystem path is the path you named, and a plugin carrying a lockfile pin is governed by that pin. The other half of holding a configuration to the record is not bounded that way: every entry the record holds must still be accounted for by a configured attachment, however that plugin resolves. So the record establishes that the gates it names are still attached whatever serves them, and it establishes the artifact identity of the ones served from the cache.

Honoring vs. updating

By default aggrega pull honors an existing lockfile: a dependency already pinned resolves to its exact pinned version (verified against its pinned digest), only references that are not yet pinned are resolved and added, and pins for references the Release no longer reaches are pruned. So a re-pull of an unchanged Release is a no-op — it reproduces the same lockfile byte-for-byte (including generated_at). Adding a new dependency, or pulling after a hand-edit removed a pin, resolves just that gap and leaves every other pin untouched.

A dependency a re-pull reads from the cache is recorded exactly as the pull that fetched it recorded it. Its row keeps the version, the content digest and the manifest_digest — the last taken from the manifest stored beside the content in the cache — along with the signature and deprecation that pull verified at the registry. None of that is looked up again while a build would accept the row, and --detail reports such a dependency as cache-reuse, so a re-pull whose dependencies are all cached, over a lockfile that records every signature the trust configuration requires and only signatures a build accepts, writes the same lockfile whether or not the registry can be reached.

A re-pull looks a signature up again exactly where a build would refuse the row, and there are two such rows.

  • A required signature the lockfile does not record. Where the trust configuration requires a signature for a dependency the cache serves and the lockfile row records none — the row was edited, the lockfile was written afresh over a cache an earlier pull filled, or the requirement was added after the pull that wrote the row — the re-pull asks that dependency’s registry for its signature, by the digest of the manifest stored beside it in the cache, exactly as it does for a dependency it fetches, and records the verified signature on the row. That row is the one a build refuses (No verified signature is recorded for an artifact that requires one), so pulling again is what clears that refusal. A registry that attaches no signature, or a signature the trust configuration does not accept, halts the re-pull as it halts a pull that fetched the dependency. The settings that let a pull admit a dependency with no signature leave such a row as it is and ask nothing about it: skip_signature_verification at the top level, the same switch on the registry’s own entry except for a kind the workspace-wide signing policy requires, and a registry marked advisory.
  • A recorded signature a build does not accept. Where the row records a signature whose cached signature bundle was removed or altered after the pull that cached it — or a signature copied from another row, whose bundle is intact but was made for another artifact — a build refuses the row whatever the signing requirement says (A cached signature bundle does not match the digest recorded for it, A recorded signature was made for a different artifact). So the re-pull asks that dependency’s registry about its signature again, whatever the requirement says, through the same verification a dependency it fetches gets: what that verifies replaces the row’s signature, and the bundle it names is cached again, a cached copy that no longer matches its digest rewritten — so the row and the cache hold what the pull that fetched the dependency left. A signature the trust configuration does not accept halts the re-pull as it halts a pull that fetched the dependency, and so does a registry attaching none where a signature is required. Where the verification records none — skip_signature_verification where it applies, which asks nothing, a registry attaching no signature where none is required, or an advisory registry where nothing verifies — the row’s signature is cleared, which a build admits under the same settings.

A row whose recorded signature a build accepts is not asked about again, and neither is a row recording none that nothing requires a signature for.

A dependency named without a registry, in a workspace that now names no default_registry, cannot be asked about. Its row was bound to a registry by the pull that recorded its signature, and with no default there is no registry to ask. Where such a row records a signature a build does not accept, the re-pull halts with the build’s own refusal, saying no registry is configured to ask about the row again, and leaves the lockfile as it was. Configuring the registry the dependency came from as default_registry and pulling again repairs it.

What that honoring governs is what a registry or the cache serves. An entity a local catalog directory supplies is resolved from that directory, at the version its file declares, and the entry the lockfile records for it is not consulted on the way. The lockfile still records such an entity, so you will see it there — but editing that entry by hand does not hold the entity at the version you wrote, and the next reconcile rewrites the entry to match the file. To change which version of a locally-supplied entity a Release resolves, edit the catalog file rather than the lockfile.

A pin names bytes, not a place, so a cache entry that no longer holds its pin is passed over rather than trusted. An entity edited in place — a new body under the same version — leaves the content cache holding the earlier body under that name and version. A catalog directory is read first, so an entity one still supplies is pinned from its file and the stale entry is never read. The render the pull runs to discover the Release’s external inputs reads each pin the way a build does, from the catalog directory holding the pinned bytes, and reports the entry it passed over with the notice aggrega build prints. Where no catalog directory supplies the entity and a registry is reachable, the pull fetches the pinned version again, rewrites the entry, and says so on standard error, naming the entry and both digests:

reuse: cache entry for <name>:<version> held <digest the entry held>, not the pinned <pinned digest>; refreshed from the registry (pin unchanged)

The fetched bytes are held to the pin as any fetch under a pin is, so a registry serving other bytes under that version halts the pull, as described below. Where no source holds the pinned bytes — no catalog directory supplies the entity, the cache entry holds other bytes, and no registry serves the pinned version or the run reaches none — the pull and aggrega pull --verify halt with E0135 — or E0133 where the cache entry’s manifest is not the one the lockfile pins — naming each source they read and what it held; where the run reached no registry, the halt also names the step that fetches the pinned version again.

To update pinned versions, run aggrega pull --upgrade --release <release> — it discards the existing pins and re-resolves all dependencies to the latest satisfying versions. Updating is the explicit act; the default never floats a pinned dependency. This mirrors the convention of npm ci / cargo / go build (the default realizes the lock; updating is opt-in), and it is what makes aggrega build’s automatic pull safe — build resolves exactly what the lockfile pins, never silently moving a version.

That bare form drops every recorded pin, so it asks for confirmation before doing anything. Answer it in advance with --yes for non-interactive use; with standard input not a terminal and no --yes, it refuses rather than waiting for an answer nobody can give. Naming targets (aggrega pull --upgrade --release <release> <uri>) holds every pin it did not name, so that form asks nothing. aggrega build --upgrade runs the bare form and is gated on the same terms.

If a pinned version’s bytes in the registry no longer match the digest the lockfile recorded (an immutability violation upstream), pull halts with an integrity error rather than silently adopting the changed bytes — run --upgrade to deliberately re-pin.

Checking a lockfile without writing it

aggrega pull --verify --release <release> answers one question: would running aggrega pull now change the lockfile, or the plugin trust record beside it? It performs the resolution a pull would perform, compares the lockfile and the record with it, and stops before anything a pull commits is written — the lockfile, the plugin trust record and every entity.lock are left as they are. It exits non-zero on a missing lockfile and on any difference, naming each one. Deprecation markers are not compared, as below describes. It is refused beside --upgrade, beside --dry-run, and beside --pin-sources whichever value that flag is given: a verify neither records a pin an entity.lock is missing nor halts on one, so the flag would change nothing.

It honors the recorded pins exactly as a pull does. A dependency the lockfile pins resolves at its pinned version and is checked against its pinned digest, and an entity a local catalog directory supplies is resolved from that directory, as Honoring vs. updating describes. So:

  • A reference whose registry has published a newer version since the pull is not drift. A pull would hold its pin, so the lockfile is still the one a pull would write; aggrega pull --upgrade is how the newer version is adopted.
  • A registry that now serves different bytes under a pinned version halts the verify with the integrity error that halts a pull, rather than reporting the change as drift.
  • A lockfile row edited by hand, an edited Release, and an entity edited in a local catalog directory are each reported, because each is a difference between the lockfile and what a pull resolves now.

It reads and fills the cache as a pull does. An entry the cache holds under its pin — a catalog entity, or a plugin’s .wasm — is read from there without asking a registry, which is what lets a verify run under the offline posture over a workspace a connected pull has filled. An entry the cache does not hold is fetched, as a pull fetches it, and one that no longer matches its pin is treated exactly as a pull treats it. So a verify may add to the cache, and it never moves a pin.

It compares the recorded signatures, in both files

The signature a pull verified for an artifact is part of what it writes: the signature on a lockfile entry, and on an entry of plugins-trust.yaml for a plugin attached at a verdict role. Once the pins agree, a verify holds every recorded signature to the one a pull would record now, and reports each one a pull would record where none is recorded, replace, or clear, under A recorded signature is not the one a pull would record. Every such entry, in either file, is named in the same run.

Which lockfile entries it looks up is the pull’s own choice. A re-pull asks a registry about an entry’s signature exactly where Honoring vs. updating describes, and a verify reads that same choice:

  • Two are reported without asking a registry, because a pull rewrites them whatever the registry answers: an entry the cache serves that records no signature where the trust configuration requires one — the pull records the artifact’s signature, or stops where none can be established — and an entry whose recorded signature was made for another artifact, which the pull replaces with the artifact’s own.
  • Every other entry a pull would look up again is asked about, because only the registry’s answer says whether the pull would change it: an entry whose bytes this verify fetched, and an entry whose cached signature bundle was removed, is unreadable or was altered. The verify asks the registry, as the pull would, and reports the entry where the answer records, replaces or clears its signature. The signature bundle it verified is cached as a pull caches it, so an entry whose cached bundle was removed, while its registry still serves the signature recorded, passes and leaves the cache repaired.

An entry whose recorded signature a build accepts, and an entry recording none that nothing requires a signature for, are not asked about, by a pull or by a verify.

The plugin trust record is held to the same pull. Every pull verifies the signature of each plugin attached at a verdict role at its registry, and so does a verify, which reports an entry whose signature that verification would record, replace or clear. A plugin the record holds no entry for is reported where a build refuses it for recording no signature, because a pull writes an entry carrying its signature and the build refuses the plugin until then. Any other is a first sighting, which a verify does not report, as it does not report any identity the record does not hold yet. Under the offline posture a verify asks no registry about these plugins, and Offline describes what it reports in its place.

Deprecation markers are not compared. A marker attached to an artifact after the pull is the registry’s state, and it moves without anything in the workspace changing; a verify failing on one would fail a check over files you did not touch. A recorded marker advises a build rather than stopping it for the same reason. So a pull may record a marker on an entry a verify passed.

Previewing what a pull would write

aggrega pull --dry-run --release <release> resolves the dependencies exactly as an ordinary pull does and then, instead of writing, prints what it would have written: one header naming each file’s path, followed by the content that file would hold.

aggrega pull --dry-run --release release.yaml

It names every file, not just the lockfile. The lockfile, the entity.lock beside each Recipe and FeatureRecipe whose recorded pins would move under --pin-sources, and the plugin trust record all appear in the same report, because a preview that showed only the lockfile would teach you that the lockfile is all that moves. A pull that would halt on an unpinned entity halts under --dry-run too, for the same reason: what a preview shows is what the pull would do. The files a pull would leave byte-for-byte as they are do not appear at all — a name in the report means that file is about to change. The last line counts them, and a workspace a pull would not change reports a count of zero.

Nothing on disk moves. No lockfile is written or created, no entity lock is written or removed, and no trust record is created or amended. Where a capability is served by more than one provider plugin and nothing has chosen between them, the run halts naming what to supply rather than offering to write the choice into your configuration — a preview does not edit a config file on its way past.

The resolution itself still runs, so the cache still fills. Which external inputs a Release consumes is a product of rendering it, and a run that declined to resolve would have nothing to report, so --dry-run fetches and stores exactly as a pull does. The content under .aggrega/cache is read only through the pins a lockfile records, so filling it changes nothing a build resolves; what a dry run shows is what a pull would write.

A bare --upgrade asks nothing under this flag. The confirmation exists because a full refresh drops every recorded pin, and a preview drops none — so aggrega pull --dry-run --upgrade --release <release> is the form to reach for when what you want to know is what a refresh would cost you, and it runs without an answer.

It is not accepted with --verify, which already writes none of those files. The pair would leave the flag doing nothing while reading as though it had done something, so it is refused rather than ignored.

One thing a pinning preview cannot always show in full, and it says so when it happens. A pull asked to pin rewrites the entity.lock beside each Recipe and FeatureRecipe and then renders the Release to discover its external inputs; a preview leaves those locks alone, so where a pin recorded there has gone stale — you edited an imported file since it was pinned, for instance — that render is held to the stale digest the unwritten lock still records, and stops. Everything else in the report is exactly what a pull would write; only the reported lockfile’s external-input pins are short. The run says so on both its output and its diagnostics rather than handing you a lockfile that looks complete. A first resolution of a workspace is unaffected, because there is no recorded digest yet for anything to be stale against.

The composition these pins describe

A lockfile pins what a build of this Release will consume, so the resolution draws the composition that build draws: it resolves the documents, applies the transformations the workspace’s attachments declare, and puts the result through the checks a build makes over a finished graph. Two things follow from that, and both arrive at the pass that writes the lockfile rather than at the first build to read it.

A composition those checks reject halts the pull. A uses: edge whose target does not satisfy its socket’s selector:, a Feature attached to a component its appliesTo: does not admit, and every other violation those checks report stop this command, with the diagnostic a build of the same documents prints — and the halt names every finding in one run rather than the first, so one pass hands you the whole list to correct. It happens before the write, so <release-stem>.lock and plugins-trust.yaml are left exactly as they were and a Release that will not build is never recorded as one that resolved cleanly. What that does not cover is the attachments that return a verdict: no ir-verdict or render-verdict attachment runs here, so a rejecting verdict stops the build, release-scoped lint or release-scoped validation that dispatches it rather than this command.

An attachment in a role that shapes the graph runs during that pass, so a plugin that will not resolve halts the pull. A label-transform attachment decides node labels before anything is matched against them, and an annotation-transform attachment injects annotations that expand into Feature attachments — both change what the graph holds, so drawing the graph means dispatching them, and dispatching them means holding each plugin’s own bytes. A plugin whose bytes this pass cannot obtain halts the run, naming the plugin and what could not be found for it — the same refusal a build of the same workspace makes when it cannot obtain them. What it dispatches is the attachment list this pass has just resolved, carrying the settings and definition files the lockfile records for a later build to reconstruct, so both passes run the same attachment against the same input.

A Plugin a pipeline step names that nothing holds halts the pull as well. Each Plugin a Recipe’s or FeatureRecipe’s pipeline names is resolved with the Release’s other dependencies — from a catalog directory, the copy inside the compiler binary, the content cache, or the registry — and one that none of them holds is one a build could not load either. So the pull stops before it writes anything, naming the Plugin and the Recipe or FeatureRecipe whose pipeline names it, with the condition a build raises when it reaches that step (A plugin reference is not a Plugin entity). That holds for every Recipe and FeatureRecipe the Manifest binds, including one nothing in this Release attaches, because each is resolved and pinned whether or not it renders. Publish the Plugin, or place it in a catalog directory with its built .wasm beside it, and pull again.

That halt and a degraded run are different outcomes, deliberately. A render that cannot finish — the one How the resolution finds external inputs and Offline both describe — leaves every dependency pin correct, so the pins are written and the shortfall is reported. A composition the checks reject is not a shortfall in what was resolved: it is a Release that will not build, so nothing is pinned for it and the run stops.

The cache

Pulled content is stored under .aggrega/cache, split into an entities/ subtree for catalog entities, a source-artifacts/ subtree for source artifacts, and an inputs/ subtree for the external inputs a render consumes. A catalog entity’s slot is named by its kind, its coordinate and its version — so a Component and a Recipe that share a coordinate and a version keep two slots — a source artifact’s by where it was fetched from, its version and a prefix of its content digest, and an external input’s by its content digest; what a build reads from any of them is checked against what the lockfile records. Identical version pins therefore share one slot across Releases. Each source-artifact slot holds the authoritative archive, a regenerated extraction, and a small metadata file; the extraction is regenerated on every read, so build output depends on the archive and the lockfile, not on the state of the extracted files.

Every name the cache derives from a value is one Windows, Linux and macOS all accept. A coordinate, a version, a registry host or a digest carries characters a file name cannot: the / between a coordinate’s parts, the : before a version, inside sha256: and before a registry’s port. So each value — a kind, a coordinate, a version, a registry host or a digest — is spelled before it becomes a directory or file name — a lowercase letter, a digit, ., _ and - are written as they are, and every other character is written as an escape opening with +. The Component core/devtool/adminer:1.0.0 at version 1.0.0 is the slot entities/+zx000043omponent/core+zsdevtool+zsadminer+zx00003a1.0.0/1.0.0/, and a slot named by a content digest is sha256+zx00003a<hex>. An uppercase letter is escaped too, so two coordinates differing only in letter case keep two slots on a file system that ignores case; a name Windows reserves for a device, such as con, has its first letter escaped; and no name ends in a full stop. Two different values never share a name, and one value has the same name on every machine. aggrega cache status lists each entry by the values its names were spelled from — a catalog entity by its coordinate, version and kind — rather than by the spelled names.

An entry of an archive keeps the name its publisher gave it, so on Windows one Windows cannot hold is refused. The files a source artifact or a catalog entity’s archive carries are laid out under the names the archive gives them, not spelled by the cache. Where the extraction runs on Windows, an entry holding a part Windows cannot hold as written — a name it reserves for a device, such as NUL or aux, in any letter case and with or without an extension, or a part ending in a full stop or a space — is refused with E0340, naming the entry, and nothing of that archive is laid out. On Linux and macOS such an entry is laid out as it is named. An entry climbing out of the extraction’s directory is refused on every machine.

A catalog entity’s slot is an entry only with its manifest. The slot holds the content a registry served and, beside it, the manifest that describes that content. A slot holding the content alone — a fetch that stopped between the two writes, or a file placed there by hand — is not an entry: a pull, and a verifying pull, ask the entity’s registry for it again where one can be reached, while a build, which never fetches, treats the entity as missing, as a pull does when no registry can be reached.

What reaches the cache is held to two things: the shape the entity’s own schema describes, and the place the cache names for it. A body fetched from a registry is put through the schema of its kind — the same check that reads it back — before it is cached, so a published entity or library the registry serves that its own schema refuses halts the pull, naming what was fetched, rather than being cached and met as a fault later. And a value a cache location is built from that would place a cached file somewhere other than the place the value names — a version that is a path rather than a version, a source url path or module_subdir that climbs above its place — is refused where the location is built, naming the offending value. A value written into a Recipe or a FeatureRecipe you author is held the same way at the moment the cache location is built from it — and a git source’s module_subdir earlier, before the repository is fetched, as below.

A git repository is archived from its own checkout. For a git-repository source the pull checks the repository out at the commit it pins and archives the directory module_subdir names, or the whole repository. A module_subdir that climbs above the repository as written — ../shared, or ..\shared — is refused before the repository is fetched, with E0307 quoting the value, so nothing beside the checkout is read. A symbolic link the repository commits is archived as the file or directory it points to where that lies inside the repository — module_subdir itself may be such a link. One leading out of the repository halts the pull with E0321, naming the link and where it leads, and nothing is cached, so a repository you pull from cannot have the pull copy a file of your machine into the artifact. The checkout is removed once the pull stops, so the message names the link by its place in the repository, and the repository and the revision the source names, rather than a directory that no longer exists. The link is the repository’s to change. The workspace boundary states the rule this applies.

The cache is anchored to the workspace rather than to the directory you ran the command from, so one workspace has one cache and a pull run from a subdirectory fills the same store a build run from the root reads.

A pull where no workspace was found and none was named is refused before anything is fetched. When nothing names a root and discovery anchors nothing — from the folder you run it in, or, for a Release named by an absolute path, from that Release’s own folder — the folder would be the root, and a cache written beneath it would make it a workspace. So the pull stops, writes no lockfile and no cache, and names the folder and the two ways out: name your workspace with --workspace-root or AGGREGA_WORKSPACE_ROOT, or give that folder a .aggrega-config.yaml carrying a workspace: block. The pull tool of aggrega mcp, called with no workspace_root on a server launched with no root, is refused the same way; Configuration lists the other commands this holds for.

Building where the network cannot be reached

Because this command is the only step that reaches out, one connected run is enough to make every later build local. That run writes the lockfile and fills the workspace cache with the bytes those pins name, and a build then needs nothing beyond them.

Three things travel to the disconnected machine:

  • The Release and its lockfile. Commit <release-stem>.lock beside the Release; it is what tells the build which version and digest every dependency resolved to.
  • plugins-trust.yaml, where the workspace attaches a verdict-returning plugin. A build compares the verdict attachments its configuration names against that record before any of them runs, so carrying the record is what holds the disconnected build to the identities that were reviewed and to the signatures pull verified for them. Commit it beside the lockfile, as The plugin trust record describes.
  • The cache directory. The entities, the source artifacts and the pinned inputs all live under it, and anything a local catalog_dirs directory does not supply is read from there.

Build on the disconnected machine as usual. Setting the offline posture there is worth doing even though a build over a filled lockfile reads its closure from the cache: it turns a would-be network reach into an immediate refusal naming the posture, rather than a connection attempt that has to time out first. Anything the cache does not hold, and any external input the lockfile does not pin, halts the build naming what is missing and the resolution that would pin it — nothing is fetched quietly to fill the gap.

An airgapped machine and an offline workspace are different claims, and the difference is worth keeping. A machine behind an air gap may hold a local copy of a registry, or a catalog_dirs catalog carrying everything it needs, in which case an ordinary pull on that machine is satisfiable without reaching out at all. The offline posture describes what a command may reach for, not what the machine holds; Offline sets out what it refuses and what it leaves alone.

Offline

Under the offline posture — the top-level offline key in a configuration file, AGGREGA_OFFLINE in the environment, or --offline on the command line — aggrega pull refuses network access. The refusal happens before any connection is attempted rather than as a timeout partway through a fetch, so an offline pull reaches no registry and no remote source. Where a committed file or an exported variable set the posture and you want past it for one command, --offline=false allows the network for that run alone.

--upgrade is refused outright under the posture, and it is the one option here that is. A full refresh floats every dependency to the highest version a registry currently offers, so it needs to ask a registry what it currently serves. An ordinary pull does not: it honours the pins it already records, resolves only what has none, and is therefore satisfiable from what the machine holds. The refusal says which of the three places set the posture and how to allow the network for one run.

Resolution then draws only on what the machine already holds: the catalog_dirs search stack and the cache under .aggrega/cache. Against a catalog and cache that satisfy every reference, an offline pull completes normally and writes an ordinary lockfile. The lockfile records each dependency’s URI, resolved version and digest, and never which of those places served the bytes — so an offline pull and an online pull that resolve the same versions write the same lockfile.

A dependency an offline pull cannot satisfy locally halts it. The entry is never skipped:

  • A catalog entity that resolves nowhere halts the pull, naming the reference and where it was referenced from, so both the missing dependency and the thing that asked for it are named.
  • A remote source: halts the pull, naming the source and telling you either to allow network access or to populate the cache from a connected environment.
  • A dependency the cache holds whose required signature the lockfile does not record, or whose recorded signature a build does not accept, halts the pull with the offline refusal, naming the dependency: recording the signature means asking its registry, as Honoring vs. updating describes. Allowing the network for that one run records it. A recorded signature a build accepts is not looked up again, so it does not stop an offline pull.

An external input is the one that does not halt, and it says so instead. The render that finds them cannot fetch what is not already stored, so an offline pull over a Release with an unpinned external input completes, writes every dependency pin it resolved, and reports three things: that the render did not finish, what it did pin, and that a build of this Release will halt naming the URL. The dependency pins it wrote are correct — nothing about them depended on the render — so they are kept rather than thrown away for a reader to reproduce.

That is deliberate rather than a gap, and there is no switch for it. A pull that discarded correct work would cost you the part that succeeded; a pull that stayed quiet would hand you a lockfile that looks complete and is not. Saying so is the only outcome that leaves you able to act: run the pull again from a connected environment, or from one whose cache already holds the content, and the same command pins it.

So an offline pull is a refusal to touch the network rather than a reduced result for everything a document names, and for external inputs it is a completed resolution that tells you what it could not reach. A lockfile that exists is one whose dependency resolution completed; whether its external inputs are complete is what the pull’s own output tells you, and what a build then holds it to.

--verify under the offline posture covers less, and reports that it does. Asking where a recorded source ref points today means reaching its remote, which the offline posture refuses. So an offline --verify checks the pinned dependencies and skips that axis, and it prints a line saying so rather than reporting a match it never established. A recorded signature only its registry can confirm — on a lockfile entry whose cached signature bundle was removed or altered — is skipped the same way, on a line naming each such entry:

verify: offline, so the signature the lockfile records for "<reference>" was not checked at its registry, which alone can say whether a pull would record it again; this verify does not cover it

A recorded signature a pull would rewrite whatever the registry answered is still reported offline, because no answer is needed to know it, as It compares the recorded signatures, in both files describes.

A plugin attached at a verdict role that a registry serves is where an offline verify and an offline pull part. Such a plugin is never pinned in the lockfile, so every pull resolves its .wasm from its registry, and an offline pull over a workspace attaching one stops there, naming the plugin as one whose .wasm it could not resolve — even where the content cache holds it, and whether or not that registry is marked advisory or skips signature verification. An offline verify asks the registry nothing about the plugin instead: it reads the plugin from the content cache, as a build reads it, and stops where the cache does not hold its .wasm or holds one that no longer matches the digest its published manifest names. It still holds the plugin’s identity to the plugin trust record and re-checks its host functions against that .wasm, and it halts where either disagrees, exactly as a connected verify does. It reports the plugin where a pull rewrites its entry whatever the registry answers, which is where a build refuses the plugin over its entry: for recording no signature, because its entry records none or the record holds no entry for it, or because the signature its entry records was made for another artifact, which the pull replaces with the plugin’s own. Every other entry — one whose signature a build accepts, and one whose cached signature bundle was removed or altered — it names on a line saying its signature was not checked, and reports nothing about that signature:

verify: offline, so the signature of "<plugin>" was not checked at its registry, which alone can say whether a pull would record the same signature on its entry in the plugin trust record; this verify does not cover it

So an offline verify passes over an entry whose signature a connected pull would replace or clear — one whose signer was edited by hand, say, or one its registry no longer attaches — with that line the only thing saying so. An air-gapped verify stays available; what it does not tell you is whether a ref has moved since, or whether a skipped signature would be recorded again. A check that reads the exit code alone covers those only when the verify runs connected.

Integration with aggrega build

  • Verification. aggrega build verifies every resolved dependency against the lockfile and halts on drift: an entity, a library or a plugin whose content no longer matches its pin, a reference the Release now reaches that the lockfile does not pin or one it pins that the Release no longer reaches, and a Release file edited since the pull. Run aggrega pull --release <release>, the command the halt prints, to clear it: the pull resolves the Release as it now stands, rewrites the pins that moved and holds every other one, so nothing floats that you did not change. Where what moved is a file under a Recipe’s local source, the pull first names aggrega pin for that entity, as The entity lock describes. A lockfile this command has just written passes that check, because the command runs the same check before writing it; a build that halts on drift straight after a pull was given different inputs from the pull — a --catalog directory passed to one and not the other, or a workspace configuration edited between them — so run the two over the same ones. aggrega validate --release and every aggrega inspect selection that resolves a Release hold the lockfile to the same check and refuse with the same halt, so neither passes over a lockfile a build refuses.
  • Auto-pull. If the lockfile is missing and auto_pull is true, aggrega build runs the pull first automatically. If auto_pull is false, which is its default, the build halts and asks you to pull. The pull a build runs follows pin_sources_at_pull, so over an unpinned entity it halts exactly as a pull does. The pull step a build runs is the same one this page describes, so a build that fills an existing lockfile halts on a moved source ref exactly as aggrega pull does — see Determinism and integrity.
  • Offline. Under the offline posture, aggrega build uses only what the machine already holds, and refuses network access before any connection is attempted. A reference whose content the cache does not hold halts the build rather than failing partway through a fetch, and a build with no lockfile that is not asked to fill one halts naming the pull that would fill it, exactly as it does online. --auto-pull is not refused: the fill it asks for is the pull this page describes, so over catalog entities already cached or present in a local catalog it writes the lockfile without reaching a registry — a Recipe whose chart is fetched from a remote source is resolved again, so offline it halts even where the cache holds that chart — and a reference neither holds — or a cached one whose required signature the lockfile does not record, or whose recorded signature a build does not accept — halts it with the pull’s own refusal naming that reference. --upgrade is refused, for the reason Offline gives.
  • Catalog search. Pull honors catalog_dirs from .aggrega-config.yaml even when no --catalog is given — and a Release’s own directories where the configuration gives it some under workspace.releases — and resolves the same first-win search stack aggrega build does, so the dependencies it pins match what build searches. A listed directory that is not a directory — nothing exists there, say — is refused by both commands before anything is resolved or written, naming the entry and the configuration file and line listing it, as Where local entities are read from shows.

How the resolution finds external inputs

Nothing in this section changes the rule above — there is still one moment at which anything is pinned, and it is this command. What it describes is how the command reaches the third of the three kinds, which matters when you are wiring the resolution into a pipeline, reading a run that degraded, or reasoning about why this command renders at all.

A catalog entity and a source artifact are each named in a document; an external input is not. Resolving the first two is a matter of reading what you authored. An external input is named by a provider, part-way through a render, and which URLs it names follows from the values being rendered — a values entry that is absent leaves a whole subtree of a chart’s schema uncompiled and every remote reference in that subtree unrequested. No read of the Release can enumerate the set.

So the command does two things in one pass: it resolves and pins the closure the documents name, then renders that closure to see which remote documents the providers ask for. The rendered artifacts are dropped and the pins are kept. Both are internal to the one command, and neither is a second moment at which something might be pinned — there is one lockfile write, and it carries every pin.

Two consequences are worth knowing before wiring the resolution into an automated pipeline as a cheap step. It costs more than a resolution that only reads documents, because it renders. And it can fail for a reason a document-only resolution could not: a provider that cannot render this Release. When that happens the dependency pins are still written, because nothing about them depended on the render, and the diagnostic names the stage that stopped, what was pinned, and that a build will halt naming the unpinned URL. The run is not lost, and Offline shows the same outcome reached a different way.

The render also holds the lockfile to the comparison a build applies, before anything is written. It runs the build’s own sequence, so it compares the lockfile this command is about to write against what a build of the same Release resolves to, exactly as a build compares a lockfile it finds on disk. A lockfile that comparison refuses is not written — nor is anything else the command would have written after it — and the command halts saying that the resolution and the build disagree about what the Release depends on, followed by each entry the comparison named. Nothing in your files can cause that, and resolving again would reach the same disagreement, so report it with the Release rather than retrying. It is the one render failure that stops the write, and it is why a build of the same Release, over the same inputs, does not report drift over a lockfile this command wrote.

There is no switch to skip the render. One would preserve as an option exactly the surprise a single moment removes: a Release that resolves cleanly while an input its render needs is left unpinned, found only at build time.

--auto-pull folds this same resolution into a build, and the build renders once. The fill’s render is the one that finds and pins the external inputs, and the build presents that render rather than performing a second one, so a one-command build costs the same render an ordinary build over a filled lockfile costs. aggrega build sets out which of a build’s render flags reach it.

The set follows from the Release’s parameters, which is how component pins already behave. Editing a Release’s parameters between the resolution and the build is an edit to the Release, so the build halts at the drift comparison naming the file, before any render could request a URL that is not pinned; the remedy is this command. Parameters imported from a separate file are not recorded by content, so editing that file instead reaches the render, which halts naming the unpinned URL — with the remedy naming this command too.

Determinism and integrity

A Recipe’s source: may template its version against the Release’s resolved values and infra (and over locals defined on the same); these resolve at pull time and the result is pinned. The pull evaluates only the locals: entries the source: fields read, and the entries those read in turn, with Aggrega’s own template helpers alone: an entry the source reads that calls a Sprig function halts the pull naming the entry, the field and the function, while an entry no source: field reads is left to the build, which evaluates and checks it when the Recipe renders — see Resolving a source: coordinate registers a narrower function set. A mutable Git tag or branch is pinned to the concrete commit it points at, and the ref you authored is recorded beside it. At build time the cached archive’s digest is re-verified against the lockfile, so a tampered cache is caught.

A recorded ref is held to the commit it pinned. The ref is recorded because later runs ask it again, not for readability — a build asks which artifact it names, and a pull asks whether it still points where it did. A pull that is not an upgrade re-asks each recorded ref where it points, and a ref that has moved at its remote halts the run — naming the artifact, the ref, the commit the lockfile pins and the commit it resolves to now — rather than adopting the move. Run aggrega pull --upgrade --release <release> to adopt it. A targeted upgrade, which names entity URIs, does not: a source reference is not an entity you can name, so a targeted run holds it exactly as a plain pull does.

That check is the one thing the build-time digest re-verify cannot do for you. A pull that adopted a moved ref would rewrite the fetched bytes and the recorded digest in the same act, so the two values a build compares would have moved together and agreed — and you would be building different source content than the lockfile was reviewed against, with nothing reporting it.

Only a ref the lockfile records is held this way, and a ref is recorded whenever you author one. A Recipe that names its source by version: alone has no ref, so there is nothing for a later run to re-ask — which is the right answer, because a version you wrote yourself cannot move under you. The lockfile reference states what is recorded.

Write the ref, not the commit. A build finds a git-sourced artifact by the ref you authored, matched against the ref the lockfile recorded, so ref: v1.2.3 builds against the commit that tag was pinned at and the commit never has to appear in your Recipe. Naming a mutable tag in version: instead does not work and is not meant to: version: is matched as written, and for a git source the lockfile pins a commit.

The lockfile pins content fetched from registries and remote sources, and records the digest of each entity it resolves from your catalog directories — over the entity file and every file it names beside it, as The lockfile describes — and of each Release file the resolution read. The files of a source beginning with ./ or ../, and an artifact file an entity imports, are also pinned one by one in the lock beside that entity, as The entity lock describes, which is what names the one that moved; the integrity of the rest of your workspace between builds is the responsibility of the source-control system. See byte-identical output for the scope of the determinism guarantee.

Authentication

Registry credentials are read from the Docker credential configuration alone: config.json in the directory DOCKER_CONFIG names, or ~/.docker/config.json when that variable is unset, together with any credential helper or OS keychain the file delegates to through credsStore or credHelpers. aggrega login <registry> writes a credential there, and so does docker login <registry>; run either before aggrega pull for a private OCI catalog or chart registry. The files podman login and helm registry login write are not read.

A credential configuration that cannot be read is reported without what it holds. Where config.json is not valid JSON, an entry’s auth value is not a base64-encoded user and password joined by a colon, or a credential helper the file names cannot answer, reaching the registry fails with a message naming the registry and the credential file, never what the file or the entry holds. aggrega login and aggrega logout report a config.json that is not valid JSON the same way, and change nothing in it. Correct the file; an entry that cannot be read can also be replaced with aggrega login <registry>.

A classic Helm chart repository or chart archive (helm-https-chart), a compose fragment (compose-https-fragment) and a Git repository reached over HTTP or HTTPS (git-repository) authenticate with the netrc file, the per-user credential file curl and Git also read. It is the only credential store these three kinds read: ~/.config/helm/repositories.yaml and Git credential helpers are not read. A Git repository reached over SSH authenticates through the SSH agent and reads no netrc file.

machine charts.example.com
login deploy-bot
password <token>

Which file is read. The file the NETRC environment variable names, when it is set. Otherwise .netrc in your home directory; on Windows, _netrc in %USERPROFILE% when that file exists, and .netrc there when it does not. A missing file holds no credentials and is not an error. A file that exists and cannot be read, or does not follow the netrc format, stops the command with E0360, naming the file — and, for a format fault, the line — but never what the file holds: The netrc file cannot be read. On Linux and macOS, a netrc file that other users of the machine can read draws one warning naming it; make it readable by you alone (chmod 600).

Which entry answers a request. Each request is looked up by its host — the host name without the port, ignoring letter case — and is answered by the first machine entry naming that host, or by the default entry when none does. The entry’s login and password are sent as HTTP basic credentials, over http and https alike; an entry missing either sends nothing. A repository whose index places its charts on another host is answered per request: the index request takes the repository host’s entry, and the chart request the chart host’s. A request that goes without a credential must be readable anonymously, and a server that answers 401 or 403 stops the pull as an unauthorized fetch, whose remedy names the entry to add and the file it was looked for in.

The credential is written nowhere. It is read when a fetch runs and sent with the request: the lockfile, the entity.lock beside the Recipe, the source cache and every message carry the source’s URL as you wrote it.

A source URL carries no credential. A Recipe or FeatureRecipe whose source url writes a user before its host — https://user:token@charts.example.com/…, or a token written alone as https://token@charts.example.com/… — is refused with E0361 as the document is read, before anything is fetched: validating the Recipe refuses it, and so does every pull, pin and build that reaches it. The message names the host and never the credential: A source URL carries a credential. Put the credential in a machine entry of the netrc file instead. Over SSH, a user written alone — ssh://git@github.com/… — names an account rather than a secret and is accepted, while a password written there is refused too.

The check reads only the part of the URL before the host. A token carried in a query string or a path — …/index.yaml?access_token=… — is not detected, so do not write one there: the URL is recorded as written in the lockfile, in the entity.lock and in the source cache, the names of the cache’s directories included.

Environment variables

The workspace settings pull reads can be overridden through the environment, above the committed config and below any flag: AGGREGA_OFFLINE (see Offline, and --offline for the flag above it), AGGREGA_CATALOG_DIRS (OS-path-list separated; supply absolute paths), AGGREGA_ARTIFACT_CACHE_DIR, AGGREGA_DEFAULT_REGISTRY, and AGGREGA_SKIP_SIGNATURE_VERIFICATION (loud — wherever a pull would have checked a signature, it logs a warning that verification is globally disabled). See environment-variables.md for the full list and the precedence model.

See also

  • ./aggrega-build.md — verifies the lockfile and auto-pulls when configured.
  • ./aggrega-serve.md — the daemon carries this same resolution at aggrega/resolveDependencies, and inside aggrega/build for a request whose autoPull field asks for it, so an editor can run it without leaving the session; either way it runs only when a request names it, and writes the same lockfile this command does.
  • ./aggrega-push.md — publishes catalog entities to a registry.
  • ./aggrega-lint.md — the publish gate that precedes aggrega push.
  • ../../architecture/13-catalog-and-registry.md — the catalog, lockfile, and cache model in full.

Synopsis

aggrega pull [<uri>...] [flags]

Description

Resolve the Release's catalog and source dependencies into the cache and write the per-Release lockfile.
By default, pull reconciles the lockfile against the current dependency resolution while honoring
the pins it already records. That pin discipline governs what a registry or the content cache
serves: such an entity is fetched at its pinned version and verified against its pinned digest,
and if the registry no longer serves the pinned bytes, pull halts rather than silently re-pinning.
An entity a local catalog directory supplies is resolved from that directory instead, at the
version its file declares, and its recorded pin is not consulted — so editing a pin by hand does
not hold a locally-supplied entity at that version, and the reconcile rewrites the entry to match
the file. A reference with no pin — newly added, or removed from the lockfile by hand — is
resolved fresh and added. Entities no longer among the resolved dependencies are pruned.
Re-running pull on an unchanged dependency set is a no-op.
Use --upgrade with no positional arguments to discard the existing lockfile and re-resolve
every entity from current registry state, floating each dependency to the highest available
version. That form drops every recorded pin, so it asks for confirmation first; --yes answers in
advance, and on a non-interactive stdin it refuses rather than waiting for an answer nobody can
give. Pass one or more entity URIs after --upgrade to upgrade only those: each named pin
is dropped and re-resolved fresh while every other pin — and the recorded external inputs —
is held unchanged. A named target may also be a plugin that returns an accept-or-reject verdict;
such a plugin carries no lockfile pin, and its identity is recorded beside the lockfile instead.
Naming one the workspace still attaches adopts the identity it resolves to. Naming one the
workspace no longer attaches drops its recorded identity — the one way to clear an entry that
outlived the attachment it was recorded for. A bare --upgrade does both for every plugin at once.
A URI given without --upgrade is a usage error.
Each Recipe and FeatureRecipe this Release builds from one of your catalog directories carries
the pins for its own inputs in the entity.lock beside it: a remote source: written out in full,
a file an artifacts entry imports, and each file of a local source:. Recording them is the
entity author's step, aggrega pin.
By default pull records none of them, and halts on an entity whose lock is missing any, naming
the entity, each input and its class, and the command that records them. A local source's files
are held to their pins as one set: a file added, changed or removed since the pin halts the pull
the same way.
Pass --pin-sources, or set pin_sources_at_pull in the workspace configuration, to have pull run
that same step instead; --pin-sources=false restores the halt for one run.
Which files of a local source directory belong to its entity was decided when the entity was
pinned, by the ignore rules of the plugin that served its capability for the author, and its
entity.lock records that decision. Where the plugin this workspace binds for that capability
declares different rules, pull prints a warning naming both plugins and the difference, and
carries on: the entity's files are the ones its recorded rules kept.

Flags

FlagDefaultDescription
--catalog[]Catalog directory; repeatable. Each —catalog <dir> is prepended to the catalog search stack (first match wins): the workspace catalog_dirs, or, for a Release the workspace configuration gives directories of its own under workspace.releases, that Release’s; the stack ends with the directory named catalog at the workspace root when there is one. A catalog_dirs list written empty reads no local catalog at all.
--detailfalsePrint, per resolved entity, what this pull did — fetched fresh from a registry, reused a cache slot, found in a local catalog, served from inside the compiler binary, or external (the Release’s own Aggregate or Manifest, read from the file or entry the Release names). Stdout only; not written to the lockfile
--dry-runfalseResolve the dependencies and print what this pull would write instead of writing it: each file’s path and the content it would hold go to stdout, and the lockfile, the entity.lock beside every Recipe and FeatureRecipe whose recorded pins would move under —pin-sources, and the plugin trust record are all left untouched. Only the files that would actually change are named. The resolution itself runs exactly as it would otherwise, so the content cache still fills, a pull that would halt on an unpinned entity halts here too, and a bare —upgrade asks nothing because it drops no pin — what a dry run shows is what a pull would write. Not accepted with —verify, which already writes none of them
--include-prereleasefalseNot yet implemented: accepted and ignored, so a script that passes it keeps working when it starts having an effect
--pin-sourcesfalseRun the entity author’s pin step over the Recipes and FeatureRecipes this Release builds, recording in the entity.lock beside each the pin for every input it reads — a remote source: written out in full, a file an artifacts entry imports, and each file of a local source — instead of halting on an entity whose lock does not record them. The same step as aggrega pin, writing the same bytes. It writes beside the entity, so it runs only where the entity has a writable home: a document in one of your catalog directories. An entity resolved from the cache has none and is never pinned. Overrides the workspace’s pin_sources_at_pull in both directions: —pin-sources pins for this run and —pin-sources=false halts for this run, whatever the setting says
--progressfalseForce the pull-progress surface on even when stderr is not a terminal, printing one plain line per step as it completes, with its time. The default is auto: the interactive phase checklist is shown only when stderr is a terminal that interprets escape sequences, a terminal that does not gets the same plain lines, and redirected or piped output gets none
--quietfalseSilence the pull-progress surface on stderr. Does not affect stdout. Takes precedence over —progress
--release—Path to Release YAML file (required). A relative path resolves against the directory you run the command in, not against the workspace root. Where that directory is in no workspace and no root is named, an absolute path finds the workspace from the Release’s own folder
--upgradefalseRe-resolve dependencies from current registry state, floating each to the highest available version. Bare (no positional URIs) discards the lockfile and re-resolves every entity, and asks for confirmation first because it drops every recorded pin; with one or more entity URIs, re-resolves only those, holding all other pins and the recorded external inputs unchanged, and asks nothing (mutually exclusive with —verify)
--verifyfalseVerify the existing lockfile against the dependency resolution a pull would perform now, without writing the lockfile, the plugin trust record or any entity.lock; exits non-zero on drift or missing lockfile. The resolution honors the pins the lockfile records exactly as a pull does: a reference whose registry has published a newer version since the pull is not drift, because a pull would hold its pin, and a registry now serving different bytes under a pinned version halts the verify as it halts a pull. The content cache is read and filled as a pull reads and fills it: an entry the cache holds under its pin is read from there without asking a registry, one it does not hold is fetched, and one that no longer matches its pin is treated exactly as a pull treats it. Also holds the entity.lock beside each Recipe and FeatureRecipe in your catalog directories that the Release reaches to what a build compares it with, and exits non-zero on a pin a build would refuse: an imported file that no longer matches its recorded digest, a local source whose files no longer match their recorded digests, or a source pin that disagrees with the lockfile. Also compares the signature the lockfile records for each artifact, and the plugin trust record for each plugin, with the one a pull would record now, and exits non-zero where a pull would record, replace or clear one: a signature a requirement asks for that is not recorded, and one made for another artifact, are reported without asking a registry, because a pull rewrites them whatever it answers; a signature a pull looks up again and might record unchanged — the artifact was fetched, or its cached signature bundle was removed or altered — is asked about at its registry, or under the offline posture left unchecked with a line saying so; and each plugin the plugin trust record covers is verified at its registry, as every pull verifies it, except under the offline posture, where it is read from the content cache as a build reads it, its identity and host functions are still checked, and its signature is left unchecked with a line saying so, unless a build refuses it for recording none or one made for another artifact, which is reported. Deprecation markers are not compared. Also reports the compiler and core-plugin versions the lockfile records — reported for audit and never compared against this binary, so a toolchain difference is never drift. Not accepted with —pin-sources, whichever value it is given: a verify neither records a pin an entity.lock is missing nor halts on one, so the flag would change nothing (mutually exclusive with —upgrade)
--yesfalseAnswer the bare —upgrade confirmation in advance, for non-interactive use. It reaches that one prompt and nothing else: every other form of pull asks nothing, so passing it changes no behaviour there