@cavelang/cli 0.15.0 → 0.20.0

package/README.md

@@ -31,15 +31,19 @@ Every command answers `--help` with its options and examples (also
 | `highlight [file…]` | | ANSI syntax colors from the tree-sitter grammar's own highlight query (see [`@cavelang/highlight`](../highlight)); `cave export` colors the same way on a terminal. |
 | `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`. |
+| `query [--db p] <pattern…>` | `--json`, `--all`, `--aliases`, `--as-of <t>`, `--resolve`, `--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). `--aliases` widens matching through the §13.6 closure; `--as-of <t>` reconstructs belief at a past date/timestamp/tx (spec §12.3); `--resolve` matches only the winners the §26 resolution policy picks among contested facts (incompatible with `--all`). `--no-prelude` aligns the read-time registry with a store written via `add --no-prelude`. |
+| `resolve [--db p]` | `--aliases`, `--policy`, `--json`, `--no-prelude` | Contested facts under the §26 resolution policy: every fact more than one belief series speaks about, candidates ranked (precedence class, reliability-weighted confidence, tx) with the winner first — what `query --resolve` would match. `--policy` prints the effective policy instead: the built-in precedence ladder merged with in-band `source/<name> HAS precedence:` / `HAS reliability:` declarations. |
 | `derive [--db p] [rules.cave…]` | `--dry-run`, `--full`, `--aliases`, `--min-conf <p>`, `--max-passes <n>`, `--list`, `--retract <r>`, `--json`, `--no-prelude` | Declare and fire rules (spec §24, see [`@cavelang/rules`](../rules)): `premises => conclusion` forward chaining over current beliefs, `BECAUSE`/`VIA` lineage, watermark-incremental and idempotent; retracts conclusions whose premises no longer hold. |
 | `act [--db p] <name> [p=v…]` | `--declare`, `--list`, `--retract <n>`, `--dry-run`, `--no-check`, `--aliases`, `--hooks <file>`, `--json`, `--no-prelude` | Execute an action template (spec §25, see [`@cavelang/act`](../act)): validate parameters, check CAVE-Q preconditions against current belief, append effects atomically with lineage inside the §20.3 shape gate; out-of-band hooks fire after commit. |
 | `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]` | `--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. |
+| `suggest-alias [--db p]` | `--min <s>`, `--limit <n>`, `--agent <template>`, `--timeout <s>`, `--write`, `--json`, `--no-prelude` | Alias discovery (spec §27, see [`@cavelang/shape`](../shape)): same-entity candidates from string/graph similarity as suggested `ALIAS` claims at review-band confidence (0.3–0.5). Prints pipeable CAVE text; `--write` appends stamped `@src:suggest/alias`; `--agent` runs an LLM judge over the candidates (the ingest/eval shell contract). Pairs with any recorded `ALIAS` history are never re-suggested. |
+| `sync [--db p] <source>` | `--as <label>`, `--into <label>`, `--dry-run`, `--no-record`, `--json`, `--no-prelude` | Store merge (spec §28, see [`@cavelang/sync`](../sync)): another CAVE store file — or `;@`-annotated canonical text, `-` for stdin — merges by row identity; present rows skip, re-runs merge nothing, effective merges append a `SYNCED-INTO` record (`--no-record` for checkouts, spec §28.6). |
+| `export [--db p]` | `--out <file>`, `--current`, `--tx`, `--no-prelude` | Canonical CAVE text — all rows in tx order, or current beliefs only. `--tx` precedes every claim line with its `;@` transaction annotation (spec §28.4), so the text carries row identity: the committed, reviewable store text of the §28.6 branching convention. Stdout by default; `--out` writes a file and reports the claim count. |
+| `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/fuse/search/about/neighbors/reconstruct/derive/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. |
 | `eval <suite…>` | see `cave eval --help` | Golden-fixture extraction/query evals (ROADMAP item 9, see [`@cavelang/eval`](../eval)): N fresh-store runs against any agent, claim-key + value scoring with §9.5 actor-stamp normalization, CAVE-Q expectations, optional LLM judge, `--min` CI gate. |
 | `connect <source>` | see `cave connect --help` | Deterministic structured ingestion (spec §23, see [`@cavelang/connect`](../connect)): CSV/TSV/JSON/JSONL/SQLite/URL records through `?field` mapping templates, per-record digests, `--watch`, `--prune`, query-time `--query` overlay. |
+| `reconstruct [--db p] <seed…>` | `--query <text>`, `--agent <template>`, `--steps <n>`, `--claims <n>`, `--timeout <s>`, `--trace`, `--no-prelude` | Active memory reconstruction from seed cues (spec §18, see [`@cavelang/loop`](../loop)): best-first traversal collecting related claims as canonical CAVE text; the heuristic policy by default, an LLM select/stop policy with `--agent` (ROADMAP item 10). |
 | `demo` | | The cave-loop multi-hop recovery demo (§18). |
 | `version` | | Print the cave version. |
 | `help [command]` | | The overview, or one command's options and examples. |

package/dist/src/cli.d.ts

@@ -8,11 +8,14 @@
  * - `cave parse [file]` — lint / dump the AST (`--json`)
  * - `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 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 check [--db <path>]` — knowledge health report (`--stale`, `--json`)
- * - `cave export [--db <path>]` — canonical text out (`--current`)
+ * - `cave suggest-alias [--db <path>]` — same-entity candidates (spec §27; async, routed in `main.ts`)
+ * - `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 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`)
@@ -28,7 +31,7 @@ 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 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 act [--db <path>] <name> [p=v...]   execute an action (spec \u00A725) [--dry-run] [--no-check] [--hooks <file>]\n  cave act --declare [file...]             declare actions from a CAVE document; --list / --retract <name> manage them\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 eval <suite..> --agent '<command>'  golden-fixture extraction/query/reconstruction evals (items 9, 10)\n  cave connect <source> --map <file>       deterministic structured ingestion (CSV/JSON/SQLite/URL, spec \u00A723)\n  cave reconstruct [--db <path>] <seed..>  reconstruct memory from seed cues (spec \u00A718) [--agent] [--query] [--trace]\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>] [--resolve] [--no-prelude]\n  cave resolve [--db <path>]               contested facts + winners (spec \u00A726) [--aliases] [--policy] [--json]\n  cave derive [--db <path>] [rules.cave..] declare + fire rules (spec \u00A724) [--dry-run] [--full] [--list] [--retract <rule>]\n  cave act [--db <path>] <name> [p=v...]   execute an action (spec \u00A725) [--dry-run] [--no-check] [--hooks <file>]\n  cave act --declare [file...]             declare actions from a CAVE document; --list / --retract <name> manage them\n  cave check [--db <path>]                 knowledge health report (spec \u00A720) [--stale <days>] [--json]\n  cave suggest-alias [--db <path>]         propose same-entity ALIAS candidates (spec \u00A727) [--min <s>] [--agent] [--write]\n  cave sync [--db <path>] <source>         merge another store by row identity (spec \u00A728) [--dry-run] [--as] [--into]\n  cave export [--db <path>] [--out <file>] emit canonical CAVE text [--current] [--tx] [--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 eval <suite..> --agent '<command>'  golden-fixture extraction/query/reconstruction evals (items 9, 10)\n  cave connect <source> --map <file>       deterministic structured ingestion (CSV/JSON/SQLite/URL, spec \u00A723)\n  cave reconstruct [--db <path>] <seed..>  reconstruct memory from seed cues (spec \u00A718) [--agent] [--query] [--trace]\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;
@@ -53,9 +56,29 @@ export declare const addCommand: (argv: readonly string[]) => Output;
  */
 export declare const importCommand: (argv: readonly string[]) => Output;
 export declare const queryCommand: (argv: readonly string[]) => Output;
+/**
+ * `cave resolve` — the human view of contradiction resolution (spec §26.4):
+ * contested facts with their candidates ranked as the policy sees them,
+ * or the effective policy itself under `--policy`.
+ */
+export declare const resolveCommand: (argv: readonly string[]) => Output;
 export declare const deriveCommand: (argv: readonly string[]) => Output;
 export declare const actCommand: (argv: readonly string[]) => Output;
 export declare const checkCommand: (argv: readonly string[]) => Output;
+/**
+ * `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`.
+ */
+export declare const suggestAliasCommand: (argv: readonly string[]) => Promise<Output>;
+/**
+ * `cave sync` — store merge (spec §28): another store's rows arrive by
+ * identity — a store file merges through SQL, `;@`-annotated canonical
+ * text (`cave export --tx`, or `-` for stdin) replays under its recorded
+ * ids. Idempotent: re-runs merge nothing and append no record.
+ */
+export declare const syncCommand: (argv: readonly string[]) => Output;
 export declare const exportCommand: (argv: readonly string[]) => Output;
 /**
  * `cave reconstruct` — the §18 loop over the store: heuristic policy by

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

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAoBH,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,wkEAwBgC,CAAA;AAIlD,2FAA2F;AAC3F,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA+Q9C,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;AA8CD,eAAO,MAAM,UAAU,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAsFpD,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;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAU,MAAM,SAAS,MAAM,EAAE,KAAG,OAAO,CAAC,MAAM,CAgEhF,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,MA2C9C,CAAA"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAyBH,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,88EA2BgC,CAAA;AAIlD,2FAA2F;AAC3F,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAqZ9C,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,MA8CtD,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MA+CxD,CAAA;AAED,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAsHvD,CAAA;AA8CD,eAAO,MAAM,UAAU,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAsFpD,CAAA;AAqCD,eAAO,MAAM,YAAY,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MA0BtD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,GAAU,MAAM,SAAS,MAAM,EAAE,KAAG,OAAO,CAAC,MAAM,CA6DjF,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAmDrD,CAAA;AAED,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,MAAM,EAAE,KAAG,MAwBvD,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAU,MAAM,SAAS,MAAM,EAAE,KAAG,OAAO,CAAC,MAAM,CAgEhF,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,MA+C9C,CAAA"}

package/dist/src/cli.js

@@ -8,11 +8,14 @@
  * - `cave parse [file]` — lint / dump the AST (`--json`)
  * - `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 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 check [--db <path>]` — knowledge health report (`--stale`, `--json`)
- * - `cave export [--db <path>]` — canonical text out (`--current`)
+ * - `cave suggest-alias [--db <path>]` — same-entity candidates (spec §27; async, routed in `main.ts`)
+ * - `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 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`)
@@ -30,11 +33,12 @@ 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 { 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 { emitClaim } from '@cavelang/canonical';
+import { labelOf, sanitizeLabel, syncFile, syncText } from '@cavelang/sync';
+import { emitClaim, txOfLine } from '@cavelang/canonical';
 const ok = (out) => ({ code: 0, out, err: '' });
 const fail = (err, code = 1) => ({ code, out: '', err });
 export const usage = `cave — Compressed Atomic Verb Expressions
@@ -44,12 +48,15 @@ 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>] [--no-prelude]
+  cave query [--db <path>] <pattern>       run a CAVE-Q pattern [--json] [--all] [--aliases] [--as-of <t>] [--resolve] [--no-prelude]
+  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 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 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 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)
@@ -131,7 +138,10 @@ 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. Unlike
 \`cave add\`, import never stamps actor provenance — replayed claims must
-keep the claim keys they were exported with (spec §9.5).
+keep the claim keys they were exported with (spec §9.5). Import always
+mints fresh transaction ids — ;@ annotations in a \`cave export --tx\`
+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
@@ -139,7 +149,7 @@ Examples:
     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>] [--no-prelude]
+  cave query [--db <path>] <pattern> [WHERE <filter>] [--json] [--all] [--aliases] [--as-of <t>] [--resolve] [--no-prelude]
 
 Options:
   ${dbHelp}
@@ -149,6 +159,11 @@ Options:
   --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
+  --resolve      match resolved winners only (spec §26): contested facts —
+                 same fact from several sources, or opposite polarity —
+                 collapse to the row the resolution policy picks
+                 (precedence class, reliability-weighted confidence, tx);
+                 incompatible with --all
   --no-prelude   open the store without the standard verb registry
 
 Patterns are claim triples with ?variables and optional metadata filters
@@ -162,7 +177,38 @@ Examples:
   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 'service HAS owner: ?who' --resolve
   cave query --db k.db '?x ?verb ?y @production' --json`,
+    resolve: `cave resolve — contested facts and their winners (spec §26)
+
+Usage:
+  cave resolve [--db <path>] [--aliases] [--policy] [--json] [--no-prelude]
+
+Options:
+  ${dbHelp}
+  --aliases      widen resolution groups through current ALIAS claims
+                 (spec §13.6) — aliased names contest one fact
+  --policy       print the effective resolution policy instead: the
+                 built-in precedence ladder merged with in-band
+                 source/<name> HAS precedence: / HAS reliability: claims
+  --json         emit the report as JSON
+  --no-prelude   open the store without the standard verb registry
+
+Lists every fact more than one belief series currently speaks about —
+same fact from different sources (§9.5 actor stamps, content sources)
+or opposite polarity — with the candidates ranked as the resolution
+policy sees them: precedence class first, reliability-weighted
+confidence second, latest transaction last. The winner is what
+\`cave query --resolve\` matches; the rest are invisible there. Declare
+policy overrides in-band, e.g.:
+
+  source/scanner-a HAS reliability: 60%
+  source/ingest HAS precedence: 1
+
+Examples:
+  cave resolve --db k.db
+  cave resolve --db k.db --aliases
+  cave resolve --db k.db --policy`,
     derive: `cave derive — declare and fire rules (spec §24)
 
 Usage:
@@ -269,21 +315,113 @@ Examples:
   cave check --db k.db
   cave check --db k.db --stale 30
   cave check --db k.db --json | jq '.violations'`,
+    'suggest-alias': `cave suggest-alias — propose same-entity ALIAS candidates for review (spec §27)
+
+Usage:
+  cave suggest-alias [--db <path>] [options]
+
+Options:
+  ${dbHelp}
+  --min <s>            minimum evidence score, 0..1 or N% (default 60%)
+  --limit <n>          at most n suggestions, strongest first
+  --agent <template>   LLM judge filtering the candidates — the cave
+                       ingest/eval shell contract: the prompt (each pair
+                       with both sides' current claims) is piped to stdin
+                       and {prompt-file} is substituted; stdout replies
+                       with a JSON array of confirmed suggestion numbers
+  --timeout <seconds>  judge timeout (default 120)
+  --write              append the suggestions, stamped @src:suggest/alias,
+                       instead of only printing them
+  --json               print suggestions with scores and signals as JSON
+  --no-prelude         open the store without the standard verb registry
+
+Candidates come from string similarity (case/separator drift, segment
+containment, prefixes, typos) and shared rare attribute values; shared
+relations strengthen a candidate but never create one. Suggested claims
+are questions, not merges: confidence 30–50% puts them in cave check's
+review band, and a pair with any recorded ALIAS history — merged,
+rejected or unmerged — is never suggested again.
+
+Output is CAVE text: review it, edit it, pipe it into cave add — or
+--write it and review afterwards. A written suggestion is a positive
+claim, so the opt-in §13.6 closure links it until reviewed:
+
+  confirm   echo 'dupe ALIAS canonical' | cave add --db k.db
+  reject    echo 'dupe ALIAS canonical @src:suggest/alias @ 0%' | cave add --db k.db
+
+(rejection retracts the suggestion's own series — contexts are part of
+claim identity, §9.2, so a plain @ 0% append would start a new series
+and leave the suggested link standing).
+
+Examples:
+  cave suggest-alias --db k.db
+  cave suggest-alias --db k.db --min 80% --limit 10
+  cave suggest-alias --db k.db | cave add --db k.db
+  cave suggest-alias --db k.db --agent 'claude -p' --write`,
+    sync: `cave sync — merge another store into this one by row identity (spec §28)
+
+Usage:
+  cave sync [--db <path>] <source> [--as <label>] [--into <label>]
+            [--dry-run] [--no-record] [--json] [--no-prelude]
+
+Options:
+  ${dbHelp}
+  --as <label>   origin label in the merge record (default: the source
+                 file's basename stem; stdin defaults to "stdin")
+  --into <label> target label in the merge record (default: the database
+                 file's basename stem)
+  --dry-run      compute the full report inside a rolled-back transaction
+  --no-record    do not append the store/<from> SYNCED-INTO store/<into>
+                 merge record
+  --json         emit the report as JSON
+  --no-prelude   open the store without the standard verb registry
+
+The source is a CAVE store file (recognized by the SQLite header),
+canonical text with ;@ transaction annotations (cave export --tx), or -
+for annotated text on stdin. Rows merge by identity: a row's UUIDv7 is
+its id everywhere, so present rows skip, re-runs merge nothing, and two
+stores syncing each other converge. Contradictions coexist (spec §9.4)
+and resolve at read time (cave resolve, --resolve); everything appended
+after a merge outsorts everything merged, whatever the origin machine's
+clock read (spec §28.2). An effective merge appends one record claim,
+stamped @src:sync — the sync log is its belief series.
+
+Branching (spec §28.6): commit the full annotated export — the text is
+the store — and rebuild working stores from it. A checkout is plumbing
+(--no-record); landing reviewed text into a live store is a real merge
+event (let it record). Never hand-merge exports: sync both sides into
+a fresh store and re-export — the union — which git can run for you as
+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 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] [--no-prelude]
+  cave export [--db <path>] [--out <file>] [--current] [--tx] [--no-prelude]
 
 Options:
   ${dbHelp}
   --out <file>   write to a file instead of stdout
   --current      current beliefs only (skip superseded rows)
+  --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
 
 Examples:
   cave export --db k.db
   cave export --db k.db --out backup.cave
-  cave export --db k.db --current --out snapshot.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,
+                                    # reviewable store text (spec §28.6)`,
     reconstruct: `cave reconstruct — active memory reconstruction from seed cues (spec §18)
 
 Usage:
@@ -441,6 +579,7 @@ export const queryCommand = (argv) => {
             all: { type: 'boolean' },
             aliases: { type: 'boolean' },
             'as-of': { type: 'string' },
+            resolve: { type: 'boolean' },
             'no-prelude': { type: 'boolean' }
         },
         allowPositionals: true
@@ -454,6 +593,7 @@ export const queryCommand = (argv) => {
         const matches = caveQuery(store, pattern, {
             all: values.all === true,
             aliases: values.aliases === true,
+            resolve: values.resolve === true,
             ...values['as-of'] === undefined ? {} : { asOf: values['as-of'] }
         });
         if (values.json === true) {
@@ -479,6 +619,59 @@ export const queryCommand = (argv) => {
         store.close();
     }
 };
+/**
+ * `cave resolve` — the human view of contradiction resolution (spec §26.4):
+ * contested facts with their candidates ranked as the policy sees them,
+ * or the effective policy itself under `--policy`.
+ */
+export const resolveCommand = (argv) => {
+    const { values } = parseArgs({
+        args: [...argv],
+        options: {
+            db: { type: 'string' },
+            aliases: { type: 'boolean' },
+            policy: { type: 'boolean' },
+            json: { type: 'boolean' },
+            'no-prelude': { type: 'boolean' }
+        },
+        allowPositionals: false
+    });
+    const percent = (value) => `${Math.round(value * 1000) / 10}%`;
+    const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {});
+    try {
+        if (values.policy === true) {
+            const policy = store.resolutionPolicy();
+            if (values.json === true) {
+                return ok(`${JSON.stringify(policy, undefined, 2)}\n`);
+            }
+            const width = Math.max(...policy.map(entry => entry.prefix.length + 7));
+            const lines = policy.map(entry => {
+                const subject = entry.prefix === '' ? 'source' : `source/${entry.prefix}`;
+                const dimensions = [
+                    ...entry.precedence === undefined ? [] : [`precedence ${entry.precedence}`],
+                    ...entry.reliability === undefined ? [] : [`reliability ${percent(entry.reliability)}`]
+                ];
+                return `${subject.padEnd(width)}  ${dimensions.join(', ')}`;
+            });
+            return ok(`${lines.join('\n')}\n`);
+        }
+        const contested = store.contested({ aliases: values.aliases === true });
+        if (values.json === true) {
+            return ok(`${JSON.stringify(contested, undefined, 2)}\n`);
+        }
+        if (contested.length === 0) {
+            return ok('no contested facts\n');
+        }
+        const lines = contested.flatMap(group => group.rows.map((row, at) => `${at === 0 ? '' : '  over '}${row.raw_line} ; class ${row.res_class}, effective ${percent(row.res_conf)}`));
+        return ok(`${lines.join('\n')}\n`);
+    }
+    catch (error) {
+        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
+    }
+    finally {
+        store.close();
+    }
+};
 export const deriveCommand = (argv) => {
     const { values, positionals } = parseArgs({
         args: [...argv],
@@ -791,12 +984,141 @@ export const checkCommand = (argv) => {
         store.close();
     }
 };
+/**
+ * `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`.
+ */
+export const suggestAliasCommand = async (argv) => {
+    try {
+        const { values } = parseArgs({
+            args: [...argv],
+            options: {
+                db: { type: 'string' },
+                min: { type: 'string' },
+                limit: { type: 'string' },
+                agent: { type: 'string' },
+                timeout: { type: 'string' },
+                write: { type: 'boolean' },
+                json: { type: 'boolean' },
+                'no-prelude': { type: 'boolean' },
+                help: { type: 'boolean', short: 'h' }
+            },
+            allowPositionals: false
+        });
+        if (values.help === true) {
+            return ok(`${commandHelp['suggest-alias']}\n`);
+        }
+        const minScore = values.min === undefined ?
+            defaultMinScore :
+            values.min.endsWith('%') ? Number(values.min.slice(0, -1)) / 100 : Number(values.min);
+        if (!Number.isFinite(minScore) || minScore < 0 || minScore > 1) {
+            return fail(`cave suggest-alias: --min expects a score in 0..1 or N%, got ${JSON.stringify(values.min)}\n`);
+        }
+        const limit = values.limit === undefined ? undefined : Number(values.limit);
+        if (limit !== undefined && (!Number.isInteger(limit) || limit < 1)) {
+            return fail(`cave suggest-alias: --limit expects a positive integer, got ${JSON.stringify(values.limit)}\n`);
+        }
+        const timeoutSeconds = values.timeout === undefined ? undefined : Number(values.timeout);
+        if (timeoutSeconds !== undefined && (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0)) {
+            return fail(`cave suggest-alias: --timeout must be a positive number of seconds, got '${values.timeout}'\n`);
+        }
+        const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {});
+        try {
+            let suggestions = suggestAliases(store, { minScore, ...limit === undefined ? {} : { limit } });
+            if (values.agent !== undefined && suggestions.length > 0) {
+                const reply = await shellComplete(values.agent, timeoutSeconds === undefined ? {} : { timeoutSeconds })(judgePrompt(store, suggestions));
+                suggestions = parseJudgeReply(reply, suggestions.length).map(index => suggestions[index]);
+            }
+            if (values.json === true) {
+                return ok(`${JSON.stringify(suggestions, undefined, 2)}\n`);
+            }
+            if (suggestions.length === 0) {
+                return ok('no alias suggestions\n');
+            }
+            const lines = suggestions.map(suggestion => suggestion.line);
+            if (values.write === true) {
+                const { appended } = writeSuggestions(store, suggestions);
+                return ok(`${lines.join('\n')}\nappended ${appended} suggested alias claim(s)\n`);
+            }
+            return ok(`${lines.join('\n')}\n`);
+        }
+        finally {
+            store.close();
+        }
+    }
+    catch (error) {
+        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
+    }
+};
+/**
+ * `cave sync` — store merge (spec §28): another store's rows arrive by
+ * identity — a store file merges through SQL, `;@`-annotated canonical
+ * text (`cave export --tx`, or `-` for stdin) replays under its recorded
+ * ids. Idempotent: re-runs merge nothing and append no record.
+ */
+export const syncCommand = (argv) => {
+    const { values, positionals } = parseArgs({
+        args: [...argv],
+        options: {
+            db: { type: 'string' },
+            as: { type: 'string' },
+            into: { type: 'string' },
+            'dry-run': { type: 'boolean' },
+            'no-record': { type: 'boolean' },
+            json: { type: 'boolean' },
+            'no-prelude': { type: 'boolean' }
+        },
+        allowPositionals: true
+    });
+    const [source, ...extra] = positionals;
+    if (source === undefined || extra.length > 0) {
+        return fail('cave sync: exactly one source is required — a CAVE store file, ;@-annotated text, or - for stdin (spec §28.5)\n');
+    }
+    const dbPath = values.db ?? defaultDbPath();
+    const store = open(dbPath, values['no-prelude'] === true ? { registry: Registry.empty } : {});
+    try {
+        const options = {
+            into: values.into === undefined ? labelOf(dbPath) : sanitizeLabel(values.into),
+            record: values['no-record'] !== true,
+            dryRun: values['dry-run'] === true,
+            ...values.as === undefined ? {} : { from: sanitizeLabel(values.as) }
+        };
+        const report = source === '-' ?
+            syncText(store, readFileSync(0, 'utf8'), { 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: '' };
+        }
+        if (report.problems.length > 0) {
+            const detail = report.problems.map(problem => `  line ${problem.line}: ${problem.message}`).join('\n');
+            return fail(`cave sync: ${source}: ${report.problems.length} problem(s), nothing merged\n${detail}\n`);
+        }
+        const lines = [
+            `merged ${report.merged} claim(s), ${report.edges} edge(s)` +
+                (report.skipped > 0 ? `, ${report.skipped} already present` : '') +
+                (report.dryRun ? ' (dry run)' : '')
+        ];
+        if (report.record !== undefined) {
+            lines.push(`record: ${report.record}`);
+        }
+        return ok(`${lines.join('\n')}\n`);
+    }
+    catch (error) {
+        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
+    }
+    finally {
+        store.close();
+    }
+};
 export const exportCommand = (argv) => {
     const { values } = parseArgs({
         args: [...argv],
         options: {
             db: { type: 'string' },
             current: { type: 'boolean' },
+            tx: { type: 'boolean' },
             out: { type: 'string' },
             'no-prelude': { type: 'boolean' }
         },
@@ -804,12 +1126,12 @@ export const exportCommand = (argv) => {
     });
     const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {});
     try {
-        const text = store.exportText({ current: values.current === true });
+        const text = store.exportText({ current: values.current === true, tx: values.tx === true });
         if (values.out === undefined) {
             return ok(text);
         }
         writeFileSync(values.out, text);
-        const claims = text === '' ? 0 : text.trimEnd().split('\n').length;
+        const claims = text === '' ? 0 : text.trimEnd().split('\n').filter(line => txOfLine(line) === undefined).length;
         return ok(`exported ${claims} claim(s) to ${values.out}\n`);
     }
     finally {
@@ -918,12 +1240,16 @@ export const cave = (argv) => {
                 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 'demo':