settld 0.1.2 → 0.1.5

package/README.md

@@ -1,6 +1,45 @@
 # Settld
 
-Settld is the closure layer for delegated autonomous work.
+Settld is verify-before-release receipts for delegated autonomous work: **verify what happened**, retain **audit-ready evidence**, and **settle** outcomes deterministically.
+
+Wedge (current): an x402-style gateway that turns `HTTP 402` into `hold -> verify -> release/refund`, with deterministic receipts. Default posture is strict: **hold 100% until PASS**; **refund on FAIL**. Optionally require an **Ed25519 provider signature** over the upstream response hash.
+
+What you get in this repo:
+
+- `settld` CLI for bundle verification + a conformance pack (CI / audit evidence)
+- Runnable Node.js prototype (API + agent simulator)
+- Protocol + product docs (schemas/specs, trust anchors, warning codes, etc.)
+- Positioning and go-to-market narrative: `docs/marketing/agent-commerce-substrate.md`
+
+## 10-minute Demo: Verified Receipt (x402 Verify-Before-Release)
+
+Prereqs: Node.js 20+.
+
+```sh
+npm ci && npm run quickstart:x402
+```
+
+By default the script keeps services running until you press Ctrl+C.
+
+If you already ran `npm ci` in this repo, you can skip it:
+
+```sh
+npm run quickstart:x402
+```
+
+To run once and exit (CI-friendly):
+
+```sh
+npm ci && SETTLD_QUICKSTART_KEEP_ALIVE=0 npm run quickstart:x402
+```
+
+Success: prints `OK`, a `gateId=...`, and a `gateStateUrl=...`.
+
+Next: `docs/QUICKSTART_X402_GATEWAY.md`
+
+If you tried and failed:
+
+- Run `./scripts/collect-debug.sh` and open a GitHub issue using the "Quickstart failure" template: https://github.com/aidenlippert/settld/issues/new?template=quickstart-failure.yml
 
 The core mental model in this repo:
 
@@ -9,16 +48,17 @@ The core mental model in this repo:
 - **Trust is a black box**: telemetry/evidence are append-only, hash-chained, and (optionally) signed.
 - **Money is a ledger**: every settlement is double-entry and must always balance.
 
-This repository is a runnable Node.js prototype (API + agent simulator) and a set of product/architecture docs.
-
 ## Bundle verification (CI / audit evidence)
 
 - Overview: `docs/OVERVIEW.md`
 - Quickstart: `docs/QUICKSTART_VERIFY.md`
 - Kernel v0 quickstart (local dev stack + conformance + explorer): `docs/QUICKSTART_KERNEL_V0.md`
+- Kernel v0 product surface (enforced vs not enforced): `docs/KERNEL_V0.md`
+- Kernel Compatible policy + listing format: `docs/KERNEL_COMPATIBLE.md`
 - Producer bootstrap: `docs/QUICKSTART_PRODUCE.md` (trust → produce → strict verify)
 - SDK quickstart (first verified run): `docs/QUICKSTART_SDK.md`
 - SDK quickstart (Python): `docs/QUICKSTART_SDK_PYTHON.md`
+- x402 gateway quickstart (verify-before-release wedge): `docs/QUICKSTART_X402_GATEWAY.md`
 - Integrations (GitHub Actions templates): `docs/integrations/README.md`
 - Protocol contract (schemas/specs): `docs/spec/README.md`
 - Conformance pack (portable oracle): `conformance/v1/README.md`
@@ -117,6 +157,18 @@ Run conformance (kernel control plane, disputes + holdback):
 ./bin/settld.js conformance kernel --ops-token tok_ops
 ```
 
+No-clone registry flow:
+
+```sh
+npx settld conformance kernel --ops-token tok_ops
+```
+
+No-clone release artifact flow (download `settld-<version>.tgz` from GitHub Releases):
+
+```sh
+npx --yes --package ./settld-<version>.tgz settld conformance kernel --ops-token tok_ops
+```
+
 Ops workspaces (HTML):
 
 - Kernel Explorer: `GET /ops/kernel/workspace` (requires ops token)
@@ -142,9 +194,15 @@ Ops workspaces (HTML):
 - `docs/QUICKSTART_PRODUCE.md`
 - `docs/QUICKSTART_SDK.md`
 - `docs/QUICKSTART_SDK_PYTHON.md`
+- `docs/QUICKSTART_MCP.md`
+- `docs/QUICKSTART_MCP_HOSTS.md`
 - `docs/ADOPTION_CHECKLIST.md`
 - `docs/SUPPORT.md`
 - `docs/OPERATIONS_SIGNING.md`
+- `docs/KERNEL_V0.md`
+- `docs/KERNEL_COMPATIBLE.md`
+- `docs/ops/PAYMENTS_ALPHA_R5.md`
+- `docs/ops/X402_PILOT_WEEKLY_METRICS.md`
 - `docs/ops/ARTIFACT_VERIFICATION_STATUS.md`
 - `docs/ops/TRUST_CONFIG_WIZARD.md`
 - `docs/integrations/README.md`

package/SETTLD_VERSION

@@ -1 +1 @@
-0.1.2
+0.1.5

package/bin/settld-mcp

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../scripts/mcp/settld-mcp-server.mjs';

package/bin/settld.js

@@ -14,6 +14,7 @@ function usage() {
   console.error("  settld conformance kernel:list");
   console.error("  settld closepack export --agreement-hash <sha256> --out <path.zip> [--ops-token tok_ops] [--base-url http://127.0.0.1:3000] [--tenant-id tenant_default] [--protocol 1.0]");
   console.error("  settld closepack verify <path.zip> [--json-out <path.json>]");
+  console.error("  settld x402 receipt verify <receipt.json|-> [--strict] [--format json|text] [--json-out <path>]");
   console.error("  settld dev up [--no-build] [--foreground]");
   console.error("  settld dev down [--wipe]");
   console.error("  settld dev ps");
@@ -203,6 +204,18 @@ function main() {
     process.exit(1);
   }
 
+  if (cmd === "x402") {
+    const sub = argv[1] ? String(argv[1]) : "";
+    const sub2 = argv[2] ? String(argv[2]) : "";
+    if (sub === "receipt" && sub2 === "verify") {
+      return runNodeScript("scripts/x402/receipt-verify.mjs", argv.slice(3));
+    }
+    usage();
+    // eslint-disable-next-line no-console
+    console.error(`unknown x402 subcommand: ${sub}${sub2 ? ` ${sub2}` : ""}`);
+    process.exit(1);
+  }
+
   usage();
   // eslint-disable-next-line no-console
   console.error(`unknown command: ${cmd}`);

package/conformance/kernel-v0/README.md

@@ -30,6 +30,8 @@ Example (docker compose dev stack):
 
 ```sh
 ./bin/settld.js conformance kernel --ops-token tok_ops
+# or, once published:
+npx settld conformance kernel --ops-token tok_ops
 ```
 
 Optional:
@@ -38,6 +40,7 @@ Optional:
 node conformance/kernel-v0/run.mjs --ops-token tok_ops --case tool_call_holdback_release
 node conformance/kernel-v0/run.mjs --ops-token tok_ops --case marketplace_run_replay_evaluate
 node conformance/kernel-v0/run.mjs --ops-token tok_ops --list
+node conformance/kernel-v0/run.mjs --ops-token tok_ops --closepack-out-dir /tmp/settld-closepacks
 ```
 
 Write a machine-readable report:
@@ -58,3 +61,7 @@ The runner prints `INFO ...` lines with `agreementHash` / `runId` and direct lin
   - `adjustmentId = sadj_agmt_${agreementHash}_holdback`
   - `kind = holdback_release` (payee win) or `holdback_refund` (payer win)
 - Applying the same verdict again is **idempotent** (returns the existing adjustment and reports `alreadyExisted=true`).
+- Reputation facts remain stable under retries/tick reruns, and closepack verify enforces sourceRef hash resolution against the portable artifact graph.
+- A kernel closepack can be exported from `agreementHash` and verified offline:
+  - `settld closepack export ...`
+  - `settld closepack verify ...`

package/conformance/kernel-v0/run.mjs

@@ -12,6 +12,9 @@ import {
   signHashHexEd25519,
   verifyHashHexEd25519
 } from "../../src/core/crypto.js";
+import { buildDisputeOpenEnvelopeV1 } from "../../src/core/dispute-open-envelope.js";
+import { exportToolCallClosepack, verifyToolCallClosepackZip } from "../../scripts/closepack/lib.mjs";
+import { SETTLEMENT_VERIFIER_SOURCE } from "../../src/core/settlement-verifier.js";
 
 function parseArgs(argv) {
   const out = {
@@ -22,6 +25,7 @@ function parseArgs(argv) {
     opsToken: null,
     caseId: null,
     jsonOut: null,
+    closepackOutDir: null,
     list: false,
     help: false
   };
@@ -62,6 +66,11 @@ function parseArgs(argv) {
       i += 1;
       continue;
     }
+    if (a === "--closepack-out-dir") {
+      out.closepackOutDir = String(argv[i + 1] ?? "");
+      i += 1;
+      continue;
+    }
     if (a === "--list") {
       out.list = true;
       continue;
@@ -79,7 +88,7 @@ function usage() {
   // eslint-disable-next-line no-console
   console.error("usage:");
   console.error(
-    "  node conformance/kernel-v0/run.mjs --ops-token <tok_opsw> [--base-url http://127.0.0.1:3000] [--tenant-id tenant_default] [--protocol 1.0] [--case <id>] [--json-out <path>] [--list]"
+    "  node conformance/kernel-v0/run.mjs --ops-token <tok_opsw> [--base-url http://127.0.0.1:3000] [--tenant-id tenant_default] [--protocol 1.0] [--case <id>] [--json-out <path>] [--closepack-out-dir <dir>] [--list]"
   );
   console.error("");
   console.error("notes:");
@@ -242,6 +251,65 @@ function assertArbitrationVerdictArtifact({ artifact, caseId, runId, disputeId,
   assertArtifactHash(artifact);
 }
 
+function buildSignedDisputeOpenEnvelopeV1({
+  tenantId,
+  agreementHash,
+  receiptHash,
+  holdHash,
+  openedByAgentId,
+  signerKeyId,
+  signerPrivateKeyPem
+}) {
+  const envelopeCoreWithPlaceholder = buildDisputeOpenEnvelopeV1({
+    envelopeId: `dopen_tc_${agreementHash}`,
+    caseId: `arb_case_tc_${agreementHash}`,
+    tenantId,
+    agreementHash,
+    receiptHash,
+    holdHash,
+    openedByAgentId,
+    openedAt: new Date().toISOString(),
+    reasonCode: "TOOL_CALL_DISPUTE",
+    nonce: `nonce_${sha256Hex(`${agreementHash}:${openedByAgentId}`).slice(0, 16)}`,
+    signerKeyId,
+    signature: "placeholder"
+  });
+  const signature = signHashHexEd25519(envelopeCoreWithPlaceholder.envelopeHash, signerPrivateKeyPem);
+  return { ...envelopeCoreWithPlaceholder, signature };
+}
+
+function assertDisputeOpenEnvelopeArtifact({
+  artifact,
+  agreementHash,
+  receiptHash,
+  holdHash,
+  caseId,
+  openedByAgentId,
+  signerKeyId,
+  signerPublicKeyPem
+}) {
+  assert(artifact && typeof artifact === "object" && !Array.isArray(artifact), "dispute-open artifact must be an object");
+  assert(String(artifact.schemaVersion ?? "") === "DisputeOpenEnvelope.v1", "dispute-open artifact schemaVersion mismatch");
+  assert(String(artifact.artifactType ?? "") === "DisputeOpenEnvelope.v1", "dispute-open artifact artifactType mismatch");
+  assert(String(artifact.caseId ?? "") === String(caseId), "dispute-open artifact caseId mismatch");
+  assert(String(artifact.agreementHash ?? "") === String(agreementHash), "dispute-open artifact agreementHash mismatch");
+  assert(String(artifact.receiptHash ?? "") === String(receiptHash), "dispute-open artifact receiptHash mismatch");
+  assert(String(artifact.holdHash ?? "") === String(holdHash), "dispute-open artifact holdHash mismatch");
+  assert(String(artifact.openedByAgentId ?? "") === String(openedByAgentId), "dispute-open artifact openedByAgentId mismatch");
+  assert(String(artifact.signerKeyId ?? "") === String(signerKeyId), "dispute-open artifact signerKeyId mismatch");
+  assert(isSha256Hex(String(artifact.envelopeHash ?? "")), "dispute-open artifact envelopeHash must be sha256 hex");
+  assert(typeof artifact.signature === "string" && artifact.signature.trim() !== "", "dispute-open artifact signature missing");
+  assert(
+    verifyHashHexEd25519({
+      hashHex: String(artifact.envelopeHash),
+      signatureBase64: String(artifact.signature),
+      publicKeyPem: signerPublicKeyPem
+    }) === true,
+    "dispute-open signature verification failed"
+  );
+  assertArtifactHash(artifact);
+}
+
 function buildSignedArbitrationVerdictV1({
   tenantId,
   runId,
@@ -291,6 +359,8 @@ async function runToolCallHoldbackDisputeCase({ opts, verdict }) {
   const arbiterKeys = createEd25519Keypair();
 
   const arbiterKeyId = keyIdFromPublicKeyPem(arbiterKeys.publicKeyPem);
+  const payerKeyId = keyIdFromPublicKeyPem(payerKeys.publicKeyPem);
+  const payeeKeyId = keyIdFromPublicKeyPem(payeeKeys.publicKeyPem);
 
   await requestJson({
     ...opts,
@@ -381,6 +451,15 @@ async function runToolCallHoldbackDisputeCase({ opts, verdict }) {
       receiptHash,
       holdHash,
       openedByAgentId: verdict === "payer" ? payerAgentId : payeeAgentId,
+      disputeOpenEnvelope: buildSignedDisputeOpenEnvelopeV1({
+        tenantId: opts.tenantId,
+        agreementHash,
+        receiptHash,
+        holdHash,
+        openedByAgentId: verdict === "payer" ? payerAgentId : payeeAgentId,
+        signerKeyId: verdict === "payer" ? payerKeyId : payeeKeyId,
+        signerPrivateKeyPem: verdict === "payer" ? payerKeys.privateKeyPem : payeeKeys.privateKeyPem
+      }),
       arbiterAgentId,
       summary: "Conformance dispute",
       evidenceRefs: []
@@ -397,12 +476,40 @@ async function runToolCallHoldbackDisputeCase({ opts, verdict }) {
   assert(settlementId, "arbitrationCase.settlementId missing");
   assert(runId, "arbitrationCase.runId missing");
 
+  let duplicateOpenErr = null;
+  try {
+    await requestJson({
+      ...opts,
+      method: "POST",
+      pathname: "/tool-calls/arbitration/open",
+      idempotencyKey: `conf_${suffix}_open_duplicate`,
+      body: {
+        agreementHash,
+        receiptHash,
+        holdHash,
+        openedByAgentId: verdict === "payer" ? payerAgentId : payeeAgentId,
+        arbiterAgentId,
+        summary: "Conformance dispute duplicate open",
+        evidenceRefs: []
+      }
+    });
+  } catch (err) {
+    duplicateOpenErr = err;
+  }
+  assert(duplicateOpenErr && Number(duplicateOpenErr.status) === 409, "duplicate dispute open must return 409");
+  assert(
+    String(duplicateOpenErr?.body?.code ?? "") === "DISPUTE_ALREADY_OPEN",
+    "duplicate dispute open must fail with DISPUTE_ALREADY_OPEN"
+  );
+
   // Ensure the case artifact is vendored.
   const caseArtifactId = `arbitration_case_${caseId}`;
   assert(
     open?.arbitrationCaseArtifact && typeof open.arbitrationCaseArtifact === "object" && String(open.arbitrationCaseArtifact.artifactId ?? "") === caseArtifactId,
     "open response missing arbitrationCaseArtifact.artifactId"
   );
+  const disputeOpenEnvelopeArtifactId = String(open?.disputeOpenEnvelopeArtifact?.artifactId ?? "");
+  assert(disputeOpenEnvelopeArtifactId === `dopen_tc_${agreementHash}`, "open response missing disputeOpenEnvelopeArtifact.artifactId");
   await requestJson({
     ...opts,
     method: "GET",
@@ -420,6 +527,17 @@ async function runToolCallHoldbackDisputeCase({ opts, verdict }) {
     expectedVerdictId: null,
     expectedVerdictHash: null
   });
+  const disputeOpenEnvelopeArtifact = await fetchArtifact({ opts, artifactId: disputeOpenEnvelopeArtifactId });
+  assertDisputeOpenEnvelopeArtifact({
+    artifact: disputeOpenEnvelopeArtifact,
+    agreementHash,
+    receiptHash,
+    holdHash,
+    caseId,
+    openedByAgentId: verdict === "payer" ? payerAgentId : payeeAgentId,
+    signerKeyId: verdict === "payer" ? payerKeyId : payeeKeyId,
+    signerPublicKeyPem: verdict === "payer" ? payerKeys.publicKeyPem : payeeKeys.publicKeyPem
+  });
 
   // Force the maintenance tick into the "window elapsed" branch, but ensure it blocks on the open arbitration case.
   await sleep(challengeWindowMs + 25);
@@ -558,6 +676,153 @@ async function runToolCallHoldbackDisputeCase({ opts, verdict }) {
     "second verdict submission should include arbitrationVerdictArtifact.artifactId"
   );
 
+  const replayEvaluate = await requestJson({
+    ...opts,
+    method: "GET",
+    pathname: `/ops/tool-calls/replay-evaluate?agreementHash=${encodeURIComponent(agreementHash)}`
+  });
+  assert(replayEvaluate && typeof replayEvaluate === "object", "tool-call replay-evaluate response missing");
+  assert(replayEvaluate?.comparisons?.chainConsistent === true, "tool-call replay-evaluate chainConsistent must be true");
+  assert(
+    String(replayEvaluate?.replay?.expected?.adjustmentKind ?? "") ===
+      (verdict === "payer" ? "holdback_refund" : "holdback_release"),
+    "tool-call replay-evaluate expected.adjustmentKind mismatch"
+  );
+
+  const reputationFacts = await requestJson({
+    ...opts,
+    method: "GET",
+    pathname: `/ops/reputation/facts?agentId=${encodeURIComponent(payeeAgentId)}&toolId=tool_call&window=allTime&includeEvents=1`
+  });
+  assert(reputationFacts && typeof reputationFacts === "object", "reputation facts response missing");
+  assert(Number(reputationFacts?.facts?.totals?.disputes?.opened ?? 0) >= 1, "reputation facts disputes.opened must be >= 1");
+  if (verdict === "payer") {
+    assert(Number(reputationFacts?.facts?.totals?.disputes?.payerWin ?? 0) >= 1, "reputation facts disputes.payerWin must be >= 1");
+  } else {
+    assert(Number(reputationFacts?.facts?.totals?.disputes?.payeeWin ?? 0) >= 1, "reputation facts disputes.payeeWin must be >= 1");
+  }
+  assert(
+    Number(reputationFacts?.facts?.totals?.economics?.adjustmentAppliedCents ?? 0) >= Number(settlementAdjustment?.amountCents ?? 0),
+    "reputation facts economics.adjustmentAppliedCents must include adjustment amount"
+  );
+  const reputationEvents = Array.isArray(reputationFacts?.events) ? reputationFacts.events : [];
+  const reputationEventIds = reputationEvents.map((row) => String(row?.eventId ?? "")).filter(Boolean);
+  assert(new Set(reputationEventIds).size === reputationEventIds.length, "reputation events must not contain duplicate eventId values");
+  const reputationAggregateBeforeRetry = normalizeForCanonicalJson(reputationFacts?.facts ?? {}, { path: "$" });
+  const pinnedAsOf = String(reputationFacts?.asOf ?? "");
+  assert(Number.isFinite(Date.parse(pinnedAsOf)), "reputation facts must include a valid asOf timestamp");
+  const disputeEventId = `rep_dsp_${agreementHash}`;
+  const verdictEventId = `rep_vrd_${String(verdictRes?.arbitrationVerdict?.verdictHash ?? "").toLowerCase()}`;
+  const adjustmentId = `sadj_agmt_${agreementHash}_holdback`;
+  const adjustmentEventId = `rep_adj_${adjustmentId}`;
+
+  const disputeEvent = reputationEvents.find((row) => String(row?.eventId ?? "") === disputeEventId);
+  assert(disputeEvent && typeof disputeEvent === "object", "reputation events must include dispute_opened event");
+  assert(String(disputeEvent?.sourceRef?.artifactId ?? "") === caseArtifactId, "dispute_opened sourceRef.artifactId mismatch");
+  assert(isSha256Hex(String(disputeEvent?.sourceRef?.hash ?? "")), "dispute_opened sourceRef.hash must be sha256");
+  const disputeStatus = await requestJson({
+    ...opts,
+    method: "GET",
+    pathname: `/artifacts/${encodeURIComponent(caseArtifactId)}/status`
+  });
+  assert(
+    String(disputeStatus?.artifactHash ?? "") === String(disputeEvent?.sourceRef?.hash ?? ""),
+    "dispute_opened sourceRef.hash must resolve to arbitration case artifact hash"
+  );
+
+  const verdictEvent = reputationEvents.find((row) => String(row?.eventId ?? "") === verdictEventId);
+  assert(verdictEvent && typeof verdictEvent === "object", "reputation events must include verdict_issued event");
+  assert(String(verdictEvent?.sourceRef?.artifactId ?? "") === verdictArtifactId, "verdict_issued sourceRef.artifactId mismatch");
+  assert(isSha256Hex(String(verdictEvent?.sourceRef?.hash ?? "")), "verdict_issued sourceRef.hash must be sha256");
+  const verdictStatus = await requestJson({
+    ...opts,
+    method: "GET",
+    pathname: `/artifacts/${encodeURIComponent(verdictArtifactId)}/status`
+  });
+  assert(
+    String(verdictStatus?.artifactHash ?? "") === String(verdictEvent?.sourceRef?.hash ?? ""),
+    "verdict_issued sourceRef.hash must resolve to arbitration verdict artifact hash"
+  );
+
+  const adjustmentEvent = reputationEvents.find((row) => String(row?.eventId ?? "") === adjustmentEventId);
+  assert(adjustmentEvent && typeof adjustmentEvent === "object", "reputation events must include adjustment_applied event");
+  assert(String(adjustmentEvent?.sourceRef?.sourceId ?? "") === adjustmentId, "adjustment_applied sourceRef.sourceId mismatch");
+  assert(isSha256Hex(String(adjustmentEvent?.sourceRef?.hash ?? "")), "adjustment_applied sourceRef.hash must be sha256");
+  const adjustmentStatus = await requestJson({
+    ...opts,
+    method: "GET",
+    pathname: `/ops/settlement-adjustments/${encodeURIComponent(adjustmentId)}`
+  });
+  assert(
+    String(adjustmentStatus?.adjustment?.adjustmentHash ?? "") === String(adjustmentEvent?.sourceRef?.hash ?? ""),
+    "adjustment_applied sourceRef.hash must resolve to settlement adjustment hash"
+  );
+  const reputationEventCountBeforeRetry = Number(reputationFacts?.facts?.totals?.eventCount ?? reputationEvents.length);
+
+  const tickAgain = await requestJson({
+    ...opts,
+    method: "POST",
+    pathname: "/ops/maintenance/tool-call-holdback/run",
+    idempotencyKey: `conf_${suffix}_tick_again`,
+    body: { dryRun: false, limit: 250 }
+  });
+  assert(tickAgain && typeof tickAgain === "object", "maintenance retry response missing");
+
+  const reputationFactsAfterRetry = await requestJson({
+    ...opts,
+    method: "GET",
+    pathname: `/ops/reputation/facts?agentId=${encodeURIComponent(payeeAgentId)}&toolId=tool_call&window=allTime&includeEvents=1`
+  });
+  const reputationFactsPinnedAsOf = await requestJson({
+    ...opts,
+    method: "GET",
+    pathname: `/ops/reputation/facts?agentId=${encodeURIComponent(payeeAgentId)}&toolId=tool_call&window=allTime&includeEvents=1&asOf=${encodeURIComponent(
+      pinnedAsOf
+    )}`
+  });
+  const reputationAggregateAfterRetry = normalizeForCanonicalJson(reputationFactsAfterRetry?.facts ?? {}, { path: "$" });
+  const reputationAggregatePinnedAsOf = normalizeForCanonicalJson(reputationFactsPinnedAsOf?.facts ?? {}, { path: "$" });
+  const reputationEventsAfterRetry = Array.isArray(reputationFactsAfterRetry?.events) ? reputationFactsAfterRetry.events : [];
+  const eventCountAfterRetry = Number(reputationFactsAfterRetry?.facts?.totals?.eventCount ?? reputationEventsAfterRetry.length);
+  assert(
+    eventCountAfterRetry === reputationEventCountBeforeRetry,
+    "reputation eventCount must remain stable across retry/tick reruns"
+  );
+  const retryEventIds = reputationEventsAfterRetry.map((row) => String(row?.eventId ?? "")).filter(Boolean);
+  assert(new Set(retryEventIds).size === retryEventIds.length, "reputation events must remain deduplicated after retries");
+  assert(
+    canonicalJsonStringify(reputationAggregateAfterRetry) === canonicalJsonStringify(reputationAggregateBeforeRetry),
+    "reputation aggregates must remain stable across retry/tick reruns"
+  );
+  assert(
+    canonicalJsonStringify(reputationAggregatePinnedAsOf) === canonicalJsonStringify(reputationAggregateBeforeRetry),
+    "reputation aggregates must remain stable for a pinned asOf window"
+  );
+
+  const closepackOutDir =
+    typeof opts.closepackOutDir === "string" && opts.closepackOutDir.trim() !== ""
+      ? path.resolve(process.cwd(), opts.closepackOutDir.trim())
+      : path.resolve("/tmp", "settld-kernel-closepacks");
+  const closepackZipPath = path.join(closepackOutDir, `${agreementHash}.zip`);
+
+  const closepackExport = await exportToolCallClosepack({
+    baseUrl: opts.baseUrl,
+    tenantId: opts.tenantId,
+    protocol: opts.protocol,
+    apiKey: opts.apiKey,
+    opsToken: opts.opsToken,
+    agreementHash,
+    outPath: closepackZipPath
+  });
+  assert(closepackExport?.ok === true, "closepack export must return ok=true");
+  assert(typeof closepackExport?.outPath === "string" && closepackExport.outPath.trim() !== "", "closepack export must return outPath");
+  assert(typeof closepackExport?.zipSha256 === "string" && /^[0-9a-f]{64}$/.test(closepackExport.zipSha256), "closepack export zipSha256 must be sha256 hex");
+
+  const closepackVerify = await verifyToolCallClosepackZip({ zipPath: closepackZipPath });
+  assert(closepackVerify?.ok === true, "closepack verify must return ok=true");
+  assert(closepackVerify?.replayMatch === true, "closepack verify must return replayMatch=true");
+  assert(closepackVerify?.sourceRefResolution?.ok === true, "closepack verify sourceRefResolution.ok must be true");
+
   return {
     agreementHash,
     receiptHash,
@@ -566,7 +831,13 @@ async function runToolCallHoldbackDisputeCase({ opts, verdict }) {
     disputeId,
     settlementId,
     runId,
-    adjustmentId: `sadj_agmt_${agreementHash}_holdback`
+    adjustmentId,
+    replayEvaluate,
+    closepack: {
+      path: closepackZipPath,
+      zipSha256: closepackExport.zipSha256,
+      verify: closepackVerify
+    }
   };
 }
 
@@ -641,7 +912,11 @@ async function runMarketplaceRunReplayEvaluateCase({ opts }) {
       amountCents: 10_000,
       currency: "USD",
       etaSeconds: 60,
-      note: "conformance bid"
+      note: "conformance bid",
+      verificationMethod: {
+        mode: "deterministic",
+        source: SETTLEMENT_VERIFIER_SOURCE.DETERMINISTIC_LATENCY_THRESHOLD_V1
+      }
     }
   });
 
@@ -707,6 +982,17 @@ async function runMarketplaceRunReplayEvaluateCase({ opts }) {
     pathname: `/runs/${encodeURIComponent(runId)}/settlement`
   });
   assert(settlement && typeof settlement === "object", "run settlement missing");
+  const decisionRecord = settlement?.decisionRecord ?? settlement?.settlement?.decisionTrace?.decisionRecord ?? null;
+  assert(decisionRecord && typeof decisionRecord === "object", "run settlement decisionRecord missing");
+  assert(
+    String(decisionRecord?.verifierRef?.modality ?? "").toLowerCase() === "deterministic",
+    "run settlement decisionRecord.verifierRef.modality must be deterministic"
+  );
+  assert(
+    String(decisionRecord?.verifierRef?.verifierId ?? "") === "settld.deterministic.latency-threshold",
+    "run settlement decisionRecord.verifierRef.verifierId mismatch"
+  );
+  assert(isSha256Hex(String(decisionRecord?.verifierRef?.verifierHash ?? "")), "run settlement decisionRecord.verifierRef.verifierHash must be sha256");
 
   const replayEvaluate = await requestJson({
     ...opts,
@@ -720,6 +1006,7 @@ async function runMarketplaceRunReplayEvaluateCase({ opts }) {
     replayEvaluate?.comparisons?.decisionRecordReplayCriticalMatchesStored === true,
     "replay-evaluate decisionRecordReplayCriticalMatchesStored must be true"
   );
+  assert(replayEvaluate?.comparisons?.verifierRefMatchesStored === true, "replay-evaluate verifierRefMatchesStored must be true");
 
   return {
     rfqId,
@@ -758,7 +1045,8 @@ async function main() {
     tenantId: opts.tenantId,
     protocol: opts.protocol,
     apiKey: opts.apiKey,
-    opsToken: opts.opsToken
+    opsToken: opts.opsToken,
+    closepackOutDir: opts.closepackOutDir
   };
 
   let pass = 0;

package/docs/ACCESS.md

@@ -0,0 +1,57 @@
+# Access (v0.3)
+
+Access is modeled as a first-class, **revocable**, **time-scoped** dependency of a job. Access secrets are never written to the event log; only references are.
+
+## Principles
+
+- **No secrets in logs**: the event stream stores `credentialRef` (e.g. `vault://...`), never door codes/passwords.
+- **Scoped and revocable**: access plans are time-bounded and can be revoked instantly.
+- **Execution is gated**: the system rejects execution start without an active access plan and access granted within the plan window.
+- **Revocation forces safe exit**: access revocation transitions the job to a safe-exit mode and rejects further “work” events.
+
+## Events
+
+### `ACCESS_PLAN_ISSUED` (server-signed)
+
+Payload shape (current prototype, strict):
+
+```json
+{
+  "jobId": "job_123",
+  "accessPlanId": "ap_456",
+  "method": "SMART_LOCK_CODE|BUILDING_CONCIERGE|ON_SITE_OWNER|DOCKED_IN_BUILDING",
+  "credentialRef": "vault://access/ap_456/v1",
+  "scope": { "areas": ["ENTRYWAY"], "noGo": ["BEDROOM_2"] },
+  "validFrom": "2026-01-26T18:00:00Z",
+  "validTo": "2026-01-26T22:00:00Z",
+  "revocable": true,
+  "requestedBy": "system|customer|ops"
+}
+```
+
+### `ACCESS_GRANTED` / `ACCESS_DENIED` (robot- or operator-signed)
+
+Payload includes the plan reference (no secrets):
+
+```json
+{ "jobId": "job_123", "accessPlanId": "ap_456", "method": "BUILDING_CONCIERGE" }
+```
+
+### `ACCESS_REVOKED` / `ACCESS_EXPIRED` (server-signed in v0.3)
+
+```json
+{ "jobId": "job_123", "accessPlanId": "ap_456", "requestedBy": "customer", "reason": "..." }
+```
+
+## Enforced invariants (v0.3)
+
+- `ACCESS_GRANTED`/`ACCESS_DENIED` are rejected unless:
+  - an `ACCESS_PLAN_ISSUED` exists, and
+  - the `accessPlanId` matches the current plan, and
+  - the event timestamp is within `[validFrom, validTo]`.
+- `EXECUTION_STARTED` is rejected unless:
+  - an access plan exists, and
+  - access is currently granted, and
+  - the event timestamp is within the plan window.
+- After `ACCESS_REVOKED`, the job moves to `ABORTING_SAFE_EXIT`, and “work” events are rejected.
+

package/docs/ADOPTION_CHECKLIST.md

@@ -0,0 +1,44 @@
+# Adoption checklist (design partner ready)
+
+Use this as an operational checklist to adopt Settld verification in CI with audit-grade evidence retention.
+
+## Verification posture
+
+- Decide strict vs non-strict (`docs/spec/STRICTNESS.md`).
+- Decide whether warnings gate builds (`--fail-on-warnings`, `docs/spec/WARNINGS.md`).
+- Decide required verification outputs to archive:
+  - Recommended: archive `VerifyCliOutput.v1` JSON + the bundle itself.
+
+## Trust anchors
+
+- Define who owns governance root keys (generation, storage, rotation).
+- Define how trust anchors are distributed to CI (secret store, repo file, env injection).
+- Define update process and emergency rotation response.
+
+See `docs/spec/TRUST_ANCHORS.md` and `docs/spec/TOOL_PROVENANCE.md`.
+
+## Key management + governance operations
+
+- Who is authorized to sign:
+  - bundle head attestations
+  - verification reports
+- Rotation and revocation procedures (who triggers, how fast, how communicated).
+- Decide whether timestamp proofs are required for historical acceptance.
+
+See `docs/spec/GovernancePolicy.v2.md` and `docs/spec/RevocationList.v1.md`.
+
+## Storage + retention
+
+- Where bundles live (artifact store) and retention period.
+- Whether verification happens on:
+  - the original produced bundle, or
+  - a downloaded bundle copy (must remain byte-identical).
+- Who can access archived bundles and verification receipts.
+
+## Release pinning + upgrades
+
+- Pin verifier version (SemVer) for CI stability.
+- Define upgrade cadence and rollback plan.
+
+See `docs/spec/VERSIONING.md` and `docs/RELEASING.md`.
+