@openwop/spec-artifacts 2.0.0-rc.0

package/schemas/workload-identity.schema.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/workload-identity.schema.json",
+  "title": "OpenWOP workload identity and delegated actor chain (RFC 0154)",
+  "description": "RFC 0154 §A/§B. An authenticated workload identity, and the delegation context a request may carry.\n\nThe governing rule is negative and it is why every object here is closed: raw certificates, tokens, proofs, and credentials MUST NOT enter these objects. `subject` is an OPAQUE identifier and `proofRef` is a REFERENCE. A verified identity is a fact about a completed verification, not a container for the material that proved it — and these objects are projected into events, spans, and audit records, which is exactly where credential material must never reach (`SECURITY/threat-model-secret-leakage.md`).\n\nThe second rule is that identity is not authorization (RFC 0147 R12). Knowing which workload called says nothing about what it may do; tenant, audience, and policy are re-evaluated at every boundary.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["scheme", "subject"],
+  "properties": {
+    "scheme": {
+      "enum": ["spiffe", "mtls-san", "cloud-subject", "oauth-client"],
+      "description": "How the identity was presented and verified. Closed: an unrecognized scheme is a verification path nobody implemented."
+    },
+    "subject": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Opaque verified identifier, e.g. a SPIFFE ID. MUST NOT be a credential, token, or certificate."
+    },
+    "issuer": { "type": "string", "minLength": 1 },
+    "audience": {
+      "type": "string",
+      "minLength": 1,
+      "description": "RFC 0154 §A — the audience the presented identity was minted for. A host MUST reject an identity whose audience is not its own: accepting one is how a credential valid elsewhere becomes a credential valid here."
+    },
+    "keyBinding": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Proof-of-possession binding. Carries the METHOD and a thumbprint reference, never the key.",
+      "required": ["method"],
+      "properties": {
+        "method": { "enum": ["mtls", "dpop"] },
+        "thumbprintRef": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$",
+          "description": "Digest reference to the bound key. Pattern-constrained so a raw key cannot be pasted here and still validate."
+        }
+      }
+    },
+    "delegation": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "RFC 0154 §B — the verified delegation chain, if any.",
+      "required": ["chain", "audience"],
+      "properties": {
+        "chain": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Ordered delegation hops. Non-empty: a delegation context with no chain claims a delegation nobody can inspect.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["subject"],
+            "properties": {
+              "subject": { "type": "string", "minLength": 1 },
+              "issuer": { "type": "string", "minLength": 1 },
+              "scopes": {
+                "type": "array",
+                "uniqueItems": true,
+                "items": { "type": "string", "minLength": 1 },
+                "description": "RFC 0154 §B — the effective scopes VERIFIED for this hop from its proof (RFC 0049 scope grammar). OPTIONAL and provenance, not authorization: the host still evaluates the resolved principal's own scopes. When present on consecutive hops, a later hop's scopes MUST NOT exceed the previous hop's (`auth.md` §\"Bounds\" — scope amplification is refused: `delegation_scope_amplified`)."
+              }
+            }
+          }
+        },
+        "audience": { "type": "string", "minLength": 1 },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "RFC 0154 §B — a delegation without an expiry is a standing grant, which is not what delegation means."
+        },
+        "proofRef": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$",
+          "description": "Digest REFERENCE to the verified proof. Never the proof itself."
+        }
+      }
+    }
+  }
+}

package/schemas/workspace-file-create.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/workspace-file-create.schema.json",
+  "title": "WorkspaceFileCreate",
+  "description": "RFC 0059. Request body for `PUT /v1/host/workspace/files/{path}` (atomic create/replace). The `path` is taken from the URL and MUST NOT be supplied here; the host assigns `version`, `etag`, and `updatedAt`. The client supplies only `content` and an optional `contentType`. Optimistic concurrency is expressed via the `If-Match` request header (the file's current `etag`), NOT a body field — a stale `If-Match` returns `409 workspace_conflict`. A `content` exceeding `capabilities.workspace.maxFileBytes` returns `workspace_too_large`. The response is a full `workspace-file.schema.json`.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["content"],
+  "properties": {
+    "content": {
+      "type": "string",
+      "description": "UTF-8 file body to persist. SR-1-redacted on write per RFC 0059 §E WSR-1."
+    },
+    "contentType": {
+      "type": "string",
+      "default": "text/markdown",
+      "description": "Advisory MIME type of `content`. Defaults to `text/markdown`."
+    }
+  }
+}

package/schemas/workspace-file.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/workspace-file.schema.json",
+  "title": "WorkspaceFile",
+  "description": "RFC 0059. A versioned, tenant·workspace-scoped ground-truth file in the `host.workspace` store. Returned by `GET /v1/host/workspace/files/{path}` and `PUT …/{path}`; the `list` endpoint returns the same shape minus `content` (metadata only). `path` is a flat namespace with `/`-in-names (NOT nested directories) — no `..`, no leading `/` (the pattern enforces this). Writes are atomic and optimistically concurrent via the `etag` token (`If-Match`). When `capabilities.workspace.versioned: true`, prior versions are retrievable via `?version=N`. Content is SR-1-redacted on write (RFC 0059 §E WSR-1) — never the BYOK plaintext.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["path", "content", "version", "updatedAt"],
+  "properties": {
+    "path": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._/-]{0,255}$",
+      "description": "Workspace-relative path. Flat namespace with `/`-in-names; MUST NOT contain `..` or a leading `/` (the pattern forbids both). Stable identity of the file within the `{tenant, workspace}` scope."
+    },
+    "content": {
+      "type": "string",
+      "description": "UTF-8 file body. SR-1-redacted on write per RFC 0059 §E WSR-1 — a value the run's BYOK vault resolved is persisted as `[REDACTED:<secretId>]`, never the plaintext."
+    },
+    "contentType": {
+      "type": "string",
+      "default": "text/markdown",
+      "description": "Advisory MIME type of `content`. Defaults to `text/markdown` (the ground-truth-file convention)."
+    },
+    "version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Monotonic version. 1 on first create; each successful `PUT` bumps it by one. The latest version is always retrievable; historical versions are best-effort up to `capabilities.workspace.maxVersions`."
+    },
+    "etag": {
+      "type": "string",
+      "description": "Opaque version token for `If-Match` optimistic concurrency. A `PUT` carrying a stale `If-Match` MUST be refused with `409 workspace_conflict`."
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of the write that produced this version."
+    }
+  }
+}

package/spec/v1/alias-detectors.json

@@ -0,0 +1,283 @@
+{
+  "$comment": "RFC 0167 §E — the alias inventory as data. Each detector names a literal token that, while present in the named file, proves an alias or legacy spelling is still in the corpus, and the spec/v1/deprecations.json row that must cover it. scripts/check-alias-coverage.mjs fails when a token is present and its row is missing, or when a row's detector token has disappeared (the alias is gone — retire the detector with the surface). Reviewed, not derived: a grep cannot decide what is an alias; this file records the decision.",
+  "version": 1,
+  "updated": "2026-09-03",
+  "detectors": [
+    {
+      "alias": "capabilities wrapper object",
+      "file": "spec/v1/capabilities.md",
+      "token": "deprecated legacy shape",
+      "deprecation": "openwop.deprecation.capabilities-wrapper"
+    },
+    {
+      "alias": "host.* dotted mirror keys",
+      "file": "RFCS/0073-capability-document-root-layout.md",
+      "token": "deprecated mirror",
+      "deprecation": "openwop.deprecation.host-dotted-mirror"
+    },
+    {
+      "alias": "openwop-core profile id",
+      "file": "spec/v1/profiles.md",
+      "token": "openwop-core",
+      "deprecation": "openwop.deprecation.profile-openwop-core-alias"
+    },
+    {
+      "alias": "channel state-key prefix conventions",
+      "file": "spec/v1/channels-and-reducers.md",
+      "token": "prefix",
+      "deprecation": "openwop.deprecation.channel-prefix-conventions"
+    },
+    {
+      "alias": "a2a bare supported:true",
+      "file": "spec/v1/a2a-integration.md",
+      "token": "supported: true",
+      "deprecation": "openwop.deprecation.a2a-bare-supported"
+    },
+    {
+      "alias": "mcp bare supported:true",
+      "file": "spec/v1/mcp-integration.md",
+      "token": "supported: true",
+      "deprecation": "openwop.deprecation.mcp-bare-supported"
+    },
+    {
+      "alias": "config.outputArtifactType",
+      "file": "schemas/workflow-definition.schema.json",
+      "token": "outputArtifactType",
+      "deprecation": "openwop.deprecation.config-output-artifact-type"
+    },
+    {
+      "alias": "config.chatCard",
+      "file": "schemas/workflow-definition.schema.json",
+      "token": "chatCard",
+      "deprecation": "openwop.deprecation.config-chat-card"
+    },
+    {
+      "alias": "capabilities.auth.subjectLinking flag",
+      "file": "schemas/capabilities.schema.json",
+      "token": "subjectLinking",
+      "deprecation": "openwop.deprecation.auth-subject-linking-flag"
+    },
+    {
+      "alias": "certification bundle v1",
+      "file": "schemas/conformance-certification-bundle.schema.json",
+      "token": "\"const\": \"1\"",
+      "deprecation": "openwop.deprecation.certification-bundle-v1"
+    },
+    {
+      "alias": "Capabilities-Etag header",
+      "file": "spec/v1/capabilities-change-detection.md",
+      "token": "Capabilities-Etag",
+      "deprecation": "openwop.deprecation.capabilities-etag-header"
+    },
+    {
+      "alias": "contractProvenance root block",
+      "file": "schemas/capabilities.schema.json",
+      "token": "contractProvenance",
+      "deprecation": "openwop.deprecation.contract-provenance"
+    },
+    {
+      "alias": "X-openwop-* webhook header family",
+      "file": "spec/v1/webhooks.md",
+      "token": "X-openwop-Signature",
+      "deprecation": "openwop.deprecation.webhook-x-header-family"
+    },
+    {
+      "alias": "409 interrupt_already_resolved beside 410 interrupt_gone",
+      "file": "spec/v1/interrupt-profiles.md",
+      "token": "interrupt_already_resolved",
+      "deprecation": "openwop.deprecation.interrupt-token-409-410-overlap"
+    },
+    {
+      "alias": "engineVersion integer root / string event split",
+      "file": "spec/v1/version-negotiation.md",
+      "token": "engineVersion` axis is split",
+      "deprecation": "openwop.deprecation.engine-version-type-split"
+    },
+    {
+      "alias": "since poll cursor",
+      "file": "spec/v1/version-negotiation.md",
+      "token": "hosts MAY also accept `since`",
+      "deprecation": "openwop.deprecation.poll-cursor-since"
+    },
+    {
+      "alias": "X-Dedup request header",
+      "file": "spec/v1/rest-endpoints.md",
+      "token": "X-Dedup",
+      "deprecation": "openwop.deprecation.custom-request-headers-x-family"
+    },
+    {
+      "alias": "X-Force-Engine-Version request header",
+      "file": "spec/v1/version-negotiation.md",
+      "token": "X-Force-Engine-Version",
+      "deprecation": "openwop.deprecation.custom-request-headers-x-family"
+    },
+    {
+      "alias": "replay.fork boolean",
+      "file": "schemas/capabilities.schema.json",
+      "token": "Legacy spelling retained",
+      "deprecation": "openwop.deprecation.replay-fork-boolean"
+    },
+    {
+      "alias": "debug-bundle seq alias",
+      "file": "schemas/debug-bundle.schema.json",
+      "token": "Legacy alias for `sequence`",
+      "deprecation": "openwop.deprecation.debug-bundle-seq"
+    },
+    {
+      "alias": "credentialProvider node config key",
+      "file": "spec/v1/node-packs.md",
+      "token": "credentialProvider",
+      "deprecation": "openwop.deprecation.credential-provider-key"
+    },
+    {
+      "alias": "publicKeyRef manifest signing field",
+      "file": "schemas/registry-version-manifest.schema.json",
+      "token": "publicKeyRef",
+      "deprecation": "openwop.deprecation.manifest-public-key-ref"
+    },
+    {
+      "alias": "approvalRequested legacy payload",
+      "file": "schemas/run-event-payloads.schema.json",
+      "token": "approvalRequested",
+      "deprecation": "openwop.deprecation.legacy-interrupt-payloads"
+    },
+    {
+      "alias": "clarificationRequested legacy payload",
+      "file": "schemas/run-event-payloads.schema.json",
+      "token": "clarificationRequested",
+      "deprecation": "openwop.deprecation.legacy-interrupt-payloads"
+    },
+    {
+      "alias": "a2a-0.3-legacy profile id",
+      "file": "spec/v1/a2a-integration.md",
+      "token": "a2a-0.3-legacy",
+      "deprecation": "openwop.deprecation.a2a-0-3-legacy-profile"
+    },
+    {
+      "alias": "mcp-2025-06-18-legacy profile id",
+      "file": "spec/v1/mcp-integration.md",
+      "token": "mcp-2025-06-18-legacy",
+      "deprecation": "openwop.deprecation.mcp-2025-06-18-legacy-profile"
+    },
+    {
+      "alias": "openwop-Webhook-Signature SDK header (never in spec)",
+      "file": "RFCS/0165-v2-preparation-wire-shapes.md",
+      "token": "openwop-Webhook-Signature",
+      "deprecation": "openwop.deprecation.sdk-webhook-signature-header"
+    },
+    {
+      "alias": "RFC 0144 extension-class host.* families declared in neither spelling",
+      "file": "spec/v1/capability-declaration-classes.json",
+      "token": "\"class\": \"extension\"",
+      "deprecation": "openwop.deprecation.undeclared-host-extension-families"
+    },
+    {
+      "alias": "/v1/ path-key prefix (the v1 wire surface; removed with the v1 tree)",
+      "file": "spec/v1/rest-endpoints.md",
+      "token": "All paths under `/v1/` are versioned",
+      "deprecation": "openwop.deprecation.v1-path-prefix"
+    },
+    {
+      "alias": "per-RFC G<n> local gap id",
+      "file": "spec/v1/gaps.schema.json",
+      "token": "\"local\"",
+      "deprecation": "openwop.deprecation.gap-local-alias"
+    },
+    {
+      "alias": "registry manifest `deprecated` version flag",
+      "file": "schemas/registry-version-manifest.schema.json",
+      "token": "Advisory: this version is deprecated",
+      "deprecation": "openwop.deprecation.manifest-deprecated-field"
+    },
+    {
+      "alias": "two-segment interrupt resume token",
+      "file": "spec/v1/interrupt.md",
+      "token": "hmac_sha256(secret, payload)",
+      "deprecation": "openwop.deprecation.interrupt-token-unversioned"
+    },
+    {
+      "alias": "details.retryAfterMs body spelling",
+      "file": "spec/v1/rest-endpoints.md",
+      "token": "retryAfterMs",
+      "deprecation": "openwop.deprecation.error-details-retry-after-spellings"
+    },
+    {
+      "alias": "dotted ai.* configurable keys",
+      "file": "spec/v1/run-options.md",
+      "token": "ai.credentialRef",
+      "deprecation": "openwop.deprecation.configurable-dotted-keys"
+    },
+    {
+      "alias": "replay.sideEffectSuppression gate flag",
+      "file": "spec/v1/replay.md",
+      "token": "sideEffectSuppression",
+      "deprecation": "openwop.deprecation.security-opt-in-flags"
+    },
+    {
+      "alias": "supportedTransports root field",
+      "file": "spec/v1/capabilities.md",
+      "token": "supportedTransports",
+      "deprecation": "openwop.deprecation.supported-transports-field"
+    },
+    {
+      "alias": "capabilities.grpc block / core gRPC transport doc",
+      "file": "spec/v1/grpc-transport.md",
+      "token": "REST + SSE remains the REQUIRED wire surface",
+      "deprecation": "openwop.deprecation.grpc-transport-core"
+    },
+    {
+      "alias": "/.well-known/wop rebrand alias",
+      "file": "RFCS/0176-v2-persisted-data-and-coexistence.md",
+      "token": "/.well-known/wop",
+      "deprecation": "openwop.deprecation.well-known-wop-alias"
+    },
+    {
+      "alias": "engines.openwop with no upper bound",
+      "file": "spec/v1/node-packs.md",
+      "token": "`engines.openwop`",
+      "deprecation": "openwop.deprecation.engines-absent-ceiling"
+    },
+    {
+      "alias": "peer-dependency identifiers outside the declaration file",
+      "file": "spec/v1/host-capabilities.md",
+      "token": "pack_peer_dependency_undefined",
+      "deprecation": "openwop.deprecation.pack-peer-dependency-aliases"
+    },
+    {
+      "alias": "signing.method two-convention enum",
+      "file": "schemas/registry-version-manifest.schema.json",
+      "token": "synonymous in practice",
+      "deprecation": "openwop.deprecation.manifest-signing-method"
+    },
+    {
+      "alias": "connection provider version precedence (clause 6)",
+      "file": "spec/v1/connection-packs.md",
+      "token": "greater-than-or-equal to the built-in's",
+      "deprecation": "openwop.deprecation.connection-provider-version-precedence"
+    },
+    {
+      "alias": "seam/test operations in the canonical path manifest",
+      "file": "spec/v1/operation-path-manifest.json",
+      "token": "/v1/host/sample/a2a/tasks/{taskId}",
+      "deprecation": "openwop.deprecation.seam-operations-in-canonical-api"
+    },
+    {
+      "alias": "corpus-coherence scenarios in host bundles",
+      "file": "conformance/src/lib/scenario-disposition.ts",
+      "token": "See lib/spec-coherence.ts for why not a new disposition value",
+      "deprecation": "openwop.deprecation.coherence-scenarios-in-host-bundle"
+    },
+    {
+      "alias": "suite tarball vendored corpus",
+      "file": "conformance/README.md",
+      "token": "The vendored contract is digest-checked",
+      "deprecation": "openwop.deprecation.suite-vendored-corpus"
+    },
+    {
+      "alias": "certification bundle v2 open root",
+      "file": "schemas/certification-bundle-v2.schema.json",
+      "token": "\"const\": \"2\"",
+      "deprecation": "openwop.deprecation.certification-bundle-v2-open-root"
+    }
+  ]
+}

package/spec/v1/capability-declaration-classes.json

@@ -0,0 +1,176 @@
+{
+  "$comment": "Ledger for the §A rule in spec/v1/host-extensions.md — every §host.<name> section in host-capabilities.md is classified as a core DECLARED family or an EXTENSION namespace. Enforced by scripts/check-capability-declaration-classes.mjs (RFC 0144 G3). This file is REVIEWED, not derived: the classification turns on whether a section binds the shape or content of a wire artifact, which no heuristic decides correctly — see the RFC for two worked false positives.",
+  "sections": [
+    {
+      "section": "agentRuntime",
+      "class": "declared",
+      "key": "agentRuntime"
+    },
+    {
+      "section": "aiEnvelope",
+      "class": "declared",
+      "key": "aiEnvelope"
+    },
+    {
+      "section": "aiProviders",
+      "class": "declared",
+      "key": "aiProviders"
+    },
+    {
+      "section": "artifactTypes",
+      "class": "declared",
+      "key": "artifactTypes"
+    },
+    {
+      "section": "blobStorage",
+      "class": "declared",
+      "key": "blobStorage"
+    },
+    {
+      "section": "brand",
+      "class": "extension"
+    },
+    {
+      "section": "cache",
+      "class": "declared",
+      "key": "cache"
+    },
+    {
+      "section": "canvas",
+      "class": "extension"
+    },
+    {
+      "section": "chat",
+      "class": "extension",
+      "reason": "ctx.* surface. Its MUST binds trust propagation on prompt segments (`meta` / `untrusted`) — a prompt-assembly rule governed by RFC 0143 and carried on the aiEnvelope surface, which IS declared. It does not bind the shape or content of any `chat` discovery field."
+    },
+    {
+      "section": "coordination",
+      "class": "extension"
+    },
+    {
+      "section": "credentials",
+      "class": "declared",
+      "key": "credentials"
+    },
+    {
+      "section": "dataIntegration",
+      "class": "extension"
+    },
+    {
+      "section": "deadLetter",
+      "class": "declared",
+      "key": "deadLetter"
+    },
+    {
+      "section": "entities",
+      "class": "extension"
+    },
+    {
+      "section": "forms",
+      "class": "declared",
+      "key": "forms"
+    },
+    {
+      "section": "fs",
+      "class": "declared",
+      "key": "fs"
+    },
+    {
+      "section": "heartbeat",
+      "class": "declared",
+      "key": "heartbeat"
+    },
+    {
+      "section": "http",
+      "class": "declared",
+      "key": "httpClient"
+    },
+    {
+      "section": "kanban",
+      "class": "extension"
+    },
+    {
+      "section": "knowledge",
+      "class": "extension",
+      "reason": "ctx.* surface (`ctx.knowledge.retrieve`, `ctx.knowledge.embed`; Required methods: retrieve). Its MUSTs are host-side authorization — enforce workspace access, filter `collectionIds[]`, and surface `403 knowledge_workspace_forbidden`. There is no REST endpoint here, so that 403 is the error of a host-side method call, not a protocol response body. §A names a ctx.*-only section as the extension class."
+    },
+    {
+      "section": "kvStorage",
+      "class": "declared",
+      "key": "kvStorage"
+    },
+    {
+      "section": "launchStudio",
+      "class": "extension"
+    },
+    {
+      "section": "mcp",
+      "class": "declared",
+      "key": "mcp"
+    },
+    {
+      "section": "messaging",
+      "class": "extension"
+    },
+    {
+      "section": "nosql",
+      "class": "declared",
+      "key": "nosql"
+    },
+    {
+      "section": "oauth",
+      "class": "declared",
+      "key": "oauth"
+    },
+    {
+      "section": "promptLibrary",
+      "class": "declared",
+      "key": "promptLibrary"
+    },
+    {
+      "section": "queueBus",
+      "class": "declared",
+      "key": "queueBus"
+    },
+    {
+      "section": "scheduling",
+      "class": "declared",
+      "key": "scheduling"
+    },
+    {
+      "section": "searchIndex",
+      "class": "declared",
+      "key": "searchIndex"
+    },
+    {
+      "section": "secrets",
+      "class": "declared",
+      "key": "secrets"
+    },
+    {
+      "section": "sql",
+      "class": "declared",
+      "key": "sql"
+    },
+    {
+      "section": "tableStorage",
+      "class": "declared",
+      "key": "tableStorage"
+    },
+    {
+      "section": "toolHooks",
+      "class": "declared",
+      "key": "toolHooks"
+    },
+    {
+      "section": "vectorStore",
+      "class": "declared",
+      "key": "vectorStore"
+    },
+    {
+      "section": "webResearch",
+      "class": "extension"
+    }
+  ]
+}