provides, inject, uses
The Injection Contract & Pre-Resolved Map
Because Aggrega is an Ahead-of-Time (AOT) static compiler, no data flows backward from the live infrastructure during compilation. It is mechanically impossible for the compiler to actively fetch a physical credential (like an AWS secret) and pass it “back” to the Developer’s container environment.
Instead, the platform relies on True Control Inversion. When a developer writes inject: { env: [{ in: ORACLE_PASSWORD, from: "password" }] }, they are not initiating a data fetch; they are dictating a strict contract to the infrastructure.
- The Intent (Domain 1): The Developer declares an abstract interface: “I require a secret. I don’t know where it lives. Just inject it into my environment as
ORACLE_PASSWORDmapping to the catalog’spasswordkey.” - The Compiler Transfer (at rendering): The Go compiler takes the entry
{ in: ORACLE_PASSWORD, from: "password" }and hands it to the Ops Recipe. No physical secret is fetched. - The Plugin Output (Domain 3): The credential FeatureRecipe’s Wasm pipeline generates the precise interlocking artifacts required by the target infrastructure. For example, in Kubernetes, it outputs the
ExternalSecretCRD (instructing the cluster to fetch the vault data) AND executes a JSONPatch against the target Pod to map the resulting local K8s Secret specifically to the developer’s requested"ORACLE_PASSWORD"environment variable. - The Runtime Reality: At runtime, an operator in the cluster simply executes these generated artifacts—fetching the credential and physically mounting it into the container—completely decoupling the physical security mechanics from the AOT compiler.
To deliver this physical reality to the application without violating the Separation of Concerns, Aggrega utilizes the Injection Contract. However, this contract strictly differentiates between custom application code and Commercial Off-The-Shelf (COTS) infrastructure:
- White-Box (Custom Code): The component is a generic worker (e.g., a custom Python agent). The Go compiler and the Ops Recipe have no idea what variables the developer’s custom script expects. Therefore, the Developer dictates the delivery via the
inject:block wherever the code reads names its Recipe does not deliver by default — both for cross-component dependencies (viauses[].injectwithfrom:referencing the target’sprovides) and for the component’s own values (via component-levelinjectwithvalue:literals orfrom:referencing its ownprovides). Which mechanisms are allowed is declared per surface, and the two declarations are separate: the component’s own values are governed by thespec.injectallowlist (e.g.,inject: ["env", "file"]), while auses:edge is governed by the allowlist on the socket it is wired through,spec.usesSchema.<socket>.inject. Dictating a mechanism the governing allowlist does not name halts the build on either surface. - Black-Box (Packaged Compute): The component is a closed system (e.g., Redis, a managed API Gateway). The Ops Recipe already knows exactly how the system consumes its data. Therefore, the Component catalog entity omits the allowlist, which forbids dictation outright rather than narrowing it — omitting
spec.injectforbids component-level self-inject, and a socket declared without aninject:allowlist forbids anyinject:block on an edge wired through it. The Developer simply provides the dependency target viauses, and the platform handles the internal wiring natively via the Recipe’svaluesMapping.
The Deterministic Addressing Rule (Internal Network Physics)
Aggrega’s .context.uses pipe dynamically injects target strings into containers at compile time. Because the core Go compiler is entirely agnostic to physical networking, what counts as a valid address string relies entirely on a Social Contract upheld by Platform Ops, not a compiler function — the compiler pipes whatever deterministic pointer string the Ops Recipe produced into the downstream template context without interpretation.
The Rule: The Ops Recipe must export a deterministic, stable address pointer. The provider does not calculate IPs. Instead, the target’s Ops Recipe should formulate a predictable string and expose it via its provides: contract (e.g., publishing provides.internal_host: "http://agent-b.namespace.svc.cluster.local" in Kubernetes, or an interpolation string like "${module.db.endpoint}" in Terraform, where the module declares a matching output for the value).
Relying on the compiler to fetch post-provisioning dynamic IPs directly violates the AOT execution model. Because the compiler evaluates the topology before the cloud provisions any actual compute, it cannot physically fetch data that does not yet exist. If a service requires a random IP that is only generated after the compute boots, the compiler cannot physically fetch it. The compiler’s only job is to pipe the deterministic pointer string provided by the Ops Recipe, verbatim, into the calling container’s environment variables, leaving the final resolution to the cluster’s DNS or the active IaC state manager.
Enforcing deterministic addressing natively solves cyclic dependencies (e.g., Agent A delegates to Agent B, and Agent B delegates back to Agent A). Because the stable URL or IaC pointer is calculable as a string before either container actually spins up, the compiler safely wires both agents together without introducing temporal race conditions.
(Note: This rule applies to external ingress as well. If an architecture exposes a public API Gateway and requires that URL to be injected back into an internal container, the Go compiler cannot fetch the random cloud-generated URL (e.g., xyz123.execute-api.aws.com) because it does not exist at compile time. Ops must author their Recipe to either map a deterministic custom domain (e.g., api.enterprise.com) or export the native IaC interpolation string, ensuring the AOT compiler has a known reference to safely inject).
The Implementation Mechanics (The Catalog as the API Contract) To implement this without tightly coupling Developers to Ops, Aggrega uses the Platform Catalog (Domain 2) as the strict API contract, utilizing three distinct layers of validation:
- The Credential Feature Schema (labeled
feature.aggrega.ai/kind: secret): Validates ONLY the vault query (path,key). It is entirely agnostic to how the container consumes the data. - The
ComponentSchema (spec.injectAllowlist): Enforces the Black-Box/White-Box rule via thespec.injectfield. Ifspec.injectis present (e.g.,inject: ["env", "file"]), the developer may use component-level self-inject with those delivery mechanisms. Ifspec.injectis omitted, the compiler structurally forbids self-inject — Black-Box components rely entirely on the Recipe’svaluesMappingfor internal wiring. The build enforces it when it resolves the Aggregate, refusing the component’sinject:block and naming the mechanism, distinct from per-pillar content validation underschema:. - The
featuresSchemaMap: Defined in the Component Catalog, this explicitly declares the credential slots the Developer must (or may) use. Each entry specifiesrequired(defaultfalse),injectallowlist ([]= blackbox,[env, file]= transparent), anddescription. Because these keys are stable and contractually guaranteed, the Ops Engineer can directly rely on them to reliably dictate deterministic targets in their Go template (e.g.,existingSecret: "{{ .context.rendered_name }}-{{ .locals.secret_target_admin_password }}"on thehelmtarget), explicitly exporting the name’s suffix via.locals— a local cannot read.context.rendered_name— so the downstream credential FeatureRecipe joins the same two parts and fulfills the requirement without violating AOT execution order. Seeentities/component.mdfor the fullfeaturesSchemadesign.
The Strict Placement Rule: The inject: mechanism is available in three locations in the Developer’s Aggregate:
- Component-level self-inject: As a direct sibling to
values:on a component instance. Injects the component’s own literal values or its ownprovideskeys into the delivery pipe. Only allowed if the Component catalog declaresspec.injectwith the corresponding mechanisms. - Uses-level cross-inject: Inside explicit target definitions within the
uses:block. Injects a dependency target’sprovideskeys into the delivery pipe. - Feature/Secret-level inject: As a sibling to
values:when attaching features and secrets. Injects the attachment’s own resolvedprovideskeys — the resolved credential for a secret, or a feature’s provided values — into the delivery pipe.
All three forms populate the same .context.inject pipe. The Recipe reads a single, unified pipe regardless of how many sources contributed to it.
The inject schema defines standard enums (env, file, arg) for tooling, but leaves additionalProperties open, so a custom mechanism may be named (e.g., ssm_param for AWS Systems Manager Parameter Store). One name is taken: all is the merged view of every mechanism a Recipe reads at .context.inject.all, so an inject block naming a mechanism all halts the build at the document envelope, saying so.
Inject Entry Syntax: Under an inject block, each delivery mechanism — env, file, arg, or a custom one — is a list of entries, and every placement uses the same entry shape. The keyword an entry carries, not the placement it sits in, says what its string is, so an entry reads the same wherever it appears. A mechanism written as a map instead of a list, or an entry carrying both keywords, halts the build at the Aggregate’s document envelope, naming the path in the Aggregate where the shape is wrong.
Entry Keywords (from: and value:):
Each entry uses the in keyword for the local identifier — an environment variable name, a file path, an argument flag — plus exactly one of from: (provides key reference) or value: (literal string). A from: resolves against the provides of the node its placement names: the component’s own in component.inject, the target’s in uses[target].inject, and the attachment’s own in features[<name>].inject:
| Keyword | Meaning | Allowed in component.inject | Allowed in uses[].inject | Allowed in features[<name>].inject |
|---|---|---|---|---|
from: | Resolve against provides | ✅ Own node’s provides | ✅ Target node’s provides | ✅ The attachment’s own provides |
value: | Literal string (supports Go templates) | ✅ | ❌ (value: is not valid in uses[].inject; use component-level inject for self-inject) | ❌ (value: halts the build in an attachment’s inject; use component-level inject for self-inject) |
Examples:
# Component-level self-inject (White-Box custom code)components: my-worker: type: core/python-worker:1.0.0 values: app_token: "xyz" inject: env: - in: MY_TOKEN value: "xyz" # Literal value - in: LOG_LEVEL value: "debug" # Literal value - in: CALLBACK_HOST from: "host" # From own provides (already evaluated) - in: APP_VERSION value: '{{"{{"}} .values.app_token }}' # Go template expanding own values uses: databases: my_db: target: postgres-db inject: env: - in: DB_HOST from: "host" # Provides key from target - in: DB_PORT from: "port" # Provides key from target - in: DB_URL from: "dsn" # From target's providesThe template in APP_VERSION’s value: opens with {{"{{"}} rather than {{: the Aggregate’s whole text is read once as a template, for parameter interpolation, before self-inject resolution runs, and .values does not exist at that point, so the escape puts {{ back for self-inject resolution to evaluate. See Text that carries its own double braces.
Provider-specific note (compose). When uses: edges resolve between compose-targeted nodes, the compose provider derives depends_on entries from those edges. Those entries always use service_started semantics regardless of any target’s health: block; gating them on the target’s health is not implemented. See providers/compose.md for the full inference rules.
The Inject Key Collision Rule: A developer requesting the same delivery key (e.g., the same env var name) from two different sources is a fatal error, not a merge. The compiler detects the collision and halts the build:
| Source A | Source B | Result |
|---|---|---|
component.inject | uses[].inject | ❌ fatal halt — duplicate delivery key |
uses[target_A].inject | uses[target_B].inject | ❌ fatal halt — duplicate delivery key |
component.inject | features[<name>].inject | ❌ fatal halt — duplicate delivery key |
uses[].inject | features[<name>].inject | ❌ fatal halt — duplicate delivery key |
features[A].inject | features[B].inject | ❌ fatal halt — duplicate delivery key |
component.inject (same key twice) | — | ❌ fatal halt — duplicate delivery key |
features[A]’s FeatureRecipe injectMapping | features[B]’s FeatureRecipe injectMapping | ❌ fatal halt — duplicate delivery key across two attachments |
features[A].inject | features[B]’s FeatureRecipe injectMapping | ❌ fatal halt — duplicate delivery key across two attachments |
component.inject or uses[].inject | FeatureRecipe injectMapping | ✅ Legal — interception by design: the mapping’s value replaces that entry |
The table reads every attached Feature the same way, wherever it was attached — on the component, at a subsystem or a Release boundary, by an annotation’s expansion, or on a connection. A FeatureRecipe’s injectMapping renders after every inject: block has delivered, so it is always the later of two claims: it may rewrite what the component or one of its connections delivered, and it may rewrite what its own attachment’s inject: block delivered, but a key another attached Feature already delivered halts the build, naming both.
A Feature attached to a Release boundary whose FeatureRecipe renders once for the boundary (executionScope: boundary) reaches the components the boundary holds through the same route: its injectMapping runs once for each of them, in that component’s context, and is held by the rows above like any other mapping. The compose bridge rewriting a consumer’s host variable to reach its target through its gateway is one such mapping, so another attached Feature that delivered the same variable halts the build, naming both.
To prevent Go template boilerplate in Recipes, the compiler provides both:
.context.uses: The enriched topological edge map (for complex logic, secret references, and origin tracking)..context.inject: A pre-resolved, flattened dictionary where the compiler has already resolved all inject sources (self-inject literals, self-inject provides references, and cross-component provides references) into final string values, then applied FeatureRecipeinjectMappinginterceptions.
The Dual-State Injection Context (Null-Safety vs. Intent Purity) When generating configurations for Modifiers (the FeatureRecipe bound to any attachment, credential or otherwise), the compiler must balance null-pointer safety for Go templates, dynamic network routing, and the preservation of a capability-agnostic graph. To achieve this, the compiler provides a dual-state context to the template:
.inject_raw(The Immutable Intent): Represents the component’s owninject:block exactly as the developer authored it in Domain 1. It is immutable. If the developer omitted the block, this evaluates tonull. Ops utilizes this specifically for logical checks (e.g.,{{ if not .inject_raw }}to apply fallback behaviors). Because it is immutable, it protects Ops templates from false positives if routing features intercept and mutate the physical delivery pipe..context.inject(The Pre-Hydrated & Intercepted Pipe): A parallel, compiler-generated struct representing the physical delivery reality. It starts as a pre-hydrated map (e.g., mappingAPI_HOSTto the target’s base string"backend-instance"). Crucially, this pipe is designed to be intercepted and deep-merged by Features (e.g. network routing) utilizing theinjectMappingblock. By the time the Base Recipe renders, this pipe contains the fully formatted, physically correct strings (e.g. a correct complete network name like"backend-instance.backend-zone.svc.cluster.local"). Its contents are structured asenv,file,arg(plus any custom delivery mechanisms allowed by the Component’s inject allowlists), with a pre-merged.alldictionary combining all mechanisms for convenient whole-pipe serialization..context.self_inject(Which Own Value Each Name Delivers): Read from the same component-levelinject:block as.inject_raw, in the shape.context.uses.<alias>.injectgives a connection’s names: per mechanism, each name the developer wrote maps to the component’s own key its entry delivers —provides.<key>for afrom:entry,values.<key>for avalue:template that reads exactly one of the component’s own values and nothing else, and an empty string for anything else (a literal, two values, a read of anything besides the values). It lets a Recipe running the developer’s own image treat its own variable names as defaults — delivering an own value under its default name only when no entry already maps tovalues.<key>, so a developer who renames one value keeps every other default. That is the standard-library catalog’s convention, not a compiler rule; an enterprise catalog may deliver its components’ own values however it chooses.
Ops utilizes the .context.inject struct exclusively for safe serialization (e.g., {{ toJson .context.inject.all }}) and routing generation, ensuring the physical infrastructure receives the fully resolved coordinates while the developer’s original intent remains perfectly intact in .inject_raw.
Developer YAML Example (Granular Map):
uses: databases: my-postgres-cluster: target: db-main inject: ssm_param: # Agnostic injection paradigm (AWS Systems Manager) - in: MY_DB_HOST # Local identifier from: "host" # Target provides keyThe compiler resolves this at compile-time (mapping to static strings or internal DNS names) and passes the two objects to the Recipe:
"context": { "uses": { ... raw graph ... }, "inject": { "all": { "MY_DB_HOST": "db-main.internal" }, "ssm_param": { "MY_DB_HOST": "db-main.internal" } }}Connection-scoped configuration (values and infra). Beyond delivering a target’s provides via inject, an edge may carry its own configuration — per-connection settings the consuming Recipe reads from the enriched topology pipe:
.context.uses.<alias>.values— developer-authored, declared in the Aggregate’s verboseusesentry, validated against the socket’svalueSchema..context.uses.<alias>.infra— operator-authored, declared in the Release, validated against the socket’sinfraSchema.
The socket (usesSchema[<socket>]) is the Architect’s contract for which connections are possible and what configuration they may carry; values and infra split that configuration by authoring domain, mirroring the values/infra split on components. So an edge has two authors: the developer wires the topology and tunes it with values in the Aggregate, while the operator sets per-connection infra in the Release within the sockets the Architect declared. The Release may also wire an edge into a declared-but-unbound socket to an existing component; it may not retarget a developer-declared edge — see entities/release.md §“Per-edge connection configuration”.
Per-edge configuration is consumer-scoped: it surfaces only in the context of the node that authored the edge (the connection’s source), never in the target’s context. A target’s own rendered output is therefore invariant with respect to the consumers that connect to it. A Feature attached to the target is the one place the connections are visible: its FeatureRecipe reads which components use the target at .context.used_by — each one’s identity, socket, published provides, the namespace and boundary it is placed in, and, for a FeatureRecipe that declares it reads them, the render facts its providers reported — never the connection’s own values or infra. A Feature attached to the consumer reads, the same way, what each of its targets’ renders reported, on that connection’s entry at .context.uses.<alias>.render_facts, where its FeatureRecipe declares it reads them.
Connection attachments (features). A connection may also carry attachments of its own — a credential the consumer presents to the component this connection reaches, say — under features: on its entry, keyed by a slot the socket declares in its featuresSchema. The same two authors split them: the developer attaches on the Aggregate’s connection entry with type and values, and the operator sizes that attachment with infra, or attaches one of its own with type and infra, on the Release’s entry. An attachment on a connection carries no inject block of its own, which is why it is absent from the placement rule above: it is not one of the places a developer dictates delivery.
Each becomes an attachment of the consuming component named <alias>.<slot>, so it is consumer-scoped exactly as per-edge configuration is: its FeatureRecipe renders on the consumer’s side, and the target’s output does not change with it. It is kept out of the consuming Recipe’s .features, which holds only the attachments the component’s own block declares; the Recipe reads it under its connection instead, at .context.uses.<alias>.features.<slot>. A connection a Feature attachment draws carries no attachments. See entities/aggregate.md §“A connection’s own attachments” and entities/component.md §“Topology Sockets”.
A. Environment Variables (env) & Dynamic Destination Resolution
The standard delivery mechanism for modern cloud-native applications. For explicit topological edges (e.g., an Agent talking to a Database), Aggrega uses .context.uses to inject the environment variable mapping.
- Use Case: Receiving deterministic internal DNS names, Infrastructure-as-Code interpolation strings (e.g.,
${module.db.endpoint}), or static Vault pointers. The compiler wires these static references AOT so the runtime infrastructure or GitOps controller can resolve the live values.
B. File Mounts (file)
Many enterprise AI frameworks expect a structured config.json or .pem certificate to exist at a specific path on the disk, rather than relying on environment variables.
-
Use Case: Injecting complex JSON configurations or satisfying legacy SDKs that read from disk.
-
Dev Intent:
features:openai_key:type: core/aws-secrets-managervalues:path: /prod/ai/openaikey: "api_token"inject:file:- in: "/etc/secrets/openai.json" # Local pathfrom: "api_token" # The attachment's provides key -
Ops Reality: The Ops Recipe dynamically generates the Kubernetes
Volume,VolumeMount, andExternalSecretrequired to securely pull the vault data and mount it to/etc/secrets/openai.json.
C. Command-Line Arguments (arg)
Pre-compiled binaries (like Rust or Go worker nodes) often bypass environment variables entirely, expecting values to be passed as runtime flags in their execution command.
-
Use Case: Appending physical realities to the container’s startup command.
-
Dev Intent:
features:public-ingress:type: core/external-ingressinject:arg:- in: "--callback-url=" # Local flagfrom: "hostname" # The attachment's provides key -
Ops Reality: The hostname is the environment’s name for the component, so the operator writes it,
api.enterprise.com, in this attachment’sinfraon the Release’s entry for the component. The Feature’s Wasm plugin receives the resolved public URL via the Injection Contract and emits a JSONPatch to dynamically append the Kubernetesargsarray:["/app/binary", "--callback-url=https://api.enterprise.com"], completely bypassing the Component’s Base Recipe.