settld 0.1.2 → 0.2.0

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/AcceptanceCriteria.v1.md

@@ -0,0 +1,17 @@
+# AcceptanceCriteria.v1
+
+`AcceptanceCriteria.v1` defines buyer-side acceptance rules that can be evaluated deterministically and offline from a JobProof-derived job stream.
+
+In ClosePack bundles, it is stored at `acceptance/acceptance_criteria.json`.
+
+## Criteria kinds (v1)
+
+Each criterion has:
+
+- `criterionId` — stable identifier (string).
+- `kind` — one of:
+  - `PROOF_STATUS_EQUALS`
+  - `SLA_OVERALL_OK`
+
+Criteria are evaluated from embedded JobProof facts and (optionally) an `SlaEvaluation.v1`.
+

package/docs/spec/AcceptanceEvaluation.v1.md

@@ -0,0 +1,10 @@
+# AcceptanceEvaluation.v1
+
+`AcceptanceEvaluation.v1` is a deterministic evaluation of `AcceptanceCriteria.v1` against a specific JobProof instance.
+
+In ClosePack bundles, it is stored at `acceptance/acceptance_evaluation.json`.
+
+## Determinism contract
+
+If `acceptance/*` surfaces are present, verifiers recompute the evaluation and require exact match (canonical JSON) in strict mode.
+

package/docs/spec/AgentEvent.v1.md

@@ -0,0 +1,47 @@
+# AgentEvent.v1
+
+`AgentEvent.v1` defines the append-only run event envelope for autonomous agent execution traces.
+
+Each event is scoped to one run stream (`streamId = runId`) and can be used to reconstruct `AgentRun.v1`.
+
+## Schema
+
+See `schemas/AgentEvent.v1.schema.json`.
+
+## Required fields
+
+- `schemaVersion` (const: `AgentEvent.v1`)
+- `v` (event version, const `1`)
+- `id`
+- `streamId` (run ID)
+- `type`
+- `at` (ISO date-time)
+- `actor` (`type` + `id`)
+- `payload`
+
+## Allowed event types (v1)
+
+- `RUN_CREATED`
+- `RUN_STARTED`
+- `RUN_HEARTBEAT`
+- `EVIDENCE_ADDED`
+- `RUN_COMPLETED`
+- `RUN_FAILED`
+
+## Signature and chain fields
+
+The following fields are optional in `AgentEvent.v1` but reserved for signed chain envelopes:
+
+- `payloadHash`
+- `prevChainHash`
+- `chainHash`
+- `signature`
+- `signerKeyId`
+
+If present, these fields must be verifiable using the same hash/signature model used by Settld chained events.
+
+## Determinism
+
+Event application order is stream order.
+
+When multiple events share the same timestamp, ordering is defined by append order in the stored run stream.

package/docs/spec/AgentIdentity.v1.md

@@ -0,0 +1,62 @@
+# AgentIdentity.v1
+
+`AgentIdentity.v1` defines a portable, tenant-scoped identity record for autonomous agents.
+
+This object is intended to be:
+
+- deterministic (stable field names + required core fields),
+- cryptographically bound (primary verification key is explicit), and
+- reusable across API, SDK, and future trust/reputation surfaces.
+
+## Schema
+
+See `schemas/AgentIdentity.v1.schema.json`.
+
+## Canonicalization and hashing
+
+When `AgentIdentity.v1` is signed or hashed by higher-level protocols:
+
+- canonicalize the JSON with RFC 8785 (JCS),
+- hash canonical UTF-8 bytes with `sha256`,
+- represent digests as lowercase hex.
+
+`AgentIdentity.v1` itself does not require an embedded signature field in v1.
+
+## Required fields
+
+- `schemaVersion` (const: `AgentIdentity.v1`)
+- `agentId` (stable identifier)
+- `tenantId` (tenant scope)
+- `displayName` (human-readable label)
+- `status` (`active` | `suspended` | `revoked`)
+- `owner` (operator linkage)
+- `keys` (primary verification key descriptor)
+- `capabilities` (declared capability identifiers)
+- `createdAt` / `updatedAt` (ISO date-time)
+
+## Owner linkage
+
+`owner` binds the autonomous identity to an accountable controller:
+
+- `ownerType`: `human` | `business` | `service`
+- `ownerId`: stable owner identifier
+
+## Key descriptor
+
+`keys` defines the active verification material for the identity:
+
+- `keyId`: derived or assigned key identifier
+- `algorithm`: currently `ed25519`
+- `publicKeyPem`: PEM-encoded public key
+
+## Optional policy hints
+
+`walletPolicy` carries optional spend/approval constraints for downstream settlement systems:
+
+- `maxPerTransactionCents`
+- `maxDailyCents`
+- `requireApprovalAboveCents`
+
+These fields are optional and non-normative in v1. Implementations MAY enforce them when creating holds/settlements (for example, rejecting a settlement when `amountCents > maxPerTransactionCents` or when an out-of-band approval gate is required above `requireApprovalAboveCents`).
+
+Implementation note (this repo): the Settld API enforces `maxPerTransactionCents`, `maxDailyCents`, and `requireApprovalAboveCents` on settlement/hold creation paths that lock escrow from an agent wallet.

package/docs/spec/AgentPassport.v1.md

@@ -0,0 +1,95 @@
+# AgentPassport.v1
+
+`AgentPassport.v1` defines the portable delegation identity envelope for an autonomous economic actor.
+
+Status: Draft (architecture target; not fully enforced in runtime yet).
+
+## Purpose
+
+`AgentPassport.v1` is the root identity contract used to answer:
+
+- which principal ultimately backs this agent,
+- which keyset currently represents the agent,
+- which delegation root authorizes spend/actions,
+- which capability credentials the agent can present,
+- which policy envelope bounds autonomous execution.
+
+The object is designed to be stable, hash-addressable, and portable across hosts/runtimes.
+
+## Required fields
+
+- `schemaVersion` (const: `AgentPassport.v1`)
+- `passportId`
+- `agentId`
+- `tenantId`
+- `principalRef`
+- `identityAnchors`
+- `delegationRoot`
+- `policyEnvelope`
+- `status`
+- `createdAt`
+- `updatedAt`
+
+## Principal binding
+
+`principalRef` binds the agent to an accountable sponsor:
+
+- `principalType`: `human` | `business` | `service` | `dao`
+- `principalId`: stable principal identifier
+- `jurisdiction`: optional compliance hint (for policy packs)
+
+## Identity anchors
+
+`identityAnchors` defines key discovery and verification roots:
+
+- `did` (optional, DID URI)
+- `jwksUri` (HTTPS URL)
+- `activeKeyId`
+- `keysetHash` (sha256 hex over normalized JWK set)
+
+## Delegation root
+
+`delegationRoot` pins the root authority chain used for autonomous actions:
+
+- `rootGrantId`
+- `rootGrantHash`
+- `issuedAt`
+- `expiresAt` (nullable)
+- `revokedAt` (nullable)
+
+A revoked root (`revokedAt != null`) MUST be treated as non-executable by strict policy engines.
+
+## Capability credentials
+
+`capabilityCredentials` is an optional array of machine-verifiable capability claims. Entries carry:
+
+- `credentialType`
+- `issuer`
+- `credentialRef`
+- `credentialHash`
+- `issuedAt`
+- `expiresAt` (nullable)
+
+## Policy envelope
+
+`policyEnvelope` binds baseline controls before request-level decisions:
+
+- `maxPerCallCents`
+- `maxDailyCents`
+- `allowedRiskClasses` (`read|compute|action|financial`)
+- `requireApprovalAboveCents` (nullable)
+- `allowlistRefs` (optional references to provider/tool policy sets)
+
+## Canonicalization + hashing
+
+When used as an input to signatures or binding hashes:
+
+1. canonicalize JSON with RFC 8785 (JCS),
+2. hash canonical UTF-8 bytes with `sha256`,
+3. encode as lowercase hex.
+
+`AgentPassport.v1` does not require an embedded signature field in v1; signatures are expected in detached envelopes at transport/control layers.
+
+## Schema
+
+See `docs/spec/schemas/AgentPassport.v1.schema.json`.

package/docs/spec/AgentReputation.v1.md

@@ -0,0 +1,59 @@
+# AgentReputation.v1
+
+`AgentReputation.v1` defines a deterministic trust snapshot for a tenant-scoped agent identity.
+
+It is computed from:
+
+- run lifecycle outcomes (`AgentRun.v1`),
+- evidence coverage signals (`AgentRun.v1.evidenceRefs`),
+- escrow/settlement outcomes (`AgentRunSettlement.v1`).
+
+## Schema
+
+See `schemas/AgentReputation.v1.schema.json`.
+
+## Required fields
+
+- `schemaVersion` (const: `AgentReputation.v1`)
+- `agentId`
+- `tenantId`
+- `trustScore` (`0..100`)
+- `riskTier` (`low|guarded|elevated|high`)
+- run counters (`totalRuns`, `terminalRuns`, `createdRuns`, `runningRuns`, `completedRuns`, `failedRuns`)
+- evidence + settlement counters
+- score rates (`runCompletionRatePct`, `evidenceCoverageRatePct`, `settlementReleaseRatePct`)
+- `scoreBreakdown`
+- `computedAt`
+
+## Score semantics (v1)
+
+`trustScore` is a weighted score over bounded integer components:
+
+- run quality (terminal completion rate),
+- settlement quality (release rate over resolved settlements),
+- evidence quality (terminal runs carrying evidence),
+- activity score (bounded by run volume).
+
+Weights in v1 are deterministic and fixed by implementation:
+
+- run quality: 55%
+- settlement quality: 30%
+- evidence quality: 10%
+- activity score: 5%
+
+## Rate nullability
+
+The following fields are `null` when no denominator exists:
+
+- `runCompletionRatePct` (no terminal runs),
+- `evidenceCoverageRatePct` (no terminal runs),
+- `settlementReleaseRatePct` (no resolved settlements),
+- `avgRunDurationMs` (no terminal runs with valid start/end timestamps).
+
+## Canonicalization and hashing
+
+When hashed/signed by higher-level protocols:
+
+- canonicalize JSON via RFC 8785 (JCS),
+- hash canonical UTF-8 bytes using `sha256`,
+- emit lowercase hex digests.

package/docs/spec/AgentReputation.v2.md

@@ -0,0 +1,52 @@
+# AgentReputation.v2
+
+`AgentReputation.v2` extends `AgentReputation.v1` with explicit time windows so discovery and ranking can prioritize recent reliability.
+
+## Schema
+
+See `schemas/AgentReputation.v2.schema.json`.
+
+## Motivation
+
+`AgentReputation.v1` is all-time only. Marketplace ranking needs recency-aware scoring to prevent stale historical performance from dominating fresh outcomes.
+
+`AgentReputation.v2` adds:
+
+- fixed windows: `7d`, `30d`, `allTime`,
+- a `primaryWindow` selector,
+- top-level `trustScore`/`riskTier` projected from `primaryWindow`.
+
+## Required fields
+
+- `schemaVersion` (const: `AgentReputation.v2`)
+- `agentId`
+- `tenantId`
+- `primaryWindow` (`7d|30d|allTime`)
+- `trustScore` (`0..100`)
+- `riskTier` (`low|guarded|elevated|high`)
+- `windows` (object with required keys: `7d`, `30d`, `allTime`)
+- `computedAt`
+
+Each `windows.<window>` entry includes the same deterministic metrics surface as `AgentReputation.v1` (counts, rates, score breakdown, trust score).
+
+## Window semantics
+
+- `7d`: includes events with observed timestamps in the trailing 7 days.
+- `30d`: includes events with observed timestamps in the trailing 30 days.
+- `allTime`: includes all observations.
+
+Run observations use terminal time when available (`completedAt` or `failedAt`) and fall back to run update timestamps.
+Settlement observations use `resolvedAt` for resolved states and `lockedAt` for locked states.
+
+## Compatibility
+
+- `AgentReputation.v1` remains stable for existing integrations.
+- APIs may default to `v1` for back-compat and require explicit `reputationVersion=v2` for windowed behavior.
+
+## Canonicalization and hashing
+
+When hashed/signed by higher-level protocols:
+
+- canonicalize JSON via RFC 8785 (JCS),
+- hash canonical UTF-8 bytes using `sha256`,
+- emit lowercase hex digests.

package/docs/spec/AgentRun.v1.md

@@ -0,0 +1,47 @@
+# AgentRun.v1
+
+`AgentRun.v1` defines a deterministic snapshot of a single autonomous run executed by a registered agent identity.
+
+It is designed to be:
+
+- portable across services and SDKs,
+- reconstructable from an append-only event stream,
+- directly consumable by verification and settlement workflows.
+
+## Schema
+
+See `schemas/AgentRun.v1.schema.json`.
+
+## Required fields
+
+- `schemaVersion` (const: `AgentRun.v1`)
+- `runId`
+- `agentId`
+- `tenantId`
+- `status` (`created|running|completed|failed`)
+- `createdAt`
+- `updatedAt`
+
+## Event-derived semantics
+
+`AgentRun.v1` is treated as a derived snapshot from `AgentEvent.v1` events in the run stream.
+
+- `created` is set by `RUN_CREATED`.
+- `running` is set by `RUN_STARTED` (or heartbeat if started exists).
+- `completed` is terminal and set by `RUN_COMPLETED`.
+- `failed` is terminal and set by `RUN_FAILED`.
+
+After a terminal state (`completed|failed`), non-terminal state transitions are invalid.
+
+## Evidence linkage
+
+`evidenceRefs` is an optional deterministic list of evidence references attached by events.
+Each ref is an opaque string in v1; higher-level protocols may enforce path/hash semantics.
+
+## Canonicalization and hashing
+
+When hashed/signed by higher-level objects:
+
+- canonicalize JSON via RFC 8785 (JCS),
+- hash canonical UTF-8 bytes using `sha256`,
+- emit lowercase hex digests.