OpenWOP — v2 spec corpus

Status: released. v2 is the current protocol major — v2.0.0 was tagged 2026-09-05 and this tree is at corpus v2.1.7 (release.json). Everything under spec/v2/, schemas/v2/ and api/v2/ is normative, is vendored into @openwop/spec-artifacts, and is what @openwop/openwop-conformance 2.x measures. A new integration targets v2.
v1 is not retired. Through the overlap a host advertises both majors and preferredVersion MUST remain a 1.x member (core/versioning.md §1.1); v1 clients keep working unchanged on /v1/…. v1 end-of-support is the later of two clocks in core/overview.md, earliest 2026-12-04, and until then spec/v1/ stays the maintained parallel track. A 1.x conformance tarball still excludes this tree (conformance/scripts/pack-vendor.sh).
The banner that stood here until 2026-09-10 said "in construction … until the v2.0.0-rc.1 corpus tag". That tag landed 2026-09-03 and the line was never updated; a reader who trusted it concluded v2 did not exist. Status lines that are hand-kept drift; this one now names the tag and the file that carry the truth.

Layout (RFC 0167 §C; RFC 0174 §E.2 budget):

Path	Owner	What
`declaration.json` (+ `declaration.schema.json`)	RFC 0169 §B	The one declaration file: every root key of the v2 discovery document with its anchor (`core`, `ext` or `deleted`), witness class, maturity, facets, peer-dependency identifier (≡ key), floor scenarios and requirement ids, and the profile predicates. Hand-reviewed source; everything else is generated from it (`scripts/generate-from-declaration.mjs`) and checked against it (`scripts/check-declaration.mjs`).
`profiles.json`, `peer-dependency-aliases.json`	RFC 0169 §C, RFC 0177 §B.2	Generated.
`errors.json` (→ generated `schemas/v2/error-envelope.schema.json`), `event-codemap.json` (all rows decided), `path-manifest.json` (operations + channels), `release.json` (the one release identity `info.version` reads), `facets/<key>.schema.json` (hand-decided facet shapes the capabilities generator reads)	RFC 0171, 0176, 0172, 0169	Landed P3-B/P3-C. `migrations.json` / `deprecations.json` stay at `spec/v1/` until the RC promotes them with `applied` marks (RFC 0167).
`core/*.md`	one per child	Normative prose, ≤ 25,000 words total (`scripts/check-core-budget.mjs`, `wc -w` on raw markdown, generated `core/headers.md` included). `capabilities.md` carries one `### § <key>` heading per core family (`check-declaration.mjs`). Lands in P3-D.
`ext/<key>/`	RFC 0169 §B.3, RFC 0175 §A.1, RFC 0173 §D	Extension documents with a declared `witness:` / `technical:` / `adoption:` header: the 13 ext-anchored families, plus `grpc-transport/` (demoted; non-normative proto), `portability/` (goals/export/import), `sandbox-runtime-notes/` (RFC 0035 history), `provider-idempotency/` (the Layer-2 provider registry).

Machine artifacts here are published in @openwop/spec-artifacts (RFC 0168 §D.2), never inside the suite tarball.

Start here

Five docs, in this order, ground everything else. New to the corpus? Read these top-to-bottom before browsing the thematic groups below.

01
OpenWOP v2 Core — Overview
The six axioms, the claim vocabulary, and the rule that decides what is core and what is an extension.
02
Discovery and Capabilities
One well-known resource, one closed capability record type, generated from the single declaration file.
03
Versioning and Release
How a major is negotiated (OpenWOP-Version), the version axes, and the one release identity a host reports.
04
Runs
The unit of execution: create, read, stream, cancel, pause, fork, diff — and the one snapshot every host projects.
05
Errors
One error registry; clients route on the code, never the message, and unregistered codes are not protocol errors.

Core

The normative front door a host implements to pass the 2.0.0 floor — discovery, versioning, runs, events, errors, and the pack families.

OpenWOP v2 Core — Overview Stable · v2.1.0 · 2026-09-11
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…
Discovery and Capabilities Stable · v2.1.0 · 2026-09-11
v1 discovery had 91 root properties on an open root, supported in four shapes, and four machine registries with no schema of their own. v2 has one capability record type on a…
Versioning and Release Stable · v2.1.0 · 2026-09-11
v1 negotiated on one scalar, could not advertise two majors, split engineVersion across two types, and presumed a /v2/ path space that the /v1/v1 defect already showed is the…
Runs Stable · v2.1.0 · 2026-09-11
A run is the unit of execution, ownership and observation. This document is the run surface of api/v2/openapi.yaml: how a run is created, read, streamed, cancelled, paused, forked…
Events Stable · v2.1.0 · 2026-09-11
A run is its append-only event log; every snapshot, stream, poll, fork and diff is a projection of it. v2 has one event envelope, one closed type registry with one naming rule,…
Errors Stable · v2.1.0 · 2026-09-11
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…
Headers Stable · v2.1.7 · 2026-09-13
RFC 0171 §C.1: every non-standard header is OpenWOP-<Name> and every header is declared in OpenAPI, so this table — generated from the same declaration — enumerates all of them. A…
Idempotency Stable · v2.1.0 · 2026-09-11
A retried request MUST NOT create a second run, and a retried node MUST NOT issue a second external effect. A host MUST implement Layer 1 for every mutating endpoint and Layer 2…
Identity Stable · v2.1.0 · 2026-09-11
v1 carried a principal beside an optional Subject, a legacy rule that was advisory, a SubjectLink with no schema, and resume tokens with no scheme. v2 makes the Subject the owner…
Interrupt Stable · v2.1.0 · 2026-09-11
interrupt is the one primitive by which a run waits for something outside itself: a human decision, an answer, an external event, a conversation turn. Every kind shares one…
Replay and Fork Stable · v2.1.0 · 2026-09-11
The event log makes any past state of a run reconstructible by folding events up to a sequence. POST /runs/{runId}:fork turns that into a wire surface: a replay proves that…
Persistence and Coexistence Stable · v2.1.0 · 2026-09-11
The v2 cut renames event types that are persisted, indexed, and unique-keyed in production stores, and fork and replay read those rows verbatim. This document states how a v2 host…
Webhooks Stable · v2.1.0 · 2026-09-11
Polling a run for progress is inefficient, and SSE cannot reach systems that need server-to-server delivery. A client registers a URL and an event filter once; the host POSTs…
Security Defaults Stable · v2.1.0 · 2026-09-11
v1 protected a tenant only when a host volunteered a boolean: fourteen auth-family flags, replay.sideEffectSuppression, webhooks.durable, interrupt.approverRouting, and…
Packs Stable · v2.1.0 · 2026-09-11
Every one of the 282 pack versions published under v1 either pins <2.0.0 or declares no ceiling at all, four peer-dependency grammars were signed into the registry, and two…
Connection Packs Stable · v2.1.0 · 2026-09-11
A connection pack is a signed provider definition — the endpoints, scope catalog, and reach a connector's auth.provider string resolves against. v1 let two definitions claim one…
Form Content Packs Stable · v2.1.0 · 2026-09-11
A form-content pack ships declarative form templates a host renders in its own chrome. v1 templates had no conditional visibility, no localization, and no validation beyond…
Workflow Chain Packs Stable · v2.1.0 · 2026-09-11
A workflow-chain pack ships a reusable fragment a host expands into a concrete definition, and may compose other chains as co-registered children. v1 left three lifecycle…
Interop Stable · v2.1.0 · 2026-09-11
v1 advertised a supportedTransports list that could only honestly say rest, carried two legacy embedded-protocol profiles with dated sunsets, and let an unauthenticated peer steer…
Conformance Stable · v2.1.0 · 2026-09-11
v1 could say a host passed and could not say what it witnessed: test ids were derived from titles, the witness class was recorded on extensions but not requirements, nine…

Extensions

Families that cannot be witnessed unaided live here (RFC 0167 Axiom 1) — advertised under extensions.<org>.<key>, never a core obligation.

a2uiSurface — extension Draft · v2.0.0-rc · 2026-09-03
RFC 0169 §C.5 (deltaTransport claims-check; ext/ unless a behavioral witness lands) The v1 prose that defines the surface is spec/v1/capabilities.md (root key a2uiSurface, RFC…
brand — extension Draft · v2.0.0-rc · 2026-09-03
RFC 0169 §B.3 (RFC 0144 extension class; prose-only §host. section in v1; served under extensions.openwop-app. by the one host that has it) The v1 prose that defines the surface…
canvas — extension Draft · v2.0.0-rc · 2026-09-03
RFC 0169 §B.3 (RFC 0144 extension class; prose-only §host. section in v1; served under extensions.openwop-app. by the one host that has it) The v1 prose that defines the surface…
chat — extension Draft · v2.0.0-rc · 2026-09-03
RFC 0169 §B.3 (RFC 0144 extension class; prose-only §host. section in v1; served under extensions.openwop-app. by the one host that has it) The v1 prose that defines the surface…
coordination — extension Draft · v2.0.0-rc · 2026-09-03
RFC 0169 §B.3 (RFC 0144 extension class; prose-only §host. section in v1; served under extensions.openwop-app. by the one host that has it) The v1 prose that defines the surface…
dataIntegration — extension Draft · v2.0.0-rc · 2026-09-03
RFC 0169 §B.3 (RFC 0144 extension class; prose-only §host. section in v1; served under extensions.openwop-app. by the one host that has it) The v1 prose that defines the surface…
entities — extension Draft · v2.0.0-rc · 2026-09-03
RFC 0169 §B.3 (RFC 0144 extension class; prose-only §host. section in v1; served under extensions.openwop-app. by the one host that has it) The v1 prose that defines the surface…
grpc-transport — extension (demoted) Draft · v2.0.0-rc · 2026-09-03
The v1 definition stands at spec/v1/grpc-transport.md for v1.x hosts.
kanban — extension Draft · v2.0.0-rc · 2026-09-03
RFC 0169 §B.3 (RFC 0144 extension class; prose-only §host. section in v1; served under extensions.openwop-app. by the one host that has it) The v1 prose that defines the surface…
knowledge — extension Draft · v2.0.0-rc · 2026-09-03
RFC 0169 §B.3 (RFC 0144 extension class; prose-only §host. section in v1; served under extensions.openwop-app. by the one host that has it) The v1 prose that defines the surface…
launchStudio — extension Draft · v2.0.0-rc · 2026-09-03
RFC 0169 §B.3 (RFC 0144 extension class; prose-only §host. section in v1; served under extensions.openwop-app. by the one host that has it) The v1 prose that defines the surface…
messaging — extension Draft · v2.0.0-rc · 2026-09-03
RFC 0169 §B.3 (RFC 0144 extension class; prose-only §host. section in v1; served under extensions.openwop-app. by the one host that has it) The v1 prose that defines the surface…
portability — extension (goals, export, import) Draft · v2.0.0-rc · 2026-09-03
provider-idempotency — extension (registry) Draft · v2.0.0-rc · 2026-09-03
restTransport — extension Draft · v2.0.0-rc · 2026-09-03
RFC 0169 §C.5 (claims-check; ext/ unless a behavioral witness lands) The v1 prose that defines the surface is spec/v1/capabilities.md (root key restTransport, RFC 0113); it stands…
sandbox-runtime-notes — extension (non-normative) Draft · v2.0.0-rc · 2026-09-03
webResearch — extension Draft · v2.0.0-rc · 2026-09-03
RFC 0169 §B.3 (RFC 0144 extension class; prose-only §host. section in v1; served under extensions.openwop-app. by the one host that has it) The v1 prose that defines the surface…