@cavelang/cli 0.27.3 → 0.29.0

package/dist/src/cli.js

@@ -1,27 +1,31 @@
 /**
  * `cave` command implementation — pure functions from parsed arguments to
- * `{ code, out, err }`, so tests can call commands directly and `main.ts`
- * stays a thin dispatcher.
+ * `{ code, out, err }`, so tests can call commands directly while
+ * `dispatch.ts` gives every command one awaited process lifecycle.
  *
  * Commands:
  *
  * - `cave parse [file]` — lint / dump the AST (`--json`)
- * - `cave highlight [file]` — ANSI syntax colors (async, routed in `main.ts`)
+ * - `cave highlight [file]` — ANSI syntax colors (async)
  * - `cave add [--db <path>] [file…]` — ingest into a store (`--strict`, `--check`)
  * - `cave query [--db <path>] '<pattern>'` — CAVE-Q (`--json`, `--all`, `--aliases`, `--as-of`, `--resolve`)
  * - `cave resolve [--db <path>]` — contested facts under the §26 policy (`--aliases`, `--policy`, `--json`)
  * - `cave derive [--db <path>] [rules.cave…]` — fire rules (`--dry-run`, `--full`, `--list`, `--retract`)
  * - `cave act [--db <path>] <name> [param=value…]` — execute an action (spec §25; `--declare`, `--list`, `--retract`)
- * - `cave automate [--db <path>]` — the event-driven loop (spec §29; async, routed in `main.ts`)
+ * - `cave automate [--db <path>]` — the event-driven loop (spec §29; async)
  * - `cave check [--db <path>]` — knowledge health report (`--stale`, `--json`)
- * - `cave suggest-alias [--db <path>]` — same-entity candidates (spec §27; async, routed in `main.ts`)
+ * - `cave backup [--db <path>] --out <path>` — exact verified SQLite snapshot
+ * - `cave restore <snapshot> --db <path>` — verify and atomically restore a snapshot
+ * - `cave generate [--db <path>]` — versioned TypeScript client from EXPECTS declarations
+ * - `cave suggest-alias [--db <path>]` — same-entity candidates (spec §27; async)
  * - `cave sync [--db <path>] <source>` — merge another store by row identity (spec §28; `--dry-run`, `--as`, `--into`)
  * - `cave export [--db <path>]` — canonical text out (`--current`, `--tx`)
- * - `cave serve [--db <path>]` — the human read surface in a browser (spec §30; async, routed in `main.ts`)
+ * - `cave serve [--db <path>]` — the human read surface in a browser (spec §30; async)
  * - `cave report [--db <path>] [template.md…]` — cited markdown from CAVE-Q template blocks (spec §31)
- * - `cave connect [--db <path>] <source>` — deterministic structured ingestion (async, routed in `main.ts`)
- * - `cave eval <suite...>` — golden-fixture extraction/query/reconstruction evals (async, routed in `main.ts`)
- * - `cave reconstruct [--db <path>] <seed...>` — §18 reconstruction from seed cues (async, routed in `main.ts`)
+ * - `cave connect [--db <path>] <source>` — deterministic structured ingestion (async)
+ * - `cave eval <suite...>` — golden-fixture extraction/query/reconstruction evals (async)
+ * - `cave reconstruct [--db <path>] <seed...>` — §18 reconstruction from seed cues (async)
+ * - `cave doctor [--db <path>]` — read-only runtime, installation, and store diagnostics
  * - `cave demo` — the cave-loop multi-hop recovery demo
  * - `cave version` — print the cave version
  * - `cave help [command]` — overview, or one command's help
@@ -29,21 +33,51 @@
  * `file` defaults to stdin (`-`); `--db` defaults to `$CAVE_DB`, then
  * `cave.db`. Every command answers `--help` with options and examples.
  */
-import { readFileSync, statSync, writeFileSync } from 'node:fs';
+import { readFileSync, readSync, statSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 import { Version } from '@cavelang/core';
 import { parseDocument } from '@cavelang/parser';
 import { Registry, standardRegistry } from '@cavelang/canonical';
-import { defaultDbPath, open } from '@cavelang/store';
-import { query as caveQuery } from '@cavelang/query';
-import { check as caveCheck, defaultMinScore, defaultStaleDays, gatedIngest, judgePrompt, parseJudgeReply, suggestAliases, writeSuggestions } from '@cavelang/shape';
-import { declareRules, defaultMaxPasses, defaultMinConf, derive, listRules, retractRule } from '@cavelang/rules';
-import { act, declareActions, listActions, retractAction } from '@cavelang/act';
-import { Demo, heuristicPolicy, llmPolicy, reconstruct, reconstructAsync, shellComplete, sqliteStore } from '@cavelang/loop';
-import { labelOf, sanitizeLabel, syncFile, syncText } from '@cavelang/sync';
-import { report as caveReport } from '@cavelang/view';
-import { emitClaim, txOfLine } from '@cavelang/canonical';
+import { Sensitivity, backup as backupStore, defaultDbPath, open, restoreBackup, verifyBackup } from '@cavelang/store';
+import { defaultLimit as defaultQueryLimit, page as caveQueryPage } from '@cavelang/query';
+import { check as caveCheck, defaultMinScore, defaultStaleDays, gatedIngest, judgePrompt, parseJudgeReply, generateClient, suggestAliases, writeSuggestions } from '@cavelang/cli/shape';
+import { declareRules, defaultMaxPasses, defaultMinConf, derive, listRules, retractRule } from '@cavelang/cli/rules';
+import { act, declareActions, listActions, retractAction } from '@cavelang/cli/act';
+import { Demo, heuristicPolicy, llmPolicy, reconstruct, reconstructAsync, shellComplete, sqliteStore } from '@cavelang/cli/loop';
+import { labelOf, sanitizeLabel, syncFile, syncText } from '@cavelang/cli/sync';
+import { report as caveReport } from '@cavelang/cli/view';
+import { emitClaim } from '@cavelang/canonical';
+import { doctorCommand } from "./doctor.js";
+import { delegatedCommandNames } from "./commands.js";
+const storageRow = (value) => typeof value === 'object' && value !== null &&
+    typeof value['id'] === 'string' &&
+    typeof value['tx'] === 'string' &&
+    typeof value['claim_key'] === 'string' &&
+    typeof value['raw_line'] === 'string';
+/** Recursively replace storage rows in JSON reports with cave.claim/v1 records. */
+const stableJsonValue = (store, value) => {
+    if (storageRow(value)) {
+        const record = store.recordOf(value);
+        const ranked = value;
+        return typeof ranked['res_rank'] === 'number' ? {
+            ...record,
+            resolution: {
+                group: ranked['res_group'],
+                class: ranked['res_class'],
+                effectiveConfidence: ranked['res_conf'],
+                rank: ranked['res_rank'],
+            },
+        } : record;
+    }
+    if (Array.isArray(value))
+        return value.map(entry => stableJsonValue(store, entry));
+    if (typeof value === 'object' && value !== null) {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, stableJsonValue(store, entry)]));
+    }
+    return value;
+};
+const stableJson = (store, value) => JSON.stringify(stableJsonValue(store, value), undefined, 2);
 const ok = (out) => ({ code: 0, out, err: '' });
 const fail = (err, code = 1) => ({ code, out: '', err });
 export const usage = `cave — Compressed Atomic Verb Expressions
@@ -53,23 +87,27 @@ Usage:
   cave highlight [file...]                 print CAVE text with ANSI syntax colors
   cave add [--db <path>] [file...]         ingest into a store [--strict] [--check] [--no-prelude] [--no-src]
   cave import [--db <path>] [file...]      restore/merge from CAVE text (add without @src: stamping)
-  cave query [--db <path>] <pattern>       run a CAVE-Q pattern [--json] [--all] [--aliases] [--as-of <t>] [--at <t>] [--resolve] [--no-prelude]
+  cave query [--db <path>] <pattern>       run a bounded CAVE-Q page [--limit <n>] [--cursor <token>] [--json]
   cave resolve [--db <path>]               contested facts + winners (spec §26) [--aliases] [--policy] [--json]
   cave derive [--db <path>] [rules.cave..] declare + fire rules (spec §24) [--dry-run] [--full] [--list] [--retract <rule>]
   cave act [--db <path>] <name> [p=v...]   execute an action (spec §25) [--dry-run] [--no-check] [--hooks <file>]
   cave act --declare [file...]             declare actions from a CAVE document; --list / --retract <name> manage them
   cave automate [--db <path>]              event-driven loop (spec §29): new claims fire rules/actions/hooks/agent prompts [--once]
   cave check [--db <path>]                 knowledge health report (spec §20) [--stale <days>] [--json]
+  cave backup [--db <path>] --out <file>   exact verified SQLite snapshot [--force]
+  cave restore <snapshot> --db <path>      verify and atomically restore an exact snapshot [--force]
+  cave generate [--db <path>]              generate a typed client from EXPECTS [--out <file>] [--version <n>]
   cave suggest-alias [--db <path>]         propose same-entity ALIAS candidates (spec §27) [--min <s>] [--agent] [--write]
   cave sync [--db <path>] <source>         merge another store by row identity (spec §28) [--dry-run] [--as] [--into]
-  cave export [--db <path>] [--out <file>] emit canonical CAVE text [--current] [--tx] [--no-prelude]
-  cave serve [--db <path>]                 browse the store in a browser (spec §30) [--port <n>] [--host <a>]
-  cave report [--db <path>] [template...]  render cited markdown from a CAVE-Q template (spec §31) [--out <file>] [--resolve]
+  cave export [--db <path>] [--out <file>] emit filtered canonical CAVE text [--max-sensitivity <level>]
+  cave serve [--db <path>]                 browse a filtered store (spec §30) [--max-sensitivity <level>]
+  cave report [--db <path>] [template...]  render filtered cited markdown (spec §31) [--max-sensitivity <level>]
   cave mcp [--db <path>]                   serve the engine as an MCP server on stdio [--no-prelude]
   cave ingest [--db <path>] <globs/urls..> LLM-driven ingestion of files and web pages
-  cave eval <suite..> --agent '<command>'  golden-fixture extraction/query/reconstruction evals (items 9, 10)
+  cave eval <suite..> --agent '<command>'  golden-fixture extraction/query/reconstruction evals
   cave connect <source> --map <file>       deterministic structured ingestion (CSV/JSON/SQLite/URL, spec §23)
   cave reconstruct [--db <path>] <seed..>  reconstruct memory from seed cues (spec §18) [--agent] [--query] [--trace]
+  cave doctor [--db <path>]                diagnose runtime, installation, and store health [--hooks <file>] [--json]
   cave demo                                run the cave-loop reconstruction demo
   cave version                             print the cave version
   cave help [command]                      this text, or one command's options and examples
@@ -80,6 +118,25 @@ the repository root (section index in README.md).`;
 const dbHelp = `--db <path>    database file (default: $CAVE_DB, or cave.db)`;
 /** Per-command help, printed for \`cave <command> --help\` and \`cave help <command>\`. */
 export const commandHelp = {
+    doctor: `cave doctor — diagnose runtime, installation, and store health
+
+Usage:
+  cave doctor [--db <path>] [--hooks <file>] [--json]
+
+Options:
+  ${dbHelp}
+  --hooks <file>  validate an optional hooks JSON file
+  --json          emit the versioned cave.doctor/v1 report
+
+The command is read-only: it never creates or migrates a database and never
+runs hooks. Its output is safe to share — database and hooks paths, hook names
+and commands, URLs, and environment values are not included. Warnings such as
+a not-yet-created database exit 0; failed required checks exit 1.
+
+Examples:
+  cave doctor
+  cave doctor --db knowledge.db
+  cave doctor --hooks hooks.json --json`,
     parse: `cave parse — lint CAVE text, or dump the parsed document
 
 Usage:
@@ -152,23 +209,27 @@ file read as ordinary comments; to merge under the recorded row
 identity, use \`cave sync\` (spec §28.4).
 
 Examples:
-  cave export --db old.db --out backup.cave
+  cave export --db old.db --max-sensitivity restricted --out backup.cave
   cave import --db new.db backup.cave`,
     query: `cave query — run a CAVE-Q pattern against a store
 
 Usage:
-  cave query [--db <path>] <pattern> [WHERE <filter>] [--json] [--all] [--aliases] [--as-of <t>] [--at <t>] [--resolve] [--no-prelude]
+  cave query [--db <path>] <pattern> [WHERE <filter>] [--limit <n>] [--cursor <token>] [--json] [--all] [--aliases] [--as-of <t>] [--at <t>] [--resolve] [--no-prelude]
 
 Options:
   ${dbHelp}
-  --json         emit matches as JSON
+  --json         emit a versioned cave.query-page/v1 JSON object
+  --limit <n>    matches per page (default ${defaultQueryLimit}, maximum 1000)
+  --cursor <t>   continue the same frozen query snapshot
   --all          match all beliefs, not just current ones
   --aliases      resolve entities through current ALIAS claims (spec §13.6)
   --as-of <t>    resolve beliefs as of a past moment (spec §12.3): a date
                  (whole day included), a timestamp (whole second), or a
-                 transaction id — rows recorded later are invisible
+                 transaction id — rows recorded later are invisible;
+                 timestamps without an offset mean UTC
   --at <t>       anchor in valid time (spec §32.4): a date-like period
-                 (read as its start instant) or a timestamp. Claims whose
+                 (read as its start instant) or a timestamp (offset-less
+                 means UTC). Claims whose
                  time contexts — @2026-Q1 points, @2025..2028 ranges — do
                  not cover the instant are invisible; timeless claims
                  always match; trajectory values (20B -> 40B USD/yr)
@@ -324,7 +385,8 @@ Options:
   --no-prelude   open the store without the standard verb registry
 
 Reads the store against its own in-band EXPECTS declarations (spec §20.1)
-and reports shape violations, stale current beliefs, review candidates
+and reports actionable presence, #cardinality:one, and #unit:<unit>
+violations, stale current beliefs, review candidates
 (conf 0.3–0.7), alias disagreements (spec §13.6) and coverage stats.
 Exits 1 when violations exist; everything else is advisory.
 
@@ -332,6 +394,66 @@ Examples:
   cave check --db k.db
   cave check --db k.db --stale 30
   cave check --db k.db --json | jq '.violations'`,
+    backup: `cave backup — exact, verified SQLite snapshot (spec §13.2.2)
+
+Usage:
+  cave backup [--db <path>] --out <file> [--force]
+  cave backup --verify <file> [--sha256 <hex>]
+
+Options:
+  ${dbHelp}
+  --out <file>      destination snapshot (required when creating)
+  --force           atomically replace an existing snapshot
+  --verify <file>   verify integrity, foreign keys, schema and SHA-256 only
+  --sha256 <hex>    expected digest for --verify
+
+The source remains online. SQLite VACUUM INTO takes one consistent committed
+snapshot, including WAL-visible rows; CAVE writes to a temporary file,
+validates it, fsyncs it, then publishes it atomically. The summary SHA-256 is
+the restore verification token.
+
+Examples:
+  cave backup --db k.db --out backups/k.db
+  cave backup --verify backups/k.db --sha256 <hex>`,
+    restore: `cave restore — verify and atomically restore an exact SQLite snapshot (spec §13.2.2)
+
+Usage:
+  cave restore <snapshot> --db <path> [--force] [--sha256 <hex>]
+
+Options:
+  --db <path>       destination database (required)
+  --force           atomically replace an existing destination
+  --sha256 <hex>    require the recorded backup digest
+
+Stop every process using the destination first. Restore refuses WAL/SHM
+sidecars, verifies the input and copied temporary database, then publishes one
+atomic file. WAL, SHM, or rollback-journal sidecars cause a refusal. On
+failure the prior destination remains untouched.
+
+Example:
+  cave restore backups/k.db --db restored.db --sha256 <hex>`,
+    generate: `cave generate — deterministic TypeScript client from EXPECTS declarations (spec §20.4)
+
+Usage:
+  cave generate [--db <path>] [--out <file>] [--version <n>] [--no-prelude]
+
+Options:
+  ${dbHelp}
+  --out <file>   write the generated module instead of stdout
+  --version <n>  generated-client format version (default and currently
+                 supported: 1)
+  --no-prelude   open the store without the standard verb registry
+
+Current positive EXPECTS claims become TypeScript interfaces plus store-backed
+reader functions. #cardinality:one emits a scalar checked at runtime;
+attributes preserve text, number and unit; relation readers honor declared
+inverse verbs. The file embeds its format version and deterministic schema
+SHA-256. Conflicting declarations, invalid cardinality/unit tags, unsupported
+versions and generated type-name collisions fail without writing output.
+
+Examples:
+  cave generate --db k.db > cave-client.ts
+  cave generate --db k.db --out src/generated/cave-client.ts`,
     'suggest-alias': `cave suggest-alias — propose same-entity ALIAS candidates for review (spec §27)
 
 Usage:
@@ -414,38 +536,49 @@ a merge driver on *.cave files.
 Examples:
   cave sync --db main.db laptop.db
   cave sync --db main.db laptop.db --dry-run --json
-  cave export --db laptop.db --tx | cave sync --db main.db -
+  cave export --db laptop.db --tx --max-sensitivity restricted | cave sync --db main.db -
   cave sync --db a.db b.db && cave sync --db b.db a.db   # converge both
   cave sync --db work.db knowledge.cave --no-record      # checkout (§28.6)
   cave sync --db main.db knowledge.cave --as reorg-auth  # land the branch`,
     export: `cave export — emit canonical CAVE text from a store
 
 Usage:
-  cave export [--db <path>] [--out <file>] [--current] [--tx] [--no-prelude]
+  cave export [--db <path>] [--out <file>] [--current] [--tx]
+              [--max-sensitivity <level>] [--no-prelude]
 
 Options:
   ${dbHelp}
   --out <file>   write to a file instead of stdout — refused when it
                  names the store's own database file
-  --current      current beliefs only (skip superseded rows)
+  --current      current beliefs only (skip superseded rows); compacting
+                 view, not sanitization or selective erasure (spec §9.6)
+  --max-sensitivity <level>
+                 public, internal, confidential, or restricted (default
+                 internal; restricted includes complete portable history)
   --tx           precede every claim line with its ;@ transaction
                  annotation (spec §28.4) — the text carries row identity,
                  so cave sync replays it idempotently; other readers see
                  ordinary comments
   --no-prelude   open the store without the standard verb registry
 
+Retention: claim history is permanent. Retraction and --current do not
+guarantee erasure from the store, exports, peers, or backups (spec §9.6).
+
 Examples:
   cave export --db k.db
-  cave export --db k.db --out backup.cave
+  cave export --db k.db --out internal-export.cave
+  cave export --db k.db --max-sensitivity restricted --out complete-history.cave
   cave export --db k.db --current --out snapshot.cave
-  cave export --db k.db --tx | cave sync --db other.db -
-  cave export --db work.db --tx --out knowledge.cave    # the committed,
+  cave export --db k.db --tx --max-sensitivity restricted | cave sync --db other.db -
+  cave export --db work.db --tx --max-sensitivity restricted --out knowledge.cave
+                                                        # the committed,
                                     # reviewable store text (spec §28.6)`,
     report: `cave report — render cited markdown from a CAVE-Q template (spec §31)
 
 Usage:
   cave report [--db <path>] [template.md...] [--out <file>]
-              [--aliases] [--resolve] [--as-of <t>] [--at <t>] [--no-prelude]
+              [--aliases] [--resolve] [--as-of <t>] [--at <t>]
+              [--max-sensitivity <level>] [--no-prelude]
 
 Options:
   ${dbHelp}
@@ -458,6 +591,9 @@ Options:
   --at <t>       anchor every query in valid time (spec §32.4): claims
                  whose time contexts don't cover the instant drop out,
                  trajectory values render interpolated
+  --max-sensitivity <level>
+                 public, internal, confidential, or restricted (default
+                 internal; malformed/unknown claim labels fail closed)
   --no-prelude   open the store without the standard verb registry
 
 Reads stdin when no file (or \`-\`) is given. A template is ordinary
@@ -529,8 +665,28 @@ topic → fix over a small in-memory store.`,
 Usage:
   cave version`
 };
+const readStdin = () => {
+    const chunks = [];
+    const buffer = Buffer.allocUnsafe(64 * 1024);
+    const pause = new Int32Array(new SharedArrayBuffer(4));
+    for (;;) {
+        try {
+            const size = readSync(0, buffer, 0, buffer.length, null);
+            if (size === 0)
+                return Buffer.concat(chunks).toString('utf8');
+            chunks.push(Buffer.from(buffer.subarray(0, size)));
+        }
+        catch (error) {
+            if (error.code !== 'EAGAIN')
+                throw error;
+            // A pipe may be non-blocking on macOS. The producer is another process,
+            // so a short synchronous retry does not prevent it from making progress.
+            Atomics.wait(pause, 0, 0, 5);
+        }
+    }
+};
 const readInput = (files) => files.length === 0 || (files.length === 1 && files[0] === '-') ?
-    readFileSync(0, 'utf8') :
+    readStdin() :
     files.map(file => readFileSync(file, 'utf8')).join('\n');
 export const parseCommand = (argv) => {
     const { values, positionals } = parseArgs({
@@ -560,8 +716,7 @@ export const parseCommand = (argv) => {
 };
 /**
  * `cave highlight` — ANSI syntax colors from the tree-sitter grammar's own
- * highlight query. Async (the grammar WASM loads on first use), so `main.ts`
- * routes it separately, like `mcp` and `ingest`.
+ * highlight query. Async because the grammar WASM loads on first use.
  */
 export const highlightCommand = async (argv) => {
     const { positionals } = parseArgs({ args: [...argv], options: {}, allowPositionals: true });
@@ -577,8 +732,23 @@ export const highlightCommand = async (argv) => {
  * replays interchange text, which must preserve claim keys as exported,
  * so it never stamps.
  */
-const formatViolation = (violation) => `${violation.entity} missing ${violation.expectation.kind} ${violation.expectation.name} ` +
-    `(${violation.entity} IS ${violation.via}; ${violation.expectation.type} EXPECTS ${violation.expectation.name})`;
+const formatViolationProblem = (violation) => {
+    const { entity, expectation, actualCount, actualUnits } = violation;
+    if (actualCount === 0) {
+        return `${entity} missing ${expectation.kind} ${expectation.name}`;
+    }
+    const problems = [];
+    if (expectation.cardinality === 'one' && actualCount !== 1) {
+        problems.push(`${entity} has ${actualCount} ${expectation.kind}s ${expectation.name}; expected exactly one`);
+    }
+    if (expectation.unit !== undefined && actualUnits.some(unit => unit !== expectation.unit)) {
+        const units = actualUnits.map(unit => unit ?? '(none)').join(', ');
+        problems.push(`${entity} attribute ${expectation.name} has unit${actualUnits.length === 1 ? '' : 's'} ${units}; expected ${expectation.unit}`);
+    }
+    return problems.join('; ');
+};
+const formatViolation = (violation) => `${formatViolationProblem(violation)} ` +
+    `(${violation.entity} IS ${violation.via}; ${violation.expectation.row.raw_line})`;
 const ingestCommand = (name) => (argv) => {
     const { values, positionals } = parseArgs({
         args: [...argv],
@@ -647,6 +817,8 @@ export const queryCommand = (argv) => {
             'as-of': { type: 'string' },
             at: { type: 'string' },
             resolve: { type: 'boolean' },
+            limit: { type: 'string' },
+            cursor: { type: 'string' },
             'no-prelude': { type: 'boolean' }
         },
         allowPositionals: true
@@ -657,18 +829,22 @@ export const queryCommand = (argv) => {
     const pattern = positionals.join('\n');
     const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {});
     try {
-        const matches = caveQuery(store, pattern, {
+        const limit = values.limit === undefined ? defaultQueryLimit : Number(values.limit);
+        const result = caveQueryPage(store, pattern, {
             all: values.all === true,
             aliases: values.aliases === true,
             resolve: values.resolve === true,
+            limit,
+            ...values.cursor === undefined ? {} : { cursor: values.cursor },
             ...values['as-of'] === undefined ? {} : { asOf: values['as-of'] },
             ...values.at === undefined ? {} : { at: values.at }
         });
         if (values.json === true) {
-            return ok(`${JSON.stringify(matches, undefined, 2)}\n`);
+            return ok(`${JSON.stringify(result, undefined, 2)}\n`);
         }
+        const matches = result.matches;
         if (matches.length === 0) {
-            return ok('no matches\n');
+            return ok(`no matches\n${result.next === undefined ? '' : `next: ${result.next}\n`}`);
         }
         const lines = matches.map(match => {
             const bindings = Object.entries(match.bindings)
@@ -676,14 +852,14 @@ export const queryCommand = (argv) => {
                 .join('  ');
             // A fully bound pattern has no bindings to print; transitive matches
             // additionally carry no row — confirm with the pattern itself.
-            const line = bindings !== '' ? bindings : match.row?.raw_line ?? pattern.split('\n')[0];
+            const line = bindings !== '' ? bindings : match.claim?.claim.raw ?? pattern.split('\n')[0];
             // An interpolated trajectory shows its value at the anchor
             // (spec §32.4) — bindings already carry it in the value slot.
             return match.at !== undefined && bindings === '' ?
                 `${line} ; at ${values.at}: ${match.at.text}` :
                 line;
         });
-        return ok(`${lines.join('\n')}\n`);
+        return ok(`${lines.join('\n')}\n${result.next === undefined ? '' : `next: ${result.next}\n`}`);
     }
     catch (error) {
         return fail(`${error instanceof Error ? error.message : String(error)}\n`);
@@ -730,7 +906,7 @@ export const resolveCommand = (argv) => {
         }
         const contested = store.contested({ aliases: values.aliases === true });
         if (values.json === true) {
-            return ok(`${JSON.stringify(contested, undefined, 2)}\n`);
+            return ok(`${stableJson(store, contested)}\n`);
         }
         if (contested.length === 0) {
             return ok('no contested facts\n');
@@ -777,7 +953,7 @@ export const deriveCommand = (argv) => {
         if (values.list === true) {
             const rules = listRules(store);
             if (values.json === true) {
-                return ok(`${JSON.stringify(rules, undefined, 2)}\n`);
+                return ok(`${stableJson(store, rules)}\n`);
             }
             if (rules.length === 0) {
                 return ok('no rules\n');
@@ -839,7 +1015,7 @@ export const deriveCommand = (argv) => {
                 (declaration.prelude > 0 ? `, +${declaration.prelude} prelude claim(s)` : ''));
         }
         if (values.json === true) {
-            return { code: report.problems.length > 0 ? 1 : 0, out: `${JSON.stringify(report, undefined, 2)}\n`, err: err.join('\n') + (err.length > 0 ? '\n' : '') };
+            return { code: report.problems.length > 0 || !report.complete ? 1 : 0, out: `${stableJson(store, report)}\n`, err: err.join('\n') + (err.length > 0 ? '\n' : '') };
         }
         for (const problem of report.problems) {
             err.push(`${problem.subject}: ${problem.problems.join('; ')}`);
@@ -855,7 +1031,7 @@ export const deriveCommand = (argv) => {
         out.push(`derived${values['dry-run'] === true ? ' (dry run)' : ''}: ` +
             `+${report.appended} appended, ${report.updated} updated, ${report.retracted} retracted, ` +
             `${report.unchanged} unchanged (${report.passes} pass(es))`);
-        const hasProblems = report.problems.length > 0 || report.rules.some(rule => rule.problems.length > 0);
+        const hasProblems = !report.complete || report.problems.length > 0 || report.rules.some(rule => rule.problems.length > 0);
         return { code: hasProblems ? 1 : 0, out: `${out.join('\n')}\n`, err: err.length === 0 ? '' : `${err.join('\n')}\n` };
     }
     catch (error) {
@@ -943,7 +1119,7 @@ export const actCommand = (argv) => {
         if (values.list === true) {
             const actions = listActions(store);
             if (values.json === true) {
-                return ok(`${JSON.stringify(actions, undefined, 2)}\n`);
+                return ok(`${stableJson(store, actions)}\n`);
             }
             if (actions.length === 0) {
                 return ok('no actions\n');
@@ -983,7 +1159,7 @@ export const actCommand = (argv) => {
             ...hooksPath === undefined ? {} : { hooks: readHooks(hooksPath) }
         });
         if (values.json === true) {
-            return { code: report.ok && report.hook?.error === undefined ? 0 : 1, out: `${JSON.stringify(report, undefined, 2)}\n`, err: '' };
+            return { code: report.ok && report.hook?.error === undefined ? 0 : 1, out: `${stableJson(store, report)}\n`, err: '' };
         }
         const { lines, code } = renderActReport(report);
         return report.ok ?
@@ -1048,7 +1224,7 @@ export const checkCommand = (argv) => {
     try {
         const report = caveCheck(store, { staleDays });
         const out = values.json === true ?
-            `${JSON.stringify(report, undefined, 2)}\n` :
+            `${stableJson(store, report)}\n` :
             renderReport(report, staleDays);
         // Violations fail the check (spec §20.2); the other sections are advisory.
         return { code: report.violations.length > 0 ? 1 : 0, out, err: '' };
@@ -1057,11 +1233,83 @@ export const checkCommand = (argv) => {
         store.close();
     }
 };
+const snapshotLine = (action, snapshot) => `${action} exact backup (${snapshot.rows} row(s), schema v${snapshot.schemaVersion}, ` +
+    `${snapshot.bytes} bytes, sha256:${snapshot.sha256}) at ${snapshot.path}\n`;
+/** `cave backup` — create or verify an exact SQLite snapshot (§13.2.2). */
+export const backupCommand = (argv) => {
+    const { values } = parseArgs({
+        args: [...argv],
+        options: {
+            db: { type: 'string' },
+            out: { type: 'string' },
+            force: { type: 'boolean' },
+            verify: { type: 'string' },
+            sha256: { type: 'string' }
+        },
+        allowPositionals: false
+    });
+    if (values.sha256 !== undefined && !/^[0-9a-f]{64}$/i.test(values.sha256)) {
+        return fail('cave backup: --sha256 must be 64 hexadecimal characters\n');
+    }
+    try {
+        if (values.verify !== undefined) {
+            if (values.out !== undefined || values.force === true || values.db !== undefined) {
+                return fail('cave backup: --verify excludes --db, --out, and --force\n');
+            }
+            return ok(snapshotLine('verified', verifyBackup(values.verify, values.sha256)));
+        }
+        if (values.sha256 !== undefined) {
+            return fail('cave backup: --sha256 requires --verify\n');
+        }
+        if (values.out === undefined) {
+            return fail('cave backup: --out <file> is required\n');
+        }
+        const store = open(values.db ?? defaultDbPath());
+        try {
+            return ok(snapshotLine('created', backupStore(store, values.out, { force: values.force === true })));
+        }
+        finally {
+            store.close();
+        }
+    }
+    catch (error) {
+        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
+    }
+};
+/** `cave restore` — verify and atomically restore an exact snapshot (§13.2.2). */
+export const restoreCommand = (argv) => {
+    const { values, positionals } = parseArgs({
+        args: [...argv],
+        options: {
+            db: { type: 'string' },
+            force: { type: 'boolean' },
+            sha256: { type: 'string' }
+        },
+        allowPositionals: true
+    });
+    if (positionals.length !== 1) {
+        return fail('cave restore: exactly one snapshot file is required\n');
+    }
+    if (values.db === undefined) {
+        return fail('cave restore: --db <path> destination is required\n');
+    }
+    if (values.sha256 !== undefined && !/^[0-9a-f]{64}$/i.test(values.sha256)) {
+        return fail('cave restore: --sha256 must be 64 hexadecimal characters\n');
+    }
+    try {
+        return ok(snapshotLine('restored', restoreBackup(positionals[0], values.db, {
+            force: values.force === true,
+            ...values.sha256 === undefined ? {} : { expectedSha256: values.sha256 }
+        })));
+    }
+    catch (error) {
+        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
+    }
+};
 /**
  * `cave suggest-alias` — alias discovery (spec §27): same-entity
- * candidates as suggested `ALIAS` claims for review. Async (the optional
- * judge runs a shell agent), so `main.ts` routes it separately, like
- * `reconstruct`.
+ * candidates as suggested `ALIAS` claims for review. Async when the optional
+ * judge runs a shell agent.
  */
 export const suggestAliasCommand = async (argv) => {
     try {
@@ -1159,7 +1407,7 @@ export const syncCommand = (argv) => {
             ...values.as === undefined ? {} : { from: sanitizeLabel(values.as) }
         };
         const report = source === '-' ?
-            syncText(store, readFileSync(0, 'utf8'), { from: 'stdin', ...options }) :
+            syncText(store, readStdin(), { from: 'stdin', ...options }) :
             syncFile(store, source, options);
         if (values.json === true) {
             return { code: report.problems.length > 0 ? 1 : 0, out: `${JSON.stringify(report, undefined, 2)}\n`, err: '' };
@@ -1202,16 +1450,22 @@ export const reportCommand = (argv) => {
             resolve: { type: 'boolean' },
             'as-of': { type: 'string' },
             at: { type: 'string' },
+            'max-sensitivity': { type: 'string' },
             'no-prelude': { type: 'boolean' }
         },
         allowPositionals: true
     });
     const template = readInput(positionals);
+    const maximum = Sensitivity.parse(values['max-sensitivity'] ?? Sensitivity.defaultMaximum);
+    if (maximum === undefined) {
+        return fail(`cave report: --max-sensitivity expects ${Sensitivity.levels.join(', ')}, got ${JSON.stringify(values['max-sensitivity'])}\n`);
+    }
     const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {});
     try {
         const rendered = caveReport(store, template, {
             aliases: values.aliases === true,
             resolve: values.resolve === true,
+            maxSensitivity: maximum,
             ...values['as-of'] === undefined ? {} : { asOf: values['as-of'] },
             ...values.at === undefined ? {} : { at: values.at }
         });
@@ -1262,24 +1516,75 @@ export const exportCommand = (argv) => {
             current: { type: 'boolean' },
             tx: { type: 'boolean' },
             out: { type: 'string' },
+            'max-sensitivity': { type: 'string' },
             'no-prelude': { type: 'boolean' }
         },
         allowPositionals: false
     });
     const db = values.db ?? defaultDbPath();
+    const maximum = Sensitivity.parse(values['max-sensitivity'] ?? Sensitivity.defaultMaximum);
+    if (maximum === undefined) {
+        return fail(`cave export: --max-sensitivity expects ${Sensitivity.levels.join(', ')}, got ${JSON.stringify(values['max-sensitivity'])}\n`);
+    }
     if (values.out !== undefined && sameFile(db, values.out)) {
         return fail(`cave export: --out '${values.out}' is the source database — refusing to overwrite it\n`);
     }
     const store = open(db, values['no-prelude'] === true ? { registry: Registry.empty } : {});
     try {
-        const text = store.exportText({ current: values.current === true, tx: values.tx === true });
+        const text = store.exportText({ current: values.current === true, tx: values.tx === true, maxSensitivity: maximum });
         if (values.out === undefined) {
             return ok(text);
         }
         writeFileSync(values.out, text);
-        const claims = text === '' ? 0 : text.trimEnd().split('\n').filter(line => txOfLine(line) === undefined).length;
+        // Root claims only: indented qualifier/grouping lines are part of their
+        // parent claim, and §28.4 annotations parse as comments.
+        const claims = parseDocument(text).lines
+            .filter(line => line.kind === 'claim' && line.depth === 0).length;
         return ok(`exported ${claims} claim(s) to ${values.out}\n`);
     }
+    catch (error) {
+        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
+    }
+    finally {
+        store.close();
+    }
+};
+/** `cave generate` — spec §20.4's versioned TypeScript client artifact. */
+export const generateCommand = (argv) => {
+    const { values } = parseArgs({
+        args: [...argv],
+        options: {
+            db: { type: 'string' },
+            out: { type: 'string' },
+            version: { type: 'string' },
+            'no-prelude': { type: 'boolean' }
+        },
+        allowPositionals: false
+    });
+    const version = values.version === undefined ? undefined : Number(values.version);
+    if (version !== undefined && (!Number.isInteger(version) || version < 1)) {
+        return fail(`cave generate: --version expects a positive integer, got ${JSON.stringify(values.version)}\n`);
+    }
+    const db = values.db ?? defaultDbPath();
+    if (values.out !== undefined && sameFile(db, values.out)) {
+        return fail(`cave generate: --out '${values.out}' is the source database — refusing to overwrite it\n`);
+    }
+    const store = open(db, values['no-prelude'] === true ? { registry: Registry.empty } : {});
+    try {
+        const generated = generateClient(store, version === undefined ? {} : { version });
+        if (!generated.ok) {
+            return fail(`cave generate: schema cannot be generated:\n${generated.problems.map(problem => `  ${problem}`).join('\n')}\n`);
+        }
+        if (values.out === undefined) {
+            return ok(generated.code);
+        }
+        writeFileSync(values.out, generated.code);
+        return ok(`generated typed client v${generated.version} (${generated.fields.length} field(s), ` +
+            `sha256:${generated.digest}) to ${values.out}\n`);
+    }
+    catch (error) {
+        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
+    }
     finally {
         store.close();
     }
@@ -1287,8 +1592,7 @@ export const exportCommand = (argv) => {
 /**
  * `cave reconstruct` — the §18 loop over the store: heuristic policy by
  * default (the eval baseline), the LLM policy over a shell-agent template
- * with `--agent`. Async (the agent runs once per step), so `main.ts`
- * routes it separately, like `connect`.
+ * with `--agent`. Async because the agent runs once per step.
  */
 export const reconstructCommand = async (argv) => {
     try {
@@ -1362,8 +1666,8 @@ export const helpCommand = (argv) => {
     if (text !== undefined) {
         return ok(`${text}\n`);
     }
-    // mcp, ingest, connect, eval, automate and serve own their help (main.ts forwards `help X` to `X --help`).
-    if (topic === 'mcp' || topic === 'ingest' || topic === 'connect' || topic === 'eval' || topic === 'automate' || topic === 'serve') {
+    // Delegated commands own their help; dispatch.ts forwards `help X` to `X --help`.
+    if (delegatedCommandNames.includes(topic)) {
         return ok(`see: cave ${topic} --help\n`);
     }
     return fail(`cave help: unknown command ${JSON.stringify(topic)}\n\n${usage}\n`, 2);
@@ -1372,52 +1676,55 @@ export const helpCommand = (argv) => {
 export const cave = (argv) => {
     const [command, ...rest] = argv;
     const canonical = command === 'q' ? 'query' : command;
-    try {
-        if (canonical !== undefined && canonical in commandHelp &&
-            (rest.includes('--help') || rest.includes('-h'))) {
-            return ok(`${commandHelp[canonical]}\n`);
-        }
-        switch (canonical) {
-            case 'parse':
-                return parseCommand(rest);
-            case 'add':
-                return addCommand(rest);
-            case 'import':
-                return importCommand(rest);
-            case 'query':
-                return queryCommand(rest);
-            case 'resolve':
-                return resolveCommand(rest);
-            case 'derive':
-                return deriveCommand(rest);
-            case 'act':
-                return actCommand(rest);
-            case 'check':
-                return checkCommand(rest);
-            case 'sync':
-                return syncCommand(rest);
-            case 'export':
-                return exportCommand(rest);
-            case 'report':
-                return reportCommand(rest);
-            case 'demo':
-                return demoCommand();
-            case 'version':
-            case '--version':
-            case '-v':
-                return versionCommand();
-            case 'help':
-                return helpCommand(rest);
-            case undefined:
-            case '--help':
-            case '-h':
-                return ok(`${usage}\n`);
-            default:
-                return fail(`cave: unknown command ${JSON.stringify(command)}\n\n${usage}\n`, 2);
-        }
+    if (canonical !== undefined && canonical in commandHelp &&
+        (rest.includes('--help') || rest.includes('-h'))) {
+        return ok(`${commandHelp[canonical]}\n`);
     }
-    catch (error) {
-        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
+    switch (canonical) {
+        case 'parse':
+            return parseCommand(rest);
+        case 'add':
+            return addCommand(rest);
+        case 'import':
+            return importCommand(rest);
+        case 'query':
+            return queryCommand(rest);
+        case 'resolve':
+            return resolveCommand(rest);
+        case 'derive':
+            return deriveCommand(rest);
+        case 'act':
+            return actCommand(rest);
+        case 'check':
+            return checkCommand(rest);
+        case 'backup':
+            return backupCommand(rest);
+        case 'restore':
+            return restoreCommand(rest);
+        case 'generate':
+            return generateCommand(rest);
+        case 'sync':
+            return syncCommand(rest);
+        case 'export':
+            return exportCommand(rest);
+        case 'report':
+            return reportCommand(rest);
+        case 'doctor':
+            return doctorCommand(rest);
+        case 'demo':
+            return demoCommand();
+        case 'version':
+        case '--version':
+        case '-v':
+            return versionCommand();
+        case 'help':
+            return helpCommand(rest);
+        case undefined:
+        case '--help':
+        case '-h':
+            return ok(`${usage}\n`);
+        default:
+            return fail(`cave: unknown command ${JSON.stringify(command)}\n\n${usage}\n`, 2);
     }
 };
 //# sourceMappingURL=cli.js.map