settld 0.1.2 → 0.2.0

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

package/docs/INCIDENT_TAXONOMY.md

@@ -0,0 +1,30 @@
+# Incident Taxonomy (v0.4)
+
+Incidents are classified events that anchor evidence and claims workflows.
+
+## Types (enforced)
+
+Defined in `src/core/incidents.js`:
+
+- `DAMAGE_PROPERTY`
+- `PRIVACY_VIOLATION`
+- `SAFETY_NEAR_MISS`
+- `FAILURE_TO_COMPLETE`
+- `ACCESS_FAILURE`
+- `THEFT_ALLEGATION`
+- `ROBOT_STUCK`
+- `UNEXPECTED_HUMAN_CONTACT`
+
+## Severity (enforced)
+
+Integer scale `1..5`:
+
+- `1` — minor anomaly / near-miss
+- `3` — material anomaly; evidence likely required
+- `5` — severe safety/property risk
+
+## Event linkage
+
+- Incidents are created by `INCIDENT_DETECTED` (robot) or `INCIDENT_REPORTED` (operator or server-on-behalf-of-customer).
+- Evidence (`EVIDENCE_CAPTURED`) must reference an existing `incidentId`.
+- Claims (`CLAIM_OPENED`) must reference an existing `incidentId`.

package/docs/JOB_STATE_MACHINE.md

@@ -0,0 +1,66 @@
+# Job State Machine (v0.6)
+
+Jobs are explicit workflows. Every transition emits an event; the event log is replayable.
+
+## States
+
+- `CREATED`
+- `QUOTED`
+- `BOOKED`
+- `MATCHED`
+- `RESERVED`
+- `EN_ROUTE`
+- `ACCESS_GRANTED`
+- `EXECUTING`
+- `ASSISTED` (sub-state during execution)
+- `STALLED` (execution liveness failure)
+- `ABORTING_SAFE_EXIT` (forced by access revoke/expiry)
+- `COMPLETED`
+- `ABORTED`
+- `SETTLED`
+
+## Terminality
+
+- Terminal execution: `COMPLETED` or `ABORTED`
+- Terminal financial: `SETTLED`
+
+## Diagram (simplified)
+
+```mermaid
+stateDiagram-v2
+  [*] --> CREATED
+  CREATED --> QUOTED
+  QUOTED --> BOOKED
+  BOOKED --> MATCHED
+  MATCHED --> RESERVED
+  RESERVED --> EN_ROUTE
+  EN_ROUTE --> ACCESS_GRANTED
+  ACCESS_GRANTED --> EXECUTING
+
+  EXECUTING --> ASSISTED
+  ASSISTED --> EXECUTING
+
+  EXECUTING --> STALLED
+  ASSISTED --> STALLED
+  STALLED --> EXECUTING
+
+  EXECUTING --> ABORTING_SAFE_EXIT
+  ASSISTED --> ABORTING_SAFE_EXIT
+  STALLED --> ABORTING_SAFE_EXIT
+  ABORTING_SAFE_EXIT --> ABORTED
+
+  EXECUTING --> COMPLETED
+  EXECUTING --> ABORTED
+
+  COMPLETED --> SETTLED
+  ABORTED --> SETTLED
+
+  SETTLED --> [*]
+```
+
+## Policy hooks
+
+- Access revocation at any time → agent must transition to safe exit behavior (recorded as events).
+- Missing heartbeats → server appends `JOB_EXECUTION_STALLED` and escalates per tier/coverage policy.
+- Jobs can be rescheduled via `JOB_RESCHEDULED`, which resets dispatch and clears access planning.
+- Incidents/claims can occur in parallel; they do not necessarily change the main job status (modeled as parallel tracks in the event log).

package/docs/KERNEL_COMPATIBLE.md

@@ -0,0 +1,60 @@
+# Kernel Compatible Policy (v0)
+
+This policy defines when a capability implementation can be listed as "Kernel Compatible".
+
+## Eligibility Requirements
+
+A capability must satisfy all three checks:
+
+1. Kernel conformance passes for supported flow(s).
+2. Closepack export verifies offline.
+3. At least one deterministic verifier case passes.
+
+Required commands (or equivalent CI jobs):
+
+```sh
+./bin/settld.js conformance kernel --ops-token tok_ops
+./bin/settld.js closepack export --agreement-hash <sha256> --out /tmp/<agreementHash>.zip --ops-token tok_ops
+./bin/settld.js closepack verify /tmp/<agreementHash>.zip
+```
+
+## Listing Contract
+
+Each listed capability entry must provide:
+
+- `id` (stable identifier)
+- `name`
+- `repoPath` (or external repository URL)
+- `deterministicVerifierRef`
+- `conformanceCaseIds` (array)
+- `closepackVerified` (boolean)
+- `lastVerifiedAt` (ISO timestamp)
+
+Canonical listing file:
+
+- `docs/kernel-compatible/capabilities.json`
+
+Hosted/static mirror:
+
+- `dashboard/public/kernel-compatible/capabilities.json`
+
+## Badge Rules
+
+- Badge text: `Kernel Compatible (v0)`
+- Badge can be shown only while latest verification is passing.
+- Badge must be removed within 24h if conformance or closepack verification regresses.
+
+## Revocation Conditions
+
+Listing is revoked when:
+
+- conformance fails on latest stable release,
+- closepack verify returns `ok=false`,
+- deterministic verifier case is removed or fails repeatedly,
+- artifact-chain replay mismatches are unresolved.
+
+## Submission Flow (No Meeting Required)
+
+1. Open a PR updating `docs/kernel-compatible/capabilities.json`.
+2. Include machine-readable evidence paths or CI links for conformance and closepack verify.
+3. Maintainer verifies evidence and merges if checks pass.

package/docs/KERNEL_V0.md

@@ -0,0 +1,40 @@
+# Kernel v0
+
+Kernel v0 is the protocol/control-plane surface for payable capability calls:
+
+`agreement -> hold -> evidence -> decision -> receipt -> dispute -> verdict -> adjustment`
+
+This page is the public contract for what is enforced now vs what is explicitly out of scope.
+
+## Enforced In Kernel v0
+
+- Deterministic IDs and idempotency on core financial artifacts (holdback adjustment IDs, dispute envelopes, replay artifacts).
+- Tool-call holdback maintenance race hardening (open arbitration cases block auto-release).
+- Signed dispute-open envelope for party-initiated disputes (`DisputeOpenEnvelope.v1`).
+- Deterministic holdback adjustment issuance on verdict (`holdback_release` or `holdback_refund`).
+- Replay evaluate and closepack export/verify for independent verification.
+- `SettlementDecisionRecord.v2` emission default, with `policyHashUsed` and policy normalization pinning.
+- Append-only `ReputationEvent.v1` facts with windowed query support (`/ops/reputation/facts`).
+
+## Explicitly Not Enforced Yet
+
+- Public money-rail GA behavior (chargebacks/refunds/KYB lifecycle) for all tenants.
+- Hosted marketplace ranking policies on top of reputation facts.
+- Universal deterministic verifier coverage across all capability types.
+- Hosted click-to-try playground SLOs for untrusted anonymous traffic.
+
+## Verification Entry Points
+
+- Kernel conformance:
+  - `./bin/settld.js conformance kernel --ops-token tok_ops`
+- Closepack export and offline verify:
+  - `./bin/settld.js closepack export --agreement-hash <sha256> --out /tmp/<agreementHash>.zip --ops-token tok_ops`
+  - `./bin/settld.js closepack verify /tmp/<agreementHash>.zip`
+- Tool-call replay evaluate:
+  - `GET /ops/tool-calls/replay-evaluate?agreementHash=<sha256>`
+
+## Stability Policy
+
+- Kernel v0 aims for additive protocol evolution.
+- Existing object versions remain verifiable (no flag day replacement of historical artifacts).
+- New replay-critical requirements ship in versioned objects (for example, `SettlementDecisionRecord.v2`).

package/docs/KEY_ROTATION.md

@@ -0,0 +1,80 @@
+# SettldPay Key Rotation Runbook
+
+This runbook covers rotation for the SettldPay Ed25519 signing key used by:
+
+- `POST /x402/gate/authorize-payment` token minting
+- `GET /.well-known/settld-keys.json` public key discovery
+
+## Current model
+
+- Tokens include `kid` and are signed with the active server signer key.
+- Verifiers resolve keys via `/.well-known/settld-keys.json`.
+- For file-backed deployments (`STORE=memory` with `PROXY_DATA_DIR`), key material is persisted in:
+  - `${PROXY_DATA_DIR}/server-signer.json` (active signer compatibility file)
+  - `${PROXY_DATA_DIR}/settld-pay-keyset-store.json` (active + previous key history)
+- API supports published fallback keys via:
+  - `SETTLD_PAY_FALLBACK_KEYS` (JSON array of `{ keyId?, publicKeyPem }`)
+  - `SETTLD_PAY_FALLBACK_PUBLIC_KEY_PEM`
+  - `SETTLD_PAY_FALLBACK_KEY_ID`
+
+## Automated rotation command
+
+Run:
+
+```bash
+npm run keys:rotate -- --data-dir ./data --report artifacts/key-rotation/rotation-report.json --keep-previous 3
+```
+
+What it does:
+
+1. Generates a new Ed25519 keypair.
+2. Promotes it to active signer.
+3. Moves the prior active key into `previous[]` (published fallback set).
+4. Updates both key files in `--data-dir`.
+5. Prints:
+   - new active `kid`
+   - active JWKS entry
+   - provider notification snippet text
+6. Optionally writes a rotation report JSON artifact (`--report`).
+
+## Planned rotation (normal)
+
+1. Run `npm run keys:rotate ...` (or equivalent process in your deployment pipeline).
+2. Deploy signer with new private key (but do not remove old key yet).
+3. Publish keyset including both:
+   - new active key
+   - previous key as fallback
+4. Switch signing to the new key.
+5. Keep old key published for at least:
+   - `max token TTL` (default 5m), plus
+   - cache margin for well-known keyset refresh (recommend >=24h for external verifiers).
+6. After the overlap window, remove old key from fallback list.
+
+## Emergency rotation (key compromise)
+
+1. Stop signing with the compromised key immediately.
+2. Switch signer to a new keypair.
+3. Publish a refreshed keyset with the compromised key removed from active use.
+4. Notify providers/operators to refresh keyset immediately.
+5. Review recent `authorize-payment` and verify flows for suspicious token use.
+
+## Verification checks
+
+Before/after rotation, run:
+
+```bash
+node --test test/settld-pay-token.test.js
+node --test test/api-e2e-x402-authorize-payment.test.js
+```
+
+And manually confirm:
+
+```bash
+curl -fsS http://127.0.0.1:3000/.well-known/settld-keys.json
+```
+
+Response should include:
+
+- active `kid`
+- fallback `kid`(s) during overlap
+- `kty=OKP`, `crv=Ed25519`, and `x` set for each key

package/docs/LEDGER.md

@@ -0,0 +1,82 @@
+# Ledger (v0.4)
+
+Settld treats settlement as a double-entry ledger: every journal entry must balance to zero.
+
+## Posting sign convention
+
+- Positive `amountCents` = debit
+- Negative `amountCents` = credit
+- Every journal entry satisfies `sum(postings.amountCents) === 0`
+
+## Chart of accounts (current prototype)
+
+Defined in `src/api/store.js`:
+
+- `acct_cash` — payment processor clearing cash
+- `acct_customer_escrow` — customer escrow liability
+- `acct_platform_revenue` — platform revenue
+- `acct_owner_payable` — owner payout liability
+- `acct_operator_payable` — operator payout liability
+- `acct_developer_royalty_payable` — developer royalties liability
+- `acct_insurance_reserve` — insurance reserve
+- `acct_claims_expense` — claims expense (prototype)
+- `acct_claims_payable` — claims payable liability
+
+## Job lifecycle postings (current)
+
+### `BOOKED`
+
+Captures funds into escrow (prototype model):
+
+- Debit `acct_cash` for `amountCents`
+- Credit `acct_customer_escrow` for `amountCents`
+
+### `SETTLED` (job was `COMPLETED`)
+
+Moves escrow into revenue + payables + reserve:
+
+- Debit `acct_customer_escrow` for `amountCents`
+- Credit:
+  - `acct_platform_revenue`
+  - `acct_owner_payable`
+  - `acct_operator_payable` (only if assist occurred)
+  - `acct_developer_royalty_payable` (equals sum of licensed skill fees)
+  - `acct_insurance_reserve`
+
+Splits are deterministic and integer-cent safe (see `src/core/ledger-postings.js`).
+
+### `SETTLED` (job was `ABORTED`)
+
+Full refund from escrow:
+
+- Debit `acct_customer_escrow` for `amountCents`
+- Credit `acct_cash` for `amountCents`
+
+## Claims postings (v0.4)
+
+Claims are modeled as their own workflow, but postings stay deterministic and derived from events.
+
+### `JOB_ADJUSTED` (claim was approved)
+
+Creates a payable for the approved total (payout + refund), and offsets it via:
+
+- **Payouts** (`payoutCents`):
+  - Debit `acct_claims_expense`
+  - Credit `acct_claims_payable`
+- **Refunds** (`refundCents`, completed jobs only):
+  - Debit proportional reversals of:
+    - `acct_platform_revenue`
+    - `acct_owner_payable`
+    - `acct_operator_payable` (if assist)
+    - `acct_developer_royalty_payable` (if licensed skills)
+    - `acct_insurance_reserve`
+  - Credit `acct_claims_payable`
+
+Refund reversals are computed as a deterministic pro-rata split of the original settlement allocation (see `src/core/ledger-postings.js`).
+
+### `CLAIM_PAID`
+
+Moves funds out of cash and clears the liability:
+
+- Debit `acct_claims_payable` for `amountCents`
+- Credit `acct_cash` for `amountCents`

package/docs/LIVENESS.md

@@ -0,0 +1,76 @@
+# Execution Liveness (v0.6)
+
+Settld treats “job liveness” as an event-sourced contract:
+
+- Robots emit signed heartbeats into the job stream.
+- The server detects missing heartbeats and appends a signed `JOB_EXECUTION_STALLED` event (validated at append-time).
+- When heartbeats resume, the server can append `JOB_EXECUTION_RESUMED` to return the job to `EXECUTING`.
+
+## Events
+
+### `JOB_HEARTBEAT` (robot-signed)
+
+Constraints:
+
+- Only allowed during `EXECUTING`, `ASSISTED`, `STALLED`, or `ABORTING_SAFE_EXIT`.
+- `payload.t` must equal `event.at` (single source of time).
+- `payload.robotId` must match `event.actor.id`.
+
+Payload:
+
+```json
+{
+  "jobId": "job_123",
+  "robotId": "rob_1",
+  "t": "2026-01-26T00:00:00.000Z",
+  "stage": "TASK",
+  "progress": 3,
+  "assistRequested": false
+}
+```
+
+### `JOB_EXECUTION_STALLED` (server-signed)
+
+Constraints:
+
+- Only allowed during `EXECUTING` or `ASSISTED`.
+- Must be past the tier policy `stallAfterMs` threshold for the projected `lastHeartbeatAt` (append-time enforced).
+- Includes a policy snapshot so stalls are auditable even if defaults evolve later.
+
+Payload (reference-only, no media):
+
+```json
+{
+  "jobId": "job_123",
+  "robotId": "rob_1",
+  "detectedAt": "2026-01-26T00:05:00.000Z",
+  "reason": "NO_HEARTBEAT",
+  "lastHeartbeatAt": "2026-01-26T00:01:00.000Z",
+  "policy": { "heartbeatIntervalMs": 60000, "stallAfterMs": 180000 }
+}
+```
+
+### `JOB_EXECUTION_RESUMED` (robot- or server-signed)
+
+Constraints:
+
+- Only allowed from `STALLED`.
+- If server-signed, the server must have observed a post-stall heartbeat (append-time enforced).
+
+## Policy
+
+The current default policy is tier-driven and deterministic:
+
+- `heartbeatIntervalMs` per environment tier
+- `stallAfterMs = 3 * heartbeatIntervalMs`
+
+See `src/core/liveness.js`.
+
+## Ops hook (“liveness tick”)
+
+The server uses an internal tick (`api.tickLiveness()`) to scan active jobs and append stall/resume events through the normal append pipeline (no direct state mutation).
+
+Outbox side-effects (stubs for now):
+
+- `JOB_STATUS_CHANGED` when a stall/resume changes the job status
+- `ESCALATION_NEEDED` when `requiresOperatorCoverage` is true

package/docs/MVP_BUILD_ORDER.md

@@ -0,0 +1,36 @@
+# MVP Build Order (sprint-sized)
+
+This is the recommended implementation order for a narrow “managed environment” wedge.
+
+## Sprint 1: Core spine
+
+- Define job state machine + transition validation.
+- Append-only event log with hash chaining.
+- In-memory prototype API (create job, append event, replay).
+- Minimal robot registration and heartbeat.
+
+## Sprint 2: Booking + dispatch
+
+- Quote object + booking workflow (hold/escrow stub).
+- Deterministic matching scorer (capability + trust tiers).
+- Reservation + idempotency keys.
+- Basic replanning hooks (robot unavailable → re-match).
+
+## Sprint 3: Assist + incident workflow
+
+- Operator assist start/end events.
+- Incident taxonomy and automatic evidence bundling triggers.
+- Job timeline replay view (ops API endpoints).
+
+## Sprint 4: Ledger correctness
+
+- Double-entry ledger with settlement splits.
+- Refund and partial completion accounting.
+- Reconciliation reports (per job, per owner).
+
+## Sprint 5: Skill packaging & certification tooling (internal)
+
+- Skill bundle format + verification.
+- Capability API stubs + robot adapter interface.
+- Certification checklist automation (static + sim harness hooks).
+

package/docs/ONCALL_PLAYBOOK.md

@@ -0,0 +1,39 @@
+# On-call Playbook (v0)
+
+## Top priorities
+
+1. Human safety
+2. Property safety
+3. Privacy compliance
+4. Service reliability
+5. Financial correctness
+
+## Standard incident response
+
+1. Identify affected job(s) and current state.
+2. If robot is active:
+   - move to safe state (stop / exit / dock) via operator console,
+   - revoke access plan if needed.
+3. Preserve evidence bundle (ensure it is generated and immutable).
+4. Communicate:
+   - requester notification (status + next step),
+   - owner/operator notification if dispatch needed.
+5. Classify incident and open claim if thresholds are met.
+6. Post-incident:
+   - tag failure mode,
+   - file regression test requirements,
+   - add monitoring/alert improvements.
+
+## “Stop the world” triggers
+
+- repeated safety incidents from a robot model or skill version
+- privacy policy violations (camera/sensor misuse)
+- ledger imbalance or payout correctness bug
+
+## Debug checklist
+
+- job timeline replay (events, transitions)
+- agent heartbeats and last known telemetry
+- operator action log
+- evidence bundle frames (minimal necessary)
+

package/docs/OPERATIONS_SIGNING.md

@@ -0,0 +1,20 @@
+# Operations: Signing in production
+
+Settld supports producing strictly verifiable bundles without storing private keys on disk by using a remote signer.
+
+## Recommended posture (hardened)
+
+- Use `settld-produce --signer remote` and keep private keys inside an HSM/KMS-backed signing service.
+- Keep `trust.json` (public trust anchors) in version control and rotate via PR.
+- In CI, use strict verification and archive `VerifyCliOutput.v1` JSON.
+
+## Remote signer
+
+See `docs/spec/REMOTE_SIGNER.md` for the RemoteSigner API contract.
+
+## Key rotation (high level)
+
+1. Add new key to signer service.
+2. Update trust anchors (governance root keys and/or time authorities) via PR.
+3. Produce bundles signed by the new key while allowing overlap.
+4. Deprecate old keys per your internal policy (and/or publish revocations as governance requires).