settld 0.1.2 → 0.2.0

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
+```

package/docs/ops/THROUGHPUT_DRILL_10X.md

@@ -0,0 +1,48 @@
+# Throughput Drill 10x Runbook
+
+Objective: execute `STLD-T177` as an auditable gate artifact, not a one-off benchmark.
+
+## Command
+
+```bash
+BASE_URL=http://127.0.0.1:3000 \
+OPS_TOKEN=ops_ci \
+TENANTS=3 \
+ROBOTS_PER_TENANT=3 \
+BASELINE_JOBS_PER_MIN_PER_TENANT=10 \
+THROUGHPUT_MULTIPLIER=10 \
+DURATION=120s \
+TARGET_P95_MS=5000 \
+MAX_FAILURE_RATE=0.05 \
+node scripts/ci/run-10x-throughput-drill.mjs
+
+BASE_URL=http://127.0.0.1:3000 \
+OPS_TOKEN=ops_ci \
+node scripts/ci/run-10x-throughput-incident-rehearsal.mjs
+```
+
+If local `k6` is not installed, the runner automatically falls back to `docker` (`grafana/k6:0.48.0`).
+Set `ALLOW_DOCKER_K6_FALLBACK=0` to require native `k6`.
+
+## Outputs
+
+- K6 summary: `artifacts/throughput/10x-drill-k6-summary.json`
+- Gate report: `artifacts/throughput/10x-drill-summary.json`
+- Incident rehearsal report: `artifacts/throughput/10x-incident-rehearsal-summary.json`
+
+## Gate conditions
+
+- k6 exits with status `0`
+- `http_req_duration p(95)` <= `TARGET_P95_MS`
+- `http_req_failed rate` <= `MAX_FAILURE_RATE`
+- ingest rejection rate <= `MAX_INGEST_REJECTED_PER_MIN`
+
+## Incident rehearsal checklist
+
+- Run `node scripts/ci/run-10x-throughput-incident-rehearsal.mjs` immediately after the load drill.
+- Confirm `artifacts/throughput/10x-incident-rehearsal-summary.json` has `verdict.ok=true`.
+- Verify rehearsal checks are green:
+  - degraded-mode signal was emitted,
+  - rollback returned active policy to stable,
+  - communications markers were captured in `/ops/audit`,
+  - command-center post-rollback breach count is zero.

package/docs/ops/TRUST_CONFIG_WIZARD.md

@@ -0,0 +1,60 @@
+# Trust Config Wizard
+
+Use this when you want to create an SLA policy config from a template.
+
+## Fastest path for onboarding
+
+If you want a ready starter policy during host setup, run:
+
+```bash
+settld setup --yes --mode manual --host codex --base-url http://127.0.0.1:3000 --tenant-id tenant_default --api-key sk_live_xxx.yyy --profile-id engineering-spend --smoke
+```
+
+This sets up host MCP config and applies a starter policy profile in one run.
+
+## New policy wizard flow (template-based)
+
+1. List templates:
+
+```bash
+npm run trust:wizard -- list --format text
+```
+
+2. Preview one template:
+
+```bash
+npm run trust:wizard -- show --template delivery_standard_v1 --format text
+```
+
+3. Render a policy config file:
+
+```bash
+npm run trust:wizard -- render --template delivery_standard_v1 --overrides-json '{"metrics":{"targetCompletionMinutes":60}}' --out ./policy.delivery.json --format json
+```
+
+4. Validate the same overrides:
+
+```bash
+npm run trust:wizard -- validate --template delivery_standard_v1 --overrides-json '{"metrics":{"targetCompletionMinutes":60}}' --format json
+```
+
+Supported commands:
+
+- `list [--vertical delivery|security] [--format json|text]`
+- `show --template <templateId> [--format json|text]`
+- `render --template <templateId> [--overrides-json <json>] [--out <path>] [--format json|text]`
+- `validate --template <templateId> [--overrides-json <json>] [--format json|text]`
+
+## API endpoint
+
+- `GET /ops/sla-templates`
+  - Scope: `ops_read`
+  - Optional query: `vertical=delivery|security`
+  - Response: `SlaPolicyTemplateCatalog.v1`
+
+Example:
+
+```bash
+curl -sS "http://localhost:3000/ops/sla-templates?vertical=security" \
+  -H "x-proxy-ops-token: <ops_read_token>" | jq
+```

package/docs/ops/X402_PILOT_WEEKLY_METRICS.md

@@ -0,0 +1,76 @@
+# X402 Pilot Weekly Reliability Metrics
+
+Use this report to publish weekly reliability numbers for the Circle-backed paid tool pilot.
+
+The report is artifact-driven and summarizes paid MCP/x402 runs under `artifacts/mcp-paid-exa`.
+
+## Why this exists
+
+Before broad provider expansion, the pilot must prove:
+
+- reserve behavior is stable,
+- token and provider signature verification are stable,
+- settlement execution is stable.
+
+This command produces a deterministic JSON report you can commit or attach to release notes.
+
+## Run
+
+```bash
+npm run ops:x402:pilot:weekly-report -- \
+  --artifact-root artifacts/mcp-paid-exa \
+  --days 7 \
+  --out artifacts/ops/x402-pilot-reliability-report.json
+```
+
+Optional reliability gates:
+
+```bash
+npm run ops:x402:pilot:weekly-report -- \
+  --artifact-root artifacts/mcp-paid-exa \
+  --days 7 \
+  --max-reserve-fail-rate 0.10 \
+  --max-token-verify-fail-rate 0.01 \
+  --max-provider-sig-fail-rate 0.01 \
+  --min-settlement-success-rate 0.98
+```
+
+If threshold gates are supplied, command exit code is non-zero when any gate fails.
+
+## Output schema
+
+`X402PilotReliabilityReport.v1` includes:
+
+- `runCounts`
+  - `runsInWindow`
+  - `infraBootFailures`
+  - `toolCallAttempts`
+  - `successfulPaidCalls`
+- `metrics`
+  - `timeToFirstPaidCallMs`
+  - `reserveFailRate`
+  - `tokenVerifyFailRate`
+  - `providerSigFailRate`
+  - `settlementSuccessRate`
+  - `replayDuplicateRate`
+- `samples`
+  - run ids for reserve/token/signature/settlement failures
+- `verdict`
+  - threshold check results when thresholds are passed
+
+## Metric notes
+
+- `reserveFailRate` is inferred from attempted runs with `gateway_error` today.
+- Infrastructure boot failures are excluded from economic reliability denominators.
+- `replayDuplicateRate` uses provider replay counters emitted by paid demo artifacts (`provider-replay-probe.json` or `summary.replayCounters`).
+
+## Recommended weekly publish set
+
+- `timeToFirstPaidCallMs`
+- `reserveFailRate`
+- `tokenVerifyFailRate`
+- `providerSigFailRate`
+- `settlementSuccessRate`
+- `replayDuplicateRate`
+
+Keep provider expansion gated on these metrics, not on raw demo volume.

package/docs/ops/tool-call-disputes-holdback.md

@@ -0,0 +1,52 @@
+# Tool-Call Disputes and Holdback (Ops Runbook)
+
+## When To Use Party Open vs Ops Override
+
+- Use **party open** when:
+  - payer/payee is within the hold challenge window
+  - the dispute is expected and can be resolved by normal arbitration timelines
+
+- Use **ops/admin override** when:
+  - the challenge window is closed but funds are still held (exception path)
+  - an incorrect hold configuration needs remediation
+  - you need to open a case for forensic/incident reasons
+
+Ops override requires `ops_write` and must include an explicit override reason in the case metadata.
+
+## How Holds Get “Stuck”
+
+A hold can remain in `held` if:
+
+- an arbitration case exists for the hold and the case `status` is not `closed`
+- the verdict has been issued but the adjustment was not applied (should be rare; indicates an idempotency/DB failure)
+- escrow balances are inconsistent (wallet has insufficient escrow locked to complete release/refund)
+
+## Debug Checklist
+
+1. Identify the `holdHash`:
+   - from the hold record (FundingHold.v1)
+   - or from the arbitration case metadata (`metadata.holdHash`)
+2. List tool-call arbitration cases for the agreement:
+   - `GET /tool-calls/arbitration/cases?agreementHash=...`
+3. Verify the case metadata:
+   - `caseType: "tool_call"`
+   - `agreementHash`, `receiptHash`, `holdHash` are present and 64-hex sha256
+4. If the case is not closed, the auto-release tick will skip the hold.
+
+## Maintenance Tick
+
+The tool-call holdback maintenance tick:
+
+- will **not** auto-release holds referenced by any non-closed tool-call arbitration case
+- will skip holds whose challenge window has not yet ended
+- operates on held escrow funds only
+
+Endpoint:
+
+- `POST /ops/maintenance/tool-call-holdback/run`
+
+Suggested alerting:
+
+- Alert on `tool_call_holdback_auto_release_skipped_total{reason="arbitration_case_open"}` growth without a corresponding decrease in open case count.
+- Alert on holds blocked beyond an SLA threshold (derive from hold `createdAt` and current time).
+

package/docs/pilot-kit/PILOT_PACKAGE_SCORECARD_X402.md

@@ -0,0 +1,46 @@
+# Pilot Package + Success Scorecard (x402 Wedge)
+
+This defines the default pilot offer and measurable success gates for Settld x402 deployments.
+
+## 1. Pilot Package
+
+- Scope: 1 paid tool workflow, 1 buyer, 1 provider, 1 tenant.
+- Duration: 4-6 weeks.
+- Success proof: deterministic receipts + offline verification + export for finance.
+- Out of scope: broad marketplace rollout, unrestricted side-effect tools.
+
+## 2. Delivery Timeline
+
+1. Week 0: scope lock, baseline capture, env + keys provisioned.
+2. Week 1: first paid call in production-like flow (`402 -> retry -> verify`).
+3. Week 2-3: volume ramp + policy tuning (caps, allowlists, dispute windows).
+4. Week 4-6: KPI review, case-study artifacts, expansion decision.
+
+## 3. Scorecard (Baseline + Target)
+
+| Metric | Baseline (before Settld) | Target (pilot) | Measurement |
+|---|---:|---:|---|
+| Integration time to first paid call | > 2 days | < 1 afternoon | Start-to-first successful settled paid call |
+| Auto-resolve rate (%) | < 40% | >= 80% | `released / total verified` for in-scope runs |
+| Dispute rate (%) | > 10% | <= 5% | `disputed / settled` over pilot window |
+| Time-to-settle (p95) | > 24h | < 15m | verification-to-settlement latency |
+
+## 4. Required Evidence Artifacts
+
+- x402 gate trace (`gateId`, authorization ref, reserve id where applicable)
+- Decision + settlement binding hashes
+- Receipt export for pilot window
+- Offline verifier output sample on exported receipts
+- Weekly reliability report (`reserveFailRate`, `providerSigFailRate`, `settlementSuccessRate`)
+
+## 5. Expansion Triggers
+
+- Two or more teams request onboarding.
+- Finance requests recurring automated exports.
+- Scorecard targets met for two consecutive weekly checkpoints.
+
+## 6. No-Go / Re-scope Conditions
+
+- Integration time target misses twice.
+- Dispute rate trend worsens versus baseline.
+- Settlement reliability below threshold for two consecutive checkpoints.

package/docs/pilot-kit/README.md

@@ -0,0 +1,29 @@
+# Pilot Kit (Verify Cloud / Magic Link)
+
+This folder is the “send to prospects” kit for running a paid pilot:
+
+- Buyer materials (what the page means, what to download, how to re-verify offline)
+- Security posture summary (what we harden against)
+- Integration starting point (webhooks)
+- Simple ROI / billing templates
+
+## Recommended pilot flow
+
+1. Operator produces an `InvoiceBundle.v1` and uploads it to Verify Cloud (Magic Link).
+2. Buyer receives the link, reviews Green/Amber/Red, and (optionally) records **Approve/Hold** on the page.
+3. Buyer downloads the audit packet for archiving (bundle ZIP + deterministic JSON outputs).
+4. Operator consumes the webhook event to drive their internal workflow.
+
+## Contents
+
+- `buyer-one-pager.md` — what the buyer sees and what to do.
+- `buyer-email.txt` — copy/paste email template for sending links.
+- `offline-verify.md` — how a buyer/auditor re-verifies locally.
+- `security-summary.md` — zip and bundle hardening posture.
+- `security-qa.md` — short procurement/security questionnaire answers.
+- `architecture-one-pager.md` — deployment and data flow overview for security reviewers.
+- `procurement-one-pager.md` — procurement-facing overview (adoption + security posture).
+- `rfp-clause.md` — draft procurement / RFP language.
+- `roi-calculator-template.csv` — simple template for pilot ROI tracking.
+- `gtm-pilot-playbook.md` — outreach templates, pilot KPI gates, and case-study format.
+- `PILOT_PACKAGE_SCORECARD_X402.md` — default x402 pilot package, baseline/target scorecard, and expansion triggers.

package/docs/pilot-kit/architecture-one-pager.md

@@ -0,0 +1,48 @@
+# Verify Cloud (Magic Link) — Architecture one-pager
+
+This document describes the hosted verification service used in pilots (“Verify Cloud”, implemented by the Magic Link service).
+
+## Data flow (high level)
+
+1. Vendor uploads a Settld bundle ZIP (e.g. `InvoiceBundle.v1` / `ClosePack.v1`) using a vendor-scoped ingest key.
+2. Verify Cloud stores the ZIP and runs deterministic verification in a budgeted worker.
+3. Verify Cloud writes deterministic outputs + a redacted render model.
+4. Buyer views a hosted report link and/or downloads exports (audit packet, CSV, support bundle).
+5. (Optional) webhooks deliver verification status events.
+
+## Components
+
+- **HTTP handlers**
+  - Vendor ingest: `POST /v1/ingest/:tenantId` (Bearer ingest key)
+  - Admin upload: `POST /v1/upload` (admin `x-api-key`)
+  - Hosted report/downloads: `GET /r/:token` and `GET /r/:token/<artifact>`
+  - Exports: audit packet, support bundle, security packet, CSV
+- **Verification worker**
+  - Safe unzip with explicit budgets (rejects zip-slip/symlinks/duplicates/encrypted entries/zip bombs)
+  - Deterministic verification producing `VerifyCliOutput.v1`
+- **Storage (filesystem under `MAGIC_LINK_DATA_DIR`)**
+  - Run blobs: bundle zip, verifier output, redacted summaries, PDFs, receipts, ClosePack surfaces
+  - Minimal immutable run record: `runs/<tenant>/<token>.json` (metadata-only)
+  - Audit/usage logs (JSONL) for accounting and operations
+- **Maintenance**
+  - Retention sweeper deletes heavy artifacts after effective retention windows
+
+## Trust and integrity model
+
+- Buyers supply governance trust roots and pricing signer keys out-of-band.
+- Verification can run in strict or compat mode depending on policy and configured trust.
+- Offline verifiability: the buyer can archive the bundle ZIP and deterministically re-verify it later without access to vendor systems.
+
+## Access control model
+
+- Admin API: `x-api-key` (`MAGIC_LINK_API_KEY`)
+- Vendor uploads: ingest keys (upload-only)
+- Buyer sessions (optional): email OTP allowlist + RBAC roles (`viewer|approver|admin`)
+- Decision capture (optional): email OTP gating for approve/hold
+
+## Operational exports
+
+- **Audit packet**: archive-friendly, deterministic
+- **Support bundle**: time-bounded; metadata-first; redacted settings snapshot; no raw bundles by default
+- **Security & controls packet**: threat model + budgets + retention/redaction manifests + checksums
+

package/docs/pilot-kit/buyer-email.txt

@@ -0,0 +1,19 @@
+Subject: Verified invoice link (evidence-backed)
+
+Hi,
+
+Here is your verified invoice link:
+<PASTE_MAGIC_LINK_HERE>
+
+This link provides:
+- Green/Amber/Red verification status
+- Invoice totals + line item summary
+- Stable error/warning codes when something fails
+- Downloads for audit/offline replay (bundle ZIP + deterministic verification JSON + audit packet)
+- Optional Approve/Hold decision capture with exportable record
+
+If you need to re-verify offline, download the bundle ZIP from the page and run your verifier under your trust policy.
+
+Thanks,
+<YOUR_NAME>
+

package/docs/pilot-kit/buyer-one-pager.md

@@ -0,0 +1,31 @@
+# Settld Verified Invoice (Buyer one-pager)
+
+This invoice link is backed by a **cryptographically verifiable bundle** (an `InvoiceBundle.v1`) that can be archived and re-verified later, offline.
+
+## What you see on the page
+
+- **Green**: Verified with no warnings.
+- **Amber**: Verified, but warnings are present (common early: governance trust anchors not configured for strict verification).
+- **Red**: Verification failed.
+
+## What you can download
+
+- **Bundle ZIP**: the exact artifact that was verified (archive this for audit).
+- **Verification JSON** (`VerifyCliOutput.v1`): deterministic, machine-readable result (codes + hashes).
+- **Producer receipt** (if present): `verify/verification_report.json` from inside the bundle (producer-signed).
+- **Audit packet ZIP**: bundle ZIP + hosted verification JSON + any embedded receipt + PDF summary + decision record.
+- **PDF summary**: non-normative human summary for compatibility (not the source of truth).
+
+## Approve / Hold
+
+The page can record a simple **Approve / Hold** decision with a name + email + optional reason.
+
+This decision record is a **service record** (non-normative) and can be exported as `decision_record_v0.json`.
+
+## Offline re-verification (recommended for audit)
+
+1. Download the **Bundle ZIP**.
+2. Verify locally using `settld-verify` (or another conforming verifier) under your trust policy.
+
+See `offline-verify.md`.
+