settld 0.1.1 → 0.1.5

package/docs/spec/PricingMatrix.v1.md

@@ -0,0 +1,20 @@
+# PricingMatrix.v1
+
+This matrix is stored at `pricing/pricing_matrix.json` within Invoice bundles.
+
+## Buyer approval (contract-grade terms)
+
+Pricing terms may be buyer-approved via a detached signature surface:
+
+- `pricing/pricing_matrix_signatures.json` (`PricingMatrixSignatures.v2` recommended)
+
+New bundles SHOULD use `PricingMatrixSignatures.v2` (canonical JSON binding; formatting-independent).
+
+See:
+
+- `PricingMatrixSignatures.v2.md`
+- `PricingMatrixSignatures.v1.md` (legacy; binds to raw file bytes)
+
+## Numeric representation
+
+- prices are expressed in minor units (e.g. cents) as base-10 integer strings (no floats).

package/docs/spec/PricingMatrixSignatures.v1.md

@@ -0,0 +1,30 @@
+# PricingMatrixSignatures.v1
+
+This document provides a **buyer signature surface** for pricing terms.
+
+It is stored at:
+
+- `pricing/pricing_matrix_signatures.json` within Invoice bundles.
+
+`PricingMatrixSignatures.v1` is **legacy**: it binds to raw file bytes, so reformatting `pricing/pricing_matrix.json` (pretty-print/minify/different serializer) changes the binding hash.
+
+New bundles SHOULD use `PricingMatrixSignatures.v2` (canonical JSON binding; formatting-independent). See `PricingMatrixSignatures.v2.md`.
+
+## Binding target
+
+`PricingMatrixSignatures.v1` binds to the exact bytes of:
+
+- `pricing/pricing_matrix.json`
+
+The binding hash is:
+
+- `pricingMatrixHash` — **sha256 hex of raw file bytes** of `pricing/pricing_matrix.json` (the same value committed in the bundle `manifest.json` entry for that file).
+
+Each signature in `signatures[]` signs the `pricingMatrixHash` (bytes of the 32-byte sha256 digest) using Ed25519.
+
+## Strict vs non-strict
+
+- **Strict**: verifiers MUST reject this legacy schema version (hard failure). Use `PricingMatrixSignatures.v2` instead.
+- **Non-strict**: verifiers MAY accept this legacy schema version for compatibility, but MUST emit warning `WARN_PRICING_SIGNATURE_V1_BYTES_LEGACY`. Missing signatures MAY be accepted with warning `PRICING_MATRIX_UNSIGNED_LENIENT`.
+
+Invalid signatures are hard failures (security invariant).

package/docs/spec/PricingMatrixSignatures.v2.md

@@ -0,0 +1,29 @@
+# PricingMatrixSignatures.v2
+
+This document provides a **buyer signature surface** for pricing terms.
+
+It is stored at:
+
+- `pricing/pricing_matrix_signatures.json` within Invoice bundles.
+
+## Binding target
+
+`PricingMatrixSignatures.v2` binds to the canonical JSON value of:
+
+- `pricing/pricing_matrix.json` (`PricingMatrix.v1`)
+
+The binding hash is:
+
+- `pricingMatrixCanonicalHash` — `sha256_hex( utf8( canonical_json_stringify(pricing_matrix_json) ) )`
+
+Canonical JSON is RFC 8785 (JCS). See `CANONICAL_JSON.md`.
+
+Each signature in `signatures[]` signs `pricingMatrixCanonicalHash` (bytes of the 32-byte sha256 digest) using Ed25519.
+
+## Strict vs non-strict
+
+- **Strict**: verifiers MUST require this file to exist and MUST require at least one valid signature from a trusted buyer pricing signer key (see `TRUST_ANCHORS.md`).
+- **Non-strict**: missing signatures MAY be accepted with warning `PRICING_MATRIX_UNSIGNED_LENIENT`.
+
+Invalid signatures are hard failures (security invariant).
+

package/docs/spec/ProduceCliOutput.v1.md

@@ -0,0 +1,46 @@
+# ProduceCliOutput.v1
+
+`ProduceCliOutput.v1` is the machine-readable output emitted by `settld-produce --format json`.
+
+This is a public contract intended for CI/pipelines:
+
+- It is JSON Schema defined (see `docs/spec/schemas/ProduceCliOutput.v1.schema.json`).
+- Arrays of `errors[]` and `warnings[]` MUST be deterministically ordered (recommended sort: `(code, path)`).
+- Optional fields MUST be omitted when absent (not `null`) unless the schema explicitly allows `null`.
+
+## High-level shape
+
+- `schemaVersion`: `"ProduceCliOutput.v1"`
+- `tool`: tool identity (best-effort)
+- `mode`: deterministic controls that influenced generation
+- `target`: what was produced and where it was written
+- `ok`: overall success
+- `produceOk`: whether production succeeded (even if `verifyAfter` failed)
+- `verifyAfter` (optional): result of a post-produce verification step when requested
+- `warnings[]`: structured warning codes
+- `errors[]`: structured error codes
+- `result`: summary of produced bundle hashes and identifiers
+
+## Error/warning items (safe diagnostics)
+
+Each item in `errors[]` / `warnings[]` may include:
+
+- `code`: stable, machine-readable code (see `docs/spec/PRODUCER_ERRORS.md`).
+- `causeKind`: coarse category for operators (`signer` | `plugin` | `verify` | `input` | `io` | `internal`).
+- `causeCode`: stable, non-secret subcode identifying the internal failure class (never raw exception text).
+
+Producer tooling MUST NOT embed arbitrary exception strings in stdout JSON output; use `--explain` (stderr) for operator diagnostics.
+
+## `--explain` (deterministic stderr)
+
+`settld-produce --explain` prints a deterministic, non-secret diagnostic summary to **stderr**.
+
+Contract:
+
+- Output is deterministic for the same inputs/environment.
+- Output MUST NOT include secrets (tokens, secret header values, private keys).
+- Output ends with **exactly one** trailing newline.
+
+## Relationship to protocol objects
+
+`ProduceCliOutput.v1` describes tooling behavior; it does not change bundle protocol semantics.

package/docs/spec/ProofBundleManifest.v1.md

@@ -0,0 +1,24 @@
+# ProofBundleManifest.v1 (JobProof / MonthProof)
+
+This manifest is stored at `manifest.json` within JobProof and MonthProof bundles.
+
+## Hashing contract
+
+- `hashing.schemaVersion = "ProofBundleManifestHash.v1"`
+- file order: `path_asc`
+- excludes: `["verify/**"]`
+
+Rationale: `verify/verification_report.json` must reference `manifestHash`, so including `verify/**` in the manifest would create circular hashing.
+
+## manifestHash
+
+`manifestHash = sha256_hex( canonical_json_stringify(manifest_without_hash) )`
+
+## File entries
+
+`files[]` entries include:
+
+- `name` (path relative to bundle root)
+- `sha256` (hex sha256 of raw file bytes)
+- `bytes` (byte length)
+

package/docs/spec/README.md

@@ -0,0 +1,104 @@
+# Settld Protocol Specs
+
+This directory freezes the **wire-format contracts** that Settld emits and verifies (bundles, manifests, attestations, and verification reports).
+
+These specs are written so an independent implementer can build a verifier without reading Settld’s source.
+
+## Canonicalization + hashing (global rules)
+
+- **Canonical JSON**: JSON objects are canonicalized using RFC 8785 (JCS).
+- **Hashing**: all hashes in these specs are `sha256` over UTF-8 bytes of canonical JSON (or raw file bytes, as specified), represented as lowercase hex.
+- **Derived outputs**: bundle manifests intentionally **exclude** `verify/**` to avoid circular hashing; those files are verified out-of-band by signature and by binding to the `manifestHash`.
+
+## Documents
+
+- `CANONICAL_JSON.md` — canonical JSON rules used before hashing/signing.
+- `VERSIONING.md` — tool vs protocol versioning policy (SemVer + protocol object evolution).
+- `REFERENCE_VERIFIER_BEHAVIOR.md` — filesystem/path/ordering rules to prevent cross-impl drift.
+- `REFERENCE_IMPLEMENTATIONS.md` — reference verifier implementations and conformance parity policy.
+- `THREAT_MODEL.md` — explicit threats, mitigations, and residual risks (evidence-backed).
+- `INVARIANTS.md` — checklist mapping protocol claims → spec → code → tests → codes.
+- `MONEY_RAIL_STATE_MACHINE.md` — deterministic payout/collection lifecycle and transition rules.
+- `ESCROW_NETTING_INVARIANTS.md` — deterministic escrow mutation, settlement partition, and netting invariants.
+- `CRYPTOGRAPHY.md` — crypto primitives + byte-level hashing/signing inventory.
+- `VERIFIER_ENVIRONMENT.md` — operational assumptions and hardening guidance.
+- `ProofBundleManifest.v1.md` — JobProof/MonthProof manifest + hashing contract.
+- `FinancePackBundleManifest.v1.md` — FinancePack manifest + hashing contract.
+- `BundleHeadAttestation.v1.md` — signed head commitment for bundles.
+- `GovernancePolicy.v1.md` — signer authorization policy (strict verification).
+- `GovernancePolicy.v2.md` — signer authorization policy (signed by governance root).
+- `RevocationList.v1.md` — prospective revocation/rotation list (signed by governance root).
+- `TimestampProof.v1.md` — trustworthy signing time proof (for historical acceptance).
+- `VerificationReport.v1.md` — signed, machine-ingestible strict verification report.
+- `PricingMatrixSignatures.v2.md` — buyer signature surface for pricing terms in `InvoiceBundle.v1` (canonical JSON binding; recommended).
+- `PricingMatrixSignatures.v1.md` — legacy buyer signature surface (raw bytes binding).
+- `ClosePack.v1.md` — pre-dispute invoice package embedding `InvoiceBundle.v1` + evidence index.
+- `ClosePackManifest.v1.md` — ClosePack manifest + hashing contract.
+- `EvidenceIndex.v1.md` — deterministic evidence reference index for ClosePack.
+- `SlaDefinition.v1.md` / `SlaEvaluation.v1.md` — deterministic SLA rules + evaluation surfaces for ClosePack.
+- `AcceptanceCriteria.v1.md` / `AcceptanceEvaluation.v1.md` — deterministic acceptance rules + evaluation surfaces for ClosePack.
+- `VerifyCliOutput.v1.md` — `settld-verify --format json` machine output contract.
+- `VerifyAboutOutput.v1.md` — `settld-verify --about --format json` tool metadata contract.
+- `ProduceCliOutput.v1.md` — `settld-produce --format json` machine output contract.
+- `ToolManifest.v1.md` — signed tool/capability manifest that can be pinned by hash.
+- `ToolCallAgreement.v1.md` — hash-addressable agreement binding a tool call (`callId` + `inputHash`) to settlement terms.
+- `ToolCallEvidence.v1.md` — hash-addressable evidence binding a tool call output (`outputHash`) to an agreement hash.
+- `AgentIdentity.v1.md` — portable autonomous agent identity contract.
+- `AgentPassport.v1.md` — delegated identity envelope binding principal, keyset anchors, delegation root, and policy envelope.
+- `DelegationGrant.v1.md` — deterministic delegated-authority grant contract (scope + spend + chain + validity).
+- `ExecutionIntent.v1.md` — canonical pre-execution intent contract binding request fingerprint, risk profile, and policy/spend envelope.
+- `AgentWallet.v1.md` — deterministic autonomous wallet snapshot contract.
+- `AgentRun.v1.md` — deterministic agent run snapshot contract.
+- `AgentEvent.v1.md` — append-only event envelope for agent runs.
+- `AgentRunSettlement.v1.md` — deterministic run escrow/settlement contract.
+- `MarketplaceOffer.v2.md` — canonical pre-contract offer artifact derived from negotiation proposals.
+- `MarketplaceAcceptance.v2.md` — canonical acceptance artifact bound to a `MarketplaceOffer.v2` hash.
+- `SettlementDecisionRecord.v1.md` — legacy settlement decision artifact (historical verification).
+- `SettlementDecisionRecord.v2.md` — settlement decision artifact with replay-critical policy pinning (current).
+- `SettlementReceipt.v1.md` — canonical settlement finality receipt bound to a decision hash.
+- `FundingHold.v1.md` — deterministic escrow hold for holdback/challenge-window workflows.
+- `SettlementAdjustment.v1.md` — deterministic, idempotent adjustment artifact for held-funds release/refund.
+- `SettlementKernel.v1.md` — binding invariants + stable verification error semantics for settlement decision/receipt integrity.
+- `ArbitrationCase.v1.md` — formal arbitration case contract with appeal linkage.
+- `DisputeOpenEnvelope.v1.md` — signed dispute opener-proof envelope bound to tool-call hold/receipt/agreement hashes.
+- `ArbitrationVerdict.v1.md` — signed arbitration verdict contract with appeal references.
+- `ReputationEvent.v1.md` — append-only, deterministic economic reputation fact artifact.
+- `AgentReputation.v1.md` — deterministic trust score snapshot derived from runs + settlement outcomes.
+- `AgentReputation.v2.md` — reputation with recency windows (`7d`, `30d`, `allTime`) for marketplace ranking.
+- `InteractionDirectionMatrix.v1.md` — frozen `4x4` directional interaction matrix (`agent|human|robot|machine`).
+- `TenantSettings.v2.md` — Magic Link / Verify Cloud tenant configuration contract (current).
+- `TenantSettings.v1.md` — legacy (still accepted for stored settings migration).
+- `WARNINGS.md` — warning codes (closed set) and semantics.
+- `ERRORS.md` — error codes (stable identifiers) and semantics.
+- `PRODUCER_ERRORS.md` — producer/tooling error codes (stable identifiers) and semantics.
+- `x402-error-codes.v1.txt` — stable x402 authorize-payment / execution-intent API error codes.
+- `STRICTNESS.md` — strict vs non-strict verification contract.
+- `TRUST_ANCHORS.md` — verifier trust anchors and out-of-band key injection.
+- `TOOL_PROVENANCE.md` — tool version/commit derivation rules.
+- `REMOTE_SIGNER.md` — tooling contract for remote/delegated signing (no private keys on disk).
+- `RemoteSignerRequest.v1.md` / `RemoteSignerResponse.v1.md` — versioned stdio wrapper contract for process-based signers.
+- `SIGNER_PROVIDER_PLUGIN.md` — tooling contract for signer provider plugins (KMS/HSM/Vault integrations).
+- `ReleaseIndex.v1.md` — signed release manifest (artifact authenticity).
+- `ReleaseIndexSignatures.v1.md` — detached multi-signature wrapper for `ReleaseIndex.v1`.
+- `ReleaseTrust.v1.md` — trusted release signing keys (legacy/simple mapping).
+- `ReleaseTrust.v2.md` — trusted release signing keys with rotation/revocation + quorum.
+- `SUPPLY_CHAIN.md` — release-channel threat model and verification procedure.
+
+## Legacy archive
+
+Legacy protocol objects are retained under `docs/spec/legacy/` (including `legacy/schemas/`) for historical verification only.
+Current integrations should use the active specs listed above.
+
+## Schemas + examples
+
+- `schemas/` contains JSON Schema for the on-disk JSON documents.
+- `examples/` contains minimal example instances (illustrative, not authoritative vectors).
+
+## Quickstart
+
+See `docs/QUICKSTART_VERIFY.md` for a CI-friendly verifier quickstart using `settld-verify --format json`.
+
+## Conformance + audit evidence
+
+- Conformance oracle: `conformance/v1/README.md`
+- Audit packet (specs + vectors + conformance + checksums): `npm run audit:packet`

package/docs/spec/REFERENCE_IMPLEMENTATIONS.md

@@ -0,0 +1,29 @@
+# Reference implementations
+
+Settld’s protocol is intended to be language/toolchain independent.
+
+This repo contains multiple verifier implementations that are expected to agree on `conformance/v1/`:
+
+## JavaScript (Node)
+
+- CLI: `packages/artifact-verify/bin/settld-verify.js`
+- Conformance runner: `node conformance/v1/run.mjs --node-bin packages/artifact-verify/bin/settld-verify.js`
+- Release authenticity CLI: `packages/artifact-verify/bin/settld-release.js`
+- Release conformance runner: `node conformance/v1/run-release.mjs --release-node-bin packages/artifact-verify/bin/settld-release.js`
+
+## Python
+
+- CLI: `reference/verifier-py/settld-verify-py`
+- Conformance runner: `node conformance/v1/run.mjs --bin reference/verifier-py/settld-verify-py`
+
+## Parity policy
+
+- Verifier behavior is specified by:
+  - `STRICTNESS.md`
+  - `REFERENCE_VERIFIER_BEHAVIOR.md`
+  - `WARNINGS.md`
+  - `ERRORS.md` / `error-codes.v1.txt`
+- Conformance is the executable oracle; implementations must match the expected outcomes for all cases.
+- CLI output is a tooling contract (`VerifyCliOutput.v1`); output must be deterministic for the same inputs.
+
+Release authenticity verification (`settld-release verify`) is currently implemented in Node and gated by release conformance.

package/docs/spec/REFERENCE_VERIFIER_BEHAVIOR.md

@@ -0,0 +1,68 @@
+# Reference Verifier Behavior (v1)
+
+This document specifies **portable verifier behavior** for areas where independent implementations tend to drift (filesystem semantics, path handling, and manifest evaluation order).
+
+It complements:
+
+- `CANONICAL_JSON.md` (RFC 8785 / JCS)
+- `STRICTNESS.md` (strict vs non-strict contract)
+- `TRUST_ANCHORS.md` (trust root injection)
+- `WARNINGS.md` (warning code contract)
+- `conformance/v1/` (executable oracle)
+
+## Bundle-relative paths (manifest `files[].name`)
+
+The manifest `files[].name` values describe **bundle-relative** file paths.
+
+An implementation:
+
+1. MUST treat `files[].name` as a **portable** path using `/` as the separator (regardless of host OS).
+2. MUST reject any `files[].name` that is empty or not a string.
+3. MUST reject any `files[].name` that starts with `/` (absolute path).
+4. MUST reject any `files[].name` that contains `\` (backslash), `:` (Windows drive / URI ambiguity), or `\u0000` (NUL).
+5. MUST reject any `files[].name` that ends with `/` (directory marker).
+6. MUST reject any `files[].name` containing a `.` or `..` segment (path traversal).
+7. MUST resolve each `files[].name` against the bundle root and MUST reject any entry that escapes the bundle root (even if it “looks relative”).
+8. MUST treat a manifest containing a rejected path as a hard failure in **both** strict and non-strict modes.
+
+Conformance expects such failures to surface as `MANIFEST_PATH_INVALID`.
+
+## Duplicate manifest entries
+
+1. MUST treat duplicate `files[].name` values as invalid.
+2. MUST treat duplicate-path manifests as a hard failure in **both** strict and non-strict modes.
+
+Conformance expects such failures to surface as `MANIFEST_DUPLICATE_PATH`.
+
+## Symlinks
+
+1. MUST NOT follow filesystem symlinks when verifying a manifest-listed file.
+2. MUST treat any manifest-listed path that resolves to a symlink (at the filesystem level) as invalid in **both** strict and non-strict modes (this is a security invariant, not a compatibility affordance).
+
+Conformance expects such failures to surface as `MANIFEST_SYMLINK_FORBIDDEN`.
+
+## File hashing semantics
+
+1. MUST hash file contents as **raw bytes** (no newline normalization, no UTF-8 re-encoding).
+2. MUST treat missing files referenced by the manifest as verification failures.
+3. MUST ignore filesystem metadata (mtime, permissions) for hashing and matching purposes.
+
+## Manifest evaluation order (error precedence)
+
+To keep behavior stable and portable, implementations:
+
+1. MUST validate manifest structure (path validity and duplicate-path checks) **before** reporting hash-binding mismatches (for example, before `manifestHash mismatch` / attestation binding checks).
+2. MUST then compute and compare `manifestHash` using canonical JSON (RFC 8785) exactly as specified in `ProofBundleManifest.v1.md` / `FinancePackBundleManifest.v1.md`.
+
+This ordering prevents ambiguous “first failure wins” behavior across implementations and is relied upon by `conformance/v1/`.
+
+## Trust anchors (portable minimum)
+
+1. MUST support out-of-band injection of trusted governance roots via `SETTLD_TRUSTED_GOVERNANCE_ROOT_KEYS_JSON` (see `TRUST_ANCHORS.md`).
+2. MUST treat missing trusted governance roots as a hard failure in strict mode when governance-root signatures are required.
+
+## Strict vs non-strict (portable minimum)
+
+1. MUST apply strict/non-strict downgrades only where explicitly documented in `STRICTNESS.md`.
+2. MUST NOT downgrade the security invariants in this document (path traversal, duplicate paths, symlink refusal).
+

package/docs/spec/REMOTE_SIGNER.md

@@ -0,0 +1,66 @@
+# Remote signer (tooling contract)
+
+This document specifies the **RemoteSigner API** used by producer tooling (`settld-produce`) to obtain signatures without storing private keys on disk.
+
+This is a tooling/config surface (not a bundle protocol object). Verifiers do not change: they still verify signatures using **public keys** and **trust anchors**.
+
+## Goals
+
+- Allow bundle production with **no private key material on disk** (CI-friendly).
+- Ensure signing requests are **purpose-bound** (avoid turning the signer into a generic signing oracle).
+- Keep requests deterministic and auditable via a stable request shape.
+
+## Endpoints (v1)
+
+### `GET /v1/public-key?keyId=<keyId>`
+
+Return the public key PEM for the requested key id.
+
+Response: `RemoteSignerPublicKeyResponse.v1` (see `docs/spec/schemas/RemoteSignerPublicKeyResponse.v1.schema.json`).
+
+### `POST /v1/sign`
+
+Sign the provided message bytes under a specific key and purpose.
+
+Request: `RemoteSignerSignRequest.v1` (see `docs/spec/schemas/RemoteSignerSignRequest.v1.schema.json`).
+
+Response: `RemoteSignerSignResponse.v1` (see `docs/spec/schemas/RemoteSignerSignResponse.v1.schema.json`).
+
+## Purpose binding (required)
+
+Remote signers **MUST** refuse signing requests with unknown `purpose` values.
+
+Producer tools set `purpose` to one of:
+
+- `event_payload`
+- `governance_policy`
+- `revocation_list`
+- `timestamp_proof`
+- `pricing_matrix`
+- `bundle_head_attestation`
+- `verification_report`
+- `settlement_decision_report`
+
+## Security notes
+
+- The `messageBase64` value is **the exact bytes signed**. For Settld bundle objects this is typically `sha256(canonical_json)` represented as raw 32 bytes.
+- Signers should log: `requestId`, `keyId`, `purpose`, and selected `context` fields for auditability.
+- Remote signer endpoints should be protected with authentication/authorization (otherwise they are a signing oracle).
+
+## Authentication (recommended)
+
+For HTTP signers, producer tooling can attach a bearer token and custom headers:
+
+- `--signer-auth bearer --signer-token-env SETTLD_SIGNER_TOKEN`
+- `--signer-auth bearer --signer-token-file /path/to/token.txt`
+- `--signer-header "X-Request-Source: ci"`
+
+Tokens and secret header values are tooling-only; they must never be written into bundles or CLI JSON outputs.
+
+## Local-process / stdio signers
+
+Producer tooling also supports invoking a signer as a local process (no HTTP) where the signer reads a JSON request from stdin and prints JSON to stdout.
+
+This mode is designed for CI environments where binding/listening to local sockets may be restricted, and for integrations where the signer itself talks to an HSM/KMS.
+
+Note: some sandboxed CI environments disable piping stdin into child processes. The reference dev signer (`settld-signer-dev`) supports `--request-json-base64 <b64>` to avoid stdin piping in those environments.

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).
+