settld 0.1.2 → 0.2.0

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.

package/docs/spec/WARNINGS.md

@@ -0,0 +1,83 @@
+# Verification warnings
+
+Warnings are protocol objects, not strings.
+
+## Shape
+
+Each warning is a canonical JSON object:
+
+- `code` (required, closed set)
+- `message` (optional, string or null)
+- `detail` (optional, any JSON)
+
+Warnings are normalized (deduped + sorted) before being emitted in verification reports.
+
+## Codes (closed set)
+
+- `LEGACY_KEYS_FORMAT_USED`
+- `NONSERVER_REVOCATION_NOT_ENFORCED`
+- `TRUSTED_GOVERNANCE_ROOT_KEYS_MISSING_LENIENT`
+- `GOVERNANCE_POLICY_MISSING_LENIENT`
+- `GOVERNANCE_POLICY_V1_ACCEPTED_LENIENT`
+- `BUNDLE_HEAD_ATTESTATION_MISSING_LENIENT`
+- `MISSING_GOVERNANCE_SNAPSHOT_LENIENT`
+- `UNSIGNED_REPORT_LENIENT`
+- `VERIFICATION_REPORT_MISSING_LENIENT`
+- `CLOSE_PACK_SLA_SURFACES_MISSING_LENIENT`
+- `CLOSE_PACK_ACCEPTANCE_SURFACES_MISSING_LENIENT`
+- `PRICING_MATRIX_UNSIGNED_LENIENT`
+- `WARN_PRICING_SIGNATURE_V1_BYTES_LEGACY`
+- `TOOL_VERSION_UNKNOWN`
+- `TOOL_COMMIT_UNKNOWN`
+
+Tool provenance derivation rules are documented in `TOOL_PROVENANCE.md`.
+
+## Remediation (operator guidance)
+
+Warnings are non-fatal by default, but they are part of the **public contract**. In regulated workflows you may gate on them with `--fail-on-warnings`.
+
+- `VERIFICATION_REPORT_MISSING_LENIENT`
+  - Meaning: bundle is missing `verify/verification_report.json` but non-strict mode allows verify to proceed.
+  - Action: regenerate the bundle/receipt with a bundler/verifier that emits signed receipts, or run strict mode to require it.
+- `CLOSE_PACK_SLA_SURFACES_MISSING_LENIENT`
+  - Meaning: ClosePack bundle is missing portable SLA evaluation surfaces under `sla/*`; non-strict mode allows verify to proceed.
+  - Action: regenerate ClosePack with `sla/sla_definition.json` + `sla/sla_evaluation.json` present (or gate workflows on this warning).
+- `CLOSE_PACK_ACCEPTANCE_SURFACES_MISSING_LENIENT`
+  - Meaning: ClosePack bundle is missing portable acceptance evaluation surfaces under `acceptance/*`; non-strict mode allows verify to proceed.
+  - Action: regenerate ClosePack with `acceptance/acceptance_criteria.json` + `acceptance/acceptance_evaluation.json` present (or gate workflows on this warning).
+- `PRICING_MATRIX_UNSIGNED_LENIENT`
+  - Meaning: invoice bundle lacks a pricing terms signature surface (`pricing/pricing_matrix_signatures.json`) that proves the pricing matrix value was approved by a trusted buyer key; non-strict continues.
+  - Action: include a buyer-signed `PricingMatrixSignatures.v2` file (and/or run strict mode to require it), and gate workflows on this warning as needed.
+- `WARN_PRICING_SIGNATURE_V1_BYTES_LEGACY`
+  - Meaning: invoice bundle used legacy `PricingMatrixSignatures.v1` (raw-bytes binding), which is formatting-fragile; non-strict accepted it for compatibility.
+  - Action: migrate to `PricingMatrixSignatures.v2` (canonical JSON binding) and run strict mode to enforce it.
+- `UNSIGNED_REPORT_LENIENT`
+  - Meaning: a verification report exists but is not signed in a way required for strict assurance.
+  - Action: re-run verification with a governed verifier signer and write a signed `verify/verification_report.json`.
+- `GOVERNANCE_POLICY_MISSING_LENIENT`
+  - Meaning: governance policy file is missing; non-strict continues but governance guarantees are not established.
+  - Action: ensure the bundler emits `governance/policy.json` (and related materials); prefer strict mode for audit posture.
+- `TRUSTED_GOVERNANCE_ROOT_KEYS_MISSING_LENIENT`
+  - Meaning: verifier is running without out-of-band governance trust anchors; non-strict continues but governance signatures are not validated.
+  - Action: provide `SETTLD_TRUSTED_GOVERNANCE_ROOT_KEYS_JSON` and run strict mode for audit posture (see `TRUST_ANCHORS.md`).
+- `GOVERNANCE_POLICY_V1_ACCEPTED_LENIENT`
+  - Meaning: legacy `GovernancePolicy.v1` was accepted (compat mode).
+  - Action: upgrade to `GovernancePolicy.v2` and re-bundle; strict mode should require v2.
+- `BUNDLE_HEAD_ATTESTATION_MISSING_LENIENT`
+  - Meaning: head attestation is missing; non-strict continues but binding guarantees weaken.
+  - Action: regenerate bundle with `attestation/bundle_head_attestation.json` present and valid.
+- `MISSING_GOVERNANCE_SNAPSHOT_LENIENT`
+  - Meaning: governance snapshot(s) were missing and non-strict continued.
+  - Action: regenerate bundle including governance snapshot files; strict mode should require them.
+- `LEGACY_KEYS_FORMAT_USED`
+  - Meaning: verifier encountered a legacy key-format compatibility path.
+  - Action: update bundle/key materials to the current key format and re-bundle.
+- `NONSERVER_REVOCATION_NOT_ENFORCED`
+  - Meaning: verifier could not enforce a revocation decision for a non-server signer under the strict model (compat path).
+  - Action: include a trustworthy signing time (`timestampProof`) where required, or adjust governance posture; prefer server-governed signers.
+- `TOOL_VERSION_UNKNOWN`
+  - Meaning: verifier could not determine its version string.
+  - Action: install from a released artifact (npm tarball or pinned version) and ensure `package.json` version is available; consider gating on this warning in CI.
+- `TOOL_COMMIT_UNKNOWN`
+  - Meaning: verifier could not determine its commit identifier.
+  - Action: set the documented commit env source (see `TOOL_PROVENANCE.md`) in your CI/build environment; consider gating on this warning in CI.

package/docs/spec/error-codes.v1.txt

@@ -0,0 +1,285 @@
+FAILED
+FAIL_ON_WARNINGS
+MANIFEST_DUPLICATE_PATH
+MANIFEST_PATH_CASE_COLLISION
+MANIFEST_PATH_INVALID
+MANIFEST_SYMLINK_FORBIDDEN
+PRICING_MATRIX_SIGNATURE_INVALID
+PRICING_MATRIX_SIGNATURE_MISSING
+PRICING_MATRIX_SIGNATURE_PAYLOAD_MISMATCH
+PRICING_MATRIX_SIGNATURE_V1_BYTES_LEGACY_STRICT_REJECTED
+SETTLEMENT_DECISION_SIGNATURE_INVALID
+SETTLEMENT_DECISION_SIGNATURE_PAYLOAD_MISMATCH
+SIGNER_NOT_YET_VALID
+SIGNER_REVOKED
+SIGNER_ROTATED
+SIGNING_TIME_UNPROVABLE
+ZIP_COMPRESSION_RATIO_TOO_HIGH
+ZIP_DUPLICATE_ENTRY
+ZIP_ENCRYPTED_UNSUPPORTED
+ZIP_ENTRY_PATH_INVALID
+ZIP_ENTRY_PATH_TOO_LONG
+ZIP_EXTRACT_FAILED
+ZIP_FILE_TOO_LARGE
+ZIP_INTERNAL_ERROR
+ZIP_INVALID_CENTRAL_DIR
+ZIP_INVALID_ENTRY
+ZIP_INVALID_EOCD
+ZIP_LOCAL_HEADER_MISMATCH
+ZIP_OPEN_FAILED
+ZIP_SYMLINK_FORBIDDEN
+ZIP_TOO_MANY_ENTRIES
+ZIP_TOTAL_UNCOMPRESSED_TOO_LARGE
+ZIP_UNSUPPORTED_COMPRESSION
+ZIP_UNSUPPORTED_MULTI_DISK
+ZIP_UNSUPPORTED_ZIP64
+artifactHash mismatch
+artifactType mismatch
+attestation global governance head mismatch (chainHash)
+attestation global governance head mismatch (eventId)
+attestation invoiceBundle.attestationHash mismatch
+attestation invoiceBundle.manifestHash mismatch
+attestation job head mismatch (chainHash)
+attestation job head mismatch (eventId)
+attestation jobProof.attestationHash mismatch
+attestation jobProof.manifestHash mismatch
+attestation kind mismatch
+attestation manifestHash mismatch
+attestation missing heads
+attestation missing heads.invoiceBundle
+attestation missing heads.job
+attestation missing heads.jobProof
+attestation missing heads.month
+attestation missing heads.monthProof
+attestation missing signature fields
+attestation missing signer fields
+attestation month head mismatch (chainHash)
+attestation month head mismatch (eventId)
+attestation monthProof.attestationHash mismatch
+attestation monthProof.manifestHash mismatch
+attestation scope mismatch
+attestation scope.invoiceId mismatch
+attestation scope.period mismatch
+attestation signature invalid
+attestation signer key missing validFrom
+attestation signer key not valid
+attestation signer not authorized
+attestation tenant governance head mismatch (chainHash)
+attestation tenant governance head mismatch (eventId)
+attestation tenantId mismatch
+attestationHash mismatch
+bad signature
+bundle head attestation invalid
+closepack acceptance surfaces incomplete
+closepack acceptance_evaluation mismatch
+closepack evidence_index mismatch
+closepack invoiceBundle.embeddedPath invalid
+closepack invoiceBundle.headAttestationHash mismatch
+closepack invoiceBundle.manifestHash mismatch
+closepack sla surfaces incomplete
+closepack sla_evaluation mismatch
+declared head chainHash mismatch
+declared head eventId mismatch
+embedded invoice bundle verification failed
+event stream integrity invalid
+expected GLBatch.v1
+expected PartyStatement.v1
+failed to hash file
+failed to hash glBatch
+failed to hash partyStatement
+failed to hash settlement decision report
+financeAccountMapHash mismatch
+forfeit decisionEventRef mismatch
+forfeit decisionEventRef missing DECISION_RECORDED
+forfeit freshness check failed
+forfeit missing decision provenance
+forfeit stale at decision time
+glBatch artifactHash mismatch
+glBatch does not net to zero
+glBatchHash mismatch
+governance policy algorithms must be a non-empty array
+governance policy bundleHeadAttestationSigners must be an array
+governance policy does not allow ed25519
+governance policy missing signature fields
+governance policy revocationList invalid
+governance policy revocationList missing
+governance policy revocationList.path invalid
+governance policy signature invalid
+governance policy signerKeyId not trusted
+governance policy verificationReportSigners must be an array
+governance policyHash mismatch
+governance stream integrity invalid
+governance/global contains tenant-scoped event
+governance/tenant contains global-scoped event
+hold freshness check failed
+hold missing referenced PROOF_EVALUATED
+hold missingEvidence mismatch
+hold reasonCodes mismatch
+hold stale at decision time
+hold triggeringProofRef mismatch
+included entry ids mismatch
+incomplete governance/global stream files
+incomplete governance/tenant stream files
+invalid JSON
+invalid artifact JSON
+invalid attestation JSON
+invalid bundle head attestation JSON
+invalid governance revocation list
+invalid governance/policy.json
+invalid schemaVersion
+invalid verification report JSON
+invalid verification report subject
+invalid warning code
+invoice pricing code unknown
+invoiceClaim jobProof.embeddedPath mismatch
+invoiceClaim jobProof.headAttestationHash mismatch
+invoiceClaim jobProof.manifestHash mismatch
+invoiceClaim lineItems mismatch
+invoiceClaim totalCents invalid
+invoiceClaim totalCents mismatch
+job proof events missing
+job proof strict verification failed
+jobProofBundleHash mismatch
+jobProofHeadAttestationHash mismatch
+journalCsv.csvSha256 mismatch
+journalCsvArtifactHash mismatch
+journalCsvHash mismatch
+keyMetaByKeyId must be a Map
+list must be an object
+manifest missing manifestHash
+manifest missing required files
+manifestHash mismatch
+metering evidenceRef not in job proof manifest
+metering evidenceRef sha256 mismatch
+meteringReport jobProof binding missing
+meteringReport jobProof.embeddedPath mismatch
+meteringReport jobProof.headAttestationHash mismatch
+meteringReport jobProof.manifestHash mismatch
+missing artifactHash
+missing artifactType
+missing attestation/bundle_head_attestation.json
+missing events
+missing events/events.jsonl
+missing events/payload_material.jsonl
+missing evidence/evidence_index.json
+missing file
+missing glBatch artifactHash
+missing governance policy
+missing governance/global stream
+missing governance/policy.json
+missing governance/tenant stream
+missing job/snapshot.json
+missing keys/public_keys.json
+missing month keys/public_keys.json (PublicKeys.v1)
+missing or invalid keys/public_keys.json
+missing partyStatement artifactHash
+missing timestampProof
+missing verify/verification_report.json
+month proof strict verification failed
+monthProofBundleHash mismatch
+no governance policy rule for subjectType
+non-numeric posting total
+partyStatement artifactHash mismatch
+partyStatement basis mismatch
+partyStatement period mismatch
+partyStatement totalsByAccountId contains non-integer
+partyStatement totalsByAccountId missing
+payload_material length mismatch
+policy must be an object
+postings do not balance
+provenance refs invalid
+publicKeyByKeyId must be a Map
+reconcile.json mismatch
+reconcileReportHash mismatch
+release freshness check failed
+release missing referenced PROOF_EVALUATED
+release releasingProofRef mismatch
+release stale at decision time
+revocation list generatedAt missing
+revocation list hash mismatch
+revocation list listId missing
+revocation list missing signature fields
+revocation list must be an object
+revocation list revocations must be an array
+revocation list rotations must be an array
+revocation list signature invalid
+revocation list signerKeyId not trusted
+revocation listHash mismatch
+revocationList sha256 mismatch
+schemaVersion mismatch
+settlement decision invoiceBundle.headAttestationHash mismatch
+settlement decision invoiceBundle.manifestHash mismatch
+settlement decision report missing signature fields
+settlement decision report must be an object
+settlement decision signerKeyId not trusted
+settlement decision trusted buyer keys invalid
+settlement decision trusted buyer keys missing
+settlement forfeit ref missing SETTLEMENT_FORFEITED
+settlement forfeitEventChainHash mismatch
+settlement forfeitEventPayloadHash mismatch
+settlement freshness check failed
+settlement missing referenced PROOF_EVALUATED
+settlement settlementProofRef mismatch
+settlement stale at decision time
+sha256 mismatch
+signer key is not governed
+signer key purpose not allowed by policy
+signer keyId not allowed by policy
+signer scope not allowed by policy
+strict requires GovernancePolicy.v2
+strict requires trusted governance root keys
+strict requires trusted pricing signer keys
+tenant governance stream integrity invalid
+timestampProof messageHash invalid
+timestampProof messageHash mismatch
+timestampProof missing required fields
+timestampProof must be an object
+timestampProof signature invalid
+timestampProof signerKeyId not trusted
+totals mismatch
+trustedBuyerDecisionPublicKeyByKeyId must be a Map
+trustedGovernanceRootPublicKeyByKeyId must be a Map
+trustedPublicKeyByKeyId must be a Map
+unknown attestation signerKeyId
+unknown verification report signerKeyId
+unsupported acceptance criteria schemaVersion
+unsupported artifactType
+unsupported attestation schemaVersion
+unsupported bundle kind
+unsupported bundle type
+unsupported documentKind
+unsupported evidence index schemaVersion
+unsupported governance policy schemaVersion
+unsupported invoice claim schemaVersion
+unsupported keys schemaVersion
+unsupported manifest schemaVersion
+unsupported metering schemaVersion
+unsupported pricing matrix signatures schemaVersion
+unsupported pricing schemaVersion
+unsupported revocation list schemaVersion
+unsupported settlement decision report schemaVersion
+unsupported sla definition schemaVersion
+unsupported timestampProof kind
+unsupported timestampProof schemaVersion
+unsupported verification report profile
+unsupported verification report schemaVersion
+verification report bundleHeadAttestation.attestationHash mismatch
+verification report bundleHeadAttestation.attestationHash missing
+verification report invalid
+verification report missing bundleHeadAttestation
+verification report missing reportHash
+verification report missing signature
+verification report reportHash mismatch
+verification report signature invalid
+verification report signer key missing validFrom
+verification report signer key not valid
+verification report signer must be an object
+verification report signer not authorized
+verification report signer.keyId mismatch
+verification report signer.keyId missing
+verification report signer.scope invalid
+verification report signerKeyId not found in month keys
+verification report subject.manifestHash mismatch
+verification report subject.type mismatch
+warning must be an object
+warnings must be an array

package/docs/spec/examples/agreement_delegation_v1.example.json

@@ -0,0 +1,21 @@
+{
+  "schemaVersion": "AgreementDelegation.v1",
+  "delegationId": "dlg_example_0001",
+  "tenantId": "tenant_example",
+  "parentAgreementHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+  "childAgreementHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+  "delegatorAgentId": "agt_delegator",
+  "delegateeAgentId": "agt_delegatee",
+  "budgetCapCents": 5000,
+  "currency": "USD",
+  "delegationDepth": 1,
+  "maxDelegationDepth": 3,
+  "ancestorChain": [
+    "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+  ],
+  "createdAt": "2026-02-01T00:00:00.000Z",
+  "delegationHash": "13354b2dedb94b67957d3fd6db4ca85db31fa53a1b278b525e4361e8b1db44c7",
+  "status": "active",
+  "revision": 0,
+  "updatedAt": "2026-02-01T00:00:00.000Z"
+}