@openwop/openwop-conformance 1.25.0 → 1.28.0

package/schemas/capabilities.schema.json

@@ -2052,6 +2052,32 @@
       },
       "additionalProperties": false
     },
+    "content": {
+      "type": "object",
+      "description": "RFC 0103 (spec/v1/localized-content.md). Localized authored content (pages → sections) advertisement. Reuses the i18n annex's Accept-Language/Content-Language negotiation; it does NOT redeclare negotiation. Requires `i18n.supported: true`. `baseLocale` MUST equal `capabilities.i18n.defaultLocale`; `({baseLocale} ∪ supportedLocales)` MUST be a subset of `capabilities.i18n.supportedLocales`; `baseLocale` MUST NOT appear in `supportedLocales`. Hosts that omit this block serve no content surface; the conformance scenarios skip cleanly.",
+      "additionalProperties": false,
+      "required": ["supported", "baseLocale", "supportedLocales"],
+      "properties": {
+        "supported": {
+          "type": "boolean",
+          "description": "Host serves the localized-content surface (`GET /v1/content/pages/{slug}` + tenant-scoped admin CRUD). Requires `i18n.supported: true`."
+        },
+        "baseLocale": {
+          "type": "string",
+          "pattern": "^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8}){0,3}$",
+          "description": "The locale section `data` is authored in. MUST equal `capabilities.i18n.defaultLocale`."
+        },
+        "supportedLocales": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8}){0,3}$"
+          },
+          "description": "BCP 47 tags the host has authored content translations for. MUST NOT contain `baseLocale`; `({baseLocale} ∪ supportedLocales)` MUST be a subset of `i18n.supportedLocales`."
+        }
+      }
+    },
     "portability": {
       "type": "object",
       "description": "RFC 0098 (`Active`). Export/import of a tenant's reusable estate (agents 0070, packs 0003/0013, prompt templates 0027, connection *refs* 0045/0095, schedules 0052, roster/org-chart 0086/0087). An export bundle carries NO credential values — only refs to be re-bound at the destination (RFC 0046/0079). Import maps the estate onto the destination's RFC 0048 identity, MUST offer a no-write dry-run plan, MUST be idempotent, and is gated by an RFC 0049 scope. A host advertising this serves `/v1/host/sample/{export,import}` (promotable to `/v1/{export,import}`) and emits the content-free `import.applied` event. Hosts that omit this block neither export nor import; the conformance scenarios skip cleanly.",
@@ -2081,6 +2107,29 @@
       },
       "if": { "properties": { "import": { "const": true } }, "required": ["import"] },
       "then": { "properties": { "dryRun": { "const": true } }, "required": ["dryRun"] }
+    },
+    "interrupt": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "RFC 0104 (`Active`). Interrupt-surface capabilities. Currently advertises portable HITL approver routing on the `kind: \"approval\"` InterruptPayload.",
+      "properties": {
+        "approverRouting": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["supported"],
+          "description": "RFC 0104. When `supported: true`, the host surfaces the OPTIONAL, ADVISORY `approverGroupRefs` / `approverRoleRefs` / `audience` fields on the approval InterruptPayload unchanged, resolves the ref kinds it advertises against its own identity/RBAC, ENFORCES eligibility at resolve time (the refs stay advisory metadata for clients; enforcement is host-side), and SHOULD route notifications to the resolved union. Refs are opaque to the engine and snapshotted at decision time for deterministic replay. Hosts that omit this block (or set `supported: false`) ignore the fields and remain conformant. Advertise only what the host actually resolves (`refKinds`) and honors (`audience`).",
+          "properties": {
+            "supported": { "type": "boolean", "description": "Host honors the RFC 0104 approver-routing fields." },
+            "refKinds": {
+              "type": "array",
+              "items": { "type": "string", "enum": ["group", "role"] },
+              "uniqueItems": true,
+              "description": "Which approver ref kinds the host actually resolves. `group` ⇒ honors `approverGroupRefs`; `role` ⇒ honors `approverRoleRefs`. Absent ⇒ the host resolves neither (advisory-only passthrough). Capability honesty: advertise only the kinds the host's resolver supports."
+            },
+            "audience": { "type": "boolean", "default": false, "description": "Host honors the `audience` notification-targeting override. Absent/`false` ⇒ the host notifies the resolved eligible union and ignores `audience`." }
+          }
+        }
+      }
     }
   },
   "additionalProperties": true

package/schemas/envelopes/ui.a2ui-surface.schema.json

@@ -0,0 +1,154 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/envelopes/ui.a2ui-surface.schema.json",
+  "title": "UiA2uiSurfacePayload",
+  "description": "Payload for the OPTIONAL, advertised `ui.a2ui-surface` AI Envelope kind (RFC 0102). Carries a declarative A2UI interface surface — a closed component tree the consumer renders with native widgets, routing user actions back to the producing agent WITHOUT executing any agent-supplied code. `ui.*` is a core, un-namespaced content-primitive family beside `media.*` (ai-envelope.md §\"A2UI surfaces\" / §\"Vendor-namespaced kinds\"). Not one of the four MUST-recognize universal kinds; an unrecognizing consumer falls back to store-without-render.",
+  "type": "object",
+  "required": ["catalogVersion", "surface"],
+  "additionalProperties": false,
+  "properties": {
+    "reasoning": {
+      "type": "string",
+      "description": "OPTIONAL per RFC 0030 §A — the model's reasoning, conventionally the first property of a kind whose payload benefits from multi-step composition."
+    },
+    "catalogVersion": {
+      "type": "string",
+      "enum": ["0.9.1"],
+      "description": "REQUIRED — the A2UI catalog version the surface targets. This enum IS the host's supported-version set (ai-envelope.md §\"A2UI surfaces\"); it is never a free string the producer invents. A consumer MUST refuse an unknown/higher version with `unknown_schema_version`. Pinning the version in the payload keeps `:fork`/replay deterministic after the external A2UI standard ships a breaking version."
+    },
+    "surface": {
+      "$ref": "#/$defs/surface",
+      "description": "REQUIRED — the A2UI surface document: a closed component tree (ai-envelope.md §\"A2UI surfaces\"). Self-contained: renderable from the payload alone, never a live reference into an external catalog."
+    }
+  },
+  "$defs": {
+    "surface": {
+      "type": "object",
+      "required": ["components"],
+      "additionalProperties": false,
+      "properties": {
+        "title": {
+          "type": "string",
+          "description": "OPTIONAL display title for the surface."
+        },
+        "components": {
+          "type": "array",
+          "description": "The flat, ordered component list. Each element is one of the host's day-1 catalog components, discriminated by the single-string-enum `component` field. `anyOf` (not `oneOf`) per ai-envelope.md §\"Schema discipline\".",
+          "items": { "$ref": "#/$defs/component" }
+        }
+      }
+    },
+    "component": {
+      "description": "A single A2UI component. Closed set (day-1 catalog 0.9.1); the `component` discriminator is a single-string-enum per branch.",
+      "anyOf": [
+        { "$ref": "#/$defs/heading" },
+        { "$ref": "#/$defs/text" },
+        { "$ref": "#/$defs/fieldText" },
+        { "$ref": "#/$defs/fieldDate" },
+        { "$ref": "#/$defs/fieldSelect" },
+        { "$ref": "#/$defs/fieldCheckbox" },
+        { "$ref": "#/$defs/actionButton" }
+      ]
+    },
+    "heading": {
+      "type": "object",
+      "required": ["component", "text"],
+      "additionalProperties": false,
+      "properties": {
+        "component": { "type": "string", "enum": ["heading"] },
+        "text": { "type": "string" },
+        "level": { "type": "integer", "minimum": 1, "maximum": 6 }
+      }
+    },
+    "text": {
+      "type": "object",
+      "required": ["component", "text"],
+      "additionalProperties": false,
+      "properties": {
+        "component": { "type": "string", "enum": ["text"] },
+        "text": { "type": "string" }
+      }
+    },
+    "fieldText": {
+      "type": "object",
+      "required": ["component", "id", "label"],
+      "additionalProperties": false,
+      "properties": {
+        "component": { "type": "string", "enum": ["field.text"] },
+        "id": { "type": "string", "description": "Binding key; the collected value is keyed by `id` in the resume value." },
+        "label": { "type": "string" },
+        "placeholder": { "type": "string" },
+        "required": { "type": "boolean" }
+      }
+    },
+    "fieldDate": {
+      "type": "object",
+      "required": ["component", "id", "label"],
+      "additionalProperties": false,
+      "properties": {
+        "component": { "type": "string", "enum": ["field.date"] },
+        "id": { "type": "string" },
+        "label": { "type": "string" },
+        "required": { "type": "boolean" }
+      }
+    },
+    "fieldSelect": {
+      "type": "object",
+      "required": ["component", "id", "label", "options"],
+      "additionalProperties": false,
+      "properties": {
+        "component": { "type": "string", "enum": ["field.select"] },
+        "id": { "type": "string" },
+        "label": { "type": "string" },
+        "required": { "type": "boolean" },
+        "options": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "required": ["value", "label"],
+            "additionalProperties": false,
+            "properties": {
+              "value": { "type": "string" },
+              "label": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "fieldCheckbox": {
+      "type": "object",
+      "required": ["component", "id", "label"],
+      "additionalProperties": false,
+      "properties": {
+        "component": { "type": "string", "enum": ["field.checkbox"] },
+        "id": { "type": "string" },
+        "label": { "type": "string" },
+        "default": { "type": "boolean" }
+      }
+    },
+    "actionButton": {
+      "type": "object",
+      "required": ["component", "id", "label", "action"],
+      "additionalProperties": false,
+      "properties": {
+        "component": { "type": "string", "enum": ["action.button"] },
+        "id": { "type": "string" },
+        "label": { "type": "string" },
+        "action": {
+          "type": "object",
+          "required": ["target"],
+          "additionalProperties": false,
+          "description": "Confined action (ai-envelope.md §\"A2UI surfaces\" rule 2). `target` resolves to exactly one host-allowlisted destination — a run interrupt resume or a conversation exchange — never an arbitrary URL, endpoint, or network egress. Enforced by the `a2ui-action-confinement` + `a2ui-surface-no-network-egress` SECURITY invariants.",
+          "properties": {
+            "target": {
+              "type": "string",
+              "enum": ["resume", "exchange"],
+              "description": "`resume` → the collected field values become the interrupt `resumeValue` (interrupt.md). `exchange` → the values become a conversation exchange message (RFC 0005)."
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/localized-content-language-settings.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/localized-content-language-settings.schema.json",
+  "title": "LocalizedContentLanguageSettings",
+  "description": "RFC 0103 (spec/v1/localized-content.md §B). Per-tenant authoring configuration for the content surface. Invariant: `baseLocale` MUST NOT appear in `supportedLocales` (the base locale is carried by section `data`, supported locales by `localizations`). This object is the source of truth for the host's advertised `content` capability block; the advertisement MUST reflect it (`baseLocale` equal, advertised `supportedLocales` equal or a subset).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["baseLocale", "supportedLocales", "autoTranslateOnPublish"],
+  "properties": {
+    "baseLocale": {
+      "type": "string",
+      "pattern": "^[a-z]{2}(-[A-Z]{2})?$",
+      "description": "The locale section `data` is authored in. MUST equal `capabilities.i18n.defaultLocale`."
+    },
+    "supportedLocales": {
+      "type": "array",
+      "description": "BCP-47 tags the tenant authors content translations for. MUST NOT contain `baseLocale`.",
+      "items": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$" },
+      "uniqueItems": true
+    },
+    "autoTranslateOnPublish": {
+      "type": "boolean",
+      "description": "Whether the host auto-translates missing locale fields on publish (host-extension behavior; informational at the protocol layer)."
+    }
+  }
+}

package/schemas/localized-content-page-response.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/localized-content-page-response.schema.json",
+  "title": "LocalizedContentPageResponse",
+  "description": "RFC 0103 (spec/v1/localized-content.md §D). The resolved delivery response for `GET /v1/content/pages/{slug}`. `locale` is the negotiated locale (equals the `Content-Language` response header). `sections[]` carry the ALREADY-MERGED section bodies — resolution (the per-section field merge §C) happened server-side, so no `localizations` map appears in the response. Only `published`, `enabled` sections are present, in render order.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version", "generatedAt", "locale", "slug", "page", "sections"],
+  "properties": {
+    "version": {
+      "type": "string",
+      "description": "Response schema version marker (e.g. `\"1\"`)."
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "When the resolved response was generated."
+    },
+    "locale": {
+      "type": "string",
+      "pattern": "^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8}){0,3}$",
+      "description": "The negotiated locale actually used (BCP-47). Equals the `Content-Language` response header."
+    },
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "The requested page slug."
+    },
+    "page": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["pageId", "slug", "name"],
+      "description": "Resolved page metadata (status omitted — only published pages are delivered).",
+      "properties": {
+        "pageId": { "type": "string", "minLength": 1 },
+        "slug": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+        "name": { "type": "string", "minLength": 1 },
+        "seo": { "type": "object", "additionalProperties": true }
+      }
+    },
+    "sections": {
+      "type": "array",
+      "description": "Resolved sections in render order; each body is the merged result, not the raw record.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["sectionId", "sectionType", "data"],
+        "properties": {
+          "sectionId": { "type": "string", "minLength": 1 },
+          "sectionType": { "type": "string", "minLength": 1 },
+          "data": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "The merged section body for the negotiated locale (exact → family → base shallow overlay)."
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/localized-content-page.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/localized-content-page.schema.json",
+  "title": "LocalizedContentPage",
+  "description": "RFC 0103 (spec/v1/localized-content.md §B). An authored content page: an ordered composition of sections addressed by a URL `slug`. Publication status is atomic across locales for v1. SEO carries hreflang + og:locale alternates so a renderer can emit per-locale link relations.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["pageId", "slug", "name", "status", "sectionOrder"],
+  "properties": {
+    "pageId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable identifier of the page within its tenant."
+    },
+    "slug": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "URL slug for public delivery (`GET /v1/content/pages/{slug}`). Lowercase, hyphen-separated."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-facing page name (admin/authoring label)."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["draft", "published"],
+      "description": "Publication status, atomic across locales for v1. A `draft` page MUST NOT be served on the public delivery path."
+    },
+    "sectionOrder": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Ordered list of `sectionId`s defining the page's render order."
+    },
+    "seo": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional SEO metadata for per-locale link relations.",
+      "properties": {
+        "hreflang": {
+          "type": "array",
+          "description": "hreflang alternates: per-locale canonical URLs.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["locale", "href"],
+            "properties": {
+              "locale": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$" },
+              "href": { "type": "string", "format": "uri" }
+            }
+          }
+        },
+        "ogLocaleAlternates": {
+          "type": "array",
+          "description": "og:locale:alternate values.",
+          "items": { "type": "string", "pattern": "^[a-z]{2}(-[A-Z]{2})?$" },
+          "uniqueItems": true
+        }
+      }
+    }
+  }
+}

package/schemas/localized-content-section.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/localized-content-section.schema.json",
+  "title": "LocalizedContentSection",
+  "description": "RFC 0103 (spec/v1/localized-content.md §B). One section record of an authored content page. A section is ONE record carrying a base `data` payload (authored in the host's `content.baseLocale`) plus a sparse `localizations` map of partial per-locale field overrides — never one record per locale. The negotiated locale's resolved body is computed by the normative per-section field merge (exact-locale → language-family → base `data`, shallow overlay; §C). Body field shapes inside `data`/`localizations` are open and host/section-type-defined; this schema closes the envelope, not the body.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["sectionId", "sectionType", "data", "localizations", "status", "enabled", "order"],
+  "properties": {
+    "sectionId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Stable identifier of the section within its page."
+    },
+    "sectionType": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The section-type discriminator (e.g. `hero`, `features`). The host/section-type defines the body field shape; the protocol does not."
+    },
+    "data": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "The base/default-locale fields, authored in `content.baseLocale`. Open object — body shapes are the host/section-type's concern."
+    },
+    "localizations": {
+      "type": "object",
+      "description": "Sparse map of per-locale partial field overrides. MAY be empty (`{}`). Each key is a BCP-47 tag matching `^[a-z]{2}(-[A-Z]{2})?$` and MUST NOT equal `content.baseLocale` (the base locale is carried by `data`). Each value is a partial overlay of `data` fields; missing fields fall through to `data` (per-section merge §C).",
+      "propertyNames": {
+        "pattern": "^[a-z]{2}(-[A-Z]{2})?$"
+      },
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": true,
+        "description": "Partial field overrides for one locale; shallow-overlaid onto `data`."
+      }
+    },
+    "status": {
+      "type": "string",
+      "enum": ["draft", "published"],
+      "description": "Publication status. Atomic across all locales for v1 (no per-locale publish). The public delivery path serves `published` only."
+    },
+    "enabled": {
+      "type": "boolean",
+      "description": "Whether the section participates in delivery when its page is rendered."
+    },
+    "order": {
+      "type": "integer",
+      "description": "Render order of the section within its page (lower first). `sectionOrder` on the page is authoritative; `order` is the per-section tiebreak/sort hint."
+    }
+  }
+}

package/schemas/suspend-request.schema.json

@@ -81,6 +81,26 @@
           "type": "boolean",
           "default": false,
           "description": "RFC 0093 §D2 (pins RFC 0051 UQ 2). When `true`, a configured override principal (per `interrupt-profiles.md` §approval-gate `override.requiredRole`) MAY bypass the quorum (`requiredApprovals`) and release the gate alone. Default `false`: an override principal's approval counts as ONE quorum vote; quorum still applies. Optional, additive."
+        },
+        "approverGroupRefs": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "RFC 0104 — OPTIONAL, ADVISORY. Opaque group refs whose resolved members are eligible to approve. Like `approversList`, advisory: the host resolves refs against its own identity/RBAC and ENFORCES eligibility at resolve time; the engine treats refs as opaque (no membership resolution in the engine). Capability-gated via `interrupt.approverRouting` (`refKinds` MUST include `group`). Hosts that don't advertise it ignore this field. Membership is resolved at decision time and snapshotted for deterministic replay."
+        },
+        "approverRoleRefs": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "RFC 0104 — OPTIONAL, ADVISORY. Opaque role refs whose holders are eligible to approve. Same advisory + host-resolved + opaque-to-engine + decision-time-snapshot semantics as `approverGroupRefs`. Capability-gated via `interrupt.approverRouting` (`refKinds` MUST include `role`)."
+        },
+        "audience": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "RFC 0104 — OPTIONAL, ADVISORY notification-targeting hint: who should be TOLD about this gate, distinct from who MAY approve (the eligibility refs). When OMITTED, the host SHOULD notify the resolved union of the eligibility refs (`approversList` ∪ `approverGroupRefs` ∪ `approverRoleRefs`). When PRESENT, it OVERRIDES that default. Advisory; the host remains the routing authority. Capability-gated via `interrupt.approverRouting.audience`.",
+          "properties": {
+            "subjects": { "type": "array", "items": { "type": "string" }, "description": "Opaque subject refs to notify." },
+            "groups": { "type": "array", "items": { "type": "string" }, "description": "Opaque group refs to notify." },
+            "roles": { "type": "array", "items": { "type": "string" }, "description": "Opaque role refs to notify." }
+          }
         }
       }
     },

package/src/scenarios/a2ui-surface-degrades.test.ts

@@ -0,0 +1,54 @@
+/**
+ * a2ui-surface-degrades — RFC 0102 §A point: graceful degradation.
+ *
+ * A consumer that does NOT advertise `ui.a2ui-surface` and receives one
+ * MUST fall back to store-without-render and MUST NOT fail the run (N6;
+ * `ui.a2ui-surface` is an OPTIONAL advertised kind, not a MUST-recognize
+ * universal kind — precedent `artifact-type-store-without-render`).
+ *
+ * Always-on (server-free): `ui.a2ui-surface` is NOT one of the four
+ * universal kinds, so a non-advertising consumer is entitled to degrade.
+ * Capability-gated (HTTP): posting the kind to a host that does not list it
+ * in `supportedEnvelopes` is gated (run not failed), not accepted.
+ *
+ * @see RFCS/0102-a2ui-agent-authored-interface-surfaces.md §A
+ * @see spec/v1/ai-envelope.md §"A2UI surfaces"
+ */
+
+import { describe, it, expect } from 'vitest';
+import { driver } from '../lib/driver.js';
+
+const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
+const UNIVERSAL_KINDS = ['clarification.request', 'schema.request', 'schema.response', 'error'];
+
+describe('a2ui-surface-degrades: optional-advertised, not universal (RFC 0102 §A)', () => {
+  it('ui.a2ui-surface is NOT a MUST-recognize universal kind', () => {
+    expect(
+      UNIVERSAL_KINDS.includes('ui.a2ui-surface'),
+      'ai-envelope.md §"A2UI surfaces": ui.a2ui-surface MUST be optional/advertised so an unrecognizing consumer may store-without-render',
+    ).toBe(false);
+  });
+});
+
+describe.skipIf(HTTP_SKIP)('a2ui-surface-degrades: unadvertised kind is gated, run survives (RFC 0102 §A)', () => {
+  it('posting ui.a2ui-surface to a host that does not advertise it → gated (not failed)', async () => {
+    const res = await driver.post('/v1/host/sample/envelope/accept', {
+      envelope: {
+        type: 'ui.a2ui-surface',
+        schemaVersion: 1,
+        envelopeId: 'env-a2ui-degrade-1',
+        correlationId: 'run-a2ui:node-1:turn-0:deg',
+        payload: { catalogVersion: '0.9.1', surface: { components: [] } },
+        meta: { source: 'ai-generation', ts: '2026-06-15T10:00:00Z' },
+      },
+      hostSupportedEnvelopes: ['clarification.request'], // does not advertise ui.a2ui-surface
+    });
+    if (res.status === 404) return; // seam absent — soft-skip
+    expect(res.status).toBe(200);
+    const body = res.json as { status?: string };
+    expect(
+      body.status,
+      driver.describe('RFC 0102 §A (N6)', 'an unadvertised ui.a2ui-surface MUST be gated, never crash the run'),
+    ).toBe('gated');
+  });
+});

package/src/scenarios/a2ui-surface-replay.test.ts

@@ -0,0 +1,84 @@
+/**
+ * a2ui-surface-replay — RFC 0102 §A.6: replay determinism by correlationId.
+ *
+ * The surface envelope replays by `correlationId` (ai-envelope.md §"Replay
+ * determinism"); on recovery/`:fork` the cached outcome is returned and the
+ * surface is NEVER regenerated. Re-emission with the same correlationId but a
+ * divergent `type` refuses with `envelope_correlation_conflict`. Durable
+ * state is exactly `(surface envelope, submitted resume value)`.
+ *
+ * Always-on (server-free): the surface payload is self-contained (no external
+ * `$ref`), the precondition that makes a stored surface replay deterministically
+ * after the external A2UI catalog ships a breaking version.
+ * Capability-gated (HTTP): same correlationId + different type → conflict.
+ *
+ * @see RFCS/0102-a2ui-agent-authored-interface-surfaces.md §A.6
+ * @see spec/v1/ai-envelope.md §"Replay determinism"
+ */
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { driver } from '../lib/driver.js';
+import { SCHEMAS_DIR } from '../lib/paths.js';
+
+const HTTP_SKIP = !process.env.OPENWOP_BASE_URL;
+const schema = JSON.parse(
+  readFileSync(join(SCHEMAS_DIR, 'envelopes/ui.a2ui-surface.schema.json'), 'utf8'),
+) as Record<string, unknown>;
+
+function refStrings(node: unknown, out: string[]): void {
+  if (!node || typeof node !== 'object') return;
+  if (Array.isArray(node)) {
+    node.forEach((n) => refStrings(n, out));
+    return;
+  }
+  const obj = node as Record<string, unknown>;
+  if (typeof obj['$ref'] === 'string') out.push(obj['$ref'] as string);
+  Object.values(obj).forEach((v) => refStrings(v, out));
+}
+
+describe('a2ui-surface-replay: self-contained surface (RFC 0102 §A.6)', () => {
+  it('all $refs are internal (#/...) — surface renders from the payload alone on replay', () => {
+    const refs: string[] = [];
+    refStrings(schema, refs);
+    const external = refs.filter((r) => !r.startsWith('#'));
+    expect(
+      external,
+      'RFC 0102 §A.6: a stored surface MUST be self-contained for deterministic :fork/replay (no live external-catalog ref)',
+    ).toEqual([]);
+  });
+});
+
+describe.skipIf(HTTP_SKIP)('a2ui-surface-replay: correlationId conflict on type divergence (RFC 0102 §A.6)', () => {
+  const base = {
+    schemaVersion: 1,
+    correlationId: 'run-a2ui:node-1:turn-0:rep',
+    payload: { catalogVersion: '0.9.1', surface: { components: [] } },
+    meta: { source: 'ai-generation', ts: '2026-06-15T10:00:00Z' },
+  };
+
+  it('re-emission with same correlationId + different type → envelope_correlation_conflict', async () => {
+    const first = await driver.post('/v1/host/sample/envelope/accept', {
+      envelope: { ...base, type: 'ui.a2ui-surface', envelopeId: 'env-a2ui-rep-1' },
+      hostSupportedEnvelopes: ['ui.a2ui-surface', 'clarification.request'],
+    });
+    if (first.status === 404) return; // seam absent — soft-skip
+
+    const conflict = await driver.post('/v1/host/sample/envelope/accept', {
+      envelope: {
+        ...base,
+        type: 'clarification.request',
+        envelopeId: 'env-a2ui-rep-2',
+        payload: { questions: [{ id: 'q', question: 'x' }] },
+      },
+      hostSupportedEnvelopes: ['ui.a2ui-surface', 'clarification.request'],
+    });
+    if (conflict.status === 404) return;
+    const body = conflict.json as { status?: string; reason?: string };
+    expect(
+      body.reason ?? '',
+      driver.describe('ai-envelope.md §"Replay determinism"', 'same correlationId + divergent type MUST conflict'),
+    ).toContain('envelope_correlation_conflict');
+  });
+});