Skip to content
AggregaAggrega
Select language: English

Governance and Compliance

This chapter defines how Platform Teams enforce corporate compliance across every build — through the governance socket, the catalog’s baselines and schemas, and the conventions catalog authors follow — without hardcoding policy into the compiler. Day-2 lifecycle events are the subject of Day-2 Lifecycles.

Enterprise Governance & Compliance Patterns

A core challenge in platform engineering is enforcing corporate governance (such as SOC 2 compliance, FinOps cost-center tracking, and strict ownership mapping) without polluting the open-source catalog.

If Aggrega hardcoded domain-specific logic into its official components, it would cease to be an unopinionated compiler and devolve into an opinionated framework. Conversely, if compliance is left entirely to the developer, critical tags will be misspelled, forgotten, or bypassed.

To solve this, Aggrega provides the Wasm socket mechanisms for compliance, while the Enterprise dictates the policy. Enterprises achieve zero-trust governance by adopting two distinct social contracts within their ecosystem.

1. The “Bring Your Own Baseline” (BYOB) + Wasm Validation Gate

For static, developer-provided data (such as team ownership or data classification), enterprises should never rely on the raw open-source catalog directly. Instead, the Platform Architect authors a corporate baseline — the fields every internal component must carry, declared once in a SchemaLibrary entry — and uses a governance verdict role to enforce its use.

The Catalog Contract: The enterprise creates a baseline that requires specific tags but provisions no infrastructure.

apiVersion: aggrega.ai/v1beta1
kind: SchemaLibrary
metadata:
name: CorporateBaseline
version: 1.0.0
spec:
schemas:
Ownership:
type: object
properties:
owner: { type: string }
cost_center: { type: string }
# The developer MUST provide these, or the schema validator halts the build
required: [owner, cost_center]

Every internal component (e.g., acme/datastore/postgres) references the entry from its own schema: and adds the values that are its own, so the shared fields and the component’s own fields are validated together:

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: acme/datastore/postgres
version: 1.0.0
labels:
component.aggrega.ai/type: stateful-server
spec:
schema:
values:
$ref: "CorporateBaseline#/schemas/Ownership"
properties:
database: { type: string }
required: [database]

The baseline is a library entry rather than a base Component because a Component that writes extends: receives its base’s schema: whole and declares no values of its own (see Inheritance and publishing discipline).

The Wasm Validation Failsafe: To prevent a developer from bypassing the internal catalog and pulling a naked core/postgres component directly from the public hub, the enterprise registers a topological validation plugin. It is evaluated during static analysis — after the graph is assembled and before any artifact is rendered — which is why it sees the whole topology rather than one component at a time.

# Evaluated by the governance ir-verdict role over the assembled graph
package acme.governance
import rego.v1
deny contains msg if {
some id, _ in input.graph.spec.nodes
not input.graph.spec.values_mapping[id].owner
msg := sprintf("node %v declares no owner; use a component whose schema references 'CorporateBaseline#/schemas/Ownership'.", [id])
}

A decision the policy collects under its deny key is a rejection, and the build halts on it.

Forbidding free-form connections: A developer may wire an edge through a socket the catalog did not declare — an ad-hoc socket (see dependency-resolution). That openness is deliberate, and so is the fact that the compiler holds no opinion about it: an organisation that wants every connection to go through a socket its Architects declared expresses that as policy rather than relying on the compiler. Every edge in the graph carries socket_declaration, which reads declared or ad-hoc, so the rule is one line:

# Evaluated by the governance ir-verdict role over the assembled graph
package acme.governance
import rego.v1
deny contains msg if {
some e in input.graph.spec.edges
e.socket_declaration == "ad-hoc"
msg := sprintf("%v connects to %v through the free-form socket %v; declare the socket in the component type's usesSchema.",
[e.source, e.target, e.socket])
}

The value is always present on every edge, whichever way the edge was authored, so a policy never has to read an absent field as “declared”. And it is an axis of its own: it says where the socket came from, not who drew the edge, so it composes with origin_feature and origin_release rather than overlapping them — a policy can forbid free-form connections while still allowing the Release to wire declared ones.

Centralized Enterprise Governance (Evaluating Complete Reality): Out-of-band mechanisms (like CODEOWNERS on a git repository) review the files that change, not the architecture they compile to. The governance verdict roles judge the architecture itself. Because the AOT compiler builds the IR Graph by flattening both the Developer’s Aggregate and the Platform Operator’s Release, a policy at the ir-verdict role evaluates the complete reality before physical artifacts are generated, and one at the render-verdict role evaluates the artifacts themselves. Policies can fatally halt the build if a developer requests an unapproved Component, or — reading the aggrega.ai/recipe-uri provenance stamped on each rendered object — if the Manifest maps a component to an unapproved Recipe.

2. The Wasm Mutator Gate (Dynamic Compliance)

Developers should not be forced to manually type environmental compliance tags (e.g., environment: production or soc2_in_scope: true) into their Aggregate, as these change depending on the GitOps target.

For dynamic metadata, enterprises utilize the Mutation Gate — the governance socket’s label-transform role, which runs during topology construction. After the graph is expanded, and before static analysis evaluates it, the compiler executes the Wasm plugin the enterprise attached. That plugin reads the Release’s environment, the labels the nodes already declare and the values each node’s instance declares, and names the labels the build’s nodes should carry — so the required metadata reaches the component without the developer typing it (e.g., the label compliance.aggrega.ai/data-class: restricted decided from the Release’s environment, or datastore.aggrega.ai/engine: vector decided from a database’s declared extensions). The values are read-only: the plugin decides labels and nothing else.

A policy at this role names the label — the node, the key, and the value it takes — rather than writing the edit instruction the build applies. The reason matters to whoever authors one: the instruction addresses a label by path, and an Aggrega label key routinely contains a /, which is the path separator, so a hand-written path would address a nested location instead of one label. The build addresses the label the decision names, and the projection of the nodes this role receives puts them one level shallower than a verdict over the whole graph.

# Evaluated by the governance label-transform role, during topology construction
package acme.tagging
import rego.v1
labels contains {"node": id, "key": "acme.com/soc2-scope", "value": "true"} if {
input.compilation_context.environment == "production"
some id, node in input.graph.nodes
node.labels["component.aggrega.ai/type"] == "stateful-server"
}

Because these tags are injected into the standard metadata dictionary in-memory before rendering begins, Wasm rendering plugins can read them to conditionally generate specific physical configurations — hardened AWS or Kubernetes resources, for instance — as artifacts are rendered.

Stating a rule once: governance attachments are workspace-scoped. The two patterns above are authored per component and per Feature, but the governance attachment that enforces them is not. A governance plugin is attached at the workspace configuration’s plugins.governance key, and that attachment binds every build in the workspace. A corporate rule is therefore stated in exactly one place: the platform team attaches the plugin once, and no component, Aggregate or Release has to opt in, mention it, or be edited for it to apply. This is what makes the validation failsafe in pattern 1 a complete answer rather than a per-project convention — a developer who bypasses the internal catalog and requests a naked core/postgres is evaluated by the same attached policy as everyone else, because the policy is a property of the workspace rather than of the component they chose.

A workspace rule rejects; it does not rewrite the developer’s contract. The scope is universal, and the effect is deliberately limited to a verdict. A rule that applies everywhere halts a build that violates it, naming what to fix, and it cannot instead amend the offending component into compliance. That boundary is what keeps the mechanism debuggable at estate scale: a build either matches the rules the workspace declares or stops with a message pointing at the authored line, and rendered output never contains a constraint or a resource that no authored file asked for. Where an enterprise does want the graph changed rather than judged, it attaches a transform role — pattern 2 above — and that change is scoped to what the operator attached it to do, which is why it is an explicit act of the platform team rather than an invisible rewrite.

The practical consequence for a platform team closing the compliance circle: express the shape a payload must have as schema constraints on a corporate baseline, express the cross-entity rules the estate requires as an attached verdict role, and express derived metadata the developer should never type as an attached transform role. All three are declared once and apply to every build, and none of them requires the developer to know they exist.

3. Preserving Domain Intelligence (The Configurations & Safety)

Because the Aggrega compiler is unopinionated, it possesses zero hardcoded knowledge of AI frameworks, token budgets, or memory partitioning. Instead, the generic cloud-native schemas act as an empty vessel. Rather than being hardcoded into the compiler core, highly specialized domain intelligence is distributed across the entire extensible Aggrega ecosystem. It is encapsulated within the Platform Catalog through specialized components, features, and recipes. Developers preserve their specific application intent within their values and uses blocks — strictly governed by the Architect’s schema: declarations (compact form or full JSON Schema 2020-12) and usesSchema sockets — while the physical translation of that intelligence is executed by target-specific WebAssembly plugins.

A. Modeling Domain-Specific Implementations (Validated via Split Schemas)

Platform Architects can leverage the Split Schema pipeline to model any complex architecture, completely independent of the core compiler:

  • Opaque Execution Logic (values): If an enterprise deploys an AI Gateway, the Developer configures the gateway’s own behaviour — on the standard library’s AI gateway, the models map publishing each alias a caller may ask for and the upstream each one resolves to. The core compiler does not parse these concepts. They reside safely in the opaque values payload, strictly validated by the component’s schema: declaration. The compiler simply passes this payload to the Wasm plugin to generate the gateway’s configuration. Controls that several gateway products share, such as a fallback chain, a retry count or the choice between entries publishing the same alias, are Features attached to the gateway rather than values on it, each realized for a gateway in that gateway’s own terms.
  • Topological Dependency Mapping (uses): Where an AI framework wires an agent to its tools or to a vector datastore, that wiring dictates who talks to whom, so it is declared in the uses pillar; a list of names kept in values, such as the standard library’s tools_allowed, is a convention that draws no edge. The compiler draws these explicit edges in the IR Graph verbatim. This allows downstream Wasm rendering plugins to programmatically generate the network policies and physical boundaries required to secure the connections, without the compiler understanding the underlying AI framework.
  • Complex Data Structures (e.g., CoALA): Rather than being limited to one flat list of targets, Architects declare as many sockets in usesSchema as a structure needs, each with its own selector and its own per-edge valueSchema. For example, to implement the CoALA framework, an Architect can declare semantic_memory, episodic_memory, and working_memory as distinct sockets, so each memory store is a distinct topological target. The generic policy engines evaluate these structured edges to mandate granular access control guardrails for each distinct cognitive lobe.

B. Core Security & Indirection Mechanisms

While the payload is unopinionated, the generic schema enforces strict structural mechanisms that support secure artifact generation:

  • The Attachment-Not-A-Value Pattern: the standard-library convention is that a credential is requested as an attachment, never written into a values block where it would be an inline literal the compiler carries verbatim. A credential attachment names a credential Feature type (one labeled feature.aggrega.ai/kind: secret) and uses its own values to describe the query against a secret store. Credential routing is then capability-agnostic late binding, and the core compiler never resolves or exposes the material — it pipes the pointer the Ops Recipe supplied. This is a convention the catalog and the schemas encourage, not a compiler check: the compiler does not interpret what a values leaf means, so an author who inlines material inlines it. What the schema does guarantee is that the attachment surface exists and is typed.
  • Abstract Trust Verification: Because the values block is broadly extensible, Architects can mandate abstract directives like tls_pinning or required_signatures: 2 (for Quorum consensus). The core compiler passes these schema-validated objects into the flat IR graph verbatim. A custom Wasm rendering plugin can then read these values to generate artifacts for hardware-level Human-in-the-Loop (HITL) approval gates. If an application attempts to bypass consensus rules, the physically deployed proxy blocks the execution until a webhook approval is received.

C. Advanced Operational Safety (spec.interoperability)

To protect fragile workloads from conflicting infrastructure mutations, the generic Feature schema defines an interoperability control:

  • spec.interoperability.conflictsWith — a list of the Features that cannot reach the same component as this one. The compiler halts the build before rendering when the attachments one component ends up with — gathered from every scope that reaches it: the component itself, a subsystem or boundary holding it, its Release component entry, and annotation-driven expansion — hold this Feature and one it names. It is a comparison of the names the Feature’s author declared against the Features the component carries, with no meaning read into either: the incompatibility is the author’s judgement, and the compiler holds a build to it. One declaration is enough, names are matched whatever their versions, and two Features attached to sibling boundaries that share no component never meet.

4. Network Boundary Governance (Default Deny Convention)

Developers do not write network policies directly; the required network boundaries are mapped by the compiler’s Intermediate Representation (IR) graph, which carries every topological edge between components declared in the Aggregate.

  • Internal boundaries. The compiler draws the flat IR graph and restricts nothing itself: without a policy, every connection the cluster’s network allows stays reachable. The convention is that a policy written for a component allows a connection only where the Aggregate declares an edge for it, beside what the policy’s own attachment names, and denies every other connection in the direction the policy governs.
  • The standard-library realization. The standard-library catalog realizes the convention as two Features the operator attaches to a component in the Release, one for each direction of a connection: core/caller-allowlist admits connections only from the components whose uses edges point at it, and core/egress-allowlist lets the component connect only to the components its own edges point at and to the cluster’s DNS. On the helm target each is realized by a FeatureRecipe that writes a Kubernetes NetworkPolicy from the edges the compiler hands it, naming each component’s pods from what that component’s own render emitted — the selectors and labels its workloads carry, the namespace they are emitted into and the ports their containers declare — so no label or port is restated by hand. Each also admits the component’s own pods and what the Release names on the attachment: sources outside the Aggregate on the inbound side, and on the outbound side address ranges for a target the cluster does not run, which renders no pods to select and is admitted only by range, on any port. The compiler cannot inspect the cluster, so each halts the build until the Release affirms that the cluster’s network plugin enforces network policy; compose has no network policy, and a build attaching either there halts.
  • Public ingress (agnostic perimeter control). Public ingress is governed by the enterprise’s custom rules at a governance verdict role. A corporate security team can author a policy that evaluates a node’s cloud-native ontology type and rejects the build if a developer attempts to attach a public-ingress feature to a worker or task node. The compiler does not interpret what “public” means; it enforces the Boolean output of the Wasm validation gate.

5. Compile-Time Provenance Stamping

The compiler builds a provenance record during compilation, capturing the compiler version and the versions of the Aggregate, Manifest and Release it compiled — and no timestamp, so the record never breaks byte-identical output. The helm renderer emits the compiler version as the aggrega.ai/compiler-version label on generated Kubernetes manifests, and the helm-chart renderer on the template files a Recipe adds to a chart, since it copies the chart’s own templates unchanged; enterprise security teams use this to identify which rendered artifacts were built by which compiler version — important when a vulnerability is discovered in a specific compiler release and the affected artifacts need to be audited.

The compose provider stamps the same provenance keys as service labels, the terraform provider as a provenance file in each module it assembles, and the cloudformation provider under each resource’s Metadata; the in-memory provenance record exists for every compilation.

6. Metadata and Annotations as the Extension Surface

The Go compiler is agnostic to domain-specific concepts — AI frameworks, database engines, Kubernetes idioms — and works only on flat graph-level operations against the IR. To drive the ecosystem without hardcoding domain-specific logic into the Go binary, the platform uses standard metadata labels and annotations as the extension surface for domain intelligence.

The compiler reads no domain-specific annotations. It bundles all developer-provided annotations and duck-typing labels into the flat IR graph and passes this metadata verbatim to the governance and rendering plugins. The WebAssembly ecosystem interprets the metadata and executes the required logic — evaluating compliance policies, injecting tags into cloud-native artifacts, or triggering feature expansion — independently of the core compiler.

This keeps the extensibility surface wide (anyone can author a Wasm plugin that reads a new annotation prefix) while keeping the core compiler stable: no core release is required for the ecosystem to add a new domain-specific annotation.

What a policy reads about an attachment

A verdict role evaluating the IR graph receives the graph whole — every value an author declared sensitive withheld, as described below — and that includes every attachment each node carries, keyed by the name the author gave it — or, for an attachment written on one of the node’s connections, by the connection’s alias and the slot joined by a dot. The point of carrying attachment detail rather than a summary is that Aggrega has no opinion to summarise: the compiler routes attachments without judging what they hold, so the facts a policy needs to judge them are the facts a policy is given.

Per attachment, the graph carries:

  • The Feature type it requests, and the catalog version resolved for it. The type is the string the author wrote, verbatim — a version-pinned reference and a bare one are different strings for one referent, so a policy that compares types should expect either spelling.
  • The attached Feature’s catalog labels, verbatim. Unfiltered, unnormalised, in the order the catalog entity declares them. A policy reads exactly what the catalog author wrote, including labels of the author’s own invention that Aggrega has no knowledge of.
  • The attached Feature’s catalog annotations, verbatim. The Feature entity’s own metadata.annotations, carried on exactly the same terms as its labels — unfiltered, unnormalised, in the entity’s declared order — so an annotation key in an author’s own namespace arrives as authored. This is a different subject from the annotation that caused an annotation-expanded attachment to exist in the first place: the graph reports that origin separately, and an attachment written in a features: block carries the entity’s annotations while reporting no expansion origin at all.
  • Which declared attachment slot it fills. A featuresSchema slot is filled by attaching a Feature under the slot’s name, so an attachment naming a slot its Component declares reports that slot’s name, and one that fills none reports free. An attachment written on a connection fills a slot the connection’s socket declares, and reports that slot’s name; since a socket admits no other name, it never reports free. The value is the slot’s name rather than a flag, because which binding point was filled is usually the more useful half of the answer.
  • Which connection it was written on, if any. An attachment written on one of the component’s connections carries that connection’s socket and alias, which name the graph edge it is presented on — and through that edge, the component it is presented to. An attachment of the component’s own block carries none. The connection is carried as data rather than left to be read out of the attachment’s name, which holds the alias and not the socket.
  • Whether it handles material an author declared sensitive, and which of its delivery keys carry that material. Both are derived from declarations — a sensitive leaf on a Feature’s schema, a sensitive slot on the consuming Component, whether one it declares for its own attachments or one on the socket a connection is wired through — never from inspecting a value.
  • Its values, its infra, and its delivery mapping, plus whether the attachment was written in a features: block or contributed by annotation-driven expansion — with every value an author declared sensitive withheld, as the next paragraph describes.

A policy is told where declared-sensitive material is, and is never handed the material. Each leaf the graph marks as declared sensitive — in any attachment’s values or infra, whatever scope or connection it was written on, in a boundary attachment’s infra, in a node’s own values and infra, and in a connection’s own values and infra — reaches the policy as a single-key marker, {"aggrega_withheld": "declared"}, in place of the value. The key survives, so a policy still sees which leaves a payload carries; the marking that names those leaves survives, so a policy still sees which of them carry declared material; and every fact listed above arrives as before, along with every value no declaration marks. None of the facts a policy reasons on — what an attachment is, what it fills, what it is presented to, what its catalog entity says about it, and where its secret material travels — is a value an author can declare sensitive, and the material itself is the one thing a policy does not need in order to judge where it goes. It is the same withholding the command line applies when it prints the graph and the daemon applies when it answers an editor’s request for it. Those surfaces hand the values back to a person who explicitly asks; a policy’s copy offers no such request. It applies to the policy’s copy alone: the graph the build renders from is untouched, so no rendered byte changes.

An attachment’s labels bind the compiler in exactly one place, and it is not a policy decision: a slot may declare a selector, and a fill whose labels do not satisfy it halts the build. Past that gate the labels steer nothing — how a value is routed and delivered is the same whichever labels a Feature carries. So a policy reading a label is reading metadata the compiler carried without interpreting, not second-guessing a branch inside it.

A Feature’s catalog annotations bind it in no place at all: no compiler behaviour branches on them, and a slot declares no constraint over them the way it may over labels. They are carried and nothing else.

Rules this makes writable, none of which the compiler makes for you:

  • Forbid free-form attachment. An estate that requires every attachment to fill a declared binding point rejects any attachment reporting free. This is the counterpart of the attachment surface staying open: composition is free by default, and an operator who does not want it free says so.
  • Refuse by-value delivery of sensitive material. Aggrega warns when a declared-sensitive datum travels through a delivery key as a literal, and never halts — the by-value credential family is deliberate. An operator who wants that warning to be a refusal expresses it here.
  • Decide for yourself what counts as a credential. The standard library marks its credential Features with a family label, and reading that label is one way to reason about them. A broader or narrower predicate — an internal label, a naming rule, a set of approved types — is equally available, because the labels arrive rather than a verdict about them.
  • Gate on whatever your catalog records in its own metadata. An estate that keeps review status, data residency or ownership as annotations on its Feature entities can require them of every attachment. A rule keyed on an annotation Aggrega has never heard of works exactly as well as one keyed on a key it ships, because the annotations arrive as authored — which also means a Feature and a Component are judged on the same footing, each by the catalog metadata its own entity declares.
  • Govern what a component presents to whom. A credential written on a connection names that connection, and the connection’s edge names its target, so an estate can refuse a credential presented to a component outside a trust zone it marks with a label of its own — a judgement that needs both ends of the connection, which no fact on the consuming component alone supplies.

A verdict role accepts or rejects; it never rewrites. The build either proceeds unchanged or halts with the verdict’s message, so a policy cannot quietly bring a non-compliant graph into compliance.

Attachment detail reaches a policy evaluating the IR graph. A policy evaluating rendered artifacts receives those artifacts and no graph, which is a property of that input rather than a restriction applied to it: the two stages answer different questions, and attachment topology is not among the questions rendered output can be asked.

Expressing the estate’s rules in a policy language

The patterns above describe what a governance attachment does; this section is about what an enterprise writes to get it. A platform team with fifty rules to state does not want fifty plugins. It wants its rules as content — files it reviews, versions and ships like any other artifact — with one attached engine evaluating them.

That is what a policy-language engine attached to the socket provides, and two of them ship inside the compiler for exactly this purpose: a Rego engine and a CEL engine. An operator attaches one, declares the policy files it should load, and the rules run: no external toolchain, nothing fetched at build time, and no policy logic in the compiler. Evaluation happens inside the WebAssembly guest, which is where all domain intelligence lives.

The same engine serves every governance role, so an estate covers its whole surface with one attached plugin and several attachments of it:

  • Judging the architecture. Attached over the build graph, a policy reads every node, edge and attachment the compiler holds, plus the routing paths enumerated alongside them, and reports what must stop the build. This is where a topology invariant, a cross-boundary authorisation rule, or a credential-flow rule lives.
  • Judging the output. Attached over the rendered artifacts, a policy reads the files the build produced — as text, and as parsed documents where the format was parsed ahead of the policy — and reports on the concrete result.
  • Supplying derived metadata. Attached to shape labels, a policy decides which labels the build’s nodes carry, from the Release’s environment and from what the nodes already declare. This is the mechanism pattern 2 above describes, with the rule expressed as policy content rather than as a purpose-built plugin.
  • Adding a capability the developer did not type. Attached to inject annotations, a policy adds annotations to the build’s components; an annotation under a key the Manifest registers a binding for expands into a Feature attachment, so a corporate rule can supply the wrap a component needs rather than merely rejecting its absence. A decision writes any value an operator could write on that annotation — a string, or an object of subkeys for a binding that routes several — and the build reads it exactly as it reads the same value written in the Release. It may only add: a value that would remove or opt out of an annotation is refused, and an injected value the build cannot route or the bound Feature does not admit is refused naming the plugin that injected it.

A rule reads what the payload carries and reports its decision under a named key:

# Evaluated by a governance verdict role over the assembled graph
package acme.security
import rego.v1
deny contains msg if {
some id, node in input.graph.spec.nodes
node.labels["compliance.aggrega.ai/data-class"] == "restricted"
not node.labels["acme.com/owner"]
msg := sprintf("node %v holds restricted data and declares no owner.", [id])
}

A rule that follows data along the graph reads the routes the payload enumerates. language-reference/examples/policy-data-class-route/ is one, end to end: it halts a build where a component holding data of one class reaches a component of another class along a route with no declassifying Feature attached on it, and the same Aggregate completes when a Release routes that traffic through a gateway carrying core/data-masking. The compiler carries the class label as a string and ranks nothing — the classes, their order and the Features that count as declassifying are the attachment’s settings. The rule is written once for each of three engines — the two compiled into the CLI, and OPA behind the reference adapter guest — each copy on its own, so a build on which two engines disagree shows the disagreement.

A policy’s own vocabulary is preserved. The severities the socket acts on are a closed set, but the names a policy collects its decisions under belong to the policy. The default names are the conventional ones a Rego corpus already uses, and an operator whose policies name their decisions differently declares the mapping in the attachment’s settings — so an estate that already maintains a policy library adopts the socket without rewriting it. The mapping is typed by the schema the plugin declares for its settings, so a malformed one halts the build before any policy runs rather than mis-routing a verdict.

A whole policy library travels as one attachment. A policy set can be attached file by file, or as a single archive carrying its policy files and its data documents together, which the guest opens. An archive that cannot be read is reported as such, naming the file — never as a policy set that reached no decision, because “the library was unreadable” must never be indistinguishable from “the library allowed the build”.

An unevaluable policy stops the build. When a policy cannot be evaluated, the attachment fails and the build halts with a fault naming the plugin, deliberately distinct from a verdict that stops the build. The two cases must not be confused, and neither of them is an allow.

The full authoring surface — the payload each role exposes, the decision keys, the mapping onto severities, and how an archive is attached — is in language-reference/plugins/policy-socket.md.

Inheritance and publishing discipline

Inheritance via extends: is the catalog mechanism that lets Platform Architects build specialised child entities on top of shared baselines. The two catalog kinds part company on their data pillars. A Feature’s parent and child schemas compose at workspace-load time, producing a unified schema with per-leaf provenance. An extending Component authors no pillar content: it writes the literal marker schema: inherited and receives its base’s schema: block exactly as the base authored it, at every depth of a chain.

That is what settles the governance question a shared baseline raises — what constraints a child may declare relative to its base. For a Component the answer is structural rather than policed: the child’s declared contract simply is the base’s, so a base’s constraint cannot be loosened, dropped or retyped by a child, and no publish-time check is needed to keep the baseline intact. A child that legitimately needs a tighter rule than its base declares expresses that as an added entry in its assertions: block, which composes alongside the base’s rules rather than replacing them.

What a child Component does compose is structure: its attachment slots (featuresSchema), topology sockets (usesSchema), self-inject allowlist (inject) and named assertions all merge along the chain, with a redeclared entry replacing the base’s outright.

Rule placement: which rules live in the policy plugin vs the per-Component schema

The publishing-discipline plugin is the home for cross-cutting rules that apply across the catalog: supply-chain rules (e.g., “every Recipe must implements: a Component that exists in the catalog”), enterprise compliance rules (e.g., “every Component with compliance.aggrega.ai/scope: pci-dss must extends: the corporate pci baseline”). These rules cross multiple entities, evaluate the workspace as a unit, or enforce conventions at publish time rather than at build time.

The per-Component / per-Feature schema: declaration is the home for per-entity constraints: per-field types, ranges, patterns, enums; cross-field rules expressed in the dedicated assertions: block. These constraints are local to one entity and travel with it through the catalog.

The split is not arbitrary. A rule like “every required field must be present” is a per-entity constraint that belongs in required: arrays. A rule like “every child entity that extends a pci-dss parent must declare a workspace-level governance label” is a cross-entity rule that the policy plugin enforces. The two rule classes never overlap because they answer different questions: the schema validates “does this instance match its contract”; the policy plugin validates “does this catalog satisfy the cross-cutting rules the workspace requires”.

When authoring a new governance rule, the placement question is: does the rule depend only on a single entity’s content (→ schema or assertions block) or does it depend on the relationship between multiple entities or workspace-level configuration (→ policy plugin). The Wasm-linter pattern is the canonical mechanism for the cross-cutting case; enterprise catalogs may distribute custom policy plugins that consume the same plugin-contract interface as the standard publishing-discipline plugin.

Annotation prefix discipline

The annotation namespace carries origin semantics — different prefixes signal different audiences and different governance authorities. Catalog authors, enterprise platform teams, and the Aggrega platform itself all author annotations into the same flat dictionary; the prefix is what keeps the audiences distinct.

PrefixOriginAudienceMutability
aggrega.ai/ (bare)Reserved: emitted by the Aggrega compiler onlyInternal tooling, provenance stampingNot user-authorable; bare-prefix annotations declared in user content are rejected at publish time
<sub-domain>.aggrega.ai/ (e.g., component.aggrega.ai/, feature.aggrega.ai/, compliance.aggrega.ai/)Catalog conventionArchitects authoring catalog entities; Wasm policy plugins consuming the labelsCatalog publisher authors; consumers read
<enterprise-domain>/ (e.g., acme.com/, my-org.io/)Enterprise overlayEnterprise platform teams; enterprise Wasm pluginsEnterprise authors; the platform compiler ignores them as opaque metadata
<community-domain>/ (e.g., cncf.io/, kubernetes.io/)External ecosystemCross-ecosystem tooling reading well-known labelsCommunity-governed

The bare aggrega.ai/ prefix carries the strongest discipline: it is reserved for platform-emitted annotations only. The compiler emits aggrega.ai/compiler-version, aggrega.ai/component-id, aggrega.ai/recipe-uri, aggrega.ai/boundary-path, and related provenance keys on rendered output; user content that declares an aggrega.ai/<key> annotation directly is rejected at publish time. The discipline prevents user-authored annotations from colliding with platform-emitted provenance.

Sub-domain prefixes under <sub-domain>.aggrega.ai/ are the catalog-convention space. The standard library uses component.aggrega.ai/type (the cloud-native ontology label), feature.aggrega.ai/kind (the operational-vs-credential Feature partition), compliance.aggrega.ai/* (the compliance-axis labels), and similar scoped sub-namespaces. Each sub-domain is governed by a specific catalog audience: component.aggrega.ai/* by Component-entity authors, feature.aggrega.ai/* by Feature-entity authors, compliance.aggrega.ai/* by the compliance-policy audience. Cross-sub-domain reads (a Wasm plugin reading from multiple sub-namespaces) are permitted but rare; each plugin typically scopes itself to one sub-namespace.

Enterprise-domain prefixes (acme.com/..., my-org.io/...) are the platform-extension surface. The Aggrega compiler treats them as opaque metadata; enterprise Wasm plugins consume them. Enterprises author whatever prefix structure fits their governance — flat (acme.com/owner: team-payments), sub-domain (security.acme.com/scope: pii), or hierarchical (org.acme.com/billing-center: finance). The platform does not constrain enterprise prefix layout; the only rule is that enterprise prefixes do not collide with aggrega.ai/ or its sub-domains.

The discipline matters because annotations cascade — annotations authored on an Aggregate’s subsystem propagate to every component in the subsystem, a component instance’s own annotations override its subsystem’s, and a module’s annotations reach the module’s own components; annotations on a Release boundary propagate to every component in the boundary. A provider annotation reaches the rendered output from either side, and where both write the same key the Release’s value is the one applied. Without prefix discipline, an Aggregate-side annotation could silently override a platform-emitted provenance key, or an enterprise annotation could collide with a catalog-convention key. The prefix table makes the audiences explicit and the collision-prevention rule enforceable at publish time.

See language-reference/vocabulary/labels-and-annotations.md for the per-entity annotation surface enumeration and the three-bucket cascade semantics (.context.annotations.release / .context.annotations.catalog / .context.annotations.aggregate).