settld 0.1.0

package/Dockerfile

@@ -0,0 +1,45 @@
+FROM node:20-bookworm-slim AS deps
+
+WORKDIR /app
+COPY package*.json ./
+COPY SETTLD_VERSION ./
+RUN if [ -f package-lock.json ]; then npm ci --omit=dev --ignore-scripts; else npm install --omit=dev --no-audit --no-fund --ignore-scripts; fi && npm cache clean --force
+
+FROM node:20-bookworm-slim AS prep
+RUN mkdir -p /data && chown -R 65532:65532 /data
+
+FROM gcr.io/distroless/nodejs20-debian12:nonroot AS runtime
+
+WORKDIR /app
+ENV NODE_ENV=production
+ENV HOME=/tmp
+
+ARG SETTLD_VERSION=0.0.0
+ARG GIT_SHA=unknown
+
+# Expose build metadata to the API (x-settld-build) and to operators.
+ENV SETTLD_VERSION=$SETTLD_VERSION
+ENV PROXY_BUILD=$GIT_SHA
+
+LABEL org.opencontainers.image.title="settld"
+LABEL org.opencontainers.image.version=$SETTLD_VERSION
+LABEL org.opencontainers.image.revision=$GIT_SHA
+
+# Copy dependencies first for better layer caching.
+COPY --from=deps /app/node_modules ./node_modules
+COPY --from=deps /app/package.json ./package.json
+COPY --from=deps /app/SETTLD_VERSION ./SETTLD_VERSION
+
+# Runtime-writable locations should be mounted as volumes in k8s; create /data with correct ownership for safety.
+COPY --from=prep /data /data
+
+# Copy application code.
+COPY src ./src
+COPY packages ./packages
+COPY services ./services
+COPY docs/pilot-kit ./docs/pilot-kit
+
+EXPOSE 3000
+
+# Distroless node image uses "node" as the entrypoint.
+CMD ["src/api/server.js"]

package/README.md

@@ -0,0 +1,150 @@
+# Settld
+
+Settld is the closure layer for delegated autonomous work.
+
+The core mental model in this repo:
+
+- **Jobs are state machines**: a job moves through explicit states (booked → executing → completed/aborted → settled).
+- **Everything else is events**: every transition and operational action emits an event that can be replayed.
+- **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`
+- 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`
+- Integrations (GitHub Actions templates): `docs/integrations/README.md`
+- Protocol contract (schemas/specs): `docs/spec/README.md`
+- Conformance pack (portable oracle): `conformance/v1/README.md`
+- Audit packet generator: `npm run audit:packet` (see `docs/RELEASE_CHECKLIST.md`)
+- Support / filing bugs: `docs/SUPPORT.md`
+
+## Quick start
+
+Start the API:
+
+```sh
+PROXY_OPS_TOKEN=tok_ops npm run dev:api
+```
+
+Or start the full local dev stack (Postgres + MinIO + API + receiver + finance sink):
+
+```sh
+./bin/settld.js dev up
+```
+
+Developer helper flow (recommended for local Neon/PG usage):
+
+```sh
+npm run dev:env:init
+# edit .env.dev once (DATABASE_URL, etc.)
+npm run dev:start
+```
+
+Optional: start local Postgres + MinIO (for `STORE=pg` and S3-style evidence storage):
+
+```sh
+docker compose up -d
+```
+
+Run the full stack (API + maintenance + receiver + finance sink) via compose profile:
+
+```sh
+docker compose --profile app up --build
+```
+
+Initialize MinIO buckets (optional; required for S3/MinIO-backed evidence/artifact demos):
+
+```sh
+docker compose --profile init run --rm minio-init
+```
+
+Run the API backed by Postgres:
+
+```sh
+export STORE=pg
+export DATABASE_URL=postgres://proxy:proxy@localhost:5432/proxy
+npm run dev:api
+```
+
+Use MinIO for evidence objects (S3-compatible, via presigned URLs):
+
+```sh
+export PROXY_EVIDENCE_STORE=minio
+export PROXY_EVIDENCE_S3_ENDPOINT=http://localhost:9000
+export PROXY_EVIDENCE_S3_REGION=us-east-1
+export PROXY_EVIDENCE_S3_BUCKET=proxy-evidence
+export PROXY_EVIDENCE_S3_ACCESS_KEY_ID=proxy
+export PROXY_EVIDENCE_S3_SECRET_ACCESS_KEY=proxysecret
+export PROXY_EVIDENCE_S3_FORCE_PATH_STYLE=1
+```
+
+Create a job:
+
+```sh
+curl -sS -X POST http://localhost:3000/jobs \
+  -H 'content-type: application/json' \
+  -d '{"templateId":"reset_lite","constraints":{"roomsAllowed":["kitchen","living_room"],"privacyMode":"minimal"}}' | jq
+```
+
+Run the agent simulator (registers an executor and runs a sample job lifecycle):
+
+```sh
+npm run agent:sim
+```
+
+Run tests:
+
+```sh
+npm test
+```
+
+Run conformance (bundle verification oracle):
+
+```sh
+./bin/settld.js conformance test
+```
+
+Run conformance (kernel control plane, disputes + holdback):
+
+```sh
+./bin/settld.js conformance kernel --ops-token tok_ops
+```
+
+Ops workspaces (HTML):
+
+- Kernel Explorer: `GET /ops/kernel/workspace` (requires ops token)
+
+## Docs
+
+- `docs/PRD.md`
+- `docs/ARCHITECTURE.md`
+- `docs/DOMAIN_MODEL.md`
+- `docs/JOB_STATE_MACHINE.md`
+- `docs/EVENT_ENVELOPE.md`
+- `docs/ACCESS.md`
+- `docs/SKILLS.md`
+- `docs/TRUST.md`
+- `docs/LEDGER.md`
+- `docs/SKILL_BUNDLE_FORMAT.md`
+- `docs/CERTIFICATION_CHECKLIST.md`
+- `docs/THREAT_MODEL.md`
+- `docs/INCIDENT_TAXONOMY.md`
+- `docs/ONCALL_PLAYBOOK.md`
+- `docs/MVP_BUILD_ORDER.md`
+- `docs/QUICKSTART_VERIFY.md`
+- `docs/QUICKSTART_PRODUCE.md`
+- `docs/QUICKSTART_SDK.md`
+- `docs/QUICKSTART_SDK_PYTHON.md`
+- `docs/ADOPTION_CHECKLIST.md`
+- `docs/SUPPORT.md`
+- `docs/OPERATIONS_SIGNING.md`
+- `docs/ops/ARTIFACT_VERIFICATION_STATUS.md`
+- `docs/ops/TRUST_CONFIG_WIZARD.md`
+- `docs/integrations/README.md`

package/SETTLD_VERSION

@@ -0,0 +1 @@
+0.0.0

package/bin/settld.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+function usage() {
+  // eslint-disable-next-line no-console
+  console.error("usage:");
+  console.error("  settld --version");
+  console.error("  settld conformance test [--case <id>] [--bin settld-verify] [--node-bin <path/to/settld-verify.js>] [--keep-temp]");
+  console.error("  settld conformance list");
+  console.error("  settld conformance kernel --ops-token <tok_opsw> [--base-url http://127.0.0.1:3000] [--tenant-id tenant_default] [--protocol 1.0] [--case <id>]");
+  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 dev up [--no-build] [--foreground]");
+  console.error("  settld dev down [--wipe]");
+  console.error("  settld dev ps");
+  console.error("  settld dev logs [--follow] [--service api]");
+  console.error("  settld dev info");
+  console.error("  settld init capability <name> [--out <dir>] [--force]");
+}
+
+function repoRoot() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  return path.resolve(here, "..");
+}
+
+function readVersion() {
+  try {
+    const fp = path.join(repoRoot(), "SETTLD_VERSION");
+    return fs.readFileSync(fp, "utf8").trim();
+  } catch {
+    return null;
+  }
+}
+
+function runNodeScript(scriptRelPath, args) {
+  const script = path.join(repoRoot(), scriptRelPath);
+  const res = spawnSync(process.execPath, [script, ...args], { stdio: "inherit" });
+  process.exit(typeof res.status === "number" ? res.status : 1);
+}
+
+function runCommandOrExit(cmd, args, { cwd } = {}) {
+  const res = spawnSync(cmd, args, { stdio: "inherit", cwd: cwd ?? repoRoot() });
+  if (res.error && res.error.code === "ENOENT") {
+    // eslint-disable-next-line no-console
+    console.error(`missing executable: ${cmd}`);
+    process.exit(127);
+  }
+  process.exit(typeof res.status === "number" ? res.status : 1);
+}
+
+function dockerCompose(args) {
+  // Prefer `docker compose` (newer), fall back to `docker-compose` (older installs).
+  const primary = spawnSync("docker", ["compose", ...args], { stdio: "inherit", cwd: repoRoot() });
+  if (!primary.error && typeof primary.status === "number") return primary.status;
+  if (primary.error && primary.error.code === "ENOENT") {
+    // No docker binary; try docker-compose anyway.
+    const fallback = spawnSync("docker-compose", args, { stdio: "inherit", cwd: repoRoot() });
+    if (fallback.error && fallback.error.code === "ENOENT") {
+      // eslint-disable-next-line no-console
+      console.error("missing executable: docker (or docker-compose)");
+      return 127;
+    }
+    return typeof fallback.status === "number" ? fallback.status : 1;
+  }
+  // docker exists but compose subcommand may not; try docker-compose.
+  const fallback = spawnSync("docker-compose", args, { stdio: "inherit", cwd: repoRoot() });
+  if (fallback.error && fallback.error.code === "ENOENT") {
+    // eslint-disable-next-line no-console
+    console.error("missing executable: docker-compose");
+    return 127;
+  }
+  return typeof fallback.status === "number" ? fallback.status : 1;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0] ? String(argv[0]) : "";
+
+  if (!cmd || cmd === "-h" || cmd === "--help") {
+    usage();
+    process.exit(cmd ? 0 : 1);
+  }
+
+  if (cmd === "--version" || cmd === "-v") {
+    // eslint-disable-next-line no-console
+    console.log(readVersion() ?? "unknown");
+    process.exit(0);
+  }
+
+  if (cmd === "conformance") {
+    const sub = argv[1] ? String(argv[1]) : "test";
+    if (sub === "test") return runNodeScript("conformance/v1/run.mjs", argv.slice(2));
+    if (sub === "list") return runNodeScript("conformance/v1/run.mjs", ["--list", ...argv.slice(2)]);
+    if (sub === "kernel") return runNodeScript("conformance/kernel-v0/run.mjs", argv.slice(2));
+    if (sub === "kernel:list") return runNodeScript("conformance/kernel-v0/run.mjs", ["--list", ...argv.slice(2)]);
+    usage();
+    // eslint-disable-next-line no-console
+    console.error(`unknown conformance subcommand: ${sub}`);
+    process.exit(1);
+  }
+
+  if (cmd === "dev") {
+    const sub = argv[1] ? String(argv[1]) : "";
+    const rest = argv.slice(2);
+    if (!sub) {
+      usage();
+      // eslint-disable-next-line no-console
+      console.error("missing dev subcommand");
+      process.exit(1);
+    }
+
+    if (sub === "up") {
+      const build = !rest.includes("--no-build");
+      const foreground = rest.includes("--foreground");
+      const upArgs = ["--profile", "app", "up", ...(foreground ? [] : ["-d"]), ...(build ? ["--build"] : [])];
+      const upStatus = dockerCompose(upArgs);
+      if (upStatus !== 0) process.exit(upStatus);
+      const initStatus = dockerCompose(["--profile", "init", "run", "--rm", "minio-init"]);
+      if (initStatus !== 0) process.exit(initStatus);
+      // eslint-disable-next-line no-console
+      console.log("");
+      // eslint-disable-next-line no-console
+      console.log("dev stack is up:");
+      // eslint-disable-next-line no-console
+      console.log("  baseUrl:   http://127.0.0.1:3000");
+      // eslint-disable-next-line no-console
+      console.log("  tenantId:  tenant_default");
+      // eslint-disable-next-line no-console
+      console.log("  opsToken:  tok_ops");
+      // eslint-disable-next-line no-console
+      console.log("  explorer:  http://127.0.0.1:3000/ops/kernel/workspace?opsToken=tok_ops");
+      process.exit(0);
+    }
+
+    if (sub === "down") {
+      const wipe = rest.includes("--wipe");
+      const downArgs = ["--profile", "app", "down", ...(wipe ? ["-v"] : [])];
+      process.exit(dockerCompose(downArgs));
+    }
+
+    if (sub === "ps") {
+      process.exit(dockerCompose(["--profile", "app", "ps"]));
+    }
+
+    if (sub === "logs") {
+      const follow = rest.includes("--follow") || rest.includes("-f");
+      const serviceIdx = rest.findIndex((v) => v === "--service");
+      const service = serviceIdx >= 0 ? String(rest[serviceIdx + 1] ?? "").trim() : "";
+      const tailArgs = ["--profile", "app", "logs", ...(follow ? ["-f"] : []), ...(service ? [service] : [])];
+      process.exit(dockerCompose(tailArgs));
+    }
+
+    if (sub === "info") {
+      // eslint-disable-next-line no-console
+      console.log(JSON.stringify({ baseUrl: "http://127.0.0.1:3000", tenantId: "tenant_default", opsToken: "tok_ops" }, null, 2));
+      process.exit(0);
+    }
+
+    usage();
+    // eslint-disable-next-line no-console
+    console.error(`unknown dev subcommand: ${sub}`);
+    process.exit(1);
+  }
+
+  if (cmd === "init") {
+    const sub = argv[1] ? String(argv[1]) : "";
+    if (!sub) {
+      usage();
+      // eslint-disable-next-line no-console
+      console.error("missing init subcommand");
+      process.exit(1);
+    }
+    if (sub === "capability") {
+      return runNodeScript("scripts/init/capability.mjs", argv.slice(2));
+    }
+    usage();
+    // eslint-disable-next-line no-console
+    console.error(`unknown init subcommand: ${sub}`);
+    process.exit(1);
+  }
+
+  if (cmd === "closepack") {
+    const sub = argv[1] ? String(argv[1]) : "";
+    if (!sub) {
+      usage();
+      // eslint-disable-next-line no-console
+      console.error("missing closepack subcommand");
+      process.exit(1);
+    }
+    if (sub === "export") {
+      return runNodeScript("scripts/closepack/export.mjs", argv.slice(2));
+    }
+    if (sub === "verify") {
+      return runNodeScript("scripts/closepack/verify.mjs", argv.slice(2));
+    }
+    usage();
+    // eslint-disable-next-line no-console
+    console.error(`unknown closepack subcommand: ${sub}`);
+    process.exit(1);
+  }
+
+  usage();
+  // eslint-disable-next-line no-console
+  console.error(`unknown command: ${cmd}`);
+  process.exit(1);
+}
+
+main();

package/conformance/README.md

@@ -0,0 +1,14 @@
+# Conformance packs
+
+Conformance packs are **language-agnostic test oracles** for Settld verification.
+
+They are intended for:
+
+- external verifier implementations (Go/Rust/etc.)
+- auditors and partners who want “no guessing” reproducibility
+- internal release gating (prevent protocol drift)
+
+## Packs
+
+- `conformance/v1/` — first conformance pack for protocol `v1` objects.
+

package/conformance/kernel-v0/README.md

@@ -0,0 +1,60 @@
+# Kernel Conformance (v0)
+
+This conformance pack exercises Settld's **economic kernel control plane** behavior for:
+
+- Tool-call holdback escrow (`FundingHold.v1`)
+- Dispute opening (`ArbitrationCase.v1` metadata `caseType: "tool_call"`)
+- Holdback maintenance freeze while a case is open
+- Deterministic verdict adjustment issuance (`SettlementAdjustment.v1`)
+- Run settlement replay evaluation (`GET /runs/:runId/settlement/replay-evaluate`)
+
+It is intentionally **invariant-focused** (idempotency, deterministic IDs, and escrow safety), not deep object-equality snapshotting.
+
+## Run
+
+1. Start the API with an ops token that has `ops_write`:
+
+Example (local):
+
+```sh
+PROXY_OPS_TOKENS='tok_ops:ops_read,ops_write,finance_read,finance_write,audit_read' npm run dev:api
+```
+
+Example (docker compose dev stack):
+
+```sh
+./bin/settld.js dev up
+```
+
+2. Run conformance:
+
+```sh
+./bin/settld.js conformance kernel --ops-token tok_ops
+```
+
+Optional:
+
+```sh
+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
+```
+
+Write a machine-readable report:
+
+```sh
+./bin/settld.js conformance kernel --ops-token tok_ops --json-out /tmp/settld-kernel-v0-report.json
+```
+
+The runner prints `INFO ...` lines with `agreementHash` / `runId` and direct links to:
+
+- Kernel Explorer: `GET /ops/kernel/workspace?opsToken=...&agreementHash=...`
+- Replay evaluate: `GET /runs/:runId/settlement/replay-evaluate`
+
+## What It Asserts
+
+- A holdback maintenance tick will **not auto-release** held funds when a matching tool-call arbitration case is open.
+- On verdict issuance, the server creates **exactly one** deterministic adjustment:
+  - `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`).

package/conformance/kernel-v0/cases.json

@@ -0,0 +1,19 @@
+{
+  "schemaVersion": "KernelConformanceCases.v0",
+  "cases": [
+    {
+      "id": "tool_call_holdback_release",
+      "kind": "tool_call_holdback_dispute",
+      "verdict": "payee"
+    },
+    {
+      "id": "tool_call_holdback_refund",
+      "kind": "tool_call_holdback_dispute",
+      "verdict": "payer"
+    },
+    {
+      "id": "marketplace_run_replay_evaluate",
+      "kind": "marketplace_run_replay_evaluate"
+    }
+  ]
+}