settld 0.1.2 → 0.2.0

package/docs/plans/2026-02-20-trust-os-v1-jira-backlog.md

@@ -0,0 +1,348 @@
+# Trust OS v1 (Jira-Ready Backlog)
+
+Date: 2026-02-20
+Owner: CEO / Product / Platform
+Release Name: `Trust OS v1`
+Release Objective: Ship a production-grade, rail-agnostic inter-agent trust kernel with deterministic policy enforcement, dispute/reversal handling, auditable receipts, and operator controls.
+
+## Scope Boundaries (v1)
+
+In scope:
+- Runtime decisions: `allow`, `challenge`, `deny`, `escalate`.
+- Request binding, policy hash pinning, deterministic evidence/receipt export.
+- Dispute lifecycle + arbitration verdict + automatic settlement/reversal outcome.
+- Operator inbox (approval/escalation controls).
+- One hardened rail adapter path.
+- Three starter vertical profiles.
+
+Out of scope:
+- Policy marketplace and monetization.
+- Full open discovery network.
+- Building a new wallet rail.
+
+## Program Milestones
+
+- Milestone M1 (Sprint 1): Enforcement core + request binding + receipt schema freeze.
+- Milestone M2 (Sprint 2): Dispute/reversal runtime + operator inbox MVP.
+- Milestone M3 (Sprint 3): Rail adapter hardening + profile system + release gate.
+
+## Epics
+
+- `STLD-E2401` Policy Runtime Enforcement
+- `STLD-E2402` Execution Binding + Evidence + Receipts
+- `STLD-E2403` Dispute Court + Reversal Engine
+- `STLD-E2404` Operator Inbox + Controls
+- `STLD-E2405` Rail Adapter Hardening
+- `STLD-E2406` Vertical Policy Profiles
+- `STLD-E2407` QA, Conformance, and Release Gates
+
+## Jira Ticket Backlog
+
+### Epic `STLD-E2401` Policy Runtime Enforcement
+
+#### `STLD-T2401`
+- Type: Story
+- Priority: P0
+- Summary: Implement canonical runtime policy decision point (`allow/challenge/deny/escalate`) for all paid action paths.
+- Owner: Backend Platform
+- Estimate: 5d
+- Dependencies: None
+- Acceptance Criteria:
+  - Every paid action path calls policy runtime before execution.
+  - Decision output includes `decision`, `reasonCode`, `policyHash`, `policyVersion`, `decisionId`.
+  - Deterministic decision output for same input and policy version.
+
+#### `STLD-T2402`
+- Type: Story
+- Priority: P0
+- Summary: Add stable reason code registry and API surface for denied/challenged/escalated actions.
+- Owner: Backend Platform
+- Estimate: 3d
+- Dependencies: `STLD-T2401`
+- Acceptance Criteria:
+  - Reason codes are schema-validated and documented.
+  - API responses expose reason code and remediation hints.
+  - CLI/SDK map reason codes consistently.
+
+#### `STLD-T2403`
+- Type: Story
+- Priority: P0
+- Summary: Enforce policy evaluation at MCP entry points and bridge paths.
+- Owner: MCP / Integrations
+- Estimate: 3d
+- Dependencies: `STLD-T2401`
+- Acceptance Criteria:
+  - MCP tool calls cannot bypass policy runtime.
+  - MCP responses return policy decision metadata.
+  - Integration tests cover allowed/challenged/denied flows.
+
+#### `STLD-T2404`
+- Type: Task
+- Priority: P1
+- Summary: Add policy decision metrics and latency SLO instrumentation.
+- Owner: DevOps / Observability
+- Estimate: 2d
+- Dependencies: `STLD-T2401`
+- Acceptance Criteria:
+  - Metrics emitted: decision count by type/reason, eval latency p50/p95.
+  - Dashboard and alert thresholds configured.
+
+### Epic `STLD-E2402` Execution Binding + Evidence + Receipts
+
+#### `STLD-T2410`
+- Type: Story
+- Priority: P0
+- Summary: Enforce request binding between authorization token and canonical request fingerprint.
+- Owner: Backend Platform
+- Estimate: 4d
+- Dependencies: `STLD-T2401`
+- Acceptance Criteria:
+  - Request mutation/replay attempts fail with deterministic error code.
+  - Fingerprint algorithm is stable and versioned.
+  - Test vectors added for strict and side-effecting modes.
+
+#### `STLD-T2411`
+- Type: Story
+- Priority: P0
+- Summary: Bind policy hash/version and request hash into settlement decision records.
+- Owner: Backend Platform
+- Estimate: 2d
+- Dependencies: `STLD-T2410`
+- Acceptance Criteria:
+  - Decision records include policy/version/request binding fields.
+  - Offline verifier validates these bindings.
+
+#### `STLD-T2412`
+- Type: Story
+- Priority: P0
+- Summary: Ship `ReceiptBundle.v1` export with deterministic manifest and verification output.
+- Owner: Protocol / Backend
+- Estimate: 4d
+- Dependencies: `STLD-T2411`
+- Acceptance Criteria:
+  - Receipt bundle includes decision, settlement, and verification artifacts.
+  - Bundle verifies offline with strict mode.
+  - Repeat export produces identical canonical hashes.
+
+#### `STLD-T2413`
+- Type: Task
+- Priority: P1
+- Summary: Add SDK helpers for receipt retrieval/export across JS and Python.
+- Owner: SDK
+- Estimate: 3d
+- Dependencies: `STLD-T2412`
+- Acceptance Criteria:
+  - JS and Python SDK expose receipt export APIs.
+  - SDK smoke tests cover end-to-end retrieval and verification.
+
+### Epic `STLD-E2403` Dispute Court + Reversal Engine
+
+#### `STLD-T2420`
+- Type: Story
+- Priority: P0
+- Summary: Implement dispute case state machine (`opened`, `evidence_collected`, `under_review`, `verdict_issued`, `closed`).
+- Owner: Backend Platform
+- Estimate: 4d
+- Dependencies: `STLD-T2411`
+- Acceptance Criteria:
+  - State transitions are deterministic and idempotent.
+  - Invalid transitions are blocked with stable error codes.
+  - Case timeline is append-only and signed.
+
+#### `STLD-T2421`
+- Type: Story
+- Priority: P0
+- Summary: Implement verdict application pipeline to trigger automatic release/refund/reversal outcomes.
+- Owner: Backend Platform
+- Estimate: 4d
+- Dependencies: `STLD-T2420`
+- Acceptance Criteria:
+  - Verdict maps to deterministic financial outcome.
+  - Reversal entries are balanced and idempotent.
+  - Duplicate verdict processing does not double-settle.
+
+#### `STLD-T2422`
+- Type: Story
+- Priority: P0
+- Summary: Add dispute APIs and SDK wrappers for open/attach evidence/issue verdict.
+- Owner: API + SDK
+- Estimate: 3d
+- Dependencies: `STLD-T2420`
+- Acceptance Criteria:
+  - APIs exposed with authz enforcement.
+  - SDK wrappers for JS/Python and MCP tool surface.
+  - Contract tests cover happy and failure cases.
+
+#### `STLD-T2423`
+- Type: Task
+- Priority: P1
+- Summary: Add dispute SLA timers and escalation triggers.
+- Owner: Backend Platform
+- Estimate: 2d
+- Dependencies: `STLD-T2420`
+- Acceptance Criteria:
+  - Time-window breaches emit escalation events.
+  - Alerts and dashboards for aging disputes.
+
+### Epic `STLD-E2404` Operator Inbox + Controls
+
+#### `STLD-T2430`
+- Type: Story
+- Priority: P0
+- Summary: Build operator inbox page for challenged/escalated actions with approve/deny actions.
+- Owner: Frontend
+- Estimate: 5d
+- Dependencies: `STLD-T2401`, `STLD-T2422`
+- Acceptance Criteria:
+  - Operators can view pending items with policy context and evidence refs.
+  - Approve/deny writes signed operator action events.
+  - Pagination/filtering by tenant and severity.
+
+#### `STLD-T2431`
+- Type: Story
+- Priority: P0
+- Summary: Implement emergency controls: pause agent, quarantine, revoke delegation, kill switch.
+- Owner: Backend + Frontend
+- Estimate: 4d
+- Dependencies: `STLD-T2430`
+- Acceptance Criteria:
+  - Emergency actions are auditable and idempotent.
+  - Paused/quarantined agents cannot execute paid actions.
+  - Recovery flow documented and tested.
+
+#### `STLD-T2432`
+- Type: Task
+- Priority: P1
+- Summary: Add operator decision audit export for finance and compliance.
+- Owner: Backend
+- Estimate: 2d
+- Dependencies: `STLD-T2430`
+- Acceptance Criteria:
+  - Export contains decision metadata, actor, timestamp, reason, linked receipt/case IDs.
+
+### Epic `STLD-E2405` Rail Adapter Hardening
+
+#### `STLD-T2440`
+- Type: Story
+- Priority: P0
+- Summary: Harden one production adapter lane (`x402 + Stripe` or `x402 + AWAL`) under Trust OS enforcement.
+- Owner: Integrations
+- Estimate: 5d
+- Dependencies: `STLD-T2403`, `STLD-T2412`, `STLD-T2421`
+- Acceptance Criteria:
+  - End-to-end flow uses adapter with Trust OS decisions.
+  - Settlement and receipts remain deterministic.
+  - Replay and mutation attacks are rejected in adapter path.
+
+#### `STLD-T2441`
+- Type: Task
+- Priority: P1
+- Summary: Add adapter conformance tests and CI gate.
+- Owner: QA / Integrations
+- Estimate: 2d
+- Dependencies: `STLD-T2440`
+- Acceptance Criteria:
+  - CI fails on adapter regressions.
+  - Conformance report artifact uploaded per run.
+
+### Epic `STLD-E2406` Vertical Policy Profiles
+
+#### `STLD-T2450`
+- Type: Story
+- Priority: P0
+- Summary: Implement profile schema and profile hashing/signing contract.
+- Owner: Protocol + Backend
+- Estimate: 3d
+- Dependencies: `STLD-T2401`
+- Acceptance Criteria:
+  - Profile schema supports limits, allowlists, approval tiers, dispute defaults, compliance toggles.
+  - Profile hash is embedded in decisions/receipts.
+
+#### `STLD-T2451`
+- Type: Story
+- Priority: P0
+- Summary: Add CLI commands: `settld profile init`, `validate`, `simulate`.
+- Owner: CLI
+- Estimate: 4d
+- Dependencies: `STLD-T2450`
+- Acceptance Criteria:
+  - `init` scaffolds profile manifest and rules.
+  - `validate` performs schema + semantic checks.
+  - `simulate` runs policy against provided scenarios and outputs deterministic results.
+
+#### `STLD-T2452`
+- Type: Story
+- Priority: P0
+- Summary: Ship three starter profiles: `engineering-spend`, `procurement`, `data-api-buyer`.
+- Owner: Product + Backend
+- Estimate: 3d
+- Dependencies: `STLD-T2451`
+- Acceptance Criteria:
+  - Profiles are packaged and documented.
+  - Simulation fixtures pass in CI.
+
+#### `STLD-T2453`
+- Type: Task
+- Priority: P1
+- Summary: Add profile docs and quickstart guides in MkDocs/GitBook.
+- Owner: Docs
+- Estimate: 2d
+- Dependencies: `STLD-T2452`
+- Acceptance Criteria:
+  - Docs include usage, simulation examples, and troubleshooting.
+
+### Epic `STLD-E2407` QA, Conformance, and Release Gates
+
+#### `STLD-T2460`
+- Type: Story
+- Priority: P0
+- Summary: Add security regression tests for replay, token mutation, bypass attempts, and unauthorized escalation actions.
+- Owner: QA / Security
+- Estimate: 3d
+- Dependencies: `STLD-T2410`, `STLD-T2431`
+- Acceptance Criteria:
+  - Automated test suite covers top abuse paths.
+  - CI blocks release on failures.
+
+#### `STLD-T2461`
+- Type: Story
+- Priority: P0
+- Summary: Add end-to-end deterministic test: challenge -> operator approve -> execute -> receipt -> dispute -> verdict -> reversal.
+- Owner: QA
+- Estimate: 3d
+- Dependencies: `STLD-T2422`, `STLD-T2430`
+- Acceptance Criteria:
+  - E2E test runs in CI and emits artifact traces.
+  - Idempotency and deterministic output asserted.
+
+#### `STLD-T2462`
+- Type: Task
+- Priority: P0
+- Summary: Enforce release gate checklist for Trust OS v1 (conformance, receipts, disputes, adapters, docs).
+- Owner: DevOps
+- Estimate: 2d
+- Dependencies: `STLD-T2460`, `STLD-T2461`, `STLD-T2441`, `STLD-T2453`
+- Acceptance Criteria:
+  - Release workflow blocks tag publish if any gate fails.
+  - Release artifact bundle includes proof of all required checks.
+
+## Sprint Plan (Suggested)
+
+### Sprint 1 (Weeks 1-2)
+- `STLD-T2401`, `STLD-T2402`, `STLD-T2403`, `STLD-T2410`, `STLD-T2411`, `STLD-T2460`
+
+### Sprint 2 (Weeks 3-4)
+- `STLD-T2412`, `STLD-T2420`, `STLD-T2421`, `STLD-T2422`, `STLD-T2430`, `STLD-T2431`
+
+### Sprint 3 (Weeks 5-6)
+- `STLD-T2440`, `STLD-T2441`, `STLD-T2450`, `STLD-T2451`, `STLD-T2452`, `STLD-T2461`, `STLD-T2462`, `STLD-T2453`
+
+## Release Exit Criteria (Trust OS v1)
+
+- Runtime policy enforcement is mandatory for all paid actions.
+- Request binding enforcement blocks replay/mutation attempts.
+- Receipt bundle export verifies offline in strict mode.
+- Dispute->verdict->financial outcome is deterministic and replay-safe.
+- Operator emergency controls are audited and tested.
+- One rail adapter path is production-hardened and conformance-gated.
+- Three vertical profiles are documented and simulation-tested.

package/docs/plans/2026-02-21-agent-economic-actor-operating-model.md

@@ -0,0 +1,169 @@
+# Agent Economic Actor Operating Model (v1)
+
+Date: 2026-02-21  
+Owner: Product + Platform + Risk
+
+## Why this model
+
+Goal: let agents spend and act with much more autonomy while keeping actions bounded, auditable, and reversible.
+
+Settld does this by treating autonomy as a controlled envelope:
+
+1. identity + delegation,
+2. policy-bound authorization,
+3. deterministic evidence + receipts,
+4. dispute/reversal recourse.
+
+## How customers are served
+
+Primary user groups:
+
+1. Agent builders: quick setup, policy profiles, paid tool calls, receipts.
+2. Platform/runtime teams: central controls across hosts, no-bypass enforcement.
+3. Ops/finance/risk/compliance: audit exports, dispute workflows, deterministic reconciliation.
+4. Design partners: staged rollout with fail-closed release gates.
+
+## Deployment modes
+
+### Mode A: Hosted control plane + managed wallet (default)
+- `settld setup --wallet-mode managed --wallet-bootstrap remote`
+- Fastest time-to-first-paid-call, least wallet ops burden.
+
+### Mode B: Hosted control plane + BYO wallet
+- `settld setup --wallet-mode byo`
+- Customer controls custody while Settld enforces trust contract.
+
+### Mode C: Hosted/self-hosted control plane + no wallet rails
+- `settld setup --wallet-mode none`
+- Non-paid trust control path (proof/audit/dispute readiness before spend).
+
+Reference flows:
+- `docs/QUICKSTART_MCP_HOSTS.md`
+- `scripts/setup/onboard.mjs`
+- `services/magic-link/src/server.js`
+
+## Should Settld manage agent wallets?
+
+Answer: optional and policy-dependent.
+
+1. Managed mode: Settld control plane bootstraps wallet provider config and returns runtime env.
+2. BYO mode: customer supplies wallet env/refs; Settld still enforces policy and receipts.
+3. No-wallet mode: only trust/evidence control path is active.
+
+Wallet bootstrap and runtime bootstrap endpoints:
+- `POST /v1/tenants/{tenantId}/onboarding/wallet-bootstrap`
+- `POST /v1/tenants/{tenantId}/onboarding/runtime-bootstrap`
+- `POST /v1/tenants/{tenantId}/onboarding/runtime-bootstrap/smoke-test`
+
+## Should every agent have identity?
+
+Yes.
+
+Identity model (already defined in spec surface):
+
+1. `AgentPassport.v1`: principal binding + active key anchors + delegation root + policy envelope.
+2. `DelegationGrant.v1`: bounded authority transfer (scope, spend limits, depth, revocation).
+3. `ExecutionIntent.v1`: canonical request/risk/spend/policy binding precondition.
+
+Spec anchors:
+- `docs/spec/AgentPassport.v1.md`
+- `docs/spec/DelegationGrant.v1.md`
+- `docs/spec/ExecutionIntent.v1.md`
+
+Runtime anchors:
+- `src/api/app.js` (passport validation, delegation lineage, wallet policy enforcement)
+- `src/core/settlement-kernel.js`
+
+## How wallet assignment should work
+
+Do not default to “1 wallet per agent.”  
+Default to deterministic assignment:
+
+`tenant + environment + profile + risk tier + delegation depth -> sponsorWalletRef + policyRef + policyVersion`
+
+Recommended rules:
+
+1. High-risk financial agents: dedicated sponsor wallet.
+2. Low-risk read/compute agents: pooled sponsor wallet with strict per-call and daily limits.
+3. Delegated child agents: inherited wallet policy with depth checks and tighter caps.
+4. Cross-team isolation: separate wallet by business unit + policy pack.
+
+## How agents get funded
+
+Funding control should be policy-driven, not ad hoc:
+
+1. Prefund sponsor wallet.
+2. Enforce per-call, per-day, and cumulative limits.
+3. Add threshold-based top-up automation.
+4. Lock escrow before authorization where required.
+5. Require deterministic reserve and rollback semantics on failure.
+
+Current code anchors:
+- `src/api/app.js` (`computeX402DailyAuthorizedExposureCents`, wallet policy checks, reserve + rollback)
+- `src/core/money-rail-adapters.js`
+- `src/core/x402-gate.js`
+
+## Setup flow (operator runbook)
+
+1. Tenant bootstrap (runtime key material and tenant setup).
+2. Wallet bootstrap (`managed` local/remote or `byo` env resolution).
+3. Runtime bootstrap (MCP env + host config).
+4. Profile apply (`settld profile ...`) and passport generation.
+5. Host smoke test and first paid call run.
+6. Conformance matrix + release gate checks.
+
+Command anchors:
+- `settld setup`
+- `settld profile init|validate|simulate|apply`
+- `npm run mcp:probe`
+- `settld doctor`
+
+## What this enables agents to do
+
+As autonomy tiers increase, agents can do more actions safely:
+
+### Tier 0 (Observe)
+- Read-only calls, no spend.
+
+### Tier 1 (Bounded spend)
+- Paid tool calls under strict caps and allowlists.
+
+### Tier 2 (Delegated execution)
+- Multi-step workflows with delegation lineage and challenge windows.
+
+### Tier 3 (Conditional autonomy)
+- Challenge/escalate fallback and operator overrides.
+
+### Tier 4 (Programmatic economic actor)
+- Cross-tool/cross-agent spend orchestration with deterministic receipts, disputes, and reversals.
+
+## Hard controls (must stay fail-closed)
+
+1. No policy bypass across MCP stdio, MCP HTTP bridge, and gateway paths.
+2. Authority boundaries: who can sign/revoke/pause/kill-switch.
+3. Adapter invariant conformance for every rail lane.
+4. Determinism soak checks for repeat export/verification.
+5. Onboarding SLO gates for real operator usability.
+
+## What still must be built
+
+1. No-bypass negative matrix as release blocker.
+2. Authority boundary and rollback drill automation.
+3. Shared adapter invariant gate for all rails.
+4. Deterministic repeat-run soak gate.
+5. Onboarding SLO CI gate tied to runtime metrics.
+
+Execution artifacts:
+- `planning/jira/trust-os-v1-gap-closure-backlog.json`
+- `planning/jira/trust-os-v1-gap-closure-tickets.csv`
+- `planning/jira/agent-economic-actor-backlog.json`
+
+## External research references
+
+- Coinbase AgentKit docs: [https://docs.cdp.coinbase.com/agent-kit/docs/welcome](https://docs.cdp.coinbase.com/agent-kit/docs/welcome)
+- Coinbase Agentic Wallet docs: [https://docs.cdp.coinbase.com/agentic-wallet/welcome](https://docs.cdp.coinbase.com/agentic-wallet/welcome)
+- Circle docs: [https://developers.circle.com/](https://developers.circle.com/)
+- Privy docs: [https://docs.privy.io/](https://docs.privy.io/)
+- SPIFFE overview: [https://spiffe.io/docs/latest/spiffe-about/overview/](https://spiffe.io/docs/latest/spiffe-about/overview/)
+- EIP-4337: [https://eips.ethereum.org/EIPS/eip-4337](https://eips.ethereum.org/EIPS/eip-4337)
+