settld 0.1.2 → 0.2.0

package/docs/spec/ReleaseIndex.v1.md

@@ -0,0 +1,32 @@
+# ReleaseIndex.v1
+
+`ReleaseIndex.v1` is a **signed release manifest** for Settld distribution artifacts.
+
+It is a tooling contract (not a bundle protocol object). Its purpose is to make release authenticity verifiable:
+
+- A third party can verify the `ReleaseIndex.v1` signature (rooted in a release signing key).
+- A third party can verify that the release artifacts match the hashes recorded in the index.
+
+## Files
+
+Releases publish:
+
+- `release_index_v1.json` — the `ReleaseIndex.v1` document
+- `release_index_v1.sig` — detached signatures over the canonical JSON bytes of `release_index_v1.json` (single or quorum)
+
+## Canonicalization and signing
+
+- Canonical JSON: RFC8785/JCS-style canonicalization (sorted object keys; no `-0` / non-finite numbers).
+- Signature is over the **SHA-256 digest** of the canonical JSON UTF-8 bytes.
+
+## Relationship to circularity
+
+`ReleaseIndex.v1` intentionally **does not list** itself or its signature as artifacts, to avoid circular hashing.
+
+## Schema
+
+See:
+
+- `docs/spec/schemas/ReleaseIndex.v1.schema.json`
+- `docs/spec/schemas/ReleaseIndexSignature.v1.schema.json`
+- `docs/spec/schemas/ReleaseIndexSignatures.v1.schema.json`

package/docs/spec/ReleaseIndexSignatures.v1.md

@@ -0,0 +1,17 @@
+# ReleaseIndexSignatures.v1
+
+`ReleaseIndexSignatures.v1` is a tooling contract that wraps one or more `ReleaseIndexSignature.v1` entries.
+
+It exists so a single `release_index_v1.sig` file can carry multiple signatures (for quorum-based release signing) without changing `ReleaseIndex.v1`.
+
+## Relationship to `release_index_v1.sig`
+
+`release_index_v1.sig` may contain either:
+
+- a single `ReleaseIndexSignature.v1` object (legacy/single-signature), or
+- a `ReleaseIndexSignatures.v1` object containing `signatures[]`.
+
+## Schema
+
+See `docs/spec/schemas/ReleaseIndexSignatures.v1.schema.json`.
+

package/docs/spec/ReleaseTrust.v1.md

@@ -0,0 +1,13 @@
+# ReleaseTrust.v1
+
+`ReleaseTrust.v1` is a tooling/config document describing which public keys are trusted to sign `ReleaseIndex.v1`.
+
+This trust domain is **separate** from bundle signer governance keys.
+
+`ReleaseTrust.v1` is a legacy/simple format: a mapping of `keyId -> publicKeyPem` with no rotation, revocation, or quorum policy.
+
+For rotation/revocation/quorum, use `ReleaseTrust.v2`.
+
+## Schema
+
+See `docs/spec/schemas/ReleaseTrust.v1.schema.json`.

package/docs/spec/ReleaseTrust.v2.md

@@ -0,0 +1,26 @@
+# ReleaseTrust.v2
+
+`ReleaseTrust.v2` is a tooling/config document describing which public keys are trusted to sign `ReleaseIndex.v1`, including **rotation** and **revocation** semantics.
+
+This trust domain is **separate** from bundle signer governance keys.
+
+## Key evaluation
+
+When verifying a release:
+
+- `signatureTime` is `ReleaseIndex.v1.toolchain.buildEpochSeconds` (an integer Unix epoch time).
+- A trusted key is considered usable only if:
+  - `notBeforeEpochSeconds` is absent or `signatureTime >= notBeforeEpochSeconds`
+  - `notAfterEpochSeconds` is absent or `signatureTime <= notAfterEpochSeconds`
+  - `revokedAtEpochSeconds` is absent or `signatureTime < revokedAtEpochSeconds`
+
+## Quorum policy
+
+`policy.minSignatures` specifies how many **valid** signatures from trusted, usable keys are required to accept the release index.
+
+If `policy.requiredKeyIds` is present, each listed `keyId` must appear among the valid signatures as well.
+
+## Schema
+
+See `docs/spec/schemas/ReleaseTrust.v2.schema.json`.
+

package/docs/spec/RemoteSignerRequest.v1.md

@@ -0,0 +1,21 @@
+# RemoteSignerRequest.v1 (tooling contract)
+
+This document defines the **stdio wrapper** request shape for delegated signing.
+
+It is a tooling contract used when invoking a signer as a local process (stdin/stdout). HTTP signers use the endpoint-specific request/response schemas referenced in `REMOTE_SIGNER.md`.
+
+Schema: `docs/spec/schemas/RemoteSignerRequest.v1.schema.json`.
+
+## Shape
+
+- `schemaVersion` (optional): `"RemoteSignerRequest.v1"`
+- `op`: `"publicKey"` or `"sign"`
+- If `op === "publicKey"`:
+  - `keyId`: string
+- If `op === "sign"`:
+  - `body`: `RemoteSignerSignRequest.v1`
+
+## Determinism + safety
+
+- Requests must be **purpose-bound** (see `RemoteSignerSignRequest.v1`).
+- Producers must treat this as a pure signing oracle interface; secrets must never be embedded in bundles.

package/docs/spec/RemoteSignerResponse.v1.md

@@ -0,0 +1,16 @@
+# RemoteSignerResponse.v1 (tooling contract)
+
+This document defines the **stdio wrapper** response shape for delegated signing.
+
+Schema: `docs/spec/schemas/RemoteSignerResponse.v1.schema.json`.
+
+## Shape
+
+- A `RemoteSignerResponse.v1` is one of:
+  - `RemoteSignerPublicKeyResponse.v1` (for `op=publicKey` requests)
+  - `RemoteSignerSignResponse.v1` (for `op=sign` requests)
+
+## Notes
+
+- Stdio signers should return a non-zero exit code on failure and write a concise error to stderr.
+- Producers must not depend on stderr text for behavior; only structured JSON should be treated as a stable contract.

package/docs/spec/ReputationEvent.v1.md

@@ -0,0 +1,63 @@
+# ReputationEvent.v1
+
+`ReputationEvent.v1` is an append-only, deterministic artifact for recording economic reputation facts tied to settlement and dispute lifecycle changes.
+
+It is intentionally facts-first: consumers aggregate event streams into scores and risk models without mutating historical records.
+
+## Fields
+
+Required:
+
+- `schemaVersion` (const: `ReputationEvent.v1`)
+- `artifactType` (const: `ReputationEvent.v1`)
+- `artifactId` (must equal `eventId`)
+- `eventId` (deterministic ID)
+- `tenantId`
+- `occurredAt` (ISO datetime)
+- `eventKind`
+  - `decision_approved`
+  - `decision_rejected`
+  - `holdback_auto_released`
+  - `dispute_opened`
+  - `verdict_issued`
+  - `adjustment_applied`
+- `subject`
+  - `agentId` (reputation subject)
+  - optional `toolId`
+  - optional `counterpartyAgentId`
+  - optional `role` (`payee|payer|arbiter|system`)
+- `sourceRef`
+  - `kind` (producer-defined reference namespace)
+  - optional stable references (`artifactId`, `sourceId`, `hash`, `agreementHash`, `receiptHash`, `holdHash`, `decisionHash`, `verdictHash`, `runId`, `settlementId`, `disputeId`, `caseId`, `adjustmentId`)
+  - must include at least one stable reference besides `kind`
+- `facts` (object; structured event facts used for aggregation)
+- `eventHash` (sha256 hex over immutable event core)
+
+Optional fields are omitted when absent.
+
+## Hashing
+
+`eventHash` is computed as sha256 of RFC 8785 canonical JSON excluding:
+
+- `eventHash`
+- `artifactHash` (storage-level hash, if present)
+
+## Deterministic ID Conventions
+
+Recommended deterministic IDs for kernel v0 conformance:
+
+- decision: `rep_dec_${decisionHash}`
+- holdback auto-release: `rep_rel_${agreementHash}`
+- dispute opened: `rep_dsp_${agreementHash}`
+- verdict issued: `rep_vrd_${verdictHash}`
+- adjustment applied: `rep_adj_${adjustmentId}`
+
+## Invariants
+
+- Events are append-only and immutable.
+- Re-issuing the same event source must produce the same `eventId` and `eventHash`.
+- Persistence must treat duplicate `eventId` with same hash as idempotent.
+
+## Schema
+
+See `docs/spec/schemas/ReputationEvent.v1.schema.json`.

package/docs/spec/RevocationList.v1.md

@@ -0,0 +1,28 @@
+# RevocationList.v1
+
+This document provides **prospective** revocation and rotation semantics for signer keys, while preserving historical acceptance when a verifier can prove the signing time.
+
+## File location (bundles)
+
+`governance/revocations.json`
+
+This file is included in the bundle manifest (i.e., it is part of the immutable payload), and it is intentionally **not** under `verify/**`.
+
+## Schema
+
+See `schemas/RevocationList.v1.schema.json`.
+
+## Semantics (v1)
+
+- `revocations[]` declares a key as revoked at `revokedAt`.
+- `rotations[]` declares that an old key is superseded at `rotatedAt` and a new key becomes valid from that time.
+
+Strict verification rule:
+
+- A key revoked at time **T** is NOT acceptable for signatures made at or after **T**.
+- A signature made before **T** remains acceptable **only if** the bundle contains a trustworthy signing time for that signature (see `TimestampProof.v1`).
+
+## Signing + trust (strict verification)
+
+`RevocationList.v1` is signed by a governance root key (trusted out-of-band by the verifier).
+

package/docs/spec/SIGNER_PROVIDER_PLUGIN.md

@@ -0,0 +1,32 @@
+# Signer provider plugins (tooling contract)
+
+Signer provider plugins extend `settld-produce` with custom key custody and signing implementations (KMS/HSM/Vault/remote approval flows) without changing bundle protocol objects.
+
+This is a **tooling** contract (not protocol v1). Verifiers remain unchanged.
+
+## CLI usage
+
+`settld-produce --signer plugin --signer-plugin <path|package> [--signer-plugin-export createSignerProvider] [--signer-plugin-config <json>] --gov-key-id <id> --server-key-id <id> ...`
+
+## Plugin contract
+
+Your plugin must export a function (default name: `createSignerProvider`):
+
+- Signature: `async createSignerProvider({ config, env }) -> provider`
+
+Where `provider` is an object implementing:
+
+- `async getPublicKeyPem({ keyId }) -> publicKeyPem`
+- `async sign({ keyId, algorithm, messageBytes, purpose, context }) -> { signatureBase64, signerReceipt? }`
+
+Notes:
+
+- `messageBytes` are the exact bytes to sign (typically 32 bytes: sha256 of canonical JSON).
+- `purpose` is required and must be enforced by the provider (refuse unknown purposes).
+- Do not log or return private key material.
+
+## Packaging guidance
+
+- If `--signer-plugin` is a path, it is resolved relative to the current working directory.
+- If `--signer-plugin` is a package name, it must be resolvable via Node module resolution (installed in the environment where `settld-produce` runs).
+

package/docs/spec/STRICTNESS.md

@@ -0,0 +1,68 @@
+# Strict vs Non-Strict Verification
+
+This document defines the **compatibility contract** for verifier behavior.
+
+## Definitions
+
+- **Strict mode**: missing/invalid protocol surfaces are hard failures.
+- **Non-strict mode**: verifier performs best-effort verification and emits **warnings** for legacy or incomplete bundles, but still rejects tampering (e.g., manifest hash mismatch, file hash mismatch).
+
+## Contract matrix (v1 protocol era)
+
+### Proof bundles (JobProofBundle.v1, MonthProofBundle.v1)
+
+| Surface | Strict | Non-strict |
+|---|---:|---:|
+| `manifest.json` present + `manifestHash` correct | required (fail) | required (fail) |
+| `manifest.json` file hashes correct | required (fail) | required (fail) |
+| trusted governance root keys provided out-of-band | required (fail) | best-effort (warn + continue) |
+| `governance/policy.json` present | required (fail) | best-effort (warn + continue) |
+| `governance/policy.json` version | **must be `GovernancePolicy.v2`** (fail) | allow `GovernancePolicy.v1` (warn + continue) |
+| `governance/policy.json` signature (governance root) | required (fail) | not required (no check) |
+| `governance/revocations.json` present + signature | required (fail) | not required (no check) |
+| `attestation/bundle_head_attestation.json` present + valid | required (fail) | best-effort (warn + continue) |
+| `verify/verification_report.json` present + signed | required (fail) | best-effort (warn + continue if missing; verify if present) |
+
+### Finance packs (FinancePackBundle.v1)
+
+| Surface | Strict | Non-strict |
+|---|---:|---:|
+| `manifest.json` present + `manifestHash` correct | required (fail) | required (fail) |
+| `manifest.json` file hashes correct | required (fail) | required (fail) |
+| trusted governance root keys provided out-of-band | required (fail) | best-effort (warn + continue) |
+| `governance/policy.json` present | required (fail) | best-effort (warn + continue) |
+| `governance/policy.json` version | **must be `GovernancePolicy.v2`** (fail) | allow `GovernancePolicy.v1` (warn + continue) |
+| `governance/policy.json` signature (governance root) | required (fail) | not required (no check) |
+| `governance/revocations.json` present + signature | required (fail) | not required (no check) |
+| `attestation/bundle_head_attestation.json` present + valid | required (fail) | best-effort (warn + continue) |
+| `verify/verification_report.json` present + signed | required (fail) | best-effort (warn + continue if missing; verify if present) |
+
+### Invoice bundles (InvoiceBundle.v1)
+
+| Surface | Strict | Non-strict |
+|---|---:|---:|
+| `manifest.json` present + `manifestHash` correct | required (fail) | required (fail) |
+| `manifest.json` file hashes correct | required (fail) | required (fail) |
+| trusted governance root keys provided out-of-band | required (fail) | best-effort (warn + continue) |
+| `governance/policy.json` present | required (fail) | best-effort (warn + continue) |
+| `governance/policy.json` version | **must be `GovernancePolicy.v2`** (fail) | allow `GovernancePolicy.v1` (warn + continue) |
+| `governance/policy.json` signature (governance root) | required (fail) | not required (no check) |
+| `governance/revocations.json` present + signature | required (fail) | not required (no check) |
+| `attestation/bundle_head_attestation.json` present + valid | required (fail) | best-effort (warn + continue) |
+| `verify/verification_report.json` present + signed | required (fail) | best-effort (warn + continue if missing; verify if present) |
+| `pricing/pricing_matrix_signatures.json` present + valid buyer signature(s) (`PricingMatrixSignatures.v2` required; `PricingMatrixSignatures.v1` legacy accepted only non-strict with `WARN_PRICING_SIGNATURE_V1_BYTES_LEGACY`) | required (fail) | best-effort (warn + continue if missing) |
+
+### Close packs (ClosePack.v1)
+
+| Surface | Strict | Non-strict |
+|---|---:|---:|
+| ClosePack `manifest.json` present + `manifestHash` correct | required (fail) | required (fail) |
+| ClosePack manifest file hashes correct | required (fail) | required (fail) |
+| trusted governance root keys provided out-of-band | required (fail) | best-effort (warn + continue) |
+| ClosePack governance policy surfaces | required (fail) | best-effort (warn + continue) |
+| ClosePack head attestation present + valid | required (fail) | best-effort (warn + continue) |
+| ClosePack verification report present + signed | required (fail) | best-effort (warn + continue if missing; verify if present) |
+| embedded `payload/invoice_bundle/**` strictly verifies under same posture | required (fail) | required (fail) |
+| `evidence/evidence_index.json` present + matches deterministic recomputation | required (fail) | required (fail) |
+| SLA evaluation surfaces (`sla/*`) | optional; if present must recompute + match | optional; missing emits `CLOSE_PACK_SLA_SURFACES_MISSING_LENIENT` |
+| acceptance evaluation surfaces (`acceptance/*`) | optional; if present must recompute + match | optional; missing emits `CLOSE_PACK_ACCEPTANCE_SURFACES_MISSING_LENIENT` |

package/docs/spec/SUPPLY_CHAIN.md

@@ -0,0 +1,33 @@
+# Supply chain: releases
+
+This doc describes what Settld release authenticity *does* and *does not* guarantee.
+
+## Threat model (release channel)
+
+### Assets
+
+- Authenticity of published release artifacts (`*.tgz`, conformance pack, audit packet, etc.)
+- Integrity of the mapping: “this tool install corresponds to this commit/release”
+
+### Attacks prevented (assuming release signing key not compromised)
+
+- Artifact swap: attacker replaces one or more release artifacts after build
+- Checksum swap: attacker replaces artifacts *and* checksums together
+- CI compromise without release key access: attacker can run arbitrary steps but cannot forge a valid `ReleaseIndex.v1` signature
+
+### Attacks not prevented
+
+- Release signing key compromise (attacker can sign malicious artifacts)
+- Compromised dependency supply chain *before* release build (mitigated by lockfiles/SBOM, not eliminated)
+
+## Operational response
+
+If the release signing key is suspected compromised:
+
+- Rotate the release signing key and publish an updated `ReleaseTrust.v2` (and revoke the compromised key).
+- Publish a security advisory describing impacted releases and mitigation steps.
+
+## How to verify a release (high-level)
+
+1. Verify `release_index_v1.sig` against `release_index_v1.json` using a trusted `ReleaseTrust.v2`.
+2. Verify each artifact’s `sha256` matches the index.

package/docs/spec/SettlementAdjustment.v1.md

@@ -0,0 +1,45 @@
+# SettlementAdjustment.v1
+
+`SettlementAdjustment.v1` is a deterministic, idempotent adjustment artifact that applies a single escrow operation against funds held in a related `FundingHold.v1`.
+
+Sprint 21 uses exactly one adjustment per `agreementHash` for tool-call holdback disputes.
+
+## Fields
+
+Required:
+
+- `schemaVersion` (const: `SettlementAdjustment.v1`)
+- `adjustmentId` (deterministic ID; for tool-call holdback: `sadj_agmt_${agreementHash}_holdback`)
+- `tenantId`
+- `agreementHash` (sha256 hex)
+- `receiptHash` (sha256 hex)
+- `holdHash` (sha256 hex)
+- `kind` (`holdback_release|holdback_refund`)
+- `amountCents` (non-negative int; must be `<= heldAmountCents` at application time)
+- `currency`
+- `createdAt` (ISO datetime)
+- `adjustmentHash` (sha256 hex; computed from immutable core)
+
+Optional:
+
+- `verdictRef`:
+  - `caseId`
+  - `verdictHash` (sha256 hex)
+- `metadata` (implementation-defined JSON object)
+
+## Hashing
+
+`adjustmentHash` is computed as sha256 of the RFC 8785 canonical JSON of the core object excluding:
+
+- `adjustmentHash`
+- `metadata`
+
+## Invariants
+
+- Adjustments must operate on held escrow funds only (no negative balances, no external clawbacks).
+- Persistence must enforce uniqueness for `adjustmentId` per tenant; duplicates must be treated as idempotent retries returning the existing adjustment.
+
+## Schema
+
+See `docs/spec/schemas/SettlementAdjustment.v1.schema.json`.
+

package/docs/spec/SettlementDecisionRecord.v1.md

@@ -0,0 +1,48 @@
+# SettlementDecisionRecord.v1
+
+`SettlementDecisionRecord.v1` is the canonical decision artifact for an `AgentRunSettlement.v1` state transition.
+
+It binds one settlement decision to:
+
+- the settlement principal (`settlementId`, `runId`, `tenantId`),
+- the governing policy/verifier references,
+- and the execution lineage (`runLastEventId`, `runLastChainHash`, `resolutionEventId`).
+
+## Purpose
+
+- make settlement decisions replayable and attributable;
+- bind payout/refund decisions to specific run/settlement lineage;
+- provide a stable hash (`decisionHash`) for downstream receipt binding.
+
+## Required fields
+
+- `schemaVersion` (const: `SettlementDecisionRecord.v1`)
+- `decisionId`
+- `tenantId`
+- `runId`
+- `settlementId`
+- `decisionStatus`
+- `decisionMode`
+- `policyRef`
+- `verifierRef`
+- `workRef`
+- `decidedAt`
+- `decisionHash`
+
+Optional fields:
+
+- `agreementId`
+- `decisionReason`
+- `verificationStatus`
+
+## Canonicalization and hashing
+
+`decisionHash` is computed over canonical JSON after removing `decisionHash` from the object:
+
+1. canonicalize JSON with RFC 8785 (JCS),
+2. hash canonical UTF-8 bytes using `sha256`,
+3. encode as lowercase hex.
+
+## Schema
+
+See `schemas/SettlementDecisionRecord.v1.schema.json`.

package/docs/spec/SettlementDecisionRecord.v2.md

@@ -0,0 +1,53 @@
+# SettlementDecisionRecord.v2
+
+`SettlementDecisionRecord.v2` is the canonical decision artifact for an `AgentRunSettlement.v1` state transition.
+
+It is identical in semantic intent to `SettlementDecisionRecord.v1`, but adds **replay-critical policy pinning** so decisions can be re-evaluated deterministically from protocol artifacts alone.
+
+## Purpose
+
+- make settlement decisions replayable and attributable;
+- bind payout/refund decisions to specific run/settlement lineage;
+- provide a stable hash (`decisionHash`) for downstream receipt binding;
+- pin the **exact policy hash used** during evaluation (`policyHashUsed`).
+
+## Required fields
+
+- `schemaVersion` (const: `SettlementDecisionRecord.v2`)
+- all required fields from `SettlementDecisionRecord.v1`
+- `policyHashUsed` (sha256 hex, lowercase)
+
+Optional fields:
+
+- all optional fields from `SettlementDecisionRecord.v1`
+- `policyNormalizationVersion` (string; OPTIONAL; v2 emitters SHOULD include this to pin the normalization algorithm used to compute `policyHashUsed`)
+- `profileHashUsed` (sha256 hex, lowercase; OPTIONAL; emit when an authorization/policy profile fingerprint is available, for example `bindings.spendAuthorization.policyFingerprint`)
+- `verificationMethodHashUsed` (sha256 hex, lowercase; OPTIONAL; omit when absent)
+- `bindings` (object; OPTIONAL) - settlement receipt trail bindings for gateway-style flows:
+  - `authorizationRef`
+  - `token` (`kid`, `sha256`, `expiresAt`)
+  - `request` (`sha256`)
+  - `response` (`status`, `sha256`)
+  - `providerSig` (`required`, `present`, `verified`, `providerKeyId`, `error`)
+  - `reserve` (`adapter`, `mode`, `reserveId`, `status`)
+  - `policyDecisionFingerprint` (`fingerprintVersion`, `policyId`, `policyVersion`, `policyHash`, `verificationMethodHash`, `evaluationHash`)
+
+## Policy pinning rules
+
+- `policyHashUsed` MUST be the hash of the normalized policy object actually evaluated.
+- If the evaluated policy is carried inline (for example, in an agreement payload), `policyHashUsed` MUST match the normalized inline policy payload.
+- If the policy is resolved from a policy registry, `policyHashUsed` MUST match the policy payload referenced by the registry entry.
+- `profileHashUsed`, when present, MUST be the hash of the concrete profile/fingerprint material used to authorize or constrain policy evaluation for this decision.
+- `verificationMethodHashUsed` SHOULD be set when verifier selection depends on an explicit verification method payload.
+
+## Canonicalization and hashing
+
+`decisionHash` is computed over canonical JSON after removing `decisionHash` from the object:
+
+1. canonicalize JSON with RFC 8785 (JCS),
+2. hash canonical UTF-8 bytes using `sha256`,
+3. encode as lowercase hex.
+
+## Schema
+
+See `schemas/SettlementDecisionRecord.v2.schema.json`.

package/docs/spec/SettlementDecisionReport.v1.md

@@ -0,0 +1,44 @@
+# SettlementDecisionReport.v1
+
+`SettlementDecisionReport.v1` is a canonical JSON object that records a buyer’s **Approve/Hold** decision for a specific `InvoiceBundle.v1`.
+
+It is intended to be archived alongside the invoice bundle zip and re-verified later **offline** (without access to the hosted service).
+
+## Purpose
+
+- Provide a portable, cryptographically verifiable receipt of a buyer decision.
+- Bind the decision to a specific invoice bundle instance (mix-and-match defense).
+- Capture the effective hosted verification posture and result summary the decision was made under.
+
+## Core fields
+
+- `schemaVersion = "SettlementDecisionReport.v1"`
+- `decision`: `"approve"` or `"hold"`
+- `decidedAt`: ISO timestamp of the decision action
+- `invoiceBundle` (binding target):
+  - `manifestHash`: invoice bundle manifest hash
+  - `headAttestationHash`: invoice bundle head attestation hash
+- `policy`: effective policy snapshot (requiredMode / failOnWarnings / allowAmberApprovals / requiredPricingMatrixSignerKeyIds / etc.)
+- `verification`: summary slice of the hosted verification output (stable codes)
+- `tool`: `{ name, version, commit }` (best-effort provenance for the hosted verifier build)
+- `actor` (optional): service-level claims about who clicked approve/hold (e.g., email, auth method)
+
+## Report hash + signature
+
+- `reportHash` is computed over the canonical JSON object with `reportHash`, `signature`, `signerKeyId`, and `signedAt` removed.
+- If the report is signed, it includes:
+  - `signature` (base64 Ed25519 signature)
+  - `signerKeyId`
+  - `signedAt`
+
+Signature algorithm:
+
+- The signed message is the bytes of the 32-byte sha256 digest (`reportHash` hex decoded).
+- Algorithm: Ed25519.
+
+## Trust anchors (out-of-band)
+
+To verify a settlement decision report, the verifier needs trusted buyer decision signer public keys out-of-band.
+
+See `TRUST_ANCHORS.md`.
+

package/docs/spec/SettlementKernel.v1.md

@@ -0,0 +1,59 @@
+# SettlementKernel.v1
+
+`SettlementKernel.v1` defines the binding invariants between `AgentRunSettlement.v1`, `SettlementDecisionRecord.v1|v2`, and `SettlementReceipt.v1`.
+
+The kernel is considered valid only when artifact hash integrity, identity binding, and temporal ordering all hold.
+
+## Kernel invariants
+
+- Settlement object exists and has the expected `runId`.
+- `decisionRecord` exists and has a valid `decisionHash` (`sha256` over canonical JSON without `decisionHash`).
+- `decisionRecord.runId` and `decisionRecord.settlementId` match settlement.
+- `settlementReceipt` exists and has a valid `receiptHash` (`sha256` over canonical JSON without `receiptHash`).
+- `settlementReceipt.runId` and `settlementReceipt.settlementId` match settlement.
+- `settlementReceipt.decisionRef` must exist and bind to `decisionRecord` (`decisionId` + `decisionHash`).
+- Temporal ordering must hold:
+  - `decisionRecord.decidedAt` is valid ISO date-time.
+  - `settlementReceipt.createdAt` is valid ISO date-time.
+  - `settlementReceipt.settledAt`, when present, is valid ISO date-time.
+  - `settlementReceipt.createdAt >= decisionRecord.decidedAt`.
+  - `settlementReceipt.settledAt >= decisionRecord.decidedAt` (when present).
+  - `settlementReceipt.settledAt >= settlementReceipt.createdAt` (when present).
+
+## Verification error code semantics
+
+When kernel verification fails, implementations return one or more stable codes:
+
+- `settlement_missing`
+- `settlement_run_id_mismatch`
+- `decision_record_missing`
+- `decision_record_hash_invalid`
+- `decision_record_hash_mismatch`
+- `decision_record_run_id_mismatch`
+- `decision_record_settlement_id_mismatch`
+- `settlement_receipt_missing`
+- `settlement_receipt_hash_invalid`
+- `settlement_receipt_hash_mismatch`
+- `settlement_receipt_run_id_mismatch`
+- `settlement_receipt_settlement_id_mismatch`
+- `settlement_receipt_decision_ref_missing`
+- `settlement_receipt_decision_id_mismatch`
+- `settlement_receipt_decision_hash_mismatch`
+- `decision_record_decided_at_invalid`
+- `settlement_receipt_created_at_invalid`
+- `settlement_receipt_settled_at_invalid`
+- `settlement_receipt_before_decision`
+- `settlement_receipt_settled_before_decision`
+- `settlement_receipt_settled_before_created`
+
+## API-level enforcement
+
+- Settlement mutation routes reject invalid bindings with:
+  - HTTP `409`
+  - error code `SETTLEMENT_KERNEL_BINDING_INVALID`
+  - `details.errors[]` containing kernel verification codes above.
+
+- `/ops/network/command-center` exposes settlement-kernel health via:
+  - `commandCenter.settlement.kernelVerificationErrorCount`
+  - `commandCenter.settlement.kernelVerificationErrorCountsByCode[]`
+  - alert type `settlement_kernel_verification_error_code` when configured thresholds are breached.