@cavelang/cli 0.27.3 → 0.29.0

package/src/cli.ts

@@ -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
@@ -30,17 +34,18 @@
  * `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 { Sensitivity, backup as backupStore, defaultDbPath, open, restoreBackup, verifyBackup } from '@cavelang/store'
+import type { Store } from '@cavelang/store'
+import { defaultLimit as defaultQueryLimit, page as caveQueryPage } from '@cavelang/query'
 import {
   check as caveCheck, defaultMinScore, defaultStaleDays, gatedIngest, judgePrompt, parseJudgeReply,
-  suggestAliases, writeSuggestions
+  generateClient, suggestAliases, writeSuggestions
 } from '@cavelang/shape'
 import type { Report, Violation } from '@cavelang/shape'
 import { declareRules, defaultMaxPasses, defaultMinConf, derive, listRules, retractRule } from '@cavelang/rules'
@@ -53,7 +58,9 @@ import {
 import { labelOf, sanitizeLabel, syncFile, syncText } from '@cavelang/sync'
 import type { SyncReport } from '@cavelang/sync'
 import { report as caveReport } from '@cavelang/view'
-import { emitClaim, txOfLine } from '@cavelang/canonical'
+import { emitClaim } from '@cavelang/canonical'
+import { doctorCommand } from './doctor.ts'
+import { delegatedCommandNames } from './commands.ts'
 
 export type Output = {
   readonly code: number
@@ -61,6 +68,39 @@ export type Output = {
   readonly err: string
 }
 
+const storageRow = (value: unknown): value is Parameters<Store['recordOf']>[0] =>
+  typeof value === 'object' && value !== null &&
+  typeof (value as Record<string, unknown>)['id'] === 'string' &&
+  typeof (value as Record<string, unknown>)['tx'] === 'string' &&
+  typeof (value as Record<string, unknown>)['claim_key'] === 'string' &&
+  typeof (value as Record<string, unknown>)['raw_line'] === 'string'
+
+/** Recursively replace storage rows in JSON reports with cave.claim/v1 records. */
+const stableJsonValue = (store: Store, value: unknown): unknown => {
+  if (storageRow(value)) {
+    const record = store.recordOf(value)
+    const ranked = value as typeof value & Record<string, unknown>
+    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: Store, value: unknown): string =>
+  JSON.stringify(stableJsonValue(store, value), undefined, 2)
+
 const ok = (out: string): Output =>
   ({ code: 0, out, err: '' })
 
@@ -74,23 +114,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
@@ -103,6 +147,26 @@ 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: Record<string, string> = {
+  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:
@@ -178,24 +242,28 @@ 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)
@@ -355,7 +423,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.
 
@@ -364,6 +433,69 @@ Examples:
   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:
@@ -447,7 +579,7 @@ 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`,
@@ -455,32 +587,43 @@ Examples:
   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}
@@ -493,6 +636,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
@@ -568,9 +714,27 @@ Usage:
   cave version`
 }
 
+const readStdin = (): string => {
+  const chunks: Buffer[] = []
+  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 as NodeJS.ErrnoException).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: readonly string[]): string =>
   files.length === 0 || (files.length === 1 && files[0] === '-') ?
-    readFileSync(0, 'utf8') :
+    readStdin() :
     files.map(file => readFileSync(file, 'utf8')).join('\n')
 
 export const parseCommand = (argv: readonly string[]): Output => {
@@ -602,8 +766,7 @@ export const parseCommand = (argv: readonly string[]): Output => {
 
 /**
  * `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: readonly string[]): Promise<Output> => {
   const { positionals } = parseArgs({ args: [...argv], options: {}, allowPositionals: true })
@@ -620,9 +783,25 @@ export const highlightCommand = async (argv: readonly string[]): Promise<Output>
  * replays interchange text, which must preserve claim keys as exported,
  * so it never stamps.
  */
+const formatViolationProblem = (violation: Violation): string => {
+  const { entity, expectation, actualCount, actualUnits } = violation
+  if (actualCount === 0) {
+    return `${entity} missing ${expectation.kind} ${expectation.name}`
+  }
+  const problems: string[] = []
+  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: Violation): string =>
-  `${violation.entity} missing ${violation.expectation.kind} ${violation.expectation.name} ` +
-  `(${violation.entity} IS ${violation.via}; ${violation.expectation.type} EXPECTS ${violation.expectation.name})`
+  `${formatViolationProblem(violation)} ` +
+  `(${violation.entity} IS ${violation.via}; ${violation.expectation.row.raw_line})`
 
 const ingestCommand = (name: 'add' | 'import') => (argv: readonly string[]): Output => {
   const { values, positionals } = parseArgs({
@@ -693,6 +872,8 @@ export const queryCommand = (argv: readonly string[]): Output => {
       'as-of': { type: 'string' },
       at: { type: 'string' },
       resolve: { type: 'boolean' },
+      limit: { type: 'string' },
+      cursor: { type: 'string' },
       'no-prelude': { type: 'boolean' }
     },
     allowPositionals: true
@@ -703,18 +884,22 @@ export const queryCommand = (argv: readonly string[]): Output => {
   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)
@@ -722,14 +907,14 @@ export const queryCommand = (argv: readonly string[]): Output => {
         .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`)
   } finally {
@@ -775,7 +960,7 @@ export const resolveCommand = (argv: readonly string[]): Output => {
     }
     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')
@@ -823,7 +1008,7 @@ export const deriveCommand = (argv: readonly string[]): Output => {
     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')
@@ -885,7 +1070,7 @@ export const deriveCommand = (argv: readonly string[]): Output => {
         (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('; ')}`)
@@ -902,7 +1087,7 @@ export const deriveCommand = (argv: readonly string[]): Output => {
       `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) {
     return fail(`${error instanceof Error ? error.message : String(error)}\n`)
@@ -989,7 +1174,7 @@ export const actCommand = (argv: readonly string[]): Output => {
     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')
@@ -1030,7 +1215,7 @@ export const actCommand = (argv: readonly string[]): Output => {
       ...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 ?
@@ -1097,7 +1282,7 @@ export const checkCommand = (argv: readonly string[]): Output => {
   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: '' }
@@ -1106,11 +1291,87 @@ export const checkCommand = (argv: readonly string[]): Output => {
   }
 }
 
+const snapshotLine = (
+  action: 'created' | 'verified' | 'restored',
+  snapshot: ReturnType<typeof verifyBackup>
+): string =>
+  `${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: readonly string[]): Output => {
+  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: readonly string[]): Output => {
+  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: readonly string[]): Promise<Output> => {
   try {
@@ -1209,7 +1470,7 @@ export const syncCommand = (argv: readonly string[]): Output => {
       ...values.as === undefined ? {} : { from: sanitizeLabel(values.as) }
     }
     const report: SyncReport = 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: '' }
@@ -1251,16 +1512,22 @@ export const reportCommand = (argv: readonly string[]): Output => {
       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 }
     })
@@ -1310,23 +1577,72 @@ export const exportCommand = (argv: readonly string[]): Output => {
       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: readonly string[]): Output => {
+  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()
   }
@@ -1335,8 +1651,7 @@ export const exportCommand = (argv: readonly string[]): Output => {
 /**
  * `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: readonly string[]): Promise<Output> => {
   try {
@@ -1420,8 +1735,8 @@ export const helpCommand = (argv: readonly string[]): Output => {
   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)
@@ -1431,50 +1746,54 @@ export const helpCommand = (argv: readonly string[]): Output => {
 export const cave = (argv: readonly string[]): Output => {
   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)
-    }
-  } catch (error) {
-    return fail(`${error instanceof Error ? error.message : String(error)}\n`)
+  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 '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)
   }
 }