settld 0.1.2 → 0.2.0

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

@@ -0,0 +1,43 @@
+# DisputeOpenEnvelope.v1
+
+`DisputeOpenEnvelope.v1` is the signed opener-proof artifact for tool-call arbitration case creation.
+
+It binds the dispute subject (`agreementHash`, `receiptHash`, `holdHash`) and opener identity into a deterministic, replayable signature envelope.
+
+## Required fields
+
+- `schemaVersion` (const: `DisputeOpenEnvelope.v1`)
+- `artifactType` (const: `DisputeOpenEnvelope.v1`)
+- `artifactId` (must equal `envelopeId`)
+- `envelopeId`
+- `caseId`
+- `tenantId`
+- `agreementHash` (sha256 hex)
+- `receiptHash` (sha256 hex)
+- `holdHash` (sha256 hex)
+- `openedByAgentId`
+- `openedAt` (ISO date-time)
+- `reasonCode` (stable machine code, uppercase snake-case)
+- `nonce` (caller-generated uniqueness value)
+- `signerKeyId`
+- `envelopeHash` (sha256 over canonical envelope core)
+- `signature` (base64 Ed25519 signature over `envelopeHash`)
+
+## Deterministic IDs
+
+- Recommended envelope ID convention for tool-call disputes:
+  - `dopen_case_${caseId}`
+
+## Canonicalization and hashing
+
+1. Build canonical core object excluding `envelopeHash`, `signature`, and `artifactHash`.
+2. Compute `envelopeHash = sha256(canonical-json(core))`.
+3. Verify `signature` against `envelopeHash` using `signerKeyId` public key.
+
+## Verification requirements
+
+- `openedByAgentId` must match the signer agent identity key referenced by `signerKeyId`.
+- Subject hashes in envelope must match the arbitration-open request + hold bindings.
+- For non-admin opens, a valid `DisputeOpenEnvelope.v1` is required.
+
+See `docs/spec/schemas/DisputeOpenEnvelope.v1.schema.json`.

package/docs/spec/ERRORS.md

@@ -0,0 +1,76 @@
+# Verifier Errors (v1)
+
+This document defines the **stable error-code contract** for `settld-verify`.
+
+- **Warnings** are documented separately in `WARNINGS.md`.
+- In machine output (`VerifyCliOutput.v1`), errors appear in `errors[]` as `{ code, path?, message?, detail? }`.
+- **Stability guarantee**: error `code` meanings are stable within protocol v1 unless a deliberate, documented protocol change is made.
+
+## Severity model
+
+- Errors are **fatal**: they indicate verification did not establish required guarantees.
+- Some errors may only be reachable in strict mode (because non-strict may downgrade certain missing surfaces into warnings); see `STRICTNESS.md`.
+
+## Core error codes (high-value contract)
+
+These codes are relied on by fixtures, conformance packs, and CI consumers.
+
+- `MANIFEST_PATH_INVALID` — A manifest entry path is unsafe/invalid (absolute/traversal/escape/backslash/colon). Remediation: regenerate bundle; do not accept the bundle as structurally safe. Evidence: conformance security cases.
+- `MANIFEST_DUPLICATE_PATH` — Manifest contains duplicate `files[].name`. Remediation: regenerate bundle with unique paths. Evidence: conformance security cases.
+- `MANIFEST_PATH_CASE_COLLISION` — Manifest contains file paths that collide under case-insensitive normalization (e.g. `A.txt` vs `a.txt`). Remediation: regenerate bundle with case-unique paths; do not rely on case sensitivity for protocol semantics.
+- `MANIFEST_SYMLINK_FORBIDDEN` — A manifest-listed file is a symlink. Remediation: bundle must contain regular files only; remove symlinks and regenerate. Evidence: conformance security cases.
+
+- `sha256 mismatch` — A manifest-listed file hash does not match actual bytes. Remediation: bundle was tampered with or incorrectly generated; regenerate bundle. Evidence: strict-fail tamper fixtures/conformance.
+- `missing file` — Manifest references a file that does not exist. Remediation: bundle is incomplete; regenerate bundle. Evidence: strict required file enumeration + file hashing.
+
+- `manifestHash mismatch` — The embedded `manifestHash` does not match the computed manifest hash (canonical JSON). Remediation: bundle is inconsistent/tampered; regenerate bundle.
+
+- `verification report subject.manifestHash mismatch` — Receipt binds to a different manifest than the bundle. Remediation: do not mix receipts across bundles; re-verify/generate receipt for this bundle.
+- `verification report bundleHeadAttestation.attestationHash mismatch` — Receipt binds to a different head attestation than the bundle. Remediation: do not mix attestations across bundles; re-verify/generate receipt for this bundle.
+
+- `strict requires trusted governance root keys` — Strict verification requires trust roots but they were not provided. Remediation: provide `SETTLD_TRUSTED_GOVERNANCE_ROOT_KEYS_JSON` (see `TRUST_ANCHORS.md`). Evidence: conformance trust cases.
+- `governance policy signerKeyId not trusted` — Governance policy signature cannot be validated under provided trust roots. Remediation: correct/pin trust roots; verify policy provenance.
+
+- `attestation signer not authorized` — Bundle head attestation signer is not allowed by policy. Remediation: update governance policy or use an authorized signer; regenerate bundle.
+- `verification report signer not authorized` — Receipt signer is not allowed by policy. Remediation: update governance policy or use an authorized verifier signer; regenerate receipt.
+
+- `missing verify/verification_report.json` — A required verification receipt is absent. Remediation: (strict) regenerate the bundle/receipt; (non-strict) expect `VERIFICATION_REPORT_MISSING_LENIENT` warning instead of failure.
+- `signer keyId not allowed by policy` — The signer key is not allowlisted by governance policy. Remediation: update policy allowlist or sign with an authorized key.
+- `SIGNER_REVOKED` — The signer is revoked as-of the effective signing time. Remediation: rotate keys and re-sign; ensure timestampProof is present when verifying historical signatures.
+- `SIGNING_TIME_UNPROVABLE` — Verification cannot establish a trustworthy signing time required for a revocation timeline decision. Remediation: include a valid `timestampProof` or adjust policy to not require a trustworthy time for the decision.
+
+- `PRICING_MATRIX_SIGNATURE_MISSING` — Strict verification requires `pricing/pricing_matrix_signatures.json` (`PricingMatrixSignatures.v2` recommended; `PricingMatrixSignatures.v1` legacy) but it is absent from the manifest. Remediation: include buyer-approved pricing signatures (see `PricingMatrixSignatures.v2.md`) or use compat mode with an explicit warning posture.
+- `PRICING_MATRIX_SIGNATURE_V1_BYTES_LEGACY_STRICT_REJECTED` — Strict verification rejects legacy `PricingMatrixSignatures.v1` (raw-bytes binding) because it is formatting-fragile and creates operational footguns. Remediation: migrate to `PricingMatrixSignatures.v2` (canonical JSON binding) and re-bundle.
+- `PRICING_MATRIX_SIGNATURE_PAYLOAD_MISMATCH` — The pricing matrix signature surface is present, but its declared binding hash does not match the pricing matrix payload (either raw bytes for `PricingMatrixSignatures.v1` or canonical JSON for `PricingMatrixSignatures.v2`). Remediation: regenerate the signature surface from the intended pricing matrix payload and ensure the bundle contains the intended pricing matrix value.
+- `PRICING_MATRIX_SIGNATURE_INVALID` — The pricing matrix signature surface is present and hash-bound correctly, but at least one trusted signature failed to verify. Remediation: regenerate signatures using the correct buyer key(s) and ensure verifiers trust the corresponding public keys (see `TRUST_ANCHORS.md`).
+
+- `invoice pricing code unknown` — Metering references a code that has no price in `PricingMatrix.v1`. Remediation: update pricing to cover all metered codes or fix the metering report.
+- `invoiceClaim totalCents mismatch` — `InvoiceClaim.v1.totalCents` does not match deterministic recomputation from metering+pricing. Remediation: regenerate the claim from the bound inputs.
+- `metering evidenceRef sha256 mismatch` — A metering evidence reference does not match the embedded JobProof manifest’s committed file hash. Remediation: regenerate metering evidence refs and/or re-embed the correct JobProof bundle.
+- `closepack evidence_index mismatch` — `EvidenceIndex.v1` does not match deterministic recomputation from the embedded Invoice+JobProof evidence bindings. Remediation: regenerate ClosePack’s `evidence/evidence_index.json` from the embedded inputs; treat mismatch as a tamper/inconsistency.
+
+- `FAIL_ON_WARNINGS` — CLI `--fail-on-warnings` converted warnings into a failure. Remediation: address warnings or remove gating for your posture.
+
+## How to troubleshoot (support loop)
+
+When filing an issue or investigating a pilot failure, capture:
+
+1. `settld-verify --about --format json`
+2. The full `VerifyCliOutput.v1` JSON (`--format json`)
+3. How trust roots were provided (env vars / trust file) and which root keys were intended
+4. Installation mode: npm install vs npm tarball vs from source
+
+Key fields in `VerifyCliOutput.v1` that enable diagnosis:
+
+- `errors[].code` — stable machine reason (this doc).
+- `errors[].detail` — structured context (expected/actual hashes, missing paths, signer ids).
+- `summary.manifestHash` — integrity anchor for “what was verified.”
+- `tool.version` / `tool.commit` — provenance for “what did the verifying.”
+
+## Full registry (exhaustive)
+
+The authoritative list of error codes that may be emitted as `VerifyCliOutput.v1.errors[].code` is maintained in:
+
+- `docs/spec/error-codes.v1.txt`
+
+This file is **machine-checked** by tests to prevent accidental drift (see Sprint 13 “v1 freeze” discipline).

package/docs/spec/ESCROW_NETTING_INVARIANTS.md

@@ -0,0 +1,71 @@
+# Escrow + Netting Invariants
+
+This document defines deterministic money invariants for escrow movement and netting windows.
+
+It is the Sprint 0 contract for `STLD-T006`.
+
+## Escrow wallet invariants
+
+For wallet fields:
+- `availableCents`
+- `escrowLockedCents`
+- `totalCreditedCents`
+- `totalDebitedCents`
+
+all values MUST remain non-negative integers.
+
+### Lock invariant
+
+Locking `amountCents = A` MUST satisfy:
+- `availableCents' = availableCents - A`
+- `escrowLockedCents' = escrowLockedCents + A`
+- `totalCreditedCents' = totalCreditedCents`
+- `totalDebitedCents' = totalDebitedCents`
+
+### Release invariant (payer -> payee)
+
+Releasing `A` from payer escrow to payee MUST satisfy:
+- payer: `escrowLockedCents' = escrowLockedCents - A`
+- payer: `totalDebitedCents' = totalDebitedCents + A`
+- payee: `availableCents' = availableCents + A`
+- payee: `totalCreditedCents' = totalCreditedCents + A`
+
+### Refund invariant
+
+Refunding `A` to the payer wallet MUST satisfy:
+- `escrowLockedCents' = escrowLockedCents - A`
+- `availableCents' = availableCents + A`
+- `totalCreditedCents' = totalCreditedCents + A`
+
+## Settlement partition invariants
+
+For one `AgentRunSettlement.v1` with principal `amountCents = P`:
+
+- Exactly one terminal resolution from `locked` to `released|refunded`.
+- Terminal partition MUST satisfy:
+  - `releasedAmountCents + refundedAmountCents = P`
+  - both values are non-negative integers.
+- `releaseRatePct` MUST remain integer `0..100`.
+
+## Held exposure rollforward invariant
+
+At period close:
+
+`endingHeld = openingHeld + newLocks - releases - forfeits`
+
+Rollforward generation MUST be deterministic for identical event streams.
+
+## Netting window invariants
+
+For each `(tenant, counterparty, currency, window)`:
+
+- Window membership is deterministic and replay-stable.
+- `windowNetCents = inflowCents - outflowCents`.
+- A net close operation MUST be idempotent (same input set -> same net artifact).
+- No operation may appear in more than one closed netting window.
+
+## Failure handling invariants
+
+- Insufficient available balance MUST fail before lock mutation.
+- Insufficient escrow balance MUST fail before release/refund mutation.
+- Invalid settlement partition MUST fail before persistence.

package/docs/spec/EvidenceIndex.v1.md

@@ -0,0 +1,20 @@
+# EvidenceIndex.v1
+
+`EvidenceIndex.v1` is a deterministic, audit-friendly index of evidence references implied by:
+
+- the embedded JobProof event stream (evidence capture events), and
+- the embedded Invoice bundle’s metering evidence references (file paths + hashes).
+
+In ClosePack bundles, it is stored at `evidence/evidence_index.json`.
+
+## Purpose
+
+The index exists so consumers (buyers, auditors) can quickly answer:
+
+- “What evidence exists for this job?”
+- “Which in-bundle files were referenced for billing math?”
+
+## Privacy posture
+
+Evidence references may contain sensitive URLs. ClosePack indexes should avoid embedding secrets directly; use hashes where appropriate.
+

package/docs/spec/ExecutionIntent.v1.md

@@ -0,0 +1,90 @@
+# ExecutionIntent.v1
+
+`ExecutionIntent.v1` defines the canonical pre-execution authorization target for autonomous tool calls.
+
+Status: Draft (architecture target; not fully enforced in runtime yet).
+
+## Purpose
+
+`ExecutionIntent.v1` bridges planning and policy enforcement by pinning:
+
+- exact request fingerprint target,
+- risk class and expected side-effect profile,
+- spend/loss bounds,
+- policy binding used for authorization,
+- replay-critical temporal/idempotency context.
+
+It is the object policy engines/risk engines should evaluate before minting spend authorization.
+
+## Required fields
+
+- `schemaVersion` (const: `ExecutionIntent.v1`)
+- `intentId`
+- `tenantId`
+- `agentId`
+- `requestFingerprint`
+- `riskProfile`
+- `spendBounds`
+- `policyBinding`
+- `idempotencyKey`
+- `nonce`
+- `expiresAt`
+- `createdAt`
+- `intentHash`
+
+Optional:
+
+- `runId`
+- `agreementHash`
+- `quoteId`
+
+## Request fingerprint
+
+`requestFingerprint` captures immutable request identity:
+
+- `canonicalization` (`rfc8785-jcs`)
+- `method`
+- `path`
+- `querySha256`
+- `bodySha256`
+- `requestSha256`
+
+`requestSha256` SHOULD represent the canonical hash used by authorization tokens in strict request-binding mode.
+
+## Risk profile
+
+`riskProfile` includes:
+
+- `riskClass`: `read|compute|action|financial`
+- `sideEffecting`: boolean
+- `expectedDeterminism`: `deterministic|bounded_nondeterministic|open_nondeterministic`
+- `maxLossCents`
+- `requiresHumanApproval`: boolean
+
+## Spend bounds + policy binding
+
+`spendBounds`:
+
+- `currency`
+- `maxAmountCents`
+
+`policyBinding`:
+
+- `policyId`
+- `policyVersion`
+- `policyHash`
+- `verificationMethodHash`
+
+Together they define the deterministic authorization envelope used in decision receipts.
+
+## Canonicalization + hashing
+
+`intentHash` is computed over canonical JSON of the full object excluding `intentHash`:
+
+1. canonicalize JSON with RFC 8785 (JCS),
+2. hash canonical UTF-8 bytes with `sha256`,
+3. encode lowercase hex.
+
+## Schema
+
+See `docs/spec/schemas/ExecutionIntent.v1.schema.json`.

package/docs/spec/FinancePackBundleManifest.v1.md

@@ -0,0 +1,24 @@
+# FinancePackBundleManifest.v1
+
+This manifest is stored at `manifest.json` within FinancePack bundles.
+
+## Hashing contract
+
+- `hashing.schemaVersion = "FinancePackBundleManifestHash.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 FinancePack bundle root)
+- `sha256` (hex sha256 of raw file bytes)
+- `bytes` (byte length)
+

package/docs/spec/FundingHold.v1.md

@@ -0,0 +1,60 @@
+# FundingHold.v1
+
+`FundingHold.v1` represents a deterministic, wallet-backed escrow hold created for a specific settlement subject (for Sprint 21: tool-call holdback).
+
+It is designed to support:
+
+- A bounded challenge window (`challengeWindowMs`) after hold creation.
+- Automatic release of held funds if no dispute is opened before the window ends.
+- Freeze of auto-release while a related arbitration case remains open.
+- Resolution via an idempotent, deterministic `SettlementAdjustment.v1` keyed by `agreementHash`.
+
+## Fields
+
+Required:
+
+- `schemaVersion` (const: `FundingHold.v1`)
+- `tenantId`
+- `agreementHash` (sha256 hex, lowercase)
+- `receiptHash` (sha256 hex, lowercase)
+- `payerAgentId`
+- `payeeAgentId`
+- `amountCents` (gross amount for the subject)
+- `heldAmountCents` (portion held in escrow; must be `<= amountCents`)
+- `currency`
+- `holdbackBps` (basis points, 0..)
+- `challengeWindowMs` (0..)
+- `createdAt` (ISO datetime)
+- `holdHash` (sha256 hex; computed from the immutable core)
+- `status` (`held|released|refunded`)
+- `revision` (non-negative int)
+- `updatedAt` (ISO datetime)
+
+Optional:
+
+- `resolvedAt` (ISO datetime; present when `status != held`)
+- `metadata` (implementation-defined JSON object)
+
+## Hashing
+
+`holdHash` is computed as sha256 of the RFC 8785 canonical JSON of the **immutable core**, which excludes:
+
+- `holdHash`
+- `status`
+- `resolvedAt`
+- `updatedAt`
+- `revision`
+- `metadata`
+
+This ensures `holdHash` is stable across state transitions.
+
+## Invariants
+
+- `heldAmountCents <= amountCents`
+- Escrow operations must only move `heldAmountCents`.
+- A `FundingHold.v1` must not be “resolved” more than once (application must be idempotent).
+
+## Schema
+
+See `docs/spec/schemas/FundingHold.v1.schema.json`.
+

package/docs/spec/GovernancePolicy.v1.md

@@ -0,0 +1,34 @@
+# GovernancePolicy.v1
+
+This document is the **explicit contract** for signer authorization.
+
+It exists so authorization is not inferred from “whatever code happens to do today”. A strict verifier MUST be able to load a policy, apply it deterministically, and fail with a crisp reason when the signer is not authorized.
+
+## Status
+
+`GovernancePolicy.v1` is a legacy/compat surface. In strict mode, verifiers require `GovernancePolicy.v2` (signed by a governance root trusted out-of-band).
+
+## File location (bundles)
+
+`governance/policy.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/GovernancePolicy.v1.schema.json`.
+
+## Semantics (v1)
+
+- `algorithms` is a declared allowlist of acceptable signature algorithms for governed signatures. v1 supports `ed25519`.
+- `verificationReportSigners` governs who may sign `verify/verification_report.json` (`VerificationReport.v1`) for each `subjectType` (e.g. `JobProofBundle.v1`).
+- `bundleHeadAttestationSigners` governs who may sign `attestation/bundle_head_attestation.json` (`BundleHeadAttestation.v1`) for each `subjectType`.
+
+Rule application:
+
+- The verifier selects the rule whose `subjectType` matches the bundle being verified.
+- `allowedKeyIds = null` means “no explicit key allowlist; any key that satisfies the other rule constraints may sign”.
+- If `allowedKeyIds` is a non-null array, the signer key id MUST be present in that list.
+- `allowedScopes` is enforced against the signed document’s declared signer scope (`global` vs `tenant`) when present.
+- `requireGoverned = true` means the signer must be governed by the included governance streams (i.e., the key lifecycle is declared by governance events).
+- `requiredPurpose = server` means the signer key must be a server signer key.

package/docs/spec/GovernancePolicy.v2.md

@@ -0,0 +1,30 @@
+# GovernancePolicy.v2
+
+This document is the **explicit contract** for signer authorization in strict verification, with a mandatory governance-root signature.
+
+## File location (bundles)
+
+`governance/policy.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/GovernancePolicy.v2.schema.json`.
+
+## Semantics (v2)
+
+`GovernancePolicy.v2` is the same conceptual policy as v1, but with two critical hardenings:
+
+1. `allowedKeyIds` is an explicit allowlist (not nullable). Strict verification relies on explicit authorization, not “any governed key”.
+2. The policy is signed by a governance root key (trusted out-of-band by the verifier).
+
+The policy also binds to a `RevocationList.v1` snapshot via `revocationList.sha256`.
+
+## Signing + trust (strict verification)
+
+Strict verification MUST:
+
+- verify `policyHash` and `signature`, and
+- require `signerKeyId` to be trusted out-of-band as a governance root key.
+