settld 0.1.5 → 0.2.0

package/docs/plans/2026-02-21-agent-economic-actor-operating-model.md

@@ -0,0 +1,169 @@
+# Agent Economic Actor Operating Model (v1)
+
+Date: 2026-02-21  
+Owner: Product + Platform + Risk
+
+## Why this model
+
+Goal: let agents spend and act with much more autonomy while keeping actions bounded, auditable, and reversible.
+
+Settld does this by treating autonomy as a controlled envelope:
+
+1. identity + delegation,
+2. policy-bound authorization,
+3. deterministic evidence + receipts,
+4. dispute/reversal recourse.
+
+## How customers are served
+
+Primary user groups:
+
+1. Agent builders: quick setup, policy profiles, paid tool calls, receipts.
+2. Platform/runtime teams: central controls across hosts, no-bypass enforcement.
+3. Ops/finance/risk/compliance: audit exports, dispute workflows, deterministic reconciliation.
+4. Design partners: staged rollout with fail-closed release gates.
+
+## Deployment modes
+
+### Mode A: Hosted control plane + managed wallet (default)
+- `settld setup --wallet-mode managed --wallet-bootstrap remote`
+- Fastest time-to-first-paid-call, least wallet ops burden.
+
+### Mode B: Hosted control plane + BYO wallet
+- `settld setup --wallet-mode byo`
+- Customer controls custody while Settld enforces trust contract.
+
+### Mode C: Hosted/self-hosted control plane + no wallet rails
+- `settld setup --wallet-mode none`
+- Non-paid trust control path (proof/audit/dispute readiness before spend).
+
+Reference flows:
+- `docs/QUICKSTART_MCP_HOSTS.md`
+- `scripts/setup/onboard.mjs`
+- `services/magic-link/src/server.js`
+
+## Should Settld manage agent wallets?
+
+Answer: optional and policy-dependent.
+
+1. Managed mode: Settld control plane bootstraps wallet provider config and returns runtime env.
+2. BYO mode: customer supplies wallet env/refs; Settld still enforces policy and receipts.
+3. No-wallet mode: only trust/evidence control path is active.
+
+Wallet bootstrap and runtime bootstrap endpoints:
+- `POST /v1/tenants/{tenantId}/onboarding/wallet-bootstrap`
+- `POST /v1/tenants/{tenantId}/onboarding/runtime-bootstrap`
+- `POST /v1/tenants/{tenantId}/onboarding/runtime-bootstrap/smoke-test`
+
+## Should every agent have identity?
+
+Yes.
+
+Identity model (already defined in spec surface):
+
+1. `AgentPassport.v1`: principal binding + active key anchors + delegation root + policy envelope.
+2. `DelegationGrant.v1`: bounded authority transfer (scope, spend limits, depth, revocation).
+3. `ExecutionIntent.v1`: canonical request/risk/spend/policy binding precondition.
+
+Spec anchors:
+- `docs/spec/AgentPassport.v1.md`
+- `docs/spec/DelegationGrant.v1.md`
+- `docs/spec/ExecutionIntent.v1.md`
+
+Runtime anchors:
+- `src/api/app.js` (passport validation, delegation lineage, wallet policy enforcement)
+- `src/core/settlement-kernel.js`
+
+## How wallet assignment should work
+
+Do not default to “1 wallet per agent.”  
+Default to deterministic assignment:
+
+`tenant + environment + profile + risk tier + delegation depth -> sponsorWalletRef + policyRef + policyVersion`
+
+Recommended rules:
+
+1. High-risk financial agents: dedicated sponsor wallet.
+2. Low-risk read/compute agents: pooled sponsor wallet with strict per-call and daily limits.
+3. Delegated child agents: inherited wallet policy with depth checks and tighter caps.
+4. Cross-team isolation: separate wallet by business unit + policy pack.
+
+## How agents get funded
+
+Funding control should be policy-driven, not ad hoc:
+
+1. Prefund sponsor wallet.
+2. Enforce per-call, per-day, and cumulative limits.
+3. Add threshold-based top-up automation.
+4. Lock escrow before authorization where required.
+5. Require deterministic reserve and rollback semantics on failure.
+
+Current code anchors:
+- `src/api/app.js` (`computeX402DailyAuthorizedExposureCents`, wallet policy checks, reserve + rollback)
+- `src/core/money-rail-adapters.js`
+- `src/core/x402-gate.js`
+
+## Setup flow (operator runbook)
+
+1. Tenant bootstrap (runtime key material and tenant setup).
+2. Wallet bootstrap (`managed` local/remote or `byo` env resolution).
+3. Runtime bootstrap (MCP env + host config).
+4. Profile apply (`settld profile ...`) and passport generation.
+5. Host smoke test and first paid call run.
+6. Conformance matrix + release gate checks.
+
+Command anchors:
+- `settld setup`
+- `settld profile init|validate|simulate|apply`
+- `npm run mcp:probe`
+- `settld doctor`
+
+## What this enables agents to do
+
+As autonomy tiers increase, agents can do more actions safely:
+
+### Tier 0 (Observe)
+- Read-only calls, no spend.
+
+### Tier 1 (Bounded spend)
+- Paid tool calls under strict caps and allowlists.
+
+### Tier 2 (Delegated execution)
+- Multi-step workflows with delegation lineage and challenge windows.
+
+### Tier 3 (Conditional autonomy)
+- Challenge/escalate fallback and operator overrides.
+
+### Tier 4 (Programmatic economic actor)
+- Cross-tool/cross-agent spend orchestration with deterministic receipts, disputes, and reversals.
+
+## Hard controls (must stay fail-closed)
+
+1. No policy bypass across MCP stdio, MCP HTTP bridge, and gateway paths.
+2. Authority boundaries: who can sign/revoke/pause/kill-switch.
+3. Adapter invariant conformance for every rail lane.
+4. Determinism soak checks for repeat export/verification.
+5. Onboarding SLO gates for real operator usability.
+
+## What still must be built
+
+1. No-bypass negative matrix as release blocker.
+2. Authority boundary and rollback drill automation.
+3. Shared adapter invariant gate for all rails.
+4. Deterministic repeat-run soak gate.
+5. Onboarding SLO CI gate tied to runtime metrics.
+
+Execution artifacts:
+- `planning/jira/trust-os-v1-gap-closure-backlog.json`
+- `planning/jira/trust-os-v1-gap-closure-tickets.csv`
+- `planning/jira/agent-economic-actor-backlog.json`
+
+## External research references
+
+- Coinbase AgentKit docs: [https://docs.cdp.coinbase.com/agent-kit/docs/welcome](https://docs.cdp.coinbase.com/agent-kit/docs/welcome)
+- Coinbase Agentic Wallet docs: [https://docs.cdp.coinbase.com/agentic-wallet/welcome](https://docs.cdp.coinbase.com/agentic-wallet/welcome)
+- Circle docs: [https://developers.circle.com/](https://developers.circle.com/)
+- Privy docs: [https://docs.privy.io/](https://docs.privy.io/)
+- SPIFFE overview: [https://spiffe.io/docs/latest/spiffe-about/overview/](https://spiffe.io/docs/latest/spiffe-about/overview/)
+- EIP-4337: [https://eips.ethereum.org/EIPS/eip-4337](https://eips.ethereum.org/EIPS/eip-4337)
+

package/docs/plans/2026-02-21-trust-os-v1-strategy.md

@@ -0,0 +1,241 @@
+# Trust OS v1 Strategy
+
+Date: 2026-02-21  
+Owner: Settld Product + Platform
+
+## Positioning
+
+Settld is a Trust OS for autonomous agent actions.  
+It is not a wallet replacement and not a prompt-only guardrail product.
+
+Settld is the control plane that makes agent spending and execution:
+
+1. enforceable,
+2. auditable,
+3. reversible when required,
+4. portable across hosts and payment rails.
+
+## Core Objective
+
+Become the default trust and control layer for paid and high-risk autonomous actions.
+
+Any agent integration should be able to:
+
+1. act with bounded authority,
+2. prove what happened,
+3. emit deterministic receipts,
+4. resolve disputes and apply reversals safely,
+5. pass audit/compliance scrutiny,
+6. plug into real operations workflows.
+
+## Product Direction (Trust OS v1)
+
+Current release focus: terminal-first onboarding + MCP host integration, with deterministic trust guarantees.
+
+### Pillar 1: Policy Runtime Enforcement
+
+Guarantee:
+- Paid and high-risk actions are gated by deterministic decisions (`allow|challenge|deny|escalate`) and stable reason codes.
+
+Implementation anchors:
+- `src/api/app.js`
+- `scripts/mcp/settld-mcp-server.mjs`
+- `src/core/policy.js`
+- `src/core/event-policy.js`
+
+Test/gate anchors:
+- `test/mcp-paid-exa-tool.test.js`
+- `test/mcp-paid-weather-tool.test.js`
+- `test/mcp-paid-llm-tool.test.js`
+- `test/api-e2e-x402-authorize-payment.test.js`
+
+### Pillar 2: Execution Binding + Evidence + Receipts
+
+Guarantee:
+- Request/authorization/policy/decision bindings are hash-addressable and replay/mutation failures are deterministic.
+
+Implementation anchors:
+- `src/core/settlement-kernel.js`
+- `src/core/x402-receipt-verifier.js`
+- `src/core/tool-call-agreement.js`
+- `src/core/tool-call-evidence.js`
+- `docs/spec/SettlementDecisionRecord.v2.md`
+
+Test/gate anchors:
+- `test/settlement-kernel.test.js`
+- `test/x402-receipt-verifier.test.js`
+- `test/api-e2e-proof-strict-settlement-gating.test.js`
+- `test/api-e2e-idempotency-settlement-disputes.test.js`
+
+### Pillar 3: Dispute + Reversal Engine
+
+Guarantee:
+- Dispute lifecycles and verdict outcomes are deterministic, idempotent, and financially safe.
+
+Implementation anchors:
+- `src/api/app.js`
+- `src/core/dispute-open-envelope.js`
+- `src/core/settlement-adjustment.js`
+- `src/core/x402-reversal-command.js`
+- `src/core/x402-provider-refund-decision.js`
+
+Test/gate anchors:
+- `test/api-e2e-tool-call-holdback-arbitration.test.js`
+- `test/api-e2e-x402-gate-reversal.test.js`
+- `test/x402-reversal-command.test.js`
+- `test/arbitration-schemas.test.js`
+
+### Pillar 4: Operator Controls
+
+Guarantee:
+- Challenged/escalated actions have auditable operator paths; emergency controls are explicit and recorded.
+
+Implementation anchors:
+- `src/api/app.js`
+- `src/core/governance.js`
+- `src/core/agent-wallets.js`
+- `src/core/agreement-delegation.js`
+
+Test/gate anchors:
+- `test/api-e2e-ops-kernel-workspace.test.js`
+- `test/api-e2e-ops-arbitration-workspace.test.js`
+- `test/api-e2e-ops-arbitration-workspace-browser.test.js`
+
+### Pillar 5: Rail Adapter Hardening
+
+Guarantee:
+- Rail adapters are pluggable but cannot bypass trust-kernel enforcement.
+
+Implementation anchors:
+- `services/x402-gateway/src/server.js`
+- `src/core/money-rail-adapters.js`
+- `src/core/x402-gate.js`
+- `src/core/wallet-provider-bootstrap.js`
+
+Test/gate anchors:
+- `test/x402-gateway-autopay.test.js`
+- `test/api-e2e-x402-provider-signature.test.js`
+- `test/circle-sandbox-batch-settlement-e2e.test.js`
+- `test/provider-conformance-strict-mode.test.js`
+
+### Pillar 6: Profile-Based Policy UX
+
+Guarantee:
+- Policy profiles are deterministic, testable, and usable from terminal-first workflows.
+
+Implementation anchors:
+- `scripts/profile/cli.mjs`
+- `src/core/profile-templates.js`
+- `src/core/policy-packs.js`
+- `scripts/setup/wizard.mjs`
+
+Test/gate anchors:
+- `test/cli-profile.test.js`
+- `test/setup-wizard.test.js`
+- `docs/QUICKSTART_PROFILES.md`
+
+### Pillar 7: Production Gates
+
+Guarantee:
+- Release readiness is fail-closed when deterministic trust gates regress.
+
+Implementation anchors:
+- `.github/workflows/tests.yml`
+- `.github/workflows/release.yml`
+- `scripts/ci/run-kernel-v0-ship-gate.mjs`
+- `scripts/ci/run-production-cutover-gate.mjs`
+
+Test/gate anchors:
+- `test/production-cutover-gate-script.test.js`
+- `test/throughput-gate-script-reporting.test.js`
+- `test/x402-hitl-smoke-script.test.js`
+- `test/mcp-host-cert-matrix-script.test.js`
+
+## Users (Near Term)
+
+1. Developers and agent builders who need safe paid-action execution.
+2. Platform/runtime teams requiring enforceable controls across hosts.
+3. Finance, ops, risk, and compliance stakeholders needing deterministic evidence.
+4. Design partners running real-money agent spend with incident controls.
+
+## Priority Use Cases
+
+1. Agent-to-tool paid calls with deterministic policy envelopes.
+2. Agent-to-agent settlement with challenge windows and receipts.
+3. Procurement-style bounded spending with approvals/escalations.
+4. API/service consumption under budget and compliance constraints.
+5. Multi-agent workflows with auditable and bounded hop-by-hop execution.
+
+## Explicit Non-Goals
+
+1. Replacing all wallet providers.
+2. Replacing all agent frameworks.
+3. Becoming a single-host feature.
+4. Shipping prompt-only governance without deterministic settlement controls.
+
+## Roadmap (Now -> Long Term)
+
+### Phase 1: Production Core (Now)
+- Close v1 backend gaps.
+- Complete deterministic gates.
+- Finalize terminal-first host onboarding.
+- Harden evidence artifacts for production review.
+
+### Phase 2: Frictionless Adoption (Next)
+- Default managed wallet path where possible.
+- One-command onboarding for Codex/Claude/Cursor/OpenClaw.
+- Strong first verified receipt path.
+- Better operator reliability workflows.
+
+### Phase 3: Platform Expansion
+- Multiple adapter lanes under one trust contract.
+- Richer profile packs + simulation.
+- Tenant automation and enterprise controls.
+
+### Phase 4: Agentverse Infrastructure
+- Cross-runtime inter-agent trust fabric.
+- Cross-tenant dispute/reputation/attestation primitives.
+- Open standards leadership for machine-native commerce trust.
+
+## Decision Record
+
+Chosen approach: trust-kernel-first (policy + evidence + recourse), then rail expansion.
+
+Rejected alternatives:
+1. Rail-first product strategy (faster demo surface but weak durable moat).
+2. Host-specific product strategy (faster initial distribution but no cross-host trust portability).
+
+## Rollout and Rollback
+
+Rollout:
+1. Gate by deterministic CI artifacts and ship-gate checks.
+2. Progress environments only when policy/runtime + evidence + reversal checks pass.
+3. Promote adapter lanes behind conformance and abuse-path coverage.
+
+Rollback:
+1. Fail closed on gate regressions.
+2. Block release promotion if kernel-v0 ship gate or production cutover gate fails.
+3. Revert adapter-specific rollout independently from trust-kernel contract.
+
+## Observability Requirements
+
+1. Policy runtime: decision mix + p50/p95 latency.
+2. Evidence/receipt: deterministic hash drift rate.
+3. Disputes: open backlog, SLA breaches, reversal completion latency.
+4. Rails: authorization failure rates, insolvency/reversal events.
+5. Adoption: time-to-first-verified-receipt, host onboarding success rate.
+
+## Success Criteria
+
+Near term:
+1. Terminal onboarding with minimal off-terminal steps.
+2. End-to-end paid flow with verified receipt and no policy bypass.
+3. Deterministic dispute-to-reversal CI path.
+4. Host compatibility matrix with evidence artifacts.
+5. Production cutover gates green.
+
+Long term:
+1. Settld is the default trust layer across multiple ecosystems.
+2. Teams adopt Settld to reduce operational and compliance burden.
+3. Agent commerce scales without becoming ungovernable.
+

package/docs/research/2026-02-21-agent-spend-host-landscape.md

@@ -0,0 +1,57 @@
+# Agent Spend Host Landscape (2026-02-21)
+
+## Why this matters
+To get Settld adopted, we need to integrate where autonomous spend is already happening and where users already run agents day-to-day.
+
+## What users are running today
+
+### 1) Coding-agent hosts with MCP support are the default surface
+- Codex exposes MCP server setup in CLI (`codex mcp add ...`) and shared config between CLI + IDE extension.
+- Claude Code has first-class MCP server management (`claude mcp add`, `list`, `get`) and scope controls.
+- Cursor supports MCP in editor + CLI (`cursor-agent mcp ...`) with stdio/SSE/HTTP transports.
+
+Implication for Settld:
+- MCP-first distribution is correct.
+- Setup must be one command, host-aware, and idempotent.
+
+### 2) Wallet/payment rails are accelerating and commoditizing
+- Coinbase Agentic Wallet positions CLI/MCP wallet operations with built-in limits and x402 support.
+- Stripe + OpenAI announced Instant Checkout and ACP in ChatGPT (US rollout, Sept 29, 2025).
+- x402 continues to position HTTP-native pay-per-use flows as core agent payment rail.
+
+Implication for Settld:
+- We should not position as "just another wallet".
+- Differentiate with policy runtime, deterministic enforcement, dispute/evidence lifecycle, and cross-host operational safety.
+
+### 3) OpenClaw ecosystem is active but noisier/higher risk
+- OpenClaw docs confirm skills-based extension model and local skill install paths.
+- Community skill/marketplaces and wallet wrappers are growing quickly.
+- Security incidents around malicious skills have been reported in ecosystem media.
+
+Implication for Settld:
+- Keep OpenClaw as a target host, but treat it as higher-risk environment.
+- Emphasize signed policy packs, deterministic receipts, and strict tool/policy constraints.
+
+## Build priorities derived from this landscape
+1. Make `settld setup` fully host-native for Codex/Claude/Cursor/OpenClaw.
+2. Make policy deployment one step from onboarding (starter profile apply + dry-run + live).
+3. Keep MCP smoke validation built in so users know setup is real immediately.
+4. Publish security posture for skill-hosted environments (verification, guardrails, audit proofs).
+5. Avoid wallet-only framing; focus on trust/runtime layer for any wallet/payment rail.
+
+## Confidence notes
+- Official docs/newsroom items are high confidence.
+- Community ecosystem pages indicate direction, but quality varies; use for signal, not sole source of truth.
+
+## Sources
+- OpenAI Docs MCP: https://platform.openai.com/docs/docs-mcp
+- Anthropic Claude Code MCP: https://docs.anthropic.com/en/docs/claude-code/mcp
+- Cursor MCP docs: https://docs.cursor.com/advanced/model-context-protocol
+- Cursor CLI MCP docs: https://docs.cursor.com/cli/mcp
+- Coinbase Agentic Wallet docs: https://docs.cdp.coinbase.com/agentic-wallet/welcome
+- Stripe newsroom (OpenAI Instant Checkout + ACP): https://stripe.com/us/newsroom/news/stripe-openai-instant-checkout
+- x402 docs: https://docs.x402.org/
+- x402 site: https://www.x402.org/
+- OpenClaw skills docs: https://docs.openclaw.ai/skills
+- OpenClaw community directory example: https://www.ruleofclaw.ai/
+- OpenClaw ecosystem incident coverage (secondary source): https://www.tomshardware.com/tech-industry/cyber-security/malicious-moltbot-skill-targets-crypto-users-on-clawhub

package/docs/spec/ArbitrationOutcomeMapping.v1.md

@@ -0,0 +1,62 @@
+# ArbitrationOutcomeMapping.v1
+
+This document freezes deterministic mapping from dispute/arbitration outcomes to settlement directives in Trust OS v1.
+
+## Purpose
+
+Dispute outcomes must produce one unambiguous financial directive so settlement resolution is:
+
+- deterministic,
+- replay-safe,
+- auditable with stable evidence traces.
+
+## Outcome to directive mapping
+
+Input: `AgentRunSettlement.v1.disputeResolution` + settlement `amountCents`
+
+- `outcome=accepted`
+  - directive: `status=released`
+  - `releaseRatePct=100`
+  - `releasedAmountCents=amountCents`
+  - `refundedAmountCents=0`
+- `outcome=rejected`
+  - directive: `status=refunded`
+  - `releaseRatePct=0`
+  - `releasedAmountCents=0`
+  - `refundedAmountCents=amountCents`
+- `outcome=partial`
+  - financial outcome: `reversal`
+  - settlement directive: `status=released`
+  - requires `releaseRatePct` integer in range `1..99`
+  - `releasedAmountCents=floor(amountCents * releaseRatePct / 100)`
+  - `refundedAmountCents=amountCents - releasedAmountCents`
+  - both released/refunded amounts must be non-zero (true split)
+
+## Validation invariants
+
+- `accepted` may include `releaseRatePct` only as `100`.
+- `rejected` may include `releaseRatePct` only as `0`.
+- `partial` must include `releaseRatePct` in `1..99`.
+- `withdrawn|unresolved` must not include `releaseRatePct` and cannot derive settlement directives.
+- `amountCents` must be a positive safe integer when deriving directives.
+
+Invalid combinations fail-closed with stable error code `DISPUTE_OUTCOME_DIRECTIVE_INVALID`.
+
+## Resolve request guardrails
+
+For `/runs/{runId}/settlement/resolve` when a dispute directive exists:
+
+- request `status` may be omitted (derived status is authoritative),
+- explicit `status` must equal derived status,
+- explicit `releaseRatePct`, `releasedAmountCents`, and `refundedAmountCents` must match derived values exactly.
+- if settlement is already resolved and dispute directive is present, dispute status must be `closed`.
+
+Status mismatch fails with `DISPUTE_OUTCOME_STATUS_MISMATCH`.
+Directive amount/rate mismatch fails with `DISPUTE_OUTCOME_AMOUNT_MISMATCH`.
+Resolved-settlement directive precondition mismatch fails with `TRANSITION_ILLEGAL`.
+
+## Determinism requirements
+
+- identical dispute inputs must generate identical directives across retries.
+- idempotency replay for resolve operations must return the same settlement and decision traces.
+- decision traces should include the resolved `disputeSettlementDirective` for audit.

package/docs/spec/DisputeCaseLifecycle.v1.md

@@ -0,0 +1,51 @@
+# DisputeCaseLifecycle.v1
+
+This document freezes dispute + arbitration lifecycle behavior enforced by Trust OS v1 APIs.
+
+## Run dispute lifecycle (`AgentRunSettlement.v1`)
+
+State machine:
+
+- `none -> open`
+- `closed -> open`
+- `open -> closed`
+
+Invalid transitions fail closed with `TRANSITION_ILLEGAL`.
+
+Guard rules:
+
+- Dispute open is allowed only before dispute-window expiry (`DISPUTE_WINDOW_EXPIRED` on expiry).
+- `/runs/{runId}/dispute/open` is rejected when settlement is still locked (`status=locked`).
+- Dispute close requires an active open dispute (and matching `disputeId` when provided).
+- Dispute evidence/escalation updates require an active open dispute.
+- Escalation level cannot downgrade an active dispute.
+
+## Arbitration case lifecycle (`ArbitrationCase.v1`)
+
+Statuses:
+
+- `open`
+- `under_review`
+- `verdict_issued`
+- `closed`
+
+Operational transitions:
+
+- Case creation (`action=open` or `action=appeal`) creates case in `under_review`.
+- Assignment/evidence paths may advance `open -> under_review`.
+- Verdict is accepted only from `open|under_review`, and sets `verdict_issued`.
+- Close is accepted only from `verdict_issued`, and sets `closed`.
+
+Invalid transitions fail closed with `TRANSITION_ILLEGAL`.
+
+Guard rules:
+
+- Arbitration open requires parent dispute status `open`.
+- Appeal requires parent case in `verdict_issued|closed` and valid parent verdict metadata.
+- Verdict and appeal actions are denied after dispute-window expiry (`DISPUTE_WINDOW_EXPIRED`).
+
+## Determinism requirements
+
+- Panel assignment canonicalizes and lexically sorts `panelCandidateAgentIds` before hashing.
+- Candidate reordering must not change `assignmentHash` or chosen arbiter.
+- Transition/window denials emit stable machine codes for replay automation.

package/docs/spec/OperatorAction.v1.md

@@ -0,0 +1,90 @@
+# OperatorAction.v1
+
+`OperatorAction.v1` is the canonical operator-evidence artifact used for high-risk control actions.
+
+It captures who acted, which case was affected, what action was taken, and why. The signed form binds this surface to an Ed25519 signature for offline verification.
+
+## Purpose
+
+`OperatorAction.v1` enables:
+
+- deterministic replay/audit of emergency operator decisions,
+- hash-based tamper detection over a frozen action surface,
+- stable verification codes for schema/key/hash/signature failures.
+
+## Emergency RBAC + dual-control policy
+
+For `/ops/emergency/*` actions, `OperatorAction.v1` is evaluated against runtime authorization policy:
+
+- Role matrix:
+  - `pause|quarantine`: `oncall|ops_admin|incident_commander`
+  - `revoke|kill-switch`: `ops_admin|incident_commander`
+  - `resume`: follows the strictest targeted control class (`ops_admin|incident_commander` when resuming `revoke|kill-switch`)
+- Dual-control:
+  - `revoke|kill-switch` class actions require both `operatorAction` and `secondOperatorAction`.
+  - The two approvals must be from distinct `actor.operatorId` and distinct `signature.keyId`.
+  - Missing or non-distinct second approvals fail closed.
+
+## Required fields
+
+- `schemaVersion` (const: `OperatorAction.v1`)
+- `caseRef`
+  - `kind` (`challenge|dispute|escalation`)
+  - `caseId`
+- `action` (`APPROVE|REJECT|REQUEST_INFO|OVERRIDE_ALLOW|OVERRIDE_DENY`)
+- `justificationCode` (uppercase machine token)
+- `actor`
+  - `operatorId`
+- `actedAt` (ISO 8601 date-time)
+
+Optional:
+
+- `actionId`
+- `justification`
+- `actor.role` (lowercase token)
+- `actor.tenantId`
+- `actor.sessionId`
+- `actor.metadata`
+- `metadata`
+- `signature`
+  - `schemaVersion` (const: `OperatorActionSignature.v1`)
+  - `algorithm` (const: `ed25519`)
+  - `keyId`
+  - `signedAt` (ISO 8601 date-time)
+  - `actionHash` (`sha256` hex)
+  - `signatureBase64`
+
+Optional fields MUST be omitted when absent (not `null`) unless explicitly allowed by schema.
+
+## Canonicalization + hashing
+
+`actionHash` is computed over canonical JSON (RFC 8785 / JCS) of the unsigned `OperatorAction.v1` object.
+
+Hash algorithm: `sha256` over canonical UTF-8 bytes, lowercase hex output.
+
+`actionHash` is carried inside `signature.actionHash` in the signed envelope.
+
+## Signing and verification
+
+Signing (`signOperatorActionV1`) attaches a `signature` object and signs `actionHash` using Ed25519.
+
+Verification (`verifyOperatorActionV1`) enforces:
+
+1. `action.schemaVersion === OperatorAction.v1`,
+2. `action.signature.schemaVersion === OperatorActionSignature.v1`,
+3. `signature.keyId` matches the expected public key id,
+4. `signature.actionHash` equals recomputed hash,
+5. Ed25519 signature verification succeeds.
+
+Failures return stable codes such as:
+
+- `OPERATOR_ACTION_SCHEMA_MISMATCH`
+- `OPERATOR_ACTION_SIGNATURE_SCHEMA_MISMATCH`
+- `OPERATOR_ACTION_KEY_ID_MISMATCH`
+- `OPERATOR_ACTION_HASH_MISMATCH`
+- `OPERATOR_ACTION_SIGNATURE_INVALID`
+- `OPERATOR_ACTION_SCHEMA_INVALID`
+
+## Schema
+
+See `docs/spec/schemas/OperatorAction.v1.schema.json`.