settld 0.1.1 → 0.1.5

package/docs/RELEASING.md

@@ -0,0 +1,81 @@
+# Releasing Settld
+
+This repo treats the **protocol** (docs + schemas + vectors + fixtures) as an API. Releases must be repeatable and reviewable.
+
+See `docs/spec/VERSIONING.md` for “what requires a bump”.
+
+## Release checklist
+
+See `docs/RELEASE_CHECKLIST.md` for the definitive artifact completeness requirements.
+
+1. Ensure `npm test` is green.
+2. Ensure fixture determinism gate passes (it’s part of `npm test`).
+3. Update `CHANGELOG.md`:
+   - Add a new version section (Keep a Changelog format).
+   - Call out any protocol-surface changes explicitly.
+4. Bump tool version(s) you ship:
+   - `packages/artifact-verify/package.json` `version`
+   - `packages/api-sdk-python/pyproject.toml` `project.version` (when shipping Python SDK changes)
+   - `SETTLD_VERSION` (repo/service version stamp)
+5. Run packaging smoke test:
+   - `node scripts/ci/npm-pack-smoke.mjs`
+   - `node scripts/ci/cli-pack-smoke.mjs`
+   - `python3 -m build packages/api-sdk-python --sdist --wheel --outdir /tmp/settld-python-dist-smoke`
+   - Optionally generate full release artifacts locally: `npm run release:artifacts`
+6. Create a tag and push it:
+   - Tag format: `vX.Y.Z`
+   - `git tag -a vX.Y.Z -m "vX.Y.Z"`
+   - `git push origin vX.Y.Z`
+
+On tag push, GitHub Actions builds and publishes release artifacts (Docker image, Helm chart, npm tarballs, Python wheel/sdist artifacts, SHA256SUMS).
+If `NPM_TOKEN` is configured in repo secrets, the release lane also publishes:
+
+- `settld` (CLI, so `npx settld ...` works directly),
+- `settld-api-sdk` (JS SDK used by starter templates),
+- `@settld/provider-kit` (provider middleware package),
+- `create-settld-paid-tool` (scaffold CLI package).
+  After publish, the workflow runs registry smoke checks and uploads `npm-postpublish-smoke-<version>` artifacts with command outputs + JSON summary evidence.
+The `release_gate` job also runs a staging billing smoke (`dev:billing:smoke:prod`) and uploads `billing-smoke-prod.log` + `billing-smoke-status.json` as gate artifacts.
+
+Python package publishing uses PyPI Trusted Publishing (OIDC) via either:
+
+- the `python_publish` job in `.github/workflows/release.yml` (full release lane), or
+- `.github/workflows/python-pypi.yml` (Python-only publish lane).
+
+Before the first publish, configure a PyPI trusted publisher for this repo/workflow and allow the `pypi` GitHub environment.
+
+## TestPyPI dry-run lane
+
+Use `.github/workflows/python-testpypi.yml` as a manual pre-production lane:
+
+1. Ensure `packages/api-sdk-python/pyproject.toml` `project.version` matches the version you plan to publish.
+2. Run the `python-testpypi` workflow via `workflow_dispatch` and pass `version`.
+3. The workflow builds wheel+sdist, asserts versioned filenames, and publishes to TestPyPI using OIDC (`testpypi` environment).
+4. Validate installability from TestPyPI before running a production tag release.
+
+## Python-only PyPI lane
+
+Use `.github/workflows/python-pypi.yml` when you want to publish just the Python SDK to PyPI without waiting for other release jobs (Docker/Helm/conformance/audit).
+
+1. Set `packages/api-sdk-python/pyproject.toml` `project.version` to the target version.
+2. Ensure PyPI trusted publishing is configured for workflow `python-pypi.yml` and environment `pypi`.
+3. Run the `python-pypi` workflow via `workflow_dispatch`.
+4. Confirm wheel/sdist publish completed on PyPI and smoke-install in a clean venv.
+
+## Release authenticity
+
+Releases also publish a signed `ReleaseIndex.v1` (`release_index_v1.json` + `release_index_v1.sig`) to make artifact authenticity verifiable.
+
+See `docs/spec/ReleaseIndex.v1.md` and `docs/spec/SUPPLY_CHAIN.md`.
+
+The release workflow expects a repo secret named `SETTLD_RELEASE_SIGNING_PRIVATE_KEY_PEM` containing an Ed25519 private key PEM used only for signing release indexes.
+
+The corresponding public key (and quorum policy, if used) is pinned in `trust/release-trust.json` and should be treated as a security-sensitive change (PR + review).
+
+## Protocol vectors / fixtures rotation
+
+If a change *intentionally* changes protocol meaning (schemas/spec semantics/strictness/canonicalization/hashing), do not “let it drift”:
+
+- Update specs and schemas together.
+- Rotate vectors and/or add fixtures deliberately.
+- Add a clear “Protocol change” entry to `CHANGELOG.md`.

package/docs/REPO_SETTINGS.md

@@ -0,0 +1,37 @@
+# Repo Settings (Recommended)
+
+These are GitHub-side settings we expect for a fail-closed kernel repo.
+
+## Branch Protection (main)
+
+- Require a pull request before merging.
+- Require status checks to pass before merging:
+  - `tests / pr_issue_link_guard`
+  - `tests / changelog_guard`
+  - `tests / unit_tests`
+  - `tests / openapi_drift`
+  - `tests / npm_pack_smoke (ubuntu-latest)`
+  - `tests / npm_pack_smoke (macos-latest)`
+  - `tests / npm_pack_smoke (windows-latest)`
+  - `tests / cli_cross_platform (ubuntu-latest)`
+  - `tests / cli_cross_platform (macos-latest)`
+  - `tests / cli_cross_platform (windows-latest)`
+  - `tests / python_verifier_conformance`
+  - `tests / github_action_settld_verify (jobproof)`
+  - `tests / github_action_settld_verify (monthproof)`
+  - `tests / github_action_settld_verify (financepack)`
+- Dismiss stale PR approvals when new commits are pushed.
+- Require linear history.
+- Block force pushes and deletions.
+- Require conversation resolution.
+
+Optional:
+
+- Require signed commits.
+- Require CODEOWNERS review (if/when CODEOWNERS exists).
+
+## Actions
+
+- Keep secrets scoped to environments (staging/prod).
+- Require manual approval for production deployments (if/when added).
+

package/docs/RUNBOOK.md

@@ -0,0 +1,86 @@
+# Settld Operations Runbook
+
+## Quick reference
+
+| Symptom | Likely cause | Action |
+|---|---|---|
+| `outbox_pending_gauge` growing | downstream down or worker stuck | check `/ops/status`, check delivery logs, restart worker |
+| `delivery_dlq_pending_total_gauge` > 0 | repeated delivery failures | inspect DLQ; fix destination; requeue (audited) |
+| `ingest_rejected_total` spike | integration bug or hostile input | check `/ops/status` top reject codes; identify client from logs |
+| stripe billing rejects/replayable dead-letter rising | dropped/invalid webhook windows or apply failures | follow `docs/ops/BILLING_WEBHOOK_REPLAY.md` |
+| go-live gate blocked | one or more S13 checks failed | run `node scripts/ci/run-go-live-gate.mjs` + `node scripts/ci/build-launch-cutover-packet.mjs`, inspect `artifacts/gates/s13-go-live-gate.json` + `artifacts/gates/s13-launch-cutover-packet.json` |
+| `/healthz` dbOk=false | Postgres down/unreachable | fix DB connectivity; do not restart-loop workers |
+| `ARTIFACT_HASH_MISMATCH` | non-determinism or duplicate IDs | **stop ingestion**, preserve state, investigate |
+
+## Standard endpoints
+
+- `GET /health` liveness
+- `GET /healthz` health with signals
+- `GET /metrics` metrics
+- `GET /ops/status` backlog + DLQ + top reject codes
+
+## Common scenarios
+
+### Outbox backlog growing
+
+1. `GET /ops/status` (confirm which backlog is growing).
+2. Check logs for `outbox.claim`, `ledger.apply.*`, `delivery.*`.
+3. If deliveries: verify destination health/auth; allow retries or move to DLQ.
+4. If ledger apply: investigate DB errors; do **not** manually mutate ledger tables.
+
+### Delivery DLQ non-zero
+
+1. Inspect failure reason codes in DB/ops tooling (destination down, non-2xx, auth, timeout).
+2. Fix destination.
+3. Requeue (audited) and watch `delivery_dlq_pending_total_gauge` return to 0.
+
+### Ingest rejects spike
+
+1. `GET /ops/status` → identify top reject reason codes.
+2. Correlate to request logs by `requestId` and tenant.
+3. If attack suspected: enable/raise rate limiting; rotate/revoke keys as needed.
+
+### Stripe billing dead-letter/replay spike
+
+1. Run `docs/ops/BILLING_WEBHOOK_REPLAY.md` command sequence.
+2. Dry-run replay first, then run live replay if dry-run is clean.
+3. Confirm post-replay `reconcile/report` counters move as expected and incident log is updated.
+
+### Settlement / artifact drift (critical)
+
+Stop. This is a “system-of-record” incident.
+
+Immediate actions:
+1. Stop accepting new writes (ingest + event appends).
+2. Preserve DB snapshot and logs.
+3. Identify the job/artifact with drift.
+4. Compare event stream bytes + pinned hashes; look for nondeterminism (timestamps, randomness, floats).
+
+Do not resume ingestion until:
+- root cause is fixed, and
+- a regression test is added, and
+- a replay produces identical hashes.
+
+### Throughput launch drill (T177)
+
+1. Run `node scripts/ci/run-10x-throughput-drill.mjs` with production-like env.
+2. Confirm `artifacts/throughput/10x-drill-summary.json` shows `verdict.ok=true`.
+3. Run `node scripts/ci/run-10x-throughput-incident-rehearsal.mjs`.
+4. Confirm `artifacts/throughput/10x-incident-rehearsal-summary.json` shows `verdict.ok=true`.
+5. If failed:
+- inspect `http_req_duration p95`, `http_req_failed rate`, and ingest reject rate.
+- keep release gate blocked until thresholds pass.
+
+### Go-live gate (T182)
+
+1. Run `node scripts/ci/run-go-live-gate.mjs`.
+2. Run `node scripts/ci/build-launch-cutover-packet.mjs`.
+3. Inspect `artifacts/gates/s13-go-live-gate.json` and `artifacts/gates/s13-launch-cutover-packet.json`.
+4. Gate requires:
+- deterministic critical suites pass,
+- 10x throughput drill pass,
+- lighthouse tracker indicates >=3 paid production settlements.
+
+## DR: backup/restore drill
+
+Use `scripts/backup-restore-test.sh` (PG mode) to prove restore correctness.

package/docs/SKILLS.md

@@ -0,0 +1,42 @@
+# Skills & Royalties (v0.3)
+
+Skills are licensed to a job as explicit events. Royalties are deterministic and flow into the settlement ledger.
+
+## Principles
+
+- **Licensing is explicit**: paid capabilities must be licensed (`SKILL_LICENSED`) before use.
+- **Usage is auditable**: the executor can emit `SKILL_USED` events during execution.
+- **Settlement is deterministic**: developer royalties payable equals the sum of licensed skill fees.
+
+## Events
+
+### `SKILL_LICENSED` (server-signed)
+
+Licenses a skill version to a job.
+
+```json
+{
+  "jobId": "job_123",
+  "skill": { "skillId": "skill_reset_lite", "version": "1.2.0", "developerId": "dev_abc" },
+  "pricing": { "model": "PER_JOB", "amountCents": 399, "currency": "USD" },
+  "licenseId": "lic_789",
+  "terms": { "refundableUntilState": "EXECUTING", "requiresCertificationTier": "CERTIFIED" }
+}
+```
+
+### `SKILL_USED` (robot- or operator-signed)
+
+Proves the skill actually ran (v0.3 uses the `licenseId` as the linkage):
+
+```json
+{ "jobId": "job_123", "licenseId": "lic_789", "step": "wipe_surfaces" }
+```
+
+## Enforced invariants (v0.3)
+
+- `SKILL_LICENSED` is rejected after execution starts.
+- `SKILL_USED` is rejected unless a matching `SKILL_LICENSED` exists in the job stream.
+- At `SETTLED` (job completed):
+  - Developer royalties payable equals the sum of `SKILL_LICENSED.pricing.amountCents`.
+  - The journal entry must balance to zero.
+

package/docs/SKILL_BUNDLE_FORMAT.md

@@ -0,0 +1,48 @@
+# Skill Bundle Format (v0)
+
+Settld skills are **signed bundles** with deterministic policies and testable constraints.
+
+## Goals
+
+- Portability: skill runs against a stable Capability API, not robot-specific SDKs.
+- Certifiability: static checks + simulation + hardware-in-loop tests.
+- Safety: constraints are explicit and enforced (agent clamps unsafe actions).
+- Auditability: versioned, signed, and reproducible.
+
+## Bundle layout (proposed)
+
+```
+skill/
+  skill.json
+  policy/
+    graph.json
+  tests/
+    cases.json
+  assets/
+    ... optional (small models, prompts, classifiers)
+  signatures/
+    bundle.sig
+```
+
+### `skill.json` (metadata)
+
+- `id`, `name`, `version`
+- `developerId`
+- `requiredCapabilities`
+- `safetyConstraints` (speed/force envelopes, contact rules, allowed zones)
+- `privacyProfile` (sensor usage, retention expectations)
+- `certificationTier` (e.g., `dev`, `lab_cert`, `field_cert`)
+
+### `policy/graph.json`
+
+Deterministic policy representation (behavior tree or state machine) that calls Capability API primitives.
+
+### `tests/cases.json`
+
+- simulation cases and expected outcomes
+- regression triggers (known failure modes)
+
+### Signatures
+
+- Signed by Settld certification key (tier-dependent).
+- Agent verifies signature before installation/execution.

package/docs/SLO.md

@@ -0,0 +1,70 @@
+# Service Level Objectives (SLO) — v1
+
+This document defines a minimal, explicit set of SLOs for Settld as a finance-grade system-of-record service.
+
+These SLOs are enforced in CI (kind smoke) via a post-run `/metrics` snapshot check (`scripts/slo/check.mjs`).
+
+## SLO-1: API availability (no 5xx during smoke)
+
+**Objective**
+
+- During the Kubernetes smoke lifecycle, the Settld API must not emit HTTP 5xx responses.
+
+**Metric**
+
+- `http_requests_total{status="5xx"}` derived from `http_requests_total{status="<code>"}`
+
+**Threshold**
+
+- `sum(http_requests_total{status=~"5.."}) == 0` for the duration of the smoke run.
+
+**Why**
+
+Any 5xx indicates server-side failure (misconfig, migration issues, DB issues, regressions).
+
+## SLO-2: Delivery rails health (no DLQ / no stuck backlog at end-of-run)
+
+**Objective**
+
+- At the end of the smoke run, there is no delivery DLQ backlog and no stuck delivery backlog.
+
+**Metrics**
+
+- `delivery_dlq_pending_total_gauge`
+- `deliveries_pending_gauge{state="pending"}`
+- `deliveries_pending_gauge{state="failed"}`
+
+**Thresholds**
+
+- `delivery_dlq_pending_total_gauge == 0`
+- `deliveries_pending_gauge{state="pending"} == 0`
+- `deliveries_pending_gauge{state="failed"} == 0`
+
+**Why**
+
+DLQ backlog is an on-call page. Pending backlog at end-of-run implies workers are stuck or PG is unhealthy.
+
+## SLO-3: Outbox boundedness (no runaway backlog at end-of-run)
+
+**Objective**
+
+- At the end of the smoke run, total outbox pending work is below a safe bound.
+
+**Metric**
+
+- `outbox_pending_gauge{kind=...}`
+
+**Threshold**
+
+- `sum(outbox_pending_gauge) <= 200` (CI default; configurable)
+
+**Why**
+
+If the outbox is growing without being drained, the system is not steady-state safe.
+
+## CI enforcement
+
+- Script: `scripts/slo/check.mjs`
+- Source of truth: `/metrics` snapshot taken after the smoke lifecycle completes.
+- Thresholds are configurable via env (see script header).
+

package/docs/SUMMARY.md

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

package/docs/SUPPORT.md

@@ -0,0 +1,31 @@
+# Support / filing a good bug
+
+Settld verification is designed to be diagnosable from **structured, stable outputs**.
+
+## Attach these artifacts
+
+1. `settld-verify --about --format json`
+2. `settld-verify --format json ...` output (`VerifyCliOutput.v1`)
+3. Trust anchor method (env vars or trust file path) and intended root `keyId`s (public keys OK; **no private keys**)
+4. Installation mode (npm version pinned, npm tarball, or from source)
+5. OS + Node version
+
+## Helpful flags
+
+- `--explain` — prints deterministic diagnostics to stderr without changing JSON stdout.
+- `--fail-on-warnings` — converts warnings into a failure (CI gating posture).
+
+## Where to look first
+
+- Error codes and remediation: `docs/spec/ERRORS.md`
+- Warning codes and remediation: `docs/spec/WARNINGS.md`
+- Trust anchor posture: `docs/spec/TRUST_ANCHORS.md`
+- Strict/non-strict semantics: `docs/spec/STRICTNESS.md`
+
+## Quickstart failures (Docker / local dev)
+
+If you're stuck getting the quickstart running:
+
+1. Run `./scripts/collect-debug.sh`
+2. Attach the resulting `settld-debug-*.tar.gz` to a GitHub issue using the \"Quickstart failure\" template:
+   - https://github.com/aidenlippert/settld/issues/new?template=quickstart-failure.yml

package/docs/THREAT_MODEL.md

@@ -0,0 +1,36 @@
+# Threat Model (v0)
+
+## Assets to protect
+
+- Physical safety of people/property.
+- Requester privacy (sensor data, recordings).
+- Financial correctness (ledger, payouts, refunds).
+- Integrity of black box logs (events/evidence).
+- Integrity of skill artifacts (bundles, versions).
+- Device identity (robot/agent keys).
+
+## Primary attackers
+
+- Compromised robot/agent device.
+- Malicious skill developer (or supply-chain compromise).
+- Insider misuse (operator overreach).
+- Requester/owner fraud (false claims, tampered evidence).
+- Network attacker (MITM, replay).
+
+## Controls (MVP principles)
+
+- Device identity: per-agent keypair; rotate credentials; restrict API tokens.
+- Transport security: mTLS for agent; scoped auth for consoles and apps.
+- Artifact integrity: signed skill bundles; allow-list certified tiers.
+- Log integrity: hash-chained event logs; signatures from agent keys.
+- Least privilege: capability-limited skills; scoped operator actions.
+- Revocation: access plans and device certs can be revoked immediately.
+- Audit: immutable operator action log and evidence bundle timeline.
+
+## Abuse scenarios to design for
+
+- Operator issues unsafe command → agent clamps; event logged.
+- Skill tries to activate camera in privacy-off zone → denied; event logged.
+- Attempt to delete/reorder events → chain verification fails.
+- Chargeback/refund disputes → ledger + evidence bundle support resolution.
+

package/docs/TRUST.md

@@ -0,0 +1,59 @@
+# Trust (v0.4)
+
+Settld’s trust layer is a “privacy-respecting black box”: an append-only, tamper-evident event log with signer policy, plus minimal evidence references and a deterministic claims workflow.
+
+## Core guarantees
+
+- **Validated causality at append-time**: the server rejects events that break the chain, violate schema, violate signer policy, or violate core job/claims gates.
+- **Tamper-evidence**: each event commits to its canonical payload (`payloadHash`) and to the previous link (`chainHash`), so deletion/reordering is detectable.
+- **Proof of actor**: sensitive event families require signatures (robot/operator/server) based on event type.
+- **Minimal recording**: raw media is never embedded in the event log; evidence is stored out-of-band and only referenced.
+- **Deterministic economics**: claims adjustments and payouts produce double-entry ledger postings that always balance.
+
+## Incident events
+
+Incidents create the “what went wrong” anchor for evidence and claims.
+
+- `INCIDENT_DETECTED` (robot-signed): anomaly detected during execution.
+- `INCIDENT_REPORTED` (server- or operator-signed): customer report or operator report.
+
+Incidents are keyed by `incidentId` and include a strict taxonomy type and integer severity `1..5`.
+
+## Evidence events
+
+Evidence is out-of-band and reference-only:
+
+- `EVIDENCE_CAPTURED` (robot- or server-signed)
+
+`EVIDENCE_CAPTURED` payloads include:
+
+- `evidenceRef`: object-storage style URI (e.g. `obj://...`) — never raw bytes.
+- metadata: `kind`, `durationSeconds`, `contentType`, `redaction`.
+
+Evidence must reference an existing `incidentId` (append-time enforced).
+
+## Claims workflow
+
+Claims are modeled as a strict event-driven workflow:
+
+- `CLAIM_OPENED` (server-signed)
+- `CLAIM_TRIAGED` (server- or operator-signed)
+- `CLAIM_APPROVED` / `CLAIM_DENIED` (server-signed)
+- `JOB_ADJUSTED` (server-signed) — ties approval to deterministic ledger adjustments
+- `CLAIM_PAID` (server-signed) — references the external payment and posts ledger entries
+
+Append-time gates enforce that claims:
+
+- reference an existing incident,
+- can’t be approved/denied twice,
+- can’t be paid before adjustment,
+- can’t be approved for “no-execution” jobs except explicit access failures.
+
+## Ledger linkage (high level)
+
+- `JOB_ADJUSTED` creates `acct_claims_payable` for the approved total (payout + refund) and offsets it via:
+  - `acct_claims_expense` for payouts, and/or
+  - proportional reversals of job settlement allocations for refunds.
+- `CLAIM_PAID` reduces `acct_claims_payable` and credits `acct_cash`.
+
+See `docs/LEDGER.md` for the exact posting rules.

package/docs/WORKFLOW.md

@@ -0,0 +1,35 @@
+# Workflow (Single Source Of Truth)
+
+Planning and execution are intentionally simple:
+
+1. **GitHub Issues** are the only live backlog (single source of truth).
+2. **PRs** are the unit of shipping. Every PR must link an Issue.
+3. **CI** is fail-closed for kernel invariants (protocol, verification, settlement, determinism).
+
+## Planning
+
+- Create an Issue using an issue form (feature/bug/ops/ci).
+- Assign labels:
+  - one `prio:*`
+  - one `stream:*`
+  - one `type:*`
+- Put the Issue in the current Milestone (e.g. `S20`).
+
+## Shipping
+
+- Branch naming: `issue/<number>-<slug>` (e.g. `issue/123-mcp-tool-manifests`)
+- PR title: include the Issue number (e.g. `#123 ...`)
+- PR description: include `Closes #123` so merge closes the Issue.
+
+## Definition Of Done (DoD)
+
+- Tests added/updated for behavioral changes.
+- Protocol changes include docs + schema + vectors/fixtures (lockstep).
+- Ops-impacting changes include runbook updates.
+- CI green on all required checks.
+
+## In-Repo Planning Files
+
+- `planning/STATUS.md` is only a pointer to GitHub Issues.
+- Implementation trackers under `planning/sprints/` are evidence records (what shipped), not a live backlog.
+

package/docs/X402_BATCH_SETTLEMENT.md

@@ -0,0 +1,126 @@
+# X402 Batch Settlement Worker
+
+This worker creates deterministic provider payout batches from paid MCP/x402 demo artifacts and can optionally submit those batches to Circle rails.
+
+## Purpose
+
+- Aggregate released x402 gates by provider and currency.
+- Emit deterministic payout manifests and per-provider batch files.
+- Persist idempotency state so reruns do not double-settle the same gate.
+- Optionally execute payouts (`--execute-circle`) with retry-safe batch state.
+
+By default it remains artifact-driven (manifest-only) and does not call external payout rails.
+
+## Inputs
+
+1. Artifact root with run directories (default `artifacts/mcp-paid-exa`).
+2. Provider payout registry (`X402ProviderPayoutRegistry.v1`).
+3. Worker state file (`X402BatchWorkerState.v1`).
+
+Registry example: `docs/examples/x402-provider-payout-registry.example.json`
+
+## Run
+
+```bash
+npm run settlement:x402:batch -- \
+  --artifact-root artifacts/mcp-paid-exa \
+  --registry docs/examples/x402-provider-payout-registry.example.json
+```
+
+Dry run (no state mutation):
+
+```bash
+npm run settlement:x402:batch -- \
+  --artifact-root artifacts/mcp-paid-exa \
+  --registry docs/examples/x402-provider-payout-registry.example.json \
+  --dry-run
+```
+
+Execute payouts in stub mode (safe local flow):
+
+```bash
+npm run settlement:x402:batch -- \
+  --artifact-root artifacts/mcp-paid-exa \
+  --registry docs/examples/x402-provider-payout-registry.example.json \
+  --execute-circle \
+  --circle-mode stub
+```
+
+Execute payouts in Circle sandbox mode:
+
+```bash
+npm run settlement:x402:batch -- \
+  --artifact-root artifacts/mcp-paid-exa \
+  --registry docs/examples/x402-provider-payout-registry.example.json \
+  --execute-circle \
+  --circle-mode sandbox
+```
+
+## Outputs
+
+Each run writes:
+
+- `payout-manifest.json`
+- `payout-manifest.meta.json` (`manifestHash` + optional signature)
+- `payout-reconciliation.json` (batch totals recomputation + gate/receipt linkage + drift check)
+- `batches/<batchId>.json` for each provider batch
+
+Default output root:
+
+`artifacts/settlement/x402-batches/<timestamp>/`
+
+## Idempotency
+
+State file tracks processed gates by `gateId` and persisted batch payout status:
+
+- first run: eligible released gates are batched and recorded
+- subsequent runs: previously processed gates are skipped for new batch creation
+- when `--execute-circle` is enabled:
+  - `submitted` batches are not re-submitted
+  - `failed` batches are retried until `maxAttempts` is reached
+
+`--dry-run` always skips payout execution even when `--execute-circle` is provided.
+
+State path default:
+
+`artifacts/settlement/x402-batch-state.json`
+
+## Circle execution env
+
+Required when `--execute-circle --circle-mode sandbox|production`:
+
+- `CIRCLE_API_KEY`
+- `CIRCLE_WALLET_ID_SPEND`
+- `CIRCLE_TOKEN_ID_USDC`
+- `ENTITY_SECRET` (or `CIRCLE_ENTITY_SECRET_HEX`) preferred
+- `CIRCLE_ENTITY_SECRET_CIPHERTEXT_TEMPLATE`
+  - or `CIRCLE_ENTITY_SECRET_CIPHERTEXT` with `CIRCLE_ALLOW_STATIC_ENTITY_SECRET=1`
+
+Optional:
+
+- `CIRCLE_BASE_URL`
+- `CIRCLE_BLOCKCHAIN`
+- `CIRCLE_FEE_LEVEL` (default `MEDIUM`)
+- `CIRCLE_TIMEOUT_MS`
+
+## Demo integration
+
+`scripts/demo/mcp-paid-exa.mjs` can run this worker automatically after a successful paid-tool call:
+
+- `SETTLD_DEMO_RUN_BATCH_SETTLEMENT=1`
+- `SETTLD_DEMO_BATCH_PROVIDER_WALLET_ID=<walletId>` (required for sandbox/production if `CIRCLE_WALLET_ID_ESCROW` is not set)
+
+The demo writes:
+
+- `batch-payout-registry.json`
+- `batch-worker-state.json`
+- `batch-settlement.json`
+
+## Optional manifest signing
+
+Set both env vars:
+
+- `SETTLD_BATCH_SIGNER_PUBLIC_KEY_PEM`
+- `SETTLD_BATCH_SIGNER_PRIVATE_KEY_PEM`
+
+If present, the worker adds an Ed25519 signature to `payout-manifest.meta.json`.