settld 0.1.2 → 0.2.0

package/docs/ARTIFACTS.md

@@ -0,0 +1,60 @@
+# Artifacts
+
+Settld artifacts are immutable, verifiable JSON documents (often later delivered via webhook/S3) derived from an event-sourced job stream.
+
+## Finance Finality: "Effective" Artifacts
+
+For finance and audit workflows, the *economically final* artifact is determined by settlement:
+
+- If a job is settled, the effective artifact is the one whose `sourceEventId` equals the `SETTLED` event id.
+- If a job is not settled, the effective artifact is anchored to the proof event selected for the latest completion anchor.
+
+API:
+
+- `GET /jobs/:jobId/artifacts/effective?type=WorkCertificate.v1`
+
+This endpoint exists so downstream systems do **not** reinvent "which certificate counts" (and accidentally treat ids as chronology).
+
+## Listing Artifacts (Storage Listing)
+
+API:
+
+- `GET /jobs/:jobId/artifacts`
+  - Optional filters: `type=…`, `sourceEventId=…`
+  - Pagination: `limit=…` with either `offset=…` (simple) or `cursor=…` (seek).
+
+Important: this endpoint is a *storage listing*. It is **not** a job timeline. Artifact creation time may lag source-event time due to worker retries, backfills, or delayed processing.
+
+### Ordering Contract (Postgres)
+
+For the Postgres store, artifact listing uses:
+
+- `ORDER BY created_at DESC, artifact_id DESC`
+
+This ordering is deterministic, but it is based on artifact persistence time (`created_at`), not source event time.
+
+### Cursor Pagination (Postgres-only)
+
+Cursor pagination is supported only when running with the Postgres-backed store.
+
+Cursor semantics:
+
+- The cursor is an opaque `base64url`-encoded JSON payload.
+- It is a seek cursor over `(created_at, artifact_id)` matching the ordering above.
+
+Moving dataset semantics:
+
+- While you are paging, new artifacts may be inserted at the "top" (newer `created_at`).
+- A cursor walk does not guarantee you will see inserts that occur after you started paging.
+- If you need the latest artifacts, restart from the top (no cursor) or use `/artifacts/effective` for finance truth.
+
+Cursor payload format (v1):
+
+```json
+{
+  "v": 1,
+  "order": "created_at_desc_artifact_id_desc",
+  "createdAt": "2026-01-01T00:00:00.000000Z",
+  "artifactId": "workcert_job_123_evt_456"
+}
+```

package/docs/CERTIFICATION_CHECKLIST.md

@@ -0,0 +1,33 @@
+# Skill Certification Checklist (v0)
+
+## Static checks
+
+- Declares required capabilities (no undeclared API calls).
+- Declares safety constraints (force/speed/contact).
+- Declares privacy profile (sensors, retention).
+- No forbidden syscalls / no network egress from skill runtime (policy decision).
+- Deterministic policy graph passes schema validation.
+
+## Simulation
+
+- Passes baseline navigation/manipulation tests.
+- Passes “edge” scenarios (clutter, lighting changes, occlusion).
+- Timeouts and abort paths behave safely.
+- Evidence triggers fire on impacts/uncertainty/assist start.
+
+## Hardware-in-loop (lab apartment)
+
+- Repeated runs meet completion + incident thresholds.
+- Operator assist path is usable and logs actions correctly.
+- Local policy enforcement clamps unsafe command attempts.
+
+## Privacy review
+
+- Media capture respects privacy mode and zones.
+- Evidence is minimal by default; only triggered bundles retained.
+
+## Release controls
+
+- Tier gating: `lab_cert` → limited environments; `field_cert` → broader.
+- Rollback plan and regression monitoring.
+

package/docs/CIRCLE_SANDBOX_E2E.md

@@ -0,0 +1,152 @@
+# 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`
+
+Fastest way to generate these from your Circle account:
+
+```bash
+settld setup circle --api-key 'TEST_API_KEY:...' --mode auto --out-env ./.tmp/circle.env
+```
+
+Then load them:
+
+```bash
+set -a; source ./.tmp/circle.env; set +a
+```
+
+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