Skip to content
AggregaAggrega
Select language: English

Manifest

The conceptual role of the Manifest entity (Domain 4 — the mapping table binding abstract interfaces to concrete Recipes) lives in architecture/04-entity-taxonomy.md. This page covers the Manifest authoring surface: how it sits alongside the Release, the flat-URI mapping shape, composition via extends, URI shorthand rules, annotation-driven Feature bindings, and the platform-reserved aggrega.ai/ prefix.

Manifest vs. Release: Concern Separation

The Manifest and the Release carry non-overlapping responsibilities:

  • The Manifest dictates which Recipe realizes each catalog type, and through that Recipe’s spec.capability the provider (e.g., Helm, Helm-chart, Compose) that renders it. It is the mapping table — a per-project Git-committed record of which concrete Recipe implements each abstract interface; the versions and digests a build holds those Recipes to are pinned separately, in each Release’s lockfile.
  • The Release dictates the destination (e.g., the physical output folder for GitOps artifact generation). It is the deployment router — a per-environment description of where the compiled artifacts land.

The Release schema carries no provider field at any nesting level; provider dispatch belongs exclusively to the Manifest.

The compilation path. When a user runs aggrega build --release release.yaml, the compiler resolves physical artifacts by joining both sources:

  1. Read destination. The compiler scans the Release’s boundaries — for example, boundary ovh-cluster-3 contains the component user-db (type: core/postgres:1.0.0).
  2. Scan Manifest. It opens the Manifest the Release points at via its manifest: field.
  3. Two-tier lookup. It checks the name tier for "user-db" first. If not found, it checks the type tier for "core/postgres:1.0.0" (versioned), then "core/postgres" (unversioned).
  4. Resolve the Recipe. The matching entry’s value is a Recipe URI; the Recipe it names declares in spec.capability which provider renders it.
  5. Output generation. The compiler now knows the target folder (dist/boundaries/ovh-cluster-3/), the provider (Helm rendering via Wasm), and the artifact (the Recipe’s source code). Ahead-of-time GitOps boundaries are respected end-to-end.

Flat URI mapping

The Manifest’s mappings: block is a flat map from component-type URI to Recipe URI (and from feature-type URI to FeatureRecipe URI). The mapping is capability-agnostic at the Manifest level; capability determination flows from each resolved Recipe’s spec.capability field at render time, not from the Manifest’s structural shape. The block organises mappings under two top-level keys:

  • components.type maps a component-type URI to a Recipe URI. Every component instance of the declared type resolves to the specified Recipe. The mapping is one-to-one per component-type. A key that does not name an instance’s exact type still reaches it by the type’s base, when no key names that exact type and no other key is written for the same base — so a key written without a version (core/postgres), or one naming another version (core/postgres:1.0.0), can reach an instance of core/postgres:2.0.0 — but the Recipe it names must implement each such instance’s own version: an instance of core/postgres:2.0.0 reached that way and mapped to a Recipe declaring implements: core/postgres:1.0.0 halts the build. Map such an instance with a key naming its version (core/postgres:2.0.0) to a Recipe that implements it.
  • features.type maps a feature-type URI to a FeatureRecipe URI. Every Feature attachment of the declared type resolves to the specified FeatureRecipe. Credential Features (labeled feature.aggrega.ai/kind: secret) live in the same features.type map as operational Features — the unified Feature entity model.

Each block also accepts a name tier alongside type, mapping a specific instance name to a Recipe (or FeatureRecipe) URI. The name tier takes precedence over the type tier: an instance named in components.name resolves to that Recipe, while every other instance of the same type resolves through components.type. This expresses a per-instance override — two instances of one component type can deploy through two different Recipes (for example, most database instances use the bulk-mapped Recipe while one instance is pinned to a different physical implementation), without forking the component type or duplicating the Manifest. The override applies uniformly: the named instance both renders through and pins its source from the override Recipe. features.name is the symmetric tier for Feature attachments, keyed by the attachment’s own name — the key it is written under in a component’s features: — never by the name of the component it is attached to. The per-instance recipe override example walks a minimal two-instance case end to end.

An attachment a connection carries is keyed by the name it takes on the consuming component: <alias>.<slot>, the alias the connection is written under, a dot, and the slot the attachment fills (see the Aggregate’s connection entry). So one connection’s credential can be realized differently from every other attachment of its type:

spec:
mappings:
features:
type:
core/referenced-secret:1.0.0: helm/k8s-secret-from-parameter:1.0.0
name:
# The credential the "gpt" connection carries in its "credential" slot.
gpt.credential: helm/k8s-external-secret:1.0.0

The entry is pinned and verified like any other name-tier entry, as the next paragraph describes. The Feature the attachment names is pinned and verified too, exactly as the Feature of an attachment written on the component itself is, under the connection entry its author wrote — see The lockfile.

A name key has to name something the build holds. The tier is matched by exact name, so a components.name key that is not a component instance in the build, or a features.name key that is not an attachment in it — most often the name of the component an attachment sits on, written where the attachment’s own name belongs — would be consulted by nothing, and the instances it was meant for would quietly resolve through the type tier. The build halts on such a key instead, before anything renders, naming the Manifest, the key, the names of that kind the build does hold, and the name you probably meant — see A Manifest name mapping names nothing in the build.

A realization bound by name is pinned and verified like one bound by type. aggrega pull acquires every Recipe and FeatureRecipe either tier binds — from a catalog directory, the cache or a registry — and records each in the Release’s lockfile with its resolved version and content digest, under the mapping entry that binds it: manifest.spec.mappings.components.name.<instance> for a name-tier entry, beside manifest.spec.mappings.components.type.<type> for a type-tier one. aggrega build holds every one of them to its pin. A lockfile that records no row for a realization the Manifest binds halts the build as out of date, naming the realization and the entry that binds it; a realization whose content changed since the pull halts it the same way, naming both digests. In both cases aggrega pull --release <release> records the realization as it now stands. Like a type entry, a name entry is pinned whether or not the Release declares an instance of that name, so a name entry naming a Recipe no catalog or registry holds halts the pull; a name entry naming no instance the build holds is pinned too, and halts the build as the paragraph above describes.

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: production-manifest
version: 1.0.0
spec:
mappings:
components:
type:
# Component-type → Recipe URI. A Recipe URI is at most two segments: an
# optional leading capability, then the recipe name. The bare one-segment
# form (last line) is the common case.
core/datastore/postgres: helm/postgres:1.2.0
core/api-server: helm/api-helm:0.5.0
core/python-worker: standard-python-worker:2.0.0
features:
type:
# Feature-type → FeatureRecipe URI. Credential Features (e.g., aws-secrets-manager) sit alongside operational ones.
core/data-masking: helm/data-masking-litellm:1.0.0
core/aws-secrets-manager: helm/eso-aws-fetcher:1.0.0

Capability determination at render time. The Manifest entry binds a component-type to a Recipe URI. A Recipe URI carries at most two segments — an optional leading capability, then the recipe name — plus an optional :version; the resolver splits on the first / only, so a reference with a third segment names no recipe and halts resolution. At render time, the resolver loads the Recipe via direct URI lookup against the lockfile and catalog, and each Recipe’s spec.capability field determines the per-(path, capability) dispatch grouping. The Manifest’s structural shape stays flat regardless of how many providers the broader catalog supports.

Direct URI lookup

The Manifest’s mapping value is a Recipe URI. The compiler resolves the URI directly against the lockfile and catalog, returning the matching Recipe. It does not iterate spec.implements declarations to find a Recipe that “implements” a component-type. Each Manifest entry binds the developer’s authored component-type to a specific Recipe URI; the choice is explicit and unambiguous in the Manifest content.

spec.implements is a consistency check over the mapping table. The resolved Recipe’s spec.implements value MUST match the Manifest’s component-type key for that mapping entry — or a base that key extends, at any depth of the chain, since a Recipe written against a base implements everything extending it. A value matching neither produces an OPS_ERROR with a clear diagnostic naming the Manifest entry, the resolved Recipe, and the conflicting spec.implements value. The check fires once per Manifest mapping entry, over the composed Manifest and before any Recipe is resolved — static, deterministic, and walking nothing beyond the mapped type’s own extends chain. A components.type key that reaches a component instance at a version it does not name is judged once more for that instance, the same way, with the instance’s own type at the version the build compiles it as standing where the key stood, as Flat URI mapping describes. See ../vocabulary/inheritance-and-interface.md for what a base’s Recipe does and does not spare a specialization.

Every command that reads a Release’s dependencies runs it, and each decides for itself what a finding means: aggrega build and aggrega pull halt, since both produce something you would go on to use, while aggrega validate and aggrega lint report it with the rest of their findings and exit non-zero, and the editor publishes it as one diagnostic among the others. aggrega lint is the exception for the judgement of an instance: it judges the mapping entries and not the instances they reach, so it does not report it, while aggrega build, aggrega pull and aggrega validate --release do. See ../errors/fatal-halts.md for the diagnostic and how to fix it.

The consistency check is the only mapping surface that reads the extends chain. Recipe selection remains exact on the mapping key: a component type that extends a mapped base still needs its own entry here, and gets no entry by inheritance.

spec.implements also suggests candidates. An instance whose type carries no Manifest mapping halts the build with an OPS_ERROR that lists the recipes whose spec.implements is able to implement that type as pin candidates; editor completion on a mapping value ranks those same matching recipes first. Both surfaces read spec.implements against the requested type itself, so a recipe implementing one of that type’s bases is not offered as a candidate even though the mapping would be judged consistent. spec.implements thus declares what a recipe can implement and informs the human’s choice — in the consistency check, the no-mapping diagnostic, and completion — but it never resolves a build. The Manifest mapping is the user’s explicit deployment choice, pinned in the lockfile for reproducibility; the catalog never chooses a deployment on the user’s behalf.

Three forms for the URI version segment

A Recipe URI in the Manifest may carry the version in any of three forms:

  • Exact — helm/postgres:1.2.0. The lockfile must pin exactly this version; at first lockfile resolve, the resolver pins this version; if the catalog or registry does not contain this version at resolve time, the workspace load halts with an error.
  • Range — helm/postgres:^1.2.0. Semver range with the standard MVS rule; at first lockfile resolve, the resolver pins the highest available version satisfying the range.
  • Unversioned — helm/postgres. No :version suffix; at first lockfile resolve, the resolver pins the latest available version.

Subsequent builds use the lockfile-pinned version regardless of the user-typed form. Re-resolving to a newer version requires explicit user action — aggrega pull --upgrade --release <release> <uri> re-resolves a single dependency while holding every other pin, or aggrega pull --upgrade --release <release> re-resolves all — the lockfile is the source of truth for builds; the user-typed form is how the user expresses the version constraint at authoring time.

Capability-qualified references

Recipe identity in the catalog is capability-scoped: two recipes may share a metadata.name and version while declaring different spec.capability values. The registry identity is recipe/{capability}/{name}:{version}, derived from the recipe’s kind, its spec.capability without any version pin it carries, and its name; the standard-library catalog tree mirrors that coordinate at recipe/{capability}/{name}/ by convention. A Manifest mapping value names the recipe at either precision:

  • Bare — mariadb:1.0.0. Resolves when exactly one recipe in the catalog carries the name; the dominant form in practice.
  • Capability-qualified — compose/mariadb:1.0.0. The segment before the first / names the recipe’s spec.capability, without its version pin — a pin written into the reference is refused (E0095). Required when more than one recipe ships the same name: a bare reference matching two recipes is ambiguous and halts loudly at resolution rather than silently picking one.

A Recipe URI has no further positions. The resolver splits on the first / only, so compose/mariadb names capability compose and recipe mariadb, and a three-segment reference matches no recipe at either precision.

The version-segment forms above apply to both shapes.

Registry-published entities in mappings

An entity consumed from a registry rather than a local catalog is referenced by exactly the same identity a local one uses: the reference carries no registry host and no entity-kind segment. The resolver supplies both — the host from the workspace’s configured default registry, the kind segment from where the reference sits in the schema — per the Context-Aware Shorthand URIs rules below. When neither a local catalog directory nor the cache holds a copy, aggrega pull — or a build run with --auto-pull — fetches the entity from the derived location, caches it, and pins the resolved version and content digest in the lockfile; subsequent builds consume the cache without network access.

# Aggregate fragment — a registry-published Component as the type:
components:
db:
type: core/datastore/mariadb:1.0.0

Because the host and the entity-kind segment are derived rather than authored, writing either into the reference does not address the published entity — it produces an identity no catalog entry carries. A Component or Feature reference is its metadata.name verbatim plus an optional :version, whether the entity resolves from the local catalog, from the cache, or from a registry. A workspace consuming a private registry names that host in its own configuration rather than in each reference.

Completeness check

After all mappings resolve, the compiler verifies that every component and attachment instance (a credential Feature is an attachment like any other) in the developer’s Aggregate has a resolved Recipe or FeatureRecipe. Unmapped entities cause a fatal halt with an explicit diagnostic listing every missing entity and suggesting which components.type or features.type key to add to close the gap.

YAML anchors for DRY manifests

To avoid YAML bloat across large mapping sets, the Manifest supports an optional defs: block for standard YAML anchors (& and *):

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: global-base-manifest
version: 1.0.0
defs:
- &python_worker_recipe "helm/standard-python-worker:2.0.0"
spec:
mappings:
components:
type:
core/python-worker: *python_worker_recipe
core/postgres: helm/postgres:1.2.0

Feature negotiation

The capability handshake uses the same flat-URI mapping:

  1. The developer attaches core/data-masking to a component in the Aggregate, under a name of its own in that component’s features: map.
  2. The compiler looks up core/data-masking in the Manifest’s features.type map.
  3. If the lookup resolves to a FeatureRecipe URI (e.g., helm/data-masking-litellm:1.0.0), the capability exists and the FeatureRecipe’s pipeline executes in the defined order.
  4. If features.type contains no matching entry, the compiler halts the build and lists the unmapped Feature.

The Manifest also accepts a features.annotations block — a parallel authoring surface that lets a Release or Aggregate subsystem attach Features by annotation key rather than by per-component declaration. The binding shape, the side-vs-pillar partition that governs which authoring surface uses which routing paths, the explicit-attachment-wins discipline, and the schema-defaults rule live in the dedicated Annotation-Driven Feature Bindings section further down.

Composition via extends

A Manifest may declare a single extends: reference naming a base Manifest whose mappings it inherits. The reference is not a URI and never resolves through the catalog: a Manifest is deployment-side, authored beside the Release rather than published, so the value is either a relative path to a Manifest file — ./base-manifest.yaml — or the bare metadata.name of a Manifest sitting in the Release’s own directory. A relative path must lead to a Manifest inside the workspace — or, where the Release was named outside the workspace (on the command line, or by the workspace configuration), inside the directory holding that Release, and for a Manifest you name on its own on the command line outside the workspace, inside the directory holding the Manifest: one that climbs out, or that a symbolic link carries out, is refused before the file it names is read (see errors/fatal-halts.md §“A reference to another file leads out of the directory it must stay inside”). Child mappings overwrite the base on key collision, supporting environment-overlay patterns (staging/prod parity with surgical per-environment diffs) and local-development patterns without full-copy authoring.

Merge semantics. When a local Manifest extends a base Manifest, the compiler performs a shallow key replacement per tier — the type and name dictionaries are merged independently, not deep-merged — which guarantees O(1) dictionary lookups and keeps inheritance behavior predictable. Within each tier, child keys overwrite parent keys.

The local-development bridge pattern. A common use of extends is swapping a credential FeatureRecipe for local prototyping without touching the Aggregate. In production, the base Manifest maps the credential Feature core/aws-secrets-manager to a production FeatureRecipe under the features.type tier. For local prototyping, the platform team provides a local-manifest that extends the base and surgically overrides the credential Feature mapping to use host-env-injector — a local FeatureRecipe that delivers the credential into the Compose file as a variable reference such as ${SECRET_NAME}, which Docker Compose substitutes from the shell environment or a .env file when the stack starts. The developer gets a standard local workflow, and the Aggregate remains capability-agnostic for production.

Context-Aware Shorthand URIs

The Aggrega compiler utilizes Context-Aware Inference when resolving OCI URIs in Manifests. If an engineer omits the Fully Qualified Domain Name (FQDN) and the architectural entity type, the compiler automatically falls back to the default registry (configured in .aggrega-config.yaml) and infers the entity type based on where the string is located in the schema.

The Inference Rules:

  1. Domain Default: Any URI lacking a domain (e.g., python-worker-helm:1.0) is prefixed with the configured default_registry (default: hub.aggrega.ai/).
  2. Contextual Entity Expansion: The compiler appends the correct entity path based on the strict schema dictionary:
    • Strings under Aggregate.spec.components[].type expand to /component/.
    • Strings under Aggregate.spec.aggregates[].type expand to /aggregate/.
    • Strings under Manifest.spec.mappings.components.type or Manifest.spec.mappings.components.name expand to /recipe/.
    • Strings under Manifest.spec.mappings.features.type or Manifest.spec.mappings.features.name expand to /featurerecipe/. This includes credential Features (labeled feature.aggrega.ai/kind: secret) — they use the same FeatureRecipe path.
    • Strings assigned to pipeline[].plugin expand to /plugin/.
  3. Three-Tier Precedence: Before applying the OCI inference, the compiler searches the workspace’s catalog directories and the artifact cache (the workspace and cache tier) as defined in the Three-Tier Entity Resolution Model. OCI inference only applies when the entity reaches the registry tier. A mapping key or value is never read as a file path: a Recipe or FeatureRecipe authored locally sits in a catalog directory — catalog/ at the workspace root, or one workspace.catalog_dirs lists — and is named by its reference.

The Shorthand in Action:

# Capability-qualified — required when two recipes share the name "postgres":
"core/postgres": "helm/postgres:2.0"
# Bare — resolves when one recipe carries the name:
"core/postgres": "postgres:2.0"
# Found in a local catalog directory or the cache; failing both, `aggrega pull`
# (or a build run with --auto-pull) fetches it from the registry location derived
# from the configured default registry and the Recipe kind.
# A private registry is named in workspace configuration, not in the reference.

No ops/ prefix. Recipe names carry no ops/ prefix — the recipe/ entity type directory in the OCI taxonomy already identifies the domain, and Recipes ship under recipe/{capability}/{name} without additional prefixing. Manifests reference Recipes by {capability}/{name}, or by the bare name for context-aware inference. See architecture/13-catalog-and-registry.md §6 for the full OCI taxonomy.

Annotation-Driven Feature Bindings

The Manifest’s features.annotations block declares bindings between annotation keys and Feature types plus the routing paths each binding sends the annotation value through. The binding is the authoring surface for compressing repetitive per-component Feature attachments — the pattern where dozens of components across a boundary each carry an identical features: block — into single annotation declarations on Release boundaries or Aggregate subsystems.

Schema shape:

spec:
mappings:
features:
type:
core/rewrite-host: helm/rewrite-host-helm:1.0.0
core/db-pool: helm/db-pool-helm:1.0.0
annotations:
feature.aggrega.ai/rewrite-host:
feature: core/rewrite-host
maps:
infra:
- upstream # Release-side: routes annotation value into infra.upstream
feature.aggrega.ai/db-pool:
feature: core/db-pool
maps:
values:
- pool # Aggregate-side: routes annotation value into values.pool

A binding carries a feature field naming the target Feature type and a maps block grouping dotted-path subkey routes by target pillar. The feature field references a Feature type that must also appear in the sibling features.type section (which is where the FeatureRecipe version binding lives). The maps block declares two pillar-keyed lists — maps.infra and maps.values — each carrying dotted-path strings that point into the target Feature’s spec.schema.<pillar>.<path> properties. A binding must declare at least one path across the two lists (the JSON Schema enforces minProperties: 1 on maps).

Provider polymorphism for the same annotation key — e.g., feature.aggrega.ai/rewrite-host binding to core/k8s-dns-resolver in a Kubernetes deployment but to core/compose-bridge in a local Compose deployment — is expressed by choosing different Feature types in different Manifests; each Manifest binds the annotation to one Feature, and the chosen Feature’s FeatureRecipe carries the provider-specific implementation.

The side-vs-pillar partition. The Aggregate-as-Authoring-Surface invariant restricts each authoring side to one pillar’s routing paths. Aggregate-side annotations route only through maps.values paths; Release-side annotations route only through maps.infra paths. A binding declaring paths in both pillars supports cross-side composition: an Aggregate-side annotation fires the values-pillar subset; a Release-side annotation against the same key fires the infra-pillar subset; both contributions compose into one Feature attachment per (Component, Feature) pair with both pillars populated. A side-vs-pillar mismatch — e.g., an Aggregate-side annotation against a binding declaring only maps.infra — halts the build with a clear diagnostic naming the annotation key, the routed pillar, the authoring side, and the source location, filed under the domain of the document the annotation value was authored in.

Path-target validation. At catalog load, the compiler verifies that every dotted path declared under maps.infra and maps.values corresponds to a property the target Feature’s spec.schema.<pillar> actually declares. A binding routing to a path the Feature schema does not list halts catalog load with a clear OPS_ERROR, naming the binding, the target Feature, and the pillar and path it routed through. Schema shapes that escape simple property-walk ($ref, patternProperties, oneOf / anyOf / allOf composition) terminate the static check at that branch and let downstream schema validation catch any mismatch.

Annotation value shapes. A binding consumes annotation values in three shapes. Scalar — a single YAML value (string, number, boolean). A scalar paired with a binding declaring exactly one path across both pillars routes the value to that single path; a scalar paired with a binding declaring more than one path is ambiguous routing and halts the build with a clear diagnostic, filed under the domain of the document the annotation value was authored in. Structured — a YAML map whose top-level subkeys each match a dotted-path entry under maps.infra or maps.values; each subkey routes to its declared pillar independently, and the side-vs-pillar partition applies per subkey. Explicit YAML null — opts out of the inherited binding at the cascade scope (with per-subkey null inside a structured value opting out of individual subkeys while siblings stand). For the canonical authoring teaching on structured values — cascade merge per subkey, cross-side composition, per-subkey type validation, the relaxed-default discipline for schema fields without a declared type — see providers/well-known-annotations.md §“Structured annotation values”.

Explicit attachment wins on key collision. When a Release component or Aggregate component carries both an explicit features: entry and an annotation that expands to the same Feature key, the explicit entry is preserved and the annotation expansion for that key on that component is a no-op. The synthetic attachment never overwrites an author-declared Feature instance. Authors can therefore use annotation expansion for the bulk of components and surgically override individual components by writing an explicit features: entry with the same key — the explicit entry carries the per-component customization, the annotation cascades to every other component unchanged.

Per-leaf explicit-wins on cross-side composition. When an explicit attachment and an annotation contribution both populate the same Feature instance but write to different leaves, both contributions stand and the resulting Feature carries both leaves with per-leaf provenance recording each leaf’s source. When an explicit attachment and an annotation contribution target the same leaf within the same pillar, the explicit contribution wins and the IR records the suppressed annotation provenance as an override marker on that leaf. Catalog load surfaces this override at build time via an advisory lint warning naming the suppressed annotation key + source.

Schema defaults at expansion time. The synthetic Feature attachment produced by annotation expansion carries only the leaves the annotation value populates through the binding’s declared paths. Schema defaults declared on the target Feature’s spec.schema are not merged into the synthetic attachment at expansion time. Default-value materialization is the FeatureRecipe rendering layer’s responsibility, applied uniformly to explicit and synthetic attachments so the two paths produce the same downstream output for the same effective configuration.

Annotation namespace separation:

PrefixOwnerPurpose
aggrega.ai/Aggrega platform onlyPlatform-native annotations read directly by the provider (e.g., aggrega.ai/namespace).
feature.aggrega.ai/Official standard libraryFeature-annotation shortcuts bound in the Manifest.
{any-other-domain}/Enterprise / communityCustom Feature-annotation shortcuts.

aggrega.ai/ Prefix Reservation

Manifest features.annotations bindings cannot use the bare aggrega.ai/ prefix — it is reserved for platform-native annotations emitted by the compiler (OTel/provenance labels, etc.). Scoped sub-prefixes (component.aggrega.ai/*, compliance.aggrega.ai/*, enterprise acme.aggrega.ai/*) remain available for user authoring. See providers/well-known-annotations for the platform-reserved annotation set.