settld 0.1.1 → 0.1.5

package/docs/spec/TRUST_ANCHORS.md

@@ -0,0 +1,84 @@
+# Trust anchors (out-of-band)
+
+Strict verification requires **trusted root keys** that are *not* bundled inside artifacts.
+
+This is intentional: bundling trust anchors inside the thing being verified would create a trust-loop.
+
+## Release authenticity trust (separate domain)
+
+Settld release authenticity (verifying the tool distribution artifacts themselves) uses a **separate trust domain** from bundle verification.
+
+- Release trust roots live in `trust/release-trust.json` (see `ReleaseTrust.v2.md`).
+- Release verification CLI: `settld-release verify --dir <release-assets-dir> --trust-file trust/release-trust.json --format json`
+
+Do not mix release signing keys with bundle/governance signing keys (different purpose, different blast radius).
+
+## Governance roots (required for strict)
+
+`GovernancePolicy.v2` and `RevocationList.v1` are signed by governance root keys that must be trusted out-of-band.
+
+Verifier input mechanism:
+
+- `SETTLD_TRUSTED_GOVERNANCE_ROOT_KEYS_JSON`
+  - JSON object mapping `keyId -> publicKeyPem`
+  - required for strict verification
+
+Recommended operational posture:
+
+- Store the trust roots JSON (or a `trust.json` file that contains it) in version control.
+- Distribute updates via PR + review (treat as a security-sensitive change).
+- Pin tool versions in CI (see `docs/spec/VERSIONING.md`) so a verification receipt can be mapped to a stable tool build.
+- For regulated workflows: run strict mode and gate on warnings (`--fail-on-warnings`) when policy requires it (see `STRICTNESS.md` and `WARNINGS.md`).
+
+## Buyer pricing signer keys (required for strict InvoiceBundle pricing terms)
+
+Invoice bundles may include buyer-approved pricing terms via `pricing/pricing_matrix_signatures.json` (`PricingMatrixSignatures.*`).
+
+Verifier input mechanism:
+
+- `SETTLD_TRUSTED_PRICING_SIGNER_KEYS_JSON`
+  - JSON object mapping `keyId -> publicKeyPem`
+  - required to validate buyer pricing signatures in strict mode
+
+Optional restriction:
+
+- `SETTLD_TRUSTED_PRICING_SIGNER_KEY_IDS_JSON`
+  - JSON array of allowed `keyId` strings
+  - when set and non-empty, only signatures by these key IDs are treated as trusted (even if additional keys are present in `SETTLD_TRUSTED_PRICING_SIGNER_KEYS_JSON`)
+
+Do not overload governance roots: pricing signer trust is a separate trust set with a distinct purpose and blast radius.
+
+## Buyer decision signer keys (required to verify SettlementDecisionReport)
+
+Buyer approval/hold receipts (`SettlementDecisionReport.v1`) are signed and must be verified under a buyer-controlled trust set.
+
+Verifier input mechanism:
+
+- `SETTLD_TRUSTED_SETTLEMENT_DECISION_SIGNER_KEYS_JSON`
+  - JSON object mapping `keyId -> publicKeyPem`
+  - required to validate settlement decision report signatures
+
+## Time authorities (required only when needed)
+
+Bundles may include `timestampProof` objects that require a verifier-trusted time authority key.
+
+Verifier input mechanism:
+
+- `SETTLD_TRUSTED_TIME_AUTHORITY_KEYS_JSON`
+  - JSON object mapping `keyId -> publicKeyPem`
+  - required only when verifying a timestamp proof that must be trusted in strict mode
+
+## Fixture corpus convention
+
+The committed end-to-end fixtures under `test/fixtures/bundles/v1/**` include a `trust.json` file that contains the trusted keys used by tests.
+
+The CLI fixture harness reads that file and injects the corresponding env vars when running `settld-verify` against fixtures.
+
+## Rotation workflow (example)
+
+1. Add the new root key to your trust file (do not remove the old one yet).
+2. Roll out the trust file change to CI/verifier environments.
+3. Begin signing new governance policy streams with the new root key.
+4. Once all verifiers are updated and the old root is no longer needed, remove the old root key from the trust file.
+
+If you remove a trust root key too early, strict verification will fail with trust-related errors (see `ERRORS.md`).

package/docs/spec/TenantSettings.v1.md

@@ -0,0 +1,90 @@
+# TenantSettings.v1
+
+`TenantSettings.v1` is the **tenant-scoped configuration contract** for Settld Verify Cloud / Magic Link.
+
+This version is legacy and is superseded by `TenantSettings.v2` (which adds artifact storage controls and archival export sinks).
+
+It controls:
+
+- default verification posture (`auto|strict|compat`)
+- tenant-specific governance trust roots (for strict verification without deploy-time env config)
+- tenant-specific pricing signer keys (for strict verification of buyer-approved pricing terms)
+- retention and quota limits
+- buyer policy controls for vendor submissions
+- buyer portal authentication + RBAC (service-level)
+- buyer decision authentication controls (service-level)
+- buyer decision signing configuration (service-level)
+- webhook configuration
+
+## Schema
+
+See `schemas/TenantSettings.v1.schema.json`.
+
+## Vendor / contract policy controls (service-level)
+
+`vendorPolicies` and `contractPolicies` are **service-level** enforcement knobs for Verify Cloud. They do **not** change `InvoiceBundle.v1`.
+
+Policy selection precedence:
+
+1. `contractPolicies[contractId]` (if `contractId` is present on the run)
+2. `vendorPolicies[vendorId]` (if `vendorId` is present on the run)
+3. no policy
+
+Policy fields:
+
+- `requiredMode`: `auto|strict|compat` override for how the hosted verifier runs (independent of uploader requested mode).
+- `failOnWarnings`: if true, hosted output is failed when any warnings are present (same as CLI `--fail-on-warnings` posture).
+- `allowAmberApprovals`: if false, buyers cannot record **Approve** decisions when status is Amber.
+- `requireProducerReceiptPresent`: if true, hosted output fails if `verify/verification_report.json` is missing (even in compat mode).
+- `requiredPricingMatrixSignerKeyIds`: when set, hosted verification fails unless `pricing/pricing_matrix_signatures.json` includes at least one trusted signature whose `signerKeyId` is allowlisted by this policy.
+- `retentionDays`: optional per-policy retention override for runs matching that vendor/contract.
+
+## Decision authentication (service-level)
+
+`decisionAuthEmailDomains` configures optional **email OTP gating** for buyer decision actions (`Approve`/`Hold`) on Magic Links.
+
+- If empty (default): decision capture is unauthenticated and relies on typed actor name+email.
+- If non-empty: decision capture requires an email OTP, and the email domain MUST match one of the configured domains.
+
+This is a service control plane feature (not part of the frozen `InvoiceBundle.v1` protocol).
+
+## Buyer portal authentication + RBAC (service-level)
+
+Verify Cloud supports **buyer portal** access without sharing the tenant API key.
+
+This is a service control plane feature (not part of the frozen `InvoiceBundle.v1` protocol).
+
+### Authentication
+
+`buyerAuthEmailDomains` configures **email OTP login** for buyer users.
+
+- If empty (default): buyer portal OTP login is disabled.
+- If non-empty: buyers can request an OTP and establish a session if their email domain matches one of the configured domains.
+
+### Roles
+
+`buyerUserRoles` is an optional mapping from **buyer email → role**:
+
+- `admin`: manage settings, ingest keys, policies, exports, billing
+- `approver`: view inbox, export audit packet/CSV, approve/hold (via signed `SettlementDecisionReport.v1`)
+- `viewer`: view inbox only
+
+If an email is not listed in `buyerUserRoles`, it is treated as `viewer`.
+
+## Pricing signer trust (service-level)
+
+`pricingSignerKeysJson` is an optional tenant-scoped trust set for **buyer pricing signer keys**.
+
+It is used to populate `SETTLD_TRUSTED_PRICING_SIGNER_KEYS_JSON` for hosted verification runs so that
+`pricing/pricing_matrix_signatures.json` can be validated in strict mode.
+
+`trustedPricingSignerKeyIds` is an optional allowlist of key IDs. When set and non-empty, Verify Cloud MUST treat only those key IDs as trusted pricing signers (even if additional keys exist in `pricingSignerKeysJson`).
+
+## Settlement decision signing (service-level)
+
+`settlementDecisionSigner` configures how Verify Cloud signs buyer approval/hold receipts (`SettlementDecisionReport.v1`).
+
+Supported modes:
+
+- local PEM private key (pilot posture)
+- delegated remote signer (hardened key custody)

package/docs/spec/TenantSettings.v2.md

@@ -0,0 +1,99 @@
+# TenantSettings.v2
+
+`TenantSettings.v2` is the **tenant-scoped configuration contract** for Settld Verify Cloud / Magic Link.
+
+It is a backwards-compatible evolution of `TenantSettings.v1` that adds:
+
+- per-tenant artifact storage cost controls (`artifactStorage`)
+- tenant-configurable archival export sink (`archiveExportSink`)
+- buyer notification delivery config (`buyerNotifications`)
+- automatic settlement decision policy controls (`autoDecision`)
+- payment trigger delivery controls (`paymentTriggers`)
+- tenant-scoped request rate limits (`rateLimits`)
+
+## Schema
+
+See `schemas/TenantSettings.v2.schema.json`.
+
+## Vendor / contract policy controls (service-level)
+
+Unchanged from `TenantSettings.v1`:
+
+- `vendorPolicies` and `contractPolicies` are Verify Cloud enforcement knobs and do **not** change `InvoiceBundle.v1`.
+
+## Artifact storage controls (service-level)
+
+`artifactStorage` controls what Verify Cloud persists under `MAGIC_LINK_DATA_DIR`.
+
+Fields:
+
+- `storeBundleZip` (default `true`): persist `zips/<token>.zip` so a buyer can download the exact bytes that were verified.
+- `storePdf` (default `true`): persist `pdf/<token>.pdf` when an invoice claim is present.
+- `precomputeMonthlyAuditPackets` (default `false`): allow the service to cache monthly audit packet zips for export sinks (still safe to generate on-demand).
+
+These are service controls (not part of the frozen `InvoiceBundle.v1` protocol).
+
+## Archival export sink (service-level)
+
+`archiveExportSink` configures an optional monthly archival push of:
+
+- monthly audit packet ZIP (`/v1/tenants/:tenant/audit-packet?month=…`)
+- monthly CSV export (`/v1/tenants/:tenant/export.csv?month=…`)
+
+Supported sink types:
+
+- `s3`: S3-compatible object storage.
+
+Secrets (e.g. `secretAccessKey`) are encrypted at rest when `MAGIC_LINK_SETTINGS_KEY_HEX` is configured.
+
+## Buyer notifications (service-level)
+
+`buyerNotifications` configures post-verification delivery of buyer links.
+
+Fields:
+
+- `emails`: recipient list (normalized lowercase emails).
+- `deliveryMode`: `smtp|webhook|record`.
+- `webhookUrl`: required when `deliveryMode=webhook`.
+- `webhookSecret`: optional HMAC secret for webhook delivery (encrypted at rest when settings key is configured).
+
+Notification delivery is idempotent per run token.
+
+## Auto-decision policy (service-level)
+
+`autoDecision` configures optional automatic buyer decisions immediately after verification completes.
+
+Fields:
+
+- `enabled`: turn policy automation on/off.
+- `approveOnGreen`: auto-approve `green` runs.
+- `approveOnAmber`: auto-approve `amber` runs.
+- `holdOnRed`: auto-hold `red` runs.
+- `templateIds`: optional template allowlist. When set, auto-decision only applies to listed SLA template IDs.
+- `actorName` / `actorEmail`: actor identity stamped into `SettlementDecisionReport.v1` for automated decisions.
+
+Automated decisions are best-effort and respect idempotency/lockout (`DECISION_ALREADY_RECORDED`).
+
+## Payment triggers (service-level)
+
+`paymentTriggers` configures optional outbound delivery when an artifact is approved.
+
+Fields:
+
+- `enabled`: enable/disable payment trigger delivery.
+- `deliveryMode`: `record|webhook`.
+- `webhookUrl`: required when `enabled=true` and `deliveryMode=webhook`.
+- `webhookSecret`: optional HMAC signing secret (encrypted at rest when settings key is configured).
+
+Delivery is idempotent per approved decision report hash.
+
+## Tenant rate limits (service-level)
+
+`rateLimits` configures tenant + IP window limits:
+
+- `uploadsPerHour` (default `100`)
+- `verificationViewsPerHour` (default `1000`)
+- `decisionsPerHour` (default `300`)
+- `otpRequestsPerHour` (default `300`)
+
+Exceeded limits return `429` with a `Retry-After` header.

package/docs/spec/TimestampProof.v1.md

@@ -0,0 +1,25 @@
+# TimestampProof.v1
+
+This document defines a **trustworthy signing time** proof that can be embedded inside signed protocol documents (e.g. `BundleHeadAttestation.v1` and `VerificationReport.v1`).
+
+## Semantics
+
+`TimestampProof.v1` is an **independent attestation of time** over a specific message hash. It exists so strict verification can support “historical acceptance” under prospective revocation rules without trusting a signer-controlled timestamp field.
+
+v1 supports one proof kind:
+
+- `kind = "ed25519_time_authority"` — an Ed25519 signature by a trusted time authority key.
+
+Fields:
+
+- `timestamp`: the asserted timestamp (RFC3339 / ISO string).
+- `messageHash`: `sha256` hex of the canonical JSON bytes of the signed document’s **core payload**, computed **without** the `timestampProof` field.
+- `signerKeyId` / `signature`: the time authority signature.
+
+## Trust model (strict verification)
+
+Strict verification MUST treat the time as trustworthy only if:
+
+- the proof verifies cryptographically, and
+- the proof’s signer key is trusted out-of-band by the verifier (a “time authority” trust anchor).
+

package/docs/spec/ToolCallAgreement.v1.md

@@ -0,0 +1,34 @@
+# ToolCallAgreement.v1
+
+`ToolCallAgreement.v1` binds a payable tool invocation to deterministic settlement terms.
+
+The output is a hash-addressable agreement (`agreementHash`) that can be referenced by downstream holds, disputes, and receipts without trusting an online service.
+
+## Fields
+
+Required:
+
+- `schemaVersion` (const: `ToolCallAgreement.v1`)
+- `toolId` (string)
+- `manifestHash` (sha256 hex; hash of the referenced `ToolManifest.v1`)
+- `callId` (string; tool-call correlation id)
+- `inputHash` (sha256 hex; hash of canonical JSON of the tool-call input payload)
+- `acceptanceCriteria` (object or `null`)
+- `settlementTerms` (object or `null`)
+- `payerAgentId` (string or `null`)
+- `payeeAgentId` (string or `null`)
+- `createdAt` (ISO 8601 date-time)
+- `agreementHash` (sha256 hex)
+
+## Canonicalization + hashing
+
+1. Canonicalize using RFC 8785 (JCS).
+2. The `agreementHash` is `sha256` over UTF-8 bytes of canonical JSON of the **agreement core**:
+   - the full `ToolCallAgreement.v1` object **excluding** the `agreementHash` field.
+
+Implementations must treat the nullable fields (`acceptanceCriteria`, `settlementTerms`, `payerAgentId`, `payeeAgentId`) as present with explicit `null` when absent so `agreementHash` does not depend on “omitted vs null” representation.
+
+## Schema
+
+See `docs/spec/schemas/ToolCallAgreement.v1.schema.json`.
+

package/docs/spec/ToolCallEvidence.v1.md

@@ -0,0 +1,47 @@
+# ToolCallEvidence.v1
+
+`ToolCallEvidence.v1` records the outcome of a tool invocation (`outputHash`, optional references/metrics) and binds it to a `ToolCallAgreement.v1` via `agreementHash`.
+
+The output is a hash-addressable evidence record (`evidenceHash`) that can be optionally signed by an agent key.
+
+## Fields
+
+Required:
+
+- `schemaVersion` (const: `ToolCallEvidence.v1`)
+- `agreementHash` (sha256 hex; points to `ToolCallAgreement.v1`)
+- `callId` (string; must match the agreement `callId`)
+- `inputHash` (sha256 hex; must match the agreement `inputHash`)
+- `outputHash` (sha256 hex; hash of canonical JSON of the tool-call output payload)
+- `outputRef` (string or `null`; optional pointer to stored output)
+- `metrics` (object or `null`; optional timing/quality metrics)
+- `startedAt` (ISO 8601 date-time)
+- `completedAt` (ISO 8601 date-time)
+- `createdAt` (ISO 8601 date-time)
+- `evidenceHash` (sha256 hex)
+
+Optional:
+
+- `signature` (object): Ed25519 signature over `evidenceHash`
+  - `algorithm` (const: `ed25519`)
+  - `signerKeyId` (string)
+  - `evidenceHash` (sha256 hex; must equal the parent `evidenceHash`)
+  - `signature` (base64)
+
+## Canonicalization + hashing
+
+1. Canonicalize using RFC 8785 (JCS).
+2. The `evidenceHash` is `sha256` over UTF-8 bytes of canonical JSON of the **evidence core**:
+   - the full `ToolCallEvidence.v1` object excluding `evidenceHash` and `signature`.
+
+Implementations must treat the nullable fields (`outputRef`, `metrics`) as present with explicit `null` when absent so `evidenceHash` does not depend on “omitted vs null” representation.
+
+## Signing
+
+- When present, `signature.signature` is an Ed25519 signature over the **bytes** of `evidenceHash` (hex), base64-encoded.
+- Verifiers should ensure `signature.evidenceHash` matches the enclosing `evidenceHash` before verifying the signature.
+
+## Schema
+
+See `docs/spec/schemas/ToolCallEvidence.v1.schema.json`.
+

package/docs/spec/ToolManifest.v1.md

@@ -0,0 +1,47 @@
+# ToolManifest.v1
+
+`ToolManifest.v1` describes a payable capability (a tool) as a signed, portable contract that can be pinned by hash.
+
+This object is intentionally small: it exists to make third-party discovery and replay possible without “server configuration context”.
+
+## Fields
+
+Required:
+
+- `schemaVersion` (const: `ToolManifest.v1`)
+- `toolId` (string; stable identifier)
+- `toolVersion` (string; SemVer)
+- `endpoints[]` (non-empty array)
+  - `kind` (const: `http`)
+  - `baseUrl` (string)
+  - `callPath` (string)
+  - `manifestPath` (string)
+- `inputSchemaHash` (sha256 hex; hash of the canonical JSON input schema)
+- `outputSchemaHash` (sha256 hex; hash of the canonical JSON output schema)
+- `createdAt` (ISO 8601)
+- `signature` (required)
+  - `algorithm` (const: `ed25519`)
+  - `signerKeyId` (string)
+  - `manifestHash` (sha256 hex)
+  - `signature` (base64)
+  - `signerPublicKeyPem` (optional; PEM string)
+
+Optional:
+
+- `verifierHints` (object or `null`): non-binding hints for consumers about how to evaluate/verify outputs (e.g. deterministic verifier).
+
+## Canonicalization + hashing
+
+1. Canonicalize using RFC 8785 (JCS).
+2. The `manifestHash` is `sha256` over UTF-8 bytes of canonical JSON of the **manifest core**:
+   - the full `ToolManifest.v1` object **excluding** the `signature` field.
+
+## Signing
+
+- The `signature.signature` value is an Ed25519 signature over `manifestHash` (the hex hash string), using the private key corresponding to `signerKeyId`.
+- Consumers may verify using `signature.signerPublicKeyPem` when present, or via an external key registry for `signerKeyId`.
+
+## Schema
+
+See `docs/spec/schemas/ToolManifest.v1.schema.json`.
+

package/docs/spec/VERIFIER_ENVIRONMENT.md

@@ -0,0 +1,38 @@
+# Verifier Environment Assumptions + Hardening (v1)
+
+This document describes operational assumptions and recommended hardening when deploying `settld-verify`.
+
+## Filesystem assumptions
+
+- The bundle is verified from a local directory (or an extracted zip) whose contents are stable during verification.
+- The verifier treats manifest paths as portable `/`-separated bundle-relative paths.
+- The verifier refuses symlinks for manifest-listed files and rejects path traversal attempts.
+  - Spec: `REFERENCE_VERIFIER_BEHAVIOR.md`
+
+## CI / production recommendations
+
+- **Regulated workflows**: run **strict mode** by default.
+  - CLI: `settld-verify --strict --format json …`
+  - Spec: `STRICTNESS.md`
+- **Warnings policy**:
+  - If warnings represent “unknown provenance / incomplete guarantees” in your environment, enable `--fail-on-warnings`.
+  - CLI: `settld-verify --fail-on-warnings …`
+  - Spec: `WARNINGS.md`
+- **Pin tool versions**:
+  - Prefer installing a pinned version of `settld-verify` and recording `VerifyCliOutput.v1.tool.{version,commit}` as evidence.
+  - Spec: `TOOL_PROVENANCE.md`, `VERSIONING.md`
+
+## Trust anchor distribution (do / don’t)
+
+- DO distribute governance-root public keys out-of-band and pin them (e.g., repo file, immutable artifact, or configuration management).
+- DO treat trust anchors as high-integrity inputs (tampering undermines authorization checks).
+- DON’T fetch trust roots over unauthenticated channels at verification time.
+- Spec: `TRUST_ANCHORS.md`
+
+## Volatility and determinism
+
+- CLI output ordering of `errors[]` and `warnings[]` is deterministic (sorted) to support CI and archival.
+- If you need stronger determinism guarantees, archive both:
+  - `verify/verification_report.json` inside the bundle (receipt), and
+  - `settld-verify --format json` output (what your CI observed).
+

package/docs/spec/VERSIONING.md

@@ -0,0 +1,107 @@
+# Versioning (tools vs protocol)
+
+Settld has **two coupled version surfaces**:
+
+1. **Tool versions** (SemVer): the software you install/run (`settld-verify`, bundlers, services).
+2. **Protocol versions** (object `*.v1`, `*.v2`, …): on-disk/wire-format contracts (schemas + semantics).
+
+This document defines when to bump **tool SemVer**, when to introduce **new protocol object versions**, and how to avoid accidental drift.
+
+## Tool SemVer policy
+
+Tools follow Semantic Versioning:
+
+- **MAJOR**: any breaking change to a public surface (CLI flags/output, verification semantics in strict mode, required protocol surfaces, bundle layout requirements, removal of documented warnings, etc.).
+- **MINOR**: backwards-compatible additions (new CLI flags, new optional output fields, new warning codes, new non-strict compatibility paths).
+- **PATCH**: bug fixes and perf improvements that do not change documented behavior (same pass/fail, same codes, same hashes/signatures).
+
+### Concrete examples (tool SemVer)
+
+- Add a new CLI flag (e.g. `--hash-concurrency`) that does not change verification semantics → **MINOR**.
+- Fix a bug where strict mode accepted an invalid signature and now fails it → **MAJOR** (strict semantics changed).
+- Stream file hashing (perf) while keeping hashes, codes, and strict/non-strict semantics identical → **PATCH**.
+- Add a new warning code and surface it in `VerifyCliOutput.v1` → **MINOR**.
+- Change sorting of `errors[]` / `warnings[]` in CLI JSON output → **MAJOR** (downstream parsers/snapshots can break).
+
+## Protocol surface policy
+
+The protocol is treated like an API:
+
+- Specs: `docs/spec/*`
+- Schemas: `docs/spec/schemas/*`
+- Vectors: `test/fixtures/protocol-vectors/v1.json`
+- End-to-end fixtures: `test/fixtures/bundles/v1/*`
+
+## v1 freeze (protocol becomes a stable contract)
+
+Protocol `v1` is a **frozen contract**: customers, auditors, and independent implementers must be able to pin a tool version and rely on the v1 meaning indefinitely.
+
+### Allowed changes (v1)
+
+- Documentation clarifications and additional examples that do **not** change acceptance criteria.
+- Performance improvements that do **not** change:
+  - pass/fail outcomes,
+  - error/warning codes,
+  - hashes/signatures (canonicalization inputs and bytes),
+  - strict/non-strict downgrade behavior.
+- New tests, fixtures, and conformance cases that increase coverage without changing behavior.
+
+### Not allowed changes (v1)
+
+- Any change to `docs/spec/schemas/*v1*.json` that would alter the schema contract.
+- Any change to `test/fixtures/protocol-vectors/v1.json` that changes canonical meaning.
+- Any change to canonicalization rules (RFC 8785 / JCS) or hashing inputs.
+- Any change to strictness semantics in `STRICTNESS.md`.
+- Any change to warning code meanings in `WARNINGS.md`.
+
+### Enforcement (CI + local)
+
+Changes to v1 schemas/vectors must be **deliberate**:
+
+- CI fails if v1 schemas or `test/fixtures/protocol-vectors/v1.json` change unless:
+  - `CHANGELOG.md` is updated, **and**
+  - the PR includes an explicit marker `protocol-change` (PR body or commit message).
+- A local freeze test (`test/protocol-v1-freeze.test.js`) asserts v1 schema/vector file hashes are unchanged unless `ALLOW_PROTOCOL_V1_MUTATION=1` is set (intended only for deliberate rotations).
+
+### What is a breaking protocol change?
+
+Any change that alters what an independent verifier would accept/reject, or what it would compute as hashes/signatures, including:
+
+- JSON Schema breaking changes for existing `*.v1` objects.
+- Canonicalization changes (RFC 8785 / JCS rules).
+- Hashing changes (algorithm, input bytes, file inclusion/exclusion rules).
+- Strictness contract changes (required surfaces, required validations, downgrade behavior).
+- Bundle layout changes that affect required files or meaning.
+
+### When to introduce `v2` objects vs mutate `v1`
+
+Do **not** mutate the meaning of `*.v1` objects in a way that would cause previously valid instances to become invalid (or vice versa) in strict mode.
+
+Introduce a `v2` when:
+
+- A required field changes shape/type/meaning.
+- A new required field is introduced.
+- The canonicalization/hashing/signing inputs change.
+- You need to remove/rename fields or change invariants.
+
+You may evolve `v1` only via **compatible additions**:
+
+- Add new **optional** fields that are omitted when absent (not `null`).
+- Clarify docs without changing semantics.
+- Add new warning codes (closed set remains documented).
+
+### How vectors and fixtures relate to compatibility
+
+- **Protocol vectors** lock canonical examples and edge cases. Any intentional protocol change requires a deliberate vector update (and review).
+- **Bundle fixtures** are a conformance corpus. Changes to strict/non-strict behavior should be expressed as:
+  - a new fixture directory (single fault), and
+  - an expectation row in `test/fixtures/bundles/v1/fixtures.json`.
+
+## Compatibility matrix (within a major tool version)
+
+Within a given tool **MAJOR**:
+
+- Verifier `X.Y.Z` must verify bundles produced by bundler `X.*.*` (same major), subject to documented strict/non-strict behavior and governance trust anchors.
+- Bundlers may emit new **optional** protocol fields in `v1` objects; verifiers in the same major should ignore unknown optional fields unless strict rules say otherwise.
+
+If a change requires a new protocol object version (`*.v2`), that is a **MAJOR** tool bump unless explicitly documented as “dual read” compatibility.

package/docs/spec/VerificationReport.v1.md

@@ -0,0 +1,50 @@
+# VerificationReport.v1
+
+`VerificationReport.v1` is a canonical JSON object emitted into `verify/verification_report.json`.
+
+In strict mode, it is **required** and **must be signed**.
+
+## Purpose
+
+- Provide a machine-ingestible record of verification results.
+- Bind verification statements to a specific bundle by referencing:
+  - `subject.manifestHash`
+  - `bundleHeadAttestation.attestationHash` (binding to the head commitment)
+
+## Core fields
+
+- `schemaVersion = "VerificationReport.v1"`
+- `profile = "strict"`
+- `tool`: `{ name: "settld", version: string | null, commit?: string }`
+- `warnings`: array of warning objects (see `WARNINGS.md`)
+- `subject`:
+  - `type`: bundle kind/type (e.g. `JobProofBundle.v1`, `MonthProofBundle.v1`, `FinancePackBundle.v1`)
+  - `manifestHash`: the bundle manifest hash
+- `bundleHeadAttestation` (strict-required for bundles that support head attestations):
+  - `attestationHash`: must match `attestation/bundle_head_attestation.json` computed hash
+
+## Report hash + signature
+
+- `reportHash` is computed over the canonical JSON object with `reportHash` and `signature` removed.
+- If the report is signed, it includes:
+  - `signature` (base64)
+  - `signerKeyId`
+  - `signedAt`
+
+## Timestamp proof (optional)
+
+`timestampProof` (when present) provides a verifier-trusted signing time for revocation/rotation historical acceptance checks. It is computed over the report core **without** `timestampProof` so it can bind to the report payload.
+
+## No circular hashing
+
+`verify/**` is excluded from bundle manifests. The report binds to the bundle by:
+
+- including `subject.manifestHash`
+- including `bundleHeadAttestation.attestationHash`
+- being signed by a governed server key (in strict mode)
+
+## Tool identity completeness
+
+`tool.commit` is a best-effort build identifier (typically a git commit SHA) intended to answer “what build produced this receipt”.
+
+- If the tool commit cannot be determined, the report MUST include warning code `TOOL_COMMIT_UNKNOWN`.

package/docs/spec/VerifyAboutOutput.v1.md

@@ -0,0 +1,10 @@
+# VerifyAboutOutput.v1
+
+`VerifyAboutOutput.v1` is the machine-readable JSON output emitted by `settld-verify --about --format json`.
+
+This is a **tool metadata contract** intended for CI and operational introspection.
+
+## Schema
+
+See `schemas/VerifyAboutOutput.v1.schema.json`.
+

package/docs/spec/VerifyCliOutput.v1.md

@@ -0,0 +1,28 @@
+# VerifyCliOutput.v1
+
+`VerifyCliOutput.v1` is the machine-readable JSON output emitted by `settld-verify --format json`.
+
+This is a **tool contract** intended for CI gating and automated ingestion. It is versioned and treated as a stable surface.
+
+## Schema
+
+See `schemas/VerifyCliOutput.v1.schema.json`.
+
+## Semantics
+
+- `ok` is the CLI’s overall verdict, including policy flags like `--fail-on-warnings`.
+- `verificationOk` reflects the underlying verifier result (`true` only when the bundle verification succeeded).
+- When available, `errors[].code` is promoted from the verifier’s structured error (`result.detail.error`) to prefer stable, code-like identifiers; `errors[].message` may contain a human summary (`result.error`).
+- `errors` and `warnings` are sorted deterministically by `(path, code)`.
+- The CLI supports `--hash-concurrency <n>` to bound parallel hashing work; it does not change verification semantics.
+- `tool.commit` is a best-effort build identifier for the verifier tool (typically a git commit SHA or build revision).
+
+## `--explain` (deterministic stderr)
+
+`settld-verify --explain` prints a deterministic diagnostic summary to **stderr** (while `--format json` continues to print machine output to stdout).
+
+Contract:
+
+- Output is deterministic for the same inputs/environment.
+- Output MUST NOT include secrets.
+- Output ends with **exactly one** trailing newline.