@ouispec/contract 0.1.0

package/dist/validate.js

@@ -0,0 +1,89 @@
+/**
+ * @ouispec/contract/validate — checks a value against the
+ * contract's schemas with a full JSON Schema (2020-12) validator: a control
+ * table, a mapping, a catalog, a manifest, knowledge, `oui.config.json`, an
+ * approval message or an event declaration document. For build steps, tests
+ * and servers; the browser needs only the types.
+ */
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import formatsPlugin from 'ajv-formats';
+import { CONTRACT_SCHEMAS, CONTRACT_TYPES } from './generated/schemas.js';
+// ajv-formats is CommonJS; under ESM interop its function is on `default`.
+const addFormats = formatsPlugin.default ?? formatsPlugin;
+export class ContractError extends Error {
+    what;
+    ref;
+    problems;
+    constructor(what, ref, problems) {
+        super(`${what} does not match the OUI contract's ${ref}:\n${problems.map((p) => `  - ${p}`).join('\n')}`);
+        this.what = what;
+        this.ref = ref;
+        this.problems = problems;
+        this.name = 'ContractError';
+    }
+}
+/** The schema `$id` (and pointer) a reference names. */
+export function contractSchemaId(ref) {
+    const target = ref in CONTRACT_TYPES ? CONTRACT_TYPES[ref] : ref;
+    const [file, pointer] = target.split('#');
+    const schema = CONTRACT_SCHEMAS[file];
+    if (!schema)
+        throw new Error(`"${ref}" is not a schema or type of the OUI contract`);
+    return pointer ? `${schema.$id}#${pointer}` : schema.$id;
+}
+function describe(error) {
+    const at = error.instancePath || '/';
+    switch (error.keyword) {
+        case 'additionalProperties':
+            return `${at} has "${error.params.additionalProperty}", which the contract does not define`;
+        case 'unevaluatedProperties':
+            return `${at} has "${error.params.unevaluatedProperty}", which the contract does not define`;
+        case 'enum':
+            return `${at} must be one of ${error.params.allowedValues.map((v) => JSON.stringify(v)).join(', ')}`;
+        default:
+            return `${at} ${error.message ?? 'is invalid'}`;
+    }
+}
+/** Compile every schema of the contract once. */
+export function createContractValidator() {
+    const ajv = new Ajv2020({ allErrors: true, strict: true, strictRequired: false });
+    addFormats(ajv);
+    for (const schema of Object.values(CONTRACT_SCHEMAS))
+        ajv.addSchema(schema);
+    const compiled = new Map();
+    const validator = (ref) => {
+        const id = contractSchemaId(ref);
+        let fn = compiled.get(id);
+        if (!fn) {
+            fn = ajv.getSchema(id);
+            if (!fn)
+                throw new Error(`the OUI contract has no schema at ${id}`);
+            compiled.set(id, fn);
+        }
+        return fn;
+    };
+    const problems = (ref, value) => {
+        const validate = validator(ref);
+        if (validate(value))
+            return [];
+        // A `oneOf`'s branches each report why they do not match; the most specific
+        // reasons are the deepest ones.
+        const errors = validate.errors ?? [];
+        return [...new Set(errors.map(describe))];
+    };
+    return {
+        problems,
+        assert(ref, value, what) {
+            const found = problems(ref, value);
+            if (found.length)
+                throw new ContractError(what, ref, found);
+        },
+    };
+}
+let shared = null;
+/** Every way `value` breaks the contract's `ref`. Compiles the schemas on first use. */
+export function contractProblems(ref, value) {
+    shared ??= createContractValidator();
+    return shared.problems(ref, value);
+}
+//# sourceMappingURL=validate.js.map

package/dist/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@ouispec/contract",
+  "version": "0.1.0",
+  "description": "The OUI integrator contract (ADR-0226 §3): versioned JSON Schemas for the control table, control-kind registration, tier 2 mapping, binding, action effect, room catalog, manifest, knowledge, oui.config.json, approvals and event declarations; the TypeScript types generated from them; a validator; and the integrator guide",
+  "homepage": "https://github.com/wesreid/oui/tree/main/packages/contract#readme",
+  "bugs": {
+    "url": "https://github.com/wesreid/oui/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wesreid/oui.git",
+    "directory": "packages/contract"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./validate": {
+      "types": "./dist/validate.d.ts",
+      "import": "./dist/validate.js",
+      "default": "./dist/validate.js"
+    },
+    "./codegen": {
+      "types": "./dist/codegen.d.ts",
+      "import": "./dist/codegen.js",
+      "default": "./dist/codegen.js"
+    },
+    "./schemas/*": "./schemas/*",
+    "./INTEGRATOR-GUIDE.md": "./INTEGRATOR-GUIDE.md",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "README.md",
+    "INTEGRATOR-GUIDE.md",
+    "dist",
+    "schemas"
+  ],
+  "sideEffects": false,
+  "dependencies": {
+    "ajv": "^8.17.0",
+    "ajv-formats": "^3.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/generate.mjs --check",
+    "generate": "tsc -p tsconfig.build.json && node scripts/generate.mjs && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "test": "vitest run",
+    "clean": "rm -rf dist"
+  }
+}

package/schemas/action-effect.json

@@ -0,0 +1,113 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.closurestudio.ai/oui/v1/action-effect.json",
+  "title": "ActionEffect",
+  "description": "What using an action does (ADR-0226 §2.6): one vocabulary for a design-system control's binding, a room catalog's entry and a generated API tool, so a page control, a room action and an API call are told apart by what they change, never by where they are declared.\n\n| Effect | What it changes | ADR-0210 access |\n|---|---|---|\n| `view`, `selection`, `navigate`, `open` | What is shown | read |\n| `edit` | The document, one undo step | write |\n| `file` | Imports or exports a file | write |\n| `mutate` | Backend data, through an API operation | write |\n| `job` | Starts work that outlives the call, settled on its outcome | write |\n| `transaction` | An irreversible external act: an order, a payment, a send, a publish | write, approved |\n\nA `transaction`, and any `write` declared `destructive`, runs only on an approval the person gave, bound to the call (ADR-0228).",
+  "oneOf": [
+    { "$ref": "#/$defs/SimpleEffect" },
+    {
+      "description": "Goes to another page: a route pattern from the app's routes.",
+      "type": "object",
+      "properties": { "kind": { "const": "navigate" }, "to": { "type": "string", "minLength": 1 } },
+      "required": ["kind", "to"],
+      "additionalProperties": false
+    },
+    {
+      "description": "Opens a container on the page: the binding id of a dialog, drawer, popover or tab set.",
+      "type": "object",
+      "properties": { "kind": { "const": "open" }, "container": { "type": "string", "minLength": 1 } },
+      "required": ["kind", "container"],
+      "additionalProperties": false
+    },
+    {
+      "description": "Changes backend data through an API operation, by its `operationId` (`updateVoice`).",
+      "type": "object",
+      "properties": { "kind": { "const": "mutate" }, "operation": { "type": "string", "minLength": 1 } },
+      "required": ["kind", "operation"],
+      "additionalProperties": false
+    },
+    {
+      "description": "Starts work that outlives the call, such as a GPU job. The handler returns `{ ok: true, pending: { jobId } }`; the action is reported done only when the job's completion arrives, failed when it fails, and never done when it has not finished within `timeoutMs` (default 5 minutes). Its states are `JobStatus`.",
+      "type": "object",
+      "properties": {
+        "kind": { "const": "job" },
+        "estimatedDuration": { "type": "string" },
+        "timeoutMs": { "type": "number", "exclusiveMinimum": 0 }
+      },
+      "required": ["kind"],
+      "additionalProperties": false
+    },
+    {
+      "description": "An irreversible external act: an order placed, a payment made, a message sent, something published. Modelled on `job`: its handler may return `pending: { jobId }` and it settles on the outcome. It always needs the person's approval of the exact call (ADR-0228), which no policy waives.\n\n- `operation`: the API operation it goes through, when it is one.\n- `approvalMinutes`: how long an approval of it lasts, at most 30 (default 5).",
+      "type": "object",
+      "properties": {
+        "kind": { "const": "transaction" },
+        "operation": { "type": "string", "minLength": 1 },
+        "estimatedDuration": { "type": "string" },
+        "timeoutMs": { "type": "number", "exclusiveMinimum": 0 },
+        "approvalMinutes": { "type": "integer", "minimum": 1, "maximum": 30 }
+      },
+      "required": ["kind"],
+      "additionalProperties": false
+    }
+  ],
+  "$defs": {
+    "SimpleEffect": {
+      "description": "An effect that needs nothing but its name.",
+      "enum": ["view", "selection", "edit", "file"]
+    },
+    "ActionEffectKind": {
+      "description": "The effect kinds, in the order of the table above. The vocabulary, what each one may change, and what needs the person's approval are OUI's (`oui-spec`).",
+      "enum": ["view", "selection", "navigate", "open", "edit", "file", "mutate", "job", "transaction"]
+    },
+    "EffectAccess": {
+      "description": "Whether an effect only changes what is shown (`read`), or changes something (`write`), as ADR-0210 names it. An action that declares no effect is a `write`.",
+      "enum": ["read", "write"]
+    },
+    "JobStatus": {
+      "description": "Where an action whose effect is `job` or `transaction` is (plan §2.3, #205/#209):\n\n- `started`: the handler returned; the job is tracked from this moment, so an outcome that arrives before the first poll is kept.\n- `running`: still going; the runtime polls the app's `JobTracker`.\n- `complete`: the job's declared completion arrived; the result exists.\n- `failed`: its declared failure arrived; the result never will.\n- `timeout`: it did not finish within `timeoutMs`. A failure, never a late success.\n- `unverified`: no `JobTracker`, or no job id to follow: the work was started but cannot be confirmed from the page.",
+      "enum": ["started", "running", "complete", "failed", "timeout", "unverified"]
+    },
+    "JobOutcome": {
+      "description": "A job's end, as the assistant is told it. `complete` means the result exists; `failed` that it never will. A `complete` outcome carries the declared result fields beside its job id.",
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": { "status": { "const": "complete" }, "jobId": { "type": "string" } },
+          "required": ["status", "jobId"],
+          "additionalProperties": true
+        },
+        {
+          "type": "object",
+          "properties": { "status": { "const": "failed" }, "jobId": { "type": "string" }, "error": { "type": "string" } },
+          "required": ["status", "jobId", "error"],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "JobSettlement": {
+      "description": "What an action that settles on a job reports, from its first answer to its last: `started` (with the job id when the handler gave one), `running` while it polls, then the `JobOutcome`, or `unverified`. A `timeout` is reported as the error `TIMEOUT`, never as data.",
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": { "status": { "const": "started" }, "jobId": { "type": "string" } },
+          "required": ["status"],
+          "additionalProperties": true
+        },
+        {
+          "type": "object",
+          "properties": { "status": { "const": "running" }, "jobId": { "type": "string" } },
+          "required": ["status", "jobId"],
+          "additionalProperties": false
+        },
+        { "$ref": "#/$defs/JobOutcome" },
+        {
+          "type": "object",
+          "properties": { "status": { "const": "unverified" }, "message": { "type": "string" } },
+          "required": ["status", "message"],
+          "additionalProperties": false
+        }
+      ]
+    }
+  }
+}

package/schemas/agent-binding.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.closurestudio.ai/oui/v1/agent-binding.json",
+  "title": "AgentBinding",
+  "description": "The semantic binding a design-system control carries (ADR-0220 §2.2): what the control means, in the user's terms, declared where the page uses it, as its `agent` prop.\n\nIt uses a room catalog entry's vocabulary (id, title and description; `ActionEffect`; `destructive`), so to the generator a page control and a room entry look the same. What is never written: the input schema, which is derived from the control's own props, and where the control is, which the generator derives from the page's component tree.\n\n**Every value is a build-time constant** (#203). The generator reads bindings from source without running it, so each value is a literal, a `const` it can follow, a property of a constant object, a template literal or `+` over those, or a single-literal type read through the type checker. A value built by a call (`t('save')`, `format(...)`) is refused, naming the binding. A field's build-time `hint` and `placeholder` are added to its tool description the same way.",
+  "type": "object",
+  "properties": {
+    "id": {
+      "description": "Stable, globally unique, dotted and lower-kebab: `voices.library`, `voices.detail.engine`. The first segment is the area. The tool name is the id with `.` and `-` as `_`, at most 64 characters.",
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9][a-z0-9-]*)+$"
+    },
+    "title": { "description": "Defaults to the control's visible label or aria-label.", "type": "string" },
+    "description": { "description": "What using it does, for someone who cannot see the screen.", "type": "string", "minLength": 1 },
+    "effect": {
+      "description": "What using it does: what reach paths, data and verification are derived from (ADR-0226 §2.6).",
+      "$ref": "action-effect.json"
+    },
+    "destructive": {
+      "description": "It removes or replaces something the person made; running it needs the person's approval (ADR-0228).",
+      "type": "boolean"
+    },
+    "confirm": {
+      "description": "It changes what the person is working in (their account, project or role) rather than their work; the assistant asks before using it.",
+      "type": "boolean"
+    },
+    "item": { "description": "Set when the control is one of a list's rows: which row.", "$ref": "#/$defs/AgentItem" }
+  },
+  "required": ["id", "description"],
+  "additionalProperties": false,
+  "$defs": {
+    "AgentItem": {
+      "description": "One of several of the same control rendered from a list: which one it is.",
+      "type": "object",
+      "properties": {
+        "key": { "description": "The id of what the row shows (a voice id, a project id).", "type": "string" },
+        "title": { "description": "What the row is called on screen (the voice's name).", "type": "string" },
+        "description": {
+          "description": "What this row is, when the rows' meanings are only known at run time (a model's parameters, from its manifest). Shown with the row in the page state.",
+          "type": "string"
+        }
+      },
+      "required": ["key", "title"],
+      "additionalProperties": false
+    },
+    "NonAgentBinding": {
+      "description": "On a control the assistant must never operate — purely decorative, or chrome that duplicates a bound control. The reason is required and is reviewed like any other declaration.",
+      "type": "object",
+      "properties": { "nonAgent": { "type": "string", "minLength": 1 } },
+      "required": ["nonAgent"],
+      "additionalProperties": false
+    },
+    "AgentProp": {
+      "description": "The `agent` prop of a single-purpose control.",
+      "anyOf": [{ "$ref": "#" }, { "$ref": "#/$defs/NonAgentBinding" }]
+    }
+  }
+}

package/schemas/approvals.json

@@ -0,0 +1,249 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.closurestudio.ai/oui/v1/approvals.json",
+  "title": "Approvals",
+  "description": "Approvals (ADR-0228): the shapes the agent worker, the approval store in the realtime server, the browser's approval card, OUI's surface runtime and a conversation engine exchange. An irreversible action — a `transaction`, or a `write` declared `destructive` — runs only on an approval the person gave, bound to the exact call by a single-use token.\n\n1. The worker stops the turn at the call and stores it (`PendingApprovalInput`); the person's tab receives `agent:approval_required` (`ApprovalRequiredEvent`) and renders the approval card from its `preview`, whose every word comes from the action's declaration, never from the model.\n2. In a UI only a click on the card counts: the card sends `approval:decide` (`ApprovalDecidePayload`) from the person's own socket. On a conversation channel, the verbatim `readback` and an affirmative next turn (ADR-0210 §2.6).\n3. The store answers the decider only (`ApprovalDecideResult`): a single-use token, a compact JWS (`ApprovalTokenClaims`), and the call's `argsHash`. The tab's OUI runtime holds an `ApprovalGrant`.\n4. The next turn carries the token (`ApprovalContinuation`); the worker redeems it for the stored call, exactly (`ApprovedCall`), and runs it. A UI action request then carries `approval` (`ActionRequestApproval`), which the browser checks against its grant before it runs the handler.\n\nThe args hash is SHA-256 over the RFC 8785 (JCS) canonical JSON of the call's arguments, lowercase hex; `oui-spec/approval-vectors.json` holds every implementation, in any language, to it.",
+  "$defs": {
+    "ArgsHash": {
+      "description": "SHA-256 of the RFC 8785 canonical JSON of a call's arguments, lowercase hex.",
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "ApprovalChannel": {
+      "description": "Where the person confirmed. In a UI only a click on the card counts (`ui`); in a conversation channel, the verbatim readback and an affirmative next turn (ADR-0210 §2.6).",
+      "enum": ["ui", "voice", "phone", "sms", "chat"]
+    },
+    "ApprovalDecision": { "enum": ["approve", "decline"] },
+    "ApprovalPreviewArgument": {
+      "description": "One argument of the call, as the person reads it: its declared label and its value in words.",
+      "type": "object",
+      "properties": {
+        "name": { "description": "The argument's name in the call.", "type": "string" },
+        "label": { "description": "Its label, from the action's input schema.", "type": "string" },
+        "value": { "description": "Its value, as text.", "type": "string" }
+      },
+      "required": ["name", "label", "value"],
+      "additionalProperties": false
+    },
+    "ApprovalPreview": {
+      "description": "What the person is asked to approve. Every word comes from the action's declaration (its title, description and input schema labels), never from the model (ADR-0228 §2.2).",
+      "type": "object",
+      "properties": {
+        "title": { "type": "string" },
+        "consequence": { "description": "What running it does, from the declaration.", "type": "string" },
+        "arguments": { "type": "array", "items": { "$ref": "#/$defs/ApprovalPreviewArgument" } },
+        "readback": {
+          "description": "One sentence composed from the fields above, read or sent verbatim on a conversation channel.",
+          "type": "string"
+        }
+      },
+      "required": ["title", "arguments", "readback"],
+      "additionalProperties": false
+    },
+    "ApprovalEffect": {
+      "description": "The effect the approval is for: the action's declared effect kind (ADR-0226 §2.6, `transaction` for an irreversible external act), or `write` when it declares none.",
+      "type": "string",
+      "minLength": 1
+    },
+    "PendingApprovalInput": {
+      "description": "A call waiting for the person's approval, as the worker stores it (`POST /internal/approvals`).",
+      "type": "object",
+      "properties": {
+        "approvalId": { "description": "Equals the tool call id.", "type": "string" },
+        "toolCallId": { "type": "string" },
+        "conversationId": { "type": "string" },
+        "turnId": { "type": "string" },
+        "userId": { "description": "The user whose turn made the call: the only one who may decide it.", "type": "string" },
+        "tool": { "type": "string" },
+        "args": { "type": "object", "additionalProperties": true },
+        "argsHash": { "description": "`argsHash(args)`; the store checks it.", "$ref": "#/$defs/ArgsHash" },
+        "effect": { "$ref": "#/$defs/ApprovalEffect" },
+        "destructive": { "type": "boolean" },
+        "argsSensitive": {
+          "description": "Whether the arguments may be written to logs. They are only when the declaration says they are not sensitive.",
+          "type": "boolean"
+        },
+        "expiresAt": { "description": "Epoch ms, at most 30 minutes away (`MAX_APPROVAL_TTL_MS`).", "type": "number" },
+        "preview": { "$ref": "#/$defs/ApprovalPreview" }
+      },
+      "required": [
+        "approvalId",
+        "toolCallId",
+        "conversationId",
+        "turnId",
+        "userId",
+        "tool",
+        "args",
+        "argsHash",
+        "effect",
+        "destructive",
+        "argsSensitive",
+        "expiresAt",
+        "preview"
+      ],
+      "additionalProperties": false
+    },
+    "ApprovalRequiredEvent": {
+      "description": "`agent:approval_required`: the worker stopped the turn at a call that needs the person's approval. The approval card renders it.",
+      "type": "object",
+      "properties": {
+        "turnId": { "type": "string" },
+        "conversationId": { "type": "string" },
+        "approvalId": { "type": "string" },
+        "tool": { "type": "string" },
+        "effect": { "$ref": "#/$defs/ApprovalEffect" },
+        "destructive": { "type": "boolean" },
+        "preview": { "$ref": "#/$defs/ApprovalPreview" },
+        "expiresAt": { "type": "number" },
+        "timestamp": { "type": "number" }
+      },
+      "required": ["turnId", "conversationId", "approvalId", "tool", "effect", "destructive", "preview", "expiresAt", "timestamp"],
+      "additionalProperties": false
+    },
+    "ApprovalDecidePayload": {
+      "description": "`approval:decide`, from the person's own socket: the card's click.",
+      "type": "object",
+      "properties": { "approvalId": { "type": "string" }, "decision": { "$ref": "#/$defs/ApprovalDecision" } },
+      "required": ["approvalId", "decision"],
+      "additionalProperties": false
+    },
+    "ApprovalRefusalReason": {
+      "description": "Why an approval was refused:\n\n- `unknown`: no such pending approval: never stored, already declined or redeemed, or expired and gone.\n- `forbidden`: another user's approval, or another conversation's.\n- `expired`.\n- `decided`: already decided.\n- `used`: already redeemed.\n- `invalid`: not a token this environment signed, or malformed.\n- `mismatch`: signed, but not for the stored call.\n- `channel`: a decision from a channel that may not make it.",
+      "enum": ["unknown", "forbidden", "expired", "decided", "used", "invalid", "mismatch", "channel"]
+    },
+    "ApprovalRefusal": {
+      "type": "object",
+      "properties": {
+        "ok": { "const": false },
+        "reason": { "$ref": "#/$defs/ApprovalRefusalReason" },
+        "error": { "type": "string" }
+      },
+      "required": ["ok", "reason", "error"],
+      "additionalProperties": false
+    },
+    "ApprovalDecideResult": {
+      "description": "The answer to a decision. An approval's token goes only to the decider: the socket that clicked, or the engine that asked.",
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": {
+            "ok": { "const": true },
+            "decision": { "const": "approve" },
+            "approvalId": { "type": "string" },
+            "token": { "description": "The single-use token the continuation turn redeems.", "type": "string" },
+            "argsHash": { "description": "What the browser checks a UI action's params against before it runs it.", "$ref": "#/$defs/ArgsHash" },
+            "expiresAt": { "type": "number" },
+            "channel": { "$ref": "#/$defs/ApprovalChannel" }
+          },
+          "required": ["ok", "decision", "approvalId", "token", "argsHash", "expiresAt", "channel"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": { "ok": { "const": true }, "decision": { "const": "decline" }, "approvalId": { "type": "string" } },
+          "required": ["ok", "decision", "approvalId"],
+          "additionalProperties": false
+        },
+        { "$ref": "#/$defs/ApprovalRefusal" }
+      ]
+    },
+    "ApprovalTokenClaims": {
+      "description": "The token's claims: a compact JWS (HS256), signed with the environment's approval key.",
+      "type": "object",
+      "properties": {
+        "aid": { "description": "The approval id, which is the tool call id.", "type": "string" },
+        "sub": { "description": "The user.", "type": "string" },
+        "cid": { "description": "The conversation.", "type": "string" },
+        "tool": { "type": "string" },
+        "ah": { "description": "The args hash.", "$ref": "#/$defs/ArgsHash" },
+        "eff": { "description": "The effect.", "$ref": "#/$defs/ApprovalEffect" },
+        "ch": { "description": "Where the user confirmed.", "$ref": "#/$defs/ApprovalChannel" },
+        "iat": { "description": "Issued at, epoch seconds.", "type": "integer" },
+        "exp": { "description": "Expires at, epoch seconds.", "type": "integer" },
+        "jti": { "description": "A nonce.", "type": "string" }
+      },
+      "required": ["aid", "sub", "cid", "tool", "ah", "eff", "ch", "iat", "exp", "jti"],
+      "additionalProperties": false
+    },
+    "ApprovedCall": {
+      "description": "What redeeming a token returns: the stored call, exactly, for the worker to run.",
+      "type": "object",
+      "properties": {
+        "approvalId": { "type": "string" },
+        "toolCallId": { "type": "string" },
+        "conversationId": { "type": "string" },
+        "turnId": { "type": "string" },
+        "userId": { "type": "string" },
+        "tool": { "type": "string" },
+        "args": { "type": "object", "additionalProperties": true },
+        "argsHash": { "$ref": "#/$defs/ArgsHash" },
+        "effect": { "$ref": "#/$defs/ApprovalEffect" },
+        "destructive": { "type": "boolean" },
+        "channel": { "$ref": "#/$defs/ApprovalChannel" }
+      },
+      "required": ["approvalId", "toolCallId", "conversationId", "turnId", "userId", "tool", "args", "argsHash", "effect", "destructive", "channel"],
+      "additionalProperties": false
+    },
+    "ApprovalRedeemResult": {
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": { "ok": { "const": true }, "call": { "$ref": "#/$defs/ApprovedCall" } },
+          "required": ["ok", "call"],
+          "additionalProperties": false
+        },
+        { "$ref": "#/$defs/ApprovalRefusal" }
+      ]
+    },
+    "ApprovalStatus": {
+      "description": "An approval's state, for the turn that follows a decision.",
+      "type": "object",
+      "properties": {
+        "approvalId": { "type": "string" },
+        "status": { "enum": ["pending", "approved", "declined"] },
+        "tool": { "type": "string" },
+        "title": { "type": "string" }
+      },
+      "required": ["approvalId", "status", "tool", "title"],
+      "additionalProperties": false
+    },
+    "ApprovalContinuation": {
+      "description": "What a turn that follows a decision carries, outside the message text: the token to redeem, or that the person declined.",
+      "oneOf": [
+        {
+          "type": "object",
+          "properties": { "approvalId": { "type": "string" }, "decision": { "const": "approve" }, "token": { "type": "string" } },
+          "required": ["approvalId", "decision", "token"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "properties": { "approvalId": { "type": "string" }, "decision": { "const": "decline" } },
+          "required": ["approvalId", "decision"],
+          "additionalProperties": false
+        }
+      ]
+    },
+    "ActionRequestApproval": {
+      "description": "What a UI action request carries when it runs an approved call (`OUIActionApproval`): the browser runs a `transaction` or destructive action only when this matches a grant this tab received from its own card click (ADR-0228 §2.2.6).",
+      "type": "object",
+      "properties": {
+        "approvalId": { "type": "string" },
+        "argsHash": { "description": "`argsHash(params)` of the request the user approved.", "$ref": "#/$defs/ArgsHash" }
+      },
+      "required": ["approvalId", "argsHash"],
+      "additionalProperties": false
+    },
+    "ApprovalGrant": {
+      "description": "What the person's approval click gives this tab's OUI runtime (`runtime.grantApproval`, `OUIApprovalGrant`): the request it approved, until it expires.",
+      "type": "object",
+      "properties": {
+        "approvalId": { "type": "string" },
+        "argsHash": { "$ref": "#/$defs/ArgsHash" },
+        "expiresAt": { "description": "Epoch ms after which the grant no longer admits anything.", "type": "number" }
+      },
+      "required": ["approvalId", "argsHash", "expiresAt"],
+      "additionalProperties": false
+    }
+  }
+}