chore(stability): define the stability contract and graduate the proven core

CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.130.0
+
+### Stability contract + first graduation
+
+[docs/STABILITY.md](./docs/STABILITY.md) defines what `@stable` / `@experimental` promise consumers, the graduation bar (substantive tests + a curated-doc section + at least one real consumer + a 30-day quiet API + a CHANGELOG graduation entry), and the demotion/removal policy. A symbol tag wins over its module tag; an untagged symbol in an untagged module is experimental by default. This entry is the initial graduation: each family below is promoted at its current post-0.129.0 exact-profile shape with the evidence that passed the bar, and the 30-day breaking-change clock applies to every `@stable` symbol from this release forward.
+
+Promoted `@experimental` → `@stable` (per-symbol and module-level):
+
+- `runAgentRounds` + the kernel contract (`Driver`, `Validator`, `OutputAdapter`, `Iteration`, `LoopResult`, `AgentRunSpec`, `SandboxClient`, `ExecCtx`, `LoopTraceEmitter`, `RunAgentRoundsOptions`, and the trace-event/provenance closure in `src/runtime/types.ts`) — tests: `tests/kernel/` (`run-loop-harden`, `loop-dispatch` + the kernel suite); doc: `docs/canonical-api.md`; consumers: `bench/src/research-shot.ts`, `bench/src/corpus.ts`.
+- `supervise` / `Scope` / `Supervisor` (+ `createScope` / `createSupervisor` via their module tags) — tests: `tests/kernel/supervise.test.ts` (1,878 lines) + `coordination-driver` / `coordination-mcp`; docs: `docs/execution-model.md`, `docs/canonical-api.md`; consumers: `bench/src/gate.ts`, `examples/supervise`, `examples/supervisor-loop`.
+- personify combinators `pipeline` / `fanout` / `loopUntil` / `panel` / `verify` / `widen` + `definePersona` / `runPersonified` — tests: `tests/kernel/personify.test.ts` (797 lines); doc: `docs/canonical-api.md`; consumers: `examples/graphs`, `bench/src/gate.ts`.
+- the spawn journal family (`InMemorySpawnJournal`, `FileSpawnJournal`, `InMemoryResultBlobStore`, `FileResultBlobStore`, `replaySpawnTree`, the `SpawnForest*` views) — tests: `tests/runtime/spawn-journal-replay-identity.test.ts` + the kernel suite's journal assertions; doc: `docs/canonical-api.md`; consumers: `bench/src/gate.ts`, `examples/recursive-supervisor`.
+- the `/mcp` delegation queue + stores + status tools (`DelegationTaskQueue`, the delegation store, the feedback store, `delegate`, `delegation_status`, `delegation_history`, `delegate_feedback`) — tests: `tests/mcp/` (`task-queue`, `task-queue-durable`, `delegation-store`, `delegation-status`, `delegation-history`, `delegate`, `delegate-feedback`); doc: `docs/agent-managed-compute/current-state.md`; consumers: the shipped `agent-runtime-mcp` server (`src/mcp/server.ts`) + `examples/supervisor-loop/run-supervisor-mcp.ts`.
+- `/intelligence` (all six module-tagged modules: the barrel, `capability`, `delivery`, `effort`, `resolver`, `with-intelligence`) — tests: in-package (`capability` / `delivery` / `intelligence` / `with-intelligence`, ~1,969 lines); doc: `docs/intelligence-sdk.md`, whose status has been "shipped" since it landed; consumers: `examples/intelligence-recommend`, `examples/intelligence-webcode`, `examples/intelligence-drop-in`, `examples/self-improving-loop`.
+- the improvement generators (`improve`, the agentic generator, the improvement driver, the raw-trace distiller, the reflective generator) — tests: `src/improvement/improve.test.ts` (919 lines) + the in-package suite; doc: `docs/canonical-api.md`; consumers: `bench/src/swe-bench-env.ts`, `examples/improve`.
+- `streamAgentTurn` / `collectAgentTurn` + the turn types (`AgentTurnBackend`, `AgentTurnInput`, `AgentTurnUsage`, `CollectedAgentTurn`, `StreamAgentTurnOptions`) — tests: `src/runtime/stream-agent-turn.test.ts` (690 lines); doc: `docs/canonical-api.md`; consumers: `bench/src/router-turn.ts`, `bench/src/benchmarks/appworld.ts`, `examples/chat-handler`, `examples/runtime-run`.
+
+Kept `@experimental`, each with the failing check:
+
+- `Scope.resume` / `SupervisorOpts.resume` and `EventBus` / `createEventBus`: same-process replay only — live supervised-tree recovery after a coordinator restart and the durable cross-process mailbox are listed Not implemented in `docs/agent-managed-compute/README.md`.
+- The detached/worktree delegation leaves (`src/mcp/delegates.ts`, `detached-coder`, `detached-turn`, the worktree harnesses, `local-harness`): the module doc records the unfinished `driveTurn`-over-a-detached-session resume path.
+- The coordination MCP (`src/mcp/tools/coordination.ts`, `src/runtime/supervise/coordination-mcp.ts`): authenticated remote coordination is Not implemented.
+- `LoopLineageOptions` / `RunAgentRoundsOptions.lineage` and the member-level extension points `Driver.selectWinner`, `SandboxClient.criuStatus`, `ExecCtx.onSandboxEvent`: opt-in surfaces whose platform contracts (session continuity, CRIU fork) are still being proven.
+
+Newly tagged `@experimental` (previously untagged, unfinished):
+
+- `src/agent/define-agent.ts` — manifests validate and load, but `runtime.act` is not wired end-to-end into the eval path (`unimplementedAgentRun` is the shipped default).
+- `src/runtime/strategy-evolution.ts` — the multi-generation strategy search, a research surface.
+- the `/candidate-execution` subpath barrel.
+- the supervisor restart-recovery and event-bus durability members listed under "kept" above, now tagged explicitly at the symbol level.
+
+Maturity now renders in the generated reference: `tsdoc.json` extends TypeDoc's base tag definitions, and each subpath barrel carries `@module`, so `docs/api/<subpath>.md` shows the module-level `Stable` / `Experimental` badge directly under the page title. Module-level tags previously rendered nowhere in `docs/api`.
+
 ## 0.129.0
 
 - Require Agent Eval 0.144.4, Agent Interface 0.43.1, Agent Knowledge 7.0.11, and Sandbox 0.19.1 as one dependency set, and route the official-optimizer callback through Runtime's exact `AgentProfile` execution path.

README.md

@@ -529,6 +529,7 @@ All 29 live in [`examples/`](./examples).
 - New here? [`docs/concepts.md`](./docs/concepts.md), the mental model in plain terms.
 - [`docs/canonical-api.md`](./docs/canonical-api.md), find the primitive: "I want to ___ → use ___".
 - [`docs/api/primitive-catalog.md`](./docs/api/primitive-catalog.md), every export in one generated, never-stale list with its import path. Check it before building anything new.
+- [`docs/STABILITY.md`](./docs/STABILITY.md), what `@stable` / `@experimental` promise you, and how a symbol graduates.
 - [`docs/design.md`](./docs/design.md), the design philosophy and the internal research docs behind it: background reading, not required to use the package.
 - [`bench/HARNESS.md`](./bench/HARNESS.md), the experiment harness and how to run a benchmark.
 

docs/README.md

@@ -32,6 +32,7 @@ These are internal working documents: design theses, research narrative, and roa
 |---|---|---|
 | [../README.md](../README.md) | API entry point | Install, the loop API, the plain-language framing, the exported subpaths. Start HERE. |
 | [canonical-api.md](./canonical-api.md) | API spine + decision table | The conceptual spine + the "I want to ___ → use ___" anti-reinvention matrix of LOCAL symbols. Per-symbol signatures are generated into [api/](./api/). |
+| [STABILITY.md](./STABILITY.md) | stability contract | What `@stable` / `@experimental` promise consumers, the graduation bar, and the demotion/removal policy. |
 | [concepts.md](./concepts.md) | mental model | The product-API layer cake (chat turns, tasks, runs) — the onramp before the loop/strategy docs. |
 | [glossary.md](./glossary.md) | canonical vocabulary | One definition per term, grounded to `file:line`; drifted synonyms flagged. |
 | [execution-model.md](./execution-model.md) | the picture | The unified `Executor` port (router/bridge/cli/sandbox/BYO) + two engines, driver vs worker, spawn mechanics. |

docs/STABILITY.md

@@ -0,0 +1,40 @@
+# API stability — what `@stable` and `@experimental` mean
+
+Every exported symbol in this package carries a maturity level, declared with the TSDoc modifier tags `@stable` and `@experimental` (`@stable` is defined in [`tsdoc.json`](../tsdoc.json); `@experimental` is a TSDoc built-in).
+This doc defines what those tags promise, how a symbol graduates, and how one is demoted or removed.
+
+## What the tags mean for consumers
+
+**`@stable`** — the symbol's shape and documented behavior are a contract.
+You can build a product on it.
+A breaking change to a stable symbol goes through the demotion/removal process below: it is never silent, never same-release, and always ships with a named migration path in the CHANGELOG.
+
+**`@experimental`** — the symbol may change shape, change behavior, or disappear in any release, with only a CHANGELOG line.
+Use it to build, not to depend on: pin an exact version if an experimental symbol is load-bearing for you, and expect to follow the CHANGELOG when you bump.
+
+**Where a tag lives.**
+A tag on the symbol itself always wins.
+An untagged symbol inherits the module-level tag of the file that declares it.
+An untagged symbol in an untagged module is **experimental by default** — stability is opt-in and explicit, never assumed.
+A member-level `@experimental` inside a `@stable` interface marks that one member (an extension point) as still movable while the rest of the interface is contractual.
+
+**Where you see it.**
+The generated reference ([`docs/api/`](./api/)) renders **`Stable`** / **`Experimental`** badges on tagged symbols, and each subpath page (e.g. [`api/intelligence.md`](./api/intelligence.md)) renders its module-level badge directly under the page title.
+Module-level tags on non-entry source files are authoritative for inheritance but only render through the subpath page and per-symbol badges.
+
+## Graduation bar — experimental → stable
+
+A symbol (or a whole subpath) is promoted only when **all** of the following hold:
+
+1. **Substantive test coverage** — tests that exercise the documented behavior, not just imports that compile.
+2. **A curated-doc section** — the symbol appears in a hand-maintained doc ([`canonical-api.md`](./canonical-api.md), a dedicated doc such as [`intelligence-sdk.md`](./intelligence-sdk.md), or a subpath guide); a generated `api/` page alone does not count.
+3. **At least one real consumer** — `bench/`, `examples/`, or an external package actually calls it on a real path.
+4. **No breaking change to its API in the last 30 days** — the shape has stopped moving before the promise is made.
+5. **A CHANGELOG graduation entry** — the release notes name every promoted symbol and record the evidence for 1–3.
+
+Promotion is a normal PR: flip the tags (per-symbol and module-level), add the CHANGELOG entry, regenerate `docs/api`.
+
+## Demotion and removal
+
+A `@stable` symbol is demoted back to `@experimental`, or removed, only through a deprecation cycle: the release that announces it adds `@deprecated` (naming the replacement or the reason) while the symbol keeps working, the CHANGELOG entry names the symbol and the migration path, and removal lands no earlier than the next minor release after the announcement.
+An `@experimental` symbol needs none of that — it can be reshaped or removed in any release with a CHANGELOG line — which is exactly why the default is experimental and the stable set is enumerated, not implied.

docs/api/candidate-execution.md

@@ -6,6 +6,11 @@
 
 # candidate-execution
 
+**`Experimental`**
+
+`@tangle-network/agent-runtime/candidate-execution` — sealed candidate bundles
+plus the isolated prepare/execute/finalize/recover lifecycle around them.
+
 ## References
 
 ### AgentCandidateCodeSource

docs/api/index.md

@@ -7923,6 +7923,8 @@ Dollar accounting is known unless explicitly false. A false value must not be tr
 
 ### Scope
 
+**`Stable`**
+
 The budget-conserving reactive scope an `Agent.act` runs inside. `spawn` reserves
 budget atomically from the shared pool and fails closed when the pool cannot cover it.
 `next()` waits for one settlement from this scope's live set; `view` reads live state,
@@ -7949,6 +7951,8 @@ This scope's abort signal — aborted when the run is cancelled, a breaker trips
 
 > `readonly` `optional` **resume?**: [`ResumedWork`](runtime.md#resumedwork)\<`Out`\>
 
+**`Experimental`**
+
 Prior committed work, present ONLY on a resumed run (`undefined` on a fresh run, which is
 every run that did not pass `SupervisorOpts.resume`). The supervisor `loadTree`s the journal
 first; when a non-empty tree exists it rehydrates the already-settled children (via
@@ -7957,6 +7961,9 @@ re-spawning committed work. A resume-blind driver simply ignores it and re-spawn
 but redundant. The scope's spawn ordinal + cursor seq are already advanced past the recorded
 maxima, so any NEW spawn appends without colliding with a journaled event.
 
+ Same-process replay only — live supervised-tree recovery after a
+coordinator restart is not implemented (docs/agent-managed-compute/README.md).
+
 ##### view
 
 > `readonly` **view**: [`TreeView`](runtime.md#treeview)
@@ -8183,6 +8190,8 @@ metered event is cost-critical, so it lands before the join-barrier roll-up).
 
 ### Supervisor
 
+**`Stable`**
+
 Owns the conserved pool, the spawn log, the abort cascade, the OTP intensity breaker,
 and the root handle. `run` executes the root `Agent` to completion; `attach` wires a
 live `RootHandle` (the Q2 substrate the chat/pi-viz client later consumes).
@@ -8239,7 +8248,7 @@ live `RootHandle` (the Q2 substrate the chat/pi-viz client later consumes).
 
 ### Driver
 
-**`Experimental`**
+**`Stable`**
 
 #### Type Parameters
 
@@ -8261,8 +8270,6 @@ live `RootHandle` (the Q2 substrate the chat/pi-viz client later consumes).
 
 > `readonly` `optional` **name?**: `string`
 
-**`Experimental`**
-
 Stable identifier surfaced in trace events. Default `'driver'`.
 
 #### Methods
@@ -8271,8 +8278,6 @@ Stable identifier surfaced in trace events. Default `'driver'`.
 
 > **plan**(`task`, `history`): `Promise`\<`Task`[]\>
 
-**`Experimental`**
-
 Tasks to issue this iteration. `[task]` → refine; N copies → fanout;
 `[]` → no more work this round (kernel proceeds to `decide`).
 
@@ -8294,8 +8299,6 @@ readonly [`Iteration`](runtime.md#iteration-1)\<`Task`, `Output`\>[]
 
 > **decide**(`history`): `Decision` \| `Promise`\<`Decision`\>
 
-**`Experimental`**
-
 Inspect history and return the next state. The kernel terminates the
 loop when `decide` returns a value listed in `isTerminalDecision`
 (`'stop' | 'pick-winner' | 'fail' | 'done'`), when `maxIterations`
@@ -8315,8 +8318,6 @@ readonly [`Iteration`](runtime.md#iteration-1)\<`Task`, `Output`\>[]
 
 > `optional` **describePlan**(): [`LoopPlanDescription`](runtime.md#loopplandescription) \| `undefined`
 
-**`Experimental`**
-
 Optional: describe the move `plan()` just produced, for trace emission.
 The kernel calls this immediately after `plan()` and emits the result in
 the `loop.plan` event so a topology viewer can render the agent's chosen
@@ -8356,7 +8357,7 @@ readonly [`Iteration`](runtime.md#iteration-1)\<`Task`, `Output`\>[]
 
 ### LoopResult
 
-**`Experimental`**
+**`Stable`**
 
 #### Type Parameters
 
@@ -8378,73 +8379,53 @@ readonly [`Iteration`](runtime.md#iteration-1)\<`Task`, `Output`\>[]
 
 > **decision**: `Decision`
 
-**`Experimental`**
-
 ##### iterations
 
 > **iterations**: [`Iteration`](runtime.md#iteration-1)\<`Task`, `Output`\>[]
 
-**`Experimental`**
-
 ##### winner?
 
 > `optional` **winner?**: [`LoopWinner`](runtime.md#loopwinner)\<`Task`, `Output`\>
 
-**`Experimental`**
-
 ##### durationMs
 
 > **durationMs**: `number`
 
-**`Experimental`**
-
 ##### costUsd
 
 > **costUsd**: `number`
 
-**`Experimental`**
-
 Sum of every iteration's `costUsd`.
 
 ##### costUsdKnown?
 
 > `optional` **costUsdKnown?**: `false`
 
-**`Experimental`**
-
 False when `costUsd` is only the observed subtotal, not a complete bill.
 
 ##### estimatedCostUsd?
 
 > `optional` **estimatedCostUsd?**: `number`
 
-**`Experimental`**
-
 Sum of separately-labelled local/catalog estimates.
 
 ##### promptCache?
 
 > `optional` **promptCache?**: `Record`\<`string`, `string` \| `number`\>
 
-**`Experimental`**
-
 Aggregated provider-reported prompt-cache fields.
 
 ##### tokenUsage
 
 > **tokenUsage**: [`LoopTokenUsage`](runtime.md#looptokenusage)
 
-**`Experimental`**
-
 Sum of every iteration's token usage. `loopDispatch` commits it through
  the campaign's paid-call receipt.
 
 ##### provenance
 
 > **provenance**: [`RunProvenance`](runtime.md#runprovenance)
 
-**`Experimental`**
-
 Domain-free run provenance for auditability: the mount manifest recorded
  during `prepareBox` and the selection receipts for how the winner was
  chosen. Always present; empty arrays when nothing was recorded.

docs/api/intelligence.md

@@ -6,6 +6,24 @@
 
 # intelligence
 
+**`Stable`**
+
+Tangle Intelligence SDK — trace capture plus reviewable improvement.
+
+The client keeps live-agent trace delivery best-effort. The separate
+improvement-cycle exports analyze completed traces, run a signed baseline
+versus candidate experiment, bind review to its result, and activate only
+the exact measured candidate.
+
+  1. OBSERVE — wrap a generic agent and export one trace span per call to
+     Tangle Intelligence, swallowing every export failure so a live agent
+     never fails because Intelligence is down.
+  2. MODE 0 / OFF — at `effort: 'off'`, run the agent as PURE PASSTHROUGH
+     (zero intelligence spawns) with best-effort telemetry still on. The
+     exported trace tags usage by class `{ inferenceUsd, intelligenceUsd }`,
+     and at OFF `intelligenceUsd` is provably `0` — the mechanism that proves
+     an OFF customer paid inference-only.
+
 ## Classes
 
 ### CapabilityNotAdmittedError