@warble/ir-spec 0.6.0 → 0.8.0

package/README.md

@@ -2,8 +2,9 @@
 
 The Warble IR (`warble_ir_version`) as a resolvable npm package.
 
-**This package's version *is* the payload.** `warble_ir_version 0.6` publishes as npm version
-`0.6.0` — IR `x.y` maps to npm `x.y.0`, with the patch component always zero. Everything else in
+**This package's version *is* the payload.** IR `x.y` publishes as npm version `x.y.0`, with the
+patch component always zero — so this package's own version on the registry tells you which
+`warble_ir_version` it describes, and the bundled `ir-schema.md` is that IR's spec as it stood. Everything else in
 the package — the bundled [`ir-schema.md`](./ir-schema.md) (a copy of
 [`docs/spec/ir-schema.md`](https://github.com/Canner/Warble/blob/main/docs/spec/ir-schema.md)) and
 the `IR_VERSION` constant exported from `index.js` — is documentation, not enforcement.
@@ -12,8 +13,8 @@ the `IR_VERSION` constant exported from `index.js` — is documentation, not enf
 
 Before this package, the IR version a published dispatcher (`@warble/claude-agent-sdk`,
 `@warble/codex-local`) accepts was discoverable only by reading its source. Both dispatchers now
-declare `@warble/ir-spec` as a `peerDependencies` range (`0.6.x` today) plus an advisory
-`"warble": { "irVersion": "0.6" }` field, so a consumer — or npm's own resolver — can see which IR a
+declare `@warble/ir-spec` as a `peerDependencies` range (`x.y.x`) plus an advisory
+`"warble": { "irVersion": "x.y" }` field, so a consumer — or npm's own resolver — can see which IR a
 dispatcher speaks without opening it.
 
 **This package is not meant to be imported.** A `peerDependency` is a declaration, not a dependency

package/index.d.ts

@@ -3,7 +3,7 @@
  * `docs/spec/ir-schema.md` (bundled here as `ir-schema.md`) for why this is exported without being
  * meant to be imported by a dispatcher.
  */
-export declare const IR_VERSION: "0.6";
+export declare const IR_VERSION: "0.8";
 
-declare const _default: { IR_VERSION: "0.6" };
+declare const _default: { IR_VERSION: "0.8" };
 export default _default;

package/index.js

@@ -8,6 +8,6 @@
  * exported for tooling that wants the value without re-parsing `package.json` (e.g. a script
  * checking a dispatcher's declared peer range against the spec it names).
  */
-export const IR_VERSION = "0.6";
+export const IR_VERSION = "0.8";
 
 export default { IR_VERSION };

package/ir-schema.md

@@ -1,4 +1,4 @@
-# Warble IR — the compile contract (`warble_ir_version: 0.6`)
+# Warble IR — the compile contract (`warble_ir_version: 0.8`)
 
 The IR is the **language-neutral seam** between the Warble front-end (`warble compile`) and any
 back-end. The v1 reference back-end is the Claude Code CLI target (`warble dispatch`, Rust); other
@@ -6,26 +6,33 @@ runtimes are other thin back-ends. Both sides depend only on this document — n
 internals.
 
 `warble compile <project-dir> -o ir.json` reads a Warble project (profile + components +
-context binding) and emits **one** IR JSON document with `"warble_ir_version": "0.6"` — the
+context binding) and emits **one** IR JSON document with `"warble_ir_version": "0.8"` — the
 current, live contract the compiler emits today. (Earlier drafts of this doc kept the per-step-tier
 shape in a separate "v0.2 (proposed)" section; that has been folded into the contract below now
 that it is implemented and wired into the built core/dispatcher.) The shape below is what the
 dispatcher consumes.
 
+> **Composition boundary:** v0.8 adds the resolved `components[].entrypoint` and optional
+> `llm_calls[].component_calls` facets specified by
+> [`component-composition.md`](./component-composition.md). Every shipped reader retains them. The
+> Agent SDK and composed Codex local orchestrate targets realize narrow slices with dispatcher-owned
+> isolated child runs and their documented runtime budgets; unsupported shapes and other targets preflight wall-hit instead of
+> dropping or inlining an edge.
+
 > Scope note (v0.3+): context binding is **fine-grained**. The host injects a `ContextLoader`
 > selected for the binding kind, and the compiler **evaluates** every `context_precondition`
 > against that bound context — not merely validates vocabulary membership. The IR records passing
-> checks in `precondition_result.checks`; a Wren-project adapter also fills
-> `context_binding.resolved` with metrics/dimensions/grains and lineage, while a raw-source adapter
-> answers the constitutive probes and an external adapter emits no resolved block. A precondition
-> that is answerable-and-false, or that the adapter **cannot answer** at all, is a
+> checks in `precondition_result.checks`; a `prepared` binding also fills
+> `context_binding.resolved` with metrics/dimensions/grains and lineage, while a raw-source binding
+> answers the constitutive probes and an external one emits no resolved block. A precondition
+> that is answerable-and-false, or that the loader **cannot answer** at all, is a
 > loud compile-time fail — so an emitted IR only ever contains passing checks. See
 > [`context_precondition`](#context_precondition-closed-predicate-vocabulary) and the
 > [v0.3 binding](#v03--fine-grained-context-binding) section below.
 >
-> The coarse `context_binding.project` locator is **retained**: Wren-project back-ends use it to run
-> `wren`, while other binding kinds give it adapter-specific meaning. Fine-grained binding is
-> additive, not a replacement.
+> The coarse `context_binding.project` locator is **retained**: a back-end uses it to name the layer
+> it queries, and each binding kind gives it its own meaning. Fine-grained binding is additive, not a
+> replacement.
 
 ---
 
@@ -41,11 +48,11 @@ version on anything else — there is no best-effort or partial parse of an unre
 
 | Consumer | Accepted `warble_ir_version` | Where the accepted version is declared |
 | --- | --- | --- |
-| `core` (`warble compile`) | emits `0.6` | the `"warble_ir_version"` literal in `core/src/compile.rs` |
-| `dispatcher/claude-code-cli` | `0.6` | `SUPPORTED_IR_VERSION` in `dispatcher/claude-code-cli/src/ir.rs` |
-| `dispatcher/vercel` | `0.6` | `SUPPORTED_IR_VERSION` in `dispatcher/vercel/src/emit.rs` |
-| `dispatcher/claude-agent-sdk` | `0.6` | `SUPPORTED_IR_VERSIONS` in `dispatcher/claude-agent-sdk/src/ir.ts` |
-| `dispatcher/codex-local` | `0.6` | `SUPPORTED_IR_VERSION` in `dispatcher/codex-local/src/ir.ts` |
+| `core` (`warble compile`) | emits `0.8` | the `"warble_ir_version"` literal in `core/src/compile.rs` |
+| `dispatcher/claude-code-cli` | `0.8` | `SUPPORTED_IR_VERSION` in `dispatcher/claude-code-cli/src/ir.rs` |
+| `dispatcher/vercel` | `0.8` | `SUPPORTED_IR_VERSION` in `dispatcher/vercel/src/emit.rs` |
+| `dispatcher/claude-agent-sdk` | `0.8` | `SUPPORTED_IR_VERSIONS` in `dispatcher/claude-agent-sdk/src/ir.ts` |
+| `dispatcher/codex-local` | `0.8` | `SUPPORTED_IR_VERSION` in `dispatcher/codex-local/src/ir.ts` |
 
 Each back-end copies this value rather than importing it from `core` or from another back-end: a
 back-end shouldn't need a Rust dependency edge just to know a version string, and independent copies
@@ -62,7 +69,7 @@ is informational, not itself an input enforcement check.
 `@warble/claude-agent-sdk` and `@warble/codex-local` additionally each declare a `peerDependencies`
 entry on [`@warble/ir-spec`](../../packages/ir-spec) — a dedicated npm package whose own version *is*
 the IR version (see [IR version to npm version mapping](#ir-version-to-npm-version-mapping) below) —
-plus an advisory `"warble": { "irVersion": "0.6" }` field in the same `package.json`. This makes the
+plus an advisory `"warble": { "irVersion": "0.8" }` field in the same `package.json`. This makes the
 IR version a dispatcher speaks visible in the npm dependency graph without opening the package.
 **Neither dispatcher imports `@warble/ir-spec`** — the peer is a declaration, not a dependency edge,
 and each dispatcher keeps enforcing its own copy of `SUPPORTED_IR_VERSION`(S) above. `@warble/ir-spec`
@@ -70,8 +77,12 @@ also bundles this document itself (as `ir-schema.md`, alongside `index.js`/`inde
 snapshot for the IR version it publishes — a published npm version is immutable, so a snapshot as of
 that version is worth more than a live link back to this file on `main`, which points at whatever the
 spec later became. `just publish-check` fails if `packages/ir-spec/ir-schema.md` and this document
-ever diverge, since a publish is exactly the point that drift becomes irreversible; re-sync it with
-`cp docs/spec/ir-schema.md packages/ir-spec/ir-schema.md` whenever this document changes. Counting the
+ever diverge, since a publish is exactly the point that drift becomes irreversible. Keeping it in
+sync is not a manual step: `npm run gen:reference` in `docs/site/` writes it from this document
+alongside the generated reference pages, and the docs-site CI drift check covers it on the same
+footing, so editing this document and regenerating is all there is to it. The snapshot has to be a
+real committed file rather than a symlink — `npm pack` does not dereference one, it silently omits
+the file and ships a package with no spec in it. Counting the
 producer (what `core` actually emits) alongside every independent consumer/advisory copy, the
 `@warble/ir-spec` package's own version, its `index.js` and `index.d.ts` version constants/literals,
 both dispatchers' peer declarations, both dispatchers' advisory `warble.irVersion` fields, and the
@@ -88,7 +99,7 @@ spec title, there are **eighteen** locations that must agree:
 | 7 | `dispatcher/vercel/src/emit.rs` `MAX_SUPPORTED_IR_VERSION` | Advisory | `core/tests/ir_version_lockstep_tests.rs` |
 | 8 | `dispatcher/claude-agent-sdk/src/manifest.ts` `MIN_SUPPORTED_IR_VERSION` | Advisory | `core/tests/ir_version_lockstep_tests.rs` |
 | 9 | `dispatcher/claude-agent-sdk/src/manifest.ts` `MAX_SUPPORTED_IR_VERSION` | Advisory | `core/tests/ir_version_lockstep_tests.rs` |
-| 10 | This document's title (`warble_ir_version: 0.6`) | Spec | `core/tests/ir_version_lockstep_tests.rs` |
+| 10 | This document's title (`warble_ir_version: 0.8`) | Spec | `core/tests/ir_version_lockstep_tests.rs` |
 | 11 | `packages/ir-spec/package.json` `"version"` (mapped `x.y` -> `x.y.0`) | Producer (npm) | `core/tests/ir_version_lockstep_tests.rs` |
 | 12 | `packages/ir-spec/index.js` `IR_VERSION` | Advisory | `core/tests/ir_version_lockstep_tests.rs` |
 | 13 | `dispatcher/claude-agent-sdk/package.json` `peerDependencies["@warble/ir-spec"]` (mapped `x.y` -> `x.y.x`) | Declaration | `core/tests/ir_version_lockstep_tests.rs` |
@@ -101,14 +112,14 @@ spec title, there are **eighteen** locations that must agree:
 This table's scope is contract-bearing declarations — constants and literals something actually
 compares against — not every place `warble_ir_version` appears in prose. Each back-end's `ir` module
 doc comment also mentions the current version for a human skimming the file (e.g. `//! Typed view of
-the Warble IR (warble_ir_version: 0.6)`); nothing checks those comments, and a version bump can leave
+the Warble IR (warble_ir_version: 0.7)`); nothing checks those comments, and a version bump can leave
 them stale without breaking anything. They are deliberately not extra rows — update them as a
 courtesy to the reader, not because a test requires it.
 
 `core/tests/ir_version_lockstep_tests.rs` is the sole cross-target lockstep owner: it text-parses
 every contract-bearing declaration above and asserts that each equals the version core emits (rows
-11–15 first pass the emitted version through the mapping below, since they are npm identifiers, not
-copies of the raw `x.y` string). The target-local `ir_version_tests.rs` files only exercise their own
+11, 13, and 15 first pass the emitted version through the mapping below, since they are npm
+identifiers, not copies of the raw `x.y` string; the table marks which ones). The target-local `ir_version_tests.rs` files only exercise their own
 unsupported-version rejection and no-partial-output behavior; they do not scrape other targets'
 sources. (`core/src/lib.rs`'s doctest and `core/tests/compile_tests.rs` also assert row 1's literal
 directly, but aren't listed as separate lockstep-tested locations — they self-guard, failing the
@@ -123,8 +134,8 @@ only when `warble_ir_version` moves, on its own release line. The mapping from I
 version is fixed and mechanical:
 
 - IR version `x.y` maps to npm version `x.y.0` — the patch component is **always** zero.
-- A dispatcher's `peerDependencies["@warble/ir-spec"]` range is `x.y.x` — e.g. IR `0.6` is npm
-  version `0.6.0` and peer range `0.6.x`.
+- A dispatcher's `peerDependencies["@warble/ir-spec"]` range is `x.y.x` — e.g. IR `0.7` is npm
+  version `0.7.0` and peer range `0.7.x`.
 - An IR version with anything other than exactly two dot-separated numeric components (a three-part
   `x.y.z`, or a non-numeric component) has **no defined mapping** and is rejected by
   `core/tests/ir_version_lockstep_tests.rs` at the point it tries to compute rows 11, 13, and 15 — it
@@ -165,7 +176,7 @@ back-end accepts, and must be regenerated rather than merely re-read.
 
 ```jsonc
 {
-  "warble_ir_version": "0.6",
+  "warble_ir_version": "0.8",
   "profile": "orders-analytics",          // profile.yml `profile:`
   "context_binding": {                    // resolved from profile `context:` + context/binding.yml
     "project": "examples/jaffle-wren",    // coarse path to a wren project (retained for back-ends)
@@ -179,7 +190,7 @@ back-end accepts, and must be regenerated rather than merely re-read.
       "dimensions": [ { "name": "status", "temporal": false }, { "name": "order_date", "temporal": true } ],
       "time_dimensions": ["order_date"],
       "models": ["customers", "orders", /* … */],
-      "lineage": { "nodes": 15, "edges": 12, "resolvable": true }   // summary only; full DAG stays in the adapter
+      "lineage": { "nodes": 15, "edges": 12, "resolvable": true }   // summary only; the full DAG stays in the bound document
       // when the project carries consumer artifacts, `lineage` additionally reports
       //   "consumers": { "queries": 2, "dashboards": 1 }            // query:/dashboard: node counts
       // and, when construction had to degrade (e.g. a consumer's SQL didn't parse),
@@ -188,15 +199,20 @@ back-end accepts, and must be regenerated rather than merely re-read.
       // so pre-consumer IRs are byte-identical.
     }
   },
-  "config": {},                           // reserved profile-level config block; no fields today
+  "config": {},                           // reserved profile-level config block; optionally carries `capability_ceiling`
+  "slots": [                              // additive; present only when the PROFILE declares slots — see `slots` below
+    { "name": "plan_mode", "default": "off", "present_when": "plan_mode_available",
+      "variants": { "on": "…rendered…", "off": "…rendered…" } }
+  ],
   "components": [ /* one resolved component node, see below */ ]
 }
 ```
 
-### `config` — emptied in 0.6
+### `config` — one optional field in 0.7
 
-`config` carried one field, `tier_policy`, from the first IR through `0.5`. `0.6` removes it, and
-the block is now emitted as `{}`.
+`config` carried one field, `tier_policy`, from the first IR through `0.5`. `0.6` removed it, and
+the block was emitted as `{}` until the addition documented below gave it its first surviving
+field.
 
 `tier_policy` was a profile-wide tier stance (`cost_sensitive`) that the compiler was meant to
 resolve into per-step tiers. Only the field ever landed. No back-end read it, its value was never
@@ -214,11 +230,40 @@ control (see [`profile-schema.md`](./authoring.md#61-tiers-not-model-names)).
 The block itself stays so that profile-level config which *can* be honored is an additive change
 rather than the reintroduction of a removed key.
 
+#### `capability_ceiling` (additive since v0.7)
+
+When a profile declares `capability_ceiling` — a list of capability strings — the compiler carries
+it into `config` verbatim:
+
+```jsonc
+"config": {
+  "capability_ceiling": ["sql_execution", "chart_rendering"]
+}
+```
+
+A profile that omits `capability_ceiling` compiles exactly as before this field existed: `config`
+stays `{}`.
+
+The ceiling is a compile-time *authorization* check ("may a component of this profile require
+this capability at all"), not the dispatch-time capability *resolution* every component's
+`required_capabilities` already goes through against a target's profile (native / realize-via /
+degrade / fail — see the compile-time checks table below). The two gates are independent: a
+capability can pass the ceiling and still fail resolution against a given target, and the ceiling
+is evaluated once at compile time regardless of which target the IR is later dispatched against.
+A component whose `required_capabilities` names anything outside the profile's declared ceiling
+fails compile before resolution is ever attempted.
+
+Containment is exact string-set matching — no hierarchy or prefix inference on the `:` qualifier
+some capability names use. A ceiling of `sql_execution` does **not** admit a component requiring
+`sql_execution:read_only`; the qualifier is not an ordering, and a profile that means to allow the
+narrower capability must list it explicitly alongside (or instead of) the broader one.
+
 ## Component node (resolved: component fields ⊕ supported profile mount fields)
 
 ```jsonc
 {
   "id": "generate_dashboard",
+  "entrypoint": true,                    // resolved mount eligibility; defaults true in authoring
   "verb": "generate_dashboard",
   "type": "analytical",                   // analytical | assertive | mutating | constitutive | orchestrating
   "realization_kind": "skill",            // required in component.yml; a profile mount may replace it
@@ -229,47 +274,49 @@ rather than the reintroduction of a removed key.
   "context_requirements": [               // human-readable shape strings — always emitted, may be []
     "a wren project (semantic layer) to build dashboards over"
   ],
-  "context_precondition": [               // structured predicates — always emitted, may be []
-    { "predicate": "has_metric" },
-    { "predicate": "has_groupable_dimension" }
-    // "args" is optional per entry, e.g. { "predicate": "has_metric", "args": { "name": "revenue" } }
-    // predicate must be from the closed vocabulary — see below. Compile validates membership AND
-    // evaluates each predicate against the bound context via the injected ContextLoader.
-  ],
+  "context_precondition": [],              // dashboard delegates panel data-shape checks to answer_query
   "params": [                             // always emitted, may be []
-    { "name": "topic_default", "bind": "optional", "default": "overview" },  // profile-bound (bind)
-    { "name": "connection", "source": "runtime-injected" }                    // runtime-injected, not in git
+    { "name": "topic_default", "bind": "optional", "default": "overview" }   // profile-bound (bind)
   ],
   "binds": {                              // additive; present only when >=1 bind-family param has a value
     "topic_default": "overview"           // mount didn't supply one, so this is the declared default
   },
   "precondition_result": {                // per-predicate evaluation outcome (v0.3, see §checks)
     "status": "pass",                     // always "pass" in emitted IR — a failing predicate loud-fails
-    "checks": [                           // one entry per declared context_precondition, in order
-      { "predicate": "has_metric", "outcome": "pass" },
-      { "predicate": "has_groupable_dimension", "outcome": "pass" }
-    ]
+    "checks": []                          // one entry per declared context_precondition, in order
   },
   "brief": "…shared framing for every step, placeholders substituted…",  // additive; present only when authored — see below
+  "slots": [                              // additive; present only when the component declares slots — see below
+    { "name": "verification", "default": "base",
+      "variants": { "base": "…rendered…", "terse": "…rendered…" } }
+  ],
+  "assets": [                             // additive; present only when the component declares assets — see below
+    { "path": "themes/dark.css", "hash": "sha256:9869fecc…", "bytes": 22 }
+  ],
   "prompt_fragment": "…rendered skill instructions…",  // see §prompt rendering
   "llm_calls": [                          // per-step tier, order preserved from component llm_steps
     { "name": "plan_dashboard", "tier": "strong", "conditional": false, "when": null,
-      "consumes": [], "produces": "query_plan",
+      "consumes": [], "produces": "dashboard_plan",
       "prompt": "<plan_dashboard.md rendered, placeholders substituted, no ## header>" },
     { "name": "compose_layout", "tier": "cheap", "conditional": false, "when": null,
-      "consumes": ["query_plan"], "produces": "dashboard_summary",
+      "consumes": ["dashboard_plan"], "produces": "dashboard",
+      "component_calls": [{ "alias": "answer", "component": "answer_query" }],
       "prompt": "<compose_layout.md rendered>" }
     // a conditional step instead carries e.g. "conditional": true, "when": { "guard": "on_failure", "target": "generate_sql" }
     // — see `llm_calls[].when` below
+    // a step may also narrow its tool boundary and/or mark its artifact exclusive, e.g.
+    // "capabilities": ["sql_execution:read_only"], "produces_exclusive": true — both additive,
+    // omitted here because neither step below declares them; see `llm_calls[].capabilities` /
+    // `llm_calls[].produces_exclusive` below
   ],
   "guardrails": [                         // resolved; `locked` is the normalized lock-state
-    { "name": "read_only_execution", "locked": true }
-    // `scope`/`threshold` appear only when authored; their meaning is guardrail/target-specific,
-    // e.g. another component may emit { "name": "artifact_write", "locked": true, "scope": "." }
+    { "name": "read_only_execution", "locked": true },
+    { "name": "artifact_write", "locked": true, "scope": "." }
   ],
   "trigger": { "kind": "one_shot" },      // one_shot | scheduled | event
-  "required_capabilities": [              // union of component declarations
-    "sql_execution:read_only", "genbi_build", "llm:strong", "llm:cheap"
+  "required_capabilities": [              // declarations plus shape-implied requirements
+    "render_contract", "artifact_write", "llm:per_step_tier", "llm:strong", "llm:cheap",
+    "component_invocation"
   ],
   "borrowed_actions": [],
   "eval_ref": "generate_dashboard.eval",  // legacy reference string; retained for back-compat
@@ -279,7 +326,10 @@ rather than the reintroduction of a removed key.
   },
   "effect": {
     "render_blocks": [
-      { "type": "chart", "fields": {} }, { "type": "table", "fields": {} }, { "type": "kpi_card", "fields": {} }
+      { "type": "kpi_card", "fields": { "label": "string", "value": "number|string", "unit": "string?", "delta": "number?" } },
+      { "type": "table", "fields": { "columns": "string[]", "rows": "row[]" } },
+      { "type": "chart", "fields": { "chart_type": "bar|line|pie|area|scatter", "x": "string", "series": "string[]", "rows": "row[]" } },
+      { "type": "definition", "fields": { "sql": "string", "source_tables": "string[]", "filters": "string[]" } }
     ],
     "outcome": {
       "kind": "none"                      // none | assertion | mutation | dispatch — stays this 4-value union
@@ -451,6 +501,70 @@ an IR version bump under the policy above. As of this writing:
 A back-end that ignores `when` must do so as a documented, deliberate choice (as `claude-code-cli`
 does above) — never as a silent fallback for a guard shape it was simply never taught to recognize.
 
+#### `llm_calls[].capabilities` (additive)
+
+`string[]`, an exact-string subset of the component's own `required_capabilities` — **omitted
+entirely (not present as a key, not `null`) unless the step declares it**. A step that narrows its
+capabilities compiles to `"capabilities": [...]` on that call's IR entry; a step that doesn't
+compiles to exactly the IR it produced before this field existed. Compile validates the subset
+relationship (exact string containment, no hierarchy) against the component's declared
+`required_capabilities` and loud-fails, naming both the step and the offending capability, when a
+step names one outside that set. This is a compile-time declaration of what a step is allowed to
+need, not a runtime identity or actor concept: how a back-end scopes a step's own call is already a
+per-back-end mechanism this field says nothing about.
+
+```jsonc
+{ "name": "plan_query", "tier": "strong", "conditional": false, "when": null,
+  "consumes": [], "produces": "query_plan",
+  "capabilities": ["render_contract"],
+  "prompt": "…" }
+```
+
+#### `llm_calls[].produces_exclusive` (additive)
+
+`bool` — **omitted entirely unless `true`.** A step's plain `produces` name is unchanged; this is a
+separate provenance marker on that same artifact, meaning only the producing step is expected to
+write it. Kept as an additive boolean rather than reshaping `produces` into an object. Like
+`capabilities` above, it says nothing about *who* enforces exclusivity — that is whatever already
+scopes a step's own call at the back-end.
+
+```jsonc
+{ "name": "run_query", "tier": "cheap", "conditional": false, "when": null,
+  "consumes": ["query_plan"], "produces": "query_result",
+  "produces_exclusive": true,
+  "prompt": "…" }
+```
+
+#### `entrypoint` and `llm_calls[].component_calls` (since v0.8)
+
+The composition contract adds two protocol fields:
+
+```jsonc
+{
+  "id": "answer_query",
+  "entrypoint": false,
+  "llm_calls": [
+    {
+      "name": "compose_dashboard",
+      "component_calls": [
+        { "alias": "answer", "component": "answer_query" }
+      ]
+    }
+  ]
+}
+```
+
+`entrypoint` is a required resolved mount property, defaulting to `true` at the authoring boundary
+for profiles written before it existed. `component_calls` is omitted when empty and otherwise is a
+step-local static allowlist; its aliases resolve to unique mounted component identities after
+overlays. A non-empty list also adds the required runtime-provided `component_invocation`
+capability to the component and the declaring step's effective requirements.
+
+The compiler rejects duplicate mounted identities, invalid or duplicate aliases, missing targets,
+self-calls, and cycles before emitting the IR. See
+[`component-composition.md`](./component-composition.md) for the authoritative validation,
+preparation, runtime, envelope, and compatibility rules.
+
 #### `guardrails[].scope` / `threshold` and the `locked`/`overridable` normalization
 
 `scope` and `threshold` are passthrough fields — each is present in the resolved IR **only when
@@ -504,6 +618,14 @@ Optional free-form text, authored on the component (or replaced wholesale by a p
 same `{{project}}` / `{{project_name}}` placeholder substitution as step prompts (§Prompt
 rendering). Emitted **once, on the node itself** — never per-step — and present in the IR only when
 authored; a component with no `brief` produces IR byte-identical to before this field existed.
+
+The emitted value may be a **merge of two authored layers**: a profile's
+[`system_prompt`](./authoring.md#system_prompt--profile-level-framing-for-every-component) — shared
+by every component that profile mounts — followed by a blank line and the component's own effective
+brief. Either layer may be absent; with neither, the key is absent as described above. The merge
+happens at compile time and deliberately adds no IR field, so a back-end that already reads `brief`
+needs no change and the wire contract is unversioned by it. The trade-off is that the IR does not
+record which half came from where.
 Every back-end that assembles a system prompt places it in the same position: after the
 machine-generated preamble, before the body, on both the driver and every subagent. See
 [`profile-schema.md`](./authoring.md#brief--authored-framing-shared-across-every-step) for the
@@ -534,6 +656,165 @@ from the node's shape instead. See
 
 ---
 
+#### `slots` (additive since v0.7)
+
+`object[]` — **omitted entirely (not present as a key, not `[]`) unless the component declares
+`slots:`.** A component without any compiles to exactly the IR it did before this field existed.
+
+Each entry carries a `name`, a required `default`, a `variants` object, and `present_when` only when
+authored:
+
+```jsonc
+"slots": [
+  {
+    "name": "verification",
+    "default": "base",                    // always present; names a key of "variants"
+    "present_when": "verification_enabled", // omitted entirely unless authored
+    "variants": {
+      "base":  "…rendered text, placeholders substituted…",
+      "terse": "…rendered text…"
+    }
+  }
+]
+```
+
+**Every variant is carried; none is selected.** This is the deliberate division of labour: compile
+*transports* the alternatives, dispatch *chooses* between them. The consequence is that the IR stays
+a complete description of what the model could be told — a reader can enumerate every wording without
+running anything — at the cost of a larger document. Selecting at compile would have been smaller and
+would have made the IR silent about the paths not taken.
+
+**Variant keys are opaque.** Warble does not interpret, validate, or order them; the mapping from a
+bound model (or any other runtime fact) to a key belongs to the host's dispatch fragment. A
+consumer that hard-codes key names is coupling itself to one project's convention, not to this
+schema.
+
+**A slot is referenced from prompt text as `{{ slot.<name> }}`.** Deliberately a different syntax
+from the `{{project}}` / `{{project_name}}` value substitutions, so a slot reference and a mistyped
+placeholder are distinguishable; it is also Jinja-native attribute access, so the renderer can be
+replaced without touching authored files. Variant text goes through the same substitution as a step
+body or a `brief`.
+
+**Names are unique project-wide** — a profile-level slot may not reuse a component-level name — so a
+consumer can resolve `{{ slot.<name> }}` against a single flat name space rather than having to know
+which layer the surrounding text came from.
+
+**The same shape appears at two levels.** A component's slots are on its component node and belong
+to that component's own prompt text (its steps and `brief`); a profile's slots are the **top-level
+`slots` array** and belong to the profile's `system_prompt`. They are not merged, and a profile's
+slots are deliberately not copied onto each component node — the flat name space is what makes that
+unnecessary. Compile refuses a name declared at both levels rather than letting one shadow the
+other, so a consumer never has to implement a precedence rule.
+
+**`present_when` is a condition on the slot's presence, unrelated to `llm_calls[].when`.** When it
+does not hold, the slot is removed rather than filled with any variant: an instruction describing a
+withheld capability is worse than no instruction. Evaluating it is the host's job; compile only
+carries it.
+
+**Who resolves a slot.** Compile never picks a variant — every one travels in the IR — so a consumer
+must substitute before a prompt is sent. Two back-ends do: the Agent SDK back-end takes the host's
+table through its dispatch input, and the `warble` CLI resolves the IR document once, before any
+target-specific type deserializes it, from repeated `--slot NAME=VARIANT` flags (`--slot NAME=`
+removes a slot whose condition does not hold). A back-end that cannot yet resolve refuses an IR
+declaring slots rather than emitting the placeholder.
+
+**A slot nobody answers takes its `default` — with one exception.** A slot carrying `present_when`
+and no answer is a loud failure, not a default: `default` covers "no opinion on the wording", and it
+cannot cover "no opinion on whether this exists at all". Defaulting there is precisely the failure
+the field exists to prevent.
+
+**A consumer that records an IR hash to identify a run now records something narrower than it
+looks.** Before slots, compile finished every string, so an IR hash fixed the prompt as well. Now
+two runs can share one and have sent different prompts, so anything that needs to identify what a
+model was told has to fingerprint the assembled prompts instead — and each back-end has to produce
+it, since only dispatch knows the answer.
+
+The contract is: **a digest per named prompt surface, plus a total over all of them**, taken as late
+as possible — over the text that actually reaches the runtime, not over the plan a host may then
+rebuild. The question is excluded (it is the caller's text and varies per turn by design, so
+including it would make every turn unique and answer nothing). Per-turn content supply is excluded
+too, and deliberately: it is not an IR construct, and when it lands it needs its own decision about
+whether it joins the digest.
+
+The surfaces, per back-end:
+
+| Back-end | Surfaces |
+| --- | --- |
+| Agent SDK, from a plan | the driver's `systemPrompt` and each named subagent's prompt — what the single and split paths send as built. On the single-tier collapse path a component's `prompt_fragment` is folded into `systemPrompt` and `llm_calls[].prompt` is not read, so a one-step component's text is covered through the driver surface. |
+| Agent SDK, per turn at run time | the `systemPrompt` and subagent prompts of every turn the runtime sends, reported one fingerprint per turn, plus — for a step bound to a local OpenAI-compatible endpoint — the role/content messages it posts, keyed by position and role, since such a step builds no SDK options at all. This is the only truthful source for the staged and hybrid-tool paths: a staged step's options carry a runtime preamble ahead of the step prompt, and the hybrid-tool driver composes a prompt from the step list that appears in no plan field. A plan-derived digest **must not** claim those. |
+| Claude Code CLI | not yet produced — filed as a follow-up |
+| vercel | not yet produced — filed as a follow-up |
+| codex-local | not yet produced — filed as a follow-up |
+
+**Take it from a plan only when the host sends that plan's options as built.** Otherwise take it at
+the point of send. A host that rebuilds its options — replacing the system prompt, say — and then
+records a plan-derived digest has recorded a prompt nobody received, which is worse than recording
+nothing: it reads as evidence.
+
+A back-end that grows a new prompt-carrying surface and does not add it to its digest narrows the
+fingerprint silently. That is the same shape as an unresolved slot placeholder, one layer out, which
+is why the surfaces are listed here rather than left implicit in each implementation.
+
+**Display paths differ, and the two manifests differ from each other.** The rule above protects a
+model; a reader is not one, so a display renders an unanswered condition's default rather than
+refusing — what it shows is what the default binding would say, never a promise about what will be
+sent. Whether a display needs resolving at all depends on its schema: the `warble manifest` output
+omits prompt text structurally and so needs none, while the Agent SDK back-end's own manifest
+carries each step's prompt and therefore resolves like any other consumer of that text.
+
+#### `assets` (additive since v0.7)
+
+`object[]` — **omitted entirely (not present as a key, not `[]`) unless the component declares
+`assets:`.** Each entry is exactly `{path, hash, bytes}`:
+
+```jsonc
+"assets": [
+  { "path": "themes/dark.css", "hash": "sha256:9869fecc…", "bytes": 22 }
+]
+```
+
+`path` is as authored, relative to the component directory. `hash` is `sha256:<hex>` over the
+file's bytes and `bytes` its length; **both are computed at compile and neither is authorable** — a
+`hash:` or `bytes:` written in `component.yml` is a parse error. An author-supplied fingerprint
+could only rot, and silently replacing one would leave the author trusting a field that means
+nothing.
+
+**An IR's assets travel beside it.** Because content is not carried (below) and no consumer can
+re-read a component directory — there is none at dispatch, and a Hub component was resolved over the
+network at compile — `warble compile` writes each component's asset content into a sibling directory
+of the IR it emits: for `<dir>/ir.json`, into `<dir>/ir.assets/<component-id>/<authored path>`.
+Nothing is created for a project that declares no assets.
+
+Dispatch lands them at the authored relative path inside the agent's working directory and verifies
+every file against its `hash`. **A manifest path is re-validated on the way in, twice.** Absolute
+paths and `..` segments are refused as text; then the resolved location is checked against the
+canonicalized root, so a syntactically clean path that reaches outside through a symlinked directory
+is refused too — on the write side and on the read side. Compile checks what an author wrote against
+the component directory, but an IR is a document that can arrive from anywhere, and the working
+directory it lands in may be a real project somebody else has written to. Without both checks a
+manifest is an arbitrary file write. **Both failure modes are loud**: a manifest entry with no file in the
+travelling directory, and one whose content no longer hashes to the recorded value, each stop the
+dispatch, and nothing is landed at all rather than part of a component's set. Silence there is the
+defect this closes — a component that declared its files and received none.
+
+The consequence to know: **the artifact that travels is the IR plus that directory.** Copying an
+`ir.json` on its own and dispatching it fails loudly rather than running without the files, which is
+the right direction but is a new failure to recognise.
+
+**Content is not carried.** This is the deliberate contrast with [`slots`](#slots-additive-since-v07)
+above, and the two together define the line: a slot variant is prompt text, so its content is read
+into the IR and composed into a prompt; an asset is a file that must be present on disk when the
+component runs, so only its identity travels. Embedding binaries — or dozens of stylesheets — in
+every IR is not worth the size, and `bytes` exists so a consumer can price landing them first.
+
+**Landing is the target's business.** Copy, symlink, or pre-bake into an image: the IR says what is
+required and how to recognise it, never how to provide it. A consumer that finds an asset missing
+or hash-mismatched at dispatch time has a real failure to report, but that check is not compile's.
+
+**The hash is content identity, not a version number.** It supports "is this the same file", never
+"is this newer" — deliberately the same stance freshness takes elsewhere in this spec. Do not infer
+ordering from it.
+
 ## Resolution rules (front-end `warble compile` must implement)
 
 1. **Parse** `profile.yml`, each mounted `components/<id>/component.yml`, and `context/binding.yml`.
@@ -595,9 +876,36 @@ from the node's shape instead. See
 | `when` guard without `conditional` | `llm_steps[].when` present but `conditional` is not `true` | `step '<name>' on component '<id>' declares a 'when' guard but is not 'conditional: true' …` |
 | unknown `when` guard name | `llm_steps[].when.guard` not in the closed 3-name vocabulary (`on_failure`/`on_flag`/`on_missing`) | `unknown guard '<name>' in step '<step>' of component '<id>' …` |
 | `when` guard invalid target | `llm_steps[].when.target` is empty, or `guard: on_flag` with a non-dotted target | `guard '<name>' in step '<step>' of component '<id>' has an empty target` / `… expects a dotted 'artifact.field' target …` |
+| duplicate step name | two `llm_steps[]` entries share the same `name` | `duplicate step name '<name>' on component '<id>' — step names must be unique within a component` |
+| duplicate `produces` artifact | more than one `llm_steps[]` entry declares the same `produces` name | `duplicate 'produces' artifact '<name>' on component '<id>' — more than one step declares it, most recently '<step>'; each artifact must have exactly one producer` |
+| step consumes its own `produces` | a step's `consumes[]` entry equals that same step's own `produces` | `step '<step>' on component '<id>' consumes '<name>', its own 'produces' artifact — a step cannot consume what it produces; 'consumes' must name an earlier step's output` |
+| step consumes an artifact no earlier step produces | a step's `consumes[]` entry is not the `produces` of any strictly-earlier step in `llm_steps[]` (covers both "no step produces it" and "only a later step produces it") | `step '<step>' on component '<id>' consumes '<name>', which no earlier step produces — add a preceding step with 'produces: <name>', or remove it from 'consumes'` |
+| `on_failure` guard targets a non-earlier step | `when.guard: on_failure` and `when.target` does not name a strictly-earlier step in `llm_steps[]` (the target namespace is step names, not artifacts) | `guard 'on_failure' in step '<step>' of component '<id>' targets step '<target>', which is not a strictly-earlier step of this component — 'on_failure' can only observe the outcome of a step that has already run` |
+| `on_missing` guard targets an unproduced artifact | `when.guard: on_missing` and `when.target` is not the `produces` of any strictly-earlier step (the target namespace is artifact/`produces` names, not step names) | `guard 'on_missing' in step '<step>' of component '<id>' targets artifact '<target>', which no earlier step produces` |
+| `on_flag` guard targets an unproduced artifact | `when.guard: on_flag` and the artifact segment (before the first `.`) of the dotted `when.target` is not the `produces` of any strictly-earlier step | `guard 'on_flag' in step '<step>' of component '<id>' targets '<target>', but artifact '<artifact>' is not produced by any earlier step` |
+| capability outside ceiling | profile declares `config.capability_ceiling` and a mounted component's `required_capabilities` names a capability not in that set (exact-string containment, no hierarchy inference) | `component '<id>' requires capability '<capability>', which is outside the profile's capability_ceiling (<declared set>)` |
+| slot referenced but not declared | prompt text contains `{{ slot.<name> }}` and the component declares no such slot (including the case where it declares none at all) | `component '<id>' references slot '<name>' in its prompt text, which it does not declare (declared: <names>)` / `… but declares no slots` |
+| slot declared but not referenced | a `slots[]` entry no prompt text of that component references | `component '<id>' declares slot '<name>' but no prompt text references '{{ slot.<name> }}'` |
+| slot name unusable in a reference | a `slots[]` entry's `name` does not match `[a-z_][a-z0-9_]*`, so no `{{ slot.<name> }}` could ever resolve to it | `<owner> declares slot '<name>', which is not a usable slot name — a name must match [a-z_][a-z0-9_]* …` |
+| `produces_exclusive` with no artifact | `llm_steps[].produces_exclusive: true` on a step that declares no `produces` | `step '<step>' on component '<id>' declares 'produces_exclusive' but produces no artifact …` |
+| slot with no variants | a `slots[]` entry whose `variants` map is empty | `<owner> declares slot '<name>' with no variants` |
+| slot `default` outside its variants | `slots[].default` names a key absent from that slot's `variants` | `<owner> declares slot '<name>' with default '<key>', which is not one of its variants (<keys>)` |
+| duplicate slot name | two `slots[]` entries on the same component share a `name` | `component '<id>' declares slot '<name>' more than once` |
+| unrecognised `{{ … }}` in prompt text | a step body, `brief`, mount `brief`, `system_prompt` or slot variant contains a `{{ … }}` that is not `project`, `project_name`, or `slot.<name>` | `unrecognised template syntax in <surface>: '{{ … }}' is not a known placeholder … A single brace needs no escaping …` |
+| template statement or comment delimiter | the same surfaces contain `{%` or `{#` | `unrecognised template syntax in <surface>: '{%' is a template statement or comment delimiter, which Warble does not support …` |
+| profile/component slot name collision | a `profile.yml` `slots[]` entry shares a `name` with any mounted component's `slots[]` entry | `profile '<profile>' declares slot '<name>', which component '<id>' also declares — slot names are shared across the whole project, so rename one of them` |
+| profile slot referenced but not declared | `system_prompt` contains `{{ slot.<name> }}` and the profile declares no such slot | `profile '<profile>' references slot '<name>' in its system_prompt, which it does not declare (declared: <names>)` |
+| profile slot declared but not referenced | a profile `slots[]` entry its `system_prompt` never references | `profile '<profile>' declares slot '<name>' but its system_prompt does not reference '{{ slot.<name> }}'` |
+| duplicate profile slot name | two profile `slots[]` entries share a `name` | `profile '<profile>' declares slot '<name>' more than once` |
+| asset path escapes its directory / is missing | an `assets[].path` is absolute, contains `..`, or names no existing file (the shared file-reference rule) | `asset '<path>' must be a relative path inside its own directory …` / `… does not exist: <path>` |
+| authored asset `hash` / `bytes` | `component.yml` supplies either field on an `assets[]` entry; both are compile-computed and not authorable | `unknown field 'hash'` / `unknown field 'bytes'` (serde `deny_unknown_fields`) |
+| slot variant reference escapes its directory / is missing | a `slots[].variants` value is absolute, contains `..`, or names no existing file (the shared file-reference rule, as for `prompt_ref`) | `slot '<name>' variant '<key>' must be a relative path inside its own directory …` / `… does not exist: <path>` |
 
 `required_capabilities` is **declared only** in this POC (not enforced by the compiler;
-enforcement is the dispatcher/runtime's job).
+enforcement is the dispatcher/runtime's job) — except against a profile's `config.capability_ceiling`,
+which the compiler does check at compile time (see [`capability_ceiling`](#capability_ceiling-additive-since-v07)
+above). The ceiling check is an authorization gate on what a component may declare; it never
+substitutes for, and is unaffected by, the dispatch-time resolution that still happens later.
 
 ## Prompt rendering
 
@@ -608,6 +916,16 @@ named by step, with placeholders substituted from coarse context:
 
 - `{{project}}` → `context_binding.project`
 - `{{project_name}}` → basename of the project path
+- `{{ slot.<name> }}` → **not** substituted here; carried through for dispatch to fill from that
+  slot's variants (see [`slots`](#slots-additive-since-v07))
+
+Surrounding whitespace inside the braces is ignored. **Any other `{{ … }}`, and any `{%` or `{#`,
+is a compile error** in every prompt-text surface — step bodies, a component or mount `brief`, the
+profile `system_prompt`, and slot variants. Single braces are untouched, so a prompt teaching a
+model to emit JSON needs no escaping. There is deliberately no escape sequence for a literal `{{`:
+the substitution is plain string replacement, not a template engine, so there is nothing to escape
+for — and refusing the unrecognised forms is what lets a real engine replace it later without
+migrating any authored file.
 
 Each `llm_calls[]` entry also carries its own **per-step rendered `prompt`** — the same
 substitution as `prompt_fragment`, but rendered **per step and without** the `## <name>` header.
@@ -657,7 +975,7 @@ Warble differentiator.
 `warble compile ./examples/demo-agent -o ir.json` against the demo project in this repo must produce an
 IR equal to `examples/demo-agent/ir.golden.json` (committed alongside, used as the core's fixture test).
 `warble compile ./examples/render-demo -o ir.json` similarly must equal
-`examples/render-demo/ir.golden.json`. Both goldens use the current v0.6 contract:
+`examples/render-demo/ir.golden.json`. Both goldens use the current v0.8 contract:
 `context_requirements`, `context_precondition`, and `params` are always present (possibly `[]`, as
 on `dashboard`), while `eval` appears only on `generate_dashboard` and `scope: "."` appears only on
 render-demo's authored `artifact_write` guardrail.
@@ -668,8 +986,9 @@ render-demo's authored `artifact_write` guardrail.
 
 Where v0.2 carried a coarse project path and *declared* preconditions, v0.3 made the front-end
 **probe the bound context**. A host injects a `ContextLoader` (the trait lives in core, sans-IO).
-The same binding crate now supplies `MdlContext` for Wren projects and `RawSourceContext` for raw
-constitutive input; hosts may supply other adapters.
+Warble ships `PreparedContext` — which reads a projection the layer's own owner wrote, so any
+semantic format binds without Warble speaking it — plus `RawSourceContext` for raw constitutive
+input and `ExternalContext` for a layer held elsewhere; a host may supply its own loader.
 
 ## What lands in the IR
 - For a Wren project, `context_binding.resolved` carries the compiler's introspection result: `metrics`
@@ -692,13 +1011,14 @@ answerable only over a declared metric (see the `context_precondition` section a
 source through `RawSourceContext`; an MDL-only adapter returns unanswerable for both.
 
 ## `blast_radius` (read path)
-The adapter self-builds a lineage DAG (`model → relationship / cube → metric / dimension`, plus view
-references), and core computes `LineageGraph::blast_radius(node)` = the transitive downstream closure
-+ worst `Severity` (`Semantic > Structural > Compatibility > None`). This is exposed as read-only
-analysis on the read path, and the same query also serves as an enforcement gate for *mutating*
-applies. This is the one `provided_by: warble`
-capability — see `capability-model.md` §6/§7.1, whose coarse-binding loud-fail is now lifted because
-fine-grained binding exists.
+The bound layer's owner builds the lineage DAG (`model → relationship / cube → metric / dimension`,
+plus view references) **and** computes each node's downstream closure with a severity **rank** on its
+own scale, supplying both in the prepared-context document. Warble computes neither: it compares a
+supplied rank against an authored ceiling and decides `allow` / `escalate` / `block`, refusing
+outright when no analysis was supplied. That gate is exposed as read-only analysis on the read path
+and as the enforcement gate for *mutating* applies. It remains the one `provided_by: warble`
+capability, on those grounds rather than on computing the closure — see `capability-model.md` §6/§7.1
+and `blast-radius.md`.
 
 ---
 
@@ -772,6 +1092,15 @@ instead of trusting the prose alone:
 Both are additive optional fields on the existing envelope/block shapes above, not a new block type;
 a renderer or consumer that doesn't recognize them ignores them.
 
+When a render envelope crosses a future same-profile component-call boundary, it is wrapped as the
+`kind: render` success variant and validated against the **callee's** block contract. A
+non-rendering terminal JSON value (including the current tabular
+`{columns, rows, summary, verified, definition}` shape) is wrapped as `kind: value`. The child does
+not render or persist either form; only the root invocation owns those effects. The normalized
+wrapper and failure vocabulary are specified in
+[`component-composition.md`](./component-composition.md#6-target-neutral-request-and-result-envelopes),
+and are not part of the resolved v0.8 IR.
+
 ## 3. Renderer registry — `render(target, blocks[]) → artifact`
 Warble owns the **contract + a reference renderer (HTML)**; runtimes register/override per target.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warble/ir-spec",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "license": "Apache-2.0",
   "type": "module",
   "description": "The Warble IR (warble_ir_version) as a resolvable npm package: a version constant plus the compile-contract schema document. Not a runtime dependency — its version IS the contract.",