@openwop/spec-artifacts 2.35.1 → 2.36.0

package/spec/v2/ext/a2uiSurface/README.md

@@ -1,7 +1,8 @@
 # `a2uiSurface` extension
 
-> **Status: Draft · v2 extension.** Discovery-only reservation; no portable
-> operations or payload contract is defined in the current v2 corpus.
+> **Status: Draft · v2 extension.** Normative contract for the `ui.a2ui-surface`
+> envelope kind at per-kind schema version 2 (RFC 0209), and the deprecated
+> `deltaTransport` facet (RFC 0114 in v1).
 
 | Field | Value |
 | --- | --- |
@@ -10,24 +11,137 @@
 | **adoption:** | `none` |
 | **peer-dependency id** | `a2uiSurface` |
 | **advertised as** | `extensions.<org>.a2uiSurface` |
-| **owning RFC** | RFC 0114 |
-| **declared facets** | `deltaTransport` |
+| **owning RFC** | RFC 0209 |
+| **declared facets** | `deltaTransport` (deprecated) |
 
-## Contract boundary
+## Versions
 
-A host MAY advertise this identifier under its registered organization namespace.
-The extension record is organization-defined, so clients MUST NOT infer portable
-operations, payloads, or authorization semantics from its presence. A pack may
-name `a2uiSurface` as a dependency only when the host and pack share
-an out-of-band definition of that dependency.
+`ui.a2ui-surface` has two per-kind schema versions in v2, both in
+[`schemas/v2/envelopes/ui.a2ui-surface.schema.json`](../../../../schemas/v2/envelopes/ui.a2ui-surface.schema.json):
 
-The v1 description,
-[`spec/v1/capabilities.md`](https://github.com/openwop/openwop/blob/main/spec/v1/capabilities.md)
-(`a2uiSurface`), is useful for migration but is not a
-standalone v2 interoperability contract. A future revision can replace this
-boundary with normative behavior, schemas, and a behavioral witness.
+| Version | Branch | Shape |
+| --- | --- | --- |
+| `1`, `0` or absent | `$defs/payloadV1` | the RFC 0102 seven-component tree pinned by `catalogVersion: "0.9.1"`, unchanged from v1 |
+| `2` | `$defs/payloadV2` | `{ reasoning?, version: "v0.9", catalogId, surfaceId, messages[1..64] }`: an ordered run of A2UI v0.9 server-to-client messages in the profile below |
+
+An engine MUST validate an envelope against exactly one branch: the one for the
+version that `core/events.md` §"The envelope-kind catalog" selects (the emitted
+version, or the advertised one under `warn` below the floor). It MUST NOT
+validate against the union: a version-2 envelope carrying a version-1 payload is
+invalid, and so is the reverse. The root `anyOf` exists for tooling; a host that
+asks a model to emit version 2 hands the provider `$defs/payloadV2` alone.
+
+A host admits version 2 by advertising `schemaVersions.kinds["ui.a2ui-surface"]: 2`.
+The catalog rules then apply unchanged, so a consumer that knows only version 1
+refuses version 2 with `unknown_schema_version` and fails closed.
+
+In a version-2 payload, `catalogId` is an enum of the host-pinned catalogs, today
+exactly `https://a2ui.org/specification/v0_9/catalogs/basic/catalog.json`. Every
+message's `surfaceId` MUST equal the payload's `surfaceId`, and a
+`createSurface.catalogId` MUST equal the payload's `catalogId`. The schema cannot
+express either cross-field rule, so the engine checks both at admission and
+refuses a violation with `envelope_invalid`.
+
+## The profile
+
+Every message that validates against `payloadV2.messages[]` MUST also validate
+against upstream A2UI v0.9 `server_to_client.json` with the basic catalog and
+`common_types.json` bound. The profile only removes; it never adds a property
+A2UI lacks. Conformance vendors the upstream files, pinned by SHA-256
+(`conformance/fixtures/upstream/a2ui-v0.9/`).
+
+| Message | Profile |
+| --- | --- |
+| `createSurface` | `surfaceId`, `catalogId`, optional `theme` limited to `primaryColor` and `agentDisplayName` |
+| `updateComponents` | `surfaceId` and `components[1..512]` from the set below |
+| `updateDataModel` | as upstream: `surfaceId`, optional `path` (JSON Pointer), optional `value` |
+| `deleteSurface` | as upstream |
+
+Components, each closed and discriminated by a single-string-enum `component`:
+`Text`, `TextField`, `CheckBox`, `ChoicePicker`, `DateTimeInput`, `Button`,
+`Column`, `Row`, `Card`, `Divider`. A dynamic value is a literal or a `{path}`
+data binding. `Column` and `Row` take static `children` id lists only.
+
+| Excluded | Why |
+| --- | --- |
+| `Button.action.functionCall` (including `openUrl`) | client-side execution; `a2ui-action-confinement` |
+| `FunctionCall` values, except `checks[].condition` calling `required` | code execution on the renderer; `a2ui-surface-no-code-exec` |
+| `TextField.variant: "obscured"` | a surface MUST NOT solicit a secret; `a2ui-surface-no-secret-input` |
+| `Image`, `Video`, `AudioPlayer`, `createSurface.theme.iconUrl` | each fetches a URL; `a2ui-surface-no-network-egress` |
+| `createSurface.sendDataModel` | collected data returns only through the action below |
+| `Icon` | its vocabulary is renderer-defined; deferred |
+| `List`, `Tabs`, `Modal`, `Slider`, data-model templates | outside the day-one profile |
+
+## Actions and collected data
+
+A `Button.action` MUST be the A2UI server-event arm `{ event: { name, context? } }`
+with `name` ∈ {`resume`, `exchange`}: an interrupt resume or a conversation
+exchange. When a user fires one, the consumer resolves `event.context` against
+the surface's data model and submits the result, as the interrupt `resumeValue`
+for `resume` or as the exchanged turn's data for `exchange`. With no `context` it
+submits the whole data model at `/`. It MUST NOT submit anywhere else.
+
+A host MUST NOT emit a surface whose evident purpose is credential collection.
+Collected values become a `resumeValue` in the event log, where SR-1 redaction is
+a backstop, not a licence.
+
+## The fold
+
+A surface is identified by `(runId, surfaceId)`. Its state is the fold, in event
+`sequence` order, of the `messages` of every version-2 `ui.a2ui-surface` envelope
+the run recorded with that `surfaceId`, under A2UI v0.9 semantics:
+`updateComponents` upserts components by `id`, `updateDataModel` replaces or
+removes the value at `path`, and `deleteSurface` ends the surface.
+
+The host MUST refuse, rather than record, an envelope that would make the fold
+invalid, with `envelope_invalid`:
+
+- the first envelope for a `surfaceId` does not begin with `createSurface`;
+- `createSurface` is sent for a live `surfaceId`;
+- any message follows `deleteSurface` without a new `createSurface`.
+
+A consumer MUST NOT render the surface, or enable any action on it, until the
+fold holds exactly one component with `id: "root"`. `partial: true` keeps its
+per-envelope meaning; a surface's actions stay disabled until the envelope that
+last touched it has finalized.
+
+## Replay and fork
+
+Recorded surface envelopes are returned as recorded; no surface is regenerated.
+A reader MUST keep accepting version-1 envelopes on replay, fork and poll for the
+life of the major, including on a host whose floor is now 2: recorded envelopes
+are read, not re-admitted through the envelope-kind catalog. A fork at `fromSeq`
+folds only the envelopes in `[0, fromSeq)`.
+
+## Trust
+
+If any envelope in a surface's fold carries `meta.contentTrust: "untrusted"`, the
+whole surface is untrusted and the `untrusted_content_blocks_approval` rule
+applies to every action on it: an `approval` interrupt it is bound to MUST NOT
+advance. A later trusted `updateComponents` does not launder an earlier untrusted
+one, and one untrusted update taints a surface a trusted node created. The SR-1
+harness walks every message.
+
+## `deltaTransport` (deprecated)
+
+`schemas/v2/a2ui-surface-delta-frame.schema.json` and the `deltaTransport` facet
+are deprecated for major 2 (`spec/v1/deprecations.json`,
+`openwop.deprecation.v2-a2ui-delta-frame` and `-delta-transport-facet`). A v2 host
+SHOULD NOT advertise the facet: incremental updates are version-2 envelopes
+carrying `updateComponents` / `updateDataModel`, recorded and replayable by the
+fold. The rows carry `removeIn: "3.0"` until RFC 0197 is `Accepted`; removal then
+follows its `v2-minor` path. v1's RFC 0114 stands.
 
 ## Conformance
 
-The current `claims-check` witness validates only that the discovery claim is
-well formed. It does not demonstrate compatible runtime behavior.
+- `conformance/src/coherence/a2ui-v09-profile.test.ts` (corpus gate, no host): the
+  profile ⊂ upstream check, each excluded affordance refused, the pinned catalog,
+  the unchanged version-1 branch and the `ui.*`/`media.*` kind carve-out.
+- `conformance/src/scenarios/v2-a2ui-v09-surface.test.ts` (major 2, seams-gated on
+  `POST /conformance/seams/sample/a2ui/emit-surface` in `api/seams-v2.yaml`):
+  version selects branch, fold guarded, catalog equality, legacy readable and
+  sticky taint. A host without the seam records `inapplicable`.
+- No render before `root` is a renderer guarantee the server-oriented suite cannot
+  observe; it is witnessed by a reference-app client probe (`tier: reference-impl`).
+
+The `claims-check` witness above is the discovery claim of `extensions.<org>.a2uiSurface`.

package/spec/v2/ext/dataIntegration/README.md

@@ -27,6 +27,11 @@ The v1 description,
 standalone v2 interoperability contract. A future revision can replace this
 boundary with normative behavior, schemas, and a behavioral witness.
 
+For MCP access, the v1 `ctx.dataIntegration.fetchMCP` operation is superseded
+by `ctx.mcp` ([`host-services.md`](../../core/host-services.md) §`mcp`, RFC 0204),
+which returns MCP results unaltered. Retiring `fetchMCP` from an organization's
+`dataIntegration` record is that organization's decision.
+
 ## Conformance
 
 The current `claims-check` witness validates only that the discovery claim is

package/spec/v2/facets/a2a.schema.json

@@ -40,6 +40,10 @@
     },
     "durableTasks": {
       "type": "boolean"
+    },
+    "agentCards": {
+      "const": true,
+      "description": "RFC 0202. Present ⇒ each inventory entry with an `a2aTenant` is published as an A2A 1.0 AgentCard through GetExtendedAgentCard with tenant = a2aTenant (interop.md §Per-agent cards). Requires the a2a-1.0 profile and agents.manifestRuntime. Omit when not offered (RFC 0192)."
     }
   },
   "required": [

package/spec/v2/facets/auth.schema.json

@@ -42,6 +42,7 @@
             "enum": [
               "next-request",
               "exp-and-recheck",
+              "exp-only",
               "crl",
               "ocsp",
               "short-lived",
@@ -74,6 +75,29 @@
               ]
             }
           }
+        },
+        "$comment": "RFC 0210 §C — `exp-only` MUST NOT be advertised on `api-key` or `session`: there the host issued the credential itself, so revocation is in its own hands. The antecedent is the NEW member only, so no document that validates today can be invalidated by it. The full lane -> rule binding is deliberately NOT here (it would retroactively invalidate a committed bundle); it lives in the suite, and scripts/check-lane-revocation-rules.mjs keeps the table, this enum and the suite map in lockstep.",
+        "if": {
+          "properties": {
+            "revocation": {
+              "const": "exp-only"
+            }
+          },
+          "required": [
+            "revocation"
+          ]
+        },
+        "then": {
+          "properties": {
+            "lane": {
+              "not": {
+                "enum": [
+                  "api-key",
+                  "session"
+                ]
+              }
+            }
+          }
         }
       }
     },

package/spec/v2/facets/mcp.schema.json

@@ -70,6 +70,10 @@
           "maximum": 16
         }
       }
+    },
+    "client": {
+      "const": true,
+      "description": "RFC 0204. Present ⇒ the host exposes ctx.mcp.callTool / listTools / readResource / serverHealth to pack code (host-services.md §mcp). Omit when not offered (RFC 0192)."
     }
   },
   "required": [

package/spec/v2/facets/oauth.schema.json

@@ -0,0 +1,70 @@
+{
+  "$comment": "RFC 0199 §C.1/§E.1 — oauth gains the credentialInterrupt facet (presence semantics, RFC 0192) and providers[] gains issuer + pkce. Hand-decided: grants/providers are otherwise the v1 seed.",
+  "properties": {
+    "grants": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "authorization_code",
+          "client_credentials",
+          "refresh_token"
+        ]
+      },
+      "uniqueItems": true,
+      "description": "OAuth 2.0 grant types the host performs on a node's behalf (oauth.md §Token lifecycle)."
+    },
+    "providers": {
+      "type": "array",
+      "description": "Provider catalog the host can acquire tokens for. A connector node's `auth.provider` MUST match an `id` here.",
+      "items": {
+        "type": "object",
+        "required": [
+          "id"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Stable provider id, e.g. `slack`, `google`."
+          },
+          "authUrl": {
+            "type": "string",
+            "format": "uri",
+            "description": "Authorization endpoint."
+          },
+          "tokenUrl": {
+            "type": "string",
+            "format": "uri",
+            "description": "Token endpoint."
+          },
+          "scopesSupported": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Scopes this provider exposes."
+          },
+          "issuer": {
+            "type": "string",
+            "format": "uri",
+            "description": "RFC 0199 §A.4. The provider's authorization-server issuer identifier (RFC 8414 / RFC 9207). Absent ⇒ the host uses a provider-unique redirect URI (RFC 9700 §4.4.2.2)."
+          },
+          "pkce": {
+            "type": "string",
+            "enum": [
+              "S256",
+              "unsupported"
+            ],
+            "description": "RFC 0199 §A.1. Absent or `S256` ⇒ the host sends PKCE S256. `unsupported` ⇒ the host sends no PKCE for this provider; such a provider cannot back an MCP reach."
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "credentialInterrupt": {
+      "const": true,
+      "description": "RFC 0199 §C.1 (oauth.md §The credential interrupt). Present ⇒ the host suspends a node on a `credential` interrupt instead of failing it when no credential resolves or refresh fails terminally. Absent ⇒ it fails the node with `connector_auth_expired`."
+    }
+  }
+}

package/spec/v2/facets/webhooks.schema.json

@@ -4,12 +4,17 @@
     "signatureAlgorithms": {
       "type": "array",
       "minItems": 1,
+      "contains": {
+        "const": "v1"
+      },
       "items": {
         "type": "string",
         "enum": [
-          "v1"
+          "v1",
+          "standard-webhooks-1"
         ]
-      }
+      },
+      "description": "RFC 0201 \u00a7A.3 \u2014 `v1` MUST be listed (schema-enforced by `contains`); `standard-webhooks-1` names the Standard Webhooks 1.0.0 companion scheme a subscriber opts into per subscription at registerWebhook."
     },
     "retryPolicy": {
       "type": "object",
@@ -55,6 +60,22 @@
           "description": "Ceiling the host clamps `limit` to (RFC 0182 \u00a7A.3 page-ceiling idiom)."
         }
       }
+    },
+    "secretRotation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "overlapSeconds"
+      ],
+      "description": "RFC 0201 \u00a7E \u2014 zero-downtime rotation for subscriptions opted into `standard-webhooks-1`; advertised only by a host serving `rotateWebhookSecret` (`POST /webhooks/{webhookId}/rotate-secret`). A host that does not advertise it answers that route `404 not_found`.",
+      "properties": {
+        "overlapSeconds": {
+          "type": "integer",
+          "minimum": 60,
+          "maximum": 604800,
+          "description": "How long after a rotation `webhook-signature` carries an entry under the previous secret beside the new one; `previousSecretExpiresAt = rotatedAt + overlapSeconds`."
+        }
+      }
     }
   },
   "required": [

package/spec/v2/id-field-bindings.json

@@ -59,6 +59,7 @@
     "artifactId": "no openwop id kind governs this surface; the grammar is the owning schema's own",
     "auditCorrelationId": "no openwop id kind governs this surface; the grammar is the owning schema's own",
     "callId": "no openwop id kind governs this surface; the grammar is the owning schema's own",
+    "catalogId": "an A2UI v0.9 catalog URI (RFC 0209 §A.2), pinned by enum in ui.a2ui-surface $defs/catalogId — not an openwop id",
     "causationHostId": "no openwop id kind governs this surface; the grammar is the owning schema's own",
     "changeId": "no openwop id kind governs this surface; the grammar is the owning schema's own",
     "changelogId": "no openwop id kind governs this surface; the grammar is the owning schema's own",
@@ -99,6 +100,7 @@
     "speakerId": "no openwop id kind governs this surface; the grammar is the owning schema's own",
     "stepId": "no openwop id kind governs this surface; the grammar is the owning schema's own",
     "suiteId": "no openwop id kind governs this surface; the grammar is the owning schema's own",
+    "surfaceId": "an A2UI v0.9 surface id, scoped to (runId, surfaceId) by RFC 0209 §C.9; grammar in ui.a2ui-surface $defs/surfaceId — not an openwop id",
     "taskId": "no openwop id kind governs this surface; the grammar is the owning schema's own",
     "toolId": "no openwop id kind governs this surface; the grammar is the owning schema's own",
     "workerId": "no openwop id kind governs this surface; the grammar is the owning schema's own"