@openwop/spec-artifacts 2.44.4 → 2.44.6

package/spec/v2/core/interrupt.md

@@ -5,7 +5,7 @@
 
 ## Why this exists
 
-`interrupt` is how a run waits for something outside itself: a decision, an answer, an event, a conversation turn. Every kind shares one payload shape, event pair, resolve contract and token scheme, so a client that resolves an approval can resolve anything.
+`interrupt` is how a run waits for something outside itself: a decision, an answer, an event, a conversation turn. Every kind shares one payload shape, event pair, resolve contract and token scheme.
 
 ## Payload
 
@@ -35,7 +35,7 @@ Per-kind rules:
 
 ### Re-entry and resume values
 
-`key` is the deterministic re-entry key of one invocation. A host MUST derive it from at least the run, the node and the node's visit index: the number of that node's interrupts in this run whose resolution was consumed before this execution began. Its spelling is host-defined.
+`key` is the deterministic re-entry key of one invocation. A host MUST derive it from at least the run, the node and the node's visit index: how many of that node's interrupts in this run had their resolution consumed before this execution began. Its spelling is host-defined.
 
 - A replay or recovery of the same execution MUST re-derive the same key.
 - A later execution of the node, reached over an edge, MUST derive a different key, MUST raise a new `interrupt.requested`, and MUST NOT return an earlier visit's `resumeValue`.
@@ -45,7 +45,7 @@ Per-kind rules:
 - An in-memory cache MAY serve in-process replays but MUST NOT replace the event log for cross-process replays.
 - A host MUST validate the resume value against `resumeSchema` when one is declared, and MUST refuse a failing value with `400 validation_error`.
 
-`timeoutMs`, when set, is the interrupt's own deadline. What an approval gate does when it elapses is §Rejection.
+`timeoutMs`, when set, is the interrupt's own deadline; for an approval gate see §Rejection.
 
 ## Events
 
@@ -54,7 +54,7 @@ Every kind uses two registered types ([events.md](events.md)):
 - `interrupt.requested` — the payload is the `InterruptPayload` verbatim.
 - `interrupt.resolved` — the closed payload is `interruptResolved`. Resolving an approval-kind interrupt MUST record the applied `action` there, with the field §Approval requires.
 
-The kind-specific `approval.*` and `clarification.*` types remain registered. Their payload definitions in `schemas/v2/run-event-payloads.schema.json` are `$ref` aliases of `interruptRequested` and `interruptResolved`. A host emitting `interrupt.requested` MAY also emit the kind-specific type.
+The kind-specific `approval.*` and `clarification.*` types remain registered; their payloads in `schemas/v2/run-event-payloads.schema.json` are `$ref` aliases of `interruptRequested` and `interruptResolved`. A host emitting `interrupt.requested` MAY also emit the kind-specific type.
 
 Both events are durable and appear in the `updates` and `debug` stream modes. While suspended, `RunSnapshot.currentNodeId` names the node and `status` is `waiting-approval`, `waiting-input` or `waiting-external`.
 
@@ -72,7 +72,7 @@ Both events are durable and appear in the `updates` and `debug` stream modes. Wh
 
 ### Callback delivery
 
-`createRun.callbackUrl` names where a host that advertises `interrupt.callbackDelivery: true` delivers notice of an interrupt, so its holder can resolve it through the token surface. The payload, timing and signing are host-defined.
+`createRun.callbackUrl` names where a host advertising `interrupt.callbackDelivery: true` delivers notice of an interrupt, for resolution through the token surface. Payload, timing and signing are host-defined.
 
 A host advertising the facet:
 
@@ -98,7 +98,7 @@ The token grammar and the `interrupt.tokenAlgs[]` / `kid` check are [identity.md
 
 - **Expiry.** Every token MUST carry `expiresAt`. The default SHOULD be 30 minutes, and a host MUST cap the lifetime at the interrupt's `timeoutMs` when one exists. A token MUST NOT outlive the interrupt it resolves; past `expiresAt` the host MUST answer `410 interrupt_expired`.
 - **Invalidation.** A token MUST be invalidated when its interrupt is resolved or its run is cancelled or completed. Later use MUST answer `409 interrupt_already_resolved`.
-- **Verification.** MAC comparison MUST be constant-time. `kid` selects the verification secret, so secrets rotate without orphaning outstanding tokens.
+- **Verification.** MAC comparison MUST be constant-time. `kid` selects the verification secret, so secrets rotate without orphaning tokens.
 - **Intent.** A token minted with `intent: resolve` authorizes both operations. A host MAY mint `intent: inspect` tokens; a resolve with one MUST be refused with `403`.
 
 ## Approval
@@ -141,9 +141,9 @@ The facet `spec/v2/facets/interrupt.schema.json` carries `tokenAlgs[]` (REQUIRED
 - **`audience`** is a notification hint, never eligibility. When omitted, the host SHOULD notify the union of the eligibility refs.
 - A host that does not advertise a ref kind MUST ignore that field.
 
-Eligibility binds every writer of the suspension record, not every route. A host whose durable store is writable by a principal other than the engine MUST enforce the same eligibility at the store, or MUST NOT expose the record to that principal for write.
+Eligibility binds every writer of the suspension record. A host whose durable store is writable by a principal other than the engine MUST enforce the same eligibility at the store, or MUST NOT expose the record to that principal for write.
 
-Refs are opaque to the engine; the host resolves them. Membership MUST be resolved at decision time and MUST NOT be re-resolved during replay or `forkRun`: the recorded eligibility decision is fixed history ([replay.md](replay.md)).
+Refs are opaque to the engine. Membership MUST be resolved at decision time and MUST NOT be re-resolved during replay or `forkRun`: the recorded eligibility decision is fixed history ([replay.md](replay.md)).
 
 ## During the v1 overlap
 

package/spec/v2/core/oauth.md

@@ -5,11 +5,11 @@
 
 ## Why this exists
 
-A connector node needs a token a user granted to a third party. The host obtains, stores and refreshes it and hands it to the node's sandbox, so a pack names a provider and scopes and never touches the grant. Here the host is an OAuth client; [identity.md](identity.md) covers the host as a protected resource.
+A connector node needs a token a user granted to a third party. The host obtains, stores and refreshes it and hands it to the node's sandbox; a pack names a provider and scopes and never touches the grant. Here the host is an OAuth client; [identity.md](identity.md) covers it as a protected resource.
 
 ## Credentials
 
-A host advertising `credentials` MUST resolve a `{ ref, scope }` reference (`schemas/v2/credential-reference.schema.json`) at node execution and inject the material into the node sandbox only.
+A host advertising `credentials` MUST resolve a `{ ref, scope }` reference (`schemas/v2/credential-reference.schema.json`) at node execution and inject the material only into the node sandbox.
 
 - The material MUST NOT appear in inputs, variables, events, the debug bundle or replay state (invariant `credential-payload-redaction`).
 - A failed resolution is `credential_not_found`, `credential_forbidden` (outside the caller's scope; fail closed) or `credential_scope_unsupported` (a scope not in `credentials.scopes`).
@@ -46,7 +46,7 @@ Where the provider is reached as an MCP server:
 - It fetches the server's Protected Resource Metadata (RFC 9728) only from URLs derived from the manifest's server URL.
 - Discovery verifies and never selects. A discovered issuer or endpoint that differs from the manifest's, or from the tuple pinned at registration, MUST be refused `connection_auth_metadata_mismatch`. A grant for such a provider whose manifest declares no `issuer` MUST be refused the same way.
 
-This binds a provider the host configures itself as well as one a connection pack defines: the configured server URL and issuer stand in for the manifest's, and the tuple is pinned when the host loads that configuration.
+This binds a host-configured provider as well as a connection-pack one: the configured server URL and issuer stand in for the manifest's, pinned when the host loads that configuration.
 
 ## The credential interrupt
 
@@ -61,6 +61,6 @@ Then:
 - `connectUrl` MUST be host-owned, MUST NOT be pre-authenticated, and MUST complete only for the initiating Subject.
 - The host resolves the interrupt when the grant completes. A resolve of `authorized` MUST be refused `400 validation_error` unless a credential now resolves.
 - `declined` fails the node with `connector_auth_declined`.
-- A host that binds a node to one credential reference (for example, a connection) reads "resolves" as that reference resolving with the node's scopes, carries it as `credentialRef`, and still completes `connectUrl` only for the initiating Subject.
+- A host that binds a node to one credential reference (such as a connection) reads "resolves" as that reference resolving with the node's scopes, carries it as `credentialRef`, and still completes `connectUrl` only for the initiating Subject.
 
 *Sources: RFCs 0046, 0047, 0199.*

package/spec/v2/core/packs.md

@@ -14,7 +14,7 @@ A manifest's `engines.openwop` MUST match the grammar in `schemas/v2/node-pack-m
 - A v2 host MUST treat a range with no upper bound as bounded by `<2.0.0`.
 - A host MUST refuse to install a version whose range does not admit the host's protocol major with `pack_engine_unsupported` (`spec/v2/errors.json`).
 - `pack_runtime_requirement_unmet` remains a runtime-requirement code and MUST NOT be used for the protocol major.
-- Both checks MUST run at install on every publication path — the canonical registry, a vendor registry's write API, and a mirror ingest — so no registry-side artifact can bypass it.
+- Both checks MUST run at install on every publication path — the canonical registry, a vendor registry's write API, and a mirror ingest.
 
 The range is a claim about the pack's own surface, not about run semantics. Admitting major M asserts that:
 
@@ -37,7 +37,7 @@ A host advertises `packs` when it serves the registry surface above:
 
 The registry is versioned by tree, not header. It publishes `registry/v2/packs/<name>/-/<version>.{json,sbom.json,sig,tgz}` as a parallel tree of re-signed manifests with regenerated SBOMs and index.
 
-- A signed compatibility overlay MUST be rejected: signatures authorize by namespace, and a mirror re-derives the signer at ingest.
+- A signed compatibility overlay MUST be rejected; a mirror re-derives the signer at ingest.
 - `.well-known/openwop-registry.json` `endpoints` is the negotiation: it names both trees, and a client MUST resolve every registry path through it rather than construct one.
 - `publicKey` is unversioned: keys are not protocol-versioned.
 
@@ -85,7 +85,7 @@ There is one signing scheme. `signing` on a version manifest (`schemas/v2/regist
 - **`keyId`** is the signing key id.
 - A block carrying `method`, `publicKeyRef` or `signatureRef` fails validation.
 
-The same block applies to a **bare manifest** — the `pack.json` inside the tarball, which is the document the signature covers. `signing` is OPTIONAL there, because an authoring-time `pack.json` exists before it is signed. When present it MUST be the identical closed `{ keyId, scheme }` object, on every bare manifest kind.
+The same block applies to a **bare manifest** — the `pack.json` inside the tarball, which is the document the signature covers. `signing` is OPTIONAL there; when present it MUST be the identical closed `{ keyId, scheme }` object, on every bare manifest kind.
 
 - A verifier MUST verify the signature against the issuing registry's key for `keyId`, and MUST check the pack name against that key's `permittedNamespaces`.
 - A signature over tarball bytes is not a v2 signature; such a pack MUST be re-signed, not relabeled.
@@ -103,7 +103,7 @@ A registry MUST refuse a submission that breaks these rules or republishes a ver
 
 ## The registry's own schemas
 
-A registry MUST validate submissions against vendored copies of these schemas pinned to a corpus tag, and MUST re-sync them from that tag before any v2 publication. An unpinned or drifted vendored schema is a registry defect: it rejects documents the protocol requires the registry to accept.
+A registry MUST validate submissions against vendored copies of these schemas pinned to a corpus tag, and MUST re-sync them from that tag before any v2 publication. An unpinned or drifted vendored schema is a registry defect.
 
 ## Errors
 
@@ -126,7 +126,13 @@ A `frontend-plugin` pack (`schemas/v2/frontend-plugin-manifest.schema.json`) shi
 
 A host without `uiPlugins` MUST reject the pack and render its own way.
 
-A breaking method change is `ui-plugin/2`. `host.announce` MUST be length-capped (SHOULD ≤ 400 characters) and SHOULD be rate-limited; `host.documentChanged` SHOULD be debounced, and a plugin MUST treat the latest as authoritative and tolerate unknown `host.selectionChanged` kinds. `maxEntryBytes` caps an entry bundle.
+On the message protocol:
+
+- A breaking method change is `ui-plugin/2`.
+- `host.announce` MUST be length-capped (SHOULD ≤ 400 characters) and SHOULD be rate-limited.
+- `host.documentChanged` SHOULD be debounced. A plugin MUST treat the latest one as authoritative and tolerate unknown `host.selectionChanged` kinds.
+
+`maxEntryBytes` caps an entry bundle.
 
 ## During the v1 overlap
 

package/spec/v2/core/persistence.md

@@ -14,7 +14,7 @@ How a v2 host reads what a v1 host wrote, what happens to a run in flight at the
 - A host MUST NOT carry a private mapping.
 - A vendor-prefixed v1 type the codemap does not name MUST be read under its own name, unchanged.
 - "Vendor-prefixed" means the first segment is an org registered in the `extensions` object of `spec/v2/declaration.json` ([events.md §Rules](events.md)). `openwop.` is the only reserved prefix. An unregistered first segment is not a vendor prefix and falls to the refusal in §"The reader rule".
-- An org is registered by pull request against the corpus and takes effect on the `@openwop/spec-artifacts` release that carries it. A shipped entry is append-only: deregistering an org would turn every log already written under it from pass-through into refusal.
+- An org is registered by pull request against the corpus and takes effect on the `@openwop/spec-artifacts` release that carries it. A shipped entry is append-only.
 
 ## The era key
 
@@ -32,9 +32,9 @@ Discovery MUST advertise the value the host writes for new runs and nothing else
 Absent stays era `2` forever; it is never backfilled.
 
 - A host MUST NOT rewrite historical rows to add an explicit `2`, and a reader MUST NOT require one.
-- A host with more than one creation path MUST begin stamping `3` on all of them in the same change. An unstamped path's runs read as era `2` — a silent wrong read.
+- A host with more than one creation path MUST begin stamping `3` on all of them in the same change. An unstamped path's runs read as era `2`.
 
-The snapshot field is required on the wire, and MAY be synthesized: for an era-`2` run with nothing stored, the host MUST supply `2` from the absent-⇒-`2` rule rather than fail the read. The field alone therefore cannot falsify era handling; the reader and writer rules carry the obligation.
+The snapshot field is required on the wire, and MAY be synthesized: for an era-`2` run with nothing stored, the host MUST supply `2` from the absent-⇒-`2` rule rather than fail the read.
 
 ## The `eventLog` family
 
@@ -44,7 +44,7 @@ The snapshot field is required on the wire, and MAY be synthesized: for an era-`
 - MUST serve the cursor contract of [events.md §"Poll"](events.md) over that log;
 - MUST NOT emit an event `type` the codemap does not name.
 
-The record carries no separate storage claim: it asserts that the era key, the codemap and the poll cursor are implemented as written here. Its `crossEngineOrdering` facet is a replay property, specified in [replay.md §"Cross-engine ordering"](replay.md).
+The record makes no separate storage claim. Its `crossEngineOrdering` facet is a replay property, specified in [replay.md §"Cross-engine ordering"](replay.md).
 
 ## The reader rule
 
@@ -58,16 +58,16 @@ A v2 host reading a run in era `2` MUST translate every event through the codema
 
 The rule binds every reader: poll, SSE, fork, replay divergence, debug bundle, summary memory.
 
-The translation is a read projection. A host MUST NOT rewrite era-`2` rows in place. The one exception is a background backfill that stamps `3` and rewrites `type` under the same `(runId, sequence)` key: it is permitted only as an atomic per-run operation with the original preserved, because the fork prefix must stay byte-equivalent to the translated parent ([replay.md](replay.md)).
+The translation is a read projection. A host MUST NOT rewrite era-`2` rows in place. The one exception is a background backfill that stamps `3` and rewrites `type` under the same `(runId, sequence)` key: it is permitted only as an atomic per-run operation with the original preserved, so a fork prefix stays byte-equivalent ([replay.md](replay.md)).
 
 ### The writer rule
 
 The era key is fixed when the run is created and fixes the log's vocabulary for the run's lifetime.
 
 - An append to a run in era `2` MUST use v1 vocabulary — the name the codemap maps *from*, not the v2 name it maps to.
-- A host that upgrades mid-flight MUST NOT begin writing v2 names into a log the reader translates as era `2`. The reader would map an already-mapped name a second time, or fail with `event_type_unmapped` on a name absent from the codemap's v1 side.
+- A host that upgrades mid-flight MUST NOT begin writing v2 names into a log the reader translates as era `2`.
 - A run created after the upgrade is era `3` and is written in v2 vocabulary, untranslated.
-- A writer that emits a property a closed def cannot seat MUST mark the row with what it could not seat, so the refusal names the writer instead of surfacing as an unexplained read failure.
+- A writer that emits a property a closed def cannot seat MUST mark the row with what it could not seat, so the refusal names the writer.
 
 This binds every writer for as long as an era-`2` run stays open (§"Runs pinned to v1"). Its witness is `v2-era-2-append-vocabulary`.
 
@@ -76,7 +76,7 @@ This binds every writer for as long as an era-`2` run stays open (§"Runs pinned
 Through the overlap ([versioning.md §5](versioning.md)), an era-`3` log, stored in v2 vocabulary, must still read on `/v1/…` exactly as before the cut. A host serving both majors:
 
 - MUST map an era-`3` log's `type` back to its v1 spelling on the v1 read path, through the same codemap row, inverted.
-- MUST verify at load that `spec/v2/event-codemap.json` is a bijection, since only then is the inverse exact. If a row folds two v1 names onto one v2 name, the host MUST refuse to serve the v1 representation rather than guess a spelling.
+- MUST verify at load that `spec/v2/event-codemap.json` is a bijection. If a row folds two v1 names onto one v2 name, the host MUST refuse to serve the v1 representation rather than guess a spelling.
 - MUST emit a type with no codemap row (v2-only vocabulary, which has no v1 spelling) unchanged on the v1 read path, MUST NOT drop the row, and MUST NOT refuse the read for it.
 
 ### The seat
@@ -84,7 +84,7 @@ Through the overlap ([versioning.md §5](versioning.md)), an era-`3` log, stored
 - The adapter MUST sit at the storage boundary every reader passes through — the storage interface's event-list method, not a wrapper some call sites bypass.
 - A host leg MUST name its seat in its ADR.
 
-The seat is a claims-check ([conformance.md §Witness class](conformance.md)): it is discharged by that disclosure and by audit, never by the wire. It binds every reader, including ones the suite has no name for; `run-event.schema.json` records why passing legs do not discharge it.
+The seat is a claims-check ([conformance.md §Witness class](conformance.md)): it is discharged by that disclosure and by audit, never by the wire. It binds every reader, including ones the suite has no name for.
 
 ## Runs pinned to v1
 
@@ -100,9 +100,9 @@ Multi-region skew is read-side only: after the cut, a v2 region MUST NOT accept
 
 - **Certification bundles** — never upgraded. A v1 bundle substantiates no new certification after 2026-11-10; every host produces a fresh v2-rc bundle before the cut ([conformance.md](conformance.md)).
 - **Webhook deliveries** — dual-emitted, and queued deliveries drained, per [webhooks.md §"Dual emission through the overlap"](webhooks.md).
-- **Interrupt resume tokens** — drained. A token that is not `ow2.`-prefixed is a v1 token and resolves under `kid: legacy` until `expiresAt`; new tokens carry the `ow2.` prefix ([identity.md](identity.md)). The rule is written over the prefix, never a segment count.
+- **Interrupt resume tokens** — drained, per [identity.md](identity.md) §4.
 - **Layer-1 and Layer-2 records** (idempotency, idempotent responses, invocation claims and logs, effect-escape ledger, dispatch outbox, envelope correlations) — unchanged; keyed on ids the cut does not rename. `GET /runs/{runId}/effects` and `GET /runs/{runId}/compensation` are new reads over them ([security-defaults.md](security-defaults.md)).
-- **Owner stamps** — a run without a Subject MUST be legacy-stamped at first v2 read and MUST NOT be rewritten later. A host's stored owner fields are projected to the Subject; the projection is the host's to name.
+- **Owner stamps** — a run without a Subject is legacy-stamped per [identity.md](identity.md) §1.2. A host's stored owner fields are projected to the Subject; the projection is the host's to name.
 - **Audit log** — never upgraded.
 
 ## Per-store disposition
@@ -141,6 +141,4 @@ Template — one row per store:
 
 A host MAY claim a qualification rung (`durable-single-instance`, `durable-multi-instance`, `multi-region-qualified`; cumulative) only with the evidence [RFC 0158 §D](https://github.com/openwop/openwop/blob/main/RFCS/0158-durable-execution-and-disaster-recovery-qualification.md) names for it, and MUST NOT claim one from tests in which no process was terminated. A rung is evidence, not a capability: discovery carries none, and the certification bundle publishes the rung and its bounds ([conformance.md §Bundle v3](conformance.md)).
 
-See also: [overview.md](overview.md), [events.md](events.md), [replay.md](replay.md), [identity.md](identity.md), [webhooks.md](webhooks.md).
-
 *Sources: RFCs 0041, 0158, 0170, 0171, 0172, 0176, 0180, 0185, 0186, 0187.*

package/spec/v2/core/portability.md

@@ -5,7 +5,7 @@
 
 ## Why this exists
 
-A tenant's reusable estate moves between hosts as one export bundle, and lands on the destination under the importing caller's identity. This document states the bundle and the rules an importer follows. An adapter that turns another platform's export into a bundle is host tooling.
+A tenant's reusable estate moves between hosts as one export bundle, and lands on the destination under the importing caller's identity. An adapter that turns another platform's export into a bundle is host tooling.
 
 ## The export bundle
 
@@ -24,8 +24,8 @@ An `ExportBundle` (`schemas/v2/export-bundle.schema.json`) carries `bundleVersio
 
 ## Import rules
 
-- **No credential material.** A bundle MUST NOT contain credential values: a `connection-ref` item carries only references and provider ids. The importer MUST report unbound references in `secretsToRebind` and MUST NOT invent or transfer secret material. A host MUST reject with `422` an imported bundle whose payload carries a literal credential value.
-- **Dry run.** When `import` is advertised, import MUST offer a dry run. A dry run MUST NOT write, and MUST return the plan it would execute: creates, updates, skips, conflicts and unbound credential references.
+- **No credential material.** A bundle MUST NOT contain credential values: a `connection-ref` item carries only references and provider ids. A host MUST reject with `422` an imported bundle whose payload carries a literal credential value. The importer MUST report unbound references in `secretsToRebind` and MUST NOT invent or transfer secret material.
+- **Dry run.** When `import` is advertised, import MUST offer a dry run, which MUST NOT write and MUST return the plan it would execute: creates, updates, skips, conflicts and unbound credential references.
 - **Idempotent.** Import MUST be idempotent: re-applying a bundle resolves each item to `skipped` or `updated`, never to a duplicate create.
 - **Ordered.** Items MUST be applied in `dependsOn` topological order. A cycle is a `422`.
 - **Re-owned.** Every imported entity MUST be re-owned to the caller's Subject at the destination ([identity.md](identity.md) §1). `source.originPrincipal` is informational and MUST NOT grant any access. Host-scoped handles are re-minted as [identity.md](identity.md) §5 requires.
@@ -39,6 +39,6 @@ An applied import emits `import.applied` (`schemas/v2/run-event-payloads.schema.
 
 ## Routes
 
-No protocol path is defined for export or import: a host serves them on routes of its own. A host-private migration from an anonymous sandbox into a signed-in tenant fits this contract, because its response is a subset of the import outcome.
+No protocol path is defined for export or import: a host serves them on routes of its own. A host-private migration from an anonymous sandbox into a signed-in tenant fits this contract.
 
 *Sources: RFCs 0043, 0096, 0098.*

package/spec/v2/core/replay.md

@@ -5,11 +5,11 @@
 
 ## Why this exists
 
-`POST /runs/{runId}:fork` makes any past state of a run re-executable: a replay proves that current code reproduces recorded history; a branch explores an alternative from a recorded point. This document states what a fork MUST reproduce, what it MUST NOT re-fire, and how a host proves the second.
+`POST /runs/{runId}:fork` makes any past run state re-executable: a replay proves current code reproduces recorded history; a branch explores an alternative from a recorded point. This document states what a fork MUST reproduce, what it MUST NOT re-fire, and how a host proves the second.
 
 ## The surface
 
-A host that advertises `replay` ([capabilities.md](capabilities.md)) serves `forkRun` (`api/v2/openapi.yaml`, `POST /runs/{runId}:fork`) and `getEffectSeamManifest` (`GET /host/effect-seams`).
+A host advertising `replay` ([capabilities.md](capabilities.md)) serves `forkRun` (`api/v2/openapi.yaml`, `POST /runs/{runId}:fork`) and `getEffectSeamManifest` (`GET /host/effect-seams`).
 
 The `replay` facet (`spec/v2/facets/replay.schema.json`) is `{ modes[], retention?, effectSeamsManifest }`:
 
@@ -46,9 +46,9 @@ A host MUST cache the observable result (return value, workflow-state effects, e
 ## Determinism caveats (`replay` mode)
 
 1. A side-effecting node MUST NOT call the external system twice; see §Suppression.
-2. `ctx.interrupt(K)` MUST short-circuit to the persisted `interrupt.resolved` value.
+2. `ctx.interrupt(K)` MUST short-circuit to the persisted `interrupt.resolved`, raising no new `interrupt.requested`.
 3. `ctx.getVersion` pins from the source run are fixed history; the replay MUST take the recorded branch.
-4. Nodes MUST consume time via `ctx.now()` where available; direct clock reads make replay non-deterministic.
+4. Nodes MUST consume time via `ctx.now()` where available; direct clock reads are non-deterministic.
 5. Recorded-fact events such as `memory.written` are fixed history. A replay MUST re-emit them verbatim from the log and MUST NOT regenerate their identifiers or timestamps — never a new `memoryId`. A `branch` MAY perform its own memory writes with fresh identifiers.
 6. Approver eligibility recorded on a resume event is fixed history; a host MUST NOT re-resolve membership during replay.
 
@@ -80,11 +80,11 @@ For a fork with `mode: replay`:
 5. The guarantee is whole-run and requires both classification before execution and a default-deny guard at every effect seam.
 6. A dispatch to a peer host is an outbound call under rule 2; the peer is never contacted.
 
-Pure nodes and LLM calls served from the invocation log MUST re-execute live; otherwise divergence detection is vacuous.
+Pure nodes and LLM calls served from the invocation log MUST re-execute live.
 
 **Fan-out.** A host that projects its log outward — webhook delivery, A2A push, outbound streams, analytics or audit sinks — MUST NOT deliver events a replay re-emits as fixed history, and a fork of either mode MUST NOT inherit its source's A2A push configs. Replay-ness MUST be read from the run, never from the event type; the fork's own log MUST still carry the re-emitted events ([webhooks.md](webhooks.md)).
 
-**Branch.** A branch re-fires effects for sequences `>= fromSeq`; those are effects the operator asked for. A host MAY suppress branch effects and MUST NOT report that as replay suppression. A host SHOULD surface the re-fire in operator-facing fork UI.
+**Branch.** A branch re-fires effects for sequences `>= fromSeq`. A host MAY suppress branch effects and MUST NOT report that as replay suppression. A host SHOULD surface the re-fire in operator-facing fork UI.
 
 ### The effect-seam manifest
 
@@ -95,7 +95,7 @@ A host advertising `replay` MUST publish `schemas/v2/effect-seam-manifest.schema
 - Two seams a host guards through one code path but that leave by different mechanisms are different `kind`s; two that leave by the same mechanism for different business reasons are one.
 - `other` is the escape for a mechanism this list does not name — raw TCP, gRPC, a filesystem write, a device SDK. A row using it MUST carry `note` naming that mechanism.
 
-**Completeness outranks driveability.** Every outbound effect path the node runtime can reach MUST be listed, including one the suite cannot drive (typically `smtp` or `other`); the scenario records that one `inapplicable`, naming the mechanism. A host MUST NOT omit a seam because the suite cannot drive it, and MUST NOT relabel it as a `kind` the suite can drive. The manifest is a self-declaration whose false negatives are found by audit, not a witness.
+**Completeness outranks driveability.** Every outbound effect path the node runtime can reach MUST be listed, including one the suite cannot drive (typically `smtp` or `other`); the scenario records that one `inapplicable`, naming the mechanism. A host MUST NOT omit a seam because the suite cannot drive it, and MUST NOT relabel it as a `kind` the suite can drive.
 
 ## Replay-from-event-log internals
 
@@ -111,7 +111,7 @@ A v2 host MUST fork a run created before the cut (era `2`, [persistence.md](pers
 
 - The fork's prefix MUST be byte-equivalent to the *translated* parent — the parent as read through the codemap, not its stored bytes.
 - `run.started` on the fork MUST carry the legacy Subject (`issuer: urn:openwop:legacy`, [identity.md](identity.md)) where the parent had none.
-- A backfill of an era-`2` log is permitted only atomically per run with the original preserved, so this obligation stays checkable.
+- A backfill of an era-`2` log is permitted only atomically per run with the original preserved.
 
 ## Cross-engine ordering
 
@@ -120,16 +120,14 @@ When a host advertises both `idempotency.multiRegion` and `eventLog.crossEngineO
 - `status`, `variables`, and the projected event log up to `fromSeq` MUST be byte-equivalent across regions.
 - Per-region wall-clock and entropy fields in events after the boundary MAY differ.
 
-A host that advertises only one of the two keeps the single-region contract above; a host that advertises neither is single-region and the cross-region claim does not apply.
+A host advertising only one of the two, or neither, keeps the single-region contract.
 
 ## Retention
 
-A host advertising `replay` MUST document retention for source snapshots, source logs, the invocation records replay depends on, and forked runs; `retention.days` MAY advertise the window. When the range `fromSeq` needs has expired, the host MUST reject the fork with `410` or `422`; `details` SHOULD carry `sourceRunId`, `fromSeq`, and the boundary.
+A host advertising `replay` MUST document retention for source snapshots, source logs, the invocation records replay depends on, and forked runs; `retention.days` MAY advertise the window. When the range `fromSeq` needs has expired, the host MUST reject the fork with `410 run_expired` or `422`; `details` SHOULD carry `sourceRunId`, `fromSeq`, and the boundary.
 
 ## Declared nondeterminism
 
 `nondeterminismPolicy` is the host's statement of which nondeterministic sources it declares rather than suppresses. A host advertising `nondeterminismPolicy.declared` MUST record every declared source in the run's event log at the point it is read, so a fork replays the recorded value rather than re-drawing it. A source the host neither declares nor suppresses is a replay defect, not a policy choice.
 
-See also: events.md, runs.md, persistence.md, security-defaults.md.
-
-*Sources: RFCs 0036, 0039, 0041, 0057, 0104, 0111, 0140, 0173, 0176, 0194.*
+*Sources: RFCs 0036, 0039, 0041, 0057, 0104, 0111, 0140, 0173, 0176, 0194, 0228.*

package/spec/v2/core/runs.md

@@ -1,7 +1,7 @@
 # Runs
 
 > **Status: Stable.**
-> **Normative home:** `runList`, `limits`, `conversationPrimitive`, `dataResidency`, `deadLetter`.
+> **Normative home:** `runList`, `limits`, `conversationPrimitive`, `dataResidency`, `deadLetter`, `budget`.
 
 ## Why this exists
 
@@ -38,7 +38,7 @@ Every operation accepts `OpenWOP-Version` ([overview.md](overview.md)) and every
 | `getRunCompensation` | `GET /runs/{runId}/compensation` | `runs:read` | `compensation` |
 | `getRunEffects` | `GET /runs/{runId}/effects` | `runs:read` | `idempotency` |
 
-A gated operation the host does not advertise (or an absent `diffRun`) answers `404`; for annotations it is `404 not_found`.
+A gated operation the host does not advertise (or an absent `diffRun`) answers `404 not_found` ([errors.md](errors.md)).
 
 ## Create
 
@@ -67,7 +67,7 @@ The `201` response is `{ runId, status, eventsUrl, statusUrl? }`. `status` is on
 
 ### Refusals
 
-- `mode: eval` makes `evalSuiteRef` and `agentId` REQUIRED. It starts an eval-suite projection that emits the content-free `eval.*` family and terminates with an `EvalSummary`. A host that does not advertise `agents.evalSuite` MUST reject it.
+- `mode: eval` makes `evalSuiteRef` and `agentId` REQUIRED. It starts an eval-suite projection that emits the content-free `eval.*` family and terminates with an `EvalSummary`. A host that does not advertise `agents.evalSuite` MUST reject it `422 capability_not_provided`.
 - A host advertising `dataResidency` MUST reject a `residency.region` outside `dataResidency.regions` with `422 residency_unavailable` and create no run (see §"Conversation and residency capabilities").
 - A workflow that references a capability-gated reserved node type on a host that does not advertise the capability MUST be rejected with `422 capability_required`.
 
@@ -99,9 +99,12 @@ The `201` response is `{ runId, status, eventsUrl, statusUrl? }`. `status` is on
 
 ### Limits
 
-`limits` always carries `clarificationRounds` (per task), `schemaRounds` (per envelope) and `envelopesPerTurn` (per chat turn). A host advertising `maxNodeExecutions`, `maxRunDurationMs` or `maxLoopIterations` MUST enforce it. On any breach the host MUST emit `cap.breached`, with `nodeId` for `clarification` and `schema`, and fail the node or run. Its `observed` exceeds `limit` and MUST be reused on replay and fork, never recomputed.
+`limits` always carries `clarificationRounds` (per task), `schemaRounds` (per envelope) and `envelopesPerTurn` (per chat turn).
 
-`budget.maxTokens` and `budget.maxCostUsd` clamp to `maxBudgetTokens` and `maxBudgetCostUsd`. `maxRequestBodyBytes` is the largest REST request body accepted.
+- A host advertising `maxNodeExecutions`, `maxRunDurationMs` or `maxLoopIterations` MUST enforce it.
+- On any breach the host MUST emit `cap.breached` and fail the node or run. The event carries `nodeId` for a `clarification` or `schema` breach. Its `observed` exceeds `limit` and MUST be reused on replay and fork, never recomputed.
+- `budget.maxTokens` and `budget.maxCostUsd` clamp to `maxBudgetTokens` and `maxBudgetCostUsd`.
+- `maxRequestBodyBytes` is the largest REST request body accepted.
 
 ### `ai` section
 
@@ -114,6 +117,16 @@ The `201` response is `{ runId, status, eventsUrl, statusUrl? }`. `status` is on
 
 `tokenBudget` resolves to `min(tokenBudget, memory.distillation.maxTokenBudget)`. A run that cannot distill within it MUST fail atomically with `token_budget_exceeded`.
 
+### `budget` section
+
+`budget` caps a run's spend. The effective budget is the minimum across the `scopes` that apply (run, workflow, agent, project), clamped per §Limits; only the run scope has a wire surface. Whichever of `budget` and the `run` section binds first fires its own `cap.breached` kind.
+
+- `budget.reserved` records the effective budget, and consumption is derived from `provider.usage`, `agent.toolCalled` and `node.retried`, never measured twice. A replay reuses both.
+- Under either `enforce` mode a host MUST emit `budget.reserved`, `budget.threshold-crossed` and `budget.exhausted`, and MAY coalesce `budget.consumed`.
+- `hard` exhaustion under `onExhaustion: fail` emits `cap.breached` (`kind: budget-*`) and fails the run `budget_exhausted`. Under `interrupt` it raises an approval whose `resumeValue` adds budget, recorded by a second `budget.reserved`. An `advisory` host MUST NOT stop the run.
+- A resolved model outside `modelAllow`, or in `modelDeny` (which wins), is refused `budget_model_denied` before the call.
+- `dimensions` lists only what the host enforces and MAY omit `cost`. The `budget.*` events and `cap.breached` MUST NOT carry rate cards, unit prices, cost breakdowns, credentials or model prose (`budget-no-pricing-leak`); the aggregate cost is allowed.
+
 ### Validation and persistence
 
 - An unknown root key, an unknown key inside a section, or a dotted key (`ai.provider` as a string key) MUST be rejected with `400 validation_error`.
@@ -277,10 +290,10 @@ A host advertising `deadLetter` MUST, when a run or node exhausts its retry poli
 - keep the failed run fork-eligible for `retentionDays`, and not purge it sooner;
 - purge it after `retentionDays`, after which a fork fails as for an unknown run.
 
-This sink holds runs. Queue messages ([host-services.md](host-services.md) §`queueBus`) and webhook deliveries ([webhooks.md](webhooks.md) §Dead letters) have their own.
+Queue messages ([host-services.md](host-services.md) §`queueBus`) and webhook deliveries ([webhooks.md](webhooks.md) §Dead letters) have sinks of their own.
 
 ## During the v1 overlap
 
 A non-terminal run inherited from v1 continues, or is cancelled `v1_pin_unsupported`, per [persistence.md](persistence.md) §"Runs pinned to v1".
 
-*Sources: RFCs 0053, 0058, 0084, 0170, 0171, 0176, 0182.*
+*Sources: RFCs 0053, 0058, 0084, 0170, 0171, 0176, 0182, 0228.*

package/spec/v2/core/security-defaults.md

@@ -140,6 +140,4 @@ A threat model missing a sibling section fails the template gate.
 
 Rows `C6.1`–`C6.9` are `spec/v1/migrations.json` entries.
 
-See also: identity.md, replay.md, webhooks.md, capabilities.md, conformance.md.
-
 *Sources: RFCs 0150, 0163, 0164, 0170, 0173, 0214, 0218, 0224.*

package/spec/v2/core/storage.md

@@ -5,37 +5,35 @@
 
 ## Why this exists
 
-A node pack keeps files, records and indexes in storage services the host provides, reached through `ctx` ([host-services.md](host-services.md)). This document states what a host takes on by advertising one.
+A node pack keeps files, records and indexes in storage services the host provides, reached through `ctx` ([host-services.md](host-services.md)). Each family below is a contract a host takes on by advertising it.
 
 ## Operations
 
-A host advertising a family MUST expose each of its operations to pack code, returning at least the fields shown; it MAY return more. An operation marked † is required only when the named facet is `true`.
+A host advertising a family MUST expose each of its operations to pack code, returning at least the fields shown; it MAY return more. An operation marked † is required only when its facet is `true`: `kvStorage.atomicIncrement`, `kvStorage.compareAndSwap`, `sql.transactions` or `blobStorage.presignSupported`.
 
-| Family | Operations |
-| --- | --- |
-| `fs` (`ctx.fs`) | `read(path) → bytes, contentType?` · `write(path, bytes, contentType?) → path, sizeBytes` · `delete(path) → deleted` · `stat(path) → sizeBytes, modifiedAt, contentType?` · `list(prefix?, cursor?, limit?) → entries[path, sizeBytes], nextCursor?` |
-| `kvStorage` (`ctx.storage.kv`) | `get(key) → value?, expiresAt?` · `put(key, value, ttlSeconds?) → ok` · `delete(key) → deleted` · `list(prefix?, cursor?, limit?) → entries[key], nextCursor?` · † `atomicIncrement(key, delta?) → value` · † `compareAndSwap(key, expectedValue, newValue) → swapped` |
-| `tableStorage` (`ctx.storage.table`) | `createTable(name, schema) → ok` · `insert(table, row) → rowId` · `get(table, rowId) → row?` · `query(table, filter?, cursor?, limit?) → rows, nextCursor?` · `update(table, rowId, patch) → ok` · `delete(table, rowId) → deleted` |
-| `sql` (`ctx.db.sql`) | `query(datasourceId, sql, params) → rows, rowCount` · `execute(datasourceId, sql, params) → rowsAffected` · † `transaction(datasourceId, operations[sql, params]) → committed` |
-| `nosql` (`ctx.db.nosql`) | `insert(datasourceId, collection, doc) → id` · `get(…, id) → doc?` · `query(…, filter, cursor?, limit?) → docs, nextCursor?` · `update(…, id, patch) → ok` · `delete(…, id) → deleted` |
-| `vectorStore` (`ctx.db.vector`) | `upsert(collection, vectors[id, embedding, metadata?]) → upserted` · `query(collection, embedding, k, filter?) → matches[id, score, metadata?]` · `delete(collection, ids) → deleted` |
-| `searchIndex` (`ctx.db.search`) | `index(index, docs[id, fields]) → indexed` · `query(index, q, k?, filter?) → hits[id, score, fields?]` · `delete(index, ids) → deleted` |
-| `blobStorage` (`ctx.storage.blob`) | `put(bucket, key, bytes, contentType?) → url, sizeBytes` · `get(bucket, key) → bytes, contentType?` · `delete(bucket, key) → deleted` · `list(bucket, prefix?, cursor?) → entries[key, sizeBytes], nextCursor?` · † `presign(bucket, key, expiresInSeconds, method) → url, expiresAt` |
-| `cache` (`ctx.storage.cache`) | `get(key) → value?, expiresAt?` · `put(key, value, ttlSeconds) → ok` · `delete(key) → deleted` |
+- **`fs`** (`ctx.fs`): `read(path) → bytes, contentType?` · `write(path, bytes, contentType?) → path, sizeBytes` · `delete(path) → deleted` · `stat(path) → sizeBytes, modifiedAt, contentType?` · `list(prefix?, cursor?, limit?) → entries[path, sizeBytes], nextCursor?`
+- **`kvStorage`** (`ctx.storage.kv`): `get(key) → value?, expiresAt?` · `put(key, value, ttlSeconds?) → ok` · `delete(key) → deleted` · `list(prefix?, cursor?, limit?) → entries[key], nextCursor?` · † `atomicIncrement(key, delta?) → value` · † `compareAndSwap(key, expectedValue, newValue) → swapped`
+- **`tableStorage`** (`ctx.storage.table`): `createTable(name, schema) → ok` · `insert(table, row) → rowId` · `get(table, rowId) → row?` · `query(table, filter?, cursor?, limit?) → rows, nextCursor?` · `update(table, rowId, patch) → ok` · `delete(table, rowId) → deleted`
+- **`sql`** (`ctx.db.sql`): `query(datasourceId, sql, params) → rows, rowCount` · `execute(datasourceId, sql, params) → rowsAffected` · † `transaction(datasourceId, operations[sql, params]) → committed`
+- **`nosql`** (`ctx.db.nosql`): `insert(datasourceId, collection, doc) → id` · `get(…, id) → doc?` · `query(…, filter, cursor?, limit?) → docs, nextCursor?` · `update(…, id, patch) → ok` · `delete(…, id) → deleted`
+- **`vectorStore`** (`ctx.db.vector`): `upsert(collection, vectors[id, embedding, metadata?]) → upserted` · `query(collection, embedding, k, filter?) → matches[id, score, metadata?]` · `delete(collection, ids) → deleted`
+- **`searchIndex`** (`ctx.db.search`): `index(index, docs[id, fields]) → indexed` · `query(index, q, k?, filter?) → hits[id, score, fields?]` · `delete(index, ids) → deleted`
+- **`blobStorage`** (`ctx.storage.blob`): `put(bucket, key, bytes, contentType?) → url, sizeBytes` · `get(bucket, key) → bytes, contentType?` · `delete(bucket, key) → deleted` · `list(bucket, prefix?, cursor?) → entries[key, sizeBytes], nextCursor?` · † `presign(bucket, key, expiresInSeconds, method) → url, expiresAt`
+- **`cache`** (`ctx.storage.cache`): `get(key) → value?, expiresAt?` · `put(key, value, ttlSeconds) → ok` · `delete(key) → deleted`
 
-The facets are `kvStorage.atomicIncrement` and `kvStorage.compareAndSwap`, `sql.transactions`, and `blobStorage.presignSupported`. `presign` takes `method` `GET` or `PUT`, and `…` in a `nosql` row repeats `datasourceId, collection`.
+`presign` takes `method` `GET` or `PUT`, and `…` in a `nosql` operation repeats `datasourceId, collection`.
 
 ## Shared rules
 
 - **Tenant isolation.** A read for one tenant MUST NOT return data another tenant wrote, even under an identical key or name: `kvStorage` `get` and `list`, `tableStorage` `get` and `query`, `vectorStore` and `searchIndex` `query`, `blobStorage` and `cache` `get`.
-- **Datasources.** `sql` and `nosql` datasources are scoped per tenant, and access to another tenant's datasource MUST be refused.
+- **Datasources.** `sql` and `nosql` datasources are scoped per tenant; access to another tenant's datasource MUST be refused.
 - **Backend-invariant.** The operation shapes of `sql` and `nosql` MUST NOT vary with the advertised `drivers`, nor those of `vectorStore` and `searchIndex` with the advertised `backends`. A host MAY back `sql` with any driver it advertises.
 - **Size limits.** A key over `kvStorage.maxKeyBytes`, and a write over `fs.maxFileSizeBytes`, `kvStorage.maxValueBytes`, `blobStorage.maxObjectBytes` or `cache.maxValueBytes`, MUST be refused. A `tableStorage` insert MUST be refused once `maxRowsPerTable` is reached.
 - **Expiry.** `kvStorage` and `cache` MUST honour an entry's expiry, as a read sees it, with at most one second of drift. `maxTtlSeconds` caps `ttlSeconds` for each.
 
-What a family advertises also names its targets: `sql.datasources`, `nosql.datasources`, `vectorStore.collections`, `searchIndex.indexes` and `blobStorage.buckets`. `tableStorage` advertises `maxColumnsPerRow`, `indexable` and `fullTextSearch` as limits and features, with no further rule.
+A family's advertisement also names its targets: `sql.datasources`, `nosql.datasources`, `vectorStore.collections`, `searchIndex.indexes` and `blobStorage.buckets`. `tableStorage` advertises `maxColumnsPerRow`, `indexable` and `fullTextSearch` as limits and features, with no further rule.
 
-No error code specific to these families is registered; [errors.md](errors.md) governs the code a refused call carries.
+A refused call carries `not_found`, `forbidden`, `validation_error`, or `storage_limit_exceeded` for a limit or quota ([errors.md](errors.md) §Host-service refusals). A sandbox escape is `forbidden` with `details.reason: path-outside-sandbox`.
 
 ## `fs`
 
@@ -57,8 +55,8 @@ No error code specific to these families is registered; [errors.md](errors.md) g
 
 ## `sql` and `nosql`
 
-- `sql` MUST be treated as a parametric template: bound values MUST flow through `params`, never through string interpolation. A host SHOULD verify parameter binding before execution, and a pack MUST NOT concatenate user input into `sql`.
-- When `sql.transactions` is `true`, a partial failure inside `transaction` MUST roll back the whole batch.
+- `sql` MUST be treated as a parametric template: bound values MUST flow through `params`, never through string interpolation. A pack MUST NOT concatenate user input into `sql`, and a host SHOULD verify parameter binding before execution.
+- When `sql.transactions` is `true`, a partial failure inside `transaction` MUST roll back the whole batch, which resolves `committed: false`.
 - `nosql` filter operators MUST NOT permit injection. Server-side script evaluation, such as MongoDB `$where`, MUST be refused unless an explicit allowlist is configured.
 
 ## `vectorStore` and `searchIndex`
@@ -70,4 +68,4 @@ No error code specific to these families is registered; [errors.md](errors.md) g
 
 Presigned URLs MUST expire at the advertised TTL. A presigned request after expiry MUST fail at the storage layer, not after an authorization skip.
 
-*Sources: RFCs 0014, 0015, 0016, 0018, 0019.*
+*Sources: RFCs 0014, 0015, 0016, 0018, 0019, 0228.*

package/spec/v2/core/versioning.md

@@ -13,11 +13,11 @@ How a v2 host selects a major, what each version axis means, and what a release
 A v2 host MUST advertise two root fields, both REQUIRED in `schemas/v2/capabilities.schema.json` ([capabilities.md](capabilities.md)):
 
 - `protocolVersions[]` — every `<major>.<minor>` it serves, each matching `^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$`. Through the overlap that is `["1.<n>", "2.<m>"]`; after v1 end-of-support, `["2.<m>"]`.
-- `preferredVersion` — MUST be a member of `protocolVersions[]`. Through the overlap it MUST name a 1.x member, because a header-less request is a v1 client's ([capabilities.md](capabilities.md) §1; §1.3). On a host serving a single major, it MUST equal `protocolVersion`.
+- `preferredVersion` — MUST be a member of `protocolVersions[]`. Through the overlap it MUST name a 1.x member ([capabilities.md](capabilities.md) §1; §1.3). On a host serving a single major, it MUST equal `protocolVersion`.
 
 A host that drops v1 advertises a `2.x` `preferredVersion`; its header-less representation becomes the closed v2 root.
 
-A v2 consumer reads `preferredVersion` as the header-less default. When it is absent on a v1 document, the default is `max(protocolVersions[])`, else `protocolVersion`. The suite's `--target-major` defaults from it.
+A v2 consumer reads `preferredVersion` as the header-less default. When it is absent on a v1 document, the default is `max(protocolVersions[])`, else `protocolVersion`.
 
 ### 1.2 Paths
 
@@ -47,8 +47,6 @@ A request on an unversioned path MAY carry `OpenWOP-Version: <major>` or `OpenWO
 | Header absent on any other unversioned path | MUST serve major 2: the path is the v2 surface (§1.2) |
 | `/v1/…` path with `OpenWOP-Version` other than `1` | MUST answer `400` `protocol_version_mismatch` |
 
-`/.well-known/openwop` is the one resource both majors serve at the same unversioned path, so it is the only place a header-less request can come from a client of the earlier major.
-
 A request on a `/v1/…` path key MUST NOT carry `OpenWOP-Version` with a value other than `1`. `protocol_version_unsupported`, `protocol_version_mismatch` and `client_version_unsupported` (§1.5) are rows in `spec/v2/errors.json` ([errors.md](errors.md)).
 
 ### 1.4 The response header
@@ -131,7 +129,6 @@ Dispositions:
 
 - One grammar covers protocol, envelope-kind and pack axes wherever a version is `<major>.<minor>` (#1, #2, #11, #15).
 - `typeId@<semver>` is a pack axis (`packs.md`); the `2` in `typeId@2.0.0` never means `OpenWOP-Version: 2`.
-- `docs/PROTOCOL-STATUS.md` carries one row per axis.
 
 ### 2.1 `engineVersion` (axis 3)
 
@@ -141,7 +138,7 @@ Dispositions:
 
 ### 2.2 `eventLogSchemaVersion` (axis 4)
 
-`eventLogSchemaVersion` is the era key; the schema floor is `minimum 2`. Its stamping, absent-⇒-`2` and discovery rules are `persistence.md` §"The era key"; the reader contract is `persistence.md`.
+`eventLogSchemaVersion` is the era key; the schema floor is `minimum 2`. Its stamping, absent-⇒-`2`, discovery and reader rules are in [persistence.md](persistence.md) §"The era key".
 
 ## 3. Where v2 lives
 
@@ -168,15 +165,13 @@ Through the overlap a host:
 - MUST emit `OpenWOP-Version` on every response (§1.4);
 - MUST serve `/.well-known/openwop` as one resource whose representation the request header selects ([capabilities.md](capabilities.md)).
 
-The dual-stack scenario creates one run through `/v1/runs` with no header and reads it through `/runs` with `OpenWOP-Version: 2`; the response headers name the contract used.
-
 A run minted under major 1 and read under major 2 MUST use the tenant-bound projection `<tenantId>/<v1-id>` ([identity.md](identity.md) §5). A host MUST NOT return a bare v1 id in a major-2 response.
 
 ### Retirement
 
 The overlap ends at v1 end-of-support ([overview.md](overview.md)): `protocolVersions[]` drops the `1.<n>` member, and every alias carrying the `v1-end-of-support` trigger is removed.
 
-- **Retirement is atomic.** §1.1 admits no state in which both majors are advertised and `2.x` is preferred, so dropping v1 retires the whole `/v1` path space at once.
+- **Retirement is atomic.** Dropping v1 retires the whole `/v1` path space at once (§1.1).
 - **Retirement changes every header-less request's default contract**, from major 1 to major 2. Before retirement, a host MUST check for collisions between manifest top-level path segments and non-protocol unversioned routes, and MUST move each colliding route or apply §1.4 content negotiation.
 
 ### Host-proprietary paths: `/host/<org>/…`