@cavelang/cli 0.34.0 → 0.36.0

package/dist/src/cli.js

@@ -34,13 +34,17 @@
  * `file` defaults to stdin (`-`); `--db` defaults to `$CAVE_DB`, then
  * `cave.db`. Every command answers `--help` with options and examples.
  */
-import { readFileSync, readSync, statSync, writeFileSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { readFileSync, readSync, realpathSync, statSync } from 'node:fs';
+import { readHooks } from "./hooks-config.js";
+import { basename, dirname, join, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
-import { Version } from '@cavelang/core';
+import { writeOutput } from "./atomic-output.js";
+import { errorMessage } from "./error-message.js";
+import { Time, Version } from '@cavelang/core';
 import { parseDocument, Token } from '@cavelang/parser';
 import { Registry, standardRegistry } from '@cavelang/canonical';
-import { LocateError, Sensitivity, backup as backupStore, defaultDbPath, openAt, restoreBackup, verifyBackup } from '@cavelang/store';
+import { backup as backupStore, defaultDbPath, kindOf, LocateError, openAt, QuerySql, restoreBackup, Sensitivity, verifyBackup } from '@cavelang/store';
+import { Declared, assemble as assembleSources } from '@cavelang/cli/connect';
 import { defaultLimit as defaultQueryLimit, maxLimit as maxQueryLimit, page as caveQueryPage } from '@cavelang/query';
 import { check as caveCheck, defaultMinScore, defaultStaleDays, gatedIngest, judgePrompt, parseJudgeReply, generateClient, suggestAliases, writeSuggestions } from '@cavelang/cli/shape';
 import { declareRules, defaultMaxPasses, defaultMinConf, derive, listRules, retractRule } from '@cavelang/cli/rules';
@@ -218,7 +222,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}
@@ -244,6 +248,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
@@ -263,6 +273,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)
 
@@ -479,7 +490,7 @@ Usage:
 
 Options:
   ${dbHelp}
-  --out <file>   write the generated module instead of stdout
+  --out <file>   atomically replace a file with the generated module
   --version <n>  generated-client format version (default and currently
                  supported: 1)
   --no-prelude   open the store without the standard verb registry
@@ -502,7 +513,7 @@ Usage:
 Options:
   ${dbHelp}
   --min <s>            minimum evidence score, 0..1 or N% (default 60%)
-  --limit <n>          at most n suggestions, strongest first
+  --limit <n>          positive safe integer; 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
@@ -533,6 +544,10 @@ claim, so the opt-in §13.6 closure links it until reviewed:
 claim identity, §9.2, so a plain @ 0% append would start a new series
 and leave the suggested link standing).
 
+Writes recheck pair history under their transaction reservation and skip
+reviewed pairs. --json returns the selected suggestion array; --json --write
+performs the write and returns { suggestions, appended }, with the actual count.
+
 Examples:
   cave suggest-alias --db k.db
   cave suggest-alias --db k.db --min 80% --limit 10
@@ -588,7 +603,7 @@ Usage:
 
 Options:
   ${dbHelp}
-  --out <file>   write to a file instead of stdout — refused when it
+  --out <file>   atomically replace a file instead of stdout — refused when it
                  names the store's own database file
   --current      current beliefs only (skip superseded rows); compacting
                  view, not sanitization or selective erasure (spec §9.6)
@@ -604,6 +619,10 @@ Options:
 Retention: claim history is permanent. Retraction and --current do not
 guarantee erasure from the store, exports, peers, or backups (spec §9.6).
 
+File output is staged and flushed before replacement. Existing permissions
+and valid symlinks are preserved; hard-link aliases retain the previous file.
+Dangling symlinks and non-regular output files are refused.
+
 Examples:
   cave export --db k.db
   cave export --db k.db --out internal-export.cave
@@ -622,7 +641,7 @@ Usage:
 
 Options:
   ${dbHelp}
-  --out <file>   write the rendered markdown to a file instead of stdout
+  --out <file>   atomically replace a file with the rendered markdown
   --aliases      queries match through the alias closure (spec §13.6)
   --resolve      queries match resolved winners only (spec §26) — the fix
                  when an inline splice reports an ambiguous fact
@@ -716,6 +735,15 @@ Examples:
   cave help query
   cave help serve`
 };
+const decodeInput = (bytes, source) => {
+    try {
+        // Keep the existing BOM behavior of Buffer.toString while rejecting loss.
+        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch (cause) {
+        throw new TypeError(`${source}: invalid UTF-8 input`, { cause });
+    }
+};
 const readStdin = () => {
     const chunks = [];
     const buffer = Buffer.allocUnsafe(64 * 1024);
@@ -724,7 +752,7 @@ const readStdin = () => {
         try {
             const size = readSync(0, buffer, 0, buffer.length, null);
             if (size === 0)
-                return Buffer.concat(chunks).toString('utf8');
+                return decodeInput(Buffer.concat(chunks), 'stdin');
             chunks.push(Buffer.from(buffer.subarray(0, size)));
         }
         catch (error) {
@@ -747,11 +775,78 @@ const readStdin = () => {
  */
 const openDb = (values, intent) => 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 } : {}
 });
+/** Retain command output and diagnostics when its owned store fails to close. */
+const closeCommandStore = (store, output) => {
+    try {
+        store.close();
+    }
+    catch (error) {
+        const separator = output.err === '' || output.err.endsWith('\n') ? '' : '\n';
+        return { ...output, code: output.code === 0 ? 1 : output.code,
+            err: `${output.err}${separator}store close failed: ${errorMessage(error)}\n` };
+    }
+    return output;
+};
+const withCommandStore = (store, run) => {
+    let output;
+    try {
+        output = run();
+    }
+    catch (error) {
+        output = fail(`${errorMessage(error)}\n`);
+    }
+    return closeCommandStore(store, output);
+};
+const withAsyncCommandStore = async (store, run) => {
+    let output;
+    try {
+        output = await run();
+    }
+    catch (error) {
+        output = fail(`${errorMessage(error)}\n`);
+    }
+    return closeCommandStore(store, output);
+};
+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 = (store, discovered, body) => {
+    let result;
+    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) => files.length === 0 || (files.length === 1 && files[0] === '-') ?
     readStdin() :
-    files.map(file => readFileSync(file, 'utf8')).join('\n');
+    files.map(file => decodeInput(readFileSync(file), file)).join('\n');
 export const parseCommand = (argv) => {
     const { values, positionals } = parseArgs({
         args: [...argv],
@@ -826,7 +921,7 @@ const ingestCommand = (name) => (argv) => {
     });
     const input = readInput(positionals);
     const store = openDb(values, 'write');
-    try {
+    return withCommandStore(store, () => {
         const options = {
             strict: values.strict === true,
             ...name === 'add' && values['no-src'] !== true ? { source: 'cli' } : {}
@@ -848,13 +943,7 @@ const ingestCommand = (name) => (argv) => {
             out: `added ${outcome.result.ids.length} claim(s), ${outcome.result.edges} edge(s)\n`,
             err: problems === '' ? '' : `${problems}\n`
         };
-    }
-    catch (error) {
-        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
-    }
-    finally {
-        store.close();
-    }
+    });
 };
 export const addCommand = ingestCommand('add');
 /**
@@ -870,39 +959,113 @@ export const addCommand = ingestCommand('add');
  * identity.
  */
 export const importCommand = ingestCommand('import');
-export const queryCommand = (argv) => {
-    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' }
+};
+const parseQuery = (argv) => {
+    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') };
+    }
+    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, runtime = {}) => {
+    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');
+    return await withAsyncCommandStore(store, async () => {
+        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();
+    });
+};
+export const queryCommand = (argv) => {
+    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 pattern = positionals.join('\n');
     const store = openDb(values, 'read');
-    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 }
-        });
+    return withCommandStore(store, () => {
+        return renderQueryPage(store, values, pattern, () => queryPage(store, values, pattern));
+    });
+};
+/** Every match of the overlay: the pages are followed here, inside the transaction that holds it. */
+const wholeQuery = (store, values, pattern) => {
+    const matches = [];
+    let first;
+    let cursor;
+    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, values, pattern) => 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, values, pattern, page) => {
+    {
+        const result = page();
         if (values.json === true) {
             return ok(`${JSON.stringify(result, undefined, 2)}\n`);
         }
@@ -932,12 +1095,6 @@ export const queryCommand = (argv) => {
         });
         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();
-    }
 };
 export const searchFormat = 'cave.search';
 export const searchVersion = 1;
@@ -967,7 +1124,7 @@ export const searchCommand = (argv) => {
         return fail(`cave search: --limit must be an integer from 1 to ${maxQueryLimit}\n`);
     }
     const store = openDb(values, 'read');
-    try {
+    return withCommandStore(store, () => {
         const raw = values.raw === true;
         const found = store.search(query, { raw, limit: limit + 1 });
         const matches = found.slice(0, limit);
@@ -991,13 +1148,7 @@ export const searchCommand = (argv) => {
             lines.push(`more matches beyond ${limit}; raise --limit`);
         }
         return ok(`${lines.join('\n')}\n`);
-    }
-    catch (error) {
-        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
-    }
-    finally {
-        store.close();
-    }
+    });
 };
 /**
  * `cave resolve` — the human view of contradiction resolution (spec §26.4):
@@ -1016,15 +1167,22 @@ export const resolveCommand = (argv) => {
         },
         allowPositionals: false
     });
-    const percent = (value) => `${Math.round(value * 1000) / 10}%`;
+    const percent = (value) => {
+        const rounded = Math.round(value * 1000) / 10;
+        if (value > 0 && rounded === 0)
+            return '<0.1%';
+        if (value < 1 && rounded === 100)
+            return '>99.9%';
+        return `${rounded}%`;
+    };
     const store = openDb(values, 'read');
-    try {
+    return withCommandStore(store, () => {
         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 width = policy.reduce((maximum, entry) => Math.max(maximum, entry.prefix.length + 7), 0);
             const lines = policy.map(entry => {
                 const subject = entry.prefix === '' ? 'source' : `source/${entry.prefix}`;
                 const dimensions = [
@@ -1044,13 +1202,7 @@ export const resolveCommand = (argv) => {
         }
         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({
@@ -1076,15 +1228,15 @@ export const deriveCommand = (argv) => {
         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`);
+    if (maxPasses !== undefined && (!Number.isSafeInteger(maxPasses) || maxPasses < 1)) {
+        return fail(`cave derive: --max-passes expects a positive safe integer, got ${JSON.stringify(values['max-passes'])}\n`);
     }
     // 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 {
+    return withCommandStore(store, () => {
         if (values.list === true) {
             const rules = listRules(store);
             if (values.json === true) {
@@ -1144,13 +1296,16 @@ export const deriveCommand = (argv) => {
             report = derive(store, options);
         }
         if (declaration !== undefined) {
-            err.push(...declaration.problems.map(problem => `rules line ${problem.line}: ${problem.message}`));
+            for (const problem of declaration.problems)
+                err.push(`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)` : ''));
         }
+        const hasProblems = (declaration?.problems.length ?? 0) > 0 || !report.complete ||
+            report.problems.length > 0 || report.rules.some(rule => rule.problems.length > 0);
         if (values.json === true) {
-            return { code: report.problems.length > 0 || !report.complete ? 1 : 0, out: `${stableJson(store, report)}\n`, err: err.join('\n') + (err.length > 0 ? '\n' : '') };
+            return { code: hasProblems ? 1 : 0, out: `${stableJson(store, report)}\n`, err: err.join('\n') + (err.length > 0 ? '\n' : '') };
         }
         for (const problem of report.problems) {
             err.push(`${problem.subject}: ${problem.problems.join('; ')}`);
@@ -1160,33 +1315,16 @@ export const deriveCommand = (argv) => {
                 `${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}`));
+            for (const problem of rule.problems)
+                err.push(`${rule.subject}: ${problem}`);
         }
-        out.push(...report.notes.map(note => `note: ${note}`));
-        out.push(`derived${values['dry-run'] === true ? ' (dry run)' : ''}: ` +
+        for (const note of report.notes)
+            out.push(`note: ${note}`);
+        out.push(`derived${report.complete ? '' : ' (incomplete)'}${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.complete || report.problems.length > 0 || report.rules.some(rule => rule.problems.length > 0);
         return { code: hasProblems ? 1 : 0, out: `${out.join('\n')}\n`, err: err.length === 0 ? '' : `${err.join('\n')}\n` };
-    }
-    catch (error) {
-        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
-    }
-    finally {
-        store.close();
-    }
-};
-/**
- * Loads a hooks configuration file (spec §25.4): a JSON object mapping
- * hook names to shell command templates.
- */
-const readHooks = (path) => {
-    const parsed = JSON.parse(readFileSync(path, 'utf8'));
-    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed) ||
-        Object.values(parsed).some(value => typeof value !== 'string')) {
-        throw new Error(`${path}: hooks must be a JSON object of name → shell template strings`);
-    }
-    return parsed;
+    });
 };
 /** Text rendering of a spec §25.2 execution report. */
 const renderActReport = (report) => {
@@ -1205,17 +1343,16 @@ const renderActReport = (report) => {
     ];
     let code = 0;
     if (report.hook !== undefined) {
-        if (!report.hook.fired) {
-            lines.push(`hook ${report.hook.name}: not fired (${report.hook.note})`);
+        if (report.hook.error !== undefined) {
+            // Effects may already be committed even when hook lookup failed before spawn.
+            lines.push(`hook ${report.hook.name}: ${report.hook.error}`);
+            code = 1;
         }
-        else if (report.hook.error === undefined) {
-            lines.push(`hook ${report.hook.name}: ok`);
+        else if (!report.hook.fired) {
+            lines.push(`hook ${report.hook.name}: not fired (${report.hook.note})`);
         }
         else {
-            // The claims committed before the hook ran (spec §25.4) — the
-            // failure is reported, and the exit code carries it.
-            lines.push(`hook ${report.hook.name}: ${report.hook.error}`);
-            code = 1;
+            lines.push(`hook ${report.hook.name}: ok`);
         }
     }
     return { lines, code };
@@ -1244,7 +1381,7 @@ export const actCommand = (argv) => {
         values.list === true ? 'read' :
             values.retract !== undefined ? 'write' :
                 values['dry-run'] === true ? 'scratch' : 'write');
-    try {
+    return withCommandStore(store, () => {
         if (values.declare === true) {
             const declaration = declareActions(store, readInput(positionals));
             const err = declaration.problems.map(problem => `line ${problem.line}: ${problem.message}`);
@@ -1290,7 +1427,13 @@ export const actCommand = (argv) => {
             if (at <= 0) {
                 return fail(`cave act: expected param=value, got ${JSON.stringify(pair)}\n`);
             }
-            args[pair.slice(0, at)] = pair.slice(at + 1);
+            const parameter = pair.slice(0, at);
+            if (Object.hasOwn(args, parameter)) {
+                return fail(`cave act: duplicate parameter ${JSON.stringify(parameter)}\n`);
+            }
+            Object.defineProperty(args, parameter, {
+                value: pair.slice(at + 1), enumerable: true, writable: true, configurable: true
+            });
         }
         const hooksPath = values.hooks ?? process.env['CAVE_HOOKS'];
         const report = act(store, name, args, {
@@ -1306,13 +1449,7 @@ export const actCommand = (argv) => {
         return report.ok ?
             { code, out: `${lines.join('\n')}\n`, err: '' } :
             { code, out: '', err: `${lines.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) => {
@@ -1321,26 +1458,38 @@ const renderReport = (report, staleDays) => {
     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)}`));
+        for (const violation of report.violations)
+            lines.push(`  ${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)`));
+        for (const { row, ageDays } of report.stale)
+            lines.push(`  ${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}`));
+        for (const row of report.review)
+            lines.push(`  ${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}`));
+            for (const row of disagreement.rows)
+                lines.push(`    ${row.raw_line}`);
         }
     }
+    const confidencePercent = (value) => {
+        const rounded = Math.round(value * 100);
+        if (value > 0 && rounded === 0)
+            return '<1%';
+        if (value < 1 && rounded === 100)
+            return '>99%';
+        return `${rounded}%`;
+    };
     const confidence = coverage.averageConfidence === null ?
         '' :
-        `; avg conf ${Math.round(coverage.averageConfidence * 100)}%, ${coverage.lowConfidence} low (< 0.3)`;
+        `; avg conf ${confidencePercent(coverage.averageConfidence)}, ${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`);
@@ -1362,17 +1511,14 @@ export const checkCommand = (argv) => {
         return fail(`cave check: --stale expects a non-negative number of days, got ${JSON.stringify(values.stale)}\n`);
     }
     const store = openDb(values, 'read');
-    try {
+    return withCommandStore(store, () => {
         const report = caveCheck(store, { staleDays });
         const out = values.json === true ?
             `${stableJson(store, report)}\n` :
             renderReport(report, staleDays);
         // Violations fail the check (spec §20.2); the other sections are advisory.
         return { code: report.violations.length > 0 ? 1 : 0, out, err: '' };
-    }
-    finally {
-        store.close();
-    }
+    });
 };
 const snapshotLine = (action, snapshot) => `${action} exact backup (${snapshot.rows} row(s), schema v${snapshot.schemaVersion}, ` +
     `${snapshot.bytes} bytes, sha256:${snapshot.sha256}) at ${snapshot.path}\n`;
@@ -1410,19 +1556,17 @@ export const backupCommand = (argv) => {
         // 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)) {
+        if (sameStoreFile(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' });
-        try {
-            return ok(snapshotLine('created', backupStore(store, values.out, { force: values.force === true })));
-        }
-        finally {
-            store.close();
-        }
+        const destination = values.out;
+        const store = openAt(dbPath, { intent: 'read', assemble: assembleSources });
+        return withCommandStore(store, () => {
+            return ok(snapshotLine('created', backupStore(store, destination, { force: values.force === true })));
+        });
     }
     catch (error) {
-        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
+        return fail(`${errorMessage(error)}\n`);
     }
 };
 /** `cave restore` — verify and atomically restore an exact snapshot (§13.2.2). */
@@ -1452,7 +1596,7 @@ export const restoreCommand = (argv) => {
         })));
     }
     catch (error) {
-        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
+        return fail(`${errorMessage(error)}\n`);
     }
 };
 /**
@@ -1487,15 +1631,15 @@ export const suggestAliasCommand = async (argv, runtime = {}) => {
             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`);
+        if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 1)) {
+            return fail(`cave suggest-alias: --limit expects a positive safe 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 = openDb(values, values.write === true ? 'write' : 'read');
-        try {
+        return await withAsyncCommandStore(store, async () => {
             let suggestions = suggestAliases(store, { minScore, ...limit === undefined ? {} : { limit } });
             if (values.agent !== undefined && suggestions.length > 0) {
                 const reply = await shellComplete(values.agent, {
@@ -1505,7 +1649,9 @@ export const suggestAliasCommand = async (argv, runtime = {}) => {
                 suggestions = parseJudgeReply(reply, suggestions.length).map(index => suggestions[index]);
             }
             if (values.json === true) {
-                return ok(`${JSON.stringify(suggestions, undefined, 2)}\n`);
+                const result = values.write === true ?
+                    { suggestions, ...writeSuggestions(store, suggestions) } : suggestions;
+                return ok(`${JSON.stringify(result, undefined, 2)}\n`);
             }
             if (suggestions.length === 0) {
                 return ok('no alias suggestions\n');
@@ -1516,13 +1662,10 @@ export const suggestAliasCommand = async (argv, runtime = {}) => {
                 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`);
+        return fail(`${errorMessage(error)}\n`);
     }
 };
 /**
@@ -1551,7 +1694,7 @@ export const syncCommand = (argv) => {
     }
     const dbPath = values.db ?? defaultDbPath();
     const store = openDb(values, values['dry-run'] === true ? 'scratch' : 'write');
-    try {
+    return withCommandStore(store, () => {
         const options = {
             into: values.into === undefined ? labelOf(dbPath) : sanitizeLabel(values.into),
             record: values['no-record'] !== true,
@@ -1565,7 +1708,7 @@ export const syncCommand = (argv) => {
             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');
+            const detail = report.problems.map(problem => `  ${problem.line === 0 ? '' : `line ${problem.line}: `}${problem.message}`).join('\n');
             return fail(`cave sync: ${source}: ${report.problems.length} problem(s), nothing merged\n${detail}\n`);
         }
         const lines = [
@@ -1577,18 +1720,13 @@ export const syncCommand = (argv) => {
             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();
-    }
+    });
 };
 /**
  * `cave report` — the §31 deliverable: a markdown template's cave-q
- * blocks and inline splices render from the store, every stated fact
- * cited back to its claim. Problems mark the text, land on stderr with
+ * blocks and inline splices render from the store, with matched rows
+ * cited back to their claims. Ordinary prose is not automatically checked
+ * or cited. Problems mark the text, land on stderr with
  * template line numbers, and fail the exit code — the render never
  * silently drops a fact.
  */
@@ -1607,16 +1745,22 @@ export const reportCommand = (argv) => {
         },
         allowPositionals: true
     });
-    const template = readInput(positionals);
+    if (values.at !== undefined && Time.parseInstant(values.at) === undefined) {
+        return fail(`cave report: --at cannot parse at anchor ${JSON.stringify(values.at)}\n`);
+    }
+    if (values['as-of'] !== undefined && QuerySql.asOfBoundary(values['as-of']) === undefined) {
+        return fail(`cave report: --as-of cannot parse as-of boundary ${JSON.stringify(values['as-of'])}\n`);
+    }
     const maximum = Sensitivity.parse(values['max-sensitivity'] ?? Sensitivity.defaultMaximum);
     if (maximum === undefined) {
         return fail(`cave report: --max-sensitivity expects ${Sensitivity.levels.join(', ')}, got ${JSON.stringify(values['max-sensitivity'])}\n`);
     }
-    if (values.out !== undefined && sameFile(values.db ?? defaultDbPath(), values.out)) {
+    if (values.out !== undefined && sameStoreFile(values.db ?? defaultDbPath(), values.out)) {
         return fail(`cave report: --out '${values.out}' is the source database — refusing to overwrite it\n`);
     }
+    const template = readInput(positionals);
     const store = openDb(values, 'read');
-    try {
+    return withCommandStore(store, () => {
         const rendered = caveReport(store, template, {
             aliases: values.aliases === true,
             resolve: values.resolve === true,
@@ -1631,19 +1775,13 @@ export const reportCommand = (argv) => {
         if (values.out === undefined) {
             return { code, out: rendered.markdown, err: err === '' ? '' : `${err}\n` };
         }
-        writeFileSync(values.out, rendered.markdown);
+        writeOutput(values.out, rendered.markdown);
         return {
             code,
             out: `rendered ${rendered.citations} citation(s) to ${values.out}\n`,
             err: err === '' ? '' : `${err}\n`
         };
-    }
-    catch (error) {
-        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
-    }
-    finally {
-        store.close();
-    }
+    });
 };
 /**
  * True when both paths name the same file: equal once resolved, or — when
@@ -1663,6 +1801,21 @@ const sameFile = (a, b) => {
         return false;
     }
 };
+/** Protect every physical file SQLite uses, including through a database symlink. */
+const sameStoreFile = (db, output) => {
+    if (sameFile(db, output))
+        return true;
+    try {
+        if (kindOf(db) !== 'sqlite')
+            return false;
+        const canonicalOutput = join(realpathSync(dirname(resolve(output))), basename(output));
+        return [...new Set([db, realpathSync(db)])].some(base => ['-wal', '-shm', '-journal'].some(suffix => sameFile(`${base}${suffix}`, output) || sameFile(`${base}${suffix}`, canonicalOutput)));
+    }
+    catch {
+        // The normal store-open path reports missing or unreadable source files.
+        return false;
+    }
+};
 export const exportCommand = (argv) => {
     const { values } = parseArgs({
         args: [...argv],
@@ -1681,28 +1834,22 @@ export const exportCommand = (argv) => {
     if (maximum === undefined) {
         return fail(`cave export: --max-sensitivity expects ${Sensitivity.levels.join(', ')}, got ${JSON.stringify(values['max-sensitivity'])}\n`);
     }
-    if (values.out !== undefined && sameFile(db, values.out)) {
+    if (values.out !== undefined && sameStoreFile(db, values.out)) {
         return fail(`cave export: --out '${values.out}' is the source database — refusing to overwrite it\n`);
     }
     const store = openDb(values, 'read');
-    try {
+    return withCommandStore(store, () => {
         const text = store.exportText({ current: values.current === true, tx: values.tx === true, maxSensitivity: maximum });
         if (values.out === undefined) {
             return ok(text);
         }
-        writeFileSync(values.out, text);
+        writeOutput(values.out, text);
         // Root claims only: shorthand prefixes and §28.4 annotations are not
         // claims, while qualifier/grouping leaves have a materialized parent.
         const claims = parseDocument(text).lines
             .filter(line => line.kind === 'claim' && line.parent === undefined).length;
         return ok(`exported ${claims} claim(s) to ${values.out}\n`);
-    }
-    catch (error) {
-        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
-    }
-    finally {
-        store.close();
-    }
+    });
 };
 /** `cave generate` — spec §20.4's versioned TypeScript client artifact. */
 export const generateCommand = (argv) => {
@@ -1721,11 +1868,11 @@ export const generateCommand = (argv) => {
         return fail(`cave generate: --version expects a positive integer, got ${JSON.stringify(values.version)}\n`);
     }
     const db = values.db ?? defaultDbPath();
-    if (values.out !== undefined && sameFile(db, values.out)) {
+    if (values.out !== undefined && sameStoreFile(db, values.out)) {
         return fail(`cave generate: --out '${values.out}' is the source database — refusing to overwrite it\n`);
     }
     const store = openDb(values, 'read');
-    try {
+    return withCommandStore(store, () => {
         const generated = generateClient(store, version === undefined ? {} : { version });
         if (!generated.ok) {
             return fail(`cave generate: schema cannot be generated:\n${generated.problems.map(problem => `  ${problem}`).join('\n')}\n`);
@@ -1733,16 +1880,10 @@ export const generateCommand = (argv) => {
         if (values.out === undefined) {
             return ok(generated.code);
         }
-        writeFileSync(values.out, generated.code);
+        writeOutput(values.out, generated.code);
         return ok(`generated typed client v${generated.version} (${generated.fields.length} field(s), ` +
             `sha256:${generated.digest}) to ${values.out}\n`);
-    }
-    catch (error) {
-        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
-    }
-    finally {
-        store.close();
-    }
+    });
 };
 /**
  * `cave reconstruct` — the §18 loop over the store: heuristic policy by
@@ -1788,7 +1929,7 @@ export const reconstructCommand = async (argv, runtime = {}) => {
             return fail(`cave reconstruct: --timeout must be a positive number of seconds, got '${values.timeout}'\n`);
         }
         const store = openDb(values, 'read');
-        try {
+        return await withAsyncCommandStore(store, async () => {
             const graph = sqliteStore(store);
             const result = values.agent === undefined ?
                 reconstruct(graph, heuristicPolicy(budgets), positionals) :
@@ -1805,13 +1946,10 @@ export const reconstructCommand = async (argv, runtime = {}) => {
                 ...result.claims.map(claim => emitClaim(claim))
             ];
             return ok(lines.length === 0 ? '' : `${lines.join('\n')}\n`);
-        }
-        finally {
-            store.close();
-        }
+        });
     }
     catch (error) {
-        return fail(`${error instanceof Error ? error.message : String(error)}\n`);
+        return fail(`${errorMessage(error)}\n`);
     }
 };
 /**