settld 0.1.1 → 0.1.5

package/docs/ops/P0_BACKEND_PROGRESS.md

@@ -0,0 +1,150 @@
+# P0 Backend Progress Tracker
+
+Status date: February 13, 2026
+
+This tracker is the source of truth for P0 backend execution status in code.
+
+## Scope
+
+P0 backend scope tracked here:
+
+1. Hosted baseline hardening controls
+2. Real-money payout controls and rail safety
+3. Deterministic reconciliation + enforcement evidence
+4. Billing/runtime and launch-gate alignment
+
+## Shipped in this change set
+
+- [x] Tenant-level real-money payout gate (production providers require explicit tenant enablement)
+- [x] Tenant-level payout kill switch
+- [x] Tenant-level max single payout cap
+- [x] Tenant-level daily payout exposure cap
+- [x] Tenant-level allowed provider allowlist
+- [x] Optional signed provider event ingestion enforcement for money-rail events
+- [x] Stripe production payout submit endpoint executes `/v1/transfers` with deterministic metadata mapping
+- [x] Stripe Connect payout submit enforces `stripe_connect:<acct_...>` counterparty destination in production mode
+- [x] Submit endpoint idempotency + ops audit trail (`MONEY_RAIL_OPERATION_SUBMITTED`)
+- [x] Stripe Connect KYB/capability sync endpoint updates payout eligibility from provider account state
+- [x] Chargeback policy automation (`hold|net`) with negative-balance payout enforcement
+- [x] Chargeback exposure API for per-party outstanding/recovered tracking
+- [x] Chargeback evidence automation command emits deterministic run artifact hash (optional Ed25519 signature)
+- [x] Hosted baseline evidence automation command (health/status/metrics + optional rate-limit probe + optional backup/restore drill)
+- [x] Design-partner run packet generator chaining reconcile + chargeback evidence into one hashable/signable artifact
+- [x] Periodic money-rail reconciliation scheduler with advisory-lock safety
+- [x] Money-rail reconciliation maintenance run endpoint with ops audit trail
+- [x] Maintenance status surface now includes money-rail reconciliation state/result
+- [x] Money-rail controls surfaced through existing billing plan control-plane API
+- [x] Runtime billing catalog aligns with public pricing (including Growth $0.007/run via milli-cent accounting)
+- [x] CI smoke runs exact local tarball `npx --package ./settld-<version>.tgz` command path
+
+Implemented in:
+
+- `src/api/app.js`
+- `src/api/maintenance.js`
+- `src/core/billing-plans.js`
+- `src/api/openapi.js`
+- `scripts/ci/cli-pack-smoke.mjs`
+- `scripts/ops/money-rails-chargeback-evidence.mjs`
+- `scripts/ops/hosted-baseline-evidence.mjs`
+- `scripts/ops/design-partner-run-packet.mjs`
+- `test/api-e2e-ops-money-rails.test.js`
+- `test/api-e2e-billing-plan-enforcement.test.js`
+- `test/api-e2e-ops-maintenance-money-rails-reconcile.test.js`
+- `test/pg-maintenance-money-rails-reconcile-lock.test.js`
+
+## API behavior now enforced
+
+- `POST /ops/payouts/{partyId}/{period}/enqueue`
+  - Rejects with `REAL_MONEY_DISABLED` when provider is production and tenant real-money is not enabled.
+  - Rejects with `PAYOUT_KILL_SWITCH_ACTIVE` when kill switch is on.
+  - Rejects with `PAYOUT_AMOUNT_LIMIT_EXCEEDED` when single payout exceeds tenant cap.
+  - Rejects with `PAYOUT_DAILY_LIMIT_EXCEEDED` when projected daily exposure exceeds tenant cap.
+  - Rejects with `MONEY_RAIL_PROVIDER_NOT_ALLOWED` when provider is outside tenant allowlist.
+
+- `POST /ops/money-rails/{providerId}/events/ingest`
+  - Supports optional signed-ingest verification when provider config requires it.
+  - Validates `x-proxy-provider-signature` (`t=<unix>,v1=<hmac_sha256_hex>`) against configured provider webhook secret.
+
+- `POST /ops/money-rails/{providerId}/operations/{operationId}/submit`
+  - Submits initiated payout operations to the provider.
+  - For production Stripe providers, calls Stripe `/v1/transfers` and transitions operation to `submitted` with `providerRef=transfer_id`.
+  - Enforces Connect destination shape (`stripe_connect:<acct_...>`) and returns `STRIPE_CONNECT_COUNTERPARTY_REQUIRED` when invalid.
+  - Returns `MONEY_RAIL_SUBMIT_INVALID_STATE` when operation is no longer submit-eligible.
+
+- `GET /ops/finance/money-rails/chargebacks`
+  - Returns deterministic per-party chargeback exposure (`outstanding`, `recovered`, counts) with optional `providerId|partyId|period` filters.
+
+- `POST /ops/finance/money-rails/stripe-connect/accounts/sync`
+  - Pulls Stripe Account state (`/v1/accounts/{accountId}`) and syncs Connect account capability/KYB fields.
+  - Updates `payoutsEnabled`/`transfersEnabled` + KYB status and requirement sets.
+  - Supports deterministic idempotency replay and records `STRIPE_CONNECT_ACCOUNTS_SYNC` ops audit.
+
+- `POST /ops/maintenance/money-rails-reconcile/run`
+  - Runs periodic-grade money-rail reconciliation on demand with advisory lock safety.
+  - Persists `MoneyRailReconcileReport.v1` artifacts with deterministic report hashes.
+  - Writes `MAINTENANCE_MONEY_RAIL_RECONCILE_RUN` audit records with outcome/runtime/summary.
+
+- `GET /ops/status`
+  - Exposes `maintenance.moneyRailReconciliation` (enabled/interval/limits/last run/result/audit refs).
+
+- `GET/PUT /ops/finance/billing/plan`
+  - Returns and persists `billing.moneyRails` controls.
+
+## Validation evidence
+
+Executed and passing:
+
+- `node --test test/api-e2e-ops-money-rails.test.js`
+- `node --test test/api-e2e-ops-maintenance-money-rails-reconcile.test.js`
+- `node --test test/api-e2e-billing-plan-enforcement.test.js`
+- `node scripts/ci/cli-pack-smoke.mjs`
+- `node scripts/ops/money-rails-chargeback-evidence.mjs --help`
+- `node scripts/ops/hosted-baseline-evidence.mjs --help`
+- `node scripts/ops/design-partner-run-packet.mjs --help`
+
+## Current hosted evidence snapshot (2026-02-13)
+
+- [x] `ops:hosted-baseline:evidence` passes against `https://api.settld.work` for:
+  - health/status
+  - required metrics presence
+  - billing catalog/quotas validation
+- [x] Production hosted-baseline backup/restore evidence is now passing.
+  - Captured at: `2026-02-13T02:19:48.251Z`
+  - Artifact: `artifacts/ops/hosted-baseline-prod.json`
+  - `artifactHash`: `2a5833fd44e6b904ed87763e2d1212e02ffcd9583c4d50fdd5b2cffa3d99a597`
+  - Backup/restore: `checks.backupRestore.ok=true`
+  - External archive path: `/home/aiden/ops-evidence/settld/hosted-baseline/2026-02-13`
+- [x] Staging hosted-baseline backup/restore evidence is now passing.
+  - Captured at: `2026-02-13T02:26:37.785Z`
+  - Artifact: `artifacts/ops/hosted-baseline-staging.json`
+  - `artifactHash`: `354f339d1c668eccb000416a231309ed6f3a5614539d43448aad9f6f3ca0dc28`
+  - Backup/restore: `checks.backupRestore.ok=true`
+  - External archive path: `/home/aiden/ops-evidence/settld/hosted-baseline/2026-02-13`
+
+### Money-Rail Chargeback + Design-Partner Packet (2026-02-13)
+
+- [x] Chargeback/refund simulation evidence run captured and signed.
+  - Tenant: `tenant_p0_evidence_20260213_v9`
+  - Period: `2026-02`
+  - Artifact: `artifacts/ops/chargeback-evidence-tenant_p0_evidence_20260213_v9.json`
+  - `artifactHash`: `a7df81308cfed250ecc93a2997758f09d91a807beb74f3a8cd8aaee3f181fbe7`
+
+- [x] Design-partner run packet captured and signed (reconcile is expected to fail when a chargeback reversal is present).
+  - Tenant: `tenant_p0_evidence_20260213_v9`
+  - Period: `2026-02`
+  - Artifact: `artifacts/ops/design-partner-run-packet-tenant_p0_evidence_20260213_v9.json`
+  - `artifactHash`: `c6eaa09b8ee4f662cb95403800d87cf89ace865bd6e7c29bfe09b5ab5a2b7e62`
+  - Reconcile report hash: `36e8e5fb2ed0af3574aa41c8d72e66020fe19130bb185daa67af079983354cac`
+  - External archive path: `/home/aiden/ops-evidence/settld/p0/2026-02-13/tenant_p0_evidence_20260213_v9`
+
+## Remaining P0 work (outside this code drop)
+
+- [x] Execute hosted baseline evidence runs in staging/prod with `--run-backup-restore true` and archive signed artifacts
+- [x] Execute chargeback/refund simulation runs and archive signed artifacts
+- [x] Execute design-partner run packets against live partner tenants (repeatable, no manual DB edits)
+
+References:
+
+- `docs/ops/HOSTED_BASELINE_R2.md`
+- `docs/ops/PAYMENTS_ALPHA_R5.md`
+- `planning/kernel-v0-truth-audit.md`

package/docs/ops/PAYMENTS_ALPHA_R5.md

@@ -0,0 +1,105 @@
+# Payments Alpha (R5) - Design Partner Scope
+
+This runbook defines the private real-money alpha while Kernel v0 remains public with ledger/test-fund flows.
+
+## Objective
+
+Validate mapping from kernel settlement artifacts to real payment rails with 3-5 design partners, without opening public GA risk surface.
+
+## Non-Goals (Alpha)
+
+- No public self-serve real-money onboarding.
+- No generalized multi-rail support.
+- No claim of universal chargeback protection.
+
+## Required Design Decisions
+
+- Merchant-of-record model is explicitly documented.
+- Holdback/challenge window mapping to payout timing is explicit and testable.
+- Refund and chargeback policy defines behavior when reversals exceed retained holdback.
+
+## Required Implementation Surfaces
+
+- Feature flag gate per tenant for real-money flows.
+- Rail adapter integration (for example Stripe Connect) with webhook ingestion and signed webhook verification.
+- Reconciliation tables keyed by settlement/receipt/adjustment IDs.
+- Periodic reconciliation job that produces mismatch reports.
+- Ops view for mismatch triage with reason codes.
+
+### Implementation status snapshot (2026-02-12)
+
+- Implemented in API runtime:
+  - Tenant-level real-money payout gate
+  - Tenant-level payout kill switch
+  - Tenant-level single-payout cap
+  - Tenant-level daily payout cap
+  - Tenant-level provider allowlist
+  - Optional signed provider-event ingestion enforcement for money rails
+  - Stripe Connect account mapping endpoints + payout counterparty enforcement
+  - Stripe Connect KYB/capability sync endpoint (`POST /ops/finance/money-rails/stripe-connect/accounts/sync`) pulling `/v1/accounts/{accountId}`
+  - Stripe production payout submit endpoint (`POST /ops/money-rails/{providerId}/operations/{operationId}/submit`) calling `/v1/transfers`
+  - Chargeback negative-balance policy automation (`hold|net`) + exposure API
+  - Scheduled money-rail reconciliation maintenance with advisory locks + audit trail
+  - Runtime billing catalog alignment for `free|builder|growth|enterprise` (Growth `$0.007/run` preserved with milli-cent accounting)
+- Source: `src/api/app.js`, `test/api-e2e-ops-money-rails.test.js`
+- Source (maintenance scheduler): `src/api/maintenance.js`, `test/api-e2e-ops-maintenance-money-rails-reconcile.test.js`
+- Source (billing alignment): `src/core/billing-plans.js`, `test/api-e2e-billing-plan-enforcement.test.js`
+- Source (chargeback evidence automation): `scripts/ops/money-rails-chargeback-evidence.mjs`
+- Source (design-partner run packet automation): `scripts/ops/design-partner-run-packet.mjs`
+- Tracker: `docs/ops/P0_BACKEND_PROGRESS.md`
+
+## Chargeback Evidence Command
+
+Use this command to capture a deterministic chargeback drill artifact that includes API call traces, computed checks, and a stable `artifactHash`:
+
+```bash
+npm run ops:money-rails:chargeback:evidence -- \
+  --base-url https://staging.api.settld.work \
+  --tenant-id tenant_design_partner_1 \
+  --ops-token "$SETTLD_STAGING_OPS_TOKEN" \
+  --provider-id stripe_prod_us \
+  --operation-id op_example_123 \
+  --period 2026-02 \
+  --expect-outstanding-cents 2000 \
+  --out ./artifacts/chargeback-evidence-2026-02.json
+```
+
+Optional signature fields:
+
+- `--signing-key-file <pkcs8_ed25519_pem>`
+- `--signature-key-id <key_id>`
+
+## Design-partner run packet command
+
+Use this command to generate one signed/hashable packet that chains:
+
+1. money-rail reconciliation evidence
+2. chargeback evidence
+
+```bash
+npm run ops:design-partner:run-packet -- \
+  --base-url https://staging.api.settld.work \
+  --tenant-id tenant_design_partner_1 \
+  --ops-token "$SETTLD_STAGING_OPS_TOKEN" \
+  --provider-id stripe_prod_us \
+  --period 2026-02 \
+  --chargeback-operation-id op_example_123 \
+  --chargeback-party-id pty_example_123 \
+  --chargeback-payout-period 2026-03 \
+  --expect-chargeback-payout-code NEGATIVE_BALANCE_PAYOUT_HOLD \
+  --out ./artifacts/ops/design-partner-run-packet-2026-02.json
+```
+
+## Risk Controls
+
+- Tenant-level transaction/payout limits.
+- Daily mismatch alert threshold.
+- Kill switch to disable payouts by tenant.
+- Manual override workflow for reconciliation exceptions.
+
+## Acceptance Criteria
+
+- Every external money movement maps to a kernel receipt or adjustment reference.
+- Reconciliation report is zero-drift in normal flows and explainable for induced failure scenarios.
+- Chargeback/refund simulation runbook is executed and recorded.
+- Design partner tenants can complete the same flow repeatedly without manual DB edits.

package/docs/ops/PILOT_ONBOARDING_RUNBOOK.md

@@ -0,0 +1,112 @@
+# Pilot Onboarding Runbook (x402 Gateway)
+
+Goal: install a design partner in one afternoon and prove a known-good `402 -> authorize -> verify -> settled` flow.
+
+## 1. Prerequisites
+
+- Runtime: Node 20+, Docker available for hosted acceptance checks.
+- Access:
+  - Settld API base URL (`SETTLD_BASE_URL`)
+  - tenant id (`SETTLD_TENANT_ID`)
+  - ops token (`PROXY_OPS_TOKEN`) to mint scoped API keys
+- Pilot safety defaults:
+  - `X402_PILOT_KILL_SWITCH=0`
+  - `X402_PILOT_MAX_AMOUNT_CENTS=100`
+  - `X402_PILOT_DAILY_LIMIT_CENTS=1000`
+
+## 2. Environment Setup (15-20m)
+
+```bash
+export SETTLD_BASE_URL='https://api.settld.work'
+export SETTLD_TENANT_ID='tenant_default'
+export PROXY_OPS_TOKEN='tok_ops'
+```
+
+Mint a scoped API key:
+
+```bash
+curl -sS -X POST "$SETTLD_BASE_URL/ops/api-keys" \
+  -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+  -H "x-proxy-ops-token: $PROXY_OPS_TOKEN" \
+  -H 'x-settld-protocol: 1.0' \
+  -H 'content-type: application/json' \
+  -d '{"scopes":["ops_read","ops_write","audit_read","finance_read","finance_write"]}' | jq .
+```
+
+## 3. Gateway Deploy (10-15m)
+
+Use the local smoke stack as the deployment sanity baseline:
+
+```bash
+scripts/dev/smoke-x402-gateway.sh
+```
+
+For hosted deployment, configure gateway env:
+
+- `SETTLD_API_URL=<api base>`
+- `SETTLD_API_KEY=<keyId.secret>`
+- `UPSTREAM_URL=<paid upstream base>`
+- `X402_AUTOFUND=1` for pilot/demo rails only
+
+## 4. Sandbox vs Production Mode
+
+| Mode | Required vars | Notes |
+|---|---|---|
+| `sandbox` | `SETTLD_DEMO_CIRCLE_MODE=sandbox`, `X402_REQUIRE_EXTERNAL_RESERVE=1` | Safe pilot proving reserve path without live funds |
+| `production` | `SETTLD_DEMO_CIRCLE_MODE=production`, live Circle vars (`CIRCLE_API_KEY`, wallet ids, token id) | Keep strict caps and provider allowlist on |
+
+## 5. Known-Good Health Check Flow (10m)
+
+1. Gateway health:
+
+```bash
+curl -sS http://127.0.0.1:8402/healthz | jq .
+```
+
+2. First request returns `402` + `x-settld-gate-id`:
+
+```bash
+FIRST_HEADERS=$(mktemp)
+curl -sS -D "$FIRST_HEADERS" 'http://127.0.0.1:8402/exa/search?q=pilot+health' -o /tmp/pilot-first-body.json
+GATE_ID=$(awk 'tolower($1)=="x-settld-gate-id:" {print $2}' "$FIRST_HEADERS" | tr -d '\r')
+echo "$GATE_ID"
+```
+
+3. Retry with gate id returns `200` and settlement headers:
+
+```bash
+curl -sS -D /tmp/pilot-second-headers.txt \
+  -H "x-settld-gate-id: $GATE_ID" \
+  'http://127.0.0.1:8402/exa/search?q=pilot+health' -o /tmp/pilot-second-body.json
+```
+
+4. Confirm gate resolved in API:
+
+```bash
+curl -sS "$SETTLD_BASE_URL/x402/gate/$GATE_ID" \
+  -H "x-proxy-tenant-id: $SETTLD_TENANT_ID" \
+  -H "authorization: Bearer $SETTLD_API_KEY" \
+  -H 'x-settld-protocol: 1.0' | jq '{gateId:.gate.gateId,status:.gate.status,settlement:.settlement.status}'
+```
+
+Expected: `status=resolved` and non-locked settlement.
+
+## 6. Rollback Procedure (Fail-Closed)
+
+1. Activate kill switch:
+
+```bash
+export X402_PILOT_KILL_SWITCH=1
+```
+
+2. Restart API/gateway with kill switch active.
+3. Verify authorize rejects with `X402_PILOT_KILL_SWITCH_ACTIVE`.
+4. Drain in-flight checks; stop new pilot traffic.
+5. Revert risky config (prod reserve mode, provider allowlist overrides).
+6. Run health checks again in sandbox mode before re-opening traffic.
+
+## 7. Pilot Exit Criteria
+
+- Health check flow passes end-to-end.
+- Reliability report generated (`X402PilotReliabilityReport.v1`) and within thresholds.
+- Rollback drill executed once and documented.

package/docs/ops/PRODUCTION_DEPLOYMENT_CHECKLIST.md

@@ -0,0 +1,103 @@
+# Production Deployment Checklist
+
+Use this checklist to launch and verify a real hosted Settld environment.
+
+## Phase 0: Preflight
+
+1. Confirm branch protection includes `tests / kernel_v0_ship_gate`.
+2. Confirm release workflow is blocked unless ship gate is green.
+3. Confirm staging and production have separate domains, databases, secrets, and signer keys.
+4. Confirm required services are deployable: `npm run start:prod`, `npm run start:maintenance`, `npm run start:x402-gateway`.
+
+## Phase 1: Environment + secrets
+
+1. Provision Postgres and store `DATABASE_URL`.
+2. Set `STORE=pg`, `NODE_ENV=production`, `PROXY_MIGRATE_ON_STARTUP=1`.
+3. Set scoped `PROXY_OPS_TOKENS`.
+4. Configure rate limits and quotas from `docs/CONFIG.md`.
+5. Configure gateway secrets: `SETTLD_API_URL`, `SETTLD_API_KEY`, `UPSTREAM_URL`.
+
+## Phase 2: Deploy services
+
+1. Deploy `settld-api`.
+2. Deploy `settld-maintenance`.
+3. Deploy `x402-gateway`.
+4. Verify service health:
+
+```bash
+curl -fsS https://api.settld.work/healthz
+curl -fsS https://gateway.settld.work/healthz
+```
+
+## Phase 3: Baseline ops verification
+
+1. Run hosted baseline evidence command:
+
+```bash
+npm run ops:hosted-baseline:evidence -- \
+  --base-url https://api.settld.work \
+  --tenant-id tenant_default \
+  --ops-token "$SETTLD_OPS_TOKEN" \
+  --environment production \
+  --out ./artifacts/ops/hosted-baseline-evidence-production.json
+```
+
+2. Confirm alert metric presence and health signals.
+3. Run backup/restore drill evidence path at least once before opening customer traffic.
+
+## Phase 4: MCP compatibility verification
+
+1. Run core MCP automated tests:
+
+```bash
+node --test \
+  test/mcp-stdio-spike.test.js \
+  test/mcp-http-gateway.test.js \
+  test/mcp-paid-exa-tool.test.js \
+  test/mcp-paid-weather-tool.test.js \
+  test/mcp-paid-llm-tool.test.js \
+  test/demo-mcp-paid-exa.test.js
+```
+
+2. Run the hosted-style MCP smoke gate (API + magic-link bootstrap + MCP probe):
+
+```bash
+npm run test:ci:mcp-host-smoke
+```
+
+This emits a machine-readable report at:
+
+`artifacts/ops/mcp-host-smoke.json`
+
+3. Run host quickstart validation from `docs/QUICKSTART_MCP_HOSTS.md` for:
+   Claude, Cursor, Codex, and OpenClaw.
+
+4. Update `docs/ops/MCP_COMPATIBILITY_MATRIX.md` with pass/fail + date.
+
+## Phase 5: Paid call + receipt proof
+
+1. Run a paid demo flow:
+
+```bash
+npm run demo:mcp-paid-exa
+```
+
+2. Confirm artifacts exist:
+   `artifacts/mcp-paid-exa/.../summary.json` and gate/settlement evidence files in the same run directory.
+3. Verify receipt path using existing verifier tooling.
+
+## Phase 6: Go-live decision gate
+
+Ship only when all are true:
+
+1. Kernel v0 ship gate is green.
+2. Hosted baseline evidence is green.
+3. MCP compatibility matrix is green for supported hosts.
+4. Paid MCP run artifacts verify cleanly.
+5. Rollback runbook has been rehearsed.
+
+## Phase 7: Post-release
+
+1. Monitor `/metrics` + SLO dashboards.
+2. Track weekly reliability report (`docs/ops/X402_PILOT_WEEKLY_METRICS.md`).
+3. Re-run compatibility checks on every major host release.

package/docs/ops/R1_SLOS.md

@@ -0,0 +1,66 @@
+# Release 1 SLOs and Error Budgets
+
+Date baseline: February 7, 2026
+Release target: `Settld Verified Transactions v1` (end of Sprint 4)
+
+## Scope
+
+These SLOs govern the Release 1 production path:
+
+- Agent identity registration and wallet funding.
+- Marketplace RFQ, bid, accept, and run execution flows.
+- Settlement, dispute, and policy replay endpoints.
+- Ops payout enqueue and money rail operation status/cancel flows.
+
+## SLO-1: API availability
+
+- SLI: successful request ratio for R1 endpoints.
+- Objective: 99.9% monthly availability.
+- Error budget: 43m 49s/month.
+- Burn alert thresholds:
+- Fast burn: >10% budget consumed in 1 hour.
+- Slow burn: >25% budget consumed in 7 days.
+
+## SLO-2: Settlement latency
+
+- SLI: p95 latency for terminal settlement transitions (auto or manual resolve).
+- Objective: p95 < 2.5s.
+- Error budget: 5% of settlement requests may exceed p95 threshold.
+
+## SLO-3: Verification latency
+
+- SLI: p95 latency for verification status computation on run terminal events.
+- Objective: p95 < 3.0s.
+- Error budget: 5% monthly.
+
+## SLO-4: Money rail operation freshness
+
+- SLI: age of operations remaining in `initiated` or `submitted` without progress.
+- Objective: 99% of operations progress or close within 30 minutes.
+- Error budget: 1% monthly.
+
+## SLO-5: Reconciliation backlog age
+
+- SLI: age of unresolved reconciliation mismatches.
+- Objective: 95% resolved within 48 hours.
+- Error budget: 5% monthly.
+
+## SLO-6: Determinism drift
+
+- SLI: count of deterministic replay mismatches in CI release-gate suites.
+- Objective: 0 per release candidate.
+- Error budget: none; any drift is release-blocking.
+
+## Release-blocking conditions
+
+- Any failing deterministic replay/conformance suite.
+- Any unacknowledged Sev1 or Sev2 incident on settlement or verification path.
+- Missing rollback plan for money rails, escrow/netting, or arbitration changes.
+
+## Dashboard requirements
+
+- Endpoint latency and availability by route family.
+- Settlement states over time and stuck-state counts.
+- Money rail lifecycle state histogram by provider.
+- Reconciliation mismatch count and age buckets.
+- Determinism gate pass/fail trend by commit.

package/docs/ops/RELEASE_SIGNING_INCIDENT.md

@@ -0,0 +1,58 @@
+# Release signing incident runbook
+
+This runbook covers the “release signing key compromised” scenario for Settld distribution artifacts.
+
+## Immediate goals
+
+- Prevent future malicious releases from verifying.
+- Preserve a clear audit trail of what happened and what was rotated.
+
+## Assumptions
+
+- Release authenticity is verified via `ReleaseIndex.v1` + `ReleaseTrust.v2` (see `docs/spec/SUPPLY_CHAIN.md`).
+- Release trust roots are pinned in `trust/release-trust.json`.
+- Release signing private keys are stored as CI secrets (e.g., `SETTLD_RELEASE_SIGNING_PRIVATE_KEY_PEM`).
+
+## Procedure (high-level)
+
+1) **Revoke compromised key**
+
+- Edit `trust/release-trust.json`:
+  - Keep the key entry (do not delete immediately).
+  - Set `revokedAtEpochSeconds` to the intended cutoff time.
+  - Add/update `comment` with incident reference.
+
+2) **Add replacement key**
+
+- Generate a new Ed25519 keypair (private key never committed).
+- Add its public key + `keyId` into `trust/release-trust.json`.
+- If you require quorum, ensure policy still holds (`policy.minSignatures`).
+
+3) **Rotate CI secrets**
+
+- Update the release workflow secret(s) to use the new private key(s).
+- If quorum is required, ensure CI has all required signing keys/secrets.
+
+4) **Cut a release candidate and verify**
+
+- Produce release artifacts.
+- Verify via:
+  - `settld-release verify --dir <release-assets-dir> --trust-file trust/release-trust.json --format json --explain`
+
+5) **Validate the block**
+
+- A release signed with the revoked key at/after `revokedAtEpochSeconds` must fail verification with `RELEASE_SIGNER_REVOKED`.
+
+## Automated drill
+
+CI includes a compromise drill test:
+
+- `test/release-signing-compromise-drill.test.js`
+
+This test simulates:
+
+- old key revoked
+- new key added
+- release signed with old key after revocation fails
+- release signed with new key passes
+

package/docs/ops/SELF_SERVE_LAUNCH_AUTOMATION.md

@@ -0,0 +1,89 @@
+# Self-Serve Launch Automation (S197/S198)
+
+This runbook covers the self-serve launch automation surfaces:
+
+- onboarding email sequence automation,
+- referral funnel instrumentation,
+- benchmark artifact generation for launch reporting.
+
+## 1) Onboarding email sequence
+
+Magic Link now emits a milestone-based onboarding email sequence per tenant:
+
+- `welcome`
+- `sample_verified_nudge`
+- `first_settlement_completed`
+
+Implementation:
+
+- `services/magic-link/src/onboarding-email-sequence.js`
+- wired from `services/magic-link/src/server.js` on tenant create, onboarding events, and upload progress.
+
+Environment controls:
+
+```bash
+MAGIC_LINK_ONBOARDING_EMAIL_SEQUENCE_ENABLED=1
+MAGIC_LINK_ONBOARDING_EMAIL_DELIVERY_MODE=record   # record|log|smtp
+```
+
+Default behavior:
+
+- uses `smtp` when SMTP is configured,
+- falls back to `record` otherwise.
+
+Record mode writes deterministic outbox files:
+
+- `onboarding-email-outbox/<tenantId>/<stepKey>/*.json`
+- per-tenant state: `tenants/<tenantId>/onboarding_email_sequence.json`
+
+## 2) Referral loop instrumentation
+
+Referral loop signals are ingested through onboarding events:
+
+- `referral_link_shared`
+- `referral_signup`
+
+Endpoint:
+
+```bash
+POST /v1/tenants/{tenantId}/onboarding/events
+```
+
+Example payloads:
+
+```json
+{ "eventType": "referral_link_shared", "metadata": { "channel": "email", "campaign": "launch_v1" } }
+```
+
+```json
+{ "eventType": "referral_signup", "metadata": { "sourceTenantId": "tenant_a", "referredTenantId": "tenant_b" } }
+```
+
+Metrics exposure:
+
+- `GET /v1/tenants/{tenantId}/onboarding-metrics`
+- includes `referral.linkSharedCount`, `referral.signupCount`, `referral.conversionRatePct`.
+
+## 3) Launch benchmark artifact
+
+Build benchmark report from launch gate + throughput + incident rehearsal artifacts:
+
+```bash
+node scripts/ci/build-self-serve-benchmark-report.mjs
+```
+
+Output:
+
+- `artifacts/launch/self-serve-benchmark-report.json`
+
+Inputs (defaults):
+
+- `artifacts/gates/self-serve-launch-gate.json`
+- `artifacts/throughput/10x-drill-summary.json`
+- `artifacts/throughput/10x-incident-rehearsal-summary.json`
+
+NPM shortcut:
+
+```bash
+npm run test:ops:self-serve-benchmark
+```