@openwop/spec-artifacts 2.42.7 → 2.42.9

package/schemas/v2/error-envelope.schema.json

@@ -135,82 +135,157 @@
       "minLength": 1
     },
     "details": {
-      "oneOf": [
-        {
-          "type": "object",
-          "required": [
-            "supported"
-          ],
-          "properties": {
-            "supported": {
-              "type": "array",
-              "minItems": 1,
-              "items": {
-                "type": "string",
-                "enum": [
-                  "values",
-                  "updates",
-                  "messages",
-                  "debug"
-                ]
-              },
-              "description": "Each individual mode the host serves; combinations are not listed (events.md §The events channel)."
-            }
-          },
-          "additionalProperties": true,
-          "x-openwop-error": "unsupported_stream_mode"
-        },
-        {
-          "type": "object",
-          "required": [
-            "runStatus"
-          ],
-          "properties": {
-            "runStatus": {
-              "type": "string",
-              "description": "The run status that refused the transition (runs.md §Pause and resume)."
-            }
-          },
-          "additionalProperties": true,
-          "x-openwop-error": "run_state_conflict"
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Error-specific contextual data. A code that registers a details schema in errors.json constrains it through the allOf below, selected by `error`; every other code accepts any object."
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "error": {
+            "const": "unsupported_stream_mode"
+          }
         },
-        {
-          "type": "object",
-          "additionalProperties": false,
-          "required": [
-            "type",
-            "keys"
-          ],
-          "properties": {
-            "type": {
-              "type": "string",
-              "description": "the event type whose payload could not be projected"
+        "required": [
+          "error"
+        ]
+      },
+      "then": {
+        "properties": {
+          "details": {
+            "type": "object",
+            "required": [
+              "supported"
+            ],
+            "properties": {
+              "supported": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                  "type": "string",
+                  "enum": [
+                    "values",
+                    "updates",
+                    "messages",
+                    "debug"
+                  ]
+                },
+                "description": "Each individual mode the host serves; combinations are not listed (events.md §The events channel)."
+              }
             },
-            "keys": {
-              "type": "array",
-              "items": {
-                "type": "string"
-              },
-              "minItems": 1,
-              "description": "the property names the host could neither carry nor seat"
+            "additionalProperties": true,
+            "x-openwop-error": "unsupported_stream_mode"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "error": {
+            "const": "run_state_conflict"
+          }
+        },
+        "required": [
+          "error"
+        ]
+      },
+      "then": {
+        "properties": {
+          "details": {
+            "type": "object",
+            "required": [
+              "runStatus"
+            ],
+            "properties": {
+              "runStatus": {
+                "type": "string",
+                "description": "The run status that refused the transition (runs.md §Pause and resume)."
+              }
             },
-            "eventId": {
-              "$ref": "ids.schema.json#/$defs/eventId"
+            "additionalProperties": true,
+            "x-openwop-error": "run_state_conflict"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "error": {
+            "const": "client_version_unsupported"
+          }
+        },
+        "required": [
+          "error"
+        ]
+      },
+      "then": {
+        "properties": {
+          "details": {
+            "type": "object",
+            "properties": {
+              "minClientVersion": {
+                "type": "string",
+                "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$",
+                "description": "OPTIONAL. The host's advertised minClientVersion, so a client refused at discovery learns the floor (versioning.md §1.5)."
+              }
             },
-            "sequence": {
-              "type": "integer",
-              "minimum": 0
-            }
-          },
-          "x-openwop-error": "payload_unprojectable"
+            "additionalProperties": true,
+            "x-openwop-error": "client_version_unsupported"
+          }
+        }
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "error": {
+            "const": "payload_unprojectable"
+          }
         },
-        {
-          "type": "object",
-          "additionalProperties": true
+        "required": [
+          "error"
+        ]
+      },
+      "then": {
+        "properties": {
+          "details": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "type",
+              "keys"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "description": "the event type whose payload could not be projected"
+              },
+              "keys": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                },
+                "minItems": 1,
+                "description": "the property names the host could neither carry nor seat"
+              },
+              "eventId": {
+                "$ref": "ids.schema.json#/$defs/eventId"
+              },
+              "sequence": {
+                "type": "integer",
+                "minimum": 0
+              }
+            },
+            "x-openwop-error": "payload_unprojectable"
+          }
         }
-      ]
+      }
     }
-  },
+  ],
   "x-openwop-http-status": {
     "connection_provider_unresolved": 400,
     "connector_action_unresolved": 400,

package/spec/v1/alias-detectors.json

@@ -308,6 +308,12 @@
       "file": "spec/v2/declaration.json",
       "token": "\"deltaTransport\"",
       "deprecation": "openwop.deprecation.v2-a2ui-delta-transport-facet"
+    },
+    {
+      "alias": "optional `locale` on InterruptPayload.data and the resume payload",
+      "file": "spec/v1/i18n.md",
+      "token": "## `locale` field on `InterruptPayload`",
+      "deprecation": "openwop.deprecation.interrupt-locale-field"
     }
   ]
 }

package/spec/v1/core-standard-manifest.json

@@ -4,7 +4,7 @@
   "provenance": {
     "suite": {
       "package": "@openwop/openwop-conformance",
-      "version": "2.42.7"
+      "version": "2.42.9"
     },
     "note": "Derived from the corpus at generation time. Regenerate with --write; verify with --check."
   },
@@ -421,5 +421,5 @@
       "$id": "https://openwop.dev/spec/v1/workspace-file.schema.json"
     }
   ],
-  "digest": "2da5e56166f26214299fff10d28db4e2c2d0c5e42f81aebcc20d66dc9a28c3c0"
+  "digest": "fb4145362ce7b57ba7e06e742acac2800106bb12e863f6eb6d2dc9dd2f50cb6c"
 }

package/spec/v1/deprecations.json

@@ -1002,6 +1002,28 @@
           "token": "deltaTransport"
         }
       ]
+    },
+    {
+      "id": "openwop.deprecation.interrupt-locale-field",
+      "status": "deprecated",
+      "surface": "optional `locale` field on `InterruptPayload.data` and on the interrupt resume payload",
+      "kind": "schema-field",
+      "deprecatedIn": "RFC 0171 §Migration table row `openwop.migration.C4.17` (v2 closes interrupt data and resume bodies)",
+      "authority": "RFCS/0171-v2-wire-envelope.md §Migration table, row openwop.migration.C4.17",
+      "removeIn": "2.0",
+      "replacement": "none; the locale a host rendered in is request-scoped (`Content-Language`, spec/v2/core/i18n.md)",
+      "codemod": "openwop.codemod.interrupt-locale-drop",
+      "sources": [
+        {
+          "file": "RFCS/0171-v2-wire-envelope.md",
+          "token": "openwop.migration.C4.17"
+        },
+        {
+          "file": "spec/v1/i18n.md",
+          "token": "`locale` field on `InterruptPayload`"
+        }
+      ],
+      "removalTrigger": "v2.0-cut"
     }
   ]
 }

package/spec/v1/gaps.json

@@ -1,7 +1,7 @@
 {
   "$schema": "./gaps.schema.json",
   "version": 1,
-  "updated": "2026-09-27",
+  "updated": "2026-09-28",
   "witnessClasses": [
     "witnessable-unaided",
     "witnessable-gated",
@@ -12923,8 +12923,8 @@
       "surface": "Two of the three certified hosts read a malformed value as `0.0` and refuse it (`openwop-examples` v2 reference host `router.ts`, openwop-app `protocolVersion.ts`). Under §C.2 both fail the planned `malformed-not-refused` leg.",
       "witness": "unclassified",
       "requirementId": null,
-      "disposition": "transferred",
-      "target": "rfc-0219",
+      "disposition": "closed",
+      "target": null,
       "sources": [
         {
           "file": "RFCS/registers/0219-client-version-header.gaps.md",
@@ -12940,8 +12940,8 @@
       "surface": "Whether the value names the corpus release the client implements (this RFC) or a product version (v1's `openwop-sdk/<v>`).",
       "witness": "unclassified",
       "requirementId": null,
-      "disposition": "transferred",
-      "target": "rfc-0219",
+      "disposition": "closed",
+      "target": null,
       "sources": [
         {
           "file": "RFCS/registers/0219-client-version-header.gaps.md",
@@ -12974,8 +12974,8 @@
       "surface": "`client_version_unsupported` has `details: null`. Two hosts send `details.minClientVersion`, MyndHyve sends none.",
       "witness": "unclassified",
       "requirementId": null,
-      "disposition": "transferred",
-      "target": "spec/v2/core/errors.md",
+      "disposition": "closed",
+      "target": null,
       "sources": [
         {
           "file": "RFCS/registers/0219-client-version-header.gaps.md",
@@ -12991,8 +12991,8 @@
       "surface": "The header's meaning on a `/v1/…` path during the overlap. The reference host applies the floor there; openwop-app does not.",
       "witness": "unclassified",
       "requirementId": null,
-      "disposition": "transferred",
-      "target": "rfc-0219",
+      "disposition": "closed",
+      "target": null,
       "sources": [
         {
           "file": "RFCS/registers/0219-client-version-header.gaps.md",
@@ -13068,6 +13068,23 @@
         }
       ]
     },
+    {
+      "id": "openwop.gap.0221.1",
+      "rfc": "0221",
+      "local": "G1",
+      "section": "§Implementation notes",
+      "surface": "MyndHyve's behaviour for a secret-less registration is unmeasured.",
+      "witness": "unclassified",
+      "requirementId": null,
+      "disposition": "externally-gated",
+      "target": "myndhyve-next-cut",
+      "sources": [
+        {
+          "file": "RFCS/registers/0221-generated-webhook-secret-returned-once.gaps.md",
+          "token": "G1"
+        }
+      ]
+    },
     {
       "id": "openwop.gap.spec.a2a-integration.g1",
       "rfc": "0152",

package/spec/v1/migrations.json

@@ -1038,6 +1038,24 @@
       "deprecationId": null,
       "note": "Envelopes are transient; a persisted envelope.* event is read through the adapter."
     },
+    {
+      "id": "openwop.migration.C4.17",
+      "child": "C4",
+      "kind": "remove",
+      "v1": {
+        "surface": "optional `locale` on `InterruptPayload.data` and on the resume payload (i18n.md §\"`locale` field on `InterruptPayload`\")",
+        "path": "spec/v1/i18n.md"
+      },
+      "v2": {
+        "surface": "none — interrupt data and resume bodies are closed; the rendered locale is request-scoped (`Content-Language`, spec/v2/core/i18n.md)"
+      },
+      "codemod": "openwop.codemod.interrupt-locale-drop",
+      "persistedData": "translated",
+      "requirementIds": [],
+      "gapIds": [],
+      "deprecationId": "openwop.deprecation.interrupt-locale-field",
+      "note": "Recorded 2026-09-27: the v2 schema closure (C4.9) left the v1 field no place, and it is dropped rather than re-added. A v1 `interrupt.requested` event carrying `data.locale` is read through the C.9 adapter like any other extra key."
+    },
     {
       "id": "openwop.migration.C6.1",
       "child": "C6",

package/spec/v2/README.md

@@ -30,9 +30,9 @@ when v1 ends.
 
 | Area | Documents |
 | --- | --- |
-| Foundation | [`overview`](./core/overview.md), [`versioning`](./core/versioning.md), [`headers`](./core/headers.md), [`identity`](./core/identity.md), [`oauth`](./core/oauth.md), [`capabilities`](./core/capabilities.md) |
+| Foundation | [`overview`](./core/overview.md), [`versioning`](./core/versioning.md), [`headers`](./core/headers.md), [`identity`](./core/identity.md), [`oauth`](./core/oauth.md), [`capabilities`](./core/capabilities.md), [`i18n`](./core/i18n.md) |
 | Execution | [`runs`](./core/runs.md), [`events`](./core/events.md), [`interrupt`](./core/interrupt.md), [`conversation`](./core/conversation.md), [`persistence`](./core/persistence.md), [`idempotency`](./core/idempotency.md), [`replay`](./core/replay.md) |
-| Integration | [`webhooks`](./core/webhooks.md), [`interop`](./core/interop.md), [`host services`](./core/host-services.md), [`tool catalog`](./core/tool-catalog.md), [`packs`](./core/packs.md), [`node-pack runtimes`](./core/node-pack-runtimes.md), [`connection packs`](./core/connection-packs.md), [`form-content packs`](./core/form-content-packs.md), [`workflow-chain packs`](./core/workflow-chain-packs.md) |
+| Integration | [`webhooks`](./core/webhooks.md), [`interop`](./core/interop.md), [`host services`](./core/host-services.md), [`tool catalog`](./core/tool-catalog.md), [`portability`](./core/portability.md), [`packs`](./core/packs.md), [`node-pack runtimes`](./core/node-pack-runtimes.md), [`connection packs`](./core/connection-packs.md), [`form-content packs`](./core/form-content-packs.md), [`workflow-chain packs`](./core/workflow-chain-packs.md) |
 | Reliability | [`errors`](./core/errors.md), [`security defaults`](./core/security-defaults.md), [`conformance`](./core/conformance.md) |
 
 ## Source-of-truth map

package/spec/v2/core/errors.md

@@ -19,7 +19,7 @@ Every error a v2 host returns is a row in one registry. A client routes on `erro
 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 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`.
+- `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 applies it to `details` only when `error` names that code.
 - 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.
 

package/spec/v2/core/form-content-packs.md

@@ -26,7 +26,7 @@ A form instantiated from a pack advertised through `forms.contentPacks` MUST be
 
 ## Localized strings
 
-`label`, `title`, and `description` are localized strings. A host MUST select the rendered language by the locale-selection and fallback rules of `spec/v1/i18n.md`, the `i18n` family's normative text in `spec/v2/declaration.json`, and MUST treat every rendered string as untrusted: escaped for the target surface, never interpreted as markup, script, or a template directive.
+`label`, `title`, and `description` are localized strings. A host MUST select the rendered language by the locale-selection and fallback rules of [i18n.md](i18n.md), and MUST treat every rendered string as untrusted: escaped for the target surface, never interpreted as markup, script, or a template directive.
 
 ## Validation
 

package/spec/v2/core/headers.md

@@ -16,9 +16,10 @@ Standard headers keep their standard names: `Idempotency-Key`, `ETag`, `If-None-
 | `Idempotency-Key` | 15 | Per-mutation idempotency token (`idempotency.md` Layer 1). The server caches `(tenantId, endpoint, key)` → response for ≥24h. A duplicate request returns the cached response with `OpenWOP-Idempotent-Replay: true`. |
 | `If-None-Match` | 2 | Conditional request on the discovery document (capabilities.md §1) and the run snapshot (runs.md §Snapshot). A value matching the `ETag` the host sent MUST yield `304 Not Modified` with no body. The 304 carries `OpenWOP-Version` like every response (versioning.md §1.4). |
 | `Last-Event-ID` | 1 | Resume from sequence after this ID. |
+| `OpenWOP-Client-Version` | 55 | The protocol version the client implements (versioning.md §1.5). Compared with `minClientVersion` on major.minor. A malformed value is treated as absent and MUST NOT produce a 400. Never selects a contract. |
 | `OpenWOP-Dedup` | 1 | When set, the host's cross-host claim system rejects a duplicate `(tenantId, scopeId)` pair with `409 Conflict`. |
 | `OpenWOP-Force-Engine-Version` | 1 | Test keys only. The server emits this run's events as if it ran the given engine version, which must be within `Capabilities.testing.forceEngineVersionRange`. Servers MUST reject it on production API keys with `403 force_engine_version_forbidden`. |
-| `OpenWOP-Version` | 55 | Selects one of the host's listed major.minor versions. Absent, the host uses its `preferredVersion`; an unlisted value is 406 protocol_version_unsupported. |
+| `OpenWOP-Version` | 55 | Selects one of the host's listed major.minor versions. Absent, `/.well-known/openwop` uses `preferredVersion` and every other unversioned path is v2; an unlisted value is 406 protocol_version_unsupported. |
 
 ## Response headers
 

package/spec/v2/core/i18n.md

@@ -0,0 +1,64 @@
+# Internationalization
+
+> **Status: Stable.**
+> **Normative home:** `i18n`.
+
+## Why this exists
+
+A host renders some text for humans: interrupt prompts, error messages, extension UI strings. This document states how a client asks for a locale and how a host answers. Machine-readable identifiers stay ASCII, dates and times stay ISO 8601, and number, currency and text-direction formatting are out of scope.
+
+## Language tags
+
+Every locale identifier — `Accept-Language`, `Content-Language` and every `locale` field — is a [BCP 47](https://www.rfc-editor.org/rfc/rfc5646) tag.
+
+- Tags compare case-insensitively (RFC 5646 §2.1.1, RFC 4647 §2).
+- A host SHOULD advertise and emit tags in the case RFC 5646 §2.1.1 recommends: lowercase language, titlecase script, uppercase region (`zh-Hant-TW`, `es-419`).
+
+## `Accept-Language`
+
+A client MAY send `Accept-Language` ([RFC 9110 §12.5.4](https://www.rfc-editor.org/rfc/rfc9110#section-12.5.4)) on any request. A host MAY honor it to localize human-facing text in the response.
+
+A host:
+
+- MUST parse the header without failing the request. A malformed value MUST NOT cause `400`; the host uses its default locale and proceeds.
+- MUST NOT reject a request because it does not support the requested locale.
+- MUST honor q-values: the highest-q locale it supports wins, and ties go to request order.
+- MUST NOT infer a locale from the request body to override the header, which is authoritative.
+- SHOULD set `Content-Language` to the canonical tag of the locale used when it localized the response. When it localized nothing, it SHOULD omit `Content-Language` or set it to its default locale.
+- MAY cache localized text. When localization is expensive, caching by `(localeTag, sourceText)` is RECOMMENDED.
+- MAY return default-locale text at once and emit `node.completed` when the localized version is ready. This is discouraged for an interrupt prompt, which a human needs localized now.
+
+## Fallback
+
+When a host cannot localize to the requested locale, it:
+
+1. walks the list in q-value order and uses the first locale it supports;
+2. otherwise tries the language family: asked for `ja-JP` and holding only `ja`, it uses `ja` and sets `Content-Language: ja`;
+3. otherwise uses its default locale, which it SHOULD advertise as `i18n.defaultLocale`;
+4. sets `Content-Language` to the locale it actually used, never another.
+
+## Error envelopes
+
+A host MAY localize an error `message`, and MAY then add `details.locale`.
+
+- The `error` code MUST be the same registered identifier in every locale ([errors.md](errors.md)); it is never translated.
+- `details` keys are schema field names and are not localized.
+- A human-facing `details` value MAY be localized, and SHOULD carry a `locale` sibling on the same object.
+
+## The `i18n` record
+
+A host that negotiates locale SHOULD advertise `i18n`. A host advertising it honors `Accept-Language` on every protected route; a host that omits it serves one locale.
+
+- **`defaultLocale`** — the locale returned when no `Accept-Language` entry matches `supportedLocales`; `"en"` when omitted.
+- **`supportedLocales`** — the locales the host can return for human-facing text. It MUST contain `defaultLocale`, and its order carries no meaning.
+- A host that translates by machine SHOULD list only the locales it has validated end to end.
+
+## Replay and fork
+
+Locale is chosen at request time. `Content-Language` is request-scoped and not recorded in the event log, so a replay re-projects the recorded text and does not re-render it. A fork localizes by its own request's `Accept-Language`, not the parent run's.
+
+## Clients
+
+A client that wants localized content MUST check discovery for `i18n` before sending `Accept-Language`. A host that does not advertise it ignores the header and returns its default locale.
+
+*Sources: RFC 0206.*

package/spec/v2/core/identity.md

@@ -179,7 +179,7 @@ Every id field in every v2 schema and every `api/v2/openapi.yaml` parameter and
 - A host MUST reject a tenant-bound id whose tenant segment is not the caller's with `403` `id_tenant_mismatch`.
 - A host-minted opaque segment MUST match `^[A-Za-z0-9._~-]{16,128}$`.
 - Ids in documents and bodies are bound, always. A client MAY bind at its request seam.
-- Handle grammars (`memoryRef`, workspace `path`/`etag`, the plugin version token) and their `resolvability` class are specified where each handle is used. An importer MUST re-mint every `host`-scoped handle ([capabilities.md § portability](capabilities.md)).
+- Handle grammars (`memoryRef`, workspace `path`/`etag`, the plugin version token) and their `resolvability` class are specified where each handle is used. An importer MUST re-mint every `host`-scoped handle ([portability.md](portability.md)).
 
 ### Wire form
 

package/spec/v2/core/overview.md

@@ -16,7 +16,7 @@
 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
+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), [`i18n.md`](i18n.md), [`portability.md`](portability.md) — surface obligations, signatures, A2A and MCP, host services, locale, estate export
 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
 

package/spec/v2/core/portability.md

@@ -0,0 +1,44 @@
+# Portability
+
+> **Status: Stable.**
+> **Normative home:** `portability`.
+
+## Why this exists
+
+A tenant's reusable estate moves between hosts as one export bundle, and lands on the destination under the importing caller's identity. This document states the bundle and the rules an importer follows. An adapter that turns another platform's export into a bundle is host tooling.
+
+## The export bundle
+
+An `ExportBundle` (`schemas/v2/export-bundle.schema.json`) carries `bundleVersion: "2"`, a `source` (its origin and an informational `originPrincipal`) and `items[]`. Each item has:
+
+- a `kind`: `agent`, `pack`, `prompt-template`, `connection-ref`, `schedule`, `roster` or `org-chart`;
+- a bundle-local `ref` and optional `dependsOn` edges;
+- a `payload` shaped by that kind's own schema.
+
+## The `portability` record
+
+- **`export`** — the host emits a bundle for the caller's tenant or workspace, optionally limited to some `kinds`.
+- **`import`** — the host applies a bundle.
+- **`kinds`** — the item kinds the host exports and imports.
+- **`dryRun`** — import offers a plan preview that writes nothing. A host advertising `import` MUST advertise `dryRun: true`.
+
+## Import rules
+
+- **No credential material.** A bundle MUST NOT contain credential values: a `connection-ref` item carries only references and provider ids. The importer MUST report unbound references in `secretsToRebind` and MUST NOT invent or transfer secret material. A host MUST reject with `422` an imported bundle whose payload carries a literal credential value.
+- **Dry run.** When `import` is advertised, import MUST offer a dry run. A dry run MUST NOT write, and MUST return the plan it would execute: creates, updates, skips, conflicts and unbound credential references.
+- **Idempotent.** Import MUST be idempotent: re-applying a bundle resolves each item to `skipped` or `updated`, never to a duplicate create.
+- **Ordered.** Items MUST be applied in `dependsOn` topological order. A cycle is a `422`.
+- **Re-owned.** Every imported entity MUST be re-owned to the caller's Subject at the destination ([identity.md](identity.md) §1). `source.originPrincipal` is informational and MUST NOT grant any access. Host-scoped handles are re-minted as [identity.md](identity.md) §5 requires.
+- **Executable behavior.** An imported agent or pack that is executable behavior SHOULD pass through the host's install policy ([RFC 0043](https://github.com/openwop/openwop/blob/main/RFCS/0043-registry-and-extension-policy.md)), and MAY be staged as a proposal ([RFC 0096](https://github.com/openwop/openwop/blob/main/RFCS/0096-reviewable-learning-skill-proposal-lifecycle.md)) instead of being activated.
+
+Applying an import returns an outcome per item — `created`, `updated`, `skipped` or `failed` — plus `secretsToRebind`.
+
+## The `import.applied` event
+
+An applied import emits `import.applied` (`schemas/v2/run-event-payloads.schema.json`). A host MUST NOT emit it unless it advertises `portability`. It carries counts and references only, never item payloads or secret values.
+
+## Routes
+
+No protocol path is defined for export or import: a host serves them on routes of its own. A host-private migration from an anonymous sandbox into a signed-in tenant fits this contract, because its response is a subset of the import outcome.
+
+*Sources: RFC 0043, RFC 0096, RFC 0098.*

package/spec/v2/core/runs.md

@@ -16,7 +16,7 @@ Every id `$ref`s `schemas/v2/ids.schema.json` ([identity.md](identity.md)). A `r
 
 ## Surface
 
-Every operation accepts `OpenWOP-Version` ([overview.md](overview.md)) and every response carries it. Every mutating operation accepts `Idempotency-Key` ([idempotency.md](idempotency.md)). Scopes are the `auth.md` vocabulary.
+Every operation accepts `OpenWOP-Version` ([overview.md](overview.md)) and every response carries it. Every mutating operation accepts `Idempotency-Key` ([idempotency.md](idempotency.md)). Scopes are the vocabulary listed in `api/v2/openapi.yaml`'s security schemes, matched as [identity.md](identity.md) §2.1 describes.
 
 | Operation | Method and path | Scope | Gate |
 | --- | --- | --- | --- |

package/spec/v2/core/versioning.md

@@ -43,9 +43,12 @@ A request on an unversioned path MAY carry `OpenWOP-Version: <major>` or `OpenWO
 | --- | --- |
 | Header names a major in `protocolVersions[]` | MUST serve that major |
 | Header names a major not in `protocolVersions[]` | MUST answer `406` `protocol_version_unsupported`, with `details.protocolVersions[]` echoing the list |
-| Header absent on an unversioned path | MUST serve `preferredVersion`'s major |
+| Header absent on `/.well-known/openwop` | MUST serve `preferredVersion`'s major |
+| Header absent on any other unversioned path | MUST serve major 2: the path is the v2 surface (§1.2) |
 | `/v1/…` path with `OpenWOP-Version` other than `1` | MUST answer `400` `protocol_version_mismatch` |
 
+`/.well-known/openwop` is the one resource both majors serve at the same unversioned path, so it is the only place a header-less request can come from a client of the earlier major.
+
 A request on a `/v1/…` path key MUST NOT carry `OpenWOP-Version` with a value other than `1`. `protocol_version_unsupported`, `protocol_version_mismatch` and `client_version_unsupported` (§1.5) are rows in `spec/v2/errors.json` ([errors.md](errors.md)).
 
 ### 1.4 The response header
@@ -75,10 +78,26 @@ Otherwise the page MUST move off the shared name.
 
 When both majors are advertised, a v2 client MUST select the highest major it implements that the host lists. A v1 client (no header, `/v1/` paths) is unaffected.
 
+A client announces the protocol version it implements in the `OpenWOP-Client-Version` request header, as `<major>.<minor>` or `<major>.<minor>.<patch>` (non-negative integers, no leading zeros). The value is the corpus release the client is built against (§4), not an SDK or product version.
+
+- A client SHOULD send it on every request under major 2.
+- The header is optional on every operation and never selects a major (§1.3). A host MUST NOT choose a major or a representation from it.
+- A host MUST NOT refuse a request because it omits the header or sends a malformed value.
+- A value outside the grammar MUST be treated as absent, and MUST NOT produce a `400`.
+- The value is the client's claim. A host MUST NOT use it as an authentication or authorization input.
+
 `minClientVersion` (axis 15) is optional. When a host advertises it:
 
 - It MUST use the axis-1 grammar.
-- A host MAY refuse a client below it. A refusal MUST be `426` `client_version_unsupported`.
+- A client is below it when the client's major and minor, compared as integers, are less than the floor's. The patch never decides.
+- A host MAY refuse a client below it. A refusal MUST be `426` `client_version_unsupported`, and MAY carry `details.minClientVersion` naming the floor ([errors.md](errors.md)).
+- The discovery document is not exempt: a client refused there learns the floor from `details.minClientVersion`.
+
+A host MUST NOT answer `426` `client_version_unsupported` to a request that does not carry a well-formed `OpenWOP-Client-Version` below its advertised `minClientVersion`.
+
+This header rule binds requests served under major 2. A request served under major 1 follows that major's frozen text.
+
+Open gap: RFC 9110 §15.5.22 requires an `Upgrade` header on every `426`. This floor departs from it, and no `Upgrade` value is defined yet.
 
 ## 2. The 18 version axes
 
@@ -173,4 +192,4 @@ Every vendor namespace — capability records ([capabilities.md](capabilities.md
 
 Rows `C5.1`–`C5.9` are `spec/v1/migrations.json` entries (`C5.2` is owned by `events.md`). The persisted-data disposition for each is `not-persisted`, except `C5.1` (legacy-stamped) and `C5.7` (never-upgraded).
 
-*Sources: RFC 0167, RFC 0168, RFC 0172, RFC 0176, RFC 0179, RFC 0181, RFC 0193.*
+*Sources: RFC 0167, RFC 0168, RFC 0172, RFC 0176, RFC 0179, RFC 0181, RFC 0193, RFC 0219.*