@openwop/spec-artifacts 2.42.5 → 2.42.7

package/spec/v2/core/overview.md

@@ -1,41 +1,47 @@
 # OpenWOP v2 Core — Overview
 
-> **Status: Stable · RFC 0167, 0168, 0169, 0171, 0174.**
+> **Status: Stable.**
 
 ## Why this exists
 
-`spec/v2/core/` is the front door a host implements to pass the 2.0.0 floor. This document fixes the reading order, restates the six axioms, and states once the rules other documents only reference.
+`spec/v2/core/` is what a host implements to pass the 2.0.0 floor. This document sets the reading order, states the six axioms, and holds the rules other documents only reference.
 
 ## Reading order
 
-1. `overview.md` — axioms, §0, §0a, claim vocabulary, `ext/` rule
-2. `versioning.md` — major negotiation, `OpenWOP-Version`, the 18 axes, release identity
-3. `capabilities.md` — one well-known resource, record type, closed root, derived profiles
-4. `identity.md` — Subject, lanes, `SubjectLink`, id grammars, resume tokens
-5. `runs.md` — create / get / cancel / fork, `configurable`, snapshot, owner
-6. `events.md`, `errors.md`, `headers.md` — event `oneOf`, payload and error registries, `OpenWOP-*`
-7. `interrupt.md`, `idempotency.md`, `replay.md`, `conversation.md` — run-side surfaces
-8. `persistence.md` — era key, v1 reader rule, pinned runs
-9. `security-defaults.md`, `webhooks.md`, `interop.md`, `host-services.md` — obligations of a surface, signatures, A2A / MCP, host services
-10. `packs.md`, `connection-packs.md`, `form-content-packs.md`, `workflow-chain-packs.md` — pack identity, engines ceiling
-11. `conformance.md` — requirement ids, witness classes, bundle v3, seams profile
+1. [`overview.md`](overview.md) — axioms, §0, §0a, claim vocabulary, the `ext/` rule
+2. [`versioning.md`](versioning.md) — major negotiation, `OpenWOP-Version`, the 18 axes, release identity
+3. [`capabilities.md`](capabilities.md) — the well-known resource, record type, closed root, derived profiles
+4. [`identity.md`](identity.md) — Subject, lanes, `SubjectLink`, id grammars, resume tokens
+5. [`runs.md`](runs.md) — create, get, cancel, fork; `configurable`; snapshot; owner
+6. [`events.md`](events.md), [`errors.md`](errors.md), [`headers.md`](headers.md) — event `oneOf`, payload and error registries, `OpenWOP-*` headers
+7. [`interrupt.md`](interrupt.md), [`idempotency.md`](idempotency.md), [`replay.md`](replay.md), [`conversation.md`](conversation.md) — run-side surfaces
+8. [`persistence.md`](persistence.md) — era key, v1 reader rule, pinned runs
+9. [`security-defaults.md`](security-defaults.md), [`webhooks.md`](webhooks.md), [`interop.md`](interop.md), [`host-services.md`](host-services.md), [`tool-catalog.md`](tool-catalog.md) — surface obligations, signatures, A2A and MCP, host services
+10. [`packs.md`](packs.md), [`node-pack-runtimes.md`](node-pack-runtimes.md), [`connection-packs.md`](connection-packs.md), [`form-content-packs.md`](form-content-packs.md), [`workflow-chain-packs.md`](workflow-chain-packs.md) — pack identity, engines ceiling
+11. [`conformance.md`](conformance.md) — requirement ids, witness classes, bundle v3, seams profile
 
-## Axioms in force (RFC 0167 §A)
+## Axioms in force
 
 1. A MUST without a witness class is not a requirement.
-2. One name per thing; every alias has a removal date in `spec/v1/deprecations.json` and a codemod id.
-3. Closed by default: discovery root, event envelope, payload and error registries, bundle, and `configurable` are `additionalProperties: false`; vendor extension is one positive pattern in one namespace.
-4. Registers are data: gaps, risks, deprecations, migrations, witness classes, and dispositions are files with schemas and gates; prose is checked against them, never the reverse.
-5. Security defaults are obligations of the surface: a protecting behavior binds when the surface is advertised, never when a flag is set.
-6. Nothing persisted under v1 is orphaned: every v1 artifact has a disposition in the migration register.
+2. One name per thing. Every alias has a removal date in `spec/v1/deprecations.json` and a codemod id.
+3. Closed by default. The discovery root, event envelope, payload and error registries, bundle, and `configurable` are `additionalProperties: false`. Vendor extension is one positive pattern in one namespace.
+4. Registers are data. Gaps, risks, deprecations, migrations, witness classes, and dispositions are files with schemas and gates; prose is checked against them, never the reverse.
+5. Security defaults are obligations of the surface. A protecting behavior binds when the surface is advertised, never when a flag is set.
+6. Nothing persisted under v1 is orphaned. Every v1 artifact has a disposition in the migration register.
 
-## §0 Closed-enum growth rule (RFC 0171 §A.5)
+## §0 Closed-enum growth rule
 
-A registry-backed enum (event types, error codes, envelope kinds, reason vocabularies, lanes) grows by adding a row to its registry and regenerating. Consumers MUST accept an unknown member of a registry-backed enum and MUST NOT act on it. Producers MUST NOT emit an unregistered member. Adding a member is additive in v2.x; renaming one is a major, and removing one is a major except under §0a.
+A registry-backed enum (event types, error codes, envelope kinds, reason vocabularies, lanes) grows by adding a row to its registry and regenerating.
 
-## §0a Retiring a v2 surface (RFC 0197)
+- Consumers MUST accept an unknown member of a registry-backed enum and MUST NOT act on it.
+- Producers MUST NOT emit an unregistered member.
+- Adding a member is additive in v2.x. Renaming one is a major; removing one is a major except under §0a.
 
-A 2.x minor MUST NOT change the shape of an existing v2 surface; a new shape is a new surface added beside the old one. A 2.x minor MAY remove a surface only when `scripts/check-v2-retirement.mjs` proves all of the following; otherwise the removal waits for 3.0.
+## §0a Retiring a v2 surface
+
+A 2.x minor MUST NOT change the shape of an existing v2 surface; a new shape is a new surface added beside the old one.
+
+A 2.x minor MAY remove a surface only when `scripts/check-v2-retirement.mjs` proves all of the following; otherwise the removal waits for 3.0:
 
 1. Its replacement shipped in an earlier 2.x minor.
 2. A `v2-minor` row in `spec/v1/deprecations.json` named the removal minor at least two minors and 30 days earlier.
@@ -46,26 +52,48 @@ A 2.x minor MUST NOT change the shape of an existing v2 surface; a new shape is
 
 Readers MUST keep accepting a retired shape on replay, fork and poll; only emission narrows.
 
-## v1 end-of-support (RFC 0174 §B.4)
+## v1 end-of-support
+
+v1 support ends at the later of:
+
+- (a) every INTEROP-MATRIX host's non-vacuous v2 bundle, plus 90 days;
+- (b) 18 months from the v2 release — applied if and only if an independent host is in the matrix at release.
+
+The date is computed from the matrix; nothing else MAY set it.
 
-v1 support ends at the later of (a) every INTEROP-MATRIX host's non-vacuous v2 bundle plus 90 days and (b) 18 months from the v2 release, where (b) applies if and only if an independent host is in the matrix at release. Phase 5 computes the date from the matrix; nothing else MAY set it. The hosts counted under (a) are those with a row in the INTEROP-MATRIX v2 table; a reference host that stays on the 1.x line through the overlap (the matrix says which) is not a v2 host and does not count. A host's bundle is "non-vacuous" when at least one claimed profile carries `witnessCount ≥ 1`. The anchor for a host is the date its signed bundle was committed to `evidence/v2-host-bundles/` in the spec repository, read from the public history (`git log --diff-filter=A`), never from `generatedAt` inside the bundle, which nothing signs; a later re-certification replaces the file and does not move the anchor. `evidence/v1-end-of-support.json` is the computed date and is GENERATED (`scripts/generate-v1-eos-clock.mjs`); `check-removal-dates.mjs` reads it and fails the v1-tree sources of every `v1-end-of-support` row on or after it.
+- **Counted hosts.** Those with a row in the INTEROP-MATRIX v2 table. A reference host that stays on the 1.x line through the overlap (the matrix says which) is not a v2 host and does not count.
+- **Non-vacuous.** At least one claimed profile carries `witnessCount ≥ 1`.
+- **Anchor.** The date the host's signed bundle was committed to `evidence/v2-host-bundles/` in the spec repository, read from the public history (`git log --diff-filter=A`). Never `generatedAt` inside the bundle, which nothing signs. A later re-certification replaces the file and does not move the anchor.
+- **The computed date.** `evidence/v1-end-of-support.json`, GENERATED by `scripts/generate-v1-eos-clock.mjs`. `check-removal-dates.mjs` reads it and fails the v1-tree sources of every `v1-end-of-support` row on or after it.
 
-**Old-major retention floors.** Every published old-major artifact — the npm packages `@openwop/openwop` (1.x) and `@openwop/openwop-conformance` (1.x), the PyPI package `openwop-client` (1.x) and the Go module `github.com/openwop/openwop-sdks/go` (v1.x) — MUST remain installable at its last 1.x version for 12 months from the 2.0.0 publish (the `v2.0.0` tag's commit date), independent of v1 end-of-support, which may come first; a consumer pinned to the old major MUST be able to rebuild through that window. The identities and the last 1.x versions are `spec/v2/retention-floors.json`; `scripts/check-retention-floors.mjs` prints the floor state and, with `--network`, probes each registry for the pinned version. Unpublishing, deprecating-with-removal, or retracting a listed version inside the window is a Phase 5 exit failure.
+### Old-major retention floors
 
-## Profile claim vocabulary (RFC 0169 §C.3; RFC 0155 §A unchanged)
+Every published old-major artifact MUST remain installable at its last 1.x version for 12 months from the 2.0.0 publish (the `v2.0.0` tag's commit date). This holds independent of v1 end-of-support, which may come first. A consumer pinned to the old major MUST be able to rebuild through that window.
 
-Normative for any public conformance statement:
+The artifacts are the npm packages `@openwop/openwop` (1.x) and `@openwop/openwop-conformance` (1.x), the PyPI package `openwop-client` (1.x), and the Go module `github.com/openwop/openwop-sdks/go` (v1.x). Their identities and last 1.x versions are in `spec/v2/retention-floors.json`. `scripts/check-retention-floors.mjs` prints the floor state and, with `--network`, probes each registry for the pinned version.
+
+Unpublishing, deprecating-with-removal, or retracting a listed version inside the window is a Phase 5 exit failure.
+
+## Profile claim vocabulary
+
+These rules bind any public conformance statement:
 
 - An unqualified "OpenWOP conformant" or "OpenWOP compatible" statement MUST mean `openwop-core-standard`, the executable floor, never the discovery predicate.
 - A discovery-only claim MUST say `openwop-discovery-core` and MUST NOT use the same badge as `openwop-core-standard`.
 - Every claim MUST state every additional profile it relies on; an omitted profile is an unclaimed one.
-- A certification bundle MUST name canonical profile ids; `openwop-core` is deleted (see `capabilities.md`).
+- A certification bundle MUST name canonical profile ids; `openwop-core` is deleted (see [`capabilities.md`](capabilities.md)).
 - A vendor extension MUST NOT use an `openwop-*` id without an accepted RFC.
 
-## What is `ext/` (RFC 0174 §E.2; RFC 0169 §B.3)
+## What is `ext/`
+
+`spec/v2/core/` stays within the word budget that `scripts/check-core-budget.mjs` enforces; `spec/v2/ext/` holds the rest.
+
+- Every `spec/v2/ext/<key>/` document MUST declare `witness` and both maturity axes (`technical`, `adoption`) in its header.
+- A MUST with `witness: unwitnessable` MUST NOT appear in `core/`. A document whose only witness is "deferred to Active → Accepted" enters `ext/` or is deleted.
+- An `ext/` family is advertised only under a wire-legal witness class (see [`capabilities.md`](capabilities.md)).
 
-`spec/v2/core/` stays within the word budget `scripts/check-core-budget.mjs` enforces (RFC 0190). Every `spec/v2/ext/<key>/` document MUST declare `witness` and both maturity axes (`technical`, `adoption`) in its header. A MUST with `witness: unwitnessable` MUST NOT appear in `core/`; a document whose only witness is "deferred to Active → Accepted" enters `ext/` or is deleted. An `ext/` family is advertised only under a wire-legal witness class (see `capabilities.md`).
+## What a MUST means (Axiom 1)
 
-## What a MUST means (RFC 0168 §B.1; Axiom 1)
+Every MUST, SHOULD, and MAY in `core/` is a requirement with an id in `requirements.json` and a `witness` from `witnessable-unaided | witnessable-gated | seam-gated | claims-check | negative-existence`. A seam-gated MUST is governed by [`conformance.md`](conformance.md) §"Witness class".
 
-Every MUST, SHOULD, and MAY in `core/` is a requirement with an id in `requirements.json` and a `witness` from `witnessable-unaided | witnessable-gated | seam-gated | claims-check | negative-existence`. A seam-gated MUST is governed by `conformance.md` §"Witness class".
+*Sources: RFC 0155, RFC 0167, RFC 0168, RFC 0169, RFC 0171, RFC 0174, RFC 0190, RFC 0197.*

package/spec/v2/core/packs.md

@@ -1,39 +1,56 @@
 # Packs
 
-> **Status: Stable · RFC 0177.**
+> **Status: Stable.**
 > **Normative home:** `packs`.
 
 ## Why this exists
 
-The v2 contract for pack manifests, the registry tree, peer-dependency identifiers, and signing. The per-kind rules live in connection-packs.md, form-content-packs.md, and workflow-chain-packs.md; the capability vocabulary a pack requires is capabilities.md.
+The v2 contract for pack manifests, the registry tree, peer-dependency identifiers, and signing. The per-kind rules live in [connection-packs.md](connection-packs.md), [form-content-packs.md](form-content-packs.md), and [workflow-chain-packs.md](workflow-chain-packs.md); the capability vocabulary a pack requires is [capabilities.md](capabilities.md).
 
 ## The engine range
 
-A manifest's `engines.openwop` MUST match the grammar in `schemas/v2/node-pack-manifest.schema.json`: a `>=` lower bound and an explicit `<` major ceiling (`^>=\d+(\.\d+){0,2} <\d+\.0\.0$`). 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. The range is a claim about the pack's own surface, not about run semantics: admitting major M asserts that the manifest validates against the `schemas/v2/` manifest schema for its `kind`, that every `peerDependencies` key resolves (§"Peer-dependency identifiers"), and that the version carries a §Signing signature. Each conjunct keeps its own refusal code; a mechanical ceiling bump is not a verification. 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.
+A manifest's `engines.openwop` MUST match the grammar in `schemas/v2/node-pack-manifest.schema.json`: a `>=` lower bound and an explicit `<` major ceiling (`^>=\d+(\.\d+){0,2} <\d+\.0\.0$`).
+
+- 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.
+
+The range is a claim about the pack's own surface, not about run semantics. Admitting major M asserts that:
+
+- the manifest validates against the `schemas/v2/` manifest schema for its `kind`;
+- every `peerDependencies` key resolves (§"Peer-dependency identifiers");
+- the version carries a §Signing signature.
+
+Each conjunct keeps its own refusal code. A mechanical ceiling bump is not a verification.
 
 ## The `packs` capability
 
-A host advertises `packs` when it serves the registry surface above. The record
-is the advertisement: a host MUST NOT advertise `packs` unless it resolves pack
-references through a registry reachable from its discovery document, and a
-client MUST treat an absent record as "this host installs no packs" rather than
-as an unknown.
+A host advertises `packs` when it serves the registry surface above. The record is the advertisement:
 
-`testMode` is DEPRECATED and MUST NOT be relied on by a client. It advertises
-the v1 `/v1/packs-test/*` mirror, a conformance seam (`conformance.md`
-§"The seams profile"), and remains advertisable through the overlap because hosts already publish it; it is
-removed at 3.0. A host mounting a test catalog SHOULD advertise the seams
-profile instead, and MUST NOT treat `testMode` as a second way to claim one.
+- A host MUST NOT advertise `packs` unless it resolves pack references through a registry reachable from its discovery document.
+- A client MUST treat an absent record as "this host installs no packs", not as an unknown.
+
+`testMode` is DEPRECATED and MUST NOT be relied on by a client (see §"During the v1 overlap"). A host mounting a test catalog SHOULD advertise the seams profile instead, and MUST NOT treat `testMode` as a second way to claim one.
 
 ## The registry tree
 
-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; the v1 tree is frozen through the overlap, deliberately behind this one. A signed compatibility overlay MUST be rejected: signatures authorize by namespace, and a mirror re-derives the signer at ingest.
+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.
 
-`.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.
+- A signed compatibility overlay MUST be rejected: signatures authorize by namespace, and 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.
 
 ## Peer-dependency identifiers
 
-A `peerDependencies` key MUST be a `families[].key` in `spec/v2/declaration.json` whose `anchor` is not `deleted` — equivalently a root key of the generated `schemas/v2/capabilities.schema.json` — or carry a row in `spec/v2/peer-dependency-aliases.json`, which is how a v1-era key reaches a v2 family through the overlap; the declaration key, the peer-dependency identifier, and the capabilities.md section anchor are one identifier. A host MUST refuse a key the declaration file does not name with `pack_peer_dependency_undefined`. Facet paths are not identifiers: a pack requires a family by its key and names facets in `peerDependenciesMeta.<family>.facets[]`.
+A `peerDependencies` key MUST either:
+
+- be a `families[].key` in `spec/v2/declaration.json` whose `anchor` is not `deleted` — equivalently a root key of the generated `schemas/v2/capabilities.schema.json`; or
+- carry a row in `spec/v2/peer-dependency-aliases.json` (§"The alias table").
+
+The declaration key, the peer-dependency identifier, and the capabilities.md section anchor are one identifier. A host MUST refuse a key the declaration file does not name with `pack_peer_dependency_undefined`.
+
+Facet paths are not identifiers: a pack requires a family by its key and names facets in `peerDependenciesMeta.<family>.facets[]`.
 
 ```jsonc
 "peerDependencies": { "aiProviders": "required" },
@@ -42,11 +59,13 @@ A `peerDependencies` key MUST be a `families[].key` in `spec/v2/declaration.json
 
 ## The alias table
 
-`spec/v2/peer-dependency-aliases.json` is generated from the declaration file and the published-manifest inventory, never hand-kept; each of its 23 rows is `{ alias, family, facets?, publishedUses, removalTrigger }` and covers a v1 grammar found in the wild (`host.*` dotted twins, `openwop.agents.memoryBackends`, facet paths such as `aiProviders.imageGeneration`). A v2 host MAY resolve an alias through the table during the overlap and MUST NOT resolve one after v1 end-of-support (`removalTrigger: v1-end-of-support`). A row the declaration file cannot explain fails the corpus gate.
+`spec/v2/peer-dependency-aliases.json` is generated from the declaration file and the published-manifest inventory, never hand-kept. It is how a v1-era key reaches a v2 family through the overlap. Each row is `{ alias, family, facets?, publishedUses, removalTrigger }` and covers a v1 grammar found in the wild (`host.*` dotted twins, `openwop.agents.memoryBackends`, facet paths such as `aiProviders.imageGeneration`).
+
+A v2 host MAY resolve an alias through the table during the overlap, and MUST NOT resolve one after v1 end-of-support (`removalTrigger: v1-end-of-support`).
 
 ## The manifest schema family
 
-The 13 manifest schemas carry `$id` under `https://openwop.dev/spec/v2/`; the v1 `$id`s are immutable and served read-only.
+The manifest schemas carry `$id` under `https://openwop.dev/spec/v2/`; the v1 `$id`s are immutable and served read-only.
 
 | Schema (`schemas/v2/…`) | Author | Vendor hatch |
 | --- | --- | --- |
@@ -56,25 +75,24 @@ The 13 manifest schemas carry `$id` under `https://openwop.dev/spec/v2/`; the v1
 | `security-advisory` | registry | closed |
 | `prompt-ref` | leaf | none |
 
-Every pack-authored document MUST admit `patternProperties` `^(openwop-|x-|vendor\.)`. A consumer that does not recognize a hatch property MUST ignore it and MUST NOT reject the document; the value is pack-authored and therefore untrusted (security-defaults.md).
+Every pack-authored document MUST admit `patternProperties` `^(openwop-|x-|vendor\.)`. A consumer that does not recognize a hatch property MUST ignore it and MUST NOT reject the document; the value is pack-authored and therefore untrusted ([security-defaults.md](security-defaults.md)).
 
 ## Signing
 
-There is one signing scheme. `signing` on a version manifest (`schemas/v2/registry-version-manifest.schema.json`) is `{ keyId, scheme }`, both REQUIRED:
+There is one signing scheme. `signing` on a version manifest (`schemas/v2/registry-version-manifest.schema.json`) is the closed object `{ keyId, scheme }`, both REQUIRED:
 
-| Field | Rule |
-| --- | --- |
-| `scheme` | MUST be `ed25519-canonical-json`: a detached 64-byte Ed25519 signature over the RFC 8785 (JCS) bytes of `pack.json` inside a deterministic tarball; the input MUST satisfy `conformance.md` §"Canonical JSON" (RFC 0212) |
-| `keyId` | the signing key id; `publicKeyRef` does not exist |
-| `method` | does not exist; a manifest carrying it fails validation |
+- **`scheme`** MUST be `ed25519-canonical-json`: a detached 64-byte Ed25519 signature over the RFC 8785 (JCS) bytes of `pack.json` inside a deterministic tarball. The input MUST satisfy `conformance.md` §"Canonical JSON".
+- **`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, and the v1 `{ publicKeyRef, signatureRef, method }` block fails validation on every bare manifest kind (migration row `openwop.migration.C10.1`).
+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.
 
-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.
+- 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.
 
 ## Version manifests
 
-`kind` is REQUIRED on every version manifest and every bare manifest; the v1 "absent means `node`" reading does not exist. A deprecated version is flagged `versionDeprecated: true`; the registry continues to serve it and a consumer MAY refuse to install it.
+`kind` is REQUIRED on every version manifest and every bare manifest. A deprecated version is flagged `versionDeprecated: true`; the registry continues to serve it, and a consumer MAY refuse to install it.
 
 ## The registry's own schemas
 
@@ -87,3 +105,10 @@ A registry MUST validate submissions against vendored copies of these schemas pi
 | `pack_engine_unsupported` | the range does not admit the host's protocol major (install, every path) |
 | `pack_peer_dependency_undefined` | a peer-dependency key is not a declaration-file key or an overlap alias |
 | `pack_signature_invalid` | the signature, key, or namespace check fails |
+
+## During the v1 overlap
+
+- The v1 registry tree is frozen through the overlap, behind the v2 tree.
+- `testMode` advertises the v1 `/v1/packs-test/*` mirror, a conformance seam ([conformance.md §"The seams profile"](conformance.md)). It remains advertisable through the overlap and is removed at 3.0.
+
+*Sources: RFC 0177, RFC 0212.*

package/spec/v2/core/persistence.md

@@ -1,6 +1,6 @@
 # Persistence and Coexistence
 
-> **Status: Stable · RFC 0176 (§A–§B, §D–§E), 0171 §A, 0170 §A.3, 0158 §A–§D.**
+> **Status: Stable.**
 > **Normative home:** `eventLog`.
 
 ## Why this exists
@@ -9,11 +9,16 @@ How a v2 host reads what a v1 host wrote, what happens to a run in flight at the
 
 ## The codemap is data
 
-`spec/v2/event-codemap.json`, shipped in `@openwop/spec-artifacts`, is the only authority for the v1→v2 event-type mapping; every row is `decided` (RFC 0171 §A). 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, where "vendor-prefixed" means the first segment is an org registered in the `extensions` object of `spec/v2/declaration.json` (events.md §Rules; RFC 0171 §A.1 — `openwop.` is the only reserved prefix). An unregistered first segment is not a vendor prefix and falls to the refusal below. 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, because deregistering an org would convert every log already written under it from pass-through to refusal (RFC 0180).
+`spec/v2/event-codemap.json`, shipped in `@openwop/spec-artifacts`, is the only authority for the v1→v2 event-type mapping. Every row is `decided`.
+
+- 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.
 
 ## The era key
 
-`eventLogSchemaVersion` is the era key and is required on every run snapshot (`schemas/v2/run-snapshot.schema.json`).
+`eventLogSchemaVersion` is the era key. It is required on every run snapshot (`schemas/v2/run-snapshot.schema.json`).
 
 | Value | Meaning |
 | --- | --- |
@@ -24,112 +29,92 @@ How a v2 host reads what a v1 host wrote, what happens to a run in flight at the
 
 Discovery MUST advertise the value the host writes for new runs and nothing else; a host MUST hold one constant for this axis.
 
-**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.
+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.
 
-**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 therefore cannot falsify
-era handling on its own; the reader and writer rules below 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 field alone therefore cannot falsify era handling; the reader and writer rules carry the obligation.
 
 ## The `eventLog` family
 
-`eventLog` is the capability record by which a host advertises the era contract
-above. A host that advertises `eventLog` MUST stamp `eventLogSchemaVersion` on
-every run it creates, MUST serve the cursor contract in events.md §"Poll" over
-that log, and 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, which is why its
-floor scenarios are the era-key and cursor witnesses rather than tests of a
-surface of its own. Its `crossEngineOrdering` facet is a replay property and is
-normed in replay.md §"Cross-engine ordering".
+`eventLog` is the capability record by which a host advertises the era contract above. A host that advertises `eventLog`:
+
+- MUST stamp `eventLogSchemaVersion` on every run it creates;
+- 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 reader rule
 
 A v2 host reading a run in era `2` MUST translate every event through the codemap at the storage boundary:
 
-- `type` is mapped; the payload is projected per RFC 0171 §B.
+- `type` is mapped, and the payload projected with it.
 - `sequence` MUST be preserved verbatim, including `0`.
 - `eventId`, `timestamp`, `causationId`, and vendor fields pass through.
-- A type the codemap does not name and that carries no reserved vendor prefix MUST fail the read with `event_type_unmapped` (`spec/v2/errors.json`, `500`). A malformed row MUST fail the read rather than default any field.
+- A type the codemap does not name and that carries no reserved vendor prefix MUST fail the read with `event_type_unmapped` (`spec/v2/errors.json`, `500`).
+- A malformed row MUST fail the read rather than default any field.
+
+The rule binds every reader: poll, SSE, fork, replay divergence, debug bundle, summary memory.
 
-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; a background backfill that stamps `3` and rewrites `type` under the same `(runId, sequence)` key 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, RFC 0041 §C).
+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 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 the
-read with `event_type_unmapped` on a name the codemap does not carry on its v1
-side. A run created after the upgrade is era `3` and is written in v2
-vocabulary, untranslated.
+The era key is fixed when the run is created and fixes the log's vocabulary for the run's lifetime.
 
-A writer that emits a property a closed def cannot seat (RFC 0185 §B) MUST
-mark the row with what it could not seat, so the refusal names the writer
-instead of surfacing as an unexplained read failure (RFC 0187 §D.1).
+- 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 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.
 
-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`.
+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`.
 
 ### The v1 wire of an era-`3` log
 
-Through the overlap (`versioning.md` §5) an era-`3` log, stored in v2
-vocabulary, must still read on `/v1/…` exactly as before the cut.
+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:
 
-A host serving both majors MUST therefore map an era-`3` log's `type` back to
-its v1 spelling on the v1 read path, through the **same codemap row, inverted**.
-The inverse is exact only while `spec/v2/event-codemap.json` is a bijection; a
-host MUST verify that at load and, if a row folds two v1 names onto one v2 name,
-MUST refuse to serve the v1 representation rather than guess a spelling.
-
-A type with NO codemap row — v2-only vocabulary, anything RFC 0185/0186 seated
-— has no v1 spelling to invert to. A host MUST emit it unchanged on the v1 read
-path, MUST NOT drop the row, and MUST NOT refuse the read for it (RFC 0187
-§B.1).
+- 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 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
 
-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 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): discharged by that disclosure and by audit, never by the wire. The rule binds **every** reader, including the ones the suite has no name for; `run-event.schema.json` records why three 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; `run-event.schema.json` records why passing legs do not discharge it.
 
 ## Runs pinned to v1
 
 A non-terminal run a v2 host inherits carries `version.pinned` events naming change ids. The host MUST continue it or cancel it, never follow a pin silently.
 
-| Condition | Requirement |
-| --- | --- |
-| Every pinned change id is still implemented | The run MUST continue under the reader rule; the pin is honored verbatim and `version.pinned` is never rewritten. |
-| Any pinned change id is no longer implemented | The host MUST cancel the run with `run.cancelled` reason `v1_pin_unsupported` and `cancelledBy: "v2-cutover"`; the certification bundle reports the count. |
-| Suspended on an interrupt at the cut | The run continues under the row above; its token drains per §"Everything else a v1 host persisted". |
+- **Every pinned change id is still implemented** — the run MUST continue under the reader rule. The pin is honored verbatim and `version.pinned` is never rewritten.
+- **Any pinned change id is no longer implemented** — the host MUST cancel the run with `run.cancelled` reason `v1_pin_unsupported` and `cancelledBy: "v2-cutover"`. The certification bundle reports the count.
+- **Suspended on an interrupt at the cut** — the run continues under the rules above; its token drains per §"Everything else a v1 host persisted".
 
-"Drain" is retired as the only path. Multi-region skew is read-side only: after the cut a v2 region MUST NOT accept an era-`2` write for a run it has already stamped `3` (RFC 0176 §B.3). Discovery's `minClientVersion` rule is RFC 0172 row `C5.8`.
+Multi-region skew is read-side only: after the cut, a v2 region MUST NOT accept an era-`2` write for a run it has already stamped `3`. Discovery's `minClientVersion` rule is in [versioning.md §1.5](versioning.md).
 
 ## Everything else a v1 host persisted
 
-| Artifact | Requirement |
-| --- | --- |
-| 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). |
-| Webhook deliveries | Dual-emitted, and queued deliveries drained, per webhooks.md §"Dual emission through the overlap". |
-| 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). The rule is written over the prefix, never a segment count. |
-| 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). |
-| Owner stamps | A run without a Subject MUST be legacy-stamped at first v2 read and MUST NOT be rewritten later (RFC 0170 §A.3). A host's stored owner fields are projected to the Subject; the projection is the host's to name. |
-| Audit log | Never upgraded (RFC 0170). |
+- **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.
+- **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.
+- **Audit log** — never upgraded.
 
 ## Per-store disposition
 
-A host's ADR MUST name every store it persists and give each one disposition from the closed set below.
+A host's ADR MUST name every store it persists and give each one disposition from the closed set below. A host MUST NOT decide a store's disposition during the migration.
 
 | Disposition | Meaning |
 | --- | --- |
 | `unchanged` | Rows keep their shape and keys; a v2 reader consumes them as they are. |
-| `translated` | Rows are read through the codemap at the storage boundary; never rewritten in place except the atomic per-run backfill. |
-| `drained` | Rows complete under their own v1 contract until exhausted or expired; no new rows of the v1 shape are written. |
-| `legacy-stamped` | A missing v2 field is given its legacy value at first v2 read and never rewritten. |
+| `translated` | Read through the codemap at the storage boundary; rewritten in place only by the atomic per-run backfill. |
+| `drained` | Rows complete under their own v1 contract until exhausted or expired; no new v1-shaped rows are written. |
+| `legacy-stamped` | A missing v2 field gets its legacy value at first v2 read and is never rewritten. |
 | `never-upgraded` | Rows remain v1 evidence only; v2 evidence is produced fresh. |
 | `not-persisted` | Nothing to migrate. |
 
@@ -146,20 +131,16 @@ Template — one row per store:
 | certification bundles | v1 bundles | `never-upgraded` |
 | host-internal tables | outside the wire | `unchanged` |
 
-The reference hosts' dispositions are recorded in RFC 0176; a host MUST NOT decide a store's disposition during the migration.
-
 ## Durable acceptance and recovery
 
-RFC 0158 §A–§D.
+- **Acceptance** — a host that returns success for work it accepted MUST have made the intent to perform it durable in the same transaction as the work record. A wakeup, hint, or in-process dispatch MUST NOT be the only record. The host MUST resume accepted-but-unstarted work after the accepting process dies, without client action.
+- **Liveness** — a host MUST distinguish how long a unit of work may legitimately run from the interval in which a live worker demonstrates liveness, and MUST NOT use the duration bound as the sole liveness signal.
+- **Recovery bound** — a host MUST declare the longest interval between an instance ceasing to make progress and another becoming eligible to resume its work. It MUST derive the bound from the mechanism that enforces it: one bound per enforcing mechanism, never a single aggregate. Any length is conformant; an undeclared or unenforced bound is not.
+- **Duplicates** — duplicate delivery of accepted work MUST NOT produce duplicate external effects. The host MUST dedupe on an identity that survives redelivery ([idempotency.md](idempotency.md)).
+- **Poison work** — work that fails deterministically MUST reach a terminal, operator-visible state within a bounded number of attempts.
 
-| Clause | Requirement |
-| --- | --- |
-| Acceptance (§A) | A host that returns success for work it accepted MUST have made the intent to perform it durable in the same transaction as the work record; a wakeup, hint, or in-process dispatch MUST NOT be the only record. It MUST resume accepted-but-unstarted work after the accepting process dies, without client action. |
-| Liveness (§B.3) | A host MUST distinguish how long a unit of work may legitimately run from the interval in which a live worker demonstrates liveness, and MUST NOT use the duration bound as the sole liveness signal. |
-| Recovery bound (§B.4–6) | A host MUST declare the longest interval between an instance ceasing to make progress and another becoming eligible to resume its work, and MUST derive it from the mechanism that enforces it — one bound per enforcing mechanism, never a single aggregate. Any length is conformant; an undeclared or unenforced bound is not. |
-| Duplicates (§C.7) | Duplicate delivery of accepted work MUST NOT produce duplicate external effects; the host MUST dedupe on an identity that survives redelivery (idempotency.md). |
-| Poison work (§C.8) | Work that fails deterministically MUST reach a terminal, operator-visible state within a bounded number of attempts. |
+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)).
 
-A host MAY claim a qualification rung (`durable-single-instance`, `durable-multi-instance`, `multi-region-qualified`; cumulative) only with the evidence named for it, and MUST NOT claim one from tests in which no process was terminated (§D.9). A rung is evidence, not a capability: discovery carries none, and the rung and its bounds are published in the certification bundle (conformance.md §Bundle v3).
+See also: [overview.md](overview.md), [events.md](events.md), [replay.md](replay.md), [identity.md](identity.md), [webhooks.md](webhooks.md).
 
-See also: overview.md, events.md, replay.md, identity.md, webhooks.md.
+*Sources: RFC 0041, RFC 0158, RFC 0170, RFC 0171, RFC 0172, RFC 0176, RFC 0180, RFC 0185, RFC 0186, RFC 0187.*