@cavelang/cli 0.4.0 → 0.12.0

package/README.md

@@ -28,11 +28,12 @@ Every command answers `--help` with its options and examples (also
 | Command | Flags | Behavior |
 |---|---|---|
 | `parse [file…]` | `--json` | Lint (stdin by default). Exit 1 when diagnostics exist; `--json` dumps the AST document. |
-| `add [--db p] [file…]` | `--strict`, `--no-prelude` | Ingest. Lenient by default (problems on stderr, valid lines land); `--strict` rolls back on any problem; `--no-prelude` starts from an empty registry instead of the standard §5.5 pairs. |
-| `import [--db p] [file…]` | `--strict`, `--no-prelude` | Restore/merge a database from CAVE text — same operation as `add`, because canonical text *is* the interchange format. |
+| `add [--db p] [file…]` | `--strict`, `--check`, `--no-prelude`, `--no-src` | Ingest. Lenient by default (problems on stderr, valid lines land); `--strict` rolls back on any problem; `--check` is the shape gate (spec §20.3) — the append rolls back if it introduces new expectation violations; `--no-prelude` starts from an empty registry instead of the standard §5.5 pairs. Claims without a `@src:` context are stamped `@src:cli` (spec §9.5); `--no-src` opts out. |
+| `import [--db p] [file…]` | `--strict`, `--no-prelude` | Restore/merge a database from CAVE text — `add` minus provenance stamping, because canonical text *is* the interchange format and replayed claims must keep their exported claim keys (spec §9.5). |
 | `query [--db p] <pattern…>` | `--json`, `--all`, `--no-prelude` | CAVE-Q. Extra positionals join as lines, so `WHERE` filters ride as separate arguments. Bindings print as `?x = value`; fully bound patterns print the matched raw line (or the pattern itself for transitive matches, which carry no row). `--no-prelude` aligns the read-time registry with a store written via `add --no-prelude`. |
+| `check [--db p]` | `--stale <days>`, `--json`, `--no-prelude` | Knowledge health report (spec §20, see [`@cavelang/shape`](../shape)): shape violations against in-band `EXPECTS` declarations, stale current beliefs (default horizon 90 days), review candidates (conf 0.3–0.7), alias disagreements, coverage stats. Exit 1 on violations; everything else is advisory. |
 | `export [--db p]` | `--out <file>`, `--current`, `--no-prelude` | Canonical CAVE text — all rows in tx order, or current beliefs only. Stdout by default; `--out` writes a file and reports the claim count. |
-| `mcp [--db p]` | `--no-prelude` | Serve the engine as an MCP server on stdio (see [`@cavelang/mcp`](../mcp)) — tools for add/query/search/about/neighbors/reconstruct/export/lint, with the §22 spec card as server instructions. |
+| `mcp [--db p]` | `--read-only`, `--tools <list>`, `--no-prelude`, `--src <ctx>`, `--no-src` | Serve the engine as an MCP server on stdio (see [`@cavelang/mcp`](../mcp)) — tools for add/query/search/about/neighbors/reconstruct/export/lint, with the §22 spec card as server instructions. `--read-only` / `--tools <list>` narrow the served tool surface (the agent permission boundary), composing by intersection. Appends are stamped `@src:agent/<client-name>` (spec §9.5); `--src` replaces the stamp, `--no-src` disables it. |
 | `ingest [--db p] <globs/urls…>` | see `cave ingest --help` | LLM-driven ingestion of files and web pages (fetched and readability-extracted) through any headless agent (see [`@cavelang/ingest`](../ingest)): batching, instructions markdown, hybrid knowledge context, MCP or stdout agents, incremental digests, `--plan` NDJSON for SDK drivers. |
 | `demo` | | The cave-loop multi-hop recovery demo (§18). |
 | `version` | | Print the cave version. |

package/dist/src/cli.d.ts

@@ -6,9 +6,13 @@
  * Commands:
  *
  * - `cave parse [file]` — lint / dump the AST (`--json`)
- * - `cave add [--db <path>] [file…]` — ingest into a store (`--strict`)
- * - `cave query [--db <path>] '<pattern>'` — CAVE-Q (`--json`, `--all`)
+ * - `cave highlight [file]` — ANSI syntax colors (async, routed in `main.ts`)
+ * - `cave add [--db <path>] [file…]` — ingest into a store (`--strict`, `--check`)
+ * - `cave query [--db <path>] '<pattern>'` — CAVE-Q (`--json`, `--all`, `--aliases`, `--as-of`)
+ * - `cave derive [--db <path>] [rules.cave…]` — fire rules (`--dry-run`, `--full`, `--list`, `--retract`)
+ * - `cave check [--db <path>]` — knowledge health report (`--stale`, `--json`)
  * - `cave export [--db <path>]` — canonical text out (`--current`)
+ * - `cave connect [--db <path>] <source>` — deterministic structured ingestion (async, routed in `main.ts`)
  * - `cave demo` — the cave-loop multi-hop recovery demo
  * - `cave version` — print the cave version
  * - `cave help [command]` — overview, or one command's help
@@ -21,23 +25,33 @@ export type Output = {
     readonly out: string;
     readonly err: string;
 };
-export declare const usage = "cave \u2014 Compressed Atomic Verb Expressions\n\nUsage:\n  cave parse [file...] [--json]            lint CAVE text (stdin when no file)\n  cave add [--db <path>] [file...]         ingest into a store [--strict] [--no-prelude]\n  cave import [--db <path>] [file...]      restore/merge from CAVE text (same as add)\n  cave query [--db <path>] <pattern>       run a CAVE-Q pattern [--json] [--all] [--no-prelude]\n  cave export [--db <path>] [--out <file>] emit canonical CAVE text [--current] [--no-prelude]\n  cave mcp [--db <path>]                   serve the engine as an MCP server on stdio [--no-prelude]\n  cave ingest [--db <path>] <globs/urls..> LLM-driven ingestion of files and web pages\n  cave demo                                run the cave-loop reconstruction demo\n  cave version                             print the cave version\n  cave help [command]                      this text, or one command's options and examples\n\nEvery command answers --help. --db defaults to $CAVE_DB, or cave.db in\nthe current directory. The spec lives in the .claude/skills/ directory at\nthe repository root (section index in README.md).";
+export declare const usage = "cave \u2014 Compressed Atomic Verb Expressions\n\nUsage:\n  cave parse [file...] [--json]            lint CAVE text (stdin when no file)\n  cave highlight [file...]                 print CAVE text with ANSI syntax colors\n  cave add [--db <path>] [file...]         ingest into a store [--strict] [--check] [--no-prelude] [--no-src]\n  cave import [--db <path>] [file...]      restore/merge from CAVE text (add without @src: stamping)\n  cave query [--db <path>] <pattern>       run a CAVE-Q pattern [--json] [--all] [--aliases] [--as-of <t>] [--no-prelude]\n  cave derive [--db <path>] [rules.cave..] declare + fire rules (spec \u00A724) [--dry-run] [--full] [--list] [--retract <rule>]\n  cave check [--db <path>]                 knowledge health report (spec \u00A720) [--stale <days>] [--json]\n  cave export [--db <path>] [--out <file>] emit canonical CAVE text [--current] [--no-prelude]\n  cave mcp [--db <path>]                   serve the engine as an MCP server on stdio [--no-prelude]\n  cave ingest [--db <path>] <globs/urls..> LLM-driven ingestion of files and web pages\n  cave connect <source> --map <file>       deterministic structured ingestion (CSV/JSON/SQLite/URL, spec \u00A723)\n  cave demo                                run the cave-loop reconstruction demo\n  cave version                             print the cave version\n  cave help [command]                      this text, or one command's options and examples\n\nEvery command answers --help. --db defaults to $CAVE_DB, or cave.db in\nthe current directory. The spec lives in the .claude/skills/ directory at\nthe repository root (section index in README.md).";
 /** Per-command help, printed for \`cave <command> --help\` and \`cave help <command>\`. */
 export declare const commandHelp: Record<string, string>;
 export declare 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`.
+ */
+export declare const highlightCommand: (argv: readonly string[]) => Promise<Output>;
 export declare const addCommand: (argv: readonly string[]) => Output;
 /**
  * `cave import` — restore/merge a knowledge database from CAVE text files.
- * Identical to `add` by design: canonical CAVE text *is* the interchange
+ * `add` minus provenance stamping: canonical CAVE text *is* the interchange
  * format (spec §2.2), so importing a file exported with `cave export`
- * replays its claims append-only. What the text round trip preserves:
- * every claim with metadata, full belief-series order (rows export in tx
- * order and re-ingest with fresh monotonic tx ids), qualifier/grouping
- * edges, and in-band registry declarations. Original tx timestamps are
- * re-minted — the text format carries no transaction identity.
+ * replays its claims append-only — and because contexts are part of claim
+ * identity, replay must not add a `@src:` stamp (spec §9.5). What the text
+ * round trip preserves: every claim with metadata, full belief-series order
+ * (rows export in tx order and re-ingest with fresh monotonic tx ids),
+ * qualifier/grouping edges, and in-band registry declarations. Original tx
+ * timestamps are re-minted — the text format carries no transaction
+ * identity.
  */
 export declare const importCommand: (argv: readonly string[]) => Output;
 export declare const queryCommand: (argv: readonly string[]) => Output;
+export declare const deriveCommand: (argv: readonly string[]) => Output;
+export declare const checkCommand: (argv: readonly string[]) => Output;
 export declare const exportCommand: (argv: readonly string[]) => Output;
 export declare const demoCommand: () => Output;
 export declare const versionCommand: () => Output;

package/dist/src/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAWH,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB,CAAA;AAQD,eAAO,MAAM,KAAK,unCAgBgC,CAAA;AAIlD,2FAA2F;AAC3F,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAsG9C,CAAA;AAOD,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAyBtD,CAAA;AA+BD,eAAO,MAAM,UAAU,SA7BwB,SAAS,MAAM,EAAE,KAAG,MA6BrB,CAAA;AAE9C;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa,SAzCqB,SAAS,MAAM,EAAE,KAAG,MAyCf,CAAA;AAEpD,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAsCtD,CAAA;AAED,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAuBvD,CAAA;AAED,eAAO,MAAM,WAAW,QAAO,MACS,CAAA;AAExC,eAAO,MAAM,cAAc,QAAO,MACJ,CAAA;AAE9B,wEAAwE;AACxE,eAAO,MAAM,WAAW,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAcrD,CAAA;AAED,iCAAiC;AACjC,eAAO,MAAM,IAAI,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAqC9C,CAAA"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAeH,MAAM,MAAM,MAAM,GAAG;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB,CAAA;AAQD,eAAO,MAAM,KAAK,6mDAoBgC,CAAA;AAIlD,2FAA2F;AAC3F,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAiM9C,CAAA;AAOD,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAyBtD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAU,MAAM,SAAS,MAAM,EAAE,KAAG,OAAO,CAAC,MAAM,CAM9E,CAAA;AAuDD,eAAO,MAAM,UAAU,SA1CkC,SAAS,MAAM,EAAE,KAAG,MA0C/B,CAAA;AAE9C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,SAxD+B,SAAS,MAAM,EAAE,KAAG,MAwDzB,CAAA;AAEpD,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MA4CtD,CAAA;AAED,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAsHvD,CAAA;AAqCD,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MA0BtD,CAAA;AAED,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAuBvD,CAAA;AAED,eAAO,MAAM,WAAW,QAAO,MACS,CAAA;AAExC,eAAO,MAAM,cAAc,QAAO,MACJ,CAAA;AAE9B,wEAAwE;AACxE,eAAO,MAAM,WAAW,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAcrD,CAAA;AAED,iCAAiC;AACjC,eAAO,MAAM,IAAI,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAyC9C,CAAA"}

package/dist/src/cli.js

@@ -6,9 +6,13 @@
  * Commands:
  *
  * - `cave parse [file]` — lint / dump the AST (`--json`)
- * - `cave add [--db <path>] [file…]` — ingest into a store (`--strict`)
- * - `cave query [--db <path>] '<pattern>'` — CAVE-Q (`--json`, `--all`)
+ * - `cave highlight [file]` — ANSI syntax colors (async, routed in `main.ts`)
+ * - `cave add [--db <path>] [file…]` — ingest into a store (`--strict`, `--check`)
+ * - `cave query [--db <path>] '<pattern>'` — CAVE-Q (`--json`, `--all`, `--aliases`, `--as-of`)
+ * - `cave derive [--db <path>] [rules.cave…]` — fire rules (`--dry-run`, `--full`, `--list`, `--retract`)
+ * - `cave check [--db <path>]` — knowledge health report (`--stale`, `--json`)
  * - `cave export [--db <path>]` — canonical text out (`--current`)
+ * - `cave connect [--db <path>] <source>` — deterministic structured ingestion (async, routed in `main.ts`)
  * - `cave demo` — the cave-loop multi-hop recovery demo
  * - `cave version` — print the cave version
  * - `cave help [command]` — overview, or one command's help
@@ -23,6 +27,8 @@ 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, defaultStaleDays, gatedIngest } from '@cavelang/shape';
+import { declareRules, defaultMaxPasses, defaultMinConf, derive, listRules, retractRule } from '@cavelang/rules';
 import { Demo } from '@cavelang/loop';
 const ok = (out) => ({ code: 0, out, err: '' });
 const fail = (err, code = 1) => ({ code, out: '', err });
@@ -30,12 +36,16 @@ export const usage = `cave — Compressed Atomic Verb Expressions
 
 Usage:
   cave parse [file...] [--json]            lint CAVE text (stdin when no file)
-  cave add [--db <path>] [file...]         ingest into a store [--strict] [--no-prelude]
-  cave import [--db <path>] [file...]      restore/merge from CAVE text (same as add)
-  cave query [--db <path>] <pattern>       run a CAVE-Q pattern [--json] [--all] [--no-prelude]
+  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>] [--no-prelude]
+  cave derive [--db <path>] [rules.cave..] declare + fire rules (spec §24) [--dry-run] [--full] [--list] [--retract <rule>]
+  cave check [--db <path>]                 knowledge health report (spec §20) [--stale <days>] [--json]
   cave export [--db <path>] [--out <file>] emit canonical CAVE text [--current] [--no-prelude]
   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 connect <source> --map <file>       deterministic structured ingestion (CSV/JSON/SQLite/URL, spec §23)
   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
@@ -61,23 +71,44 @@ Examples:
   cave parse notes.cave
   echo 'auth USES jwt @ 90%' | cave parse
   cave parse notes.cave --json | jq '.lines[0]'`,
+    highlight: `cave highlight — print CAVE text with ANSI syntax colors
+
+Usage:
+  cave highlight [file...]
+
+Reads stdin when no file (or \`-\`) is given. Colors come from the
+tree-sitter grammar's highlight query (@cavelang/tree-sitter-cave), the
+same source editors use. Output always carries ANSI codes — pipe through
+\`less -R\` to page. \`cave export\` colors its output the same way when
+stdout is a terminal (disable with NO_COLOR).
+
+Examples:
+  cave highlight notes.cave
+  echo 'auth USES jwt @ 90%' | cave highlight
+  cave highlight notes.cave | less -R`,
     add: `cave add — ingest CAVE text into a knowledge database
 
 Usage:
-  cave add [--db <path>] [file...] [--strict] [--no-prelude]
+  cave add [--db <path>] [file...] [--strict] [--check] [--no-prelude] [--no-src]
 
 Options:
   ${dbHelp}
   --strict       reject the whole ingest on any problem
+  --check        shape gate (spec §20.3): roll the append back if it
+                 introduces new expectation violations
   --no-prelude   open the store without the standard verb registry
+  --no-src       do not stamp actor provenance on appended claims
 
-Reads stdin when no file (or \`-\`) is given.
+Reads stdin when no file (or \`-\`) is given. Claims that carry no @src:
+context are stamped @src:cli (spec §9.5); use \`cave import\` to replay
+exported text without stamping.
 
 Examples:
   cave add --db k.db notes.cave
   echo 'auth USES jwt @ 90%' | cave add
-  cave add --db k.db --strict reviewed.cave`,
-    import: `cave import — restore/merge a database from CAVE text (same as add)
+  cave add --db k.db --strict reviewed.cave
+  cave add --db k.db --check new-services.cave`,
+    import: `cave import — restore/merge a database from CAVE text (add without @src: stamping)
 
 Usage:
   cave import [--db <path>] [file...] [--strict] [--no-prelude]
@@ -89,7 +120,9 @@ Options:
 
 Canonical CAVE text is the interchange format (spec §2.2): importing a
 file written by \`cave export\` replays its claims append-only, preserving
-the belief series, qualifier edges and in-band declarations.
+the belief series, qualifier edges and in-band declarations. Unlike
+\`cave add\`, import never stamps actor provenance — replayed claims must
+keep the claim keys they were exported with (spec §9.5).
 
 Examples:
   cave export --db old.db --out backup.cave
@@ -97,12 +130,16 @@ Examples:
     query: `cave query — run a CAVE-Q pattern against a store
 
 Usage:
-  cave query [--db <path>] <pattern> [WHERE <filter>] [--json] [--all] [--no-prelude]
+  cave query [--db <path>] <pattern> [WHERE <filter>] [--json] [--all] [--aliases] [--as-of <t>] [--no-prelude]
 
 Options:
   ${dbHelp}
   --json         emit matches as JSON
   --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
   --no-prelude   open the store without the standard verb registry
 
 Patterns are claim triples with ?variables and optional metadata filters
@@ -114,7 +151,68 @@ Examples:
   cave query --db k.db '?x HAS bug: ?bug #security'
   cave query --db k.db '?cause CAUSE app/crash' 'WHERE conf >= 0.5'
   cave query --db k.db 'terrier EXTENDS+ animal'
+  cave query --db k.db '?x USES postgres' --aliases
+  cave query --db k.db 'server IS compromised' --as-of 2026-01-15
   cave query --db k.db '?x ?verb ?y @production' --json`,
+    derive: `cave derive — declare and fire rules (spec §24)
+
+Usage:
+  cave derive [--db <path>] [rules.cave...] [--dry-run] [--full] [--aliases]
+              [--min-conf <p>] [--max-passes <n>] [--json] [--no-prelude]
+  cave derive [--db <path>] --list
+  cave derive [--db <path>] --retract <digest|subject>
+
+Options:
+  ${dbHelp}
+  --dry-run      compute and report inside a rolled-back transaction
+  --full         ignore stored watermarks — re-fire every rule (spec §24.4)
+  --aliases      premises match through the alias closure (spec §13.6)
+  --min-conf <p> do not assert conclusions below this confidence
+                 (0..1 or N%, default ${defaultMinConf})
+  --max-passes <n> fixpoint guard (default ${defaultMaxPasses})
+  --list         print the store's current rules and exit
+  --retract <r>  retract a rule (digest, unambiguous prefix, or subject)
+                 together with everything it derived, and exit
+  --json         emit the report as JSON
+  --no-prelude   open the store without the standard verb registry
+
+Rule files are CAVE documents whose \`premises => conclusion\` lines are
+rules (spec §24.1); other lines — verb declarations the rules need — are
+prelude, ingested first. Rules are stored in-band as
+\`rule/<digest> HAS rule: \\\`…\\\`\` claims, so \`cave derive\` with no file
+fires whatever the store already knows. Derived claims are stamped
+@src:rule/<digest>, carry BECAUSE edges to their premise rows and a VIA
+edge to the rule, and update append-only: re-runs are idempotent and
+watermark-incremental, and conclusions whose premises no longer hold are
+retracted (spec §24.2–§24.5).
+
+Examples:
+  cave derive --db k.db rules.cave
+  cave derive --db k.db
+  echo '?x NEEDS ?y, ?y NEEDS ?z => ?x NEEDS ?z' | cave derive --db k.db -
+  cave derive --db k.db --dry-run --json
+  cave derive --db k.db --list
+  cave derive --db k.db --retract 4a0bb974f43c`,
+    check: `cave check — knowledge health report (spec §20)
+
+Usage:
+  cave check [--db <path>] [--stale <days>] [--json] [--no-prelude]
+
+Options:
+  ${dbHelp}
+  --stale <days> staleness horizon (default: ${defaultStaleDays})
+  --json         emit the full report as JSON
+  --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
+(conf 0.3–0.7), alias disagreements (spec §13.6) and coverage stats.
+Exits 1 when violations exist; everything else is advisory.
+
+Examples:
+  cave check --db k.db
+  cave check --db k.db --stale 30
+  cave check --db k.db --json | jq '.violations'`,
     export: `cave export — emit canonical CAVE text from a store
 
 Usage:
@@ -171,26 +269,60 @@ export const parseCommand = (argv) => {
         .join('\n');
     return { code: 1, out: `${summary}\n`, err: `${problems}\n` };
 };
+/**
+ * `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`.
+ */
+export const highlightCommand = async (argv) => {
+    const { positionals } = parseArgs({ args: [...argv], options: {}, allowPositionals: true });
+    const input = readInput(positionals);
+    const { highlighter } = await import('@cavelang/highlight');
+    const { ansi } = await highlighter();
+    return ok(ansi(input));
+};
+/**
+ * Shared by `add` and `import`; the difference is actor provenance
+ * (spec §9.5). `add` records knowledge authored now, so claims without a
+ * `@src:` context are stamped `@src:cli` (`--no-src` opts out); `import`
+ * 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 ingestCommand = (name) => (argv) => {
     const { values, positionals } = parseArgs({
         args: [...argv],
         options: {
             db: { type: 'string' },
             strict: { type: 'boolean' },
-            'no-prelude': { type: 'boolean' }
+            'no-prelude': { type: 'boolean' },
+            ...name === 'add' ? { 'no-src': { type: 'boolean' }, check: { type: 'boolean' } } : {}
         },
         allowPositionals: true
     });
     const input = readInput(positionals);
     const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {});
     try {
-        const result = store.ingest(input, { strict: values.strict === true });
-        const problems = result.problems
+        const options = {
+            strict: values.strict === true,
+            ...name === 'add' && values['no-src'] !== true ? { source: 'cli' } : {}
+        };
+        // The shape gate (spec §20.3): append + check in one transaction,
+        // rolled back when the append introduces new expectation violations.
+        const outcome = name === 'add' && values.check === true ?
+            gatedIngest(store, input, options) :
+            { ok: true, result: store.ingest(input, options) };
+        if (!outcome.ok) {
+            const detail = outcome.violations.map(violation => `  ${formatViolation(violation)}`).join('\n');
+            return fail(`rejected: ${outcome.violations.length} new violation(s), nothing added (spec §20.3)\n${detail}\n`);
+        }
+        const problems = outcome.result.problems
             .map(problem => `line ${problem.line}: ${problem.message}`)
             .join('\n');
         return {
             code: 0,
-            out: `added ${result.ids.length} claim(s), ${result.edges} edge(s)\n`,
+            out: `added ${outcome.result.ids.length} claim(s), ${outcome.result.edges} edge(s)\n`,
             err: problems === '' ? '' : `${problems}\n`
         };
     }
@@ -204,13 +336,15 @@ const ingestCommand = (name) => (argv) => {
 export const addCommand = ingestCommand('add');
 /**
  * `cave import` — restore/merge a knowledge database from CAVE text files.
- * Identical to `add` by design: canonical CAVE text *is* the interchange
+ * `add` minus provenance stamping: canonical CAVE text *is* the interchange
  * format (spec §2.2), so importing a file exported with `cave export`
- * replays its claims append-only. What the text round trip preserves:
- * every claim with metadata, full belief-series order (rows export in tx
- * order and re-ingest with fresh monotonic tx ids), qualifier/grouping
- * edges, and in-band registry declarations. Original tx timestamps are
- * re-minted — the text format carries no transaction identity.
+ * replays its claims append-only — and because contexts are part of claim
+ * identity, replay must not add a `@src:` stamp (spec §9.5). What the text
+ * round trip preserves: every claim with metadata, full belief-series order
+ * (rows export in tx order and re-ingest with fresh monotonic tx ids),
+ * qualifier/grouping edges, and in-band registry declarations. Original tx
+ * timestamps are re-minted — the text format carries no transaction
+ * identity.
  */
 export const importCommand = ingestCommand('import');
 export const queryCommand = (argv) => {
@@ -220,6 +354,8 @@ export const queryCommand = (argv) => {
             db: { type: 'string' },
             json: { type: 'boolean' },
             all: { type: 'boolean' },
+            aliases: { type: 'boolean' },
+            'as-of': { type: 'string' },
             'no-prelude': { type: 'boolean' }
         },
         allowPositionals: true
@@ -230,7 +366,11 @@ 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, { all: values.all === true });
+        const matches = caveQuery(store, pattern, {
+            all: values.all === true,
+            aliases: values.aliases === true,
+            ...values['as-of'] === undefined ? {} : { asOf: values['as-of'] }
+        });
         if (values.json === true) {
             return ok(`${JSON.stringify(matches, undefined, 2)}\n`);
         }
@@ -254,6 +394,186 @@ export const queryCommand = (argv) => {
         store.close();
     }
 };
+export const deriveCommand = (argv) => {
+    const { values, positionals } = parseArgs({
+        args: [...argv],
+        options: {
+            db: { type: 'string' },
+            'dry-run': { type: 'boolean' },
+            full: { type: 'boolean' },
+            aliases: { type: 'boolean' },
+            'min-conf': { type: 'string' },
+            'max-passes': { type: 'string' },
+            list: { type: 'boolean' },
+            retract: { type: 'string' },
+            json: { type: 'boolean' },
+            'no-prelude': { type: 'boolean' }
+        },
+        allowPositionals: true
+    });
+    const minConf = values['min-conf'] === undefined ?
+        undefined :
+        values['min-conf'].endsWith('%') ? Number(values['min-conf'].slice(0, -1)) / 100 : Number(values['min-conf']);
+    if (minConf !== undefined && (!Number.isFinite(minConf) || minConf < 0 || minConf > 1)) {
+        return fail(`cave derive: --min-conf expects a confidence in 0..1 or N%, got ${JSON.stringify(values['min-conf'])}\n`);
+    }
+    const maxPasses = values['max-passes'] === undefined ? undefined : Number(values['max-passes']);
+    if (maxPasses !== undefined && (!Number.isInteger(maxPasses) || maxPasses < 1)) {
+        return fail(`cave derive: --max-passes expects a positive integer, got ${JSON.stringify(values['max-passes'])}\n`);
+    }
+    const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {});
+    try {
+        if (values.list === true) {
+            const rules = listRules(store);
+            if (values.json === true) {
+                return ok(`${JSON.stringify(rules, undefined, 2)}\n`);
+            }
+            if (rules.length === 0) {
+                return ok('no rules\n');
+            }
+            const lines = rules.map(rule => `${rule.subject} \`${rule.text}\`${rule.label === undefined ? '' : ` ; ${rule.label}`}` +
+                (rule.ok ? '' : `\n  problems: ${rule.problems.join('; ')}`));
+            return ok(`${lines.join('\n')}\n`);
+        }
+        if (values.retract !== undefined) {
+            const outcome = retractRule(store, values.retract);
+            if (!outcome.ok) {
+                return fail(`cave derive: ${outcome.error}\n`);
+            }
+            return ok(`retracted ${outcome.subjects.join(', ')} and ${outcome.derived} derived claim(s)\n`);
+        }
+        const err = [];
+        const out = [];
+        // Unlike parse/add, no positional means "fire the stored rules", never
+        // stdin — pass `-` to read a rule file from stdin explicitly.
+        const input = positionals.length > 0 ? readInput(positionals) : undefined;
+        const options = {
+            full: values.full === true,
+            aliases: values.aliases === true,
+            ...minConf === undefined ? {} : { minConf },
+            ...maxPasses === undefined ? {} : { maxPasses }
+        };
+        let declaration;
+        let report;
+        if (values['dry-run'] === true) {
+            // A dry run persists nothing — rule declarations from the file
+            // included, so declare + fire share one rolled-back transaction.
+            const rolledBack = Symbol('cave derive --dry-run');
+            let outcome;
+            try {
+                store.transaction(() => {
+                    outcome = {
+                        ...input === undefined ? {} : { declaration: declareRules(store, input) },
+                        report: derive(store, options)
+                    };
+                    throw rolledBack;
+                });
+            }
+            catch (error) {
+                if (error !== rolledBack) {
+                    throw error;
+                }
+            }
+            declaration = outcome.declaration;
+            report = outcome.report;
+        }
+        else {
+            declaration = input === undefined ? undefined : declareRules(store, input);
+            report = derive(store, options);
+        }
+        if (declaration !== undefined) {
+            err.push(...declaration.problems.map(problem => `rules line ${problem.line}: ${problem.message}`));
+            out.push(`declared ${declaration.declared} rule(s)` +
+                (declaration.unchanged > 0 ? `, ${declaration.unchanged} unchanged` : '') +
+                (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' : '') };
+        }
+        for (const problem of report.problems) {
+            err.push(`${problem.subject}: ${problem.problems.join('; ')}`);
+        }
+        for (const rule of report.rules) {
+            const state = rule.fired ?
+                `${rule.solutions} solution(s), +${rule.appended} appended, ${rule.updated} updated, ${rule.retracted} retracted, ${rule.unchanged} unchanged` :
+                'unchanged premises, skipped';
+            out.push(`${rule.subject}: ${state}${rule.label === undefined ? '' : ` ; ${rule.label}`}`);
+            err.push(...rule.problems.map(problem => `${rule.subject}: ${problem}`));
+        }
+        out.push(...report.notes.map(note => `note: ${note}`));
+        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);
+        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`);
+    }
+    finally {
+        store.close();
+    }
+};
+/** Text rendering of the §20.2 report: always shape + coverage, non-empty advisory sections. */
+const renderReport = (report, staleDays) => {
+    const lines = [];
+    const { coverage } = report;
+    lines.push(`shape: ${coverage.expectations} expectation(s), ${coverage.instances} instance(s), ${coverage.satisfied}/${coverage.checks} satisfied`);
+    if (report.violations.length > 0) {
+        lines.push(`violations (${report.violations.length}):`);
+        lines.push(...report.violations.map(violation => `  ${formatViolation(violation)}`));
+    }
+    if (report.stale.length > 0) {
+        lines.push(`stale (${report.stale.length}, older than ${staleDays} day(s)):`);
+        lines.push(...report.stale.map(({ row, ageDays }) => `  ${row.raw_line} (${ageDays}d)`));
+    }
+    if (report.review.length > 0) {
+        lines.push(`review candidates (${report.review.length}, conf 0.3-0.7):`);
+        lines.push(...report.review.map(row => `  ${row.raw_line}`));
+    }
+    if (report.disagreements.length > 0) {
+        lines.push(`alias disagreements (${report.disagreements.length}):`);
+        for (const disagreement of report.disagreements) {
+            lines.push(`  ${disagreement.about} across ${disagreement.entities.join(', ')}:`);
+            lines.push(...disagreement.rows.map(row => `    ${row.raw_line}`));
+        }
+    }
+    const confidence = coverage.averageConfidence === null ?
+        '' :
+        `; avg conf ${Math.round(coverage.averageConfidence * 100)}%, ${coverage.lowConfidence} low (< 0.3)`;
+    lines.push(`coverage: ${coverage.rows} row(s), ${coverage.facts} fact(s) — ` +
+        `${coverage.current} current, ${coverage.retracted} retracted, ${coverage.negated} negated` +
+        `${confidence}; ${coverage.entities} entities, ${coverage.typedEntities} typed`);
+    return `${lines.join('\n')}\n`;
+};
+export const checkCommand = (argv) => {
+    const { values } = parseArgs({
+        args: [...argv],
+        options: {
+            db: { type: 'string' },
+            stale: { type: 'string' },
+            json: { type: 'boolean' },
+            'no-prelude': { type: 'boolean' }
+        },
+        allowPositionals: false
+    });
+    const staleDays = values.stale === undefined ? defaultStaleDays : Number(values.stale);
+    if (!Number.isFinite(staleDays) || staleDays < 0) {
+        return fail(`cave check: --stale expects a non-negative number of days, got ${JSON.stringify(values.stale)}\n`);
+    }
+    const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {});
+    try {
+        const report = caveCheck(store, { staleDays });
+        const out = values.json === true ?
+            `${JSON.stringify(report, undefined, 2)}\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: '' };
+    }
+    finally {
+        store.close();
+    }
+};
 export const exportCommand = (argv) => {
     const { values } = parseArgs({
         args: [...argv],
@@ -291,8 +611,8 @@ export const helpCommand = (argv) => {
     if (text !== undefined) {
         return ok(`${text}\n`);
     }
-    // mcp and ingest own their help (main.ts forwards `help X` to `X --help`).
-    if (topic === 'mcp' || topic === 'ingest') {
+    // mcp, ingest and connect own their help (main.ts forwards `help X` to `X --help`).
+    if (topic === 'mcp' || topic === 'ingest' || topic === 'connect') {
         return ok(`see: cave ${topic} --help\n`);
     }
     return fail(`cave help: unknown command ${JSON.stringify(topic)}\n\n${usage}\n`, 2);
@@ -315,6 +635,10 @@ export const cave = (argv) => {
                 return importCommand(rest);
             case 'query':
                 return queryCommand(rest);
+            case 'derive':
+                return deriveCommand(rest);
+            case 'check':
+                return checkCommand(rest);
             case 'export':
                 return exportCommand(rest);
             case 'demo':