Path-Template Variables
The directory: and subDirectory: fields on a Release boundary are Go templates evaluated at build time. They control where rendered artifacts land on disk and, by extension, which artifacts assemble together — two boundaries that evaluate to the same (path, provider) tuple share an assembler and produce one merged output (one Chart.yaml, one docker-compose.yaml). This page is the authoring reference for the variables those templates can reference, the strict evaluation semantics, and the cascade rules that let boundaries inherit from their parents.
For the conceptual treatment of spatial segregation and per-(path, provider) dispatch, see architecture/16-recipe-input-composition.md. For the entity-level Release authoring surface, see entities/release.md. The provider-side consequences live in providers/architecture.md and the per-provider pages.
Strict evaluation: missingkey=error
Path templates are evaluated with Go’s missingkey=error mode. A reference to an undeclared field, an unset parameters.X key, or a typo such as {{ .parmaeters.region }} produces an explicit error rather than silently rendering an empty string into a path.
The strictness is asymmetric with the rest of the compiler — valuesMapping, injectMapping, and other value-render surfaces use missingkey=zero per Helm/Sprig convention. Path emission is structurally different: a value-render template that produces an empty string lands in a manifest field where the consequence is bounded; a path template that produces an empty string lands in a directory layout where the consequence is unbounded (collisions, broken assembly, ghost paths). The strict path-template regime exists to surface those failures at build time rather than at deploy time.
Parse-time allowlist validation
In addition to runtime strictness, path templates are validated at parse time against a closed allowlist of variable names. A reference to a variable name not in the allowlist halts the build before any rendering work begins, with a diagnostic naming the offending field and the boundary it appears on.
The allowlist is closed by design: surfaces such as .context.inject, .values, and .locals are deliberately not exposed to path templates. Path emission is a structural concern, not a value-rendering concern; tying assembly paths to per-component values would make the path graph data-dependent and erode the deterministic-output invariant.
The variable matrix
| Variable | directory: | subDirectory: | Description |
|---|---|---|---|
{{ .capability }} | yes | yes | The rendering capability (helm, helm-chart, compose, terraform, cloudformation) the contributing component’s Recipe declares, for the artifacts emitting at this path. |
{{ .boundary_name }} | yes | yes | The boundary’s authored name in the Release (e.g., production, eu-prod). |
{{ .parameters.X }} | yes | yes | Any typed parameter declared on the Aggregate and fulfilled by the Release. Strict access — referencing .parameters.unknown halts the build. |
{{ .manifest.recipe_name }} | yes | yes | The Recipe name resolved through the Manifest for the contributing component. Useful for routing per-Recipe artifacts into per-Recipe sub-folders. |
{{ .parent_boundary.* }} | yes | yes | Cascade access to the enclosing boundary’s evaluated values. See Parent-boundary cascade below. |
{{ .component_id }} | — | yes | The contributing component’s instance ID. For a Feature attached at a boundary whose FeatureRecipe runs once for the boundary (executionScope: boundary), it is the composed identity that attachment’s resources carry in their aggrega.ai/component-id label — bfr--app--shared for an attachment shared at boundary app, shortened where the attachment’s provider bounds names — so the attachment’s output lands in a directory named after that label. Available in subDirectory: only because directory: is a per-boundary property — the directory string is computed once per boundary, before any per-component routing happens. |
The directory: field defaults to boundaries/ followed by the boundary path (a stable build-time identifier derived from the boundary tree); a Release that lists its components without declaring boundaries writes them with no directory segment at all. The subDirectory: field defaults to {{ .capability }} so that each capability’s artifacts land in their own sub-folder under the boundary’s directory — whether it is omitted or written as subDirectory: "", which reads exactly as an omitted one. Setting subDirectory: ".", or writing a template that evaluates to an empty string, flattens that grouping.
What these templates do not decide: artifacts: placement
One segment of the output path is not a path template’s to set. A file a Recipe’s artifacts: block names is written under a directory named for the component that declared it, inside whatever subDirectory: evaluates to. That segment is fixed and always present, for a target that writes its contributors’ files side by side rather than nesting each contributor in a chart or a module of its own.
The reason is what names the file. A manifest a target renders or synthesizes is named by the target from the component it belongs to, so it already identifies its component. An artifact is named by the key its author wrote — app-config.yaml, netpol.yaml — and that key says nothing about the component, because the Recipe declaring it does not know which components will be bound to it. Two components in one boundary bound to one Recipe would write one path, and neither the Recipe author nor the Release author has a surface on which to separate them.
Only the directory is added; the filename stays the authored key, so the file an author reads back in the output carries the name they wrote.
What subDirectory: still buys, and how the two compose. subDirectory: moves every file a contributor emits — rendered manifests, synthesized manifests and artifacts together — so it is the tool for giving one component a directory of its own for downstream tooling that operates on a single component’s whole manifest set, or for routing several components into one shared folder. The artifacts: segment applies underneath whatever it evaluates to. Writing subDirectory: "{{ .capability }}/{{ .component_id }}" on a component whose Recipe declares artifacts: therefore produces the component’s name twice — the artifact lands at <capability>/<component>/<component>/<key> while that component’s rendered manifests land at <capability>/<component>/<key>. Reach for the override when you want the component’s whole output gathered, and leave it off when separating the artifacts is all you need, which the default already does.
.capability is resolved per component, and a boundary’s directory: is evaluated for two distinct purposes. The per-boundary evaluation that publishes .parent_boundary.directory to child boundaries runs before any component is bound, so .capability is empty there. The per-component evaluation that fixes where a contributor’s artifacts actually land carries that component’s capability. A parent authoring directory: "d-{{ .capability }}" therefore publishes d- down the cascade while its own artifacts land under d-compose.
Parent-boundary cascade
Nested boundaries receive a .parent_boundary view exposing the immediate parent boundary’s evaluated path and its own cascade-resolved data. The cascade is one level — a boundary’s .parent_boundary is its direct parent, not the grandparent. To reach further up, the parent boundary itself uses .parent_boundary in its own templates, propagating values down the tree explicitly.
Available fields under .parent_boundary:
| Field | Description |
|---|---|
.parent_boundary.directory | The parent boundary’s evaluated directory: value (post-template). |
.parent_boundary.boundary_name | The parent boundary’s authored name. |
.parent_boundary.parameters | The same .parameters.* map the parent boundary saw (parameter values are Release-global, but the alias is provided for symmetry). |
.parent_boundary.annotations | The parent boundary’s cascade-resolved annotations. |
The canonical pattern: a parent boundary that authors a directory: once, plus child boundaries that route their artifacts under the parent by declaring directory: "{{ .parent_boundary.directory }}". This collapses the children onto the parent’s assembly path, producing one merged output that contains contributors from every child. The core/compose-bridge Feature relies on exactly this: a parent boundary holding the bridge feature, two child boundaries (for example services-net and data-net) sharing the parent’s directory:, and one merged docker-compose.yaml containing every component plus the bridge service.
The mirror inverts: omit .parent_boundary.directory on the children (or evaluate to a distinct path) and each child gets its own assembly. Both shapes are first-class.
Worked layouts
Layout 1 — default per-boundary segregation
spec: boundaries: api-prod: directory: "deploy/api-prod" components: api: {} cache: {} data-prod: directory: "deploy/data-prod" components: db: {}Each boundary evaluates to a distinct directory:, so each gets its own assembly:
deploy/api-prod/<capability>/...deploy/data-prod/<capability>/...The default subDirectory: "{{ .capability }}" segregates per-capability artifacts inside each boundary directory. Two boundaries, two assembly outputs per capability, no merging.
Layout 2 — collapsed assembly via shared parent directory
spec: boundaries: cluster: directory: "deploy/cluster" annotations: aggrega.ai/chart-name: "cluster-umbrella" features: bridge: type: core/compose-bridge:1.0.0 boundaries: services-net: directory: "{{ .parent_boundary.directory }}" annotations: { aggrega.ai/namespace: services } components: api: {} data-net: directory: "{{ .parent_boundary.directory }}" annotations: { aggrega.ai/namespace: data } components: db: {}Both child boundaries evaluate directory: to deploy/cluster (the parent’s directory), so all contributors merge at one assembly path. With the default subDirectory: "{{ .capability }}", the compose contributors from both children land in deploy/cluster/compose/ and produce one merged docker-compose.yaml. The compose-bridge Feature attached at the parent runs once (boundary-scope dispatch) and contributes the bridge service to the same merged file.
The parent’s aggrega.ai/chart-name: "cluster-umbrella" annotation cascades to both children; if the boundaries also held helm-chart contributors, both children’s helm-chart sub-charts would compose under one umbrella named cluster-umbrella. Mismatched chart-name values across contributors at one path halt the build.
Layout 3 — per-component routing via subDirectory: plus parameters
spec: parameters: region: "eu-west-1" boundaries: eu-prod: directory: "deploy/{{ .parameters.region }}" components: api: subDirectory: "{{ .capability }}/{{ .component_id }}" db: subDirectory: "{{ .capability }}/{{ .component_id }}" ingress: subDirectory: "shared"The boundary’s directory: evaluates to deploy/eu-west-1 (parameter substitution). Per-component subDirectory: overrides route each contributor to a per-component sub-folder, with the ingress component overriding to a flat shared sub-folder for cross-cutting artifacts:
deploy/eu-west-1/<capability>/api/...deploy/eu-west-1/<capability>/db/...deploy/eu-west-1/shared/...This pattern fits enterprises that want per-component artifact directories for downstream tooling that operates on a single component’s manifests. Where a component’s Recipe also declares artifacts:, read What these templates do not decide above before choosing this shape: those files carry a component segment already, so this override adds a second one.
Diagnostics
The path-template surface halts the build in each of the following situations, and errors/fatal-halts.md documents them under these names. That page quotes the message each halt emits; match build output against that text.
- Path-template references a variable outside the allowlist — parse-time: a path template references a variable not in the allowlist.
- Path collision — assembly-time: two boundary contributors evaluate to the same path but disagree on a property that must be uniform across contributors at that path.
- Instance-ID collision — assembly-time: two boundaries that evaluate to the same
(path, provider)tuple contribute components with identical instance IDs. - Chart-name mismatch — assembly-time: a merged helm-chart assembly receives contributors with conflicting cascade-resolved
aggrega.ai/chart-nameannotations. - Missing template key — a path template references a field under an open variable that resolves to no value (e.g.,
{{ .parameters.region }}when the Release omitsregion, or a.parent_boundarykey at a top-level boundary that has no parent);missingkey=errorproduces an explicit message naming the boundary, the template field (directory:vssubDirectory:), and the missing key..parametersand.parent_boundaryare open — their keys are authored data — while.manifestdeclares its keys, so a mistyped key under.manifestis refused at parse time as an unknown reference instead, with the diagnostic listing the keys.manifestdefines.
Cross-references
entities/release.md— Release authoring, including spatial segregation and thedirectory:/subDirectory:fields.providers/architecture.md— provider dispatch and the per-(path, provider)assembly model.providers/compose.md— compose-side per-(path, provider)output, including the merged-path scenario.providers/helm-chart.md— helm-chart umbrella composition and the chart-name cascade rule for merged paths.entities/featurerecipe.md— boundary-scope FeatureRecipes (thecore/compose-bridgeFeature relies on the merged-path assembly model documented here).errors/fatal-halts.md— full diagnostic catalogue including the path-dispatch halts enumerated above.