@cavelang/cli 0.33.0 → 0.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavelang/cli",
-  "version": "0.33.0",
+  "version": "0.35.0",
   "type": "module",
   "description": "cave — CLI for parsing, storing, querying and exporting CAVE knowledge.",
   "keywords": [
@@ -97,26 +97,26 @@
     "@modelcontextprotocol/server": "2.0.0",
     "@mozilla/readability": "^0.6.0",
     "linkedom": "^0.18.13",
-    "@cavelang/fusion": "0.33.0",
-    "@cavelang/canonical": "0.33.0",
-    "@cavelang/core": "0.33.0",
-    "@cavelang/parser": "0.33.0",
-    "@cavelang/store": "0.33.0",
-    "@cavelang/query": "0.33.0",
-    "@cavelang/highlight": "0.33.0"
+    "@cavelang/canonical": "0.35.0",
+    "@cavelang/fusion": "0.35.0",
+    "@cavelang/core": "0.35.0",
+    "@cavelang/highlight": "0.35.0",
+    "@cavelang/parser": "0.35.0",
+    "@cavelang/query": "0.35.0",
+    "@cavelang/store": "0.35.0"
   },
   "devDependencies": {
-    "@cavelang/act": "0.33.0",
-    "@cavelang/automate": "0.33.0",
-    "@cavelang/connect": "0.33.0",
-    "@cavelang/eval": "0.33.0",
-    "@cavelang/ingest": "0.33.0",
-    "@cavelang/loop": "0.33.0",
-    "@cavelang/mcp": "0.33.0",
-    "@cavelang/rules": "0.33.0",
-    "@cavelang/shape": "0.33.0",
-    "@cavelang/view": "0.33.0",
-    "@cavelang/sync": "0.33.0"
+    "@cavelang/act": "0.35.0",
+    "@cavelang/automate": "0.35.0",
+    "@cavelang/eval": "0.35.0",
+    "@cavelang/connect": "0.35.0",
+    "@cavelang/ingest": "0.35.0",
+    "@cavelang/loop": "0.35.0",
+    "@cavelang/rules": "0.35.0",
+    "@cavelang/shape": "0.35.0",
+    "@cavelang/mcp": "0.35.0",
+    "@cavelang/sync": "0.35.0",
+    "@cavelang/view": "0.35.0"
   },
   "scripts": {
     "build": "tsc -b && node scripts/consolidate.mjs",

package/src/cli.ts

@@ -41,8 +41,9 @@ import { parseArgs } from 'node:util'
 import { Version } from '@cavelang/core'
 import { parseDocument, Token } from '@cavelang/parser'
 import { Registry, standardRegistry } from '@cavelang/canonical'
-import { Sensitivity, backup as backupStore, defaultDbPath, open, restoreBackup, verifyBackup } from '@cavelang/store'
-import type { Store } from '@cavelang/store'
+import { backup as backupStore, defaultDbPath, kindOf, LocateError, openAt, restoreBackup, Sensitivity, verifyBackup } from '@cavelang/store'
+import type { OpenIntent, Store } from '@cavelang/store'
+import { Declared, assemble as assembleSources } from '@cavelang/connect'
 import { defaultLimit as defaultQueryLimit, maxLimit as maxQueryLimit, page as caveQueryPage } from '@cavelang/query'
 import {
   check as caveCheck, defaultMinScore, defaultStaleDays, gatedIngest, judgePrompt, parseJudgeReply,
@@ -142,10 +143,12 @@ Usage:
   cave help [command]                      this text, or one command's options and examples
 
 Every command answers --help. --db defaults to $CAVE_DB, or cave.db in
-the current directory. The spec lives in the .claude/skills/ directory at
+the current directory, and names a SQLite store or a CAVE text file: text
+replays into an in-memory store for commands that only read (writes refuse
+it), and a read never creates a missing database. The spec lives in the .claude/skills/ directory at
 the repository root (section index in README.md).`
 
-const dbHelp = `--db <path>    database file (default: $CAVE_DB, or cave.db)`
+const dbHelp = `--db <path>    store: a SQLite file, or CAVE text read into memory (default: $CAVE_DB, or cave.db)`
 
 /** Per-command help, printed for \`cave <command> --help\` and \`cave help <command>\`. */
 export const commandHelp: Record<string, string> = {
@@ -250,7 +253,7 @@ Examples:
   query: `cave query — run a CAVE-Q pattern against a store
 
 Usage:
-  cave query [--db <path>] <pattern> [WHERE <filter>] [--limit <n>] [--cursor <token>] [--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] [--sources] [--no-prelude]
 
 Options:
   ${dbHelp}
@@ -276,6 +279,12 @@ Options:
                  collapse to the row the resolution policy picks
                  (precedence class, reliability-weighted confidence, tx);
                  incompatible with --all
+  --sources      overlay the store's declared sources (spec §23.4) inside a
+                 rolled-back transaction — federation-lite: external data is
+                 consulted at query time, nothing persists. The answer is
+                 whole (no --cursor, --limit is not a page size); a text
+                 store followed its local sources on open, so only URL
+                 sources are loaded here
   --no-prelude   open the store without the standard verb registry
 
 Patterns are claim triples with ?variables and optional metadata filters
@@ -286,6 +295,7 @@ with the answer; fully bound patterns print the raw line, comment included.
 
 Examples:
   cave query '?x USES jwt'
+  cave query --db notes.cave '?x USES jwt'
   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'
@@ -294,6 +304,7 @@ Examples:
   cave query --db k.db 'revenue IS' --at 2026-07
   cave query --db k.db 'alice WORKS-AT ?org' --at 2021
   cave query --db k.db 'service HAS owner: ?who' --resolve
+  cave query --db k.db '?who WORKS-AT acme' --sources
   cave query --db k.db '?x ?verb ?y @production' --json`,
 
   search: `cave search — full-text search over claims and comments (spec §13.2)
@@ -782,6 +793,57 @@ const readStdin = (): string => {
   }
 }
 
+/**
+ * Opens the store `--db` names (spec §13.7): a SQLite file, or a CAVE text
+ * file replayed into memory. `read` never creates, migrates, or changes a
+ * file — a missing path is an error, not an empty database; `scratch` is a
+ * dry run that appends inside a rolled-back transaction, so it may write
+ * but creates and migrates nothing; `write` creates a missing SQLite store,
+ * migrates an older one, and refuses text files with the materialization
+ * hint.
+ */
+const openDb = (values: { db?: string, 'no-prelude'?: boolean }, intent: OpenIntent): Store =>
+  openAt(values.db ?? defaultDbPath(), {
+    intent,
+    // A text store follows its declared sources on open (spec §23.4).
+    assemble: assembleSources,
+    ...values['no-prelude'] === true ? { registry: Registry.empty } : {}
+  })
+
+const sourcesRollback = Symbol('cave query --sources rollback')
+
+/**
+ * Runs `body` with the store's declared sources overlaid (spec §23.4): the
+ * sources, loaded beforehand (URLs included), append inside a transaction
+ * that always rolls back, so external data is consulted at query time and
+ * nothing persists, digests included.
+ */
+const withSources = <T>(store: Store, discovered: Declared.Discovery, body: () => T): undefined | { value: T } => {
+  let result: undefined | { value: T }
+  try {
+    store.transaction(() => {
+      // Discovered on a snapshot: if a writer changed the declarations
+      // since, the sequence is stale and the caller rediscovers.
+      if (!Declared.sameDeclarations(discovered.baseline, Declared.declarationState(store))) {
+        throw sourcesRollback
+      }
+      for (const source of discovered.sequence) {
+        const report = Declared.run(store, source, { force: true })
+        if (report.failures.length > 0) {
+          throw new LocateError(`source/${source.declared.name}: ${report.failures.map(failure => `${failure.record}: ${failure.problems.join('; ')}`).join('; ')}`)
+        }
+      }
+      result = { value: body() }
+      throw sourcesRollback
+    })
+  } catch (error) {
+    if (error !== sourcesRollback) {
+      throw error
+    }
+  }
+  return result
+}
+
 const readInput = (files: readonly string[]): string =>
   files.length === 0 || (files.length === 1 && files[0] === '-') ?
     readStdin() :
@@ -865,7 +927,7 @@ const ingestCommand = (name: 'add' | 'import') => (argv: readonly string[]): Out
     allowPositionals: true
   })
   const input = readInput(positionals)
-  const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  const store = openDb(values, 'write')
   try {
     const options = {
       strict: values.strict === true,
@@ -911,39 +973,150 @@ export const addCommand = ingestCommand('add')
  */
 export const importCommand = ingestCommand('import')
 
-export const queryCommand = (argv: readonly string[]): Output => {
-  const { values, positionals } = parseArgs({
-    args: [...argv],
-    options: {
-      db: { type: 'string' },
-      json: { type: 'boolean' },
-      all: { type: 'boolean' },
-      aliases: { type: 'boolean' },
-      'as-of': { type: 'string' },
-      at: { type: 'string' },
-      resolve: { type: 'boolean' },
-      limit: { type: 'string' },
-      cursor: { type: 'string' },
-      'no-prelude': { type: 'boolean' }
-    },
-    allowPositionals: true
-  })
+const queryOptions = {
+  db: { type: 'string' },
+  json: { type: 'boolean' },
+  all: { type: 'boolean' },
+  aliases: { type: 'boolean' },
+  'as-of': { type: 'string' },
+  at: { type: 'string' },
+  resolve: { type: 'boolean' },
+  sources: { type: 'boolean' },
+  limit: { type: 'string' },
+  cursor: { type: 'string' },
+  'no-prelude': { type: 'boolean' }
+} as const
+
+type QueryValues = {
+  db?: string
+  json?: boolean
+  all?: boolean
+  aliases?: boolean
+  'as-of'?: string
+  at?: string
+  resolve?: boolean
+  sources?: boolean
+  limit?: string
+  cursor?: string
+  'no-prelude'?: boolean
+}
+
+const parseQuery = (argv: readonly string[]): { values: QueryValues, pattern: string } | { failure: Output } => {
+  const { values, positionals } = parseArgs({ args: [...argv], options: queryOptions, allowPositionals: true })
   if (positionals.length === 0) {
-    return fail('cave query: a pattern is required (spec §12.1)\n')
+    return { failure: fail('cave query: a pattern is required (spec §12.1)\n') }
+  }
+  if (values.sources === true && values.cursor !== undefined) {
+    return { failure: fail('cave query: --cursor does not apply to --sources — the overlay exists for one invocation and is answered whole\n') }
   }
-  const pattern = positionals.join('\n')
-  const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  return { values, pattern: positionals.join('\n') }
+}
+
+/**
+ * `cave query --sources` — the store with its declared sources overlaid
+ * (spec §23.4). Asynchronous because the sources load first, URLs
+ * included, before the overlay appends inside a transaction that rolls
+ * back; the dispatcher routes `--sources` here. A text store followed its
+ * local sources on open, so only what assembly could not follow — URL
+ * sources and what they declare — is loaded. The overlay exists for this
+ * invocation alone, so the answer is whole: pages are followed inside the
+ * transaction and no cursor is handed out.
+ */
+export const querySourcesCommand = async (
+  argv: readonly string[],
+  runtime: { readonly fetchImpl?: Declared.DiscoverOptions['fetchImpl'] } = {}
+): Promise<Output> => {
+  const parsed = parseQuery(argv)
+  if ('failure' in parsed) {
+    return parsed.failure
+  }
+  const { values, pattern } = parsed
+  if (values.sources !== true) {
+    return queryCommand(argv)
+  }
+  const root = values.db ?? defaultDbPath()
+  // The overlay appends inside a transaction it rolls back: writable, but
+  // never creating or migrating (spec §13.7).
+  const store = openDb(values, 'scratch')
   try {
-    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 }
-    })
+    for (let attempt = 0; attempt < Declared.overlayAttempts; attempt += 1) {
+      const discovered = await Declared.discovery(store, root, {
+        // The overlay applies every source it loads (force), so discovery
+        // simulates that; a text store skips what assembly already followed.
+        force: true,
+        ...kindOf(root) === 'text' ? { skipFollowed: true } : {},
+        ...runtime.fetchImpl === undefined ? {} : { fetchImpl: runtime.fetchImpl }
+      })
+      const page = withSources(store, discovered, () => wholeQuery(store, values, pattern))
+      if (page !== undefined) {
+        return renderQueryPage(store, values, pattern, () => page.value)
+      }
+    }
+    throw Declared.staleOverlay()
+  } catch (error) {
+    return fail(`${error instanceof Error ? error.message : String(error)}\n`)
+  } finally {
+    store.close()
+  }
+}
+
+export const queryCommand = (argv: readonly string[]): Output => {
+  const parsed = parseQuery(argv)
+  if ('failure' in parsed) {
+    return parsed.failure
+  }
+  const { values, pattern } = parsed
+  if (values.sources === true) {
+    // Loading sources cannot be synchronous: the in-process entry for the
+    // overlay is `querySourcesCommand`, which the dispatcher uses.
+    return fail('cave query: --sources loads the declared sources first and runs asynchronously — use querySourcesCommand\n')
+  }
+  const store = openDb(values, 'read')
+  try {
+    return renderQueryPage(store, values, pattern, () => queryPage(store, values, pattern))
+  } catch (error) {
+    return fail(`${error instanceof Error ? error.message : String(error)}\n`)
+  } finally {
+    store.close()
+  }
+}
+
+/** Every match of the overlay: the pages are followed here, inside the transaction that holds it. */
+const wholeQuery = (store: Store, values: QueryValues, pattern: string): ReturnType<typeof caveQueryPage> => {
+  const matches: ReturnType<typeof caveQueryPage>['matches'][number][] = []
+  let first: undefined | ReturnType<typeof caveQueryPage>
+  let cursor: undefined | string
+  for (;;) {
+    const page = queryPage(store, { ...values, limit: '1000', ...cursor === undefined ? {} : { cursor } }, pattern)
+    first ??= page
+    matches.push(...page.matches)
+    if (page.next === undefined) {
+      const { next: _next, ...rest } = first
+      return { ...rest, matches }
+    }
+    cursor = page.next
+  }
+}
+
+const queryPage = (store: Store, values: QueryValues, pattern: string): ReturnType<typeof caveQueryPage> =>
+  caveQueryPage(store, pattern, {
+    all: values.all === true,
+    aliases: values.aliases === true,
+    resolve: values.resolve === true,
+    limit: values.limit === undefined ? defaultQueryLimit : Number(values.limit),
+    ...values.cursor === undefined ? {} : { cursor: values.cursor },
+    ...values['as-of'] === undefined ? {} : { asOf: values['as-of'] },
+    ...values.at === undefined ? {} : { at: values.at }
+  })
+
+const renderQueryPage = (
+  store: Store,
+  values: QueryValues,
+  pattern: string,
+  page: () => ReturnType<typeof caveQueryPage>
+): Output => {
+  {
+    const result = page()
     if (values.json === true) {
       return ok(`${JSON.stringify(result, undefined, 2)}\n`)
     }
@@ -972,10 +1145,6 @@ export const queryCommand = (argv: readonly string[]): Output => {
         line
     })
     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 {
-    store.close()
   }
 }
 
@@ -1007,7 +1176,7 @@ export const searchCommand = (argv: readonly string[]): Output => {
   if (!Number.isInteger(limit) || limit < 1 || limit > maxQueryLimit) {
     return fail(`cave search: --limit must be an integer from 1 to ${maxQueryLimit}\n`)
   }
-  const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  const store = openDb(values, 'read')
   try {
     const raw = values.raw === true
     const found = store.search(query, { raw, limit: limit + 1 })
@@ -1057,7 +1226,7 @@ export const resolveCommand = (argv: readonly string[]): Output => {
     allowPositionals: false
   })
   const percent = (value: number): string => `${Math.round(value * 1000) / 10}%`
-  const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  const store = openDb(values, 'read')
   try {
     if (values.policy === true) {
       const policy = store.resolutionPolicy()
@@ -1120,7 +1289,12 @@ export const deriveCommand = (argv: readonly string[]): Output => {
   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 } : {})
+  // The intent follows the branch order below: listing reads, retracting
+  // writes, a dry run appends inside a rolled-back transaction.
+  const store = openDb(values,
+    values.list === true ? 'read' :
+      values.retract !== undefined ? 'write' :
+        values['dry-run'] === true ? 'scratch' : 'write')
   try {
     if (values.list === true) {
       const rules = listRules(store)
@@ -1274,7 +1448,14 @@ export const actCommand = (argv: readonly string[]): Output => {
     },
     allowPositionals: true
   })
-  const store = open(values.db ?? defaultDbPath(), values['no-prelude'] === true ? { registry: Registry.empty } : {})
+  // The intent follows the branch order below: declaring and retracting
+  // write, listing reads, a dry-run execution appends inside a rolled-back
+  // transaction.
+  const store = openDb(values,
+    values.declare === true ? 'write' :
+      values.list === true ? 'read' :
+        values.retract !== undefined ? 'write' :
+          values['dry-run'] === true ? 'scratch' : 'write')
   try {
     if (values.declare === true) {
       const declaration = declareActions(store, readInput(positionals))
@@ -1395,7 +1576,7 @@ export const checkCommand = (argv: readonly string[]): Output => {
   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 } : {})
+  const store = openDb(values, 'read')
   try {
     const report = caveCheck(store, { staleDays })
     const out = values.json === true ?
@@ -1444,7 +1625,15 @@ export const backupCommand = (argv: readonly string[]): Output => {
     if (values.out === undefined) {
       return fail('cave backup: --out <file> is required\n')
     }
-    const store = open(values.db ?? defaultDbPath())
+    const dbPath = values.db ?? defaultDbPath()
+    // A text store is replayed into memory, so the backup API cannot see that
+    // the destination aliases the source: refuse before the file could be
+    // replaced by a SQLite snapshot of itself (a SQLite source is covered by
+    // the API's own check).
+    if (sameFile(dbPath, values.out)) {
+      return fail(`cave backup: --out '${values.out}' is the source database — refusing to overwrite it\n`)
+    }
+    const store = openAt(dbPath, { intent: 'read', assemble: assembleSources })
     try {
       return ok(snapshotLine('created', backupStore(store, values.out, { force: values.force === true })))
     } finally {
@@ -1527,7 +1716,7 @@ export const suggestAliasCommand = async (
     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 } : {})
+    const store = openDb(values, values.write === true ? 'write' : 'read')
     try {
       let suggestions = suggestAliases(store, { minScore, ...limit === undefined ? {} : { limit } })
       if (values.agent !== undefined && suggestions.length > 0) {
@@ -1584,7 +1773,7 @@ export const syncCommand = (argv: readonly string[]): Output => {
     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 } : {})
+  const store = openDb(values, values['dry-run'] === true ? 'scratch' : 'write')
   try {
     const options = {
       into: values.into === undefined ? labelOf(dbPath) : sanitizeLabel(values.into),
@@ -1645,7 +1834,10 @@ export const reportCommand = (argv: readonly string[]): Output => {
   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 } : {})
+  if (values.out !== undefined && sameFile(values.db ?? defaultDbPath(), values.out)) {
+    return fail(`cave report: --out '${values.out}' is the source database — refusing to overwrite it\n`)
+  }
+  const store = openDb(values, 'read')
   try {
     const rendered = caveReport(store, template, {
       aliases: values.aliases === true,
@@ -1713,7 +1905,7 @@ export const exportCommand = (argv: readonly string[]): Output => {
   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 } : {})
+  const store = openDb(values, 'read')
   try {
     const text = store.exportText({ current: values.current === true, tx: values.tx === true, maxSensitivity: maximum })
     if (values.out === undefined) {
@@ -1752,7 +1944,7 @@ export const generateCommand = (argv: readonly string[]): Output => {
   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 } : {})
+  const store = openDb(values, 'read')
   try {
     const generated = generateClient(store, version === undefined ? {} : { version })
     if (!generated.ok) {
@@ -1817,7 +2009,7 @@ export const reconstructCommand = async (
     if (timeoutSeconds !== undefined && (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0)) {
       return fail(`cave reconstruct: --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 } : {})
+    const store = openDb(values, 'read')
     try {
       const graph = sqliteStore(store)
       const result = values.agent === undefined ?
@@ -1902,6 +2094,19 @@ export const cave = (argv: readonly string[]): Output => {
       (rest.includes('--help') || rest.includes('-h'))) {
     return ok(`${commandHelp[canonical]}\n`)
   }
+  try {
+    return run(canonical, rest)
+  } catch (error) {
+    // A --db path that is not what the command needs (spec §13.7) is a
+    // usage failure, reported the way dispatch reports thrown errors.
+    if (error instanceof LocateError) {
+      return fail(`cave ${canonical}: ${error.message}\n`)
+    }
+    throw error
+  }
+}
+
+const run = (canonical: undefined | string, rest: readonly string[]): Output => {
   switch (canonical) {
     case 'parse':
       return parseCommand(rest)
@@ -1948,6 +2153,6 @@ export const cave = (argv: readonly string[]): Output => {
     case '-h':
       return ok(`${usage}\n`)
     default:
-      return fail(`cave: unknown command ${JSON.stringify(command)}\n\n${usage}\n`, 2)
+      return fail(`cave: unknown command ${JSON.stringify(canonical)}\n\n${usage}\n`, 2)
   }
 }

package/src/commands.ts

@@ -18,7 +18,7 @@ export const commandRegistry = [
   { name: 'highlight', importantOptions: [] },
   { name: 'add', importantOptions: ['--strict', '--check', '--no-prelude', '--no-src'] },
   { name: 'import', importantOptions: ['--strict', '--no-prelude'] },
-  { name: 'query', importantOptions: ['--json', '--limit', '--cursor', '--all', '--aliases', '--as-of', '--at', '--resolve', '--no-prelude'] },
+  { name: 'query', importantOptions: ['--json', '--limit', '--cursor', '--all', '--aliases', '--as-of', '--at', '--resolve', '--sources', '--no-prelude'] },
   { name: 'search', importantOptions: ['--raw', '--limit', '--json', '--no-prelude'] },
   { name: 'resolve', importantOptions: ['--aliases', '--policy', '--json', '--no-prelude'] },
   { name: 'derive', importantOptions: ['--dry-run', '--full', '--aliases', '--min-conf', '--max-passes', '--list', '--retract', '--json', '--no-prelude'] },
@@ -36,7 +36,7 @@ export const commandRegistry = [
   { name: 'mcp', importantOptions: ['--read-only', '--permissions', '--tools', '--hooks', '--no-prelude', '--src', '--no-src'], delegated: true },
   { name: 'ingest', importantOptions: ['--agent', '--stdout', '--lenient', '--plan', '--dry-run', '--json', '--no-prelude'], delegated: true },
   { name: 'eval', importantOptions: ['--agent', '--judge', '--runs', '--stdout', '--min', '--json', '--no-prelude'], delegated: true },
-  { name: 'connect', importantOptions: ['--map', '--key', '--watch', '--prune', '--query', '--dry-run', '--no-prelude'], delegated: true },
+  { name: 'connect', importantOptions: ['--map', '--key', '--watch', '--prune', '--query', '--dry-run', '--list', '--no-prelude'], delegated: true },
   { name: 'reconstruct', importantOptions: ['--query', '--agent', '--steps', '--claims', '--timeout', '--trace', '--no-prelude'] },
   { name: 'doctor', importantOptions: ['--hooks', '--json'] },
   { name: 'demo', importantOptions: [] },

package/src/dispatch.ts

@@ -1,6 +1,6 @@
 /** One promise-based command dispatcher and process lifecycle for every command. */
 
-import { cave, highlightCommand, reconstructCommand, suggestAliasCommand } from './cli.ts'
+import { cave, highlightCommand, querySourcesCommand, reconstructCommand, suggestAliasCommand } from './cli.ts'
 import { delegatedCommandNames } from './commands.ts'
 import type { Output } from './cli.ts'
 
@@ -78,6 +78,12 @@ const execute = async (raw: readonly string[], runtime: CommandRuntime): Promise
       const { runServe } = await import('@cavelang/view')
       return await runServe(rest, context)
     }
+    case 'q':
+    case 'query':
+      if (rest.includes('--sources')) {
+        return await runOutput(runtime, argv, querySourcesCommand)
+      }
+      break
     case 'reconstruct':
       return await runOutput(runtime, argv,
         args => reconstructCommand(args, { ...runtime.signal === undefined ? {} : { signal: runtime.signal } }))

package/src/doctor.ts

@@ -6,7 +6,8 @@ import { dirname, join, parse } from 'node:path'
 import { parseArgs } from 'node:util'
 import { Version } from '@cavelang/core'
 import { directCommand, runProcessSync } from '@cavelang/loop'
-import { Schema, defaultDbPath } from '@cavelang/store'
+import { LocateError, Schema, defaultDbPath, kindOf, openText } from '@cavelang/store'
+import { assemble } from '@cavelang/connect'
 import { nodeSqliteAdapter } from '@cavelang/store/adapter/node'
 import type { SqliteDatabase } from '@cavelang/store/adapter'
 
@@ -32,7 +33,7 @@ export type DoctorReport = {
   readonly configuration: {
     readonly database: {
       readonly source: 'flag' | 'environment' | 'default'
-      readonly kind: 'memory' | 'file'
+      readonly kind: 'memory' | 'file' | 'text'
       readonly exists: boolean
       readonly schemaVersion?: number
       readonly claims?: number
@@ -216,6 +217,31 @@ const inspectDatabase = (path: string, source: DatabaseConfiguration['source']):
         'Run cave add to create it, or pass --db for an existing store.')]
     }
   }
+  if (!memory && kindOf(path) === 'text') {
+    // A CAVE text file is a read-only store assembled in memory (spec
+    // §13.7, §23.4): replay it, sources included, and count what it holds.
+    const configuration: DatabaseConfiguration = { ...base, kind: 'text' }
+    try {
+      const store = openText(path, { assemble })
+      try {
+        const claims = store.currentBeliefs().filter(row => row.conf > 0).length
+        return {
+          configuration: { ...configuration, claims },
+          checks: [check('store.database', 'pass',
+            `CAVE text store assembled in memory (${claims} current claim(s)); text stores are read-only`)]
+        }
+      } finally {
+        store.close()
+      }
+    } catch (error) {
+      return {
+        configuration,
+        checks: [check('store.database', 'fail',
+          `The CAVE text store does not load: ${error instanceof LocateError ? error.message.split('\n')[0] : error instanceof Error ? error.message : String(error)}`,
+          'Fix the file (cave parse) or the source it declares; a text store is read-only.')]
+      }
+    }
+  }
 
   let db: SqliteDatabase | undefined
   let observed = base
@@ -249,7 +275,7 @@ const inspectDatabase = (path: string, source: DatabaseConfiguration['source']):
         configuration,
         checks: [check('store.database', 'warn',
           `Database schema ${version} needs migration to schema ${Schema.currentVersion}`,
-          'Back up the database, then open it with a normal cave command to migrate it.')]
+          'Close every user and copy the database file as a rollback point, then open it with a writing command such as cave add to migrate it; reads never migrate.')]
       }
     }
 

package/src/index.ts

@@ -4,7 +4,7 @@
  * and `runCli` expose the shared awaited command lifecycle.
  */
 
-export { actCommand, addCommand, backupCommand, cave, checkCommand, commandHelp, demoCommand, deriveCommand, exportCommand, generateCommand, helpCommand, highlightCommand, importCommand, parseCommand, queryCommand, reconstructCommand, reportCommand, resolveCommand, restoreCommand, searchCommand, suggestAliasCommand, syncCommand, usage, versionCommand } from './cli.ts'
+export { actCommand, addCommand, backupCommand, cave, checkCommand, commandHelp, demoCommand, deriveCommand, exportCommand, generateCommand, helpCommand, highlightCommand, importCommand, parseCommand, queryCommand, querySourcesCommand, reconstructCommand, reportCommand, resolveCommand, restoreCommand, searchCommand, suggestAliasCommand, syncCommand, usage, versionCommand } from './cli.ts'
 export { dispatch, runCli } from './dispatch.ts'
 export type { CommandRuntime } from './dispatch.ts'
 export { commandRegistry } from './commands.ts'