@arnilo/prism 0.2.5 → 0.2.7

package/docs/migration.md

@@ -1,5 +1,34 @@
 # Migration guide
 
+## 0.2.6 → 0.2.7 enterprise ERP production readiness (additive)
+
+Release **0.2.7** (plan 027) adds the enterprise ERP production-readiness primitives behind optional host-activated seams: the transactional outbox/inbox + bounded dispatcher, the durable saga compensation/reconciliation engine, multi-party separation-of-duties approvals, signed hash-chained audit export with WORM/SIEM sinks, field-level classification + fail-closed redaction, and the deterministic ERP invariant evals. **Additive-only: no exported declaration removed or changed, no persisted 0.2.6 shape repurposed.**
+
+New ERP tables use **separate forward-only migrations** (no down migrations exist; production rollback is roll-forward repair only):
+
+- `prism_erp_outbox` / `prism_erp_inbox` (migration `004_erp_messaging`, version 4) — transactional outbox/inbox with `FOR UPDATE SKIP LOCKED` claim, `ON CONFLICT DO NOTHING` idempotent append, claim-token CAS, and three partial indexes. Outbox append must run in the caller-owned `PoolClient` transaction with the business mutation (atomicity is the host's responsibility).
+- `prism_erp_approvals` (migration `005_erp_approvals`, version 5) — multi-party approval requests with decisions stored as JSONB, `FOR UPDATE` row locking for atomic quorum recomputation, rejection as any-party veto, expiry checked at every protected transition, and atomic grant consumption in the host transaction.
+
+Saga state persists as a surrogate `WorkflowCheckpointRecord` through the existing `WorkflowCheckpointAdapter` (private workflow id `__prism_saga__/<key>`) — no saga-specific SQL or 0.2.6 shape is repurposed. Audit export, field policy, and ERP invariant evals are stateless or in-memory and add no persisted shape. Secret-manager adapters (Vault/AWS/Azure/GCP) stay **deferred** behind the demand gate; no adapter ships and no ambient credential discovery is added.
+
+**Rollback notes.** Rollback = restore the 0.2.6 manifests/tag. The two new ERP migrations are forward-only; before downgrading, stop all 0.2.7 workers (outbox dispatcher, saga engine, audit exporter) and drop or ignore the `prism_erp_outbox`/`prism_erp_inbox`/`prism_erp_approvals` tables (they hold no 0.2.6 data). No 0.2.6 persisted shape changed, so an ordinary downgrade is store-safe; the added exports and ERP tables simply disappear. **"ERP production ready" remains blocked until the 0.3.0 live-service matrix is recorded** — this release adds the primitives and the protected journey evidence, not the live-service matrix.
+
+## 0.2.5 → 0.2.6 durable recovery, workspaces, and coding-agent readiness (additive)
+
+Release **0.2.6** (plan 026) adds the coding-agent readiness capabilities behind optional host-activated seams: host-selected PTY backends, the indexed/semantic repository-search seam, the ownership-scoped multi-repository/worktree lifecycle, durable process/ACP recovery, and the patch-review/diagnostics workflow. **Additive-only: no exported declaration removed or changed, no persisted 0.2.5 shape repurposed.**
+
+New durable records use **separate versioned checkpoint namespaces**, never the 0.2.5 shapes:
+
+- `prism.coding-agent.process.v1` (schemaVersion 1) — managed-process recovery records. Readers reject unknown schema versions and corrupt/foreign records fail closed (dropped, never recovered).
+- `prism.coding-agent.workspace.v1` (schemaVersion 1) — coding workspace lifecycle records.
+- `prism.coding-agent.cancel.v1` (schemaVersion 1) — durable ACP run-cancel markers.
+
+`CodingCheckpointMetadata` (schemaVersion 1, `prism.coding-agent`) is **never silently repurposed**; 0.2.5 readers reject unknown schema versions as before.
+
+**ACP active-run references (Task 5 decision: additive optional field).** `PersistedAcpSession` gains an optional bounded `activeRun` ref (frozen 512-byte cap) recorded while a durable run is live. The decision recorded here: an additive optional field, not a separate recovery namespace, because the ref is advisory metadata — the authoritative run status is always re-queried from `AgentRunLifecycle.status` at restore time, and 0.2.5 hosts safely ignore the field. `PersistedAcpSession.activeRun` stays optional; 0.2.5 records remain readable and a 0.2.5 host reading a 0.2.6 record does not lose required recovery state (the run state itself lives in the existing `prism.agent-run` records, which are untouched).
+
+**Downgrade to 0.2.5** is safe only after stopping 0.2.6 workers/replicas and marking any live 0.2.6 process/workspace records `unknown` (their leases expire within TTL); durable state never serializes a PTY fd, browser context, process object, controller, pending promise, raw terminal output, env, token, or credential, and no exact-process-survival claim is made (attach-if-attested, otherwise unknown).
+
 ## 0.2.4 → 0.2.5 maintainability and bounded performance (no migration)
 
 Release **0.2.5** (plan 025) is the maintainability-and-bounded-performance cut: the six remaining implementation god-modules split into cohesive internal family files behind preserved barrels (compat-preserving, no `exports`-map subpath), 21 pure persistence helpers moved into the dependency-free `session-store-codecs` package (ownership scope/assertion, checkpoint stale/encode/decode, branch cursors, lifecycle quota/reason/page-limit, search metadata/clipping, deepFreeze/string-array/throwIfAborted, feedback row mapping), the quadratic per-push `Buffer.concat` loops in language framing and tar parsing became chunk-array readers (linear; caps and fail-closed overflow byte-identical), two internal dead type aliases removed (`PostgresPersistenceCloseOptions`, `SqlitePersistenceCloseOptions` — never re-exported from their adapter indexes), and 76 behavior-backed coverage regressions closed the low-coverage core areas (core 91.43/84.80/91.60 lines/branches/functions). **No runtime contract change and no migration**: no exported declaration was removed or changed (the plain reviewed compat gate at 0.2.5 shows the version literal plus 105 additive internal-helper exports), no persisted shape/schema/default/behavior changed, no new runtime dependency. Store compatibility with 0.2.4: **compatible in both directions** — no migration step; rollback = restore the 0.2.4 manifests/tag (stores never change; the added exports disappear on downgrade). The 20 dead-but-compat-tracked exports deferred from Task 4 are the 0.3.0 breaking-cut removal list (see `docs/_evidence/phase25-dead-exports-triage.md`).

package/docs/operations.md

@@ -0,0 +1,104 @@
+# Operations runbook: high availability, failover, and fencing
+
+## What it does
+
+This page is the operator runbook for the high-availability story proven by plan 027 Task 6: two replicas can serve, inspect, cancel, resume, and reconcile durable ACP/workflow/saga/outbox/export operations after either replica dies. Correctness never depends on a dead process's in-memory registry — it comes from the durable `LeaseStore` (owner, token, fencing counter, expiry, renewal), the `CheckpointStore` (version CAS plus monotonic fencing token), and idempotent side-effect sinks such as the ERP outbox (`ON CONFLICT DO NOTHING` on a stable message id). The two-process proof is `scripts/phase27-ha-worker.mjs` orchestrated by `scripts/phase27-ha.test.mjs`, which records exact commands, process IDs, injected failures, timings, and durable final states in `docs/_evidence/phase27-ha-evidence.json`.
+
+## When to use it
+
+- Before running any multi-replica deployment of the server, workflow coordinator, saga runner, ACP host, or enterprise dispatcher — read the local-registry limitations and the lease/fence model.
+- When an operator or on-call engineer sees a hung lease, an uncertain commit, or a split-brain suspicion: follow "Failover procedure" and "Uncertain commits" below before touching anything.
+- When sizing leases: the failover ceiling is lease TTL plus the peer's acquisition poll interval; the drill asserts `failoverMs <= ttlMs + 5000`.
+
+## Inputs / request
+
+- A `LeaseStore` and `CheckpointStore` backed by the same durable store (PostgreSQL through `createPostgresPersistence`, or the corresponding production adapter). Lease keys carry an ownership scope (tenant/account/user) that is part of the trust boundary.
+- Operations that need a leader: `acquireLease({ namespace, key, ownerId, ttlMs })` returns a lease with `token` and monotonic `fencingToken`, or `null` while another owner holds it.
+- Durable progress: `saveCheckpoint({ namespace, key, version, expectedVersion, fencingToken, value })` — versions strictly increase, `expectedVersion` must match the current version, and a lower or absent fencing token can never replace a fenced record.
+- Idempotent side effects: give every external effect a stable id (ERP outbox `messageId` is the designed carrier) so replay is safe.
+
+## Outputs / response / events
+
+- A lease record: `{ namespace, key, ownerId, token, fencingToken, acquiredAt, expiresAt, updatedAt }`. Expired rows retain their fencing counter; the next owner inherits `fencingToken + 1`.
+- A checkpoint record: `{ namespace, key, version, fencingToken?, value, createdAt, updatedAt }`. Cursor/value changes are CAS-committed; a peer can replay an unfinished step but can never skip ahead or move the cursor backward.
+- Failover timing: the drill reports `failoverMs` (wall time between the owner's death and the peer's acquisition) and asserts it against the frozen ceiling.
+
+## Request/response example
+
+```ts
+const lease = await stores.leases.tryAcquireLease({
+  namespace: "erp.ops", key: "invoice-42", ownerId: "worker-b", ttlMs: 30_000,
+});
+if (!lease) return "another replica owns invoice-42";
+await stores.checkpoints.saveCheckpoint({
+  namespace: "erp.ops", key: "invoice-42",
+  version: 3, expectedVersion: 2, fencingToken: lease.fencingToken,
+  value: { cursor: 2, steps: ["reserve", "charge"] },
+});
+// Side effect with a stable id (idempotent replay):
+await outbox.append(client, { tenantId, messageId: "pay-t/invoice-42/charge", topic: "erp.payment.requested", payload });
+await stores.leases.releaseLease({ namespace: "erp.ops", key: "invoice-42", ownerId: "worker-b", token: lease.token });
+```
+
+## Implementation example
+
+```sh
+# Protected two-replica drill (requires PRISM_TEST_POSTGRES_URL; Docker image
+# postgres:16-alpine is the local stand-in). Recorded evidence lands in
+# docs/_evidence/phase27-ha-evidence.json.
+`PRISM_TEST_POSTGRES_URL` set to the protected connection string (locally a disposable `postgres:16-alpine` container): `node --test scripts/phase27-ha.test.mjs`
+```
+
+The drill: worker A acquires, heartbeats, commits the charge effect into the
+outbox, and is SIGKILLed inside the window between the effect commit and its
+final cursor save. Worker B (separate process, own pool, no access to A's
+registry) reads the durable state, waits out the lease expiry, acquires,
+replays the uncertain commit idempotently (outbox count stays 1), finishes,
+and releases. A stale-fence/stale-revision write and an old-token renewal are
+rejected; two simultaneous acquisitions yield exactly one owner; a foreign
+tenant's reads, writes, and lease takeover all fail closed.
+
+## Extension and configuration notes
+
+- Lease TTL is the availability knob: too short spams contention, too long
+  delays failover. The frozen drill ceiling is `ttlMs + 5000` ms; renew at
+  `ttlMs / 3` (the workflow coordinator, saga engine, and this drill all
+  follow this pattern).
+- Local in-memory registries (workflow active-run map, coordinator active
+  map, A2A live-task registry, ACP session registry, coding-agent sessions,
+  RPC active runs) are optional fast paths only. On restart, every component
+  reloads authority, status, and cursors from durable stores; a killed
+  replica's registry is never required to make progress.
+- SIEM/alerting: emit owner/fence/lease-age/state metadata only — never tenant
+  payloads, tokens, or credentials. Metrics to watch: lease-acquire latency,
+  fence counter jumps (a jump means a takeover happened), and outbox pending
+  depth.
+
+## Security and performance notes
+
+- Fencing is enforced at the store: a stale owner's write fails with
+  `ERR_PRISM_CHECKPOINT_CONFLICT` (stale version, failed CAS, or stale
+  fencing token), and a stale token's renewal returns `null`. There is
+  intentionally no "force unlock" operation — deleting a lease row manually
+  bypasses fencing and can cause split-brain writes; never do it.
+- Tenant ownership is checked on every durable read/write; cross-tenant
+  reads, saves, and lease acquisitions fail closed with ownership-mismatch
+  errors.
+- An uncertain commit (side effect landed, cursor not advanced) is resolved
+  by replaying the effect with its stable id — never by guessing. Reload
+  durable state before any retry; retries that skip the reload risk
+  overwriting a peer's fenced progress.
+- Failover is bounded but not instantaneous: the peer cannot acquire until
+  the lease expires, so recovery time is at least the remaining TTL.
+  Performance is linear in record size; the drill records contention/latency
+  with bounded, jittered acquisition polls (no hot loops) and reports the
+  measured numbers in the evidence JSON.
+
+## Related APIs
+
+- `LeaseStore` / `CheckpointStore` — the durable contracts this runbook relies on.
+- `createPostgresPersistence` — the PostgreSQL adapter used by the drill.
+- `ErpOutboxStore` — the idempotent side-effect carrier used to make replay safe.
+- `createWorkflowCoordinator` and `defineSaga`/`runSaga`/`resumeSaga` — higher-level consumers with the same fencing/cursor semantics.
+- `scripts/phase27-ha-worker.mjs` / `scripts/phase27-ha.test.mjs` — the reproducible drill; `docs/_evidence/phase27-ha-evidence.json` — the recorded run.
+- [Signed, hash-chained audit export](audit-export.md) — the cursor/CAS pattern applied to audit exports.

package/docs/policy-and-audit.md

@@ -118,6 +118,40 @@ Policy is optional. Hosts wire `record*` helpers or `evaluateAndAppend` at permi
 - The OPA decision fetch (0.2.1) is DNS-pinned through the core `pinnedFetch` primitive: one resolve per request, every resolved address SSRF-checked before the connect (rebinding defense), redirects rejected outright, timeouts/retries unchanged, and private-answer denials surface `MediaContentError` (`ssrf_denied`) rather than a transport error.
 - Export never full-scans: page size is capped; raise hard caps only with Phase 8 freeze + tests + docs updates.
 
+## Multi-party approvals
+
+Immutable approval requests carry an action digest, requester, and required roles/quorum; verified host identities vote through an explicit `ApprovalAuthority`. Prism records decisions and enforces separation-of-duties, expiry, revocation, bounded delegation, rejection, and policy-revision pins — it never resolves identities or roles itself.
+
+| API / field | Meaning |
+| --- | --- |
+| `ApprovalAuthority` | Host-owned `policyRevision` + `resolveRoles(identity, request)` returning role grants (and delegation chains) |
+| `ApprovalRequest` | Immutable request: `action {kind, digest}`, `requirements [{role, quorum}]`, `separateFromRequester`, `expiresAt`, `delegationMaxDepth` |
+| `ApprovalRecord` | Request + `status` (`pending/approved/rejected/revoked/consumed`) + `revision` + immutable `decisions` + `policyRevision` |
+| `ApprovalStore.create/decide/revoke/consume/get/query` | Durable transitions; every transition records an `auditRef` |
+| `createMemoryApprovalStore({ authority })` | Single-process reference adapter sharing the pure transition logic |
+| `createPostgresApprovalStore({ pool, schema, authority })` | Cross-replica storage (migration `005_erp_approvals`, `@arnilo/prism-enterprise-postgres`) |
+
+Quorum rules:
+
+- Each requirement needs `quorum` **distinct approved principals** through that role. Same principal voting the same role twice is idempotent; changing a vote is a conflict.
+- A rejection is terminal and vetoes the request (`rejected`), so `consume` always denies.
+- `separateFromRequester: true` denies the requester (and any authority chain deriving from the requester) from deciding.
+- `delegationMaxDepth` bounds the persisted delegation chain (delegator first); grants cannot outlive the request, leave the tenant, or widen the action.
+- Pin: `ApprovalAuthority.policyRevision` must equal the record's revision; a policy bump invalidates outstanding approvals (release denied).
+
+Revocation semantics: `revoke` is only valid for `pending`/`approved` grants, is taken by a verified tenant actor with an `auditRef`, and is terminal. After consumption, revocation cannot undo the effect — the record stays `consumed` as provenance, and reconciliation is host work.
+
+Operator audit queries: `query({ tenantId, status })` pages by `(created_at, id)`; `get({ tenantId, requestId })` returns full immutable decisions with grants and delegation chains. Every decision and manual transition carries the host `auditRef`.
+
+```sql
+-- pending approvals that never released (example host view)
+SELECT id, policy_revision, expires_at, decisions
+FROM prism.prism_erp_approvals
+WHERE status = 'pending' AND expires_at < now();
+```
+
+Hosts own identity verification and the role source; Prism does not certify NIST compliance. NIST SP 800-53 AC-5 (separation of duties) and AC-6 (least privilege) are control guidance only, not certification claims.
+
 ## OPA external policy adapter (`@arnilo/prism-policy/opa`, 0.0.28)
 
 Optional `createOpaPolicyEvaluator` evaluates `PolicyEvaluateRequest`s against a host-pinned OPA REST endpoint (`POST /v1/data/<path>` with `{"input": <document>}`) and returns a core `PolicyEvaluator` for `evaluateAndAppend`. Native `fetch` only; no OPA SDK dependency.

package/docs/process-sessions.md

@@ -17,7 +17,7 @@
 
 ## When to use it
 
-Use when a host needs attachable long-running processes (watch modes, language servers, interactive CLIs) that one-shot `shell` cannot model. Do not use as a job-control language or PTY emulator — `pty: true` fails closed with `ERR_PRISM_PROCESS_PTY_UNSUPPORTED` until a platform capability is wired. Pass a sandbox with `startProcess` for contained long-running work; omit `sandbox` for native spawn.
+Use when a host needs attachable long-running processes (watch modes, language servers, interactive CLIs) that one-shot `shell` cannot model. Do not use as a job-control language. `pty: true` (host-selected PTY) requires a `ptyBackend` passed to `createProcessSessions`; without one it fails closed before spawn with `ERR_PRISM_PROCESS_PTY_UNSUPPORTED`. Pass a sandbox with `startProcess` for contained long-running work; omit `sandbox` for native spawn.
 
 ```ts
 import { createProcessSessions } from "@arnilo/prism-coding-agent";
@@ -43,6 +43,7 @@ await sessions.dispose();
 | `ownership?` | `OwnershipScope` | Default owner key for sessions. |
 | `identity?` | `AgentIdentity` | When ownership omitted, owner key projects from identity. |
 | `sandbox?` | `ProcessSandboxBackend` | When set: require `startProcess` or fail closed; `status` loss → all running → `unknown`. |
+| `ptyBackend?` | `ProcessPtyBackend` | Host-selected interactive-terminal backend. `pty: true` delegates only here; absent backend → `ERR_PRISM_PROCESS_PTY_UNSUPPORTED` before spawn. Host supplies the PTY engine (e.g. node-pty); Prism never depends on one. |
 
 `ProcessStartRequest`:
 
@@ -51,7 +52,8 @@ await sessions.dispose();
 | `command` / `args?` | Executable + argv (not a shell string). |
 | `cwd?` | Relative/absolute path contained under registry `cwd`. |
 | `env?` | Extra env merged onto `process.env` (never in fingerprint). |
-| `pty?` | Default false; unsupported → `ERR_PRISM_PROCESS_PTY_UNSUPPORTED`. |
+| `pty?` | Default false. `true` requires the `ptyBackend` host option (delegated only to it); unsupported host → `ERR_PRISM_PROCESS_PTY_UNSUPPORTED` before spawn. |
+| `terminal?` | `{ columns, rows, term? }` for `pty: true`; defaults `120 × 40`, `xterm-256color`. Bounds: columns 1–120 (hard 500), rows 1–40 (hard 200), TERM ≤ 64 bytes (hard 256). |
 | `lifetimeMs?` | Bounded by `maxLifetimeMs`. |
 | `owner?` | Override owner string. |
 | `releaseOnCancel?` | If true, `cancelOwned` releases instead of killing. |
@@ -68,10 +70,23 @@ await sessions.dispose();
 | `cancelOwned(owner)` | Kill (default) or release owned running sessions. |
 | `markUnknown` | Backend-loss terminal state; never fabricates `exitCode`. |
 | `reconcile()` | Host resume: mark every running/starting session `unknown` (O(sessions)). |
+| `resize?` | Only when `ptyBackend.capabilities.resize` is true: bounded `{ columns, rows }` routed to the live terminal. |
 
 Events: `process_started`, `process_exited`, `process_killed`, `process_released`, `process_expired`, `process_unknown`.
 
-Errors: `ERR_PRISM_PROCESS_POLICY`, `ERR_PRISM_PROCESS_OWNERSHIP`, `ERR_PRISM_PROCESS_STATE`, `ERR_PRISM_PROCESS_LIMIT`, `ERR_PRISM_PROCESS_PTY_UNSUPPORTED`, `ERR_PRISM_PROCESS_UNSUPPORTED`.
+Errors: `ERR_PRISM_PROCESS_POLICY`, `ERR_PRISM_PROCESS_OWNERSHIP`, `ERR_PRISM_PROCESS_STATE`, `ERR_PRISM_PROCESS_LIMIT`, `ERR_PRISM_PROCESS_PTY_UNSUPPORTED`, `ERR_PRISM_PROCESS_PTY_BACKEND`, `ERR_PRISM_PROCESS_PTY_LIMIT`, `ERR_PRISM_PROCESS_UNSUPPORTED`.
+
+## Host-selected PTY backend contract
+
+`ptyBackend` is the host's interactive-terminal capability (plan 026 Task 1):
+
+- **Delegation only.** `pty: true` starts a session exclusively through `ptyBackend.startPty`; the native spawn path never allocates a terminal. A missing backend or one without `startPty` fails closed before any spawn (`ERR_PRISM_PROCESS_PTY_UNSUPPORTED`). The non-PTY path is byte-compatible with the 0.2.5 baseline.
+- **Contract.** `startPty({ file, args, cwd, env, columns, rows, term, onData })` returns `{ metadata?, write, signal, kill, release, wait, resize? }`. `capabilities.resize` is explicit — `resize` on the session exists only when declared; never duck-typed. `wait()` resolves on process exit (and rejects on backend loss); the host stops delivering `onData` once the session is terminal.
+- **Terminal data is untrusted output.** Control sequences are never parsed or emulated; the host (or an attached terminal client) interprets them. Input is raw terminal bytes; NUL is rejected with a policy error, other control bytes pass through as terminal data.
+- **Bounded attach.** `startPty` must settle within `maxPtyAttachTimeoutMs` (30 s default, 120 s hard); overflow removes the session record and fails with `ERR_PRISM_PROCESS_PTY_LIMIT`. Resize is rate-limited (60/min default, 600 hard) and fails with the same code. Backend `metadata` is bounded (`maxPtyBackendMetadataBytes`, 4 KiB default / 16 KiB hard).
+- **Backend loss.** A throwing `startPty` or a lost `wait()` surfaces as `ERR_PRISM_PROCESS_PTY_BACKEND` with a generic message (backend error text is never embedded); the session becomes `unknown` with `exitCode: null` — never fabricated.
+- **Parity.** Policy, cwd/ownership, cancel/expiry sweeps, input/lifetime/output caps, command fingerprint, events, and redaction behave exactly as non-PTY sessions; PTY sessions count against `maxSessions`.
+- **Recovery caveat (phase 26, task 5).** PTY sessions are not durable across restart: no serialized terminal fd or raw output is ever persisted. Restart recovery reports such sessions `unknown` unless a host `recoveryBackend` re-attaches them; there is no exact-process-survival claim.
 
 ## Request/response example
 
@@ -123,6 +138,46 @@ await sessions.dispose();
 - Command fingerprint is SHA-256 of `[command, ...args]` only (no env).
 - Docker reference adapter does not implement `startProcess` yet — fail closed until a capable runtime is wired.
 
+## Durable process recovery (plan 026 Task 5)
+
+Optional, host-activated: pass `checkpoints` + `leases` + `ownerId` (all three
+together; a partial recovery configuration fails closed at construction) and
+optionally `recoveryBackend` + `recoveryLimits`. With durability configured:
+
+- Intent is persisted BEFORE spawn into the versioned namespace
+  `prism.coding-agent.process.v1` (schemaVersion 1, category `coding-process`),
+  and every lifecycle transition (running, exited, killed, released, expired,
+  unknown) is a CheckpointStore CAS write under a monotonic LeaseStore fencing
+  token. Transition writes are serialized per record so CAS order never inverts
+  on slow stores.
+- `recover()` reconciles durable records against the live registry:
+  - records already live here report `attached` without mutation;
+  - terminal records report `terminal` with their exit code;
+  - `starting|running` records attach-if-attested: a `backendRef` (opaque
+    non-secret ref surfaced by a PTY/sandbox handle's optional `ref`) plus a
+    host `recoveryBackend.attach(ref)` (bounded attach timeout 30 s default /
+    120 s hard) may reattach; otherwise the record atomically becomes `unknown`
+    with exit code null — no PID probing, no fabricated exit, no duplicate
+    spawn. `recover()` without durability configured throws
+    `ERR_PRISM_RECOVERY_UNSUPPORTED`.
+- Recovered sessions are live registry sessions: input/signal/kill/release/
+  resize/wait reach the attached backend; output streaming is not re-established
+  after a restart (the host backend owns any buffered output behind its ref).
+- Replica coordination: every mutation takes a per-record lease (30 s default /
+  300 s hard); a crashed replica's lease lapses within TTL, a live one renews
+  on transitions and releases on terminal transitions. A held lease makes the
+  second replica report `unknown` without touching the record; CAS/fence
+  conflicts fail closed with `ERR_PRISM_RECOVERY_FENCE`.
+- `cancelOwned` after recovery either reaches the attached backend or records
+  the durable record unknown — never a fabricated exit.
+- Durable records are metadata only: no child/PTY handle, controller, promise,
+  raw output, env, token, or credential is ever serialized; forbidden fields,
+  corrupt, oversized, or cross-tenant records fail closed (dropped, never
+  recovered). Records are capped (32 default / 128 hard; oldest terminal
+  records evict beyond the cap; running records are never evicted).
+- Errors: `ERR_PRISM_RECOVERY_UNSUPPORTED` / `_LIMIT` / `_OWNERSHIP` / `_FENCE`
+  / `_UNKNOWN` / `_UNTRUSTED` / `_TIMEOUT` (`ProcessRecoveryError`).
+
 ## Security and performance notes
 
 | Cap | Default | Hard |