Skip to content
AggregaAggrega
Select language: English

Aggrega Entity Lock schema

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

Schema id: https://aggrega.ai/schemas/entity-lock-v1beta1.schema.json

The entity.lock file that sits beside an entity and records the content pins for the inputs that entity reaches for outside its own document: the files its artifacts import, the files of a local source, and the remote sources whose identity the entity writes out in full — and, for a local source that is a directory, the rules that decided which of its files belong to the entity. One step writes it: aggrega pin, which the entity’s author runs and which needs no Release. aggrega pull and aggrega push run that same step, and write the same bytes, when asked to — with --pin-sources, or with the workspace’s pin_sources_at_pull or pin_sources_at_push. A pull not asked to pin writes nothing here: over an entity in the workspace’s own catalog directories it compares what the step would record with what the file holds, and halts, naming aggrega pin, where a pin is missing or no longer matches its input — for a local source, a file added, changed or removed since the pin halts the pull like any other stale pin. aggrega build reads it back and halts when what is on disk no longer digests to what was recorded. It is scoped by the directory it sits in — it pins the inputs of the entity in that directory — so one file name serves every kind rather than each kind carrying a spelling of its own. The step removes the lock of an entity that reads no such input, rather than leaving an empty one behind. The entity document itself is never machine-written: what an author typed stays exactly as typed, and what the machine derived lives here. That separation is what makes the lock safe to commit and readable as a diff, because each row names one input and a moved digest names the input that moved. It carries no timestamp and no resolution metadata, so re-running the step over unchanged inputs leaves the file byte-identical. One row shape serves every kind that can record a pin, so a pin reads identically whichever kind it belongs to. The wire shape is closed (additionalProperties: false). Schema evolution discipline: adding a new optional field is SemVer-MINOR (additive); removing a field or tightening a constraint is SemVer-MAJOR.

Top-level type: object

Properties

PropertyTypeRequiredDescription
versionconst 1yesEntity-lock schema version: 1. A SemVer-MAJOR change to the schema increments it. Constant: 1
sourceDigestsobject[]noContent pins for the remote sources this entity references whose identity the entity writes out in full, frozen at resolution from the fetched bytes and read back at build to verify the cached source has not drifted. Each entry mirrors the resolved-source identity {kind, url, chart, moduleSubdir, version} plus the content digest (and, for an OCI-distributed source, the manifest digest). A source whose identity is filled in from a template — a version read from a Release’s infrastructure values, for example — carries no entry here: which artifact it names is decided by each Release that uses the entity, so each identity it resolves to is pinned in that Release’s lockfile instead. A local (filesystem-relative) source carries no entry here either: it names a path rather than something fetched, so there is no acquired archive to pin, and its files are pinned one by one in localSourceDigests instead.
artifactDigestsobject[]noContent pins for the files this entity’s artifacts import via $import — for a Recipe, those its boundary.artifacts entries import as well — frozen at resolution and read back at build to verify the imported file has not drifted. One entry per artifact whose value is a file import; an inline (literal) artifact is already part of the entity and carries no separate pin, and an artifact taken from a library is pinned by the version that library resolved at. A build compares an entry of either block with its pin the same way, and refuses a file that no longer matches it under the same condition.
localSourceDigestsobject[]noContent pins for the files of this entity’s local source — a source written as a path beside the entity rather than fetched — frozen when the entity is pinned and read back at build to verify the files have not drifted. One entry per file the source contributes to what a publication of the entity carries: every file under the directory the source names that the rules recorded under ignore keep, or the one file it names. A local source written as a template names its directory only once a Release fills the template in, so it contributes every file in the entity’s own directory the recorded rules keep, and each of those is pinned. The entity document, the author’s .aggregaignore beside it and this file are never entries: the document is the entity itself, the ignore file’s rules are recorded under ignore, and the lock cannot record its own digest. Once the lock records any entry here, a build refuses a source holding a file with no entry, a file whose content no longer digests to its entry, or missing a file an entry names.
ignoreobjectnoThe rules that decide which files under this entity’s local source directory belong to it, recorded when the entity is pinned. Every later reading of that directory applies these rules and nothing else: a publication of the entity, the comparison a pull or a publication holds the lock to, the author’s entity row, a build’s comparison and its render, and a verifying pull. So a change to the author’s .aggregaignore, to the workspace’s provider binding or to the aggrega binary moves no digest until the entity is pinned again, and pinning it again shows the change here as a diff. Present only where the entity declares a local source that is a directory, or one written as a template. A lock recording no rules keeps every file under that directory. A symbolic link anywhere under it is refused rather than followed.

Additional properties are not permitted.

entity-lock.sourceDigests[]

PropertyTypeRequiredDescription
kindenumyesThe resolved source kind. One of a closed set — the same set the lockfile’s source-artifact kind and the cache metadata’s kind carry — because all three record the same resolved-source identities and a build reads the kind to choose the loader. terraform-module-oci belongs to the set, and no source adapter serves it: a Recipe or FeatureRecipe naming it is refused as it is read. Allowed values: "helm-oci-chart", "helm-https-chart", "compose-https-fragment", "git-repository", "terraform-module-oci"
urlstringyesThe authored source URL the digest pins — the identity URL as written in spec.source.url (a repo root or a direct .tgz for helm-https-chart). Build reconstructs this same URL offline, so it is the stable identity the pin is keyed on, not a resolved artifact location.
chartstringnoThe chart name for a repo-root helm source (spec.source.chart), part of the resolved-source identity so two charts served from one repo root at the same version pin distinctly. Absent for a direct .tgz, OCI, compose, or git source, none of which selects a chart within the URL.
moduleSubdirstringnoThe directory within a git-sourced repository that is the artifact (spec.source.module_subdir), part of the resolved-source identity so two directories of one repository at the same commit pin distinctly. Absent when the whole repository is the artifact, and for every kind that reaches its artifact by URL rather than by descending into a clone.
versionstringyesThe concrete pinned version the source resolved to — a chart version for a helm-* kind, the commit a git-repository reference resolved to. Recorded as a single path segment, because it builds the cache slot the build reads the source back from, so it carries no /, no \ and no ... Pattern: ^([^/\\.]|\.[^/\\.])*\.?$.
digeststringyesThe content digest of the fetched source archive, in sha256: followed by 64 lowercase hex characters, verified against the cached bytes at build. Pattern: ^sha256:[a-f0-9]{64}$.
manifestDigeststringnoThe OCI manifest digest for an OCI-distributed source — the independent root of trust — in sha256: followed by 64 lowercase hex characters. Present only for an OCI source (a helm-oci-chart); absent for an https or git source, which carries no manifest by construction. Pattern: ^sha256:[a-f0-9]{64}$.

Additional properties are not permitted.

entity-lock.artifactDigests[]

PropertyTypeRequiredDescription
namestringyesWhich artifact’s $import file this entry pins: the artifacts: map key for an entry of artifacts, and boundary/ followed by the key for an entry of a Recipe’s boundary.artifacts — so an entry of each block written under one key is pinned apart.
digeststringyesThe content digest of the imported file’s bytes, in sha256: followed by 64 lowercase hex characters, verified at build. Pattern: ^sha256:[a-f0-9]{64}$.

Additional properties are not permitted.

entity-lock.localSourceDigests[]

PropertyTypeRequiredDescription
pathstringyesThe file’s path relative to the directory holding the entity document, written with forward slashes — charts/app/templates/deployment.yaml, for instance.
digeststringyesThe content digest of the file’s bytes, in sha256: followed by 64 lowercase hex characters, verified at build. Pattern: ^sha256:[a-f0-9]{64}$.

Additional properties are not permitted.

entity-lock.ignore

The rules that decide which files under this entity’s local source directory belong to it, recorded when the entity is pinned. Every later reading of that directory applies these rules and nothing else: a publication of the entity, the comparison a pull or a publication holds the lock to, the author’s entity row, a build’s comparison and its render, and a verifying pull. So a change to the author’s .aggregaignore, to the workspace’s provider binding or to the aggrega binary moves no digest until the entity is pinned again, and pinning it again shows the change here as a diff. Present only where the entity declares a local source that is a directory, or one written as a template. A lock recording no rules keeps every file under that directory. A symbolic link anywhere under it is refused rather than followed.

PropertyTypeRequiredDescription
pluginobjectnoThe plugin that served the entity’s capability in the author’s workspace when the entity was pinned — the workspace’s provider binding for that capability, or else the plugin built into the aggrega binary — named without a version, and the ignore rules it declared. No version and no digest of the plugin is recorded: the rules are what every reading applies, so pinning again under another release of the same plugin leaves the lock unchanged unless the rules changed. A pull whose own plugin for the capability declares different rules says so in an advisory, naming both plugins and the difference, and never halts on it. Absent where no plugin served the capability.
rulesobject[]noThe exact composed rules, in the order they apply: the plugin’s patterns, then the lines of every ignore file the plugin names that the walk found, a directory’s own file before those beneath it, then the lines of the author’s .aggregaignore beside the entity. A later match overrides an earlier one, so the author’s file has the last word on any path it names, and a line opening with ! brings back what an earlier rule excluded. A directory a rule excludes is not entered, so a file under it comes back only once the directory does.

Additional properties are not permitted.

entity-lock.ignore.plugin

The plugin that served the entity’s capability in the author’s workspace when the entity was pinned — the workspace’s provider binding for that capability, or else the plugin built into the aggrega binary — named without a version, and the ignore rules it declared. No version and no digest of the plugin is recorded: the rules are what every reading applies, so pinning again under another release of the same plugin leaves the lock unchanged unless the rules changed. A pull whose own plugin for the capability declares different rules says so in an advisory, naming both plugins and the difference, and never halts on it. Absent where no plugin served the capability.

PropertyTypeRequiredDescription
namestringyesThe plugin that served the entity’s capability when it was pinned, as <pluginType>/<name>, with no version: the rules below are what a reading applies, and the name says whose they were. At least 1 character long.
patternsstring[]noThe ignore patterns the plugin declared, as it declared them.
filesstring[]noThe names of the ignore files the plugin declared its ecosystem honours inside a source.

Additional properties are not permitted.

entity-lock.ignore.rules[]
PropertyTypeRequiredDescription
patternstringyesOne ignore pattern in gitignore syntax.
withinstringyesThe directory the pattern is scoped to, relative to the directory holding the entity document and written with forward slashes; . names that directory itself. A pattern the plugin declares is scoped to the local source directory, a line of an ignore file to the directory holding that file, and a line of the author’s .aggregaignore to the entity’s directory.
fromstringyesWhere the pattern was declared: plugin for one the plugin declared, and otherwise the path of the ignore file it was read from, relative to the directory holding the entity document.

Additional properties are not permitted.