settld 0.1.2 → 0.2.0

package/docs/ACCESS.md

@@ -0,0 +1,57 @@
+# Access (v0.3)
+
+Access is modeled as a first-class, **revocable**, **time-scoped** dependency of a job. Access secrets are never written to the event log; only references are.
+
+## Principles
+
+- **No secrets in logs**: the event stream stores `credentialRef` (e.g. `vault://...`), never door codes/passwords.
+- **Scoped and revocable**: access plans are time-bounded and can be revoked instantly.
+- **Execution is gated**: the system rejects execution start without an active access plan and access granted within the plan window.
+- **Revocation forces safe exit**: access revocation transitions the job to a safe-exit mode and rejects further “work” events.
+
+## Events
+
+### `ACCESS_PLAN_ISSUED` (server-signed)
+
+Payload shape (current prototype, strict):
+
+```json
+{
+  "jobId": "job_123",
+  "accessPlanId": "ap_456",
+  "method": "SMART_LOCK_CODE|BUILDING_CONCIERGE|ON_SITE_OWNER|DOCKED_IN_BUILDING",
+  "credentialRef": "vault://access/ap_456/v1",
+  "scope": { "areas": ["ENTRYWAY"], "noGo": ["BEDROOM_2"] },
+  "validFrom": "2026-01-26T18:00:00Z",
+  "validTo": "2026-01-26T22:00:00Z",
+  "revocable": true,
+  "requestedBy": "system|customer|ops"
+}
+```
+
+### `ACCESS_GRANTED` / `ACCESS_DENIED` (robot- or operator-signed)
+
+Payload includes the plan reference (no secrets):
+
+```json
+{ "jobId": "job_123", "accessPlanId": "ap_456", "method": "BUILDING_CONCIERGE" }
+```
+
+### `ACCESS_REVOKED` / `ACCESS_EXPIRED` (server-signed in v0.3)
+
+```json
+{ "jobId": "job_123", "accessPlanId": "ap_456", "requestedBy": "customer", "reason": "..." }
+```
+
+## Enforced invariants (v0.3)
+
+- `ACCESS_GRANTED`/`ACCESS_DENIED` are rejected unless:
+  - an `ACCESS_PLAN_ISSUED` exists, and
+  - the `accessPlanId` matches the current plan, and
+  - the event timestamp is within `[validFrom, validTo]`.
+- `EXECUTION_STARTED` is rejected unless:
+  - an access plan exists, and
+  - access is currently granted, and
+  - the event timestamp is within the plan window.
+- After `ACCESS_REVOKED`, the job moves to `ABORTING_SAFE_EXIT`, and “work” events are rejected.
+

package/docs/ADOPTION_CHECKLIST.md

@@ -0,0 +1,44 @@
+# Adoption checklist (design partner ready)
+
+Use this as an operational checklist to adopt Settld verification in CI with audit-grade evidence retention.
+
+## Verification posture
+
+- Decide strict vs non-strict (`docs/spec/STRICTNESS.md`).
+- Decide whether warnings gate builds (`--fail-on-warnings`, `docs/spec/WARNINGS.md`).
+- Decide required verification outputs to archive:
+  - Recommended: archive `VerifyCliOutput.v1` JSON + the bundle itself.
+
+## Trust anchors
+
+- Define who owns governance root keys (generation, storage, rotation).
+- Define how trust anchors are distributed to CI (secret store, repo file, env injection).
+- Define update process and emergency rotation response.
+
+See `docs/spec/TRUST_ANCHORS.md` and `docs/spec/TOOL_PROVENANCE.md`.
+
+## Key management + governance operations
+
+- Who is authorized to sign:
+  - bundle head attestations
+  - verification reports
+- Rotation and revocation procedures (who triggers, how fast, how communicated).
+- Decide whether timestamp proofs are required for historical acceptance.
+
+See `docs/spec/GovernancePolicy.v2.md` and `docs/spec/RevocationList.v1.md`.
+
+## Storage + retention
+
+- Where bundles live (artifact store) and retention period.
+- Whether verification happens on:
+  - the original produced bundle, or
+  - a downloaded bundle copy (must remain byte-identical).
+- Who can access archived bundles and verification receipts.
+
+## Release pinning + upgrades
+
+- Pin verifier version (SemVer) for CI stability.
+- Define upgrade cadence and rollback plan.
+
+See `docs/spec/VERSIONING.md` and `docs/RELEASING.md`.
+

package/docs/ALERTS.md

@@ -0,0 +1,198 @@
+# Alerts & Runbook (v1)
+
+This file defines a minimal “pilot-safe” alert pack and the exact first actions to take when something pages.
+
+Settld invariants still apply during incidents:
+- never accept an invalid chain
+- never duplicate external effects
+- never break ledger balance / month-close immutability
+
+## Metrics endpoints
+
+- `GET /metrics` emits Prometheus text.
+  - Requires an `ops_read` auth key and `x-proxy-tenant-id` header (recommended: a dedicated key for metrics scraping).
+- `GET /healthz` emits a quick JSON status (DB + backlog signals).
+- `GET /ops/status` emits a human-oriented status summary (requires `ops_read`).
+
+## High-signal alerts (recommended)
+
+### 1) Delivery DLQ nonzero (customer impact likely)
+
+**Trigger**
+- `delivery_dlq_pending_total_gauge > 0` for 5m
+
+**First actions**
+- Call `GET /ops/status` and inspect:
+  - `backlog.deliveriesFailed`
+  - `backlog.deliveryDlqTopDestinations`
+- List failed deliveries: `GET /ops/deliveries?state=failed&limit=200`
+- If it’s a transient downstream issue, requeue one and confirm it progresses:
+  - `POST /ops/deliveries/:id/requeue`
+- If a single destination is broken, fix downstream credentials/endpoint first (do not “mass requeue into a black hole”).
+
+### 2) Outbox backlog stuck (system falling behind)
+
+**Trigger**
+- `outbox_pending_gauge > 1000` for 10m
+
+**First actions**
+- Call `GET /ops/status` and inspect `backlog.outboxByKind` to see which topic is stuck.
+- Confirm worker progress in logs:
+  - outbox claim/start/end
+  - delivery retry/DLQ transitions
+- If deliveries are the bottleneck, check Delivery DLQ alert steps above.
+
+### 3) Ledger apply failures (finance correctness risk)
+
+**Trigger**
+- `increase(ledger_apply_fail_total[5m]) > 0`
+
+**First actions**
+- Treat as “stop-the-world” for finance exports until understood.
+- Inspect logs for `ledger.apply.*` around the failure and identify the entry/job IDs.
+- Verify DB invariants: ledger entries must net to zero; no double-application.
+
+### 4) Ingest rejects spiking (upstream breaking / hostile input)
+
+**Trigger**
+- `increase(ingest_rejected_total[5m]) > 50` (tune per pilot volume)
+
+**First actions**
+- Call `GET /ops/status` and inspect `reasons.topIngestRejected`.
+- Inspect DLQ: `GET /ops/dlq?type=ingest&limit=200`
+- If the rejects are signature/chain/time issues, fix upstream immediately (do not disable validation).
+
+### 5) Retention cleanup stale / failing (unbounded growth risk)
+
+**Trigger**
+- `time() - maintenance_last_success_unixtime{kind="retention_cleanup"} > 3600` (tune to your cadence)
+  - If you run cleanup every 300s, 3600s implies “missed many runs”.
+- `maintenance_last_run_ok_gauge{kind="retention_cleanup"} == 0` for 10m
+
+**First actions**
+- Check the latest retention audit record:
+  - `GET /ops/status` → `maintenance.retentionCleanup`
+  - or `GET /ops/audit?limit=50` and filter for `MAINTENANCE_RETENTION_RUN`
+- Run an audited manual cleanup (dry run first):
+  - `POST /ops/maintenance/retention/run` with `{ "dryRun": true }`
+  - then re-run with `{ "dryRun": false }` if counts look sane
+- If cleanup keeps failing, check DB health and recent migrations first (cleanup is intentionally bounded and should not take locks for long).
+
+### 6) Stripe replayable dead-letter backlog (billing drift risk)
+
+**Trigger**
+- `GET /ops/finance/billing/providers/stripe/reconcile/report?limit=200` returns:
+  - `replayableRejectedCount > 0` for 15m, or
+  - rapidly growing `rejectedReasonCounts.reconcile_apply_failed`.
+
+**First actions**
+- Snapshot report + candidate dead-letter events:
+  - `GET /ops/finance/billing/providers/stripe/reconcile/report?limit=200`
+  - `GET /ops/finance/billing/providers/stripe/dead-letter?limit=200`
+- Execute dry-run replay, then live replay if dry-run is clean:
+  - `POST /ops/finance/billing/providers/stripe/dead-letter/replay`
+- Validate post-replay counters and billing plan state.
+- Follow `docs/ops/BILLING_WEBHOOK_REPLAY.md` end-to-end and attach snapshots to incident notes.
+
+### 7) Replay mismatches detected (determinism break)
+
+**Trigger**
+- `replay_mismatch_gauge > 0` for 5m
+
+**First actions**
+- Treat as critical correctness incident.
+- Check `/ops/status` and `/ops/tool-calls/replay-evaluate` for affected agreement hashes.
+- Freeze rollout/cutover changes and investigate policy/version drift before resuming.
+
+### 8) Disputes over SLA / arbitration over SLA
+
+**Trigger**
+- `disputes_over_sla_gauge > 0` for 10m
+- `arbitration_over_sla_gauge > 0` for 10m
+
+**First actions**
+- Inspect `/ops/status` command center dispute section and case backlog.
+- Prioritize oldest open disputes and assign arbiter coverage immediately.
+- If backlog is systemic, scale operator staffing/worker capacity before requeueing traffic.
+
+### 9) Stuck holds (economic lock risk)
+
+**Trigger**
+- `settlement_holds_over_24h_gauge > 0` for 15m
+
+**First actions**
+- Inspect hold status via `/ops/tool-calls/holds`.
+- Correlate open disputes and challenge windows for affected agreement hashes.
+- If holds are blocked by missing verdicts, escalate arbitration path.
+
+### 10) Worker lag (delivery backlog)
+
+**Trigger**
+- `worker_deliveries_pending_total_gauge > 1000` for 10m
+
+**First actions**
+- Check `/ops/status` backlog and destination health.
+- Verify worker process uptime and claim/retry logs.
+- Scale worker replicas or reduce downstream failure rate before reprocessing.
+
+## Prometheus rule examples
+
+These are examples; tune thresholds for your pilot volume and SLOs.
+
+```yaml
+groups:
+  - name: settld.alerts
+    rules:
+      - alert: SettldDeliveryDLQNonzero
+        expr: delivery_dlq_pending_total_gauge > 0
+        for: 5m
+        labels: { severity: page }
+        annotations:
+          summary: "Settld deliveries in DLQ"
+          runbook: "docs/ALERTS.md#1-delivery-dlq-nonzero-customer-impact-likely"
+
+      - alert: SettldOutboxBacklogHigh
+        expr: outbox_pending_gauge > 1000
+        for: 10m
+        labels: { severity: page }
+        annotations:
+          summary: "Settld outbox backlog high"
+          runbook: "docs/ALERTS.md#2-outbox-backlog-stuck-system-falling-behind"
+
+      - alert: SettldLedgerApplyFailures
+        expr: increase(ledger_apply_fail_total[5m]) > 0
+        for: 0m
+        labels: { severity: page }
+        annotations:
+          summary: "Settld ledger apply failures detected"
+          runbook: "docs/ALERTS.md#3-ledger-apply-failures-finance-correctness-risk"
+
+      - alert: SettldIngestRejectSpike
+        expr: increase(ingest_rejected_total[5m]) > 50
+        for: 5m
+        labels: { severity: warn }
+        annotations:
+          summary: "Settld ingest rejects spiking"
+          runbook: "docs/ALERTS.md#4-ingest-rejects-spiking-upstream-breaking--hostile-input"
+
+      - alert: SettldMaintenanceStaleRetention
+        expr: time() - maintenance_last_success_unixtime{kind="retention_cleanup"} > 3600
+        for: 10m
+        labels: { severity: warn }
+        annotations:
+          summary: "Settld retention cleanup not succeeding"
+          runbook: "docs/ALERTS.md#5-retention-cleanup-stale--failing-unbounded-growth-risk"
+
+      - alert: SettldReplayMismatchDetected
+        expr: replay_mismatch_gauge > 0
+        for: 5m
+        labels: { severity: page }
+        annotations:
+          summary: "Replay mismatches detected"
+          runbook: "docs/ALERTS.md#7-replay-mismatches-detected-determinism-break"
+```
+
+## Notes on cardinality
+
+- `outbox_pending_gauge{kind=...}` is low-cardinality (bounded set of topics).
+- `delivery_dlq_pending_by_destination_gauge{destinationId=...}` only exposes the top 10 destinations by DLQ depth to stay alertable without exploding metric series.

package/docs/ARCHITECTURE.md

@@ -0,0 +1,69 @@
+# Settld Architecture (v0)
+
+Settld is a **trust fabric + runtime + ledger** for autonomous work.
+
+## Layers (logical)
+
+1. **Marketplace**: RFQs, quotes, booking, payments, scheduling.
+2. **Operations**: runtime health, dispatch, control loops, human/operator assist.
+3. **Skills**: packaging, certification, licensing, execution orchestration.
+4. **Trust**: telemetry black box, incident detection, claims, audits.
+
+Ship as a **modular monolith** initially with strict boundaries; split later.
+
+## Architectural spine: jobs + events
+
+- A **Job** is a state machine (the “source of truth” for what should happen next).
+- An **Event** is the audit trail (what did happen), emitted by:
+  - cloud services (quote created, booking confirmed),
+  - agent (entered space, checkpoint done),
+  - operator (assist start/end, action approvals),
+  - requester (approval granted/revoked, complaint filed).
+
+Invariants:
+
+- State transitions are explicit and validated.
+- Events are append-only.
+- Every settlement is balanced (sum of postings is zero).
+
+## Core components (eventual)
+
+### Settld Cloud
+
+- **Job Orchestrator**: validates and advances job state, emits job events.
+- **Dispatch Service**: matching + reservation + replanning.
+- **Ledger Service**: holds, escrow, settlement, refunds, chargebacks, splits.
+- **Trust Service**: evidence bundling, incident/claims workflow.
+- **Skill Registry**: signed bundles, certification tiers, distribution rules.
+
+### Settld Agent (on/near execution runtime)
+
+- Secure channel to cloud (mTLS + rotating certs).
+- Advertises capabilities/health.
+- Downloads/verifies signed skill bundles.
+- Executes job plans and emits telemetry/checkpoints.
+- **Local policy enforcement**: clamps cloud-requested actions to safety bounds.
+- Privacy enforcement (sensor gating, retention rules).
+
+### Operator Assist
+
+- Live streaming (WebRTC) + command channel.
+- Structured interventions (approve grasp, set nav target, select object).
+- All operator actions are logged into the black box.
+
+## Data & storage (eventual)
+
+- Transactional truth: Postgres (jobs, bookings, entities, ledger).
+- Cache/locks: Redis (reservations, idempotency, rate limits).
+- Event bus: Kafka/PubSub (job events, telemetry envelopes).
+- Evidence: object storage (S3/GCS).
+- Telemetry analytics: log pipeline + time-series for what is queried.
+
+## Security posture (MVP principles)
+
+- Device identity and attestation.
+- Signed artifacts (skills) and signed/hashed logs (black box).
+- Principle of least privilege across:
+  - access plans (time-bounded, revocable),
+  - operator consoles (scoped actions),
+  - skills (capability-limited).

package/docs/ARCHITECTURE_FOUNDER_GUIDE.md

@@ -0,0 +1,284 @@
+# Settld Founder Architecture Guide
+
+Status date: February 12, 2026
+
+## Why this document exists
+
+This is the founder-level map of what Settld is actually building, what is already true in code, and what is still planned.  
+It is intentionally opinionated: if a claim is not enforced by code/tests/conformance, it is not treated as shipped truth.
+
+---
+
+## 1) What Settld is
+
+Settld is a verifiable execution-and-settlement infrastructure for delegated agent work.
+
+The product has two surfaces that share one truth model:
+
+1. Open protocol and verifier toolchain (portable, offline-verifiable)
+2. Hosted workflow/controller product (Magic Link) that uses the same verification model
+
+Core principle: hosted UX is never the only judge.  
+Anything shown in hosted flows must be reproducible offline with the open verifier plus explicit trust anchors.
+
+Primary references:
+
+- `docs/OVERVIEW.md`
+- `docs/spec/README.md`
+- `docs/spec/INVARIANTS.md`
+- `services/magic-link/README.md`
+
+---
+
+## 2) Product surfaces
+
+## Protocol surface (open)
+
+- Bundle formats + manifests + attestations + verification reports
+- Deterministic verification semantics and stable warning/error codes
+- Conformance vectors to prevent verifier drift across implementations
+
+Key files:
+
+- `packages/artifact-verify/bin/settld-verify.js`
+- `packages/artifact-produce/bin/settld-produce.js`
+- `conformance/v1/README.md`
+- `docs/spec/CANONICAL_JSON.md`
+- `docs/spec/STRICTNESS.md`
+
+## Hosted surface (commercial)
+
+- Upload + verification workflow (strict/compat/auto)
+- Inbox/reporting/approval/hold flows
+- Webhooks/integrations/billing usage and exports
+
+Key files:
+
+- `services/magic-link/src/server.js`
+- `services/magic-link/src/tenant-settings.js`
+- `services/magic-link/README.md`
+
+## Economic kernel (shared truth engine)
+
+- Event-sourced job lifecycle
+- Deterministic replay
+- Double-entry ledger as accounting truth
+
+Key files:
+
+- `src/core/job-state-machine.js`
+- `src/core/job-reducer.js`
+- `src/core/ledger.js`
+- `src/core/escrow-ledger.js`
+- `docs/JOB_STATE_MACHINE.md`
+- `docs/LEDGER.md`
+
+---
+
+## 3) What is TRUE today (shipped truth)
+
+This section summarizes current shipped truth based on repo state and audit evidence.
+
+## 3.1 Dispute/holdback determinism is enforced
+
+- Signed dispute-open envelopes are required for non-admin opens.
+- Envelope/case IDs are deterministic from agreement hash.
+- Artifact ID is bound to envelope ID and validated.
+- Holdback auto-release is frozen while arbitration is open.
+
+Evidence:
+
+- `src/core/dispute-open-envelope.js`
+- `src/api/app.js`
+- `test/dispute-open-envelope-schemas.test.js`
+- `test/api-e2e-tool-call-holdback-arbitration.test.js`
+- `planning/kernel-v0-truth-audit.md`
+
+## 3.2 Kernel replay and closepack verification flows exist
+
+- Tool-call replay evaluation exists in API paths.
+- Closepack export and offline verify are wired and conformance-gated.
+
+Evidence:
+
+- `src/api/app.js`
+- `scripts/closepack/lib.mjs`
+- `conformance/kernel-v0/run.mjs`
+
+## 3.3 Open protocol and verifier posture is strong
+
+- Large, explicit spec surface in `docs/spec/**`
+- Deterministic verifier CLI and conformance vectors in `conformance/v1/**`
+- Security hardening for archive ingestion paths with dedicated tests
+
+Evidence:
+
+- `docs/spec/INVARIANTS.md`
+- `packages/artifact-verify/src/safe-unzip.js`
+- `test/zip-security.test.js`
+- `conformance/v1/README.md`
+
+## 3.4 Billing catalog alignment is now implemented in Magic Link runtime
+
+- Runtime plans now map to `free|builder|growth|enterprise`
+- Legacy `scale` is normalized to `enterprise` for compatibility
+- Hosted pricing/upgrade paths are aligned to the same tier set
+
+Evidence:
+
+- `services/magic-link/src/tenant-settings.js`
+- `services/magic-link/src/server.js`
+- `test/magic-link-service.test.js`
+
+---
+
+## 4) What is NOT TRUE yet (gaps to close)
+
+These are strategic blockers still marked as not shipped end-to-end.
+
+## 4.1 Hosted baseline is not fully productized
+
+Status: FALSE (per truth audit)
+
+Gap theme:
+
+- Staging/prod separation, durable worker model, quotas/rate limits, backup/restore drills, hard evidence of operational readiness
+
+Evidence anchor:
+
+- `planning/kernel-v0-truth-audit.md`
+- `docs/ops/HOSTED_BASELINE_R2.md`
+
+## 4.2 Real-money settlement alpha is not shipped
+
+Status: FALSE (per truth audit)
+
+Gap theme:
+
+- Stripe Connect mapping + webhook ingestion + reconciliation + chargeback/refund operational policy tied to kernel IDs
+
+Evidence anchor:
+
+- `planning/kernel-v0-truth-audit.md`
+- `docs/ops/PAYMENTS_ALPHA_R5.md`
+
+## 4.3 Exact tarball `npx --package ./settld-<version>.tgz` CI smoke is partial
+
+Status: PARTIAL (per truth audit)
+
+Gap theme:
+
+- CI covers related smoke paths but not the exact documented local tarball invocation path
+
+Evidence anchor:
+
+- `planning/kernel-v0-truth-audit.md`
+- `scripts/ci/cli-pack-smoke.mjs`
+- `.github/workflows/release.yml`
+
+## 4.4 Dashboard remains primarily fixture-driven
+
+Gap theme:
+
+- The dashboard experience is still largely driven by demo fixtures and static exports; live API streaming console remains roadmap work
+
+Evidence anchor:
+
+- `dashboard/src/hooks/useDemoData.js`
+- `dashboard/src/DemoApp.jsx`
+
+---
+
+## 5) Architecture map (how the code is laid out)
+
+## Ring A: Normative protocol layer
+
+Defines what artifacts are and how they verify.
+
+- `docs/spec/**`
+- `docs/spec/schemas/**`
+- `conformance/v1/**`
+
+## Ring B: Core domain kernel
+
+Pure/domain-centric logic for state transitions, settlement semantics, and ledger invariants.
+
+- `src/core/**`
+
+## Ring C: API + persistence truth boundary
+
+Operational truth implementation (API orchestration, store abstraction, Postgres durability, workers/outbox).
+
+- `src/api/**`
+- `src/db/**`
+
+## Ring D: Productized hosted workflows and integrations
+
+Buyer/operator workflow UX and automation around the same verification semantics.
+
+- `services/magic-link/**`
+- `packages/*` (SDKs, CLI tooling)
+
+---
+
+## 6) Data and trust flow (end-to-end)
+
+1. Work happens and emits events.
+2. Events are reduced into deterministic state and ledger consequences.
+3. Artifacts are produced as bundles with manifest+hash commitments.
+4. Verifier checks integrity, signatures, invariants, and policy/trust anchors.
+5. Hosted workflow can display, route decisions, and trigger automations.
+6. Any external party can re-run verification offline against exported artifacts.
+
+The core design win is that commercial workflow convenience does not replace verification truth.
+
+---
+
+## 7) Founder operating metrics and checkpoints
+
+## North-star metric
+
+Monthly Verified Settled Value (MVSV)
+
+Why it matters:
+
+- Captures whether value is being verified and settled, not just “API called”
+- Compounds with volume-based monetization
+
+## Gate checkpoints that matter most now
+
+1. Hosted baseline gate turns TRUE (ops evidence, not docs-only)
+2. Real-money alpha gate turns TRUE (first design partner cash flow)
+3. CI tarball smoke gap closes (distribution claim fully evidenced)
+
+Reference:
+
+- `planning/kernel-v0-truth-audit.md`
+
+---
+
+## 8) Practical reading order for new founder engineers
+
+1. `docs/OVERVIEW.md`
+2. `planning/kernel-v0-truth-audit.md`
+3. `docs/spec/INVARIANTS.md`
+4. `src/core/job-reducer.js`
+5. `src/core/escrow-ledger.js`
+6. `packages/artifact-verify/src/invoice-bundle.js`
+7. `conformance/v1/README.md`
+8. `services/magic-link/README.md`
+9. `services/magic-link/src/server.js`
+10. `test/magic-link-service.test.js`
+
+---
+
+## 9) Founder summary in one page
+
+- Settld is building verifiable economic finality for agent work, not just another workflow dashboard.
+- The strongest moat already shipped is protocol determinism + offline verification + conformance.
+- The biggest business-risk gaps are operational/commercial, not core protocol correctness:
+  - hosted baseline hardening
+  - real-money rail deployment
+- Product messaging and UX should keep emphasizing one non-negotiable differentiator:
+  - “You can verify settlement outcomes without trusting our hosted app.”
+