Skip to content
AggregaAggrega
Select language: English

Aggrega Plugin Trust Record schema

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

Schema id: https://aggrega.ai/schemas/plugins-trust-v1beta1.schema.json

Machine-generated record of the plugin identity trusted for each attachment that returns an accept-or-reject verdict — a plugins.governance attachment in an ir-verdict or render-verdict role, and every plugins.linter attachment. Lives at plugins-trust.yaml beside the lockfile and is committed alongside it, because a record held outside version control is one nobody can review and nothing can compare against. Written by aggrega pull, which creates the file the first time it resolves one of those attachments and adds a record per attachment as it resolves it. A file carrying records for only some of the configured attachments is a valid intermediate state rather than a damaged one. Read by aggrega build, by aggrega lint --release and by aggrega validate --release, and by the same operations reached through aggrega serve and aggrega mcp; each holds the workspace configuration to the record before any of those attachments runs. Two disagreements are refused, for different reasons: a plugin whose resolved artifact digest is not the digest recorded for it is refused rather than run, because the plugin that would run is not the one the record was reviewed for; and a record entry that no configured verdict attachment accounts for halts the run, because dropping a gate changes no rendered byte, so output produced without a gate that was reviewed is indistinguishable from output that gate approved. A build, a release-scoped lint and a release-scoped validation — from the command line, through aggrega serve or through aggrega mcp — also hold each of those plugins they read from the content cache to the signature its record carries, when they load it, as a build holds every lockfile entry to the one that entry carries: see signature below. The opposite direction — a configured attachment the record does not yet hold — is the intermediate state just described and neither comparison refuses it, and an absent record holds no entries at all, so it pins nothing and neither comparison refuses anything over it; the signature requirement is the one hold a missing entry does not escape, as signature below describes. An entry leaves the record only on an explicit upgrade: aggrega pull --upgrade naming a plugin drops that plugin’s entry when no verdict attachment names it any more, and a bare aggrega pull --upgrade drops every such entry. A plain aggrega pull neither re-resolves an entry’s identity nor removes the entry, so a halt over an entry nothing accounts for is cleared by saying so deliberately rather than by the next run. A record whose last entry is dropped is emptied rather than deleted, and an emptied record is a valid one: it holds nothing, so it pins nothing and neither comparison refuses anything over it, exactly as an absent record does. Each record is addressed by the plugin’s own identity coordinate and carries the selected version and the artifact digest as fields, so a version change is a change to a field of an existing record rather than a new record under a new address — which is what makes a re-versioned plugin distinguishable, in the file and in its diff, from one recorded for the first time. Besides that identity, a record carries two facts about the artifact it names, each recorded only when it was verified: the deprecation a publisher has attached to it, when one was found and its signature verified, and the verified-signature fact aggrega pull recorded when it verified the plugin’s own signature — the same fact, under the same key, a lockfile entry carries. Each is a fact about the recorded artifact rather than a second identity, which is why an ordinary pull records one without disturbing the identity it is held to. What the file records beyond those is nothing: no signature over the file itself, no rule inputs, no resolution provenance — no registry host, no path on the machine that wrote it — and no clock reading, so the same resolution produces the same bytes wherever and whenever it runs. A plugins.governance verdict attachment’s external rule files are recorded as digests in the lockfile’s verdict_inputs; a plugins.linter attachment’s rule inputs are recorded in neither file. Everything a build reproduces byte-for-byte is pinned in the lockfile instead; a verdict attachment shapes none of the rendered output, which is why its identity is recorded here rather than there. Schema evolution discipline: adding a new top-level section is SemVer-MINOR (additive); adding a new field inside an existing section is SemVer-MINOR; removing a key or tightening a constraint is SemVer-MAJOR.

Top-level type: object

Properties

PropertyTypeRequiredDescription
pluginsobject[]noOne record per plugin trusted for a verdict-returning attachment, addressed by the plugin’s identity coordinate. A plugin attached at two verdict roles at once — the same governance plugin bound to both ir-verdict and render-verdict — contributes a single record, because the recorded subject is the plugin’s identity rather than the attachment: the two attachments read the same artifact. Records are emitted in ascending coordinate order. Default: []
versionconst 1yesTrust-record schema version: 1. A SemVer-MAJOR change to the schema increments it. Constant: 1

Additional properties are not permitted.

plugins-trust.plugins[]

PropertyTypeRequiredDescription
deprecationobjectnoVerified retroactive deprecation marker recorded when a signed, trusted marker was discovered on the artifact digest names. A marker is a signed OCI referrer of the artifact it deprecates, attached after publication without re-publishing the artifact, so a plugin already recorded here can be deprecated afterwards — at the retracted severity, which is the withdrawal tier, that means the artifact is excluded from selection rather than merely discouraged. It is a fact about the artifact this record already addresses rather than a second identity, which is what lets aggrega pull add one while still leaving resolved_version and digest alone: recording it adopts nothing. It is recorded only when the resolved digest equals the digest already recorded — a resolution reporting different bytes is a change of identity, governed by this record’s own rule and refused unless the run asked for it. Nothing clears a recorded marker; it leaves only with the record that carries it, on the explicit upgrade that replaces or drops that record. aggrega build, aggrega lint --release and aggrega validate --release, and the same operations reached through aggrega serve and aggrega mcp, name a plugin carrying one, because a deprecated gate is otherwise fetched, cached and run with nothing said, and the workspace build.halt_on_deprecated_severity dial decides whether a build halts on it or is merely advised.
pluginstringyesThe plugin’s identity coordinate: its socket segment and its bare name joined by a slash, as in governance/aggrega-security-baseline. A bare name is unique only within its socket, so the socket segment is what distinguishes two same-named plugins in different sockets. The coordinate deliberately carries no version — that is what makes a version change visible as an edit to resolved_version below rather than as an unrelated record.
resolved_versionstringyesConcrete version selected for this plugin when the record was written (e.g. 1.2.3). Recorded as a single path segment, so it carries no /, no \ and no ... Pattern: ^([^/\\.]|\.[^/\\.])*\.?$.
digeststringyesContent digest of the resolved plugin artifact, in sha256: followed by 64 lowercase hex characters — the form the content-address is written in everywhere it is compared. Pattern: ^sha256:[a-f0-9]{64}$.
signatureVerifiedSignaturenoVerified-signature fact recorded when aggrega pull verified this plugin’s own signature against the resolving registry’s trust policy, for the artifact digest names. A pull verifies the signature of every plugin it resolves for one of these attachments, on every run, and records what it found here — replacing what the record held, and removing it where the pull verified none — without disturbing the identity the record is held to. Before a build, a release-scoped lint or a release-scoped validation runs the plugin, the cached signature bundle this fact names is re-hashed, and the run halts where the blob is missing or differs; and for a plugin read from the content cache, the run reads from that bundle which artifact the signature was made for, and halts where it was made for a different artifact than the plugin it read — so a signature copied from another plugin’s entry is refused, whatever the signing requirement says. No signature is verified there, so a bundle written into the cache by hand, made out for this plugin’s own artifact, is not told apart from one a pull verified. And where the workspace’s trust configuration requires a signature for a plugin read from the content cache — the requirement aggrega pull applies when it verifies the plugin, so the skips and an advisory registry that let a pull record none let the run go ahead too — a record carrying no signature for it, or no entry for it at all, halts the run, naming the plugin and the settings that require the signature. A plugin read from a catalog directory or from the copy inside the compiler binary is never held to that requirement.

Additional properties are not permitted.

plugins-trust.plugins[].deprecation

Verified retroactive deprecation marker recorded when a signed, trusted marker was discovered on the artifact digest names. A marker is a signed OCI referrer of the artifact it deprecates, attached after publication without re-publishing the artifact, so a plugin already recorded here can be deprecated afterwards — at the retracted severity, which is the withdrawal tier, that means the artifact is excluded from selection rather than merely discouraged. It is a fact about the artifact this record already addresses rather than a second identity, which is what lets aggrega pull add one while still leaving resolved_version and digest alone: recording it adopts nothing. It is recorded only when the resolved digest equals the digest already recorded — a resolution reporting different bytes is a change of identity, governed by this record’s own rule and refused unless the run asked for it. Nothing clears a recorded marker; it leaves only with the record that carries it, on the explicit upgrade that replaces or drops that record. aggrega build, aggrega lint --release and aggrega validate --release, and the same operations reached through aggrega serve and aggrega mcp, name a plugin carrying one, because a deprecated gate is otherwise fetched, cached and run with nothing said, and the workspace build.halt_on_deprecated_severity dial decides whether a build halts on it or is merely advised.

PropertyTypeRequiredDescription
messagestringyesHuman-readable deprecation message carried by the marker — typically a migration pointer. Where the marker carried no separate message, its reason is recorded here instead, so the reported sentence is never blank.
severitystring (enum)yesMarker severity, ordered warning < error < retracted. A build halts when this severity meets or exceeds the configured halt threshold, and is advised otherwise — the same rule and the same dial every other deprecation report reads. retracted is the withdrawal tier: an artifact at that severity is excluded from selection, where the two advisory severities leave it selectable. Allowed values: "warning", "error", "retracted"

Additional properties are not permitted.

Definitions

VerifiedSignature

Verified-signature fact a pull records when it verifies an artifact’s signature against the resolving registry’s trust policy. It is the one shape both records use for it — the lockfile, on each of its entries, and this record, on each plugin — so a verified signature reads the same in either file. Records the verification mode, the keyless identity/issuer that matched (when keyless) or the pinned key’s fingerprint (when keyed), and the content-addressed digest of the signature bundle the pull cached.

PropertyTypeRequiredDescription
bundle_digeststringyesSHA-256 digest of the cached signature bundle blob, in sha256: followed by 64 lowercase hex characters. It names the cache blob, so it builds a path and carries no /, no \ and no .. — which the sha256: form already excludes — and it is what a build, a release-scoped lint and a release-scoped validation re-hash that blob against. Pattern: ^sha256:[a-f0-9]{64}$.
identitystringnoVerified signer of the signature: the signing certificate’s subject for a keyless signature, or keyed:sha256: followed by the SHA-256 of the pinned public key’s PEM text for a keyed signature.
issuerstringnoVerified OIDC issuer for a keyless signature. Empty for a keyed signature.
modestring (enum)yesVerification mode that admitted the signature. Allowed values: "keyless", "keyed"

Additional properties are not permitted.