Wasm plugin contract
Aggrega’s compilation pipeline includes designated socket points where WebAssembly (Wasm) plugins extend the compiler’s behaviour: the governance socket’s four roles, among them a Mutation Gate at topology construction and a Validation Gate at static analysis; a post-render plugin pipeline for FeatureRecipe and Recipe steps; a provider-rendering socket; a parser socket; an importer socket; and an out-of-band linting socket. This page documents the public Wasm plugin contract: which sockets exist, what each socket consumes and produces, where each socket sits in the compilation pipeline, and the sandbox every plugin executes inside.
This page covers the sockets — the pipeline points and their input/output shapes. For the plugin — the Plugin entity, the per-export capability claims, the runtime limits, and the publish→pull→build lifecycle — see the Wasm plugin developer guide.
Aggrega embeds a Wasm host runtime — Extism on top of the Wazero engine — that loads and executes plugins behind an AOT-purity firewall: the host grants a guest zero ambient capability — no network, no filesystem, no environment, discarded stdio, an observable wall clock frozen to a build-invariant instant — so a plugin cannot break the compiler’s ahead-of-time guarantees. The full capability surface — the import-module rule at load, the instantiation-time denials, and the curated host functions — is the sandbox contract below. Plugin authors target the host through the three-language PDK (Go, Rust, TypeScript). aggrega lint dispatches the linter socket — the standard publishing-linter — through the host. aggrega build dispatches the governance socket’s build-time roles when a workspace configures them: the annotation-transform role during resolution and the label-transform role at topology construction (both shape output), plus the IR verdict at static analysis and the render verdict over the rendered artifacts. Each is a no-op when no plugin is attached at that role, so a build with no governance configuration is unchanged. aggrega build also dispatches the FeatureRecipe and Recipe pipeline: in the plugin pipeline that closes rendering — each declared step runs through the host against the rendered document set, applying the step’s RFC 6902 patches and emitting its side effects. See Status of the Language → Compilation pipeline phases.
The sandbox contract
Every socket dispatches its plugin through the same host sandbox. The sandbox has two independent layers — a structural check at load and capability denial at instantiation — and together they define what a plugin can reach, what it cannot, and what it is responsible for.
The import-module rule (load time). The loader walks the plugin binary’s import section and admits function imports only under three module namespaces: wasi_snapshot_preview1 (the WASI preview-1 runtime a guest language runtime links against), extism:host/env (the Extism runtime ABI — the PDK’s own memory and IO intrinsics), and extism:host/user (Aggrega’s curated host functions). A guest may import any function name under an allowed module; an import under any other module names a surface the host does not provide, and the plugin is rejected at load with a diagnostic naming the module and the import. The rule deliberately does not censor individual WASI function names: a statically-linked language runtime imports filesystem and socket functions its live code paths never call — pulled in transitively by dependencies — and naming an import grants nothing. Capability denial at instantiation, not import censorship, is what guarantees no I/O.
Zero ambient capability (instantiation). The host instantiates the guest with real WASI behaviour and zero ambient authority:
- no filesystem — no preopened directories, so a filesystem call fails at the call boundary;
- no network sockets;
- an empty environment;
- discarded stdio — nothing the guest writes to stdout or stderr reaches the host’s streams;
- a frozen observable wall clock, pinned to a build-invariant instant, so a guest reading the time cannot leak build time into its output;
- a real, advancing monotonic clock — a guest language runtime needs one to bootstrap, and monotonic time measures elapsed duration, not a wall-clock instant;
- real host entropy — pinned entropy would stabilise a language runtime’s internal hash seed and mask guest nondeterminism instead of letting it surface as differing output;
- a single synthetic program name as argv.
An I/O call a guest actually makes — opening a file, dialing a socket — fails at the call boundary. This is WASI’s own capability-based security model: the sandbox denies the capability rather than policing the code.
Inputs arrive only through the payload and the curated host functions. A plugin receives everything it renders or evaluates in the payload its socket carries — graph and node projections, values, and render context. Which encoding a payload arrives in is fixed per socket and named in that socket’s own section below; each published payload type ships an encode and a decode entry point for its socket’s encoding, so a guest calls one function rather than choosing a parser. For a sourced provider render, the payload carries a source listing rather than the source bytes: a sorted set of {path, is_dir} entries under the node’s source root, with no provider-layout interpretation by the host. The guest applies its own layout logic — select the single compose file, descend to a chart root, require a Chart.yaml, vendor a module recursively — and reads back exactly the slice it selects through a host callback. Beyond the payload, the host binds a curated, least-privilege set of host functions, and grants a plugin exactly the ones its binary imports:
aggrega_log— a log line on the host’s log destination.aggrega_emit_warning— a structured warning the host surfaces after the call.aggrega_fetch_external_input— the external-input fetch channel (below).aggrega_pack_source— the source-selection callback: the guest names a{file | dir | tree, path}selection under the source root and the host reads and packs exactly that under a sandbox that resolves paths under the root and rejects...aggrega_read_source_file— a single-file content read under the same sandbox, for content-dependent source selection.aggrega_parse_source— the producer-consumption callback: the guest names a syntactic format and hands over the source bytes, and the host resolves a parser for that format, runs it, and returns the canonical tree it produced. It is how a consumer obtains a producer’s output through the host instead of invoking a producer guest itself, and the host bounds it to a single level — a producer reached this way that calls it again is denied — so a consumer calls it once per source and may consume many sources in sequence.
The host derives the set a plugin imports from its .wasm binary, validates it against the curated allowlist, and cross-checks it against the host functions the guest’s describe() declares. aggrega plugin sync records the set in the entity’s spec.runtime.hostFunctions, and a publish refuses an entity whose record differs from the binary, so every plugin’s host surface is visible in the catalog and cannot drift from the binary.
Callback failures carry a machine-matchable code, under hostfunc_error_code. The reply-returning host callbacks — aggrega_fetch_external_input, aggrega_pack_source, aggrega_read_source_file, and the aggrega_parse_source producer-consumption callback — deliver failure in-band: the reply envelope carries a human-readable message and, beside it, an optional machine-matchable code under hostfunc_error_code, drawn from a closed vocabulary. The message is free-form prose for a person; the code is the stable identity a guest branches on without parsing the message. On success the code is absent; on failure the host sets both. The PDK surfaces the pair as a typed error whose text is the message and whose code field a guest matches against the language’s re-exported code constants. A guest tolerates an absent code and a code it does not recognise by falling back to the message — so matching on a code is a best-effort refinement layered over the always-present message, never a replacement for it. The closed value set is the host-function error-code schema.
🔴 Two different vocabularies name a failure on this boundary, and the key you read says which one you are holding. Confusing them is the one mistake worth calling out here, because a value from either is a plain string and neither the host nor the guest checks which set it came from.
hostfunc_error_code, on a reply the host sends a guest. Its value is a member of the closed catalogue linked above — a fixed, slowly-changing list naming the ways a host callback can fail. Because the set is closed, a guest can match a value against a named constant its kit re-exports and branch on the result.condition_codebesidecondition_short_code, on a socket output a guest returns to the host. These are the two identifiers of a halting condition the guest itself raised, and they come from the open, growing set of conditions the compiler registers rather than from the catalogue.condition_codeis the descriptive code the condition is registered under;condition_short_codeis the compact form — the letterEand four digits — that a reader quotes, searches for and pastes into a report. The host prints the short code in the bracketed head of the diagnostic it renders, so a condition a guest raises is quotable exactly as one the compiler raises is. It derives neither value, but it does check them: a short code resolving to no condition this compiler declares, or to one whose number has been retired, halts the build instead of reaching a reader as an identifier that resolves to nothing.
The two identifiers on the guest side are reported together: a guest that sets one and not the other has named a condition the host cannot resolve, and the host then reports its own generic plugin-failure condition instead, with the message still carrying the whole failure. And a condition_code is never a member of the host-function catalogue, so comparing one against a re-exported constant never matches — which is why each key names its own vocabulary rather than failure in general.
Each callback’s slots carry a stated encoding, and every slot that holds a payload document holds it as binary. Every argument a host callback takes is a pointer into guest memory, apart from aggrega_log’s numeric level; a reply-returning callback answers with a pointer too. What each of those slots holds is fixed per callback:
| Callback | Argument slots | Reply slot |
|---|---|---|
aggrega_log, aggrega_emit_warning | UTF-8 text — no payload document | no reply |
aggrega_fetch_external_input | a bare UTF-8 URL — no payload document | canonical CBOR |
aggrega_pack_source, aggrega_read_source_file, aggrega_parse_source | canonical CBOR (RFC 8949 §4.2.1) | canonical CBOR |
The table splits on what each slot holds rather than on the callback’s identity: a slot holding a payload document carries canonical CBOR, and a slot holding a bare string — a log line, a diagnostic field, a URL — carries UTF-8 text. aggrega_fetch_external_input is the one whose two slots differ: its argument is a bare URL, read as UTF-8 text, and its reply is a payload document in canonical CBOR.
What a guest does at a payload-carrying slot, and what it must not do. 🔴 A slot holding a payload document holds an opaque byte run, not UTF-8 text — so this is the shape a guest declares, not only the bytes it puts there. A guest that allocates such a request as a string, or reads such a reply as a string, does not interoperate: a text conversion in either direction corrupts binary bytes. The failure is loud rather than partial — a request the host cannot decode comes back as a reply envelope carrying the request_undecodable code, in the same in-band shape as any other callback failure, so the guest reports it instead of proceeding on a half-read payload. The payload types are SourcePackRequest and SourcePackResponse for aggrega_pack_source, SourceFileRequest and SourceFileResponse for aggrega_read_source_file, ParseInput and ParseSourceResponse for aggrega_parse_source, and the reply type FetchExternalInputResponse alone for aggrega_fetch_external_input, whose URL is allocated as text. Concretely, per kit:
- Go — build the request with the request type’s
EncodeCBOR(), allocate it withpdk.AllocateBytes(notpdk.AllocateString), and read the reply withReadBytes()on the memory the reply pointer resolves to, into the reply type’sDecodeCBOR. The fetch URL is the exception on the request side, allocated withpdk.AllocateString; its reply is read like any other. The//go:wasmimportdeclaration is a pointer either way, so nothing in the signature shows the shape — the allocation and the read are where it lives. - Rust — the
#[host_fn]declaration states the shape directly: each of the three payload callbacks readsfn <callback>(request: Vec<u8>) -> Vec<u8>;, and the fetch callback readsfn aggrega_fetch_external_input(url: String) -> Vec<u8>;. Build the request with the request type’sencode_cbor()and read the reply with the reply type’sdecode_cbor(&raw). - TypeScript — build the request with the request type’s
encodeCBOR…function, allocate it withMemory.fromBuffer(notMemory.fromString), and read the reply withreadBytes()into the reply type’sdecodeCBOR…function. The fetch URL is allocated withMemory.fromString; its reply is read withreadBytes()like the others. As in Go, thedeclare moduleentry is a pointer either way.
A guest that calls a PDK wrapper needs none of that. The wrappers — FetchExternalInput, PackSource, ReadSourceFile and ParseSource, in each language’s own spelling — do the allocation and the encoding, and none of their signatures names a wire type, so a guest that reaches these callbacks through its kit allocates and decodes nothing itself; a guest that declares and calls the host functions itself allocates and reads its memory as described above. A request allocated as text is refused rather than half-served, and a reply read as text cannot be decoded, so a mismatch between the two sides is loud rather than silent.
Two properties worth relying on. The reply carries the same encoding whether it succeeds or fails: a guest reads one slot and cannot know before decoding which of the two it holds, so one decode entry point reads both, and the error code and message described above arrive through it. And a guest fills a byte-valued field in its kit’s own field type — a byte slice in Go, a base64 string in Rust and TypeScript — because the conversion to the raw byte run the binary encoding carries is the generated encoder’s job, done on the way out and reversed on the way in. That covers ParseInput’s source bytes, the file content aggrega_read_source_file returns, the content aggrega_fetch_external_input fetched, and each packed file’s content in a pack-source reply: those bytes cross the boundary once rather than twice-encoded, and no guest base64s anything the encoder is about to un-base64. The content field of the read-source-file and fetch replies is omitted when it is empty, so the reply for an empty file or a zero-length fetched payload carries no content at all; such a reply is still a success, because a failure always carries its message and code, and each kit’s wrapper returns empty bytes for it. The tree aggrega_parse_source returns travels as a byte run holding its own JSON document verbatim; the host neither reads nor reshapes it. A parser reads the same ParseInput, in the same encoding, on its own parse export — see the parser socket.
Canonical means identical input produces identical bytes on every side, which is what lets a payload be compared across the three plugin kits rather than only round-tripped, and it is why a build’s output stays byte-identical. No CBOR library is needed in a guest and nothing hand-parses bytes: each published payload type ships the encode and decode entry points its slot’s encoding needs.
Determinism is the plugin author’s responsibility. The host consumes a guest’s output bytes verbatim and runs no serializer over them, so the contract every plugin must uphold is: identical input produces identical output bytes. The sandbox removes the ambient sources of nondeterminism — wall time, environment, filesystem state — but deliberately does not mask the rest: a guest that encodes entropy or elapsed monotonic time into its output produces visibly differing bytes across runs rather than a stably-hidden defect.
The external-input fetch channel. aggrega_fetch_external_input is the one sanctioned channel for remote content, and it is host-mediated, not guest network access: the guest names a URL, and the host serves bytes under the external-input pin discipline. A URL pinned in the Release’s lockfile is served from the local content-addressed store and verified against its recorded digest; an unpinned URL is refused with a diagnostic naming the URL and the step that pins it, because a render consumes the closure its lockfile records and never widens it. The pins are written when the Release’s dependencies are resolved, which is the one moment anything is pinned. The developer guide carries the authoring how-to and the pin discipline in full.
Maps that keep their order
Some maps a payload carries are marked order-preserving in their socket’s schema, because the order of their entries is part of what they carry: a build’s nodes, a node’s labels, the attachments on a node, a pipeline step’s inputs and outputs, the key spaces a provider declares. The published payload types hold each such map in a container that keeps its entries in the order they were set:
| Kit | Container |
|---|---|
| Go | aggrega.OrderedMap[V] — the kit’s name for the ABI package’s abi.OrderedMap[V] |
| Rust | OrderedMap<V> from the aggrega-abi crate, re-exported by the kit |
| TypeScript | the language’s own Map<string, V> |
The Go and Rust containers carry the operations of a map — look a key up, set it, delete it, read the keys, walk the entries in order, count them. Setting a key the container already holds replaces its value and keeps its place; a new key goes after every existing one.
The order survives both encodings. On the binary encoding a marked map is written as an ordered list of entries — each entry a two-element list, the key and then the value — in the container’s order, where the canonical encoding would otherwise write a map with its keys sorted. On the text encoding it is a JSON object whose members are written in the container’s order. A decoder on either encoding refuses a map that repeats a key, naming the key. A map the schema does not mark keeps the sorted map form on the binary encoding and a language’s ordinary map type in the published types.
Three consequences for a guest:
- The order is output. Because a marked map is written in the order it was filled, a guest that fills one from a source with no fixed order — iterating a built-in Go map, say — writes bytes that differ between runs of identical input. Fill it in a fixed order.
- The order holds only while the map stays in its container. A guest that converts a payload into a generic value type of its own language gets that type’s order instead: a Go
map[string]anyhas none, and Rust’sserde_json::Valuekeeps object keys sorted unless the crate is built with itspreserve_orderfeature. - In TypeScript, read and write through the generated functions. A type holding a marked map decodes its JSON member by member, so a key that reads as an array index, such as
"8080", keeps its place whereJSON.parsewould move it to the front of the object; and its encoder writes eachMapas an object, whereJSON.stringifywrites aMapas{}.Object.keysof aMapis empty too: read aMap’s keys with its ownkeys().
Values an input marks sensitive
A plugin never quotes, in a refusal or a warning it returns, a value its input marks sensitive — by its key, or as part of a payload marked as a whole. A refusal is the error an output carries; a warning is a Diagnostic the output carries, whatever its severity, or one raised through aggrega_emit_warning. The host carries that text unchanged wherever it reports it — the command line, the language server and the editor’s problem list, the assistant tools — and reads no value out of it, so the plugin is the only party able to keep the value out. Name the key, the setting or the position instead: a reader finds the value from there.
The rule covers text a library writes for the plugin as much as text the plugin writes itself. A template engine reports the data it was evaluating, a schema validator quotes a value that fails a pattern, a parser quotes the token it could not read. Where such a failure ran over a value the input marks, report it without the value — for instance, run the same step again with every marked value replaced by a placeholder, report that run’s failure when it fails at the same place, and otherwise say that the failure text is withheld. Under a payload marked as a whole, every value in that payload is a marked value, while its keys — the shape of the document — stay readable.
Where an input marks a key or a payload sensitive, spelled as the wire names it:
| Socket and export | Where the marking is read |
|---|---|
provider render_node and validate_node_input (RenderNodeInput) | node.sensitive_rendered_keys: each key names an entry of node.values when those values are the Component’s own, keyed by the leaves it declares — a Recipe’s valuesMapping writes keys no declaration names, so none of them is marked here — or an entry of a workload container’s attachments map that reads a slot declared sensitive. node.sensitive_values marks node.values as a whole: it is true when a valuesMapping — the Recipe’s, or an attachment’s FeatureRecipe’s — produced those values and reads a value an author declared sensitive. workload_projection.sensitive_workload marks every value of the workload the same way when the workload’s template reads one, and each entry of artifacts_projection.entries carries sensitive_content for its own content, a parser’s message about that content included. Each entry of omits carries sensitive when the template producing any of its kind, name or namespace reads one, and then every field of that entry is a marked value. Each entry of node.features carries its own attachment’s marking: sensitive_payload_leaves (the values.<path> and infra.<path> leaves its Feature declares sensitive), sensitive_inject (the inject delivery keys that read a provides key its Feature declares sensitive) and sensitive (whether the attachment handles declared-sensitive material at all). |
governance ir-verdict (PolicyInput) | graph: each node’s sensitive_payload_leaves, and each attachment’s sensitive_payload_leaves, sensitive_inject and sensitive. Every value those markings name already arrives as the withheld marker {"aggrega_withheld": "declared"}, so the value itself never reaches the plugin. |
No other socket input, and no other provider export’s input, carries a marking. A key marking names only what it joins exactly to a declaration, so an absent key never means a value is safe to quote: it means no declaration could be joined to that key. A payload marking is read from the references of the template that produced the payload — a reference reaching a declared value, the template handing on the whole of its data, or a template that does not parse — and never from a value, so its absence means that template read no declared value as far as its references show, or that no template produced the payload; it is not a statement that the payload carries nothing sensitive.
Pipeline placement of Wasm sockets
The compilation pipeline reserves the following socket points. The shape labels follow the four-label taxonomy from the Status page.
| Socket | Pipeline placement | Status today |
|---|---|---|
Governance socket, annotation-transform role | Resolution (before annotation expansion) | available — dispatched when a workspace attaches an annotation-transform plugin; injects annotations that expansion turns into Feature attachments |
Governance socket, label-transform role | Topology construction (the Topology Builder) | available — dispatched when a workspace attaches a label-transform plugin; auto-tags node labels via JSON Patch |
Governance socket, ir-verdict role | Static analysis (the Static Analyzer, over the IR graph) | available — dispatched when a workspace attaches an ir-verdict plugin; a halt verdict stops the build |
Governance socket, render-verdict role | Rendering (over the rendered artifacts) | available — dispatched when a workspace attaches a render-verdict plugin; a halt verdict stops the build |
FeatureRecipe and Recipe pipeline: plugins | The plugin pipeline (post-render mutation) | available — each declared step runs against the rendered document set, applying RFC 6902 patches and emitting side effects |
| Provider rendering plugins (helm, helm-chart, compose, terraform, cloudformation) | Base rendering (the providers) | available — every provider renders through its Wasm guest; rendering is Wasm-only, with no in-host renderer fallback |
Parser plugins (parse:<format>) | Rendering, for a render-verdict policy; and out-of-band, for an import | available — called for an artifact in a format a render-verdict policy does not read natively, for an importer through aggrega_parse_source, and to recognise the format of an import that names none |
Importer plugins (import:<format>) | Out-of-band (aggrega import) | available — dispatched by aggrega import, the editor session and the assistant-facing tool |
Linter plugins (linter/publishing) | Out-of-band (aggrega lint) | available — the publishing-linter ships and runs through the host via aggrega lint |
The annotation-driven Feature expansion sub-phase, part of resolution, is a native Go pipeline pass, not a Wasm socket. It validates annotation values against the target Feature’s spec.schema and injects synthetic Feature attachments at IR build time. See vocabulary/labels-and-annotations.md for the six annotation- and label-bearing surfaces and providers/well-known-annotations.md for the binding-shape and authoring teaching.
Output shape contract — what exists today
The governance socket carries a typed contract surface at each of its four roles, and the role fixes which one. Plugin authors implement guest-side code that produces the documented shapes; the host reads them at build time, once per configured plugin, when a workspace attaches a plugin at that role. The subsections below follow the order the pipeline dispatches them in.
The annotation-transform role — annotation-injection output
Pipeline placement. Resolution, after the components resolve and before annotation-driven Feature expansion runs.
Input shape (host → guest). An AnnotationTransformInput document carrying:
targets— the injection targets: the resolved components the guest may annotate — those a boundary names directly, and every component a routing entry under a boundary’saggregates:routes in, whether or not the entry names it — each carrying itsboundary_path, itscomponent_name(for a routed component, its dotted id in the build graph, such asmetrics.query), and theannotationsthe Release writes on it, so a guest can decide what to add without displacing an authored value. Each annotation value arrives as written — a string, an object of subkeys, ornullwhere the component opts out of an annotation it would inherit — and every key the component carries is present whatever its value. Ordered deterministically by the host.binding_keys— the annotation keys the Manifest registers a binding for, in author order. An injection under a registered key goes on to expand into a Feature attachment, so a guest reads this list to inject keys that will take effect. The host does not require an injection to name a registered key: an unregistered injected annotation behaves exactly as an authored unbound annotation does.sources— the definition files the attachment declared underwith.sources, each carrying its base-name path and content, sorted by path.settings— the free-form settings object the attachment declared underwith.settings, handed to the guest verbatim.
settings and sources are the same engine-agnostic with channel every other role reads, and both are absent when the attachment declares none. Because this role’s output shapes the build, the attachment’s settings and source content are pinned in the release lockfile at pull and reconstructed from it at build.
Output shape (guest → host). An AnnotationTransformOutput document carrying:
injections— the annotations to add, in order. Each names an existing target coordinate (boundary_pathandcomponent_name) plus theannotation_keyand itsannotation_value: a string, or an object of subkeys, which feeds a binding that routes several subkeys at once.
The host applies annotation additions only, to coordinates it supplied, each with a value an author could write on that annotation. It reads an injected value exactly as it reads the same value written in the Release — an object’s subkeys in the order the guest wrote them — so expansion meets it as it meets an authored one. An injection naming a coordinate the payload does not carry, or carrying null, a list, a number, a boolean or an object with no subkeys, halts the build with a message naming the coordinate and the annotation, rather than being silently dropped or applied; the whole output is checked before any of it is applied. That confinement is what bounds the role: an operator attaching a plugin here has declared annotation injection and nothing further. Where the build later refuses an injected annotation for how it routes, for a subkey value the bound Feature’s schema does not admit, or for a pillar a Release-side annotation may not use, its message names the plugin that injected it and the role it is attached at.
Wire encoding. This role’s payload and result travel as canonical CBOR (RFC 8949 §4.2.1), in both directions. A guest reads and writes it through the entry points the payload types carry — DecodeCBOR and EncodeCBOR in Go, decode_cbor and encode_cbor in Rust, decodeCBORAnnotationTransformInput and encodeCBORAnnotationTransformOutput in TypeScript — so no CBOR library is needed and nothing hand-parses bytes. In Rust the export takes and returns Vec<u8>; in TypeScript it reads Host.inputBytes() and writes Host.outputBytes(...). Each target’s annotations is a map the schema marks order-preserving, so it crosses as an ordered list of entries in the order the target holds it, and a guest reads it through its kit’s order-keeping container; each value crosses as the bytes of its JSON, as an injection’s annotation_value does in the other direction. settings crosses as the bytes of its JSON document, which a guest parses as JSON to look inside. An answer that is not an AnnotationTransformOutput in this encoding — one written as JSON, or one carrying a top-level field the shape does not declare — halts the build, naming the plugin and its export, rather than being read as an empty list of injections. Called directly with aggrega plugin run-local --export transform_annotations, a guest is handed the authored JSON payload converted into this encoding, and its answer is read as the export’s output shape and printed as JSON — an answer that is not that shape is refused, naming the export, as a build refuses it.
Type definitions. The annotation-transform wire types — AnnotationTransformInput, AnnotationTransformOutput, AnnotationTarget, AnnotationInjection, AnnotationSource — are published in all three ABI packages, generated from one codec so the three stay in lockstep.
The label-transform role — JSONPatch output
Pipeline placement. Topology construction, after the graph is flattened and before the IR graph is built, so the socket and Feature selectors the analyzer evaluates read the labels it leaves.
Input shape (host → guest). A MutatorInput document carrying:
compilation_context— release identity (release_name,environment).graph— aMutatorGraphprojection of topology nodes: each node’s Component, resolved version, labels, and thevaluesits instance declares.settings— the free-form settings object the attachment declared underwith.settings, handed to the guest verbatim.sources— the definition files the attachment declared underwith.sources, each carrying its base-name path and content, so a mutator can be driven by a checked-in rules or mapping file rather than inline settings.
The graph is a projection rather than the IR graph: each node carries its resolved label set and the values its instance declares in the Aggregate, while edges and feature payloads stay inside the compiler. The values are the Aggregate’s own, with its templates already evaluated against its parameters, so a value hoisted into a parameter arrives as the value the Release supplied; a default the Component’s schema declares, and anything a Recipe or a Feature contributes, are not among them, and a node that declares no values carries no values key. A value the node’s Component declares sensitive is withheld exactly as the verdict over the graph withholds it — it reads as {"aggrega_withheld": "declared"} — while every sibling no declaration reaches arrives as written. That is what lets a configuration the developer declared decide a label — a database whose values enable a vector extension promoted to datastore.aggrega.ai/engine: vector, say. settings and sources are the same engine-agnostic with channel the verdict roles read; the host passes them through and never interprets their content. Because a mutator’s output shapes the build, the attachment’s settings and source content are pinned in the release lockfile at pull and reconstructed from it at build, so the mutator input is invariant to a post-pull change to either until the next pull.
Output shape (guest → host). A MutatorOutput document carrying:
patches— an array of opaque JSONPatch documents (RFC 6902) that the host applies to the node labels alone; the values the input carried are read-only.
Each patch addresses a specific node’s labels via JSON Pointer (RFC 6901); the host applies the patches in array order and re-ingests the mutated label set into the IR graph. The label-transform role’s job is enterprise auto-tagging — adding compliance / observability / cost-attribution labels declared by enterprise policy without modifying catalog content. The label surface is this role’s only sanctioned target: a patch that touches a node field other than its labels, adds or removes a node, or sets a non-string label value halts the build rather than being silently absorbed. RFC 6901 is the path-grammar baseline for every document-path surface in Aggrega — the Wasm plugin contract here, plus .locals *_path exports, plus the *Path schema fields elsewhere in the corpus. See 02-naming-conventions.md “Document-path naming-suffix discipline” for the canonical baseline declaration and the *Path / *_path suffix discipline that distinguishes the two authoring sides.
Wire encoding. This role’s payload and result travel as canonical CBOR (RFC 8949 §4.2.1), in both directions. Canonical means identical input produces identical bytes on every side, which is what lets a payload be compared across the three plugin kits rather than only round-tripped, and it is why a build’s output stays byte-identical. A guest reads and writes it through the entry points its kit’s payload type already carries — DecodeCBOR and EncodeCBOR in Go, decode_cbor and encode_cbor in Rust, decodeCBORMutatorInput and encodeCBORMutatorOutput in TypeScript — so no CBOR library is needed and nothing hand-parses bytes. In Rust the export takes and returns Vec<u8>; in TypeScript it reads Host.inputBytes() and writes Host.outputBytes(...). The graph’s nodes, each node’s labels, and each node’s values are maps the schema marks order-preserving, so they cross as ordered lists of entries — the nodes in the order the build holds them, which is author order, each node’s labels in the order the node carries them, and each node’s values in the order the Aggregate writes them — and a guest reads all three through its kit’s order-keeping container. Each value crosses as the bytes of its JSON document: the Go and Rust kits hand it to the guest as that JSON, to be parsed as far as a rule needs, and the TypeScript kit as the parsed value.
Two things this does not change. The patches array stays JSON: the socket carries each patch document verbatim as opaque content and neither side reads into it, so a patch document’s own shape is independent of the encoding its socket carries. And settings and sources are still handed through verbatim — settings arrives as the bytes the attachment authored, which a guest parses as JSON if it needs to look inside.
Every other governance role carries the same encoding — the annotation-transform role and the two verdict roles each say so in their own section — so a guest serving more than one role speaks canonical CBOR at every role it serves, reading each payload through its own type’s decode entry point.
Type definitions. The mutator wire types — MutatorInput, MutatorOutput, CompilationContext, MutatorGraph, MutatorNode — are published in all three ABI packages (github.com/aggrega-ai/aggrega-abi/go, the aggrega-abi crate, and @aggrega-ai/aggrega-abi), generated from one codec so the three stay in lockstep. The host assembles the input and applies the patches the guest returns.
The verdict roles — verdict array output
A policy guest inspects a build and returns a list of verdicts; the host acts on each verdict’s severity and never interprets the policy itself. The full treatment — the four roles, severities, the operator-supplied input channel, writing a policy for either of the two engines that ship inside the compiler, wrapping a foreign policy engine, the reference guests, and how an operator attaches a policy — is on the governance socket page. This section records the pipeline placement and the typed wire shapes.
Pipeline placement. A policy is attached at exactly one verdict role, which fixes where it evaluates:
ir-verdict— evaluated at static analysis, before base rendering. The analyzer assembles the payload on every build.render-verdict— evaluated after render, over the emitted artifacts.
When a workspace attaches a verdict-role plugin, the pipeline marshals that role’s payload to the plugin and reads its verdicts back.
Input shape (host → guest). The role selects the payload:
- The
ir-verdictPolicyInputcarriesgraph— the full capability-agnostic IR graph (the same shape the Topology Builder emits), with every node, edge, and attachment detail the compiler holds, except that a value an author declared sensitive arrives withheld (see Values an input marks sensitive) — andprecalculated_paths, the routing paths the analyzer enumerates alongside, so a policy can reason about reachability without re-walking the graph. The graph is the versioned IR graph, single-sourced from their-v1beta1schema; the IR shape is not secret (it is the same graphaggrega inspectemits) and secrets in it are pointers, never plaintext. - The
render-verdictRenderPolicyInputcarriesartifacts— the rendered output files sorted by path, so the wire is byte-identical across runs of identical input. Each entry carries the artifact’s outputpathand its renderedcontent; it also carries theformatit was rendered in, when the producing provider declared one, and atree, the parsed canonical view of a format the guest does not read natively, which the host parses through the resolved parser and pipes through opaquely. Both are absent when they do not apply — a format the guest reads natively (JSON, YAML) is left unparsed for the guest to read fromcontent.
Both roles additionally carry the attachment’s sources (policy-definition files the host reads at build time and hands the guest verbatim, paths as base names, content opaque) and settings (a free-form object handed through untouched). Both are absent when the attachment declares none.
Output shape (guest → host). A PolicyOutput document carrying:
results— an array ofDiagnosticentries, each with aseverity(halt,warn, orinfo) and amessagestring. A verdict may also setcode,rule_id,classification,source_ref,location, andsuggeston the same entry; the host appends whichever of those the verdict carried to the rendered verdict, on every severity route.
Only fired verdicts appear; an allowing evaluation returns an empty array. The host walks the verdicts and maps each severity to an action: halt stops the build (surfacing every halt message), warn flags the verdict and lets the build proceed, info records it without affecting the outcome. A halt stops through the same gate a selector or appliesTo violation uses.
Wire encoding. Both roles’ payloads, and the PolicyOutput a guest returns at either, travel as canonical CBOR (RFC 8949 §4.2.1). A guest reads and writes them through the entry points the payload types carry — DecodeCBOR and EncodeCBOR in Go, decode_cbor and encode_cbor in Rust, decodeCBORPolicyInput, decodeCBORRenderPolicyInput and encodeCBORPolicyOutput in TypeScript — so no CBOR library is needed and nothing hand-parses bytes. In Rust each export takes and returns Vec<u8>; in TypeScript it reads Host.inputBytes() and writes Host.outputBytes(...). The graph’s order-preserving maps, among them its nodes and each node’s labels, cross as ordered lists of entries in the order the build holds them, and a guest reads them through its kit’s order-keeping container; which order a policy meets them in under each policy engine is on the governance socket page. settings, and an artifact’s parsed tree, cross as the bytes of their JSON documents, which a guest parses as JSON to look inside. An answer that is not a PolicyOutput in this encoding — one written as JSON, or one carrying a top-level field the shape does not declare — halts the build, naming the plugin and its export, rather than being read as an empty verdict list. Called directly with aggrega plugin run-local --export verdict_ir or --export verdict_render, a guest is handed the authored JSON payload converted into this encoding, and its answer is read as the export’s output shape and printed as JSON — an answer that is not that shape is refused, naming the export, as a build refuses it.
Type definitions. The policy wire types are published in the same three ABI packages: PolicyInput (ir-verdict role), RenderPolicyInput (render-verdict role), the shared PolicySource, and PolicyOutput, whose results entries are Diagnostic values. A diagnostic’s severity is one of three values every socket shares — halt, warn, or info — and the three are published as constants alongside the wire types in each of the three packages, so a guest reports from the same closed set the host routes on. A guest that returns any other value halts the build, with the message naming the plugin and the value it returned: an unroutable severity is a plugin defect the host reports rather than a diagnostic it drops.
Output shape contract — the FeatureRecipe pipeline and provider sockets
The sockets below carry typed contract surfaces the compiler dispatches at build. The FeatureRecipe and Recipe pipeline: steps run in the plugin pipeline over the rendered document set; the provider-rendering socket runs at base rendering; the publishing-linter runs out of band.
RFC 6902 patches (the plugin pipeline)
FeatureRecipe and Recipe pipeline: steps running in the plugin pipeline emit RFC 6902 JSON Patch operations against the rendered document set. The host hands each step the keyed document set whole; the step selects the documents it targets by content and returns key-addressed patches, which the apply engine applies to the addressed documents — typically appending a sidecar container, mounting a secret volume, or rewriting an env var. A step also returns side_effects (below), diagnostics — each entry the same shared Diagnostic shape every socket reports issues in — and outputs (below). Described at examples/04-secrets.md.
Status today: available. Each declared step runs during aggrega build.
Wire encoding. A step’s input (FRPStepInput) and its answer (FRPStepOutput) travel as canonical CBOR (RFC 8949 §4.2.1), in both directions. A guest decodes its input and encodes its answer through the entry points the payload types carry — DecodeCBOR and EncodeCBOR in Go, decode_cbor and encode_cbor in Rust (on the types the aggrega-abi crate publishes), decodeCBORFRPStepInput and encodeCBORFRPStepOutput in TypeScript — reading and writing bytes (Vec<u8> in Rust, Host.inputBytes() and Host.outputBytes(...) in TypeScript). No CBOR library is needed and nothing hand-parses bytes. The step’s with input (step_input), the outputs it returns, and the own and host document sets are maps the schema marks order-preserving, so they cross as ordered lists of entries in the order the pipeline holds them, and a guest reads and writes them through its kit’s order-keeping container — which is what lets a step’s outputs reach .steps.<id>.outputs in the order the step returned them. Each unit’s tree, each value of step_input and outputs, a patch’s value, a side effect’s crd and the render context cross as the bytes of their JSON documents, which a guest parses as JSON to look inside; a unit’s bytes cross as a raw byte run the generated decoder fills into the kit’s own field type — a byte slice in Go, a base64 string in Rust and TypeScript. Each diagnostic crosses in the shared Diagnostic shape. An answer that is not an FRPStepOutput in this encoding — one written as JSON, or one carrying a top-level field the shape does not declare — fails the step, naming the function it runs, which halts the build unless the step is optional. Called directly with aggrega plugin run-local --export step, a step is handed the authored JSON payload converted into this encoding, and its answer is read as the export’s output shape and printed as JSON — an answer that is not that shape is refused, naming the export, as a build refuses it.
Side effects — emitting resources (credential plugins in the plugin pipeline)
Credential FeatureRecipe pipelines (Two-Part Plugin Principle: Fetcher + Injector) emit full resources alongside a patch through a step’s side_effects, each declaring one of the two kinds the contract defines: emit_crd, a custom-resource document such as an ExternalSecret or VaultSecret CRD that the cluster fetches at runtime, or emit_file, a written file. A step returning any other kind halts the build, naming the node, the side effect’s index and the kind it declared. The Fetcher’s step emits the complete resource; the Injector’s step returns a patch that mounts the resulting Kubernetes Secret. Described at examples/04-secrets.md.
Status today: available.
Step output (pipeline: step outputs map)
A plugin-pipeline step publishes named outputs that subsequent steps consume via {{ .steps.<id>.outputs.<key> }}. The output shape is provider-defined per plugin; step outputs are scoped to the same pipeline and visible only to subsequent steps in declaration order. Documented at templates/expansion-matrix.md row 10.
Status today: available.
Provider rendering — the guest-driven socket
A provider is a Wasm guest. Rendering is Wasm-only: a Recipe’s capability: name resolves to the provider-rendering Plugin (pluginType: provider) that lists the name in its spec.provider.capabilities and advertises a render_node export, and that plugin’s guest renders the node. There is no in-host renderer to fall back to; a provider name that resolves to no serving Plugin halts the build at routing time. Adding a standard provider is shipping a .wasm guest and a catalog Plugin entity — the host carries no per-provider code.
A capability a provider serves carries no colon, and neither does one a pipeline step declares itself compatible with. A Recipe’s capability: is read as the capability up to its last colon and a version pin after it — helm:1.0.0 asks for helm at 1.0.0 — so a name containing a colon is one no Recipe can ask for. The host refuses such a name in describe()’s capabilities for a provider or pipeline-step guest when the guest loads and when its entity is generated for publication, naming the guest and the name. A parser’s parse:<format> and an importer’s import:<format> keep their colon: those are looked up by format, never through a Recipe’s capability:.
The host is a generic router. It reads the guest’s describe() self-report — including its render-behavior contract — and dispatches the guest’s exports without understanding any provider format. That contract drives dispatch as data:
input_kinds(sourced,synthesized,artifacts_standalone) — which Recipe input kinds the guest renders; the host gates a node’s input kind against this set.boundary_assembly(none|merge|nest) — how the guest combines a dispatch group’s output:mergeclassifies per-node output as fragments the assembler merges into one artifact,nestnests per-node files under an assembled wrapper,nonewrites each node’s output directly.nest_segment(optional) — for anestassembly, the directory each contributor’s own sub-directory is placed under, written as one directory name; absent, each contributor’s sub-directory sits directly at the dispatch position.assembly_name_annotation(optional) — a boundary annotation whose resolved value names the artifact the guest assembles from a dispatch group; absent, the guest names its assembly from the dispatch path alone.cross_boundary_linking(optional) — whether the guest wires a cross-boundaryusesedge through itslink_publishandlink_resolveexports; a guest declares it true exactly when it exports both, and the load refuses one whose flag and exports disagree.artifact_delimiters(optional) — the Go-template delimiter pair the guest applies to artifact bodies.reusable_instance(optional) — whether one loaded instance may serve every crossing of the build (see Determinism and instance reuse below).omits(optional) — whether the guest honours the omit entries a source render carries (see Leaving rendered units out below).boundary_artifacts(optional) — whether the guest’s target accepts the files a Recipe contributes to its boundary’s shared output (see Accepting the files a Recipe contributes to the boundary below).source_ignore(optional) — the files the guest’s ecosystem never ships beside a source it renders (see Declaring what a source’s ecosystem never ships below).
The socket is a fixed export set — one mandatory, the rest optional and advertised in describe():
render_node(mandatory) — render one IR node into provider-native files.assemble_boundary(optional) — merge a dispatch group’s per-node output into one artifact per path (present whenboundary_assemblyismergeornest).validate_node_input(optional) — structural pre-render validation of a node’s input; ahaltdiagnostic stops the build, awarnsurfaces to the build result.carve/reassemble(optional, paired) — the guest’s own byte-faithful patch codec for post-render pipeline steps, used only when both are advertised.name_bound(optional) — the guest judges whether a name the host proposes as a component identity yields names its target accepts, answering with a constraint rather than a name of its own.rendered_name(optional) — the guest reports the name its target gives the resources it renders for a node.link_publish/link_resolve(optional, paired) — the guest wires a cross-boundaryusesedge: the consumed endpoint publishes a handle, and the consuming endpoint resolves it into its own assembled output.
Recipe artifacts: fold into render_node through an artifacts projection on the input: the host does the $import read, the Go-template evaluation, and the provenance key/value computation, and hands the guest each entry already read and evaluated; the guest owns placement and emission in the format only it knows. Documented at architecture/13-catalog-and-registry.md.
A source render’s input carries the node’s values on node.values, and node.values_mapped says where they came from: it is true when they are the output of the Recipe’s valuesMapping — or, for an attachment’s own render, its FeatureRecipe’s — and absent when they are the component’s own values handed on as written. Whether a guest reads it is that guest’s own contract. The cloudformation provider binds a sourced template’s Parameters only from values a mapping produced, because a component’s own values may have been written for the Recipe’s other inputs; the terraform provider writes a sourced module’s arguments from the values its assembly receives, and does not read the flag. Those values travel on each rendered node of an assemble_boundary input for a node rendered from a source — a component’s whether or not a mapping produced them, an attached Feature’s only where its FeatureRecipe’s valuesMapping produced them — and the same flag travels beside them and only where they travel, so an assembler reads the same answer the node’s own render did; the cloudformation provider reads it there to learn which parameters a node’s binding filled, and refuses a reference to one from anywhere else in the stack, the host of an attached Feature included. The flag records how the values were produced and is never derived from a key or a value.
Wire encoding. Every export of this socket takes its input and returns its output as canonical CBOR (RFC 8949 §4.2.1), in both directions. A guest decodes its input and encodes its output through the entry points the payload types already carry — DecodeCBOR and EncodeCBOR in Go, decode_cbor and encode_cbor in Rust, and in TypeScript the decodeCBOR and encodeCBOR function of each type, such as decodeCBORRenderNodeInput and encodeCBORRenderNodeOutput — reading and writing bytes (Vec<u8> in Rust, Host.inputBytes() and Host.outputBytes(...) in TypeScript). No CBOR library is needed and nothing hand-parses bytes. A rendered file’s content, and every other byte field, crosses as a raw byte run that the generated decoder fills into the kit’s own field type: a byte slice in Go, a base64 string in Rust and TypeScript. The maps the schema marks order-preserving — among them a node’s values, features and uses, a reply’s derived_keys, and an assembly contributor’s values — cross as ordered lists of entries in the order the build holds them, and a guest reads them through its kit’s order-keeping container. Each value of a node’s values crosses as the bytes of its own JSON document, so the keys inside a value keep the order they were written in; so do each attachment entry of features, the render context, the parsed workload, each enriched edge, each carved unit and each patch operation, and a guest parses them as JSON to look inside. Each diagnostic crosses in the shared Diagnostic shape. An answer that is not its export’s output shape in this encoding — one written as JSON, or one carrying a top-level field the shape does not declare — halts the build, naming the export it called. The examples of payloads on this page are written as JSON for reading. Called directly with aggrega plugin run-local --export render_node, or with any other export of the socket, a guest is handed the authored JSON payload converted into this encoding, and its answer is read as the export’s output shape and printed as JSON — an answer that is not that shape is refused, naming the export, as a build refuses it.
Status today: available for all five providers. The helm guest renders sourced charts (resolving the chart root), synthesized workloads, and standalone artifacts as flat Kubernetes manifests. The helm-chart guest assembles an umbrella chart, nesting each node’s sourced chart as a sub-chart, and carries a byte-faithful patch codec and bracket ([[ ]]) artifact delimiters. The compose guest renders sourced compose files and synthesized workloads and merges a dispatch group into one docker-compose.yaml, joining a service to the networks of the components its x-aggrega-networks-of names. The terraform guest emits Terraform configuration verbatim (HCL or JSON) or vendors a sourced module and supplies its inputs as that component’s module-block arguments, validates a sourced module’s HCL structurally before render, and composes a boundary into one root configuration declaring each component as a module block sourcing that component’s own sub-directory. The cloudformation guest renders sourced templates and standalone stack fragments, merges a dispatch group into one stack template, and wires a cross-boundary uses edge through link_publish and link_resolve. Each renders offline and deterministically.
Declaring the names a guest derives
A provider guest usually derives names its output needs but nobody authored — the identifier a target addresses one resource by, the name one output is published under for another to reference — from the node identity and the resource it is emitting. Two nodes can arrive at one name whenever the parts they are derived from agree, and because the name lives inside the file bytes the host writes verbatim, the host cannot see the clash: it would have to parse the provider’s format to find it, which is exactly the knowledge that stays in the guest.
render_node therefore returns an optional derived_keys on its output, and the direction is inverted — rather than the host inspecting output, the guest declares and the host checks:
{ "files": [ { "path": "stack.yaml", "content": "..." } ], "derived_keys": { "logical-ids": ["paymentsapiQueue", "paymentsapiTopic"], "export-names": ["aggrega--prod--api--orders-db--host"] }}Each key of derived_keys is a key space the guest names, and each space carries the names the guest derived into it, in derivation order. Both the space names and the names within them are your vocabulary: the host reads them only as strings to compare for equality within one space. It does not parse a name, does not learn what a space or a name means, and never derives one itself — so one check covers every kind of name every provider derives, and a new provider needs no new host code. In the published types derived_keys is an order-keeping map, so the spaces cross in the order your guest sets them.
What the host does with them is a single question: within one space, is every declared name distinct across the contributors whose output merges into one assembly? Two contributors declaring one name in one space halt the build, and the halt names the space, the name and both contributors, so an author can act without reading the provider. Distinct names, and names that happen to match across two different spaces, pass.
Three properties are worth knowing when you decide what to declare:
- The scope is one assembled output — the set of contributors whose files merge together. A guest wanting uniqueness across a narrower or wider scope than that expresses the scope in the space name it declares, which keeps the choice yours rather than the host’s.
- One contributor may repeat a name freely. A node can render across several crossings — a source render, a workload synthesis, an artifacts placement — and the declarations merge. The same name declared twice by one contributor is that contributor describing one resource twice, not a clash.
- Declaring changes no bytes. The field is an assertion about what the guest derived, never a change to what it emitted, so a guest’s rendered output is identical whether it declares or not. Omitting
derived_keysis valid and leaves the check inert for that guest.
Reporting facts about what a guest emitted
Some things about a node’s render are visible only to the provider that produced it — what the documents it wrote contain, which names they define, how many of something it emitted — because reading them out of the file bytes means understanding the provider’s format. render_node can report such things itself, on an optional render_facts list beside its files:
{ "files": [ { "path": "stack.yaml", "content": "..." } ], "render_facts": [ { "name": "exported_outputs", "value": ["QueueUrl", "TopicArn"] }, { "name": "stacks", "value": [ { "name": "payments-api", "resources": 2 } ] } ]}Each fact is a name and a value, and both belong to your provider: which facts it reports, what each name means and what each entry holds are part of your provider’s own documented contract, so document them for the authors who will read them.
Report every fact’s value as a list — a JSON array — even when it holds one entry. One name can be reported by more than one render of a component: its own render can take several calls — a chart render and an artifacts placement, say — and each Feature attached to the component renders through a provider call of its own. No provider can know when it renders whether its report will be the only one under a name, so every report is a list, and the compiler joins the lists one name gets into one list. A fact whose value is anything else — an object, a string, a number, a boolean, null — is refused when your guest returns it: the build halts with the short code E0325, naming the fact, the node and your guest, and saying what the value was. The entries inside a list are any JSON values in the shape you document.
That a value is a list is the one thing the compiler learns about it. It keys the facts by name and hands each list to the templates that read it — the host component’s facts to every Feature attached to it, each caller’s facts to a Feature that declares it reads its callers’ render facts, and each target’s facts to a Feature that declares it reads the render facts of the components its host is wired to, as the template context describes — decoding each list into a value a template can range over. It never learns what a name or an entry means and never derives a fact itself, so a new provider can report new facts without any change on the compiler’s side. The facts a Feature attached to the node reports from its own render are kept apart from the ones the node’s own render reported.
Four properties are worth knowing when you decide what to report:
- The order is yours. The facts keep the order your guest lists them in, and each value keeps its own bytes — the order of a list’s entries and of each object’s keys is the order your guest wrote. List the facts in a fixed order, and write each entry with a fixed key order, so identical input produces identical bytes; a list of facts rather than a map exists precisely so that order survives in every kit’s own sequence type with nothing to mark, where a map keeps the order a guest wrote only when its schema marks it order-preserving and the guest fills its kit’s order-keeping container.
- Reporting changes no bytes. The files the compiler writes are the files your guest returned, whether or not facts accompany them.
- A node may report across several crossings. A node can render as a source render, a workload synthesis and an artifacts placement; the facts each one reports are kept in the order the crossings ran, and a name reported by more than one of them reads as one list joining them in that order.
- Reporting nothing is complete. Omitting
render_factsis valid, and a provider that reports nothing renders exactly as it would without the field.
The RenderFact type is published in the three ABI packages and re-exported by each language’s plugin development kit, and the kits’ render examples report two facts beside their files. In Go, a value is the JSON your guest writes; marshalling a slice of structs rather than of maps is what keeps each entry’s keys in the order you declared them:
type stackFact struct { Name string `json:"name"` Resources int `json:"resources"`}
stacks, err := json.Marshal([]stackFact{{Name: "payments-api", Resources: 2}})if err != nil { pdk.SetError(err) return 1}out := aggrega.RenderNodeOutput{ Files: files, RenderFacts: []aggrega.RenderFact{{Name: "stacks", Value: stacks}},}Leaving rendered units out
A source render can name units the provider must leave out of what it renders — a Secret a fetched chart generates afresh on every render, say. Which rendered unit an entry names is knowledge only your provider has, so the entries travel to your guest and your guest does the leaving out. They arrive on render_node’s input as an optional omits list beside the source_listing:
{ "node": { "id": "payments-api" }, "context": { }, "source_listing": { "root": "/acquired/payments-chart", "root_is_dir": true, "entries": [] }, "omits": [ { "kind": "Secret", "name": "payments-api-token", "namespace": "payments" }, { "kind": "ConfigMap", "name": "payments-api-dashboards" } ]}Each entry is a kind, a name and an optional namespace, already resolved to plain strings and listed in the order the author declared them; an entry that does not apply to the build is not carried. What the three fields select is your provider’s own contract — the kind, name and namespace of a resource in your target’s format — so document it for the authors who write the entries.
An author can build an entry’s fields from a value they declared sensitive — a resource named after a sensitive setting, say. Such an entry arrives with "sensitive": true, and your guest treats it as it treats every other marked value the render input carries (see Values an input marks sensitive): it still matches and counts the entry by its fields, which is what the entry is for, and keeps every one of its fields out of a refusal, a warning or a log line. The mark covers the whole entry, because the compiler does not say which field the value produced. It is absent when no field was built from such a value.
A guest that honours the entries does three things:
- Matches every entry against what it rendered, in your format’s terms.
- Leaves each matched unit out of everything it returns — its
files, the names it declares inderived_keysand the facts it reports inrender_facts— so nothing the compiler receives still describes it. - Reports one count per entry on an optional
omittedlist in its output, in the order the entries arrived, each the number of units that entry matched, counted whether or not another entry also matched them:
{ "files": [ { "path": "templates/deployment.yaml", "content": "..." } ], "omitted": [1, 0]}A zero is a complete answer: that entry matched nothing your guest rendered. The counts are all that travels back about what was left out; the units themselves are simply absent from what your guest returned.
A provider that does all three declares it with omits: true on its contract. The Plugin entity records the same claim as spec.provider.contract.omits; where the entity carries a render-behavior contract, the load refuses a guest whose describe() reports a different value. The entries accompany a source listing and nothing else: a render of a synthesized workload or of an artifact set never carries them.
A render that carries no entries is unchanged by the fields. Both fields are optional and absent when empty, so a render that carries no entries crosses the socket byte for byte as it would if the fields did not exist, and a guest that never reads them is unaffected by them. The OmitEntry type is published in the three ABI packages and re-exported by each language’s plugin development kit.
What the compiler does with your answer. The entries come from the omits: key an author writes on a Recipe or a FeatureRecipe (Recipe → The omits: field); the compiler evaluates each entry’s templates and hands your guest the ones that apply. It then reads your counts, and only your counts — it never looks into a returned file to check them:
- A count list that is not one non-negative count per entry it handed over halts the build — missing, too short, too long, or holding a count below zero — naming the node, your provider, how many entries went over and how many counts came back. A report that does not line up leaves no way to tell which entry left what out. See A provider’s omitted counts do not match the omits entries it was handed.
- A zero halts the build, naming the first entry in the author’s order whose count is zero: the node, your provider, the entry’s position in the list its document declares, and the kind, name and namespace it resolved to. Your guest reports the zero; the halt is the compiler’s. See An omits entry left out nothing the source rendered.
- A document declaring
omits:whose provider does not claimomits: trueis refused before anything renders, so an author learns at once that the key would have no effect rather than finding the document in the output. The compiler reads your claim from yourdescribe()once every Recipe and FeatureRecipe in the build is bound, and refuses before the first component renders — so a guest that does not claim the key is never handed an entry. The refusal names the provider and the component the document renders for, or, for a FeatureRecipe that generates once for a boundary, the boundary and the attachment. See The provider does not support omits.
Status today: available. The helm, compose and cloudformation guests distributed with the compiler declare the claim and honour the entries. The helm guest writes no field of any entry into a text it returns. The compose and cloudformation guests name an entry’s kind, name and namespace when they refuse the entry, and the units an entry left out when they refuse a file or a template that still names them, and show every field of a marked entry as <redacted> there. The helm-chart and terraform guests do not declare the claim, so a document declaring omits: that one of them renders is refused.
Accepting the files a Recipe contributes to the boundary
Some files belong to a boundary as a whole rather than to one of its components — a provider configuration a target reads once for everything the boundary deploys, say. A Recipe writes those under spec.boundary.artifacts, and the compiler, not your guest, does the work: it evaluates each file against the context an artifacts: entry is evaluated against, merges the files every contributor to the dispatch group declared by name, and writes each one once in the directory holding the group’s assembled output, beside what your assemble_boundary returns. Your guest is handed none of these files on any export and is never asked about one, so there is nothing to implement — only a statement about your target to make:
"contract": { "input_kinds": { "sourced": true, "artifacts_standalone": true }, "boundary_assembly": "nest", "boundary_artifacts": true}Declare boundary_artifacts: true only when your target reads a file placed in that directory as part of the boundary’s output. The Plugin entity records the same claim as spec.provider.contract.boundaryArtifacts; where the entity carries a render-behavior contract, the load refuses a guest whose describe() reports a different value. A Recipe declaring the block whose provider does not claim it is refused before anything renders, naming the provider and the component; see The provider does not support boundary artifacts. A file one of these merges places under a name your assembly also writes stops the build as two contributors writing one output path, so the names your assembly writes are part of what you document for authors.
Status today: available. The terraform guest distributed with the compiler declares the claim, and Terraform reads each file beside the boundary’s root configuration; the helm, compose, helm-chart and cloudformation guests do not declare it.
Declaring what a source’s ecosystem never ships
A Recipe’s local source directory — a co-located chart, a module — is published with the Recipe, and not every file in it belongs to it. A provider guest says what its own ecosystem never ships through source_ignore on its contract, as ignore rules in the syntax .gitignore uses:
"contract": { "input_kinds": { "sourced": true, "synthesized": false, "artifacts_standalone": false }, "boundary_assembly": "none", "source_ignore": { "patterns": [".git/", ".hg/", ".svn/", ".bzr/", "templates/.?*"], "files": [".helmignore"] }}patternsare rules read from the root of the source directory, applied in order, a later match overriding an earlier one.filesnames the ignore files your ecosystem honours inside a source. Wherever the walk of a source meets one, its lines are read as further rules for the directory holding it, after your patterns.
The declaration is read when an entity is pinned, not when it is rendered. The author’s pin step resolves the plugin serving the entity’s capability in their workspace, composes your rules with their own .aggregaignore — whose lines come last and so win on any path they name — and records your plugin’s name, with no version, together with the exact composed rules, in the entity’s entity.lock. Every later publication, comparison and render of that entity applies the recorded rules; the host matches them and holds no opinion of its own about any ecosystem. So the files your guest is handed at render — the listing, and every file it asks the host to pack or read — are exactly the files a publication of the entity carries, and a file the rules leave out is answered as not there, naming it. A symbolic link under a source is refused before your guest is invoked.
Compatibility follows from what was recorded. A guest can render a Recipe published for its capability when it speaks the same ABI version, its contract matches its entity’s claim, and it needs no file outside the published set. A guest that needs a file the set left out must fail its build loudly and name the file — the host’s refusal of a pack or a read names it, and a guest carries that into its own failure. Where the plugin a consumer’s workspace binds for a capability declares rules other than the ones an entity’s lock records, the consumer’s pull prints a warning naming both plugins and the difference; it never halts on it.
Omitting source_ignore declares no rules, and a source you render then keeps every file the author’s own rules keep. The field is optional and needs no ABI version of its own: a guest that omits it loads as one declaring nothing. The Plugin entity records the same declaration as spec.provider.contract.sourceIgnore; where it does, the load refuses a guest whose describe() reports something different.
Determinism and instance reuse
The host consumes a guest’s output bytes verbatim, so a guest must produce identical output from identical input. By default a guest is loaded fresh per node — zero state carried across nodes by construction. A guest that self-declares reusable_instance is instead loaded once per build and its single instance serves every crossing, which recovers the dominant per-node instantiation cost. Because reuse is safe only for a stateless guest, aggrega build --verify-determinism renders each node twice through the same instance and halts the build if any node’s two renders differ; the default build renders once and trusts the declaration. The Wasm compilation cache is disk-backed and process-wide, so a guest compiles once and warm builds skip recompilation.
The linter socket — the publishing linter
The linter socket ships as the standard publishing-linter, an out-of-band gate that runs through aggrega lint rather than at compile time. It consumes a catalog entity (and, in --pre-publish mode, the entity’s currently-published version) and returns a list of findings, each with a severity and a message; in --pre-publish mode it also returns a version-bump classification. The host dispatches it through the embedded Wasm runtime, behind the same AOT-purity firewall as every other socket. The full rule set, severities, and per-rule opt-outs are documented at cli/aggrega-lint.md.
The linter is opt-in catalog discipline: the compiler does not run it during aggrega build (with the single exception of the x-aggrega-* discouragement advisory, which surfaces at warn severity during build and at halt severity under aggrega lint --pre-publish). Because the rules live in a plugin, an enterprise can point aggrega lint at a different linter plugin to enforce its own discipline.
No parameter value reaches a linter plugin, at any scope aggrega lint runs. Before any document is handed over, the host withholds an Aggregate’s parameter defaults, the values it passes to each module it imports, and a Release’s parameters, keeping each parameter declaration’s contract — only the keys a declaration is written with, at every level it nests — and any template text that reads a parameter: a parameter’s value can be a credential itself, and the plugin attached here may be code the workspace did not write. What each document carries is set out under What a linter plugin is handed.
Wire encoding. The input and the output both travel as canonical CBOR (RFC 8949 §4.2.1). A guest decodes its input and encodes its output through the entry points its kit’s LinterInput and LinterOutput already carry — DecodeCBOR and EncodeCBOR in Go, decode_cbor and encode_cbor in Rust, decodeCBORLinterInput and encodeCBORLinterOutput in TypeScript — reading and writing bytes (Vec<u8> in Rust, Host.inputBytes() and Host.outputBytes(...) in TypeScript). No CBOR library is needed and nothing hand-parses bytes. The entity documents — proposed, previous, implemented_component and release — and each value of components cross as the bytes of their JSON documents, so a guest parses them as JSON to look inside. components is a map the schema marks order-preserving, so on the input of a rule that reads a whole Release it crosses as an ordered list of entries in the order the Aggregate declares its component instances, and a guest reads it through its kit’s order-keeping container. policies crosses as a map holding only the flags that are set, so a flag it does not carry reads as false, and each finding crosses in the shared Diagnostic shape. An answer that is not a LinterOutput in this encoding — one written as JSON, or one carrying a top-level field the shape does not declare — fails the lint, naming the export it called, rather than being read as a run that found nothing. Called directly with aggrega plugin run-local --export lint_rules, a linter is handed the authored JSON payload converted into this encoding, and its answer is read as the export’s output shape and printed as JSON — an answer that is not that shape is refused, naming the export, as a build refuses it.
Status today: available. The publishing-linter ships and runs through the host via aggrega lint.
The parser socket — canonical tree output
A parser turns a source written in a format the compiler does not read natively into a canonical structured tree, so a consumer reads the tree instead of carrying a parser of its own. The host resolves the parser that advertises the requested format as parse:<format> and calls its parse export in three places: when a render-verdict policy is handed a rendered artifact in a format it does not read natively, when an importer asks the host for a tree through aggrega_parse_source, and when an import that names no format is recognised (see the importer socket below). A guest never calls a parser itself.
Input shape (host → guest). A ParseInput document carrying:
format— the requested format, one of the parser’sparse:<format>capabilities without its prefix.bytes— the source bytes.options— an options document the consumer supplies for parser-specific behaviour, handed through verbatim. Absent when the consumer supplies none.
Output shape (guest → host). A ParseOutput document carrying the tree — the parsed source as a JSON document, whose top level may be an object, an array or a scalar — any diagnostics in the shared Diagnostic shape, optional source spans locating tree nodes in the original bytes, and a failure error when the parse could not complete. Every field and its constraints are in the generated parser socket schema reference.
Wire encoding. The input and the output both travel as canonical CBOR (RFC 8949 §4.2.1), the encoding the same ParseInput travels in when a guest hands it to aggrega_parse_source. A guest decodes its input and encodes its output through the entry points its kit’s ParseInput and ParseOutput already carry — DecodeCBOR and EncodeCBOR in Go, decode_cbor and encode_cbor in Rust, decodeCBORParseInput and encodeCBORParseOutput in TypeScript — reading and writing bytes (Vec<u8> in Rust, Host.inputBytes() and Host.outputBytes(...) in TypeScript). No CBOR library is needed and nothing hand-parses bytes. The source bytes cross as a raw byte run, and the generated decoder fills them into the kit’s own field type: a byte slice in Go, a base64 string in Rust and TypeScript. options and tree cross as the bytes of their JSON documents, so the tree a parser writes reaches its consumer verbatim. A parser that cannot complete says why in the output’s error, and the parse fails naming the parser and that message; an answer that is not a ParseOutput in this encoding — one written as JSON, or one carrying a top-level field the shape does not declare — fails the parse too, naming the parser and its parse export. A failed parse halts a build at the render-verdict role, and reaches an importer as the failure aggrega_parse_source answers with. So does a source the parser refuses — one it answers with a halt diagnostic beside its tree: the importer’s call fails with the message of each such diagnostic, in the parser’s order, and is never handed the tree. Called directly with aggrega plugin run-local --export parse, a parser is handed the authored JSON payload converted into this encoding — the source written in that payload as base64, as JSON writes any byte field — and its answer is read as the export’s output shape and printed as JSON — an answer that is not that shape is refused, naming the export, as a build refuses it.
Type definitions. The parser wire types — ParseInput, ParseOutput, NodeSpan and SourceSpan — are published in all three ABI packages and re-exported by each language’s plugin development kit, generated from one codec so the three stay in lockstep. Each kit’s parse example reads its input and writes its output this way, and so do the parsers for HCL, TOML, YAML, JSON and JSON with comments that ship inside the binary.
Status today: available — dispatched at the render-verdict role for an artifact in a format the policy does not read natively, through aggrega_parse_source for an importer, and to recognise the format of an import that names none.
The importer socket — draft authoring output
An importer turns a source written for another tool — a flow exported from an agent builder, say — into draft Aggrega authoring files. It runs out of band: aggrega import, the editor session’s aggrega/import method and the assistant-facing import tool resolve the importer that advertises the requested format as import:<format> and call its import export once per import. A build never dispatches it. Which importer runs, and what an operator hands it, is described under Which importer turns a source into drafts. The compiler’s own importers, one for each format it reads, are described on Core importers: which formats those are, what each reads, what it drafts, the settings it takes, their publication with each compiler release, and how an import fetches and verifies one the machine does not hold yet.
Input shape (host → guest). An ImportInput document carrying:
format— the format the import asked for, one of the importer’simport:<format>capabilities without its prefix.bytes— the source bytes: the whole file for an import of a file, and empty for an import of a directory, whose files arrive undersources.name— the name of the source, with no directory before it, so the importer can name the source in what it reports and in what it drafts: for an import of a file, the base name of the filebyteswas read from; for an import of a directory, the directory’s own base name, read from its full path, soaggrega import .hands the name of the directory it runs in, while the directory’s files each still arrive under their own name. Absent where the source has no name to give.sources— the named sources, each carrying its name and its bytes, in one list sorted by name: for an import of a directory, every file of it the importer’s declared file patterns select, the workspace’s build output folder left out, named by its slash-separated path inside the directory; and the files theplugins.importerentry attaching this importer declares underwith.sources, each under its base name. A directory file and awith.sourcesfile of one name refuse the import rather than one hiding the other. Absent where there are none.settings— the settings object that entry declares underwith.settings, as a JSON document with its keys sorted, handed through verbatim. Absent when no entry attaches the importer or the entry declares none.catalog— a view of the Components the workspace’s own catalog holds: the catalog the importer itself was selected from — the workspace’s catalog folders, or, where it names none, the catalog snapshot its default registry publishes, held on this machine — with nothing fetched for the view itself. Itscomponentslist holds one entry per Component name, sorted by name; where the catalog holds several versions of a Component, the entry describes the version a reference naming it without a version resolves to. Each entry carries the Component’snameandversion, itslabels, the top-level key names its values and provides declare (valuesandprovides, each sorted), and itssockets— each the socket’snameand the labelselectora dependency wired through it must satisfy — in the order the Component declares them. A Component that extends another carries what it inherits as well as what it declares, and the sockets it inherits come first. The view holds names, versions, labels and selectors only — never a value, a default or a secret — and its order is fixed, so one catalog yields one byte sequence. Absent when the catalog holds no Component.
Output shape (guest → host). An ImportOutput document carrying the entities the import produced — each a reference to an existing catalog entity or a drafted body — the mapping decisions behind them, any diagnostics in the shared Diagnostic shape, the scaffold files to write, and a failure error when the import could not complete. Every field and its constraints are in the generated importer socket schema reference.
Wire encoding. The input and the output both travel as canonical CBOR (RFC 8949 §4.2.1). A guest decodes its input and encodes its output through the entry points its kit’s ImportInput and ImportOutput already carry — DecodeCBOR and EncodeCBOR in Go, decode_cbor and encode_cbor in Rust, decodeCBORImportInput and encodeCBORImportOutput in TypeScript — reading and writing bytes (Vec<u8> in Rust, Host.inputBytes() and Host.outputBytes(...) in TypeScript). No CBOR library is needed and nothing hand-parses bytes. settings crosses inside the binary document as the bytes of its JSON document, so a guest parses it as JSON to look inside, as on every other socket. An importer that cannot complete says why in the output’s error, and the import halts naming the importer and that message; an answer that is not an ImportOutput in this encoding — one written as JSON, or one carrying a top-level field the shape does not declare — halts the import too, naming the importer and its import export. Called directly with aggrega plugin run-local --export import, an importer is handed the authored JSON payload converted into this encoding, and its answer is read as the export’s output shape and printed as JSON — an answer that is not that shape is refused, naming the export, as a build refuses it.
How a source of your format is recognised. An import may name no format, and the host then recognises one from what the importers declare, knowing no format itself. An importer declares in its describe() self-report, under importer (an ImporterContract), a detect list of the signatures a source of its formats is recognised by. Each DetectSignature names:
syntax— the syntactic format the source is parsed as, a format a parser plugin advertises asparse:<syntax>, such asjsonoryaml;files— optional file-name patterns matched against the end of the source’s name: one segment against the file’s own name, several slash-separated segments against that many trailing segments of its path, with*,?and[...]matching within a segment. A signature declaring none applies to a source that is one file whatever it is called, and to no file of a directory;match— the predicates the parsed tree must all satisfy, each aPathMatchwith apathof keys joined by dots from the top of the tree (a whole-number segment selects an array position), anisofpresent,absent,object,array,string,numberorboolean, and optionally anequalsstring or aprefixstring — at most one of the two.
When an import names no format, the host matches the signatures of every importer the import selects among — those in the workspace’s catalog and the compiler’s core importers — in order of their identity and version: it parses the source through the parser the catalog serves for a syntax — or, for a syntax the catalog serves no parser for, the one the compiler itself carries — at most once per syntax, evaluates the predicates over the tree, and reads the source as the format of the one importer whose signature matches. That is the parser an importer’s aggrega_parse_source call is answered through as well, so an importer reads its source through the parser it was recognised through. A source that does not parse in a syntax matches no signature naming it; a syntax for which neither the catalog nor the compiler serves a parser stops the recognition, naming the parser’s absence. A source no signature matches is refused asking for the format, and one recognised as more than one format is refused naming them. A signature recognises a source as every format its importer advertises, so an importer whose sources are to be recognised serves one format, and one that declares no signature is reached only by naming its format.
The importer’s Plugin entity records the same list as spec.importer.detect, derived from describe() when the entity is generated from the guest; recognition reads that record, so the guest is not loaded until its format is settled. Loading and publishing the guest refuse one whose report differs from its entity’s record, naming importer.detect, and an entity recording none makes no claim. The descriptor is refused at load where the contract is declared on a plugin that is not an importer, where a signature names no syntax or a malformed file pattern, and where a predicate names no path, an is outside the seven, or both equals and prefix.
The compiler’s core importers and the Go kit’s import example declare theirs this way. The Langflow importer reads a source as JSON and asks for an array at data.nodes; the Flowise importer asks for arrays at nodes and edges and for nothing at data.nodes; the n8n importer asks for an array at nodes, an object at connections and nothing at edges or data.nodes; the MCP importer declares one signature per client configuration, naming its file — .mcp.json, claude_desktop_config.json and .cursor/mcp.json, read as JSON with an object at mcpServers, and .vscode/mcp.json, read as JSON with comments, as Visual Studio Code reads it, with an object at servers — and one naming no file that asks for a $schema string opening with https://static.modelcontextprotocol.io/schemas/; the Compose importer reads a source as YAML, names the files Compose reads by default — compose.yaml, compose.yml, docker-compose.yml, docker-compose.yaml and their four override files — and asks for an object at services; the Dify importer reads a source as YAML, names no file, and asks for the string app at kind and for something at app.mode and at version; the CrewAI importer names config/agents.yaml and config/tasks.yaml, read as YAML with nothing asked of the tree, crew.jsonc and crew.json, read as JSON with comments with a list at agents, and agents/*.jsonc and agents/*.json, read as JSON with comments with something at role, so no two of them match one source, and a file imported on its own with no format named is read as YAML as well as JSON; the LangGraph importer names langgraph.json, read as JSON with an object at graphs, declares one signature naming no file that asks for an object at graphs and the string https://langgra.ph/schema.json at $schema, and names no environment file, since recognition reads every file any importer’s patterns select, so a pattern naming one would open the environment files of every directory imported naming no format; the Google ADK importer names root_agent.yaml, read as YAML with something at name and at instruction, or a string at agent_class and something at name, and names no other file, since a sub-agent’s configuration may be called anything and a pattern naming every YAML file would open each one of every directory imported naming no format; the Agent Framework importer reads a source as YAML, names no file, and asks for the string Prompt at kind and an object at model; the Go kit’s import example reads a source as YAML and asks for the string DemoSource at kind. In Go:
Importer: &aggrega.ImporterContract{Detect: []aggrega.DetectSignature{{ Syntax: "json", Match: []aggrega.PathMatch{{Path: "data.nodes", Is: "array"}},}}},What an import of a directory reads. A source may be a directory, and the importer’s declared file patterns decide what it reads: the host reads exactly the files of the directory, at any depth, that one of the files patterns of the importer’s signatures selects — each matched against the end of the file’s slash-separated path inside the directory — and hands them over as sources in name order, with bytes empty and the directory’s own name as name. No other file of the directory is opened. The folder a build of the workspace writes its rendered files to — dist/ beneath the workspace root — is not read as part of a directory holding it: none of its files is handed over or recognised, and a link leading to it is passed over, so a directory that has been built is read as the project it holds, while a directory that is that folder, or lies inside it, is read as named. A signature declaring no files patterns selects no file of a directory, so an importer that declares none reads one file and refuses a directory, and a directory holding no file its patterns select is refused too. The directory is held to itself: a link among the files it would read, or to a directory, that leads out of the directory is refused before anything is read, a link to a directory is never entered, and a link to a file no pattern selects is passed over unread. Recognising a directory’s format follows the same rule — each signature is tried against the files its patterns select, in name order, each file read and parsed at most once per syntax, and a signature declaring no pattern applies to none of them. The host caps nothing: a directory too large for the importer is refused by the importer’s own runtime limits. None of the compiler’s Langflow, Flowise, n8n, Dify and Agent Framework importers declares files patterns, so each reads one file; its MCP importer declares the four client configurations’ names, so it reads every one of them a directory holds, its Compose importer declares the eight Compose file names, so it is handed every Compose file a directory holds and merges those Compose would read; and its CrewAI importer declares the six names a CrewAI project’s declarations are written under, so it is handed a project’s declarations and none of its program; and its LangGraph importer declares langgraph.json, so it is handed an application’s configuration and none of its code or its environment files, an environment file reaching it only under its attachment’s with.sources; and its Google ADK importer declares root_agent.yaml, so it is handed an application’s root agent configuration and none of its code or its environment file, the configurations its sub-agents name reaching it only under its attachment’s with.sources.
Type definitions. The importer wire types — ImportInput, ImportSource, CatalogProjection, CatalogComponent, CatalogSocket, ImportOutput and the entity, decision and scaffold shapes it carries — are published in all three ABI packages and re-exported by each language’s plugin development kit, generated from one codec so the three stay in lockstep, and so are the recognition types ImporterContract, DetectSignature and PathMatch the describe self-report carries. The Go kit’s importer package, github.com/aggrega-ai/aggrega-pdk/go/pkg/importer, carries everything an importer does whatever its format, and the compiler’s core importers, every one of them built on it, read their input and write their output this way.
What an importer built on the Go kit scores against. The kit’s scorer weighs each source node against the Components of the catalog view and against nothing else: the candidates are the workspace’s own catalog — an enterprise catalog’s Components exactly as the standard library’s — and the kit carries no candidate of its own. Of each Component it reads the name, the category its component.aggrega.ai/category label carries, its labels, and the key names its values declare; its provides keys and sockets are not weighed. A Component added to the catalog is a candidate on the next import, with no importer rebuilt. Where the view is absent, because the catalog holds no Component, no node has a candidate: none is referenced or hinted, and every node the draft gives a Component of its own is drafted. Every importer that scores through the kit scores this way — the compiler’s Langflow, Flowise, n8n and Compose importers among them, while its MCP importer weighs no candidate; an importer that does not use the kit reads the view however it chooses.
What an importer built on the Go kit reads a platform’s sockets for. Sockets weigh nothing in a score, but the kit reads them to lay a draft out. A format whose flows a platform runs as they are written — as Langflow’s, Flowise’s and n8n’s do — is drafted by default as one instance of that platform’s Component carrying the flow, and each part of the flow is wired to the first socket, in the order the platform’s catalog entry lists its sockets, whose selector the labels of the part’s Component satisfy, as the view carries those labels. Only the selector and the labels are read, and the selector is matched by a function the importer supplies, since the kit carries no selector grammar of its own; where the view holds no Component of the platform’s name, no part is wired. Core importers describes the draft the compiler’s Langflow, Flowise and n8n importers make this way, and the layout setting that drafts every node as a Component of its own instead.
Status today: available — dispatched by aggrega import and by the same operation on the editor session and the assistant-facing tool.
Placement criterion: the linter socket vs the governance verdict roles
Two of the documented sockets share a similar surface — both emit per-rule results — but differ in pipeline placement and gating semantics. The criterion for deciding which socket carries a given check:
- The governance verdict roles (in-band, build-halting). Reserved for build-halting policies: a
haltverdict stops the compilation pipeline and the build produces no artifacts. Use cases are policies whose violation makes the output unsafe to apply: compliance gates (PCI / SOC2 boundary placement), topology invariants (zero-trust ingress, cross-boundary auth), credential-flow shape (no plaintext secrets in IR), etc. A policy reasons over the IR graph (ir-verdict, before render) or the rendered artifacts (render-verdict, after render). - The linter socket (out-of-band, CI / IDE, advisory). Reserved for best-practice and discoverability checks: rules whose violation is suspicious but not unsafe — orphaned secrets, unused parameters, deprecated label vocabulary, tag completeness for cost attribution, naming-convention drift. Failure produces advisory output; the build still produces artifacts.
The placement criterion phrased as a single rule: if the check should halt the build, it belongs at a governance verdict role; if the check should warn an author or a reviewer without blocking the pipeline, it belongs in the linter socket.
Both are usable today. The linter socket runs the publishing-linter via aggrega lint; the governance verdict roles are dispatched in-band during aggrega build when a workspace attaches a verdict-role plugin. Note that a verdict role carries its own severities — a policy may itself emit warn and info verdicts that advise without halting — so the halt-versus-advise line above is the placement guidance for whole checks, not a claim that a policy can only halt. See the governance socket page for the severity model.
Cross-references
policy-socket.md— the comprehensive governance-socket treatment: the four roles, verdict severities, the operator input channel, writing a policy for either of the two engines that ship inside the compiler, wrapping a foreign policy engine, and the reference guests.core-importers.md— the compiler’s own importers, one for each format it reads: what each reads, their settings, and their publication with each compiler release.10-status.md#compilation-pipeline-phases— Status page plugin-pipeline classification (Wasm plugin pipeline runtime readiness).architecture/04-entity-taxonomy.md§“Domain 3: Infrastructure Base” — Two-Part Plugin Principle for credential FeatureRecipes (Fetcher + Injector pattern).architecture/13-catalog-and-registry.md— the OCI taxonomy that leads with the provider segment.entities/featurerecipe.md— FeatureRecipepipeline:authoring surface.when-to-use-a-pipeline-step.md— decision guide: a pipeline step vs a templated FeatureRecipe.templates/expansion-matrix.md— the plugin pipeline’spipeline:with:block template-evaluation rules and.stepsaccess semantics.examples/04-secrets.md— the Fetcher + Injector pipeline shape a credential FeatureRecipe can take.errors/error-translation.md— the error-translation discipline plugin guests participate in.