settld 0.1.2 → 0.2.0

package/docs/blog/2026-02-14-your-ai-agent-just-spent-500-where-is-the-receipt.md

@@ -0,0 +1,73 @@
+# Your AI Agent Just Spent $500. Where's the Receipt?
+
+Every agent stack today can do the work.
+
+What it cannot do is produce a receipt you can actually trust.
+
+If you are shipping agents, you have this problem already:
+
+- Your agent calls tools, vendors, models, and other agents.
+- Money moves.
+- Later someone asks: "What did we get for that spend?"
+
+Most teams answer with logs, screenshots, and vibes. That does not scale, and it does not pass a CFO or audit review.
+
+Settld is the missing layer between "work done" and "money moved": deterministic settlement with verifiable evidence and a receipt trail.
+
+This post is a 10-minute, self-serve demo: put a thin gateway in front of an `x402`-style API. When the upstream says `402 Payment Required`, the gateway creates a Settld hold. When the upstream returns the resource, Settld verifies evidence and releases (or holds back) deterministically.
+
+## The Wedge: x402 Gateway (Verify Before Release)
+
+x402 gives you a clean payment negotiation surface at the HTTP layer.
+
+But it still does not solve:
+
+- Proving the work/resource was delivered correctly
+- Applying deterministic payout logic
+- Producing a receipt trail that a counterparty can verify offline
+
+The x402 gateway is the smallest thing you can install to feel the difference immediately:
+
+1. Client requests `/resource`
+2. Upstream replies `402` with `x-payment-required`
+3. Gateway creates a Settld gate + escrow hold and returns `x-settld-gate-id`
+4. Client retries with `x-settld-gate-id` + payment proof
+5. Gateway verifies the delivered response, Settld issues a deterministic decision and receipt
+
+You do not need to redesign your API. You put a proxy in front of it.
+
+## Run It Locally (10 minutes)
+
+This repo includes:
+
+- A local Settld API (in-memory)
+- A mock x402-style upstream (`services/x402-gateway/examples/upstream-mock.js`)
+- The x402 gateway (`services/x402-gateway/`)
+
+Quickstart:
+
+- `docs/QUICKSTART_X402_GATEWAY.md`
+
+The single thing to notice: your client experience stays the same (it still sees a `402`), but now there is an explicit settlement object with deterministic outcomes and an audit-friendly trail.
+
+## What You Get (Immediately)
+
+- A stable "gate id" you can attach to your own logs and job ids
+- A deterministic verify+decision step (no human-in-the-loop required for the happy path)
+- A receipt-like trail (`x-settld-*` headers + API query surface) that you can store and audit later
+
+## What This Unlocks
+
+Once you have `verify -> decide -> receipt` in the loop, you can add the things enterprises and marketplaces actually require:
+
+- Holdbacks and dispute windows that do not rely on customer support tickets
+- Reputation events based on completed/failed/disputed settlements
+- Governance controls ("do not spend with low-reputation counterparties", "cap delegation depth", "require approval above $X")
+- Delegated, multi-hop settlement (the hard moat)
+
+## If You Build Agents, This Is the New Default
+
+Agents will transact. The only question is whether they transact with receipts and deterministic settlement, or with chaos.
+
+If you want to wire this into a real x402 flow (real payment rail, no demo shortcuts), the gateway stays the same shape. The funding source changes.
+

package/docs/examples/x402-provider-payout-registry.example.json

@@ -0,0 +1,14 @@
+{
+  "schemaVersion": "X402ProviderPayoutRegistry.v1",
+  "providers": [
+    {
+      "providerId": "agt_x402_payee_127_0_0_1:9402",
+      "destination": {
+        "type": "circle_wallet",
+        "walletId": "wallet_123",
+        "blockchain": "BASE-SEPOLIA",
+        "token": "USDC"
+      }
+    }
+  ]
+}

package/docs/gitbook/README.md

@@ -0,0 +1,64 @@
+# Settld Documentation
+
+Settld is the enforceable transaction layer for autonomous work.
+
+If an agent can call a tool but cannot prove **who authorized it**, **what was agreed**, **what happened**, and **why money moved**, you do not have commerce. You have logs.
+
+Settld gives you a canonical economic loop:
+
+`Agreement -> Hold -> Evidence -> Decision -> Receipt -> Dispute -> Adjustment`
+
+## Start here
+
+- [Quickstart](./quickstart.md) — one-command onboarding to first verified paid receipt
+- [Core Primitives](./core-primitives.md) — protocol objects and invariants
+- [API Reference](./api-reference.md) — endpoint map and auth model
+- [Conformance](./conformance.md) — machine-checkable correctness gates
+- [Closepacks](./closepacks.md) — offline verification workflow
+
+## One-command onboarding
+
+```bash
+settld setup --non-interactive --host codex --base-url http://127.0.0.1:3000 --tenant-id tenant_default --settld-api-key sk_live_xxx.yyy --wallet-mode managed --wallet-bootstrap remote --profile-id engineering-spend --smoke
+```
+
+Then:
+
+1. `npm run mcp:probe -- --call settld.about '{}'`
+2. `npm run demo:mcp-paid-exa`
+3. verify first receipt with `settld x402 receipt verify`
+
+## Implementation path
+
+1. Run local stack and conformance
+2. Integrate agreement/evidence/settlement endpoints
+3. Add dispute flows with signer proof
+4. Add replay and closepack verification to ops
+5. Gate releases with conformance + verification artifacts
+
+## Who this is for
+
+- Capability providers who need enforceable paid calls
+- Agent builders who need deterministic, replayable outcomes
+- Marketplace/platform teams who need standard dispute/settlement semantics
+- Security/compliance teams who need portable audit artifacts
+
+## Kernel v0 scope
+
+Kernel v0 focuses on **paid capability calls** and their enforceable lifecycle:
+
+- signed agreement/evidence/decision/receipt artifacts
+- holdbacks and challenge windows
+- signer-bound dispute open envelopes
+- deterministic settlement adjustments
+- replay-evaluate checks
+- closepack export + offline verify
+- conformance pack assertions
+
+## Product boundaries
+
+Settld is the enforcement and verification layer.
+
+- Transport is external (HTTP, MCP gateway, queues, A2A, etc.)
+- Payment rails are adapters (card/ACH/crypto)
+- Kernel artifacts are the source of truth for why value moved

package/docs/gitbook/SETUP.md

@@ -0,0 +1,25 @@
+# GitBook Sync Setup
+
+Use this folder as your GitBook project directory.
+
+## Recommended
+
+- Repository: `aidenlippert/settld`
+- Project directory: `docs/gitbook`
+- Initial sync: import from GitHub
+
+## If your project directory is currently `docs`
+
+You can keep it. Root `docs/README.md` and `docs/SUMMARY.md` route to this curated set.
+
+## Domain
+
+- custom domain: `docs.settld.work`
+- DNS record: `CNAME docs -> 47701540b1-hosting.gitbook.io`
+
+## Update workflow
+
+1. edit docs in repo
+2. open PR
+3. merge to `main`
+4. GitBook sync updates docs site

package/docs/gitbook/SUMMARY.md

@@ -0,0 +1,15 @@
+# Summary
+
+- [Settld Docs](README.md)
+- [Quickstart](quickstart.md)
+- [Core Primitives](core-primitives.md)
+- [API Reference](api-reference.md)
+- [Conformance](conformance.md)
+- [Closepacks](closepacks.md)
+- [Guides](guides.md)
+- [Dispute Lifecycle](dispute-lifecycle.md)
+- [Replay and Audit](replay-and-audit.md)
+- [SDK Reference](sdk-reference.md)
+- [Operations Runbook](operations-runbook.md)
+- [Security Model](security-model.md)
+- [FAQ](faq.md)

package/docs/gitbook/api-reference.md

@@ -0,0 +1,73 @@
+# API Reference
+
+This page is the integration map. For endpoint-level schema details, use the generated OpenAPI reference.
+
+## OpenAPI source of truth
+
+- `openapi/settld.openapi.json`
+
+## Auth model
+
+Operator endpoints use scoped ops headers.
+
+Common headers:
+
+- `x-proxy-ops-token: <token>`
+- `x-proxy-tenant-id: <tenantId>` (when required)
+
+## Endpoint groups
+
+## Platform
+
+- `GET /healthz`
+
+## Kernel lifecycle
+
+Representative groups include:
+
+- agreement/hold/evidence/settlement operations
+- dispute open and verdict application
+- replay-evaluate endpoints
+- closepack export/verify endpoints
+
+## Billing and plans
+
+Representative endpoints:
+
+- `GET /ops/finance/billing/plan`
+- `POST /ops/finance/billing/providers/stripe/checkout`
+- `POST /ops/finance/billing/providers/stripe/portal`
+
+## Dashboard and API keys
+
+Representative endpoints:
+
+- `GET /api/dashboard/api-keys`
+- `POST /api/dashboard/api-keys`
+- `POST /api/dashboard/api-keys/:id/rotate`
+- `POST /api/dashboard/api-keys/:id/revoke`
+
+## Practical flow pattern
+
+1. Create agreement + hold context
+2. Submit evidence
+3. Trigger settlement
+4. Fetch resulting artifacts
+5. Replay-evaluate
+6. Export closepack for third-party verification
+
+## cURL example
+
+```bash
+curl -s "http://127.0.0.1:3000/ops/tool-calls/replay-evaluate?agreementHash=<agreementHash>" \
+  -H "x-proxy-ops-token: tok_ops"
+```
+
+## SDK alternatives
+
+- JavaScript SDK: `packages/api-sdk`
+- Python SDK: `packages/api-sdk-python`
+
+## Recommendation
+
+Expose generated OpenAPI pages in GitBook using the OpenAPI import feature and keep this page as architectural orientation.

package/docs/gitbook/closepacks.md

@@ -0,0 +1,55 @@
+# Closepacks (Offline Verification)
+
+A closepack is a portable verification bundle proving settlement lineage without relying on live server trust.
+
+## What you can prove with a closepack
+
+- artifact integrity and signatures
+- agreement/evidence/decision bindings
+- dispute lineage correctness
+- deterministic adjustment routing expectations
+- replay comparison consistency
+
+## Export
+
+```bash
+npx settld closepack export --agreement-hash <agreementHash> --out closepack.zip
+```
+
+Repo checkout:
+
+```bash
+./bin/settld.js closepack export --agreement-hash <agreementHash> --out closepack.zip
+```
+
+## Verify
+
+```bash
+npx settld closepack verify closepack.zip --json-out /tmp/closepack-verify.json
+```
+
+Repo checkout:
+
+```bash
+./bin/settld.js closepack verify closepack.zip --json-out /tmp/closepack-verify.json
+```
+
+## Operational policy recommendation
+
+For every production release candidate:
+
+1. Generate at least one representative closepack.
+2. Verify it offline.
+3. Store verify JSON with release artifacts.
+
+## Why this matters
+
+Closepacks shift trust from “believe the API response” to “independently verify the economic claim.”
+
+That is a core credibility boundary for settlement infrastructure.
+
+## Related references
+
+- `docs/spec/ClosePack.v1.md`
+- `docs/spec/ClosePackManifest.v1.md`
+- `docs/spec/INVARIANTS.md`

package/docs/gitbook/conformance.md

@@ -0,0 +1,59 @@
+# Conformance
+
+Conformance verifies behavioral correctness of Kernel v0, not just schema validity.
+
+## Why conformance exists
+
+Conformance catches high-impact regressions:
+
+- replay mismatches
+- dispute/holdback lifecycle drift
+- deterministic adjustment/idempotency violations
+- closepack verification failures
+
+## Run conformance
+
+Installed CLI:
+
+```bash
+npx settld conformance kernel --ops-token tok_ops --json-out /tmp/kernel-report.json
+```
+
+Repo checkout:
+
+```bash
+./bin/settld.js conformance kernel --ops-token tok_ops --json-out /tmp/kernel-report.json
+```
+
+## Minimum assertions expected
+
+- kernel artifact chain is complete
+- replay-evaluate matches stored outcomes
+- closepack export + offline verify succeeds
+- dispute flow blocks auto-release and routes held funds deterministically
+- idempotency constraints hold under retries
+
+## CI usage
+
+Store these as build artifacts:
+
+- conformance JSON report
+- closepack verify report
+- release artifact checksum list (for releases)
+
+## Run-twice idempotency check
+
+Run critical flows twice and confirm deterministic uniqueness surfaces hold (no duplicate deterministic effects).
+
+## Failure triage pattern
+
+1. Inspect failing assertion from report JSON.
+2. Map failure to primitive/invariant.
+3. Fix invariant behavior (not only response shape).
+4. Re-run until all assertions pass.
+
+## Related files
+
+- `conformance/kernel-v0/run.mjs`
+- `test/conformance-kernel-v0.test.js`
+- `docs/KERNEL_COMPATIBLE.md`

package/docs/gitbook/core-primitives.md

@@ -0,0 +1,85 @@
+# Core Primitives
+
+Settld security and settlement correctness come from signed, hash-bound artifacts with deterministic relationships.
+
+## Canonical transaction chain
+
+Kernel v0 paid capability flow (as implemented in this repo):
+
+1. `ToolManifest`
+2. `ToolCallAgreement`
+3. `FundingHold`
+4. `ToolCallEvidence`
+5. `SettlementDecisionRecord`
+6. `SettlementReceipt`
+7. Dispute branch (when needed):
+   - `DisputeOpenEnvelope`
+   - `ArbitrationCase`
+   - `ArbitrationVerdict`
+   - `SettlementAdjustment`
+
+Reality notes:
+
+- `AuthorityGrant` is **not shipped** in this repo (no code, no schema, no spec). Current authorization is enforced by API auth/scope and by policy gates (for example `AgentIdentity.walletPolicy`) depending on the workflow surface.
+- `ToolCallAgreement.v1` and `ToolCallEvidence.v1` are frozen protocol objects under `docs/spec/` (normative spec + JSON schemas + conformance vectors).
+
+## Primitive purpose
+
+### ToolManifest
+
+Capability identity, interface details, verifier hints. Prevents silent identity swaps.
+
+### ToolCallAgreement
+
+Commits parties to exact terms including call commitment (`callId`, `inputHash`) and settlement terms.
+
+### FundingHold
+
+Reserves funds before work execution, enabling reliable provider execution with escrow semantics.
+
+### ToolCallEvidence
+
+Signed evidence binding execution facts to the agreement commitment.
+
+### SettlementDecisionRecord
+
+Deterministic evaluation outcome, reason codes, policy linkage, replay-critical facts.
+
+### SettlementReceipt
+
+Finalized settlement artifact describing effective outcome and accounting effect.
+
+### Dispute artifacts
+
+- `DisputeOpenEnvelope` proves opener legitimacy for non-admin opens.
+- `ArbitrationCase` tracks active dispute subject.
+- `ArbitrationVerdict` resolves dispute.
+- `SettlementAdjustment` applies deterministic held-fund routing effect.
+
+## Critical invariants
+
+- One deterministic settlement result per agreement hash
+- Evidence must match agreement commitment (`callId`/`inputHash`)
+- Open arbitration case blocks holdback auto-release
+- Deterministic adjustment identity prevents double-apply
+- Replay checks compare recomputed vs stored decision path
+
+## Determinism in practice
+
+Determinism means:
+
+- canonicalized artifact hashing
+- explicit signer ownership
+- deterministic artifact IDs for idempotent side effects
+- reproducible replay/verification checks
+
+It does not mean all policy semantics are universal truth. It means outcomes are provably tied to declared policy and evidence.
+
+## Related references
+
+- `docs/spec/README.md`
+- `docs/spec/INVARIANTS.md`
+- `docs/spec/SettlementDecisionRecord.v2.md`
+- `docs/spec/DisputeOpenEnvelope.v1.md`
+- `docs/spec/ClosePack.v1.md`
+- `docs/KERNEL_V0.md`

package/docs/gitbook/dispute-lifecycle.md

@@ -0,0 +1,33 @@
+# Dispute Lifecycle
+
+Disputes are part of settlement finality, not an afterthought.
+
+## Lifecycle
+
+1. Receipt created with holdback terms.
+2. Counterparty opens dispute (non-admin opens require signed envelope).
+3. Arbitration case is created and marked open.
+4. Holdback auto-release is blocked while case is open.
+5. Arbiter issues verdict.
+6. Deterministic settlement adjustment routes held funds.
+
+## Invariant behavior
+
+- open case must block auto-release tick for referenced holdback
+- one deterministic adjustment effect per dispute resolution path
+- no extra clawbacks beyond held escrow in dispute adjustment path
+- idempotent retries must return existing deterministic outcomes
+
+## Error conditions
+
+Typical stable codes include:
+
+- `DISPUTE_WINDOW_EXPIRED`
+- `DISPUTE_ALREADY_OPEN`
+- `DISPUTE_INVALID_SIGNER`
+
+## Operational checks
+
+- monitor open-case age and stuck cases
+- alert on replay mismatches involving dispute artifacts
+- track adjustment conflicts as potential idempotency regressions

package/docs/gitbook/faq.md

@@ -0,0 +1,21 @@
+# FAQ
+
+## Is Settld a payment network?
+
+No. Settld is the enforcement and verification layer for economic outcomes. Payment rails are adapters.
+
+## Do we need crypto?
+
+No. Rail choice is independent from kernel enforcement semantics.
+
+## What does “offline-verifiable” mean?
+
+You can export closepacks and verify signatures/bindings/outcomes without querying Settld servers.
+
+## What is Kernel v0 focused on?
+
+Paid capability calls with holdbacks, disputes, deterministic adjustments, replay checks, and closepack verification.
+
+## Is this open?
+
+Protocol objects and conformance vectors are open; hosted operational/control-plane features are layered separately.

package/docs/gitbook/guides.md

@@ -0,0 +1,49 @@
+# Guides
+
+Use these guides to move from local proof-of-concept to production-grade operation.
+
+## Local proof flow
+
+- Start stack
+- Run conformance
+- Replay-evaluate a real agreement
+- Export and verify closepack
+
+See [Quickstart](./quickstart.md).
+
+## Build a paid capability
+
+- Generate capability template
+- Publish signed manifest
+- Emit evidence correctly
+- Set holdback/challenge-window settlement terms
+- Validate with conformance
+
+## Integrate with your existing backend
+
+- Choose SDK (JS/Python) or raw API
+- Map your lifecycle to agreement/evidence/decision stages
+- Persist artifact IDs for audit and replay
+- Add replay and closepack checks into operational workflows
+- For MCP host wiring (Claude/Cursor/Codex/OpenClaw), see `../QUICKSTART_MCP_HOSTS.md`
+
+## Operate disputes safely
+
+- Require signer-bound dispute envelope for non-admin opens
+- Enforce challenge window
+- Prevent multiple active dispute conflicts
+- Ensure verdict routes held funds via deterministic adjustment
+
+## Release process
+
+- run tests + conformance
+- produce release checksums/artifacts
+- include closepack verify evidence
+- document regression and replay findings
+
+## Deep-dive pages
+
+- [Dispute lifecycle](./dispute-lifecycle.md)
+- [Replay and audit](./replay-and-audit.md)
+- [SDK usage](./sdk-reference.md)
+- [Operations runbook](./operations-runbook.md)

package/docs/gitbook/operations-runbook.md

@@ -0,0 +1,36 @@
+# Operations Runbook
+
+Minimum operator posture for reliable kernel operation.
+
+## Daily checks
+
+- health endpoint response and DB latency
+- replay mismatch count
+- open dispute backlog
+- pending/failed maintenance jobs
+
+## Incident priorities
+
+P0:
+
+- replay mismatches on finalized settlements
+- deterministic adjustment duplication risk
+- settlement endpoint signing failures
+
+P1:
+
+- dispute queue lag beyond SLA
+- closepack verify regressions in release candidate
+
+## Recovery patterns
+
+- use deterministic IDs + idempotent handlers before manual intervention
+- re-run conformance after hotfixes
+- archive closepack + replay reports for each incident timeline
+
+## Release minimum
+
+- tests green
+- conformance green
+- closepack verify sample green
+- release artifacts/checksums generated