@openwop/spec-artifacts 2.0.0-rc.0

package/schemas/certification-bundle-v2.schema.json

@@ -0,0 +1,118 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/certification-bundle-v2.schema.json",
+  "title": "OpenWOP certification bundle, version 2 (RFC 0148 §C)",
+  "description": "A certification bundle that records what EXECUTED, not merely what passed.\n\nThe v1 bundle carried `{passed, failed, skipped}` scenario-file lists. Those three cannot express the distinction the whole program turns on: a scenario file counted as `passed` whether its assertions ran or its runner returned early, and a `skipped` entry could mean 'the operator excluded this', 'the requirement does not apply', or 'we could not check' — three claims with different consequences flattened into one word.\n\nv2 replaces the lists with per-requirement dispositions from RFC 0148 §A, and adds the counts §A.4 requires so a reader can tell a thorough run from a thin one without re-running it. `blocked` is its own total precisely because it is the one that invalidates a claim.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["bundleVersion", "suite", "host", "discovery", "claimedProfiles", "results", "scenarioManifestSha256", "targetConfigurationSha256"],
+  "properties": {
+    "bundleVersion": { "const": "2" },
+    "suite": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["package", "version"],
+      "properties": {
+        "package": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" }
+      }
+    },
+    "host": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 },
+        "vendor": { "type": "string" },
+        "commit": {
+          "type": "string",
+          "minLength": 1,
+          "description": "OPTIONAL, self-reported source revision the host was built from. NOT sufficient to attribute the bundle: a commit does not determine the artifact unless the build is deterministic — a tier-2 host measured 283/22 vs 303/2 from two builds of one commit whose container image ran `npm install` rather than `npm ci` (conformance-certification.md §\"What a bundle attributes to\")."
+        },
+        "build": {
+          "type": "string",
+          "minLength": 1,
+          "description": "OPTIONAL, self-reported identifier of what ACTUALLY EXECUTED — this, not `commit`, is what a verifier needs to re-run the same thing. Which identifier is reachable depends on when the bundle is written: a container image digest is strongest but does not exist yet for a bundle baked INTO the image at certify time; a builder-assigned build id is available during the build; a digest of the resolved dependency manifest (lockfile or resolved tree) is available at certify time and pins the closure that actually varied in the measurement behind this field. State which kind it is rather than reaching for the strongest-sounding one. See conformance-certification.md §\"A bundle attributes to a BUILD\"."
+        }
+      }
+    },
+    "discovery": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["sha256", "document"],
+      "properties": {
+        "url": { "type": "string" },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "document": { "type": "object" }
+      }
+    },
+    "claimedProfiles": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "type": "string", "pattern": "^openwop-[a-z0-9-]+$" },
+      "description": "RFC 0155 §E — canonical profile IDs only. Deprecated aliases go in `aliases`, never here, so a badge cannot be substantiated by a name that no longer means what it did."
+    },
+    "aliases": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "type": "string" }
+    },
+    "results": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["totals", "requirements"],
+      "properties": {
+        "totals": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["executedPass", "executedFail", "skipped", "inapplicable", "blocked"],
+          "description": "RFC 0148 §A/§C. All five are REQUIRED — an omitted total is indistinguishable from zero, and `blocked: 0` asserted is a different claim from `blocked` unstated.",
+          "properties": {
+            "executedPass": { "type": "integer", "minimum": 0 },
+            "executedFail": { "type": "integer", "minimum": 0 },
+            "skipped": { "type": "integer", "minimum": 0 },
+            "inapplicable": { "type": "integer", "minimum": 0 },
+            "blocked": { "type": "integer", "minimum": 0 }
+          }
+        },
+        "requirements": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Per-requirement dispositions. Non-empty: a bundle with no requirement rows records no execution, and RFC 0148 §C exists because an empty evidence set was reading as proof.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["requirementId", "scenarioId", "disposition"],
+            "properties": {
+              "requirementId": { "type": "string", "minLength": 1 },
+              "scenarioId": { "type": "string", "minLength": 1 },
+              "disposition": { "enum": ["executed-pass", "executed-fail", "skipped", "inapplicable", "blocked"] },
+              "assertionCount": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "How many assertions actually ran. `executed-pass` with `assertionCount: 0` is the vacuous pass this program exists to close, and a reader can now see it."
+              },
+              "witnessSha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+              "detail": {
+                "type": "string",
+                "description": "Required by RFC 0148 §A for any disposition other than `executed-pass` — an unexplained `blocked` is an outcome nobody can act on."
+              }
+            }
+          }
+        }
+      }
+    },
+    "scenarioManifestSha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$",
+      "description": "Digest of the scenario set this run executed. Without it a bundle cannot be distinguished from one produced against a different, smaller suite."
+    },
+    "targetConfigurationSha256": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$",
+      "description": "RFC 0147 §A.4 — configuration identity. Two runs of the same suite against differently-configured hosts are different evidence, and this is what says so."
+    }
+  }
+}

package/schemas/channel-presence-payload.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/channel-presence-payload.schema.json",
+  "title": "ChannelPresencePayload",
+  "description": "Payload of the OPTIONAL `channel.presence` RunEvent (RFC 0110). EPHEMERAL live presence for a `type:'channel'` conversation — who is currently present + (optionally) who is typing. A host MUST NOT persist this event to the replayable event log / transcript, and it MUST NOT affect replay or `:fork` determinism (presence is live state, the load-bearing distinction from the persisted `conversation.exchanged` turn — see replay.md). Membership-gated: every ref MUST be a current channel participant and the event MUST NOT be delivered to a non-member (the same DEFAULT-DENY visibility as the channel's messages; cross-tenant delivery is forbidden, CTI-1). NON-PII: subject refs are the opaque RFC 0041 vocabulary only — no IP/location/device. A host MAY emit; if it advertises `channelPresence.supported` it MUST. Gated on `channelPresence.supported` (capabilities.schema.json). See RFC 0110.",
+  "type": "object",
+  "required": ["conversationId", "present"],
+  "additionalProperties": false,
+  "properties": {
+    "conversationId": {
+      "type": "string",
+      "description": "The `type:'channel'` conversation this presence is for.",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "present": {
+      "type": "array",
+      "description": "Subject refs (RFC 0041 vocabulary `user:<id>` / `agent:<id>` — opaque, non-PII) of members CURRENTLY present in the channel. MUST be a subset of the channel's current participants; a non-member MUST NOT appear.",
+      "items": { "type": "string", "minLength": 1, "maxLength": 256 }
+    },
+    "typing": {
+      "type": "array",
+      "description": "OPTIONAL subset of `present` that is currently typing. Boolean-by-presence: a ref appears iff that member is typing. No payload beyond the subject refs (no free text, no PII).",
+      "items": { "type": "string", "minLength": 1, "maxLength": 256 }
+    }
+  },
+  "examples": [
+    {
+      "$comment": "RFC 0110 POSITIVE — two members present in a channel, one typing.",
+      "conversationId": "chan-eng",
+      "present": ["user:alice", "agent:iris"],
+      "typing": ["user:alice"]
+    },
+    {
+      "$comment": "RFC 0110 POSITIVE — typing is OPTIONAL; a presence snapshot with no one typing.",
+      "conversationId": "chan-eng",
+      "present": ["user:alice"]
+    }
+  ],
+  "$comment": "RFC 0110 NEGATIVE (not validatable as an examples[] entry, which must be VALID): a payload carrying any field beyond conversationId/present/typing (e.g. `ip`, `location`) MUST FAIL validation via `additionalProperties: false` — the no-PII guard; see conformance/src/scenarios/channel-presence-shape.test.ts."
+}

package/schemas/channel-written-payload.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/channel-written-payload.schema.json",
+  "title": "ChannelWrittenPayload",
+  "description": "Payload of the `channel.written` RunEvent. Carries the WRITE INPUT (pre-reduction), NOT the post-reduction channel state. Replay reconstructs the post-reduction state by folding all `channel.written` events through the declared reducer. See channels-and-reducers.md §Channel write event.",
+  "type": "object",
+  "required": ["channel", "value", "reducer", "writtenAt"],
+  "properties": {
+    "channel": {
+      "type": "string",
+      "description": "Channel name. MUST match a key declared under `WorkflowDefinition.channels`.",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "value": {
+      "description": "The write payload (any JSON value). Validated against `ChannelDeclaration.schema` if declared. The semantic shape depends on the channel's reducer — see per-reducer §Examples below.",
+      "type": ["object", "array", "string", "number", "boolean", "null"]
+    },
+    "reducer": {
+      "type": "string",
+      "description": "The reducer name in effect at write time. Persisted on the event so replays remain deterministic even if the channel's reducer is later renamed/swapped. Canonical names: `replace`, `append`, `merge`, `counter`, `votes`, `feedback`. Custom reducers MUST use `vendor.<org>.<name>`.",
+      "pattern": "^(replace|append|merge|counter|votes|feedback|vendor\\.[a-z][a-z0-9_-]*\\.[a-z][a-z0-9_-]*)$"
+    },
+    "nodeId": {
+      "type": "string",
+      "description": "Optional — node that performed the write. Set for writes from `ctx.channels.write(...)`; absent for system-initiated writes.",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "writtenAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp. The engine MAY normalize between this canonical form and platform-specific representations (e.g., Firestore Timestamp)."
+    },
+    "schemaVersion": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "The `ChannelDeclaration.schemaVersion` that was live at write time. Persisted on the event so replays + later folds can detect breaking schema changes — the engine validates each event's value against the channel's CURRENT schema and refuses with `channel_schema_breaking_change` when the event's version is older than `current` AND not in `compatibleWith`. Defaults to 1 when omitted (back-compat with pre-C4 servers that didn't track versions). See channels-and-reducers.md §Channel schema migration. (closes C4)"
+    },
+    "sourceEngineId": {
+      "type": "string",
+      "description": "Identifier of the engine instance that performed the write. Set when the writing engine differs from the engine that owns the parent run (e.g., a sub-workflow / cross-canvas-invoke writing to a parent's channel). Absent when the parent's own engine wrote. The fold side uses this to disambiguate origins for `channel-write` trigger filtering (`onlyFrom: 'child'` matches when this field is set and references a known child engine). See channels-and-reducers.md §Distributed reducers. (closes C2)",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "sourceRunId": {
+      "type": "string",
+      "description": "RunId of the cross-engine writer when `sourceEngineId` is set. Absent for owner-engine writes. Lets debugging surfaces (Run Timeline View per replay.md) link the write back to the originating sub-workflow / invoke run. (closes C2)",
+      "minLength": 1,
+      "maxLength": 128
+    }
+  },
+  "additionalProperties": false,
+  "$comment": "Per-reducer expectations on the `value` field (informative — not enforced at this schema level; servers SHOULD validate against `ChannelDeclaration.schema` if declared):\n\n  - `replace`: any value; supersedes prior state.\n  - `append`:  any value; appended to the channel's array. Bounded by `ChannelDeclaration.maxSize` if set.\n  - `merge`:   MUST be a JSON object (`{...}`); shallow-merged into prior state.\n  - `counter`: MUST be a number; added to the running total. Negative allowed.\n  - `votes`:   typically `{voter: string, vote: string|boolean|number, ...}`; the reducer accumulates per-voter latest-wins.\n  - `feedback`: typically `{author: string, text: string, timestamp: string, ...}`; the reducer appends bounded by `maxSize`.\n  - `vendor.*`: implementation-defined; external clients SHOULD treat as `replace` if the reducer name is unknown."
+}

package/schemas/chat-card-pack-manifest.schema.json

@@ -0,0 +1,253 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/chat-card-pack-manifest.schema.json",
+  "title": "ChatCardPackManifest",
+  "description": "Manifest for a published OpenWOP AI chat card pack — `pack.json` at the pack root with `kind: \"card\"`. Peer to the node / workflow-chain / prompt / artifact-type pack manifests; disjoint via the `kind` discriminator. See `spec/v1/chat-card-packs.md` for the canonical contract and RFC 0071 Phase 2 for the rationale.\n\nA chat card pack distributes AI step cards: each card binds a prompt template (with typed input slots) to a typed output artifact. When a host advertises `host.chat.cardPacks: supported` and a registered card is invoked, the host substitutes inputs into the prompt, routes the call through `ctx.aiEnvelope.generate`, and (when `outputArtifactType` is set) validates the result against the referenced artifact-type pack's schema before emitting `artifact.created`.",
+  "type": "object",
+  "required": [
+    "name",
+    "version",
+    "kind",
+    "engines",
+    "cards"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "kind": {
+      "type": "string",
+      "const": "card",
+      "description": "Pack kind discriminator. MUST be the literal string `\"card\"`."
+    },
+    "name": {
+      "type": "string",
+      "description": "Reverse-DNS pack name per `node-packs.md` §Naming. Reserved scopes are identical (`core.*` / `vendor.<org>.*` / `community.<author>.*` / `private.<host>.*`).",
+      "pattern": "^(core|vendor|community|private)\\.[a-z][a-z0-9_-]*(\\.[a-z][a-zA-Z0-9_-]*)+$",
+      "minLength": 1,
+      "maxLength": 256
+    },
+    "version": {
+      "type": "string",
+      "description": "Pack-level SemVer 2.0.0.",
+      "pattern": "^\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?(?:\\+[0-9A-Za-z.-]+)?$"
+    },
+    "description": {
+      "type": "string",
+      "maxLength": 1024
+    },
+    "author": {
+      "type": "string"
+    },
+    "license": {
+      "type": "string",
+      "description": "SPDX license identifier (e.g., `Apache-2.0`, `MIT`)."
+    },
+    "homepage": {
+      "type": "string",
+      "format": "uri"
+    },
+    "repository": {
+      "type": "string",
+      "format": "uri"
+    },
+    "keywords": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "maxLength": 64
+      },
+      "maxItems": 50
+    },
+    "engines": {
+      "type": "object",
+      "required": [
+        "openwop"
+      ],
+      "properties": {
+        "openwop": {
+          "type": "string",
+          "description": "Semver range — which openwop protocol versions this pack works against."
+        }
+      },
+      "additionalProperties": true
+    },
+    "dependencies": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "Other packs this pack depends on (e.g., the artifact-type pack declaring this card's `outputArtifactType`). Map of pack name → semver range."
+    },
+    "peerDependencies": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "Engine-supplied capabilities the pack consumes (e.g., `{ \"host.aiEnvelope\": \"supported\", \"host.chat.cards\": \"supported\" }`). Resolved against the host's advertised capabilities at register time."
+    },
+    "cards": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/Card"
+      },
+      "description": "AI chat card definitions this pack contributes. Each MUST have a unique `cardTypeId` within the pack."
+    },
+    "signing": {
+      "$ref": "#/$defs/Signing"
+    }
+  },
+  "$defs": {
+    "Card": {
+      "type": "object",
+      "required": [
+        "cardTypeId",
+        "prompt"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "cardTypeId": {
+          "type": "string",
+          "description": "Reverse-DNS card identifier. Same pattern and reserved scopes as a pack `name`. The value `WorkflowNode.cardType` / `ctx.chat.emitCard` MAY reference. Third parties MUST NOT publish under `core.*`.",
+          "pattern": "^(core|vendor|community|private)\\.[a-z][a-z0-9_-]*(\\.[a-z][a-zA-Z0-9_-]*)+$",
+          "minLength": 1,
+          "maxLength": 256
+        },
+        "schemaVersion": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Non-negative integer card-schema version (the envelope/artifact integer-version axis). Absent ⇒ treated as 0."
+        },
+        "prompt": {
+          "$ref": "#/$defs/PromptSpec"
+        },
+        "inputs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/InputField"
+          },
+          "description": "Typed input fields the card collects. The portable subset only; host-specific widget kinds extend via `vendor.*`/`x-` prefixed `type` values."
+        },
+        "outputArtifactType": {
+          "type": "string",
+          "description": "A registered `artifactTypeId` (RFC 0071 Phase 1) the card produces. When present, the host MUST validate the LLM output against that artifact type's schema and emit `artifact.created`. Registered-only by design: unlike a bare node `WorkflowNode.artifactType` (where the unregistered free-string tier is permanently valid), a card's product is always a contract-bound artifact, so this MUST be a reverse-DNS registered id. Omit the field for a prompt-only card that produces no durable artifact.",
+          "pattern": "^(core|vendor|community|private)\\.[a-z][a-z0-9_-]*(\\.[a-z][a-zA-Z0-9_-]*)+$"
+        },
+        "outputSchemaRef": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Path inside the pack tarball to the JSON Schema (Draft 2020-12) the LLM output MUST conform to. SHOULD be consistent with the referenced artifact type's schema. MUST set top-level `additionalProperties: false`."
+        },
+        "requiredModelCapabilities": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^([a-z][a-z0-9-]*|x-host-[a-z][a-z0-9-]*-[a-z][a-z0-9-]*)$"
+          },
+          "uniqueItems": true,
+          "maxItems": 32,
+          "description": "Model capabilities the card requires the active model to advertise. Reuses the `requiredModelCapabilities` registry in `host-capabilities.md` (spec-reserved: `structured-output`, `discriminator-enum`, `long-context`, `reasoning`, `function-calling`; host extensions `x-host-<host>-`)."
+        }
+      },
+      "patternProperties": {
+        "^(x-|vendor\\.)": {
+          "description": "Vendor / host extension escape hatch (RFC 0138). A property matching `^(x-|vendor\\.)` is a HOST EXTENSION: its semantics are unspecified by this protocol, and a consumer that does not recognize one MUST ignore it rather than reject the pack. Resolves the contradiction in `host-extensions.md` §\"Vendor-prefixed namespaces\", which requires a client receiving an unknown vendor-prefixed field to treat it as opaque — a field that `additionalProperties: false` previously made impossible to carry. SECURITY: an extension value is PACK-AUTHORED, therefore untrusted; \"ignore\" means ignore. See `node-packs.md` §\"Vendor extensions on pack manifests\" and the `pack-manifest-extension-opaque` invariant."
+        }
+      }
+    },
+    "PromptSpec": {
+      "type": "object",
+      "required": [
+        "template",
+        "placeholderMapping"
+      ],
+      "additionalProperties": false,
+      "description": "The prompt the card composes. The host substitutes mapped input values into `template`/`systemPrompt` before dispatch; segments derived from card inputs are `untrusted` (RFC 0071 Trust boundary).",
+      "properties": {
+        "template": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Prompt body with `{{placeholder}}` slots."
+        },
+        "systemPrompt": {
+          "type": "string",
+          "description": "Optional system prompt."
+        },
+        "placeholderMapping": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "description": "Map of `{{placeholder}}` name → input path (e.g. `\"spec\": \"inputs.spec\"`)."
+        },
+        "temperature": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 2
+        },
+        "maxTokens": {
+          "type": "integer",
+          "minimum": 1
+        }
+      }
+    },
+    "InputField": {
+      "type": "object",
+      "required": [
+        "id",
+        "type"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$"
+        },
+        "type": {
+          "type": "string",
+          "description": "Closed portable subset OR a `vendor.<org>.<kind>` / `x-<kind>` host extension other hosts ignore. The portable subset (G9, resolved 2026-05-27 against MyndHyve's `CardFieldType`): `text`, `longtext`, `number`, `boolean`, `select`, `multiselect`, `file`, `artifact-ref`. MyndHyve maps `textarea`→`longtext` and `toggle`→`boolean`; its product-specific kinds (`canvas-reference`, `collection-reference`, `color`) are host extensions (`vendor.myndhyve.*`), not portable.",
+          "pattern": "^(text|longtext|number|boolean|select|multiselect|file|artifact-ref|vendor\\.[a-z][a-z0-9-]*\\.[a-z][a-z0-9-]*|x-[a-z][a-z0-9-]*)$"
+        },
+        "label": {
+          "type": "string"
+        },
+        "required": {
+          "type": "boolean"
+        },
+        "default": {},
+        "options": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Choices for `type: \"select\"`."
+        }
+      }
+    },
+    "Signing": {
+      "type": "object",
+      "description": "Optional signing metadata. See node-packs.md §signing.",
+      "additionalProperties": false,
+      "properties": {
+        "publicKeyRef": {
+          "type": "string"
+        },
+        "signatureRef": {
+          "type": "string"
+        },
+        "method": {
+          "type": "string",
+          "enum": [
+            "manual",
+            "sigstore"
+          ]
+        }
+      }
+    }
+  },
+  "patternProperties": {
+    "^(x-|vendor\\.)": {
+      "description": "Vendor / host extension escape hatch (RFC 0138). A property matching `^(x-|vendor\\.)` is a HOST EXTENSION: its semantics are unspecified by this protocol, and a consumer that does not recognize one MUST ignore it rather than reject the pack. Resolves the contradiction in `host-extensions.md` §\"Vendor-prefixed namespaces\", which requires a client receiving an unknown vendor-prefixed field to treat it as opaque — a field that `additionalProperties: false` previously made impossible to carry. SECURITY: an extension value is PACK-AUTHORED, therefore untrusted; \"ignore\" means ignore. See `node-packs.md` §\"Vendor extensions on pack manifests\" and the `pack-manifest-extension-opaque` invariant."
+    }
+  }
+}

package/schemas/compact-tool-descriptor.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/compact-tool-descriptor.schema.json",
+  "title": "CompactToolDescriptor",
+  "description": "RFC 0112. A lossy, model-facing projection of `ToolDescriptor` (tool-descriptor.schema.json) returned by `GET /v1/tools?view=compact` + `GET /v1/tools/{toolId}?view=compact` when the host advertises `capabilities.toolCatalog.compactView: true`. Heavy descriptive fields (`outputSchema`, `auth`, `egress`, `approval`, `replayPolicy`, `costHint`, `latencyHint`) are dropped, and any `inputSchema` is bounded to the self-contained compact structural subset (top-level `type: \"object\"` with `properties`; no `$ref`/`oneOf`/`allOf`/`anyOf`/`not`/`patternProperties`/`dependentSchemas`). The subset is the stable structural core of RFC 0030 Tier-1, cited as rationale but pinned HERE so conformance is machine-checkable and immune to that informative table's drift. Like the full descriptor, a CompactToolDescriptor never carries credential material (SR-1) and is not an invocation path.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["toolId", "source", "safetyTier"],
+  "properties": {
+    "toolId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Unchanged from ToolDescriptor. Stable, host-unique tool identifier in the `<scope>:<tool-id>` form; MUST be stable across catalog reads for a given host version (tool-catalog.md §C MUST 3). The compact `tools[]` MUST carry the same `toolId` set as the standard view for the same principal (projection completeness)."
+    },
+    "source": {
+      "type": "string",
+      "enum": ["node-pack", "workflow", "mcp", "connector", "host-extension"],
+      "description": "Retained from ToolDescriptor so the `safetyTier: \"exec\" ⇒ source: \"host-extension\"` cross-field MUST (RFC 0069) stays expressible. Which surface backs the tool: `node-pack`/`workflow`/`mcp`/`connector`/`host-extension`."
+    },
+    "safetyTier": {
+      "type": "string",
+      "enum": ["pure", "read", "write", "exec"],
+      "description": "REQUIRED. The tool's DATA-EFFECT classification (`pure`/`read`/`write`/`exec`); per RFC 0069 an `exec` tool MUST be `source: \"host-extension\"`. Host-assigned, not derivable from a permission/approval/risk tier."
+    },
+    "title": { "type": "string", "description": "MAY — short human-readable label for a model-facing tool picker." },
+    "description": {
+      "type": "string",
+      "description": "MAY — one-line summary; the host SHOULD truncate to a model-facing summary in the compact view."
+    },
+    "inputSchema": {
+      "type": "object",
+      "description": "MAY — the tool's argument schema bounded to the compact structural subset (RFC 0112). When present it MUST have top-level `type: \"object\"` with an explicit `properties` map, and MUST NOT use `$ref`, `oneOf`, `allOf`, `anyOf`, `not`, `patternProperties`, or `dependentSchemas` AT ANY NESTING DEPTH (including inside nested property schemas). Absent ⇒ opaque/host-interpreted args. NOTE: the `propertyNames` clause below is a TOP-LEVEL structural floor only; the total any-depth constraint is enforced by the RFC 0112 conformance scenario (a schema-aware recursive walk), since pure JSON Schema cannot express it without recursion gymnastics.",
+      "required": ["type", "properties"],
+      "properties": {
+        "type": { "const": "object", "description": "Top-level MUST be `\"object\"`." },
+        "properties": { "type": "object", "description": "The argument property map (MUST be present)." }
+      },
+      "propertyNames": {
+        "$comment": "RFC 0112 compact structural subset (TOP-LEVEL FLOOR): forbid the heavy/non-portable keywords as top-level inputSchema keys. The total any-depth constraint is enforced by conformance.",
+        "not": { "enum": ["$ref", "oneOf", "allOf", "anyOf", "not", "patternProperties", "dependentSchemas"] }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "$comment": "RFC 0069 / tool-catalog.md §C-1: an exec-tier tool MUST be host-extension-sourced (exec is never protocol-tier). Mirrors tool-descriptor.schema.json.",
+      "if": { "properties": { "safetyTier": { "const": "exec" } }, "required": ["safetyTier"] },
+      "then": { "properties": { "source": { "const": "host-extension" } }, "required": ["source"] }
+    }
+  ]
+}

package/schemas/compensation-policy.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://openwop.dev/spec/v1/compensation-policy.schema.json",
+  "title": "CompensationPolicy",
+  "description": "RFC 0151 §B — the workflow-level compensation policy, carried as the reserved `settings.compensation` key on `WorkflowDefinition` (`workflow-definition.schema.json` §WorkflowSettings). Node-level `compensation` declarations say WHAT the inverse action is; this policy says WHEN the host starts an unwind and HOW it runs one — which failures qualify (`triggers`), the ordering model, retry/timeout defaults for inverse actions, what happens when an inverse action exhausts its retries, whether approval is escalated, and what a parent cancel does to an active unwind. Closed and additive. A host that advertises `capabilities.compensation` MUST validate the policy at workflow registration and refuse one that names an `orderingModel` or `profileVersion` it does not advertise (`validation_error`). A host that does NOT advertise the family MUST refuse a workflow that carries this key with `capability_required` (`details.requiredCapability: \"compensation\"`, per `capabilities.md` §\"Unsupported capability — refusal contract\") rather than accept it silently: accepting a policy the host will never honour tells the author an unwind will happen when it will not, which is RFC 0148 §B's advertise-and-opt-out failure with the sign flipped. Nothing here can WEAKEN a node's own declaration — a node's `compensation.requiresApproval: true` and `retry` bounds always win over the policy's defaults. Policy is authored, not per-run: there is deliberately no run-options overlay, because a per-run caller who could lower approval scope or drop a trigger would be authorizing their own unwind (RFC 0147 R9).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["triggers"],
+  "properties": {
+    "profileVersion": {
+      "type": "string",
+      "pattern": "^[1-9][0-9]*$",
+      "description": "The RFC 0151 profile version this policy was authored against. OPTIONAL; when present it MUST equal the host's advertised `capabilities.compensation.profileVersion` or registration fails, because `profileVersion` is part of the inverse-action identity (§C) and a workflow authored under one ordering rule MUST NOT mint identities under another."
+    },
+    "orderingModel": {
+      "type": "string",
+      "enum": ["reverse-completion", "dependency-graph"],
+      "default": "reverse-completion",
+      "description": "RFC 0151 §A/§C. `reverse-completion` (default) orders inverse actions by descending durable forward-completion sequence; `dependency-graph` MUST be a DAG and preserve reverse dependency order. The value MUST be one of the host's advertised `capabilities.compensation.orderingModels[]`; a host MUST refuse the workflow at registration otherwise, so an unwind never discovers at failure time that its ordering rule is unimplemented."
+    },
+    "triggers": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "enum": ["node-failure", "run-cancel", "cap-breach", "operator-request"]
+      },
+      "description": "Which events start an unwind. REQUIRED and closed — a policy that names no trigger is not a policy, and an open string here would let a host and an author disagree about a word. `node-failure`: a node reaches terminal failure after its own RFC 0009 retry policy and the run cannot continue. `run-cancel`: an RFC 0094 cancel is accepted while committed effects exist. `cap-breach`: an RFC 0058 / RFC 0084 `cap.breached` hard stop. `operator-request`: an authorized operator explicitly requests an unwind (§E) — MUST be authorized per RFC 0049, binding tenant, principal, action, and plan version. A trigger not listed here does NOT start an unwind; the run ends with its committed effects in place and `compensationStatus: none`, which is the honest shape — no generic rollback is inferred from an undeclared trigger (RFC 0151 §Compatibility)."
+    },
+    "retry": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Defaults for inverse actions whose node-level `compensation.retry` is absent. A node's own bounds always win. Retries reuse the inverse action's stable identity (§C) — never a fresh one, or a transient refund failure mints a second refund.",
+      "properties": {
+        "maxAttempts": { "type": "integer", "minimum": 1 },
+        "backoffMs": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "timeoutMs": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Wall-clock ceiling per inverse-action attempt, in milliseconds. A timed-out attempt counts against `retry.maxAttempts`; it is not a distinct outcome."
+    },
+    "exhaustedDisposition": {
+      "type": "string",
+      "enum": ["record-outcome", "manual-intervention"],
+      "default": "record-outcome",
+      "description": "RFC 0151 §E — what the host does when an inverse action exhausts its retries. Either way the run MUST route to RFC 0053 dead-letter handling and the run's `compensationStatus` follows the §D fold (`partial` or `failed`). `record-outcome` (default): record the failure and continue unwinding the remaining actions. `manual-intervention`: additionally emit `compensation.manual_intervention_required` and stop issuing further inverse actions until an authorized operator retries, skips with recorded justification, substitutes a registered action, or terminates as uncompensated — the rollup reads `manual` while that is unresolved. Requires `capabilities.compensation.manualIntervention: true`; a host that does not advertise it MUST refuse a policy that selects it."
+    },
+    "approvalScope": {
+      "type": "string",
+      "enum": ["declared", "all"],
+      "default": "declared",
+      "description": "RFC 0151 §E. `declared` (default): only inverse actions whose node sets `compensation.requiresApproval: true` create an RFC 0051 approval interrupt. `all`: every inverse action does, regardless of the node's declaration. This value can only ESCALATE — there is no `none`, because a policy MUST NOT strip an approval a node declared for itself (RFC 0147 R9: an inverse action can itself be harmful)."
+    },
+    "onParentCancel": {
+      "type": "string",
+      "enum": ["continue", "pause", "manual"],
+      "default": "continue",
+      "description": "RFC 0151 §C — cancellation of the parent run MUST NOT silently abandon an active compensation. `continue`: the unwind runs to its terminal rollup. `pause`: emit `compensation.paused` and hold for authorized intervention (the run's own `status` carries the wait). `manual`: emit `compensation.manual_intervention_required` and stop; rollup reads `manual`. `pause`/`manual` require `capabilities.compensation.manualIntervention: true`."
+    }
+  }
+}