settld 0.1.1 → 0.1.5

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"
+}

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

@@ -0,0 +1,26 @@
+{
+  "schemaVersion": "ArbitrationCase.v1",
+  "caseId": "arb_case_20260207_0001",
+  "tenantId": "tenant_vectors",
+  "runId": "run_vectors_0001",
+  "settlementId": "setl_run_vectors_0001",
+  "disputeId": "dsp_run_vectors_0001",
+  "claimantAgentId": "agt_vectors_payer_0001",
+  "respondentAgentId": "agt_vectors_0001",
+  "arbiterAgentId": "agt_arbiter_0001",
+  "status": "under_review",
+  "openedAt": "2026-02-07T00:00:00.000Z",
+  "summary": "Claimant alleges SLA breach on two milestones.",
+  "evidenceRefs": [
+    "artifact://proof/run_vectors_0001/report.json",
+    "artifact://marketplace/agreements/run_vectors_0001.json"
+  ],
+  "appealRef": {
+    "parentCaseId": "arb_case_20260201_0099",
+    "parentVerdictId": "arb_verdict_20260202_0003",
+    "reason": "New evidence was submitted after initial verdict."
+  },
+  "revision": 2,
+  "createdAt": "2026-02-07T00:00:00.000Z",
+  "updatedAt": "2026-02-07T00:10:00.000Z"
+}

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

@@ -0,0 +1,32 @@
+{
+  "schemaVersion": "ArbitrationVerdict.v1",
+  "verdictId": "arb_verdict_20260207_0001",
+  "caseId": "arb_case_20260207_0001",
+  "tenantId": "tenant_vectors",
+  "runId": "run_vectors_0001",
+  "settlementId": "setl_run_vectors_0001",
+  "disputeId": "dsp_run_vectors_0001",
+  "arbiterAgentId": "agt_arbiter_0001",
+  "outcome": "partial",
+  "releaseRatePct": 60,
+  "rationale": "Evidence confirms partial completion; release 60% and refund the remainder.",
+  "evidenceRefs": [
+    "artifact://proof/run_vectors_0001/report.json",
+    "artifact://marketplace/disputes/dsp_run_vectors_0001/evidence_02.json"
+  ],
+  "issuedAt": "2026-02-07T00:15:00.000Z",
+  "appealRef": {
+    "appealCaseId": "arb_case_20260208_0002",
+    "parentVerdictId": "arb_verdict_20260206_0012",
+    "reason": "Parent verdict superseded after formal appeal filing."
+  },
+  "signature": {
+    "algorithm": "ed25519",
+    "signerKeyId": "key_arbiter_0001",
+    "verdictHash": "4e6b2475878aafaef42d0cb94d8e631f932db09957ea72a6f9a34753220d4fcb",
+    "signature": "m4q2iD6n5J9rL6QmFJ2x0vQfV0dN0uU1V3V9M3rG8yN7n5TzB2W4p0m8l7Qx2k9h5x6j8m1r9p4s2t6u0v3w=="
+  },
+  "revision": 1,
+  "createdAt": "2026-02-07T00:15:00.000Z",
+  "updatedAt": "2026-02-07T00:15:00.000Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": "DisputeOpenEnvelope.v1",
+  "artifactType": "DisputeOpenEnvelope.v1",
+  "artifactId": "dopen_tc_1111111111111111111111111111111111111111111111111111111111111111",
+  "envelopeId": "dopen_tc_1111111111111111111111111111111111111111111111111111111111111111",
+  "caseId": "arb_case_tc_1111111111111111111111111111111111111111111111111111111111111111",
+  "tenantId": "tenant_default",
+  "agreementHash": "1111111111111111111111111111111111111111111111111111111111111111",
+  "receiptHash": "2222222222222222222222222222222222222222222222222222222222222222",
+  "holdHash": "3333333333333333333333333333333333333333333333333333333333333333",
+  "openedByAgentId": "agt_demo_payee_1",
+  "openedAt": "2026-02-11T12:00:00.000Z",
+  "reasonCode": "TOOL_CALL_DISPUTE",
+  "nonce": "nonce_demo_00000001",
+  "signerKeyId": "key_demo_signer_0001",
+  "envelopeHash": "6dac9a886bf7466dd5faa57aef1a033ad4d41d9f8176d755f4a5fb9e26271cf4",
+  "signature": "sig_demo_base64_0001"
+}

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

@@ -0,0 +1,32 @@
+{
+  "schemaVersion": "ProduceCliOutput.v1",
+  "tool": {
+    "name": "settld",
+    "version": "0.0.0",
+    "commit": "0123456789abcdef0123456789abcdef01234567"
+  },
+  "mode": {
+    "deterministic": true,
+    "now": "1970-01-01T00:00:00.000Z"
+  },
+  "target": {
+    "kind": "jobproof",
+    "out": "/tmp/out/bundle"
+  },
+  "ok": true,
+  "produceOk": true,
+  "warnings": [],
+  "errors": [],
+  "result": {
+    "bundleDir": "/tmp/out/bundle",
+    "type": "JobProofBundle.v1",
+    "tenantId": "tenant_default",
+    "jobId": "job_default",
+    "period": null,
+    "basis": null,
+    "protocol": null,
+    "manifestHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
+    "attestationHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+  }
+}
+

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

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": "ReleaseIndexSignature.v1",
+  "algorithm": "ed25519-sha256",
+  "keyId": "key_example",
+  "messageSha256": "0000000000000000000000000000000000000000000000000000000000000000",
+  "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA0000000000000000000000000000000000000000000=\n-----END PUBLIC KEY-----\n",
+  "signatureBase64": "AAAA"
+}
+

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

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": "ReleaseIndexSignatures.v1",
+  "signatures": [
+    {
+      "schemaVersion": "ReleaseIndexSignature.v1",
+      "algorithm": "ed25519-sha256",
+      "keyId": "key_example_a",
+      "messageSha256": "0000000000000000000000000000000000000000000000000000000000000000",
+      "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa=\n-----END PUBLIC KEY-----\n",
+      "signatureBase64": "AA=="
+    }
+  ]
+}
+

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

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": "ReleaseIndex.v1",
+  "release": { "tag": "v1.0.0", "version": "1.0.0" },
+  "toolchain": {
+    "commit": "0123456789abcdef0123456789abcdef01234567",
+    "buildEpochSeconds": 0,
+    "canonicalJson": "RFC8785",
+    "includedSchemas": ["VerifyCliOutput.v1", "ProduceCliOutput.v1", "ReleaseIndex.v1"]
+  },
+  "artifacts": [
+    { "path": "settld-artifact-verify-1.0.0.tgz", "sha256": "0000000000000000000000000000000000000000000000000000000000000000", "sizeBytes": 0, "kind": "npm-tgz" },
+    { "path": "conformance-v1.tar.gz", "sha256": "0000000000000000000000000000000000000000000000000000000000000000", "sizeBytes": 0, "kind": "conformance" }
+  ]
+}
+

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

@@ -0,0 +1,7 @@
+{
+  "schemaVersion": "ReleaseTrust.v1",
+  "releaseRoots": {
+    "key_example": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEA0000000000000000000000000000000000000000000=\n-----END PUBLIC KEY-----\n"
+  }
+}
+

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

@@ -0,0 +1,22 @@
+{
+  "schemaVersion": "ReleaseTrust.v2",
+  "policy": {
+    "minSignatures": 2,
+    "requiredKeyIds": ["key_example_a"]
+  },
+  "keys": [
+    {
+      "keyId": "key_example_a",
+      "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa=\n-----END PUBLIC KEY-----\n",
+      "notBeforeEpochSeconds": 0,
+      "comment": "example root A"
+    },
+    {
+      "keyId": "key_example_b",
+      "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMCowBQYDK2VwAyEAbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb=\n-----END PUBLIC KEY-----\n",
+      "notBeforeEpochSeconds": 0,
+      "comment": "example root B"
+    }
+  ]
+}
+

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

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": "RemoteSignerRequest.v1",
+  "op": "sign",
+  "body": {
+    "schemaVersion": "RemoteSignerSignRequest.v1",
+    "requestId": "req_00000001",
+    "keyId": "key_example",
+    "algorithm": "ed25519",
+    "messageBase64": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
+    "purpose": "bundle_head_attestation",
+    "context": {
+      "bundleKind": "JobProofBundle.v1",
+      "tenantId": "tenant_example",
+      "manifestHash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
+    }
+  }
+}
+

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

@@ -0,0 +1,8 @@
+{
+  "schemaVersion": "RemoteSignerSignResponse.v1",
+  "requestId": "req_00000001",
+  "keyId": "key_example",
+  "algorithm": "ed25519",
+  "signatureBase64": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
+  "signerReceipt": "example-receipt"
+}

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

@@ -0,0 +1,29 @@
+{
+  "schemaVersion": "ReputationEvent.v1",
+  "artifactType": "ReputationEvent.v1",
+  "artifactId": "rep_vrd_6ed7af4431923f9cb4ff8f8f0af36ac168f991f3f9f7f0f3f9ff3f0f9af3f8c9",
+  "eventId": "rep_vrd_6ed7af4431923f9cb4ff8f8f0af36ac168f991f3f9f7f0f3f9ff3f0f9af3f8c9",
+  "tenantId": "tenant_default",
+  "occurredAt": "2026-02-11T12:00:00.000Z",
+  "eventKind": "verdict_issued",
+  "subject": {
+    "agentId": "agt_payee_demo",
+    "toolId": "tool_call",
+    "counterpartyAgentId": "agt_payer_demo",
+    "role": "payee"
+  },
+  "sourceRef": {
+    "kind": "arbitration_verdict",
+    "artifactId": "arbitration_verdict_avd_demo",
+    "agreementHash": "1111111111111111111111111111111111111111111111111111111111111111",
+    "verdictHash": "6ed7af4431923f9cb4ff8f8f0af36ac168f991f3f9f7f0f3f9ff3f0f9af3f8c9",
+    "disputeId": "disp_tc_deadbeef",
+    "caseId": "arb_case_tc_deadbeef"
+  },
+  "facts": {
+    "verdictOutcome": "payee_win",
+    "releaseRatePct": 100,
+    "amountCents": 2000
+  },
+  "eventHash": "6c48dc294a69413fe9f4548ef25319c3c73396018249b1667eb52447c3ecba63"
+}

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

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": "VerificationReport.v1",
+  "profile": "strict",
+  "tool": { "name": "settld", "version": "0.0.0-example", "commit": "0123456789abcdef0123456789abcdef01234567" },
+  "warnings": [],
+  "signer": { "keyId": "key_example", "scope": "global", "governanceEventRef": null },
+  "bundleHeadAttestation": {
+    "schemaVersion": "BundleHeadAttestation.v1",
+    "attestationHash": "0000000000000000000000000000000000000000000000000000000000000000",
+    "signerKeyId": "key_example",
+    "signedAt": "2026-01-01T00:00:00.000Z",
+    "manifestHash": "0000000000000000000000000000000000000000000000000000000000000000"
+  },
+  "subject": {
+    "type": "JobProofBundle.v1",
+    "tenantId": "tenant_example",
+    "createdAt": "2026-01-01T00:00:00.000Z",
+    "manifestHash": "0000000000000000000000000000000000000000000000000000000000000000"
+  },
+  "reportHash": "0000000000000000000000000000000000000000000000000000000000000000",
+  "signature": null,
+  "signerKeyId": null,
+  "signedAt": null
+}