settld 0.1.2 → 0.2.0

package/docs/marketing/hn-repost-2026-02-17.md

@@ -0,0 +1,102 @@
+# HN Repost Draft (Tue 2026-02-17)
+
+Note on compositional settlement: keep the claim narrow. Settld can bind a settlement to an agreement delegation graph and run deterministic pre-release checks (e.g. block cycles) with stable error codes (e.g. `AGREEMENT_DELEGATION_CYCLE`). Avoid implying multi-hop settlement is \"automatic\" beyond what the current API actually enforces.
+
+## Locked Timing (ET / PT)
+
+- Copy freeze: Mon 2026-02-16 21:00 ET / 18:00 PT
+- Repost submission (target): Tue 2026-02-17 08:15 ET / 05:15 PT
+- Live monitoring: Tue 08:15–11:30 ET (respond fast while ranking is most sensitive)
+- Second sweep: Tue 18:30 ET / 15:30 PT
+
+## Submission Details
+
+- Type: Show HN (repost)
+- Link target (pick one):
+  - GitHub repo (recommended for OSS + technical audience): `README.md`
+  - Blog wedge post (more narrative): `docs/blog/2026-02-14-your-ai-agent-just-spent-500-where-is-the-receipt.md`
+  - Magic Link hosted demo (if we want buyer POV): TODO (add URL)
+- Original HN thread (if applicable): TODO (add URL)
+
+## Title Options (Pick 1)
+
+1. Show HN (Repost): Settld – verifiable receipts for agent spend (OSS)
+2. Show HN (Repost): Settld – verify-before-release receipts for x402-style APIs
+3. Show HN (Repost): Settld – deterministic settlement receipts for AI agents
+
+## OP Comment (Recommended, Short)
+
+Hi HN,
+
+Reposting with a tighter “try it in 10 minutes” wedge and more spec/conformance polish.
+
+Settld is an open source artifact protocol + verifier for turning agent work (and its evidence) into something closer to an invoice receipt: hash-bound, signed, and offline-verifiable by someone who doesn’t trust the producer.
+
+The quickest way to feel it is the in-repo x402 gateway demo: if an upstream returns `HTTP 402 Payment Required`, the proxy turns it into `hold -> verify -> release/refund` and emits a deterministic “receipt-like” trail (`x-settld-*` headers + an API query surface).
+
+TL;DR quickstart: `npm ci && npm run quickstart:x402` (prints `OK` + `gateId=...`). Full steps: `docs/QUICKSTART_X402_GATEWAY.md`
+
+Two important constraints up front:
+
+- This is not a payment processor. The local demo uses `X402_AUTOFUND=1` to simulate funding so escrow holds can be created without wiring a real rail.
+- The core contract is the verifiable receipt + deterministic outputs (stable warning/error codes), not “trust us, the dashboard says it passed.”
+
+Feedback I’d love:
+
+- If you’re shipping agents that spend money, what evidence would you require to automate payout/release?
+- Where would this break in your stack: tool calls, metering, dispute windows, refunds/chargebacks, or trust bootstrapping?
+
+## OP Comment (Longer, If Needed)
+
+Hi HN,
+
+Reposting: Settld is my attempt at a missing layer for agent workflows that spend money.
+
+Most stacks can prove “payment happened,” but can’t produce a portable receipt for “the work happened under the agreed terms” without shipping their entire log database to the counterparty.
+
+Settld (as shipped in this repo) is two things sharing the same “truth engine”:
+
+- An open artifact protocol (bundles + manifests + attestations + receipts) that can be verified offline with explicit trust anchors.
+- A hosted controller (“Magic Link”) that runs the same verifier server-side for buyer-friendly approvals and exports (optional; the hosted UI shouldn’t be the only judge).
+
+The smallest demo wedge is the x402 gateway: put a thin proxy in front of an x402-style API. When the upstream returns `HTTP 402`, the proxy routes it through a deterministic settlement step (`hold -> verify -> release/refund`) and returns a receipt-like trail you can store for audit. Quickstart: `docs/QUICKSTART_X402_GATEWAY.md`
+
+Notes / boundaries:
+
+- Local mode simulates funding (`X402_AUTOFUND=1`) to make the flow runnable without a real payment rail.
+- The interesting part (to me) is that verification outputs are deterministic and machine-readable with stable codes, and can be reproduced offline from the bundle.
+
+Would love critique on whether this is the right abstraction boundary (protocol + verifier + optional controller), and what primitives are missing to make this usable in real agent payment flows.
+
+## Defensible Claims (OK To Say)
+
+- Offline-verifiable bundles/receipts: artifacts commit to evidence by hashes; attestations/receipts are signature-checked; verification is reproducible without trusting the producer (`docs/OVERVIEW.md`, `docs/spec/`).
+- Deterministic verification outputs with stable codes (warnings/errors), suitable for CI gating and audit retention (`docs/OVERVIEW.md`, `docs/QUICKSTART_VERIFY.md`, `docs/spec/WARNINGS.md`, `docs/spec/ERRORS.md`).
+- x402 “verify-before-release” wedge exists in repo and is runnable locally in ~10 minutes (`docs/QUICKSTART_X402_GATEWAY.md`).
+- Escrow/ledger semantics are double-entry and tested as deterministic invariants (position as “ledger model + invariants,” not “we move real money”) (`docs/LEDGER.md`, `docs/spec/ESCROW_NETTING_INVARIANTS.md`).
+- Hosted Verify Cloud is optional; protocol/verifier are the trust core (don’t claim “must use the cloud”) (`docs/OVERVIEW.md`).
+
+## Claims To Avoid or Qualify
+
+- “We solve payments” or “we are escrow.” Safer: “we model escrow holds and deterministic release/refund decisions; wiring real rails is a separate integration.”
+- “CFO/audit-ready” as a blanket statement. Safer: “designed for audit evidence retention; produces deterministic, verifiable receipts.”
+- Any “multi-hop/cascade settlement is fully implemented” wording unless we choose a tight, defensible phrasing (see TODO and options below).
+
+## Likely HN Questions (Short Answers)
+
+- “Why not just use Stripe Connect?”
+  - Stripe moves money. Settld is about proving/verifying off-chain work and producing a portable, deterministic receipt that can drive a release/refund decision.
+- “Why not do this as a smart contract?”
+  - Smart contracts enforce on-chain state; the hard part here is verifying off-chain evidence/work completion and making that verification reproducible offline.
+- “Is this centralized trust?”
+  - The hosted UI is intentionally not the only judge; verification should be reproducible offline with explicit trust anchors.
+- “Does the demo move real money?”
+  - No; it simulates funding to make the end-to-end loop runnable locally (`X402_AUTOFUND=1`).
+
+## Cascade Settlement (Decision Needed Before Mon 2026-02-16)
+
+If we include anything about cascade/multi-hop settlement, pick ONE of these and stick to it:
+
+- Option A (spec-level, safest): “We added an `AgreementDelegation.v1` primitive for linking parent/child agreements in multi-hop agent chains (provenance, depth limits, and budget-capping).”
+- Option B (lightly aspirational): “We’re building toward multi-hop agent chains with compositional budget-capping and deterministic settlement; the delegation primitive is in the repo.”
+- Option C (omit): Don’t mention cascade settlement at all; keep the post focused on the verifiable receipt + verify-before-release wedge.

package/docs/marketing/show-hn-post.md

@@ -0,0 +1,45 @@
+# Show HN Draft
+
+## Title (pick one)
+
+1. Show HN (Repost): Settld – verify-before-release gateway for HTTP 402 (x402) APIs (OSS)
+2. Show HN (Repost): Settld – verifiable settlement receipts for agent spend (OSS)
+3. Show HN (Repost): Settld – deterministic release/refund decisions + receipt trail for x402
+
+---
+
+## Post Body
+
+Hi HN,
+
+Settld is an open source artifact protocol + verifier for producing hash-bound “settlement receipts”: deterministic records that tie *terms + evidence refs + a release/refund decision* together so a counterparty can verify what happened without trusting your database.
+
+Fastest way to try it is the in-repo x402 gateway demo (about 10 minutes):
+
+```bash
+npm ci && npm run quickstart:x402
+```
+
+It runs a local Settld API, a mock upstream that returns `HTTP 402 Payment Required` + `x-payment-required`, and a thin gateway. First request returns `402` plus `x-settld-gate-id`. Retry with that gate id and `x-payment: paid`, and the gateway calls Settld to:
+
+`hold -> verify -> release/refund (+ optional holdback)` and returns a receipt-like trail via `x-settld-*` headers (and a `GET /x402/gate/:id` inspection endpoint).
+
+Full quickstart (Docker + Linux notes): `docs/QUICKSTART_X402_GATEWAY.md`
+
+Two boundaries up front:
+
+- This is not a payment processor. The demo uses `X402_AUTOFUND=1` to simulate funding in an internal ledger so escrow-style holds can be created.
+- Multi-hop “agents hiring agents” is not automatic today. The repo includes an `AgreementDelegation.v1` primitive + deterministic cycle checks when a gate is bound to an agreement graph; full compositional settlement is still in progress.
+
+Feedback I’d love:
+
+1. If you’re shipping agent workflows that spend money today, what evidence would you require to automate release/refund?
+2. Where would this break first in your stack: metering, dispute windows, refunds/chargebacks, or trust anchors?
+
+---
+
+## Submission Notes (not part of the post)
+
+- Post Tue-Thu mornings ET if you want feedback quickly.
+- If someone says “just use Stripe Connect”: Stripe moves money; Settld decides how much should move based on verifiable evidence, deterministically.
+- If someone says “just use a smart contract”: smart contracts can enforce on-chain state; Settld is about verifying off-chain work completion and producing portable, deterministic receipts.

package/docs/ops/ARTIFACT_VERIFICATION_STATUS.md

@@ -0,0 +1,43 @@
+# Artifact Verification Status API
+
+This endpoint provides a normalized verification signal for an artifact:
+
+- `green`: verification passed
+- `amber`: insufficient evidence or unknown proof state
+- `red`: verification failed
+
+## Endpoint
+
+- `GET /artifacts/{artifactId}/status`
+  - Scopes: `ops_read` or `audit_read` or `finance_read`
+
+## Bulk status in ops job list
+
+- `GET /ops/jobs` includes inline verification fields per job:
+  - `verificationStatus` (`green` | `amber` | `red`)
+  - `evidenceCount`, `activeEvidenceCount`
+  - `slaCompliancePct`
+  - `verification` (full normalized verification object)
+- Scopes: `ops_read` or `audit_read`
+
+## Response shape
+
+The API returns:
+
+- Artifact identity fields (`artifactId`, `artifactType`, `artifactHash`, `jobId`, `sourceEventId`)
+- `verification` object with:
+  - `verificationStatus` (`green` | `amber` | `red`)
+  - `proofStatus` (`PASS` | `INSUFFICIENT_EVIDENCE` | `FAIL` | `null`)
+  - `reasonCodes`, `missingEvidence`
+  - `evidenceCount`, `activeEvidenceCount`
+  - `slaCompliancePct`
+  - Coverage metrics (`requiredZones`, `reportedZones`, `belowThresholdZones`, `missingZoneCount`, `excusedZones`)
+
+## Example
+
+```sh
+curl -sS "http://localhost:3000/artifacts/art_123/status" \
+  -H "x-proxy-tenant-id: tenant_default" \
+  -H "x-settld-protocol: 1.0" \
+  -H "x-proxy-ops-token: <ops_read_token>" | jq
+```

package/docs/ops/BILLING_WEBHOOK_REPLAY.md

@@ -0,0 +1,105 @@
+# Stripe Billing Webhook Replay Guardrail Runbook
+
+Use this runbook when Stripe webhook ingestion shows replayable dead-letter volume or subscription drift risk.
+
+## Preconditions
+
+- You have `finance_read` + `finance_write` scopes for the affected tenant.
+- Environment is set:
+  - `SETTLD_BASE_URL`
+  - `PROXY_OPS_TOKEN`
+  - `SETTLD_TENANT_ID`
+- `curl` and `jq` are available.
+
+## Reproducible command set
+
+### 1) Snapshot reconcile report
+
+```bash
+curl -sS \
+  -H "x-proxy-ops-token: $PROXY_OPS_TOKEN" \
+  -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+  "$SETTLD_BASE_URL/ops/finance/billing/providers/stripe/reconcile/report?limit=200" | jq .
+```
+
+Focus on:
+- `rejectedReasonCounts`
+- `replayableRejectedCount`
+- `sourceCounts`
+
+### 2) List replay candidates
+
+```bash
+curl -sS \
+  -H "x-proxy-ops-token: $PROXY_OPS_TOKEN" \
+  -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+  "$SETTLD_BASE_URL/ops/finance/billing/providers/stripe/dead-letter?limit=200" | jq .
+```
+
+Optional filters:
+- `.../dead-letter?reason=<reason>&eventType=<eventType>&limit=200`
+
+### 3) Dry-run replay
+
+```bash
+curl -sS -X POST \
+  -H "x-proxy-ops-token: $PROXY_OPS_TOKEN" \
+  -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+  -H "content-type: application/json" \
+  -d '{"dryRun":true,"limit":200}' \
+  "$SETTLD_BASE_URL/ops/finance/billing/providers/stripe/dead-letter/replay" | jq .
+```
+
+### 4) Execute replay
+
+```bash
+curl -sS -X POST \
+  -H "x-proxy-ops-token: $PROXY_OPS_TOKEN" \
+  -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+  -H "content-type: application/json" \
+  -d '{"dryRun":false,"limit":200}' \
+  "$SETTLD_BASE_URL/ops/finance/billing/providers/stripe/dead-letter/replay" | jq .
+```
+
+### 5) Validate post-replay state
+
+```bash
+curl -sS \
+  -H "x-proxy-ops-token: $PROXY_OPS_TOKEN" \
+  -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+  "$SETTLD_BASE_URL/ops/finance/billing/providers/stripe/reconcile/report?limit=200" | jq .
+```
+
+### 6) Scripted flow (recommended)
+
+```bash
+# Dry-run (default)
+scripts/dev/billing-webhook-replay.sh
+
+# Execute replay
+DRY_RUN=0 scripts/dev/billing-webhook-replay.sh
+
+# Scoped replay by reason/event type
+DRY_RUN=0 REASON=reconcile_apply_failed EVENT_TYPE=customer.subscription.updated \
+  scripts/dev/billing-webhook-replay.sh
+```
+
+## On-call validation checklist
+
+- [ ] Baseline report captured (`reconcile/report`) and incident ticket updated with snapshot.
+- [ ] Replay candidate count and reasons reviewed (`dead-letter`).
+- [ ] Dry-run replay performed and no schema/permission errors observed.
+- [ ] Live replay executed (`dryRun=false`) with `summary.failed == 0` (or failures documented).
+- [ ] Post-replay report shows expected movement in:
+  - [ ] `replayableRejectedCount` (downward or unchanged with reason)
+  - [ ] `ingestBreakdown.replayed` (upward)
+  - [ ] `sourceCounts.dead_letter_replay` (upward)
+- [ ] Tenant billing plan state verified:
+  - [ ] `GET /ops/finance/billing/plan`
+- [ ] Incident notes include replay scope (`reason`, `eventType`, `auditIds`) and final counts.
+
+## Rollback / safety notes
+
+- Replay is idempotent at event level; do not mutate historical audit rows manually.
+- If replay failures increase (`dead_letter_replay_apply_failed`), stop and investigate root cause before rerunning.
+- Never disable signature verification as an incident workaround.

package/docs/ops/CI_FLAKE_BUDGET.md

@@ -0,0 +1,31 @@
+# CI Flake Budget
+
+This repo runs with a strict flake budget for paid-call kernel coverage.
+
+## Policy
+
+- Budget: 0
+- No hidden retries in CI for test workflows.
+- No `continue-on-error: true` for test jobs.
+- No shell-level suppression (`|| true`) for test commands.
+
+## Scope
+
+- `.github/workflows/tests.yml`
+- The paid-call kernel suite job (`mcp_paid_call_kernel_suite`)
+- Existing `unit_tests` and quickstart smoke jobs
+
+## Escalation
+
+If a test flakes:
+
+1. Open/attach an issue immediately (`type:ops` or `type:bug`).
+2. Either:
+   - fix the test in the same PR, or
+   - quarantine with explicit owner + expiry date + follow-up issue.
+3. Do not merge by masking failure with retries or error suppression.
+
+## Enforcement
+
+`scripts/ci/flake-budget-guard.mjs` enforces the policy markers and blocks forbidden flaky-tolerance patterns in `tests.yml`.
+

package/docs/ops/DISPUTE_FINANCE_RECONCILIATION_PACKET.md

@@ -0,0 +1,56 @@
+# Dispute Finance Reconciliation Packet
+
+This runbook generates a deterministic packet for dispute-driven settlement adjustments.
+
+## Purpose
+
+- Produce a finance-reviewable packet for one `SettlementAdjustment.v1`.
+- Include adjustment artifact + before/after wallet snapshots for payer/payee.
+- Attach deterministic checksums and optional Ed25519 signature.
+
+## Command
+
+```bash
+node scripts/ops/dispute-finance-reconciliation-packet.mjs \
+  --base-url http://127.0.0.1:3000 \
+  --tenant-id tenant_default \
+  --ops-token tok_finw \
+  --adjustment-id sadj_agmt_<agreementHash>_holdback \
+  --payer-agent-id <payerAgentId> \
+  --payee-agent-id <payeeAgentId> \
+  --out artifacts/finance/dispute-adjustment-packet.json
+```
+
+Optional signing:
+
+```bash
+node scripts/ops/dispute-finance-reconciliation-packet.mjs \
+  --base-url http://127.0.0.1:3000 \
+  --tenant-id tenant_default \
+  --ops-token tok_finw \
+  --adjustment-id sadj_agmt_<agreementHash>_holdback \
+  --payer-agent-id <payerAgentId> \
+  --payee-agent-id <payeeAgentId> \
+  --signing-key-file ./keys/finance-ops-ed25519.pem \
+  --signature-key-id finance_ops_k1 \
+  --out artifacts/finance/dispute-adjustment-packet.signed.json
+```
+
+## Packet contract
+
+- `schemaVersion`: `DisputeFinanceReconciliationPacket.v1`
+- `adjustment`: `SettlementAdjustment.v1` payload from `/ops/settlement-adjustments/{adjustmentId}`
+- `balances.payer/payee.before|after`: wallet snapshots for reconciliation
+- `checksums.packetHash`: canonical packet checksum (`sha256`)
+- `checksums.adjustmentHash`: checksum carried by adjustment artifact
+- `signature` (optional): Ed25519 signature over `checksums.packetHash`
+
+## Finance review workflow
+
+1. Generate the packet immediately after dispute verdict/adjustment application.
+2. Verify `checksums.adjustmentHash` matches the adjustment artifact.
+3. Verify `checksums.packetHash` and (if present) `signature`.
+4. Reconcile `before -> after` snapshots against expected adjustment kind:
+   - `holdback_release`: payer escrow decreases; payee available increases.
+   - `holdback_refund`: payer escrow decreases; payer available increases.
+5. Attach packet to incident/dispute record for immutable finance traceability.

package/docs/ops/GO_LIVE_GATE_S13.md

@@ -0,0 +1,27 @@
+# S13 Go-Live Gate
+
+This gate operationalizes `STLD-T182`.
+
+## Command
+
+```bash
+RUN_THROUGHPUT_DRILL=1 \
+ALLOW_THROUGHPUT_SKIP=0 \
+GO_LIVE_TEST_COMMAND="node --test test/settlement-kernel.test.js && node --test test/api-e2e-ops-money-rails.test.js && node --test test/api-e2e-ops-finance-net-close.test.js && node --test test/api-e2e-ops-arbitration-workspace.test.js && node --test test/api-e2e-ops-command-center.test.js && node --test test/api-e2e-billing-plan-enforcement.test.js" \
+node scripts/ci/run-go-live-gate.mjs
+node scripts/ci/build-launch-cutover-packet.mjs
+```
+
+## Required checks
+
+- Deterministic critical test suite passes.
+- 10x throughput drill report passes.
+- Throughput incident rehearsal report passes.
+- Lighthouse tracker shows at least 3 accounts in `paid_production_settlement_confirmed`/`production_active` with `signedAt`, `goLiveAt`, and `productionSettlementRef` populated.
+
+## Output
+
+- `artifacts/gates/s13-go-live-gate.json`
+- `artifacts/gates/s13-launch-cutover-packet.json`
+
+Gate is **fail-closed**: non-zero exit on any failed required check.

package/docs/ops/HOSTED_BASELINE_R2.md

@@ -0,0 +1,129 @@
+# Sprint R2: Hosted Baseline (Staging + Production)
+
+This is the minimum hosted setup for a real product surface.
+
+## 1) Environment topology
+
+- `staging.app.settld.work` (frontend, Vercel)
+- `staging.api.settld.work` (API, Railway)
+- `app.settld.work` (frontend, Vercel)
+- `api.settld.work` (API, Railway)
+- Separate Postgres instances/schemas and separate secret sets for staging/prod.
+- Separate signing keys per environment (never reuse signer keys across staging/prod).
+
+## 2) Railway service split
+
+Create two Railway services from this repo per environment:
+
+- `settld-api`:
+  - start command: `npm run start:prod`
+- `settld-worker`:
+  - start command: `npm run start:maintenance`
+
+Both services must point at the same environment DB and secret set for that environment.
+
+## 3) Required runtime controls
+
+- Tenant rate limiting:
+  - `PROXY_RATE_LIMIT_RPM`
+  - `PROXY_RATE_LIMIT_BURST`
+- API-key rate limiting:
+  - `PROXY_RATE_LIMIT_PER_KEY_RPM`
+  - `PROXY_RATE_LIMIT_PER_KEY_BURST`
+- Tenant quotas:
+  - `PROXY_QUOTA_*` and `PROXY_QUOTA_PLATFORM_*` envs from `docs/CONFIG.md`.
+
+## 4) Observability + alerts
+
+Scrape `/metrics` and enable rules from `deploy/observability/prometheus-rules.yml`.
+
+R2-required alerts:
+
+- replay mismatches: `replay_mismatch_gauge`
+- stuck disputes: `disputes_over_sla_gauge`, `arbitration_over_sla_gauge`
+- stuck holds: `settlement_holds_over_24h_gauge`
+- worker lag: `worker_outbox_pending_total_gauge`, `worker_deliveries_pending_total_gauge`
+
+Reference: `docs/ALERTS.md`.
+
+## 5) Backups + restore drill
+
+- Backup/restore scripts: `scripts/backup-pg.sh`, `scripts/restore-pg.sh`
+- Full drill script: `scripts/backup-restore-test.sh`
+- Run at least weekly for staging and monthly for production.
+- Record evidence in incident/runbook logs (timestamp, operator, pass/fail, DB snapshot IDs).
+
+## 6) Clerk onboarding handoff (app -> API)
+
+The app should map Clerk identity/org to a tenant ID, then bootstrap that tenant on the API side.
+
+Recommended server-side flow:
+
+1. User signs up/signs in via Clerk at `*.app.settld.work`.
+2. App backend chooses tenant ID (for example: `tenant_<clerk_org_id>`).
+3. App backend calls:
+   - `POST /ops/tenants/bootstrap` (with a privileged ops token, server-side only)
+4. App stores/bootstrap-returns tenant API key and presents onboarding state + Explorer links.
+
+## 7) New-tenant acceptance run
+
+Use this command to prove onboarding is self-serve and conformance-ready:
+
+```bash
+npm run ops:tenant:bootstrap:conformance -- \
+  --base-url https://staging.api.settld.work \
+  --ops-token "$SETTLD_STAGING_OPS_TOKEN" \
+  --tenant-id "tenant_demo_$(date +%s)"
+```
+
+This performs:
+
+- tenant bootstrap
+- API key issuance
+- kernel conformance run with that new tenant/API key
+
+## 8) Acceptance bar (R2)
+
+- Brand-new tenant can be created from app onboarding flow.
+- Tenant receives API key without manual DB edits.
+- Tenant can run kernel conformance against staging/prod.
+- Explorer, replay, and closepack flows are reachable for that tenant.
+
+## 9) Hosted baseline evidence command
+
+Use the ops command below to collect a deterministic hosted-baseline evidence artifact (health, ops status, metrics, alert metric presence, billing catalog/quotas, optional rate-limit probe, optional backup/restore drill evidence):
+
+```bash
+npm run ops:hosted-baseline:evidence -- \
+  --base-url https://staging.api.settld.work \
+  --tenant-id tenant_default \
+  --ops-token "$SETTLD_STAGING_OPS_TOKEN" \
+  --environment staging \
+  --rate-limit-mode optional \
+  --rate-limit-probe-requests 20 \
+  --out ./artifacts/ops/hosted-baseline-evidence-staging.json
+```
+
+If you want the command to execute the backup/restore drill inline:
+
+```bash
+npm run ops:hosted-baseline:evidence -- \
+  --base-url https://staging.api.settld.work \
+  --tenant-id tenant_default \
+  --ops-token "$SETTLD_STAGING_OPS_TOKEN" \
+  --environment staging \
+  --run-backup-restore true \
+  --database-url "$DATABASE_URL" \
+  --restore-database-url "$RESTORE_DATABASE_URL" \
+  --require-backup-restore true \
+  --out ./artifacts/ops/hosted-baseline-evidence-staging.json
+```
+
+Important:
+
+- `DATABASE_URL` and `RESTORE_DATABASE_URL` must be real connection strings (not redacted placeholders like `postgres://...`).
+- Quick preflight:
+
+```bash
+node -e 'for (const n of ["DATABASE_URL","RESTORE_DATABASE_URL"]) { const v=(process.env[n]||"").trim(); if (!v) { console.error(`${n}=missing`); process.exitCode=1; continue; } const u=new URL(v); console.log(`${n} host=${u.hostname} protocol=${u.protocol}`); }'
+```

package/docs/ops/KERNEL_V0_SHIP_GATE.md

@@ -0,0 +1,69 @@
+# Kernel v0 Ship Gate
+
+This is the fail-closed release gate for shipping the current Kernel v0 OSS rails.
+
+## Command
+
+```bash
+node scripts/ci/run-kernel-v0-ship-gate.mjs
+```
+
+Optional:
+
+```bash
+RUN_KERNEL_V0_QUICKSTART_SMOKE=0 node scripts/ci/run-kernel-v0-ship-gate.mjs
+```
+
+Report output:
+
+- `artifacts/gates/kernel-v0-ship-gate.json`
+
+## CI enforcement
+
+1. `.github/workflows/tests.yml` runs `kernel_v0_ship_gate` on every `push` to `main`.
+2. `.github/workflows/tests.yml` also runs `production_cutover_gate` on every `push` to `main`.
+3. `.github/workflows/release.yml` blocks release unless that same commit has successful `kernel_v0_ship_gate` and `production_cutover_gate` results from `tests.yml`.
+4. `.github/workflows/production-cutover-gate.yml` provides manual live-environment validation using `production_cutover_gate` GitHub Environment secrets.
+
+## Included checks
+
+1. Launch-claim truth gate (`check-kernel-v0-launch-gate.mjs --mode prepublish`)
+2. Core x402 e2e confidence suite
+3. API/SDK contract freeze + OpenAPI snapshot checks
+4. x402 quickstart smoke (`quickstart:x402`, default on)
+
+Any failed check stops the sequence and returns non-zero.
+
+## Rollout plan
+
+1. Canary: ship to internal/demo environments and run full gate before every cut.
+2. Scale-out: ship to design-partner environments after two consecutive green gate runs.
+3. Full OSS release: publish only when the latest gate report is green and attached to release notes.
+
+## Rollback triggers
+
+Rollback immediately if any of the following happen after release:
+
+1. Deterministic replay/receipt verification mismatch in production-like flow.
+2. x402 authorize/verify path starts returning unexpected non-contract error codes.
+3. Quickstart regression (`quickstart:x402`) fails on clean environment.
+
+## Rollback execution
+
+1. Freeze new rollout and revert to previous known-good release/tag.
+2. Re-run ship gate against rollback candidate.
+3. Re-open rollout only after green gate + root-cause note.
+
+## Monitoring and alerting
+
+Track at minimum:
+
+1. `x402` authorize/verify success and conflict code distribution.
+2. Receipt verification failures.
+3. Quickstart smoke health in CI cadence.
+
+## Owner / on-call
+
+- Release owner: Platform/Kernel maintainer
+- Escalation owner: API maintainer
+- Rollback approver: Tech lead on-call

package/docs/ops/LIGHTHOUSE_PRODUCTION_CLOSE.md

@@ -0,0 +1,51 @@
+# Lighthouse Production Close
+
+Tracks `STLD-T180` with repo-auditable evidence.
+
+## Source of truth
+
+- `planning/launch/lighthouse-production-tracker.json`
+
+## Account status model
+
+- `targeting`
+- `contracting`
+- `integration_in_progress`
+- `go_live_scheduled`
+- `paid_production_settlement_confirmed`
+- `production_active`
+
+## Required evidence per account
+
+- Signed commercial date (`signedAt`)
+- Go-live date (`goLiveAt`)
+- Production settlement reference (`productionSettlementRef`)
+
+`productionSettlementRef` should point to a deterministic, queryable settlement artifact ID or run settlement ID.
+
+## Launch criterion
+
+At least 3 accounts must be in `paid_production_settlement_confirmed` or `production_active` with non-empty `productionSettlementRef`.
+
+## Validation path
+
+The go-live gate uses `scripts/ci/lib/lighthouse-tracker.mjs` for readiness checks and requires all active accounts to include:
+- `signedAt` (valid ISO timestamp)
+- `goLiveAt` (valid ISO timestamp and not earlier than `signedAt`)
+- `productionSettlementRef` (non-empty)
+
+## Update commands
+
+Update tracker rows with validation instead of manual JSON edits:
+
+```bash
+npm run ops:lighthouse:update -- \
+  --account lh_001 \
+  --status paid_production_settlement_confirmed \
+  --company-name "Example Co" \
+  --owner "am@settld" \
+  --signed-at 2026-02-10T12:00:00.000Z \
+  --go-live-at 2026-02-11T15:30:00.000Z \
+  --settlement-ref settle_run_abc123 \
+  --notes "First paid production settlement."
+```