settld 0.1.1 → 0.1.5

package/docs/CIRCLE_SANDBOX_E2E.md

@@ -0,0 +1,140 @@
+# Circle Sandbox E2E (Reserve Adapter)
+
+This guide is for validating the x402 reserve path against Circle sandbox before enabling production mode.
+
+## Goal
+
+Prove the reserve contract used by `POST /x402/gate/authorize-payment`:
+
+1. Reserve succeeds before token mint.
+2. Reserve failure does not mint a token.
+3. Reserve rollback path restores internal wallet state.
+
+## Production safety defaults
+
+The API is configured to fail closed in production-like environments:
+
+- `X402_REQUIRE_EXTERNAL_RESERVE` defaults to `true` when `SETTLD_ENV=production|prod`, `NODE_ENV=production`, or `RAILWAY_ENVIRONMENT_NAME=production|prod`.
+- `X402_CIRCLE_RESERVE_MODE` defaults to `production` in production-like environments.
+- In local/test environments, defaults remain:
+  - `X402_REQUIRE_EXTERNAL_RESERVE=false`
+  - `X402_CIRCLE_RESERVE_MODE=stub`
+
+To force explicit behavior in any environment, set both env vars directly.
+
+## Required env
+
+Set these for sandbox runs:
+
+- `CIRCLE_E2E=1` (enables sandbox e2e tests)
+- `CIRCLE_API_KEY` (sandbox key)
+- `CIRCLE_BASE_URL=https://api-sandbox.circle.com`
+- `CIRCLE_BLOCKCHAIN` (for example `BASE-SEPOLIA`)
+- `CIRCLE_WALLET_ID_SPEND`
+- `CIRCLE_WALLET_ID_ESCROW`
+- `CIRCLE_TOKEN_ID_USDC`
+
+If your environment uses a different naming convention, map these into the adapter config before running tests.
+
+## Suggested test flow
+
+1. Verify spend wallet has sufficient USDC.
+2. Call reserve (`spend -> escrow`) with idempotency key = gate id.
+3. Poll transaction status until terminal/safe state.
+4. Attempt rollback:
+   - cancel when still cancellable, or
+   - compensating transfer (`escrow -> spend`) when already confirmed.
+5. Verify resulting balances + persisted reserve status.
+
+## Run command
+
+After adapter wiring is complete:
+
+```bash
+CIRCLE_E2E=1 node --test test/circle-sandbox-reserve-e2e.test.js
+```
+
+## Run full paid MCP demo in Circle mode
+
+The demo now supports explicit reserve rail mode:
+
+```bash
+SETTLD_DEMO_CIRCLE_MODE=sandbox \
+X402_REQUIRE_EXTERNAL_RESERVE=1 \
+node scripts/demo/mcp-paid-exa.mjs --circle=sandbox
+```
+
+Artifacts include:
+
+- `summary.json` with `circleMode`, `circleReserveId`, `reserveTransitions`, and `payoutDestination`.
+- `reserve-state.json` with reserve details, transition timeline, and configured Circle rail metadata.
+
+## Run paid MCP demo + batch settlement in Circle mode
+
+This runs the same demo flow and then executes the batch payout worker against the generated artifact root:
+
+```bash
+SETTLD_DEMO_CIRCLE_MODE=sandbox \
+SETTLD_DEMO_RUN_BATCH_SETTLEMENT=1 \
+SETTLD_DEMO_BATCH_PROVIDER_WALLET_ID="$CIRCLE_WALLET_ID_ESCROW" \
+X402_REQUIRE_EXTERNAL_RESERVE=1 \
+node scripts/demo/mcp-paid-exa.mjs --circle=sandbox
+```
+
+Additional artifacts:
+
+- `batch-payout-registry.json`
+- `batch-worker-state.json`
+- `batch-settlement.json`
+
+## Run sandbox-gated batch settlement E2E test
+
+```bash
+CIRCLE_E2E=1 CIRCLE_BATCH_E2E=1 node --test test/circle-sandbox-batch-settlement-e2e.test.js
+```
+
+This test:
+
+1. Runs the paid MCP demo in sandbox mode with batch settlement enabled.
+2. Confirms payout submission state is recorded.
+3. Reruns the worker and verifies payout idempotency (no duplicate submit).
+
+## Run the full Circle sandbox smoke gate
+
+This command is the recommended "no-regression" check. It runs:
+
+1. Optional faucet top-ups for spend/escrow wallets (can be disabled with `CIRCLE_SKIP_TOPUP=1`).
+2. `test/circle-sandbox-reserve-e2e.test.js`
+3. `test/circle-sandbox-batch-settlement-e2e.test.js`
+
+```bash
+npm run test:x402:circle:sandbox:smoke
+```
+
+Smoke output artifact:
+
+- `artifacts/gates/x402-circle-sandbox-smoke.json`
+
+## GitHub Actions smoke workflow
+
+The repo includes `.github/workflows/x402-circle-sandbox-smoke.yml` for manual/nightly runs.
+
+Required repo secrets:
+
+- `CIRCLE_SANDBOX_API_KEY`
+- `CIRCLE_SANDBOX_WALLET_ID_SPEND`
+- `CIRCLE_SANDBOX_WALLET_ID_ESCROW`
+- `CIRCLE_SANDBOX_TOKEN_ID_USDC`
+- `CIRCLE_SANDBOX_ENTITY_SECRET_HEX`
+
+Optional repo secrets:
+
+- `CIRCLE_SANDBOX_BASE_URL` (defaults to `https://api.circle.com`)
+- `CIRCLE_SANDBOX_BLOCKCHAIN` (defaults to `BASE-SEPOLIA`)
+
+## Pass criteria
+
+- Reserve call returns a stable `reserveId`.
+- Repeated reserve calls with same gate id are idempotent.
+- Failed reserves return `X402_RESERVE_FAILED` and leave no stranded internal escrow lock.
+- Rollback returns funds to spend wallet (cancel or compensation).

package/docs/CONFIG.md

@@ -0,0 +1,297 @@
+# Settld Configuration (Runtime)
+
+This repo is intentionally “ops-first”: **safe defaults**, explicit hardening toggles, and predictable failure modes.
+
+## Store / durability
+
+- `STORE` (`memory` | `pg`, default: `memory`)
+- `DATABASE_URL` (required when `STORE=pg`)
+- `PROXY_PG_SCHEMA` (default: `public`)
+- `PROXY_PG_LOG_SLOW_MS` (default: `0` = disabled)  
+  When nonzero, logs slow queries as `pg.query.slow` with duration + a best-effort query label (never logs query args).
+- `PROXY_MIGRATE_ON_STARTUP` (`1` | `0`, default: `1`)  
+  When `1`, Settld runs SQL migrations on startup (PG advisory-lock protected so concurrent instances are safe). Set `0` if you run migrations out-of-band.
+- `PROXY_DATA_DIR` (memory mode durability via file tx-log; default: unset = purely in-memory)
+
+## HTTP limits
+
+- `PROXY_MAX_BODY_BYTES` (default: `1000000`)
+- `PROXY_INGEST_MAX_EVENTS` (default: `200`)
+
+## Protocol / versioning
+
+Settld exposes a protocol version contract via `x-settld-protocol` and enforces compatibility windows.
+
+- `PROXY_PROTOCOL_MIN` (default: current, e.g. `1.0`)  
+  Requests below this return `426` with `code: PROTOCOL_TOO_OLD`.
+
+- `PROXY_PROTOCOL_MAX` (default: current, e.g. `1.0`)  
+  Requests above this return `400` with `code: PROTOCOL_TOO_NEW`.
+
+- `PROXY_PROTOCOL_DEPRECATIONS` (optional file path)  
+  JSON map of protocol version -> cutoff date; requests past cutoff return `426` with `code: PROTOCOL_DEPRECATED`.
+  Example:
+
+  ```json
+  { "1.0": { "cutoff": "2026-12-31T00:00:00.000Z" } }
+  ```
+
+Production enforcement:
+
+- When `NODE_ENV=production`, `/ingest/proxy` and `POST /{jobs|robots|operators}/:id/events` require the request header `x-settld-protocol` (else `400` with `code: PROTOCOL_VERSION_REQUIRED`).
+
+## Rate limiting
+
+- `PROXY_RATE_LIMIT_RPM` (default: `0` = disabled)
+- `PROXY_RATE_LIMIT_BURST` (default: `PROXY_RATE_LIMIT_RPM`)
+- `PROXY_RATE_LIMIT_PER_KEY_RPM` (default: `0` = disabled)  
+  Applies an additional token bucket per authenticated API key (`auth.keyId`) after tenant-level limiting.
+- `PROXY_RATE_LIMIT_PER_KEY_BURST` (default: `PROXY_RATE_LIMIT_PER_KEY_RPM`)
+
+## Outbox reclaim / worker loop
+
+- `PROXY_RECLAIM_AFTER_SECONDS` (default: `60`)  
+  Reclaim “claimed but not processed” outbox rows after this window.
+
+- `PROXY_PG_WORKER_STATEMENT_TIMEOUT_MS` (default: `0` = disabled; PG only)  
+  Sets `statement_timeout` for worker-transaction queries (outbox claims + delivery claims + outbox processors) to prevent “hung query” pileups.
+
+- `PROXY_AUTOTICK` (`1` enables a default loop)
+- `PROXY_AUTOTICK_INTERVAL_MS` (default: `0`, or `250` when `PROXY_AUTOTICK=1`)
+- `PROXY_AUTOTICK_MAX_MESSAGES` (default: `100`)
+
+Delivery/worker tuning:
+
+- `PROXY_WORKER_CONCURRENCY_ARTIFACTS` (default: `1`)  
+  Max concurrent artifact build groups (grouped by `tenantId + jobId`).
+
+- `PROXY_WORKER_CONCURRENCY_DELIVERIES` (default: `1`)  
+  Max concurrent delivery scope groups (grouped by `scopeKey`; preserves ordering within each scope).
+
+- `PROXY_DELIVERY_HTTP_TIMEOUT_MS` (default: `0` = disabled)  
+  Abort outbound delivery HTTP requests after this timeout and retry with backoff.
+
+## Ops / API auth
+
+- `PROXY_OPS_TOKENS`  
+  Format: `token:scope1,scope2;token2:scopeA` (scopes include `ops_read`, `ops_write`, `audit_read`, `finance_write`, …)
+
+- `PROXY_OPS_TOKEN` (legacy)  
+  If `PROXY_OPS_TOKENS` is empty, this single token grants full ops access.
+
+- `PROXY_AUTH_KEY_TOUCH_MIN_SECONDS` (default: `60`)  
+  Throttle how often `last_used_at` is updated for API keys (reduces DB write amplification).
+
+## Ingest auth
+
+- `PROXY_INGEST_TOKEN` (optional)  
+  When set, `/ingest/proxy` requires header `x-proxy-ingest-token` to match.
+
+## Export destinations (deliveries)
+
+- `PROXY_EXPORT_DESTINATIONS` (JSON)  
+  Maps `tenantId -> destinations[]`.
+
+Webhook destination (preferred, secrets via ref):
+
+```json
+{
+  "tenant_default": [
+    { "destinationId": "dst_webhook", "kind": "webhook", "url": "https://example.com/hook", "secretRef": "file:/var/run/secrets/webhook_secret" }
+  ]
+}
+```
+
+S3 destination (preferred, credentials via ref):
+
+```json
+{
+  "tenant_default": [
+    {
+      "destinationId": "dst_s3",
+      "kind": "s3",
+      "endpoint": "https://s3.amazonaws.com",
+      "bucket": "my-bucket",
+      "region": "us-east-1",
+      "accessKeyIdRef": "file:/var/run/secrets/aws_access_key_id",
+      "secretAccessKeyRef": "file:/var/run/secrets/aws_secret_access_key"
+    }
+  ]
+}
+```
+
+Hardening note:
+
+- Inline secrets (`secret`, `accessKeyId`, `secretAccessKey`) are rejected when `NODE_ENV=production` unless `PROXY_ALLOW_INLINE_SECRETS=1`.
+
+## Evidence store
+
+- `PROXY_EVIDENCE_STORE` (`fs` | `memory` | `s3` | `minio`, default: `fs`)
+- `PROXY_EVIDENCE_DIR` (fs store root; default: tmp dir when not using `PROXY_DATA_DIR`)
+
+S3/minio evidence store config:
+
+- `PROXY_EVIDENCE_S3_ENDPOINT`
+- `PROXY_EVIDENCE_S3_REGION` (default: `us-east-1`)
+- `PROXY_EVIDENCE_S3_BUCKET`
+- `PROXY_EVIDENCE_S3_ACCESS_KEY_ID` (or `AWS_ACCESS_KEY_ID`)
+- `PROXY_EVIDENCE_S3_SECRET_ACCESS_KEY` (or `AWS_SECRET_ACCESS_KEY`)
+- `PROXY_EVIDENCE_S3_FORCE_PATH_STYLE` (default: `1`)
+
+Evidence download security:
+
+- `PROXY_EVIDENCE_SIGNING_SECRET` (optional; default derived from server signer)
+- `PROXY_EVIDENCE_PRESIGN_MAX_SECONDS` (default: `300`, max: `3600`)
+- `PROXY_EVIDENCE_RETENTION_MAX_DAYS` (default: `365`)  
+  Tenant cap for `contract.policies.evidencePolicy.retentionDays`.
+- `PROXY_EVIDENCE_RETENTION_MAX_DAYS_BY_TENANT` (JSON map, optional)  
+  Per-tenant override for `PROXY_EVIDENCE_RETENTION_MAX_DAYS`.
+
+## Secrets provider
+
+- `PROXY_ENABLE_ENV_SECRETS` (`1` enables `env:NAME` refs; default: disabled unless `NODE_ENV=development`)
+- `PROXY_SECRETS_CACHE_TTL_SECONDS` (default: `30`)
+
+Supported refs:
+
+- `env:NAME` (dev-only unless explicitly enabled)
+- `file:/absolute/path` (k8s secret mounts)
+
+## URL safety overrides (dev only)
+
+These exist to make local development possible (e.g. MinIO on `localhost`). Do not enable in production.
+
+- `PROXY_ALLOW_HTTP_URLS` (`1` allows `http://` where URL safety checks apply)
+- `PROXY_ALLOW_PRIVATE_URLS` (`1` allows private IP ranges)
+- `PROXY_ALLOW_LOOPBACK_URLS` (`1` allows `localhost` / loopback)
+
+## Retention / cleanup
+
+Retention is tenant-configurable via in-memory config and capped by these runtime env vars.
+
+- `PROXY_RETENTION_INGEST_RECORDS_DAYS` (default: `0` = no expiry)  
+  Sets `expires_at` for `ingest_records`.
+
+- `PROXY_RETENTION_INGEST_RECORDS_MAX_DAYS` (default: `0` = no platform cap)  
+  When set, tenant `0` means “use the cap”.
+
+- `PROXY_RETENTION_DELIVERIES_DAYS` (default: `0` = no expiry)  
+  Expiration for delivered deliveries.
+
+- `PROXY_RETENTION_DELIVERIES_MAX_DAYS` (default: `0` = no platform cap)
+
+- `PROXY_RETENTION_DELIVERY_DLQ_DAYS` (default: `PROXY_RETENTION_DELIVERIES_DAYS`)  
+  Expiration for failed (DLQ) deliveries.
+
+- `PROXY_RETENTION_DELIVERY_DLQ_MAX_DAYS` (default: `PROXY_RETENTION_DELIVERIES_MAX_DAYS`)
+
+Cleanup execution (PG mode):
+
+- `PROXY_RETENTION_CLEANUP_BATCH_SIZE` (default: `500`)  
+  Max rows per table per cleanup run.
+
+- `PROXY_RETENTION_CLEANUP_MAX_MILLIS` (default: `1500`)  
+  Wall-clock budget for a single cleanup run (enforced via PG `statement_timeout`).
+
+- `PROXY_RETENTION_CLEANUP_DRY_RUN` (`1` prints would-delete counts; no deletes)
+
+Finance reconciliation scheduling:
+
+- `PROXY_FINANCE_RECONCILE_ENABLED` (default: `1`)  
+  Enables periodic finance reconciliation maintenance ticks.
+
+- `PROXY_FINANCE_RECONCILE_INTERVAL_SECONDS` (default: `300`)  
+  Minimum interval between automatic reconciliation runs.
+
+- `PROXY_FINANCE_RECONCILE_MAX_TENANTS` (default: `50`)  
+  Max tenants scanned per automatic run.
+
+- `PROXY_FINANCE_RECONCILE_MAX_PERIODS_PER_TENANT` (default: `2`)  
+  Max GL periods reconciled per tenant in one run.
+
+Money-rail reconciliation scheduling:
+
+- `PROXY_MONEY_RAIL_RECONCILE_ENABLED` (default: `1`)  
+  Enables periodic money-rail reconciliation maintenance ticks.
+
+- `PROXY_MONEY_RAIL_RECONCILE_INTERVAL_SECONDS` (default: `300`)  
+  Minimum interval between automatic money-rail reconciliation runs.
+
+- `PROXY_MONEY_RAIL_RECONCILE_MAX_TENANTS` (default: `50`)  
+  Max tenants scanned per automatic run.
+
+- `PROXY_MONEY_RAIL_RECONCILE_MAX_PERIODS_PER_TENANT` (default: `2`)  
+  Max payout periods reconciled per tenant in one run.
+
+- `PROXY_MONEY_RAIL_RECONCILE_MAX_PROVIDERS_PER_TENANT` (default: `10`)  
+  Max money-rail providers reconciled per tenant in one run.
+
+Maintenance runner (recommended in prod):
+
+- `PROXY_MAINTENANCE_INTERVAL_SECONDS` (default: `300`)  
+  Sleep between cleanup runs in `src/api/maintenance.js`.
+
+## Quotas / backpressure
+
+On quota breach, requests return `429` with `code: TENANT_QUOTA_EXCEEDED`.
+
+- `PROXY_QUOTA_MAX_OPEN_JOBS` (default: `0` = unlimited)
+- `PROXY_QUOTA_PLATFORM_MAX_OPEN_JOBS` (default: `0` = no platform cap)
+
+- `PROXY_QUOTA_MAX_PENDING_DELIVERIES` (default: `0` = unlimited)
+- `PROXY_QUOTA_PLATFORM_MAX_PENDING_DELIVERIES` (default: `0` = no platform cap)
+
+- `PROXY_QUOTA_MAX_INGEST_DLQ_DEPTH` (default: `0` = unlimited)
+- `PROXY_QUOTA_PLATFORM_MAX_INGEST_DLQ_DEPTH` (default: `0` = no platform cap)
+
+- `PROXY_QUOTA_MAX_EVIDENCE_REFS_PER_JOB` (default: `0` = unlimited)
+- `PROXY_QUOTA_PLATFORM_MAX_EVIDENCE_REFS_PER_JOB` (default: `0` = no platform cap)
+
+- `PROXY_QUOTA_MAX_ARTIFACTS_PER_JOB_TYPE` (default: `0` = unlimited)
+- `PROXY_QUOTA_PLATFORM_MAX_ARTIFACTS_PER_JOB_TYPE` (default: `0` = no platform cap)
+
+## Outbox poison-pill
+
+- `PROXY_OUTBOX_MAX_ATTEMPTS` (default: `25`)  
+  After this many attempts, outbox work is marked done with a DLQ error marker.
+
+## Evidence ingest constraints (optional hardening)
+
+- `PROXY_EVIDENCE_CONTENT_TYPE_ALLOWLIST` (comma-separated)  
+  If set, `EVIDENCE_CAPTURED.payload.contentType` must be in the allowlist.
+
+- `PROXY_EVIDENCE_REQUIRE_SIZE_BYTES` (`1` requires `EVIDENCE_CAPTURED.payload.sizeBytes`)
+- `PROXY_EVIDENCE_MAX_SIZE_BYTES` (default: `0` = unlimited)
+
+## Backups / restore (Postgres)
+
+These helper scripts assume you have Postgres client tools installed (`pg_dump`, `pg_restore`, `psql`).
+
+- Backup:
+
+  ```sh
+  DATABASE_URL=postgres://... PROXY_PG_SCHEMA=public OUT_DIR=./backups bash scripts/backup-pg.sh
+  ```
+
+- Restore (to a fresh DB is recommended):
+
+  ```sh
+  DATABASE_URL=postgres://... PROXY_PG_SCHEMA=public bash scripts/restore-pg.sh ./backups/backup_*/db.dump
+  ```
+
+- Verify a restored DB:
+
+  ```sh
+  DATABASE_URL=postgres://... PROXY_PG_SCHEMA=public node scripts/verify-pg.js
+  ```
+
+Verification knobs:
+
+- `VERIFY_MAX_STREAMS` (default: `100`)
+- `VERIFY_MAX_ARTIFACTS` (default: `100`)
+- `VERIFY_MAX_LEDGER_ENTRIES` (default: `0` = all)
+
+RPO/RTO (practical):
+
+- RPO is the time between successful backups.
+- RTO is `restore time + verification time` and scales with DB size.

package/docs/CONTRACTS_APIS.md

@@ -0,0 +1,23 @@
+# Contracts APIs (Legacy vs Contracts-as-Code)
+
+Settld exposes two separate “contracts” API families on purpose.
+
+## Legacy: `/ops/contracts` (policy upsert)
+
+- Semantics: mutable upsert of “policy templates” (JSON `policies.*` blobs).
+- Compatibility: kept for existing integrations and tests.
+- Output: legacy `contract` records with `contractVersion` incrementing per upsert.
+
+Use this when you want to keep the existing quoting/booking contract behavior.
+
+## Contracts-as-Code: `/ops/contracts-v2` (hash-addressed documents)
+
+- Semantics: immutable, hash-addressed `ContractDocument.v1` documents with optional signatures and an activation step.
+- Output: v2 contract records that carry `contractHash`, `policyHash`, and `compilerId`.
+- Jobs pin hashes at booking-time (so later edits cannot retroactively change what governed the job).
+
+Use this when you need audit-grade pinning (hashes), signing, and deterministic compilation.
+
+## Capabilities
+
+`GET /capabilities` advertises which contract APIs and schema/compiler versions the server supports.

package/docs/DEPRECATION.md

@@ -0,0 +1,31 @@
+# Deprecation Policy
+
+Settld is infrastructure. We don’t break integrators casually.
+
+## Protocol versions (`x-settld-protocol`)
+
+- Format: `major.minor` (example: `1.0`)
+- Server advertises:
+  - `x-settld-protocol` (current)
+  - `x-settld-supported-protocols` (comma-separated)
+
+### Minimum windows
+
+- Breaking change requires a protocol bump.
+- Deprecated protocol versions remain supported for **at least 6 months**, except for urgent security fixes.
+
+### Enforcing deprecation cutoffs
+
+If configured, the server rejects deprecated versions past cutoff via `PROXY_PROTOCOL_DEPRECATIONS` and reason code `PROTOCOL_DEPRECATED`.
+
+## APIs
+
+When an API family is deprecated:
+- it will be called out in `CHANGELOG.md`
+- it may emit a warning header in non-test mode
+- it will have a published replacement
+
+Current split:
+- Legacy contracts: `/ops/contracts` (mutable policy upsert; back-compat)
+- Contracts v2: `/ops/contracts-v2` (contracts-as-code; hash-addressed + compiled)
+

package/docs/DOMAIN_MODEL.md

@@ -0,0 +1,92 @@
+# Settld Domain Model (v0)
+
+## Actors
+
+- **Requester**: Household or Business that pays and grants scoped access.
+- **Owner**: supplies executors and receives payouts.
+- **Executor**: endpoint with capabilities, health, and safety profile.
+- **Operator**: remote assist + exception handling; actions are audited.
+- **Developer**: publishes skills.
+- **Trust Counterparty**: insurance/guarantee/claims partner.
+
+## First-class entities
+
+### Job
+
+Purchasable outcome with SLA and constraints.
+
+Key fields:
+
+- `templateId` (e.g., `reset_lite`)
+- constraints (rooms allowed, privacy mode, fragile items, pets, etc.)
+- scheduling window
+- price quote + risk premium
+- selected executor + operator coverage (optional)
+- state machine status
+
+### Task Template
+
+Defines:
+
+- required skills
+- environment requirements (managed vs home)
+- SLA expectations
+- pricing inputs and guardrails
+
+### Skill
+
+Signed bundle:
+
+- metadata (name, version, developer, description)
+- required capabilities + safety constraints
+- deterministic policy graph (BT/SM) and tests
+- optional model artifacts
+- certification tier
+
+### Capability
+
+Runtime-agnostic API surface (e.g., `ExecuteWorkflow`, `CallTool`, `CollectEvidence`, `ObserveROI`).
+
+Executors advertise:
+
+- mobility/manipulation properties
+- allowed speed/force envelopes
+- autonomy/teleop allowed flags
+- sensor modes (privacy implications)
+
+### Access Plan
+
+Time-bounded, revocable credential set and instructions to access the space:
+
+- credential scope + expiry
+- revocation path
+- entry/exit safe behaviors
+
+### Incident / Claim
+
+Incident: operationally detected anomaly or requester-reported issue.
+
+Claim: workflow for remediation/payout:
+
+- triage, classify, evidence bundle attach
+- approve small payouts quickly, escalate large claims
+- ledger adjustments (refunds, owner clawbacks, reserve draws)
+
+### Ledger
+
+Double-entry system of record for money movement:
+
+- escrow/holds
+- payout splits (owner, Settld fee, operator fee, developer royalty, reserve)
+- refunds, chargebacks, tips
+
+Invariant: every journal entry balances to zero.
+
+## Trust scores (initially naive)
+
+Used for dispatch, pricing, and environment gating:
+
+- executor trust score
+- owner trust score
+- building trust score
+- skill trust score / certification tier

package/docs/EVENT_ENVELOPE.md

@@ -0,0 +1,53 @@
+# Event Envelope & Black Box Rules (v0.2)
+
+Settld’s “black box” is an append-only, hash-chained event stream. The API rejects events that fail envelope, causality, or signer-policy validation.
+
+## Envelope
+
+Each stored event uses this shape:
+
+- `v`: envelope version (currently `1`)
+- `id`: event id (`evt_...`)
+- `at`: ISO-8601 timestamp
+- `streamId`: aggregate stream id (e.g. a job id)
+- `type`: event type (e.g. `BOOKED`, `EN_ROUTE`)
+- `actor`: `{ type, id }` (who initiated the action)
+- `payload`: JSON payload (nullable)
+- `payloadHash`: `sha256(canonical(eventPayload))`
+- `prevChainHash`: previous event’s `chainHash` (or `null` for genesis)
+- `chainHash`: `sha256(canonical(chainLink))`
+- `signature`: base64 Ed25519 signature (nullable)
+- `signerKeyId`: key id of the signer (nullable)
+
+## Canonical hashing
+
+Canonical JSON rules (implemented in `src/core/canonical-json.js`):
+
+- Object keys are sorted deterministically.
+- No `undefined`, non-finite numbers, or `-0`.
+- Only JSON values (plain objects/arrays/strings/numbers/booleans/null).
+
+Hashes:
+
+- `payloadHash = sha256( canonicalJson({ v, id, at, streamId, type, actor, payload }) )`
+- `chainHash = sha256( canonicalJson({ v, prevChainHash, payloadHash }) )`
+
+Signatures:
+
+- `signature = Ed25519.sign(payloadHash)`
+- Verification uses the signer’s public key looked up by `signerKeyId`.
+
+## Append-time acceptance rules
+
+The server rejects an append if any of the following are true:
+
+- The envelope is missing required fields for the append mode (draft vs finalized).
+- `prevChainHash` does not match the current stream head (optimistic concurrency).
+- The hash chain or signature verification fails.
+- The event violates signature policy (who must sign what).
+- The event would cause an illegal job state transition.
+
+## Concurrency & idempotency
+
+- **Optimistic concurrency**: draft events must include `x-proxy-expected-prev-chain-hash`, and the server returns `409` on mismatch.
+- **Idempotency**: mutation endpoints accept `x-idempotency-key`; replays return the original response (and don’t append twice).

package/docs/FINANCE_PACK_FORMAT.md

@@ -0,0 +1,53 @@
+# FinancePackBundle.v1 Format (Finance-Grade)
+
+This document defines the on-disk format for `FinancePackBundle.v1` and its strict-verification invariants.
+
+## Directory Layout
+
+```
+settld.json
+manifest.json
+attestation/bundle_head_attestation.json
+month/...
+finance/...
+verify/verification_report.json
+```
+
+Notes:
+- `month/` is a full embedded `MonthProofBundle.v1` directory tree.
+- `attestation/bundle_head_attestation.json` is a signed `BundleHeadAttestation.v1` committing to the FinancePack manifestHash and MonthProof anchor.
+- `verify/verification_report.json` is a signed, machine-ingestible `VerificationReport.v1`.
+
+## `manifest.json` (FinancePackBundleManifest.v1)
+
+`manifest.json` includes:
+- `files[]`: sha256 hashes for the **non-verify** bundle files
+- `manifestHash`: sha256 over canonical JSON of the manifest object **excluding** `manifestHash`
+
+### Hashing Contract (`hashing.schemaVersion = FinancePackBundleManifestHash.v1`)
+
+- `fileOrder = path_asc`
+- `excludes = ["verify/**"]` (all `verify/*` derived outputs are intentionally excluded)
+
+Rationale: `VerificationReport.v1` needs to refer to `manifestHash`, so including `verify/*` in the manifest would create circular hashing.
+
+## `verify/verification_report.json` (VerificationReport.v1)
+
+`VerificationReport.v1` is canonical JSON with:
+- `tool`: identifies the generator/verifier version for auditability
+- `signer`: provenance for the report signer (including governance event ref when available)
+- `subject.manifestHash`: must equal the bundle `manifestHash`
+- `reportHash`: sha256 over canonical JSON of the report core (excluding signature fields)
+- `signature`: Ed25519 signature over `reportHash`
+
+Strict verification requires the report to be present **and signed**.
+
+If the tool version cannot be determined, the report will include a warning code `TOOL_VERSION_UNKNOWN`.
+
+## Strict Verification Invariants
+
+In strict mode (`settld-verify --strict --finance-pack ...`):
+- The embedded `MonthProofBundle.v1` must strictly verify.
+- `attestation/bundle_head_attestation.json` must exist and have a valid signature.
+- `verify/verification_report.json` must exist, have a valid `reportHash`, and have a valid signature.
+- `VerificationReport.v1.subject.manifestHash` must match the computed bundle `manifestHash`.