@openwop/spec-artifacts 2.42.6 → 2.42.7

package/spec/v2/core/conformance.md

@@ -1,27 +1,29 @@
 # Conformance
 
-> **Status: Stable · RFC 0168.**
+> **Status: Stable.**
 
 ## Why this exists
 
-The v2 evidence contract: how a requirement is asserted, how every requirement declares what can witness it, how the seams are mounted, what the suite ships, and what a bundle proves. Profiles are in overview.md; the capability vocabulary the suite gates on is capabilities.md.
+The v2 evidence contract: how a requirement is asserted, how every requirement declares what can witness it, how the seams are mounted, what the suite ships, and what a bundle proves. Profiles are in [overview.md](overview.md); the capability vocabulary the suite gates on is in [capabilities.md](capabilities.md).
 
 ## Requirement ids
 
-`expect(x, req('openwop.<area>.<slug>', '<doc> §<section>', '<requirement>'))` is the only assertion form. A scenario assertion without a requirement id MUST fail the suite's lint. Ids are minted in `conformance/requirements.json`; every test declares its id explicitly. A title reword without a corresponding `requirement-aliases.json` row MUST fail CI.
+`expect(x, req('openwop.<area>.<slug>', '<doc> §<section>', '<requirement>'))` is the only assertion form. Ids are minted in `conformance/requirements.json`, and every test declares its id explicitly.
 
-The ledger records per `it`, and a bundle's `results.requirements[]` is the per-assertion list. A post-assertion soft-skip MUST record `skipped` for every id not reached and MUST NOT record `pass`.
+- A scenario assertion without a requirement id MUST fail the suite's lint.
+- A title reword without a corresponding `requirement-aliases.json` row MUST fail CI.
+
+The ledger records per `it`; a bundle's `results.requirements[]` is the per-assertion list. A post-assertion soft-skip MUST record `skipped` for every id not reached and MUST NOT record `pass`.
 
 ### Whose fact is the reason?
 
-A soft-skip carries a disposition and a reason. The reason MUST identify a fact
-about the host under test. Use `inapplicable` only when the requirement does not
-bind that host. A missing fixture, unreadable corpus file, or other suite-side
-failure MUST be `blocked`, never `inapplicable`; a suite with a blocked row MUST
-NOT issue a certification (RFC 0168 §E.1).
+A soft-skip carries a disposition and a reason. The reason MUST identify a fact about the host under test.
+
+- Use `inapplicable` only when the requirement does not bind that host.
+- A missing fixture, unreadable corpus file, or other suite-side failure MUST be `blocked`, never `inapplicable`.
+- A suite with a blocked row MUST NOT issue a certification.
 
-When more than one gate can skip a test, evaluate host predicates before suite
-predicates.
+When more than one gate can skip a test, evaluate host predicates before suite predicates.
 
 ## Witness class
 
@@ -36,19 +38,27 @@ Every family in `spec/v2/declaration.json`, every requirement in `conformance/re
 | `negative-existence` | the suite asserts a thing is absent |
 | `unwitnessable` | no observation path exists; `rationale` REQUIRED |
 
-A protocol-tier invariant marked `unwitnessable` MUST fail the corpus gate. `tests: []` is expressible only as `unwitnessable`. A bundle disposition `blocked` does not exist as a witness class: what v1 called blocked is `seam-gated` or `unwitnessable`.
-
-A MUST whose only witness is `seam-gated` MUST either mint a normative observation path before the cut or be demoted to SHOULD. The seam count in `docs/witness-baseline.json` is a ratchet and MUST NOT rise.
+- A protocol-tier invariant marked `unwitnessable` MUST fail the corpus gate.
+- `tests: []` is expressible only as `unwitnessable`.
+- `blocked` is a bundle disposition, not a witness class.
+- A MUST whose only witness is `seam-gated` MUST either mint a normative observation path before the cut or be demoted to SHOULD.
+- The seam count in `docs/witness-baseline.json` is a ratchet and MUST NOT rise.
 
 ## The seams profile
 
-Test seams are the profile `openwop-conformance-seams-v2` (`spec/v2/profiles.json`), described by `api/seams-v2.yaml` with schemas under `schemas/v2/seams/`, in the path space `/conformance/seams/…`. The seam schemas `$ref` the canonical error and event schemas with no tolerance path. A host that mounts the seams MUST advertise the profile as `conformance.seamsProfile: "openwop-conformance-seams-v2"` at the discovery root (RFC 0168 §C.1, erratum 2026-09-05; the closed root has no `profiles[]`, capabilities.md §3); a `testSeams` capability flag does not exist and MUST NOT be advertised. `api/v2/openapi.yaml` and `spec/v2/path-manifest.json` MUST contain no seam or sample-host operation; an SDK generated from the canonical document has no seam method. The profile is versioned with the suite (`seams-v2` for 2.x).
+Test seams are the profile `openwop-conformance-seams-v2` (`spec/v2/profiles.json`), described by `api/seams-v2.yaml` with schemas under `schemas/v2/seams/`, in the path space `/conformance/seams/…`. The seam schemas `$ref` the canonical error and event schemas with no tolerance path. The profile is versioned with the suite (`seams-v2` for 2.x).
+
+- A host that mounts the seams MUST advertise the profile as `conformance.seamsProfile: "openwop-conformance-seams-v2"` at the discovery root (the closed root has no `profiles[]`; [capabilities.md](capabilities.md) §3).
+- A host MUST NOT advertise a `testSeams` capability flag.
+- `api/v2/openapi.yaml` and `spec/v2/path-manifest.json` MUST contain no seam or sample-host operation; an SDK generated from the canonical document has no seam method.
 
 ## Two products, two ledgers
 
 Corpus-coherence checks run in the spec repo's CI (`scripts/check-spec-coherence.mjs`) and MUST NOT appear in a host bundle; the bundle schema forbids their ids. `--offline` is a declared property of a scenario, not a runtime discovery.
 
-`@openwop/openwop-conformance@2.0.0` ships `dist`, `fixtures`, and `vectors` only. The corpus — `api/`, `schemas/`, the `spec/v2/*.json` registries, `CORPUS-STAMP.json` — is `@openwop/spec-artifacts@2.0.0`, an exact-pinned peer dependency the suite MUST digest-check at start and MUST refuse to run against on a mismatch. The suite is one package: `--target-major 1|2` selects the target (default: the host's `preferredVersion`), scenario ids share one namespace across majors, and the 1.x target is removed at v1 end-of-support.
+- `@openwop/openwop-conformance@2.0.0` ships `dist`, `fixtures` and `vectors` only.
+- The corpus — `api/`, `schemas/`, the `spec/v2/*.json` registries, `CORPUS-STAMP.json` — is `@openwop/spec-artifacts@2.0.0`, an exact-pinned peer dependency. The suite MUST digest-check it at start and MUST refuse to run against it on a mismatch.
+- The suite is one package: `--target-major 1|2` selects the target (default: the host's `preferredVersion`), and scenario ids share one namespace across majors. The 1.x target is removed at v1 end-of-support.
 
 ## Bundle v3
 
@@ -57,7 +67,7 @@ A certification bundle validates against `schemas/v2/certification-bundle.schema
 | Field | Rule |
 | --- | --- |
 | `suite` | `name`, `version`, `targetMajor`, `specArtifactsVersion` REQUIRED |
-| `host` | `name`, `version`, `build.{kind, id}` REQUIRED; `kind` is `image-digest`, `commit`, or `artifact-sha256` |
+| `host` | `name`, `version`, `build.{kind, id}` REQUIRED; `kind` is `image-digest`, `commit` or `artifact-sha256` |
 | `host.deployment` | OPTIONAL; `colocated-companion` only (below). Absent: the bundle measures the served host |
 | `discovery` | `url`, `sha256`, `protocolVersions`, `preferredVersion` REQUIRED |
 | `claimedProfiles[]` | `id`, `evidenceTier` (`self` \| `steward` \| `independent`), `witnessCount`, `certified` REQUIRED |
@@ -69,29 +79,70 @@ A certification bundle validates against `schemas/v2/certification-bundle.schema
 | `durability.rung` | OPTIONAL; a claim the verifier re-derives (below) |
 | `signature` | REQUIRED |
 
-`signature` is an Ed25519 attestation over the JCS bytes (§"Canonical JSON") of `{ witnessSha256, host.build, suite.version, discovery.sha256 }`; `over` MUST list exactly those four members. A host that signs bundles MUST publish the corresponding public keys as `signingKeys[]` in its discovery document, and `signature.keyId` MUST name one of them. A verifier MUST resolve `keyId` there — in the discovery document of the host the bundle is *about* — and MUST verify the attestation under the published key.
+### Signature and attribution
+
+`signature` is an Ed25519 attestation over the JCS bytes (§"Canonical JSON") of `{ witnessSha256, host.build, suite.version, discovery.sha256 }`; `over` MUST list exactly those four members.
+
+- A host that signs bundles MUST publish the corresponding public keys as `signingKeys[]` in its discovery document, and `signature.keyId` MUST name one of them.
+- A verifier MUST resolve `keyId` there — in the discovery document of the host the bundle is *about* — and MUST verify the attestation under the published key.
+- A retired key MUST stay listed.
+
+A signature that cannot be resolved to a published key attests **integrity only**, and the bundle MUST NOT be read as attributable evidence. A gate MUST distinguish three outcomes that a presence check collapses into one: *no discovery document was read*, *read and the key is not published*, and *the attestation does not verify*.
+
+`evidenceTier: independent` MUST carry a `verifierKeyId` distinct from the host's signing key. The verifier MUST refuse, not warn, on a missing or self-signed independent claim.
+
+### Certification
 
-A signature that cannot be resolved to a published key attests **integrity only**. Such a bundle MUST NOT be read as attributable evidence, and a gate MUST distinguish three outcomes that a presence check collapses into one — *no discovery document was read*, *read and the key is not published*, and *the attestation does not verify*. A retired key MUST stay listed. `evidenceTier: independent` MUST carry a `verifierKeyId` distinct from the host's signing key; the verifier MUST refuse, not warn, on a missing or self-signed independent claim. A bundle with `totals.blocked > 0` does not certify. At major 2 a requirement a test did not observe records `blocked` even when the test asserted setup facts first; an `executed-pass` carrying a `partial-witness:` detail is reserved for a leg that observed its requirement and skipped an optional extra. A verifier MUST derive the operator's opt-outs from the signed `skipped` rows and MUST reject a bundle whose captured discovery document advertises one of them (`opted-out-but-advertised`). v1 and v2 bundles are never upgraded to v3; a bundle is evidence at its own version.
+- A bundle with `totals.blocked > 0` does not certify.
+- At major 2 a requirement a test did not observe records `blocked`, even when the test asserted setup facts first.
+- An `executed-pass` carrying a `partial-witness:` detail is reserved for a leg that observed its requirement and skipped an optional extra.
+- A verifier MUST derive the operator's opt-outs from the signed `skipped` rows and MUST reject a bundle whose captured discovery document advertises one of them (`opted-out-but-advertised`).
+- v1 and v2 bundles are never upgraded to v3; a bundle is evidence at its own version.
 
-A bundle cut from a *colocated companion* — the served host's image, run beside the suite so it can trust a suite-held trust anchor — MUST carry `host.deployment: "colocated-companion"`, which the preimage covers (§"Canonical JSON"). A host serving production traffic MUST NOT list a suite-held trust anchor among the trust roots it advertises. A companion is evidence only for the requirements in `spec/v2/harness-trust-anchors.json`, and only when it pairs with a certified served-host bundle of the same `image-digest` build, signed under a key that bundle's discovery publishes, whose discovery document is equal once each document's origin and the `oidc` lane's `issuers` are set aside (RFC 0216).
+### Colocated companion
+
+A *colocated companion* is the served host's image run beside the suite, so it can trust a suite-held trust anchor.
+
+- A bundle cut from one MUST carry `host.deployment: "colocated-companion"`, which the preimage covers (§"Canonical JSON").
+- A host serving production traffic MUST NOT list a suite-held trust anchor among the trust roots it advertises.
+- A companion is evidence only for the requirements in `spec/v2/harness-trust-anchors.json`, and only when it pairs with a certified served-host bundle of the same `image-digest` build, signed under a key that bundle's discovery publishes, whose discovery document is equal once each document's origin and the `oidc` lane's `issuers` are set aside.
 
 ### Canonical JSON
 
-Every signature and digest in this corpus is over the RFC 8785 (JCS) serialization, UTF-8 encoded (RFC 0212). The value MUST be I-JSON (RFC 7493): a signer or hasher MUST refuse, not coerce, a value with duplicate member names, a lone surrogate, a non-finite number, an integer literal whose magnitude exceeds 2^53 − 1, or a non-JSON value, and a verifier that meets one in a document it must re-canonicalize MUST fail verification. `conformance/vectors/jcs-v1.json` is normative.
+Every signature and digest in this corpus is over the RFC 8785 (JCS) serialization, UTF-8 encoded. `conformance/vectors/jcs-v1.json` is normative.
+
+The value MUST be I-JSON (RFC 7493):
+
+- A signer or hasher MUST refuse, not coerce, a value with duplicate member names, a lone surrogate, a non-finite number, an integer literal whose magnitude exceeds 2^53 − 1, or a non-JSON value.
+- A verifier that meets one in a document it must re-canonicalize MUST fail verification.
+
+`witnessSha256` is SHA-256 over the JCS bytes of the rows:
 
-`witnessSha256` is SHA-256 over the JCS bytes of the rows — one object per `results.requirements[]` entry with exactly `id`, `scenario`, `result` and, each only when present, `assertions`, `detail`, `evidence`, sorted by `id` in UTF-16 code-unit order — or, only when `host.relaxations[]` is non-empty or `host.deployment` is present, of `{ "rows": …, "relaxations": …, "deployment": … }` carrying each of the last two only when so, with relaxations in the order carried. A locale-sensitive comparator MUST NOT be used. `discovery.sha256` is SHA-256 over the JCS bytes of the captured document.
+- One object per `results.requirements[]` entry, with exactly `id`, `scenario`, `result` and, each only when present, `assertions`, `detail`, `evidence`.
+- Rows sorted by `id` in UTF-16 code-unit order. A locale-sensitive comparator MUST NOT be used.
+- Only when `host.relaxations[]` is non-empty or `host.deployment` is present, the preimage is instead `{ "rows": …, "relaxations": …, "deployment": … }`, carrying each of the last two only when so, with relaxations in the order carried.
+
+`discovery.sha256` is SHA-256 over the JCS bytes of the captured document.
 
 ### Recovery evidence
 
-Recovery evidence (RFC 0158 §E) rides on rows, which `witnessSha256` digests: a row's `evidence` enters the digest only when present, and a bundle without it digests as it always did.
+Recovery evidence rides on rows: a row's `evidence` enters `witnessSha256` only when present.
 
 | Row | `evidence` member |
 | --- | --- |
-| `0158.bound-is-derived` | `recoveryBounds[]` of `{ class, bound, terms[] }`, each term `{ name, ms }`; `bound` MUST equal the sum of its terms. One entry per recovery class; there is no aggregate bound. |
-| `0158.kill-after-accept`, `0158.kill-during-execution` | `recovery: { class, boundMs, observedMs }` — the class exercised, the bound it was judged against, and the observed kill-to-resumption interval. |
+| `0158.bound-is-derived` | `recoveryBounds[]` of `{ class, bound, terms[] }`, each term `{ name, ms }` |
+| `0158.kill-after-accept`, `0158.kill-during-execution` | `recovery: { class, boundMs, observedMs }` |
+
+- In `recoveryBounds[]`, `bound` MUST equal the sum of its terms. There is one entry per recovery class and no aggregate bound.
+- In `recovery`, `class` is the class exercised, `boundMs` the bound applied, `observedMs` the kill-to-resumption interval.
+- `class` and `name` are opaque host-chosen identifiers, never a closed vocabulary.
 
-`class` and `name` are opaque host-chosen identifiers, never a closed vocabulary. `durability.rung` is outside the attestation, so a verifier MUST re-derive it and MUST reject (`rung-not-derivable`) a claim it cannot derive: every row of the rung `executed-pass`, each kill row's `class` naming a declared entry whose `bound` equals its `boundMs` and is not exceeded by its `observedMs`. Only `durable-single-instance` is derivable in this revision; a higher claim is refused. This proves arithmetic and that recovery ran once inside the bound. It does not prove the kill landed in the class it names; killing only once the execution claim is held is the host's obligation.
+`durability.rung` is outside the attestation, so a verifier MUST re-derive it and MUST reject (`rung-not-derivable`) a claim it cannot derive. Derivation requires every row of the rung to be `executed-pass`, and each kill row's `class` to name a declared entry whose `bound` equals its `boundMs` and is not exceeded by its `observedMs`. Only `durable-single-instance` is derivable in this revision; a higher claim is refused.
+
+This proves the arithmetic and that recovery ran once inside the bound. It does not prove the kill landed in the class it names; killing only once the execution claim is held is the host's obligation.
 
 ## Corpus-gate evidence
 
-An RFC whose acceptance criteria are corpus gates rather than host scenarios records the evidence label **corpus gate — no host tier** in its `Updated` line; the accepted-predicate check reads `(corpus)` rows from `evidence/corpus-ledger.json` for such an RFC and MUST NOT require a host bundle for it.
+An RFC whose acceptance criteria are corpus gates rather than host scenarios records the evidence label **corpus gate — no host tier** in its `Updated` line. For such an RFC the accepted-predicate check reads `(corpus)` rows from `evidence/corpus-ledger.json` and MUST NOT require a host bundle.
+
+*Sources: RFC 0158, RFC 0168, RFC 0212, RFC 0216.*

package/spec/v2/core/connection-packs.md

@@ -1,11 +1,11 @@
 # Connection Packs
 
-> **Status: Stable · RFC 0177, RFC 0095.**
+> **Status: Stable.**
 > **Normative home:** `connections`.
 
 ## Why this exists
 
-A connection pack is a signed provider definition — the endpoints, scope catalog, and reach a connector's `auth.provider` string resolves against. The manifest is `schemas/v2/connection-pack-manifest.schema.json`; installation and signing follow packs.md.
+A connection pack is a signed provider definition — the endpoints, scope catalog, and reach a connector's `auth.provider` string resolves against. The manifest is `schemas/v2/connection-pack-manifest.schema.json`; installation and signing follow [packs.md](packs.md).
 
 ## Provider identity
 
@@ -26,8 +26,13 @@ A connector MAY name a provider by its qualified form `<packName>#<id>`. A quali
 
 ## Resolution
 
-A host advertising `connections.packsSupported` MUST resolve a connector's `auth: { type: "oauth2", provider: P }` (and any `host.oauth` invocation for `P`) against the definition selected above to obtain its endpoints and scope catalog. An unresolvable provider MUST be refused when the dependent connector or pack is registered. On a publish-path host, resolution MUST run after the idempotency short-circuit: a byte-identical re-publish of an installed pack MUST succeed even when resolution inputs have since changed.
+A host advertising `connections.packsSupported` MUST resolve a connector's `auth: { type: "oauth2", provider: P }` (and any `host.oauth` invocation for `P`) against the definition selected above, to obtain its endpoints and scope catalog.
+
+- An unresolvable provider MUST be refused when the dependent connector or pack is registered.
+- On a publish-path host, resolution MUST run after the idempotency short-circuit: a byte-identical re-publish of an installed pack MUST succeed even when resolution inputs have since changed.
 
 ## Errors
 
 Both codes are in `spec/v2/errors.json`: `connection_provider_conflict` (two claimants for one bare id) and `connection_provider_unresolved` (no definition for the referenced id).
+
+*Sources: RFC 0095, RFC 0177.*

package/spec/v2/core/conversation.md

@@ -1,15 +1,19 @@
 # Conversation surfaces
 
-> **Status: Stable · v2.0 · RFC 0101, 0109, 0110.** Normative contract for the multi-party conversation families.
+> **Status: Stable.**
 > **Normative home:** `multiPartyConversation`, `channelPresence`, `conversationTurnModelProvenance`.
 
 ## Why this exists
 
-RFC 0101 and RFC 0110 mint no client route for opening a conversation; the obligation an advertising host takes on is stated here.
+No client route opens a conversation. This document states the obligations a host takes on by advertising a multi-party conversation family.
 
 ## `multiPartyConversation`
 
-A host advertising `multiPartyConversation` MUST accept an optional `participants` array of agent references on conversation creation, and MUST refuse a turn from a principal absent from that roster rather than silently accepting it. It MUST refuse a roster that exceeds `multiPartyConversation.maxParticipants` at creation rather than truncating it.
+A host advertising `multiPartyConversation`:
+
+- MUST accept an optional `participants` array of agent references on conversation creation;
+- MUST refuse a turn from a principal absent from that roster, rather than silently accepting it;
+- MUST refuse, at creation, a roster that exceeds `multiPartyConversation.maxParticipants`, rather than truncating it.
 
 ## `channelPresence`
 
@@ -17,4 +21,6 @@ A host advertising `channelPresence` MUST report present members as a subset of
 
 ## `conversationTurnModelProvenance`
 
-A host that stamps model provenance on an agent turn MUST advertise `conversationTurnModelProvenance`. The stamp is non-secret and non-PII — provider and model identifiers only — and a host MUST NOT place prompt or completion content in it.
+A host that stamps model provenance on an agent turn MUST advertise `conversationTurnModelProvenance`. The stamp is non-secret and non-PII (provider and model identifiers only), and a host MUST NOT place prompt or completion content in it.
+
+*Sources: RFC 0101, RFC 0109, RFC 0110.*

package/spec/v2/core/errors.md

@@ -1,30 +1,49 @@
 # Errors
 
-> **Status: Stable · RFC 0171 §B.**
+> **Status: Stable.**
 
 ## Why this exists
 
-Every error a v2 host returns is a row in one registry. A client routes on `error`, never on `message`, and a code that is not registered is not a protocol error. The registry is the single source for the envelope schema, the HTTP status, and retriability.
+Every error a v2 host returns is a row in one registry. A client routes on `error`, never on `message`. A code that is not registered is not a protocol error. The registry is the single source for the envelope schema, the HTTP status and retriability.
 
 ## The registry
 
-`spec/v2/errors.json` holds one row per code: `{ code, httpStatus, retriable, details, since, deprecated? }` plus the provenance fields `statusSource` and `source`. It registers **107** codes. `schemas/v2/error-envelope.schema.json` is GENERATED from it and MUST NOT be edited by hand.
+`spec/v2/errors.json` holds one row per code: `{ code, httpStatus, retriable, details, since, deprecated? }` plus the provenance fields `statusSource` and `source`, and an optional one-line `meaning`. `spec/v2/errors.schema.json` defines the row. It registers **107** codes. `schemas/v2/error-envelope.schema.json` is GENERATED from it and MUST NOT be edited by hand.
 
-A host MUST return a registered code, or a vendor code, in every error response. A vendor code MUST match `^(?!openwop\.)[a-z][a-z0-9]*(-[a-z0-9]+)*\.[a-z][a-z0-9_]*$` with its first segment an org registered in `spec/v2/declaration.json`; `openwop.` is reserved. The registry grows by overview.md §0.
+- A host MUST return a registered code, or a vendor code, in every error response.
+- A vendor code MUST match `^(?!openwop\.)[a-z][a-z0-9]*(-[a-z0-9]+)*\.[a-z][a-z0-9_]*$`, with its first segment an org registered in `spec/v2/declaration.json`. `openwop.` is reserved.
+- The registry grows by [overview.md](overview.md) §0.
 
 ## The envelope
 
-Every error response body MUST be `{ error, message, details? }` and nothing else (`additionalProperties: false`). `error` is the registered code or a vendor code; `message` is a non-empty string; `details` is an object whose shape is the row's `details` schema. A row whose `details` is `null` accepts any object; when a row registers a schema, the generated envelope becomes a `oneOf` discriminated on `error`. Contextual data (conflict refs, trace ids, validation paths) MUST live under `details`, never at a new top level. The same envelope is the per-id `error` of `bulkCancelRuns` (runs.md). When present, `details.correlationId` MUST be a non-empty string.
+Every error response body MUST be `{ error, message, details? }` and nothing else (`additionalProperties: false`).
 
-`x-openwop-http-status` and `x-openwop-retriable` in the generated schema mirror the registry; a host MUST answer with the registered status.
+- `error` is the registered code or a vendor code. `message` is a non-empty string.
+- `details` is an object shaped by the row's `details` schema. A row whose `details` is `null` accepts any object. When a row registers a schema, the generated envelope becomes a `oneOf` discriminated on `error`.
+- Contextual data (conflict refs, trace ids, validation paths) MUST live under `details`, never at a new top level.
+- When present, `details.correlationId` MUST be a non-empty string.
+
+The same envelope is the per-id `error` of `bulkCancelRuns` ([runs.md](runs.md)). `x-openwop-http-status` and `x-openwop-retriable` in the generated schema mirror the registry; a host MUST answer with the registered status.
 
 ## Retry timing
 
-Retry timing lives in the `Retry-After` header only. `details.retryAfter`, `details.retryAfterMs` and `details.retryAfterSeconds` are not part of v2 and a host MUST NOT emit them. A `429 rate_limited` response MUST set `Retry-After`. The retriable rows are `residency_unavailable`, `rate_limited`, `internal_error`, `pack_registry_unreachable`, `runner_unavailable`.
+Retry timing lives in the `Retry-After` header only.
+
+- A host MUST NOT emit `details.retryAfter`, `details.retryAfterMs` or `details.retryAfterSeconds`.
+- A `429 rate_limited` response MUST set `Retry-After`.
+
+The retriable rows are `residency_unavailable`, `rate_limited`, `internal_error`, `pack_registry_unreachable`, `runner_unavailable`.
 
 ## One code per state
 
-An interrupt has one code per state: a token or run-scoped resolve against an interrupt that is already resolved, or whose run is cancelled or completed, MUST return `409 interrupt_already_resolved`; a signed token past its `expiresAt` MUST return `410 interrupt_expired`; a token whose `alg` or `kid` the host does not accept MUST return `401 interrupt_token_invalid` (see interrupt.md, identity.md). The idempotency mismatch code is `idempotency_key_mismatch` only (idempotency.md). `interrupt_cancelled` is registered and names no state of the core resolve surfaces; a host MUST NOT emit it from `resolveInterruptByRun`, `inspectInterruptByToken` or `resolveInterruptByToken` (RFC 0213 §C).
+An interrupt has one code per state ([interrupt.md](interrupt.md), [identity.md](identity.md)):
+
+- A token or run-scoped resolve against an interrupt that is already resolved, or whose run is cancelled or completed, MUST return `409 interrupt_already_resolved`.
+- A signed token past its `expiresAt` MUST return `410 interrupt_expired`.
+- A token whose `alg` or `kid` the host does not accept MUST return `401 interrupt_token_invalid`.
+- `interrupt_cancelled` is registered but names no state of the core resolve surfaces. A host MUST NOT emit it from `resolveInterruptByRun`, `inspectInterruptByToken` or `resolveInterruptByToken`.
+
+The idempotency mismatch code is `idempotency_key_mismatch` only ([idempotency.md](idempotency.md)).
 
 ## Codes by HTTP status
 
@@ -138,4 +157,6 @@ Code | Status
 `payload_unprojectable` | 500
 `credential_unavailable` | 501
 `pack_registry_unreachable` | 503
-`runner_unavailable` | 503
+`runner_unavailable` | 503
+
+*Sources: RFC 0171, RFC 0213.*

package/spec/v2/core/events.md

@@ -1,155 +1,191 @@
 # Events
 
-> **Status: Stable · RFC 0171 §A, §E; RFC 0176 §A.**
+> **Status: Stable.**
 > **Normative home:** `heartbeat`, `envelopeContracts`, `envelopes`, `feedback`, `providerUsage`, `supportedEnvelopes`, `schemaVersions`, `envelopeStrictness`.
 
 ## Why this exists
 
-A run is its append-only event log; every snapshot, stream, poll, fork and diff is a projection of it. v2 has one closed envelope, type registry, payload registry, ordering field, events channel and poll cursor.
+A run is its append-only event log. Every snapshot, stream, poll, fork and diff is a projection of it. There is one closed envelope, type registry, payload registry, ordering field, events channel and poll cursor.
 
 ## The envelope
 
-`schemas/v2/run-event.schema.json` (`RunEventDoc`) is closed. `eventId`, `runId`, `type`, `payload`, `timestamp`, `sequence` and `schemaVersion` are REQUIRED; `nodeId`, `engineVersion` and `causationId` are OPTIONAL. Every id field `$ref`s its grammar in `schemas/v2/ids.schema.json` (identity.md).
+`schemas/v2/run-event.schema.json` (`RunEventDoc`) is closed. `eventId`, `runId`, `type`, `payload`, `timestamp`, `sequence` and `schemaVersion` are REQUIRED; `nodeId`, `engineVersion` and `causationId` are OPTIONAL. Every id field `$ref`s its grammar in `schemas/v2/ids.schema.json` ([identity.md](identity.md)).
 
-| Field | Rule |
+| Field | Meaning |
 | --- | --- |
-| `sequence` | The one ordering field: integer ≥ 0, first event `0`, strictly increasing per run. Persisted logs are never renumbered. |
-| `schemaVersion` | Per-event schema version, integer ≥ 1, first-class (RFC 0172 §B axis 5). |
-| `engineVersion` | Integer ≥ 0 everywhere (RFC 0172 §B axis 3). |
-| `eventId` | Host-minted, opaque; consumers MUST treat it as a string. |
-| `causationId` | The `eventId`, or AI-envelope `correlationId`, that caused this event. |
-| `timestamp` | ISO 8601. |
+| `sequence` | The one ordering field: integer ≥ 0, first event `0`, strictly increasing per run |
+| `schemaVersion` | Per-event schema version, integer ≥ 1, first-class |
+| `engineVersion` | Integer ≥ 0 everywhere |
+| `eventId` | Host-minted, opaque |
+| `causationId` | The `eventId`, or AI-envelope `correlationId`, that caused this event |
+| `timestamp` | ISO 8601 |
 
-A consumer MUST NOT throw on an event whose `type` it does not know; it folds what it understands and ignores the rest.
+- Persisted logs are never renumbered.
+- A consumer MUST treat `eventId` as a string.
+- A consumer MUST NOT throw on an event whose `type` it does not know; it folds what it understands and ignores the rest.
 
 ## Types
 
-`type` is `oneOf` a closed enum of registered protocol types and a vendor pattern. The enum is GENERATED from `spec/v2/event-codemap.json` (118 rows, every row `decided`) and MUST NOT be edited by hand. The vendor branch is exactly:
+`type` is `oneOf` a closed enum of registered protocol types and a vendor pattern. The enum is generated from `spec/v2/event-codemap.json` and MUST NOT be edited by hand. The vendor branch is exactly:
 
 ```text
 ^(?!openwop\.)[a-z][a-z0-9]*(-[a-z0-9]+)*\.[a-z][a-z0-9]*(-[a-z0-9]+)*(\.[a-z][a-z0-9]*(-[a-z0-9]+)*)?$
 ```
 
-| Rule | Requirement |
-| --- | --- |
-| Naming | A protocol type is `domain.verb-ed`: kebab-case, exactly two segments, past tense for a transition (`run.started`, `node.suspend-failed`, `run.resume-started`). `domain.noun` is permitted only for an emitted artifact (`output.chunk`, `provider.usage`, `channel.presence`, `agent.handoff`, `envelope.refusal`, `agent.reasoning-delta`, `voice.synthesis-chunk`, `voice.endpoint-candidate`); each exception is recorded in the codemap and checked by the corpus gate. |
-| Reserved prefix | `openwop.` is the only reserved prefix. `core.`, `community.`, `vendor.`, `private.` and `local.` are pack namespaces, not event namespaces, and a type under them is invalid. |
-| Vendor events | A vendor type's first segment MUST be an org registered in the `extensions` object of `spec/v2/declaration.json` — the ORG REGISTRY, not the `extensions` metadata key a host publishes in its own discovery payload; an unregistered org fails validation. An org named in `reservedOrgs` is forbidden, never registered, and `extensionsKeyPattern` is the shape a vendor type must have, not a permission to use it. The registry is normally small: `example` is held by the protocol for documentation and conformance and is never assignable to a vendor. |
-| Growth | The registry grows by the closed-enum rule in overview.md §0: a producer MUST NOT emit an unregistered protocol type; a consumer MUST accept an unknown registered member and MUST NOT act on it. |
+- **Naming.** A protocol type is `domain.verb-ed`: kebab-case, exactly two segments, past tense for a transition (`run.started`, `node.suspend-failed`, `run.resume-started`). `domain.noun` is permitted only for an emitted artifact (`output.chunk`, `provider.usage`, `channel.presence`, `agent.handoff`, `envelope.refusal`, `agent.reasoning-delta`, `voice.synthesis-chunk`, `voice.endpoint-candidate`); each exception is recorded in the codemap.
+- **Reserved prefix.** `openwop.` is the only reserved prefix. `core.`, `community.`, `vendor.`, `private.` and `local.` are pack namespaces, not event namespaces; a type under them is invalid.
+- **Vendor events.** A vendor type's first segment MUST be an org registered in the `extensions` object of `spec/v2/declaration.json` (the org registry, not the `extensions` metadata key a host publishes in discovery). An unregistered org fails validation. An org in `reservedOrgs` is forbidden and never registered. `extensionsKeyPattern` is the shape a vendor type must have, not a permission to use it. `example` is held by the protocol for documentation and conformance and is never assignable to a vendor.
+- **Growth.** The registry grows by the closed-enum rule in [overview.md](overview.md) §0. A producer MUST NOT emit an unregistered protocol type. A consumer MUST accept an unknown registered member and MUST NOT act on it.
 
 ## Payloads
 
-`schemas/v2/run-event-payloads.schema.json` holds one `$defs` entry per payload, every entry `additionalProperties: false`, and `_typeIndex`: the NORMATIVE map from v2 type to `$defs` key, GENERATED from `spec/v2/event-codemap.json`. A host MUST emit a payload that validates against the entry `_typeIndex` names for its `type`. Sub-typing is `$ref` composition, never duplication: `approval.*` and `clarification.*` resolve to `interruptRequested` / `interruptResolved` (interrupt.md); `lease.acquired`, `lease.renewed` and `lease.lost` share `leaseLifecycle`.
+`schemas/v2/run-event-payloads.schema.json` holds one `$defs` entry per payload, each `additionalProperties: false`, plus `_typeIndex`: the normative map from v2 type to `$defs` key, generated from `spec/v2/event-codemap.json`.
+
+- A host MUST emit a payload that validates against the entry `_typeIndex` names for its `type`.
+- Sub-typing is `$ref` composition, never duplication. `approval.*` and `clarification.*` resolve to `interruptRequested` / `interruptResolved` ([interrupt.md](interrupt.md)); `lease.acquired`, `lease.renewed` and `lease.lost` share `leaseLifecycle`.
+- The CloudEvents mapping and the webhook delivery envelope are generated from the same definition. An event's `type`, `eventId`, `sequence` and `payload` are byte-identical across the run stream, a CloudEvents rendering and a webhook delivery.
 
-The CloudEvents mapping and the webhook delivery envelope are GENERATED from the same definition (one source, three renderings): the event's `type`, `eventId`, `sequence` and `payload` are byte-identical across the run stream, a CloudEvents rendering and a webhook delivery.
+Specific payloads:
 
-`run.started` carries the `owner` block (identity.md §1.1).
-`run.cancelled` carries `reason`, `cancelledBy`, `durationMs`, and `parentRunId`.
-`run.completed` MUST carry `outputs` as an object; an empty object is valid, but
-an absent key is not. This distinguishes “no outputs” from “outputs not
-rendered” and is witnessed by `v2-run-completed-outputs`.
+- `run.started` carries the `owner` block ([identity.md](identity.md) §1.1).
+- `run.cancelled` carries `reason`, `cancelledBy`, `durationMs`, and `parentRunId`.
+- `run.completed` MUST carry `outputs` as an object. An empty object is valid; an absent key is not. This separates "no outputs" from "outputs not rendered".
 
 ## AI envelopes: E1–E5
 
-`schemas/v2/ai-envelope.schema.json` is the shape an LLM emits; the engine records its acceptance as one or more `RunEventDoc`s. In v2 `correlationId` and `meta.source` are REQUIRED on every envelope, and an engine MUST reject an envelope that omits either; nothing is synthesized. An envelope kind MUST be namespaced under the same `<org>.` rule as events, universal kinds and the core content-primitive families `ui.*` and `media.*` excepted.
+`schemas/v2/ai-envelope.schema.json` is the shape an LLM emits; the engine records its acceptance as one or more `RunEventDoc`s.
 
-| Gap | Contract |
-| --- | --- |
-| E1 partial reassembly | Every chunk of one partial emission carries the same `correlationId`; the events that record them are ordered by `sequence`; the emission is complete at the first recorded chunk with `partial: false`. A consumer MAY render progressively but MUST NOT enable any action before that event. |
-| E2 multi-turn correlation | Each turn is an envelope with its own `correlationId`; every event it produces carries `causationId = correlationId`. A re-emission with a `correlationId` already recorded in the run MUST return the cached outcome and MUST NOT emit new events. |
-| E3 vendor kinds | The registry of vendor kinds is `spec/v2/declaration.json`; a kind whose org is not registered is invalid. |
-| E4 sub-typing | `$ref` composition, as in the payload registry above. |
-| E5 refusal × retry | `configurable.ai.maxRefusals` (runs.md) is the ceiling on `envelope.refusal` events a run records. A host MUST NOT retry the emission that produced a refusal. |
+- `correlationId` and `meta.source` are REQUIRED on every envelope. An engine MUST reject an envelope that omits either; nothing is synthesized.
+- An envelope kind MUST be namespaced under the same `<org>.` rule as events, universal kinds and the core content-primitive families `ui.*` and `media.*` excepted.
+
+The five contracts:
+
+- **E1 partial reassembly.** Every chunk of one partial emission carries the same `correlationId`, and the events that record them are ordered by `sequence`. The emission is complete at the first recorded chunk with `partial: false`. A consumer MAY render progressively but MUST NOT enable any action before that event.
+- **E2 multi-turn correlation.** Each turn is an envelope with its own `correlationId`; every event it produces carries `causationId = correlationId`. A re-emission with a `correlationId` already recorded in the run MUST return the cached outcome and MUST NOT emit new events.
+- **E3 vendor kinds.** The registry of vendor kinds is `spec/v2/declaration.json`. A kind whose org is not registered is invalid.
+- **E4 sub-typing.** `$ref` composition, as in the payload registry above.
+- **E5 refusal × retry.** `configurable.ai.maxRefusals` ([runs.md](runs.md)) is the ceiling on `envelope.refusal` events a run records. A host MUST NOT retry the emission that produced a refusal.
 
 ## The events channel
 
-`api/v2/asyncapi.yaml` declares one channel, `runEvents`, at `/runs/{runId}/events`, and `api/v2/openapi.yaml` declares the same path (`streamRunEvents`); the two MUST resolve to the same absolute path (RFC 0172 §C.2). The `streamMode` query parameter is one pattern, not four enums:
+`api/v2/asyncapi.yaml` declares one channel, `runEvents`, at `/runs/{runId}/events`, and `api/v2/openapi.yaml` declares the same path (`streamRunEvents`). The two MUST resolve to the same absolute path.
+
+### Stream modes
+
+The `streamMode` query parameter is one pattern:
 
 ```text
 ^(values|(updates|messages|debug)(,(updates|messages|debug))*)$
 ```
 
-The default is `updates`. A host MUST implement `updates` and SHOULD implement all four. A value outside the pattern, or a mode the host does not implement, MUST return `400 unsupported_stream_mode` with `details.supported` listing each individual mode the host serves; combinations are not listed. Validation MUST run before any content negotiation.
-
 | Mode | Emits | Combines |
 | --- | --- | --- |
-| `updates` | Run transitions, terminal node transitions, suspensions, `node.dispatched`, interrupt events, `artifact.created`, `eval.*`, `deployment.*`, `workspace.updated`; each payload is a delta | yes |
+| `updates` (default) | Deltas for run transitions, terminal node transitions, suspensions, `node.dispatched`, interrupt events, `artifact.created`, `eval.*`, `deployment.*`, `workspace.updated` | yes |
 | `values` | One synthesized `state.snapshot` (`schemas/v2/run-snapshot.schema.json`) after each `updates`-tier transition | never |
-| `messages` | `ai.message.chunk` (`outputChunk` payload) from streaming AI nodes only; a host MUST populate a Tier 1 `meta` slot whenever it has the data | yes |
+| `messages` | `ai.message.chunk` (`outputChunk` payload) from streaming AI nodes only | yes |
 | `debug` | Every event in the log, including `log.appended`, `variable.changed`, `version.pinned`, `lease.*`, `node.retried` and every vendor event | yes |
 
-Vendor events appear in `debug` only. In a mixed mode the host emits the union of the filters in log order and MUST NOT reorder; each frame SHOULD carry `event:` naming the mode that admitted it, and a consumer MUST tolerate an event admitted by more than one mode.
+- A host MUST implement `updates` and SHOULD implement all four.
+- A value outside the pattern, or a mode the host does not implement, MUST return `400 unsupported_stream_mode` with `details.supported` listing each individual mode the host serves; combinations are not listed.
+- Validation MUST run before any content negotiation.
+- In `messages`, a host MUST populate a Tier 1 `meta` slot whenever it has the data.
+- Vendor events appear in `debug` only.
+- In a mixed mode the host emits the union of the filters in log order and MUST NOT reorder. Each frame SHOULD carry `event:` naming the mode that admitted it. A consumer MUST tolerate an event admitted by more than one mode.
 
 ### SSE frames
 
-Each frame carries `id:`, `event:` and `data:`: `id:` is the `sequence`, `event:` is the v2 `type` (single mode), `data:` is the `RunEventDoc`. Three frame names are not types and are absent from the `type` enum: `state.snapshot` (`values`; `data:` a `RunSnapshot`), `batch` (`bufferMs`; `data:` an array of `RunEventDoc`) and `ai.message.chunk` (`messages`; `data:` the `outputChunk` payload, persisted type `output.chunk`). A host MUST set `Content-Type: text/event-stream`, MUST emit a keep-alive comment at least every 30 seconds, and MUST close the connection after the run's terminal event (`run.completed`, `run.failed`, `run.cancelled`).
+Each frame carries `id:` (the `sequence`), `event:` (the v2 `type`, in a single mode) and `data:` (the `RunEventDoc`). Three frame names are not types and are absent from the `type` enum:
+
+- `state.snapshot` — `values` mode; `data:` is a `RunSnapshot`.
+- `batch` — `bufferMs`; `data:` is an array of `RunEventDoc`.
+- `ai.message.chunk` — `messages` mode; `data:` is the `outputChunk` payload, persisted as type `output.chunk`.
+
+A host MUST set `Content-Type: text/event-stream`, MUST emit a keep-alive comment at least every 30 seconds, and MUST close the connection after the run's terminal event (`run.completed`, `run.failed`, `run.cancelled`).
+
+#### Resuming with `Last-Event-ID`
+
+`Last-Event-ID: N` resumes every mode as an exclusive cursor, with the semantics of poll's `afterSequence`.
+
+- The host MUST stream the events with `sequence > N` in log order and MUST NOT re-emit `N`.
+- When `N` is at or beyond the last persisted sequence there is no backlog. On a live run the host MUST hold the stream open for later events; on a terminal run it MUST close the stream without a frame.
+- A host MUST NOT refuse a well-formed non-negative integer `Last-Event-ID` because no event carries that sequence. Any other value SHOULD be refused with `400 validation_error`.
+- The header is evaluated only after the caller is authorized to read the run. For a run the caller cannot read, the response MUST be the one the host gives without the header.
+- In `values` mode, resumption MUST emit a `state.snapshot` first.
 
-`Last-Event-ID: N` resumes every mode as an exclusive cursor with the semantics of poll's `afterSequence`: the host MUST stream the events with `sequence > N` in log order and MUST NOT re-emit `N`. When `N` is at or beyond the last persisted sequence there is no backlog: on a live run the host MUST hold the stream open for later events, and on a terminal run it MUST close the stream without a frame. A host MUST NOT refuse a well-formed non-negative integer `Last-Event-ID` because no event carries that sequence; any other value SHOULD be refused with `400 validation_error`. The header is evaluated only after the caller is authorized to read the run: for a run the caller cannot read, the response MUST be the one the host gives without the header (RFC 0213 §A). In `values` mode resumption MUST emit a `state.snapshot` first. With `bufferMs` (0..5000) the host accumulates events into one `event: batch` frame whose `data:` is an array of `RunEventDoc`; it MUST flush on a terminal event, on `node.suspended`, and on close; the batch's `id:` SHOULD be its highest `sequence` and `Last-Event-ID` MUST honor that id. A consumer MUST tolerate both a one-element batch and an unbatched frame. A host MUST NOT limit subscribers per run except for resource protection, and then MUST answer `429 rate_limited` with `Retry-After` rather than drop silently.
+#### Batching and subscribers
+
+With `bufferMs` (0..5000) the host accumulates events into one `event: batch` frame whose `data:` is an array of `RunEventDoc`.
+
+- It MUST flush on a terminal event, on `node.suspended`, and on close.
+- The batch's `id:` SHOULD be its highest `sequence`, and `Last-Event-ID` MUST honor that id.
+- A consumer MUST tolerate both a one-element batch and an unbatched frame.
+- A host MUST NOT limit subscribers per run except for resource protection, and then MUST answer `429 rate_limited` with `Retry-After` rather than drop silently.
 
 ### Host events
 
-`hostEvents` carries the heartbeat messages (`schemas/v2/heartbeat-evaluated.schema.json`, `schemas/v2/heartbeat-state-changed.schema.json`) at `/host/events` (`streamHostEvents`), the documented default; a host MAY declare another address under `heartbeat.deliveryChannel` (capabilities.md). The channel is content-free of run data. There is no channel without an address.
+`hostEvents` carries the heartbeat messages (`schemas/v2/heartbeat-evaluated.schema.json`, `schemas/v2/heartbeat-state-changed.schema.json`) at `/host/events` (`streamHostEvents`), the documented default. A host MAY declare another address under `heartbeat.deliveryChannel` ([capabilities.md](capabilities.md)). The channel is content-free of run data. There is no channel without an address.
 
 ## Poll
 
 `GET /runs/{runId}/events/poll` (`pollRunEvents`) is the long-poll fallback.
 
-| Parameter | Rule |
+| Parameter | Meaning |
 | --- | --- |
-| `afterSequence` | Integer ≥ 0; the response carries events with `sequence > afterSequence`. Omission means "from the first event" (sequence 0). `lastSequence` and `since` are not parameters. |
-| `timeout` | Seconds to wait for new events, 1..60, default 30. |
+| `afterSequence` | Integer ≥ 0; return events with `sequence > afterSequence`. Omitted means from sequence 0 |
+| `timeout` | Seconds to wait for new events, 1..60, default 30 |
+
+`lastSequence` and `since` are not parameters.
+
+The response is `{ runId, events, lastSequence, status, isTerminal }` (closed):
 
-The response is `{ runId, events, lastSequence, status, isTerminal }` (closed): `lastSequence` is the highest sequence in the log at the time of the response, `-1` when the log is empty; `status` is the snapshot status; `isTerminal` is whether the run is terminal. A cursor past the end of the log MUST return `200` with an empty `events` array. The shape is declared here and generated into `api/v2/openapi.yaml` from one definition.
+- `lastSequence` is the highest sequence in the log at the time of the response, `-1` when the log is empty.
+- `status` is the snapshot status; `isTerminal` is whether the run is terminal.
+- A cursor past the end of the log MUST return `200` with an empty `events` array.
 
 ## The terminal event
 
-A run's log MUST contain exactly one terminal run event — `run.completed`, `run.failed` or `run.cancelled` — and after it MUST NOT contain another terminal run event, `run.started`, `run.resumed`, `run.resume-started`, `run.paused`, `run.restored-from-snapshot`, any `node.*` event or any `interrupt.*` event. `compensation.*` events and `run.dead-lettered` MAY follow it (a compensating host unwinds after a cancelled parent); vendor-prefixed types are unconstrained. A host that receives work for a run whose terminal event is recorded — a duplicate delivery, a late worker — MUST NOT append forward-execution events for it, SHOULD record the refusal in its operational log, and MUST NOT surface the refusal as a run event (RFC 0194). No stream-closure rule changes.
+A run's log MUST contain exactly one terminal run event: `run.completed`, `run.failed` or `run.cancelled`.
+
+- After it, the log MUST NOT contain another terminal run event, `run.started`, `run.resumed`, `run.resume-started`, `run.paused`, `run.restored-from-snapshot`, any `node.*` event or any `interrupt.*` event.
+- `compensation.*` events and `run.dead-lettered` MAY follow it (a compensating host unwinds after a cancelled parent). Vendor-prefixed types are unconstrained.
+- A host that receives work for a run whose terminal event is recorded (a duplicate delivery, a late worker) MUST NOT append forward-execution events for it, SHOULD record the refusal in its operational log, and MUST NOT surface the refusal as a run event.
 
 ## Era-2 logs
 
-An `eventLogSchemaVersion` of `2` means v1-written; every reader, diff included, translates it per persistence.md §"The reader rule". **A projection MUST NOT silently drop a property**: carry or fail `500 payload_unprojectable` (hatch `^(openwop-|x-|vendor\.)`; RFC 0185). Fork and replay over an era-2 parent: replay.md.
+An `eventLogSchemaVersion` of `2` means v1-written. Every reader, diff included, translates it per [persistence.md](persistence.md) §"The reader rule".
+
+- A projection MUST NOT silently drop a property: it carries it or fails with `500 payload_unprojectable` (hatch `^(openwop-|x-|vendor\.)`).
+- Fork and replay over an era-2 parent are in [replay.md](replay.md).
 
 ## The envelope-kind catalog
 
-`supportedEnvelopes`, `schemaVersions` and `envelopeStrictness` are one flow, read in
-that order on every inbound envelope.
+`supportedEnvelopes`, `schemaVersions` and `envelopeStrictness` are one flow, read in that order on every inbound envelope.
 
-`supportedEnvelopes.kinds` is the catalog. A host advertising it MUST refuse an
-emitted `type` that is neither universal nor a member, with `unknown_envelope_kind`.
-**An absent `kinds` is not an empty catalog and is not an unrestricted one**: a host
-advertising `supportedEnvelopes` without it has made no catalog claim, and an engine
-MUST refuse every non-universal kind rather than admit it unchecked.
+### `supportedEnvelopes`
 
-`schemaVersions.kinds` maps a kind to its advertised floor; a kind absent from the map
-has a floor of `0`. An emitted `schemaVersion` ABOVE the floor MUST be refused with
-`unknown_schema_version` whatever the strictness.
-`ui.a2ui-surface` at schema version 2 is specified by `ext/a2uiSurface/README.md`.
+`supportedEnvelopes.kinds` is the catalog. A host advertising it MUST refuse an emitted `type` that is neither universal nor a member, with `unknown_envelope_kind`.
 
-`envelopeStrictness.mode` governs drift BELOW the floor only. Under `warn` — the value
-when the seat is absent — an engine MUST validate against the advertised version and
-log `envelope_schema_version_drift`. Under `strict` the same condition MUST refuse with
-`unknown_schema_version`. A host MUST NOT read an absent `mode` as "no checking".
+An absent `kinds` is not an empty catalog and is not an unrestricted one: a host advertising `supportedEnvelopes` without it has made no catalog claim, and an engine MUST refuse every non-universal kind rather than admit it unchecked.
 
-## Envelope contracts
+### `schemaVersions`
 
-`envelopeContracts` advertises that a host enforces per-node envelope permission
-sets. A host advertising `envelopeContracts.advertised` MUST refuse a node whose
-emitted envelope `type` is neither universal nor listed in that node's accepted
-set, and MUST refuse it distinctly from the capability-gated `typeId` refusal —
-the two stack rather than substitute.
+`schemaVersions.kinds` maps a kind to its advertised floor; a kind absent from the map has a floor of `0`. An emitted `schemaVersion` above the floor MUST be refused with `unknown_schema_version`, whatever the strictness. `ui.a2ui-surface` at schema version 2 is specified by `ext/a2uiSurface/README.md`.
 
-## Envelope, feedback and usage facets
+### `envelopeStrictness`
+
+`envelopeStrictness.mode` governs drift below the floor only. A host MUST NOT read an absent `mode` as "no checking".
+
+- Under `warn` (the value when the seat is absent), an engine MUST validate against the advertised version and log `envelope_schema_version_drift`.
+- Under `strict`, the same condition MUST refuse with `unknown_schema_version`.
 
-`envelopes.tierOneSubsetCompliance` advertises that the host accepts the Tier 1
-structured-output subset shared across major providers; a host advertising it MUST
-accept an envelope restricted to that subset from any provider it advertises, rather
-than refusing on provider-specific grounds.
+## Envelope contracts
+
+`envelopeContracts` advertises that a host enforces per-node envelope permission sets. A host advertising `envelopeContracts.advertised` MUST refuse a node whose emitted envelope `type` is neither universal nor listed in that node's accepted set. It MUST refuse it distinctly from the capability-gated `typeId` refusal: the two stack rather than substitute.
 
-`feedback.targets` names the resources an annotation may be attached to. A host MUST
-refuse an annotation whose target is outside the advertised set, and MUST NOT write it
-to the replayable run event log.
+## Envelope, feedback and usage facets
 
-`providerUsage.costEstimates` advertises that the host stamps a derived cost on the
-`provider.usage` event. That figure is an estimate from the host's own rate table, and
-a consumer MUST NOT treat it as a billed amount.
+- **`envelopes.tierOneSubsetCompliance`** advertises that the host accepts the Tier 1 structured-output subset shared across major providers. A host advertising it MUST accept an envelope restricted to that subset from any provider it advertises, rather than refusing on provider-specific grounds.
+- **`feedback.targets`** names the resources an annotation may be attached to. A host MUST refuse an annotation whose target is outside the advertised set, and MUST NOT write it to the replayable run event log.
+- **`providerUsage.costEstimates`** advertises that the host stamps a derived cost on the `provider.usage` event. That figure is an estimate from the host's own rate table; a consumer MUST NOT treat it as a billed amount.
 
+*Sources: RFC 0171, RFC 0172, RFC 0176, RFC 0185, RFC 0194, RFC 0213.*