@cavelang/cli 0.34.0 → 0.36.0

package/dist/internal/connect/main.js

@@ -2,39 +2,65 @@
  * `cave connect` entry — argument parsing, pass orchestration (single,
  * `--watch`, `--query`), and report rendering around `run.ts`.
  */
-import { readFileSync, watch as watchFs } from 'node:fs';
+import { rethrowFetchFailure } from "./fetch-failure.js";
+import { errorMessage } from "./error-message.js";
+import { existsSync, watch as watchFs } from 'node:fs';
+import { readText } from "./utf8.js";
 import { basename, dirname, resolve } from 'node:path';
 import { parseArgs } from 'node:util';
 import { Registry } from '@cavelang/canonical';
-import { defaultDbPath, kindOf, open, openAt } from '@cavelang/store';
-import { Record as QueryRecord } from '@cavelang/query';
+import { LocateError, defaultDbPath, kindOf, open, openAt } from '@cavelang/store';
+import { Record as QueryRecord, query as caveQuery } from '@cavelang/query';
+import * as Declared from "./declared.js";
 import * as Source from "./source.js";
 import * as Template from "./template.js";
-import { connect, federatedQuery } from "./run.js";
+import { connect } from "./run.js";
+import { withFederatedSource } from "./federation.js";
 const usage = `cave connect — deterministic structured ingestion through a mapping template (spec §23)
 
 Usage:
   cave connect [--db <path>] <source> --map <file> [options]
+  cave connect [--db <path>] [--name <n>] [--force] [--prune] [--dry-run] [--watch]
+  cave connect [--db <path>] --list
+  cave connect [--db <path>] --query '<pattern>'
 
 The source is a .csv/.tsv/.json/.jsonl/.ndjson file, a SQLite database
-(with --table or --sql), or an http(s) URL serving JSON or CSV. The
+(with --table or --sql), or an http(s) URL serving JSON, JSONL, CSV or TSV. The
 mapping is an ordinary CAVE document whose ?field variables stand for
 record fields; variable-free blocks append once per run, variable blocks
 instantiate once per record — no LLM in the loop, same input, same claims.
+A short mapping can be written inline, and --sql reshapes any tabular
+source through SQLite before the mapping sees it.
 Mapped claims retain the physical source; CSV/TSV and JSONL records also carry
 their exact one-based inclusive line span (spec §9.8).
 
+Without a source, the store's declared sources run (spec §23.4): every
+source/<name> entity whose current claims name a path, with the other
+options as attributes — HAS map:, key:, format:, delimiter:, table:, sql:,
+records:. A .cave path needs no map (the file is its own template). Paths
+resolve against the store's directory. Declared sources stamp
+@src:<name>/<key> and keep digests under source/<name>/<key>, so the
+source/<name> entity also carries the §26.3 policy for what it yields. A
+CAVE text file used as --db follows its declared sources on every open.
+
 Options:
   --db <path>          knowledge database (default: $CAVE_DB, or cave.db)
-  --map <file>         mapping template (required)
+  --map <file|inline>  mapping template (required): a file, or the template
+                       itself — a comma-separated list of claim lines,
+                       '?name IS person, ?name WORKS-AT ?company'
   --name <name>        source name for record identity (default: file basename)
   --key <field>        record key field — keyed records diff against their
                        previous claims on change; unkeyed records are
                        content-addressed
   --format <fmt>       csv | tsv | json | jsonl | sqlite (default: by extension)
   --delimiter <char>   CSV field delimiter (default , — tab for .tsv)
-  --table <name>       SQLite table to read (SELECT *)
-  --sql <query>        SQLite query (alternative to --table)
+  --table <name>       SQLite table to read (SELECT *); for other formats
+                       the temporary table --sql runs against (records)
+  --sql <query>        SQLite query (alternative to --table); for csv, tsv,
+                       json and jsonl the records load into a temporary
+                       in-memory table, values as parsed (CSV cells are
+                       text: cast for arithmetic), and the query's rows are
+                       the records
   --records <path>     dot path to the record array inside a JSON document
   --force              re-map records whose digest is unchanged
   --prune              retract claims of records that disappeared from the source
@@ -42,19 +68,40 @@ Options:
   --watch              keep running; re-map when the source or mapping changes
   --query <pattern>    federation-lite (spec §23.3): map, query the union,
                        roll back — nothing persists; uses an in-memory store
-                       when the database file does not exist
+                       when the database file does not exist; without a
+                       source, overlays every declared source
+  --list               print the declared sources as cave connect invocations
+  --name <name>        without a source: run only this declared source
   --json               with --query: emit matches as JSON
   --all                with --query: match all beliefs, not just current ones
   --aliases            with --query: resolve entities through ALIAS claims
   --no-prelude         open the store without the standard §5.5 registry
 
 Examples:
+  cave connect --db k.db --list
+  cave connect --db k.db
+  cave connect --db k.db --watch
+  cave query --db notes.cave '?who WORKS-AT acme'     # a text store follows its sources
   cave connect people.csv --map people.map.cave --db k.db --key id
   cave connect crm.sqlite --table contacts --map contacts.map.cave --key email
   cave connect https://api.example.com/deps.json --records data.items --map deps.map.cave
   cave connect events.jsonl --map events.map.cave --watch
   cave connect people.csv --map people.map.cave --query '?who WORKS-AT acme'`;
-const waitForAbort = (signal) => signal?.aborted === true ? Promise.resolve() : new Promise(resolve => signal?.addEventListener('abort', () => resolve(), { once: true }));
+/** Abort and fatal callbacks share one owned completion boundary. */
+const watchEnd = (signal) => {
+    let failure;
+    let wake;
+    const done = new Promise(resolve => { wake = resolve; });
+    signal?.addEventListener('abort', wake, { once: true });
+    if (signal?.aborted)
+        wake();
+    return {
+        fail(error) { failure ??= { error }; wake(); },
+        async wait() { await done; if (failure !== undefined)
+            throw failure.error; },
+        close() { signal?.removeEventListener('abort', wake); }
+    };
+};
 const renderReport = (report) => {
     const lines = [
         `connect: ${report.records} record(s): ${report.mapped} mapped, ${report.skipped} skipped (unchanged)` +
@@ -69,25 +116,35 @@ const renderReport = (report) => {
     }
     for (const failure of report.failures) {
         lines.push(`  ${failure.record}: FAILED`);
-        lines.push(...failure.problems.map(problem => `    ${problem}`));
+        for (const problem of failure.problems)
+            lines.push(`    ${problem}`);
     }
     return lines.join('\n');
 };
-const loadMapping = (path) => Template.parse(readFileSync(path, 'utf8'));
+/** `--map` is a template file, or the template itself written inline (spec §23.1). */
+const loadMapping = (spec) => Template.isInline(spec) && !existsSync(spec) ?
+    Template.parse(Template.inlineDocument(spec)) :
+    Template.parse(readText(spec));
 const sourceOptions = (values, context) => ({
     ...values.format === undefined ? {} : { format: values.format },
     ...values.delimiter === undefined ? {} : { delimiter: values.delimiter },
     ...values.table === undefined ? {} : { table: values.table },
     ...values.sql === undefined ? {} : { sql: values.sql },
     ...values.records === undefined ? {} : { records: values.records },
+    ...context.signal === undefined ? {} : { signal: context.signal },
     ...context.fetchImpl === undefined ? {} : { fetchImpl: context.fetchImpl }
 });
 const loadSource = async (source, values, context) => {
     try {
-        return await Source.load(source, sourceOptions(values, context));
+        context.signal?.throwIfAborted();
+        const loaded = await Source.load(source, sourceOptions(values, context));
+        context.signal?.throwIfAborted();
+        return loaded;
     }
     catch (error) {
-        throw new Error(`load ${source}: ${error instanceof Error ? error.message : String(error)}`);
+        if (context.signal?.aborted)
+            rethrowFetchFailure(context.signal, error);
+        throw new Error(`load ${source}: ${errorMessage(error)}`, { cause: error });
     }
 };
 const runPass = async (store, source, values, name, io, context) => {
@@ -135,6 +192,25 @@ const runDry = async (source, values, io, context) => {
     io.stdout.write(`${sections.join('\n\n')}\n`);
     return failures > 0 ? 1 : 0;
 };
+/** Own the command store until its work settles, preserving cleanup failures. */
+const withCommandStore = async (store, run) => {
+    let result;
+    try {
+        result = await run();
+    }
+    catch (error) {
+        try {
+            store.close();
+        }
+        catch (closeError) {
+            const messages = [error, closeError].map(errorMessage);
+            throw new AggregateError([error, closeError], `command failed: ${messages[0]}; store close also failed: ${messages[1]}`, { cause: error });
+        }
+        throw error;
+    }
+    store.close();
+    return result;
+};
 const runQuery = async (source, values, name, io, context) => {
     const { mapping, problems } = loadMapping(values.map);
     if (mapping === undefined) {
@@ -145,14 +221,17 @@ const runQuery = async (source, values, name, io, context) => {
     const db = values.db ?? defaultDbPath();
     const registry = values['no-prelude'] === true ? { registry: Registry.empty } : {};
     // Federation over a store that does not exist yet queries the source alone.
-    const store = kindOf(db) === 'missing' ? open(':memory:', registry) : openAt(db, { intent: 'scratch', ...registry });
-    try {
-        const { matches, report } = federatedQuery(store, mapping, loaded.records, {
+    const store = kindOf(db) === 'missing' ? open(':memory:', registry) : openAt(db, { intent: 'scratch', assemble: Declared.assemble, ...registry });
+    return await withCommandStore(store, () => {
+        const { result: { matches, records }, report } = withFederatedSource(store, mapping, loaded.records, {
             name,
             source,
             ...loaded.spans === undefined ? {} : { spans: loaded.spans },
             ...values.key === undefined ? {} : { key: values.key }
-        }, values.query, { all: values.all === true, aliases: values.aliases === true });
+        }, () => {
+            const matches = caveQuery(store, values.query, { all: values.all === true, aliases: values.aliases === true });
+            return { matches, records: values.json === true ? matches.map(match => QueryRecord.of(store, match)) : undefined };
+        });
         // A failed record means the union was incomplete — matches still print
         // as partial results, but the exit code must not read as success.
         const code = report.failures.length > 0 ? 1 : 0;
@@ -160,7 +239,7 @@ const runQuery = async (source, values, name, io, context) => {
             io.stderr.write(`${renderReport(report)}\n`);
         }
         if (values.json === true) {
-            io.stdout.write(`${JSON.stringify(matches.map(match => QueryRecord.of(store, match)), undefined, 2)}\n`);
+            io.stdout.write(`${JSON.stringify(records, undefined, 2)}\n`);
             return code;
         }
         if (matches.length === 0) {
@@ -175,18 +254,55 @@ const runQuery = async (source, values, name, io, context) => {
         });
         io.stdout.write(`${lines.join('\n')}\n`);
         return code;
+    });
+};
+/** Finish every owned watch resource before returning or propagating failures. */
+const watchSession = async (run, stop, watchers, active) => {
+    const errors = [];
+    let result;
+    try {
+        result = await run();
+    }
+    catch (error) {
+        errors.push(error);
+    }
+    try {
+        stop();
+    }
+    catch (error) {
+        errors.push(error);
+    }
+    for (const watcher of watchers()) {
+        try {
+            watcher.close();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+    }
+    try {
+        await active();
     }
-    finally {
-        store.close();
+    catch (error) {
+        errors.push(error);
+    }
+    if (errors.length === 1)
+        throw errors[0];
+    if (errors.length > 1) {
+        throw new AggregateError(errors, `watch session failed: ${errors.map(errorMessage).join('; ')}`, { cause: errors[0] });
     }
+    return result;
 };
 const runWatch = async (store, source, values, name, io, context) => {
+    let stopped = false;
+    const end = watchEnd(io.signal);
+    const fail = (error) => { stopped = true; end.fail(error); };
     const passOnce = async () => {
         try {
             await runPass(store, source, values, name, io, context);
         }
         catch (error) {
-            io.stderr.write(`cave connect watch pass: ${error instanceof Error ? error.message : String(error)}\n`);
+            io.stderr.write(`cave connect watch pass: ${errorMessage(error)}\n`);
         }
     };
     let running = false;
@@ -199,63 +315,458 @@ const runWatch = async (store, source, values, name, io, context) => {
             return;
         }
         running = true;
-        do {
-            queued = false;
-            await passOnce();
-        } while (queued);
-        running = false;
+        try {
+            do {
+                queued = false;
+                await passOnce();
+            } while (queued && !stopped && !io.signal?.aborted);
+        }
+        finally {
+            running = false;
+        }
     };
     const schedule = context.schedule ?? ((callback, delayMs) => setTimeout(() => { void callback(); }, delayMs));
     const cancelScheduled = context.cancelScheduled ?? (handle => clearTimeout(handle));
     const trigger = () => {
+        if (stopped || io.signal?.aborted)
+            return;
         if (running) {
             queued = true;
             return;
         }
-        if (timer !== undefined)
-            cancelScheduled(timer);
-        timer = schedule(async () => {
-            timer = undefined;
-            const pass = fire();
-            active = pass;
-            await pass;
-            if (active === pass)
-                active = undefined;
-        }, 200);
+        try {
+            if (timer !== undefined)
+                cancelScheduled(timer);
+            timer = schedule(async () => {
+                timer = undefined;
+                if (stopped)
+                    return;
+                const pass = fire();
+                active = pass;
+                try {
+                    await pass;
+                }
+                catch (error) {
+                    fail(error);
+                }
+                if (active === pass)
+                    active = undefined;
+            }, 200);
+        }
+        catch (error) {
+            fail(error);
+        }
     };
     // Watch the parent directories — editors replace files on save, and a
     // watcher on the file itself dies with the old inode.
-    const targets = [...new Set([resolve(source), resolve(values.map)])];
+    const targets = [...new Set([resolve(source), ...Template.isInline(values.map) && !existsSync(values.map) ? [] : [resolve(values.map)]])];
     const watch = context.watch ?? ((path, listener) => watchFs(path, listener));
-    const watchers = targets.map(target => watch(dirname(target), (_event, filename) => {
-        // Some platforms and watcher backends cannot identify the changed
-        // directory entry. A filename-less event is therefore a rescan signal,
-        // while Buffer filenames retain the same exact target filtering.
-        if (filename === null || filename.toString() === basename(target)) {
-            trigger();
-        }
-    }));
-    try {
+    const watchers = [];
+    return watchSession(async () => {
+        for (const target of targets) {
+            const subscription = watch(dirname(target), (_event, filename) => {
+                // Filename-less events rescan; editors may replace the watched file.
+                if (filename === null || filename.toString() === basename(target))
+                    trigger();
+            });
+            watchers.push(subscription);
+            subscription.on?.('error', error => { if (!stopped)
+                fail(error); });
+        }
         // Install watchers before the initial pass. A save during startup is
         // therefore either read by this pass or queued for the next one.
-        await passOnce();
+        await fire();
+        if (stopped || io.signal?.aborted) {
+            await end.wait();
+            return 0;
+        }
         io.stdout.write('watching (ctrl-c to stop)\n');
-        await waitForAbort(io.signal);
+        await end.wait();
         return 0;
+    }, () => {
+        stopped = true;
+        end.close();
+        if (timer !== undefined)
+            cancelScheduled(timer);
+    }, () => watchers, () => active);
+};
+const printMatches = (matches, pattern, io, records) => {
+    if (records !== undefined) {
+        io.stdout.write(`${JSON.stringify(records, undefined, 2)}\n`);
+        return;
+    }
+    if (matches.length === 0) {
+        io.stdout.write('no matches\n');
+        return;
+    }
+    const lines = matches.map(match => {
+        const bindings = Object.entries(match.bindings)
+            .map(([variable, value]) => `?${variable} = ${value}`)
+            .join('  ');
+        return bindings !== '' ? bindings : match.row?.raw_line ?? pattern;
+    });
+    io.stdout.write(`${lines.join('\n')}\n`);
+};
+const registryOf = (values) => values['no-prelude'] === true ? { registry: Registry.empty } : {};
+/** The declared sources of the store, or the one `--name` selects. */
+const selectDeclared = (store, values) => {
+    const declared = Declared.declaredSources(store);
+    if (values.name === undefined) {
+        return declared;
+    }
+    const selected = declared.filter(source => source.name === values.name);
+    if (selected.length === 0) {
+        throw new Error(`no declared source/${values.name}` +
+            (declared.length === 0 ? ' — the store declares no sources' : ` — declared: ${declared.map(source => source.name).join(', ')}`));
+    }
+    return selected;
+};
+const declaredPass = async (store, root, values, io, context) => {
+    const dir = Declared.directoryOf(root);
+    let failed = 0;
+    const done = new Map();
+    // `--name` selects one declaration and what it declares in turn. The
+    // declarations are re-read after every source: a followed .cave source
+    // may declare new sources or re-declare existing ones, and the current
+    // declaration is what runs, until nothing changes — as `assemble` does.
+    // The selection starts as the named source and everything it already
+    // owns, so a parent that fails to load does not hide its descendants.
+    const allowed = values.name === undefined ? undefined :
+        new Set(Declared.closure(store, selectDeclared(store, values).map(declared => declared.name)).map(declared => declared.name));
+    const version = Declared.versionCounter();
+    for (;;) {
+        io.signal?.throwIfAborted();
+        const next = Declared.declaredSources(store)
+            .find(declared => (allowed === undefined || allowed.has(declared.name)) && done.get(declared.name) !== Declared.signature(declared));
+        if (next === undefined) {
+            return failed > 0 ? 1 : 0;
+        }
+        version(next.name);
+        done.set(next.name, Declared.signature(next));
+        try {
+            const ready = await Declared.prepare(next, dir, context.fetchImpl, io.signal);
+            io.signal?.throwIfAborted();
+            const before = Declared.signatures(Declared.declaredSources(store));
+            const report = Declared.run(store, ready, { force: values.force === true, prune: values.prune === true });
+            if (allowed !== undefined) {
+                // The selection grows by whatever this source changed — added,
+                // re-declared, or retracted declarations alike — and by what it
+                // still owns, so an unchanged source keeps its descendants.
+                for (const name of Declared.changedNames(before, Declared.signatures(Declared.declaredSources(store))))
+                    allowed.add(name);
+                for (const name of Declared.ownedDeclarations(store, next.name))
+                    allowed.add(name);
+            }
+            io.stdout.write(`source/${next.name}: ${renderReport(report).replace(/^connect: /, '')}\n`);
+            if (report.failures.length > 0)
+                failed += 1;
+        }
+        catch (error) {
+            io.signal?.throwIfAborted();
+            io.stderr.write(`source/${next.name} (${next.path}): ${errorMessage(error)}\n`);
+            failed += 1;
+        }
+    }
+};
+const discoverOptions = (values, context, force = values.force === true) => ({
+    ...values.name === undefined ? {} : { only: values.name },
+    ...context.fetchImpl === undefined ? {} : { fetchImpl: context.fetchImpl },
+    ...context.signal === undefined ? {} : { signal: context.signal },
+    force,
+    prune: values.prune === true
+});
+/** Previews every declared source, nested declarations included, without touching the store. */
+const declaredDry = async (store, root, values, io, context) => {
+    const sections = [];
+    let failures = 0;
+    const sequence = await Declared.discover(store, root, discoverOptions(values, context));
+    io.signal?.throwIfAborted();
+    for (const ready of sequence) {
+        sections.push(`; === source/${ready.declared.name} (${ready.declared.path})`);
+        if (ready.mapping.prelude !== '') {
+            sections.push(`; --- prelude\n\n${ready.mapping.prelude.trimEnd()}`);
+        }
+        ready.records.forEach((record, at) => {
+            const instantiation = Template.instantiate(ready.mapping.templates, name => Template.fieldOf(record, name));
+            if (instantiation.problems.length > 0) {
+                failures += 1;
+                sections.push([`; --- record ${at + 1}`, ...instantiation.problems.map(problem => `; FAILED — ${problem}`)].join('\n'));
+                return;
+            }
+            sections.push(`; --- record ${at + 1}\n\n${instantiation.text.trimEnd()}`);
+        });
+    }
+    io.stdout.write(`${sections.join('\n\n')}\n`);
+    return failures > 0 ? 1 : 0;
+};
+const rollback = Symbol('cave-connect declared query rollback');
+/**
+ * Federation-lite over every declared source (spec §23.3, §23.4): the
+ * sources load first, URLs included, then append inside one transaction
+ * that rolls back after the query.
+ */
+const stale = Symbol('cave-connect declared query stale');
+const declaredQuery = async (store, root, values, io, context) => {
+    // The overlay applies every source (force), so discovery simulates that.
+    // The sequence was discovered on a snapshot; a writer may have changed
+    // the declarations since, so the replay checks and rediscovers if so.
+    for (let attempt = 0; attempt < Declared.overlayAttempts; attempt += 1) {
+        const { sequence, baseline } = await Declared.discovery(store, root, discoverOptions(values, context, true));
+        io.signal?.throwIfAborted();
+        let matches;
+        let records;
+        let failed = 0;
+        try {
+            store.transaction(() => {
+                if (!Declared.sameDeclarations(baseline, Declared.declarationState(store))) {
+                    throw stale;
+                }
+                for (const source of sequence) {
+                    const report = Declared.run(store, source, { force: true, prune: values.prune === true });
+                    if (report.failures.length > 0) {
+                        failed += 1;
+                        io.stderr.write(`source/${source.declared.name}: ${renderReport(report).replace(/^connect: /, '')}\n`);
+                    }
+                }
+                matches = caveQuery(store, values.query, { all: values.all === true, aliases: values.aliases === true });
+                if (values.json === true)
+                    records = matches.map(match => QueryRecord.of(store, match));
+                throw rollback;
+            });
+        }
+        catch (error) {
+            if (error === stale) {
+                continue;
+            }
+            if (error !== rollback) {
+                throw error;
+            }
+        }
+        printMatches(matches, values.query, io, records);
+        return failed > 0 ? 1 : 0;
     }
-    finally {
+    throw Declared.staleOverlay();
+};
+const declaredWatch = async (store, root, values, io, context) => {
+    let stopped = false;
+    const end = watchEnd(io.signal);
+    const fail = (error) => { stopped = true; end.fail(error); };
+    const dir = Declared.directoryOf(root);
+    const passOnce = async () => {
+        try {
+            await declaredPass(store, root, values, io, context);
+        }
+        catch (error) {
+            io.stderr.write(`cave connect watch pass: ${errorMessage(error)}\n`);
+        }
+        try {
+            if (!stopped && !io.signal?.aborted)
+                refreshWatchers();
+        }
+        catch (error) {
+            // Keep current subscriptions available to retry on the next save.
+            io.stderr.write(`cave connect watch subscriptions: ${errorMessage(error)}\n`);
+        }
+    };
+    let running = false;
+    let queued = false;
+    let timer;
+    let active;
+    const fire = async () => {
+        if (running) {
+            queued = true;
+            return;
+        }
+        running = true;
+        try {
+            do {
+                queued = false;
+                await passOnce();
+            } while (queued && !stopped && !io.signal?.aborted);
+        }
+        finally {
+            running = false;
+        }
+    };
+    const schedule = context.schedule ?? ((callback, delayMs) => setTimeout(() => { void callback(); }, delayMs));
+    const cancelScheduled = context.cancelScheduled ?? (handle => clearTimeout(handle));
+    const trigger = () => {
+        if (stopped || io.signal?.aborted)
+            return;
+        if (running) {
+            queued = true;
+            return;
+        }
+        try {
+            if (timer !== undefined)
+                cancelScheduled(timer);
+            timer = schedule(async () => {
+                timer = undefined;
+                if (stopped)
+                    return;
+                // Retained so shutdown waits for a pass in flight (a URL fetch, say)
+                // instead of closing the store under it.
+                const pass = fire();
+                active = pass;
+                try {
+                    await pass;
+                }
+                catch (error) {
+                    fail(error);
+                }
+                if (active === pass)
+                    active = undefined;
+            }, 200);
+        }
+        catch (error) {
+            fail(error);
+        }
+    };
+    // Every local declared file and mapping; URL sources only run on file
+    // changes. A followed .cave source may declare more, so the set is
+    // refreshed after every pass.
+    const watch = context.watch ?? ((path, listener) => watchFs(path, listener));
+    const watched = new Map();
+    const refreshWatchers = () => {
+        let declared;
+        try {
+            // A named watch watches the selection and everything it owns.
+            declared = values.name === undefined ?
+                selectDeclared(store, values) :
+                Declared.closure(store, selectDeclared(store, values).map(source => source.name));
+        }
+        catch {
+            return;
+        }
+        const targets = new Set(declared.flatMap(source => [
+            ...Source.isUrl(source.path) ? [] : [Declared.resolvePath(source.path, dir)],
+            // A map is a file when it resolves to one, as the loader decides; only
+            // otherwise is it inline and nothing to watch.
+            ...source.map === undefined || (Template.isInline(source.map) && !existsSync(Declared.resolvePath(source.map, dir))) ?
+                [] : [Declared.resolvePath(source.map, dir)]
+        ]));
+        for (const target of targets) {
+            if (watched.has(target))
+                continue;
+            let active = true;
+            const subscription = watch(dirname(target), (_event, filename) => {
+                if (!active)
+                    return;
+                if (filename === null || filename.toString() === basename(target)) {
+                    trigger();
+                }
+            });
+            watched.set(target, { close: () => { active = false; subscription.close(); } });
+            subscription.on?.('error', error => { if (active && !stopped)
+                fail(error); });
+        }
+        const errors = [];
+        for (const [target, subscription] of watched) {
+            if (targets.has(target))
+                continue;
+            // Retire ownership before closing: a failed close must not suppress a
+            // fresh subscription if this path is declared again on a later pass.
+            watched.delete(target);
+            try {
+                subscription.close();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1) {
+            throw new AggregateError(errors, `retiring watch subscriptions failed: ${errors.map(errorMessage).join('; ')}`, { cause: errors[0] });
+        }
+    };
+    return watchSession(async () => {
+        refreshWatchers();
+        if (watched.size === 0) {
+            io.stderr.write('cave connect: nothing to watch — no declared local source\n');
+            return 1;
+        }
+        await fire();
+        if (stopped || io.signal?.aborted) {
+            await end.wait();
+            return 0;
+        }
+        io.stdout.write('watching (ctrl-c to stop)\n');
+        await end.wait();
+        return 0;
+    }, () => {
+        stopped = true;
+        end.close();
         if (timer !== undefined)
             cancelScheduled(timer);
-        watchers.forEach(watcher => watcher.close());
-        await active;
+    }, () => watched.values(), () => active);
+};
+/**
+ * `cave connect` without a source (spec §23.4): the store's declared
+ * sources. `--list` prints them, `--dry-run` previews, `--query` overlays
+ * them in a rolled-back transaction, `--watch` re-runs on file changes,
+ * and the plain form runs one pass over each.
+ */
+const runDeclared = async (values, io, context) => {
+    const perSource = ['map', 'key', 'format', 'delimiter', 'table', 'sql', 'records']
+        .filter(option => values[option] !== undefined);
+    if (perSource.length > 0) {
+        io.stderr.write(`cave connect: ${perSource.map(option => `--${option}`).join(', ')} describe a source argument — ` +
+            'without one, declare them on the source/<name> entity (spec §23.4)\n');
+        return 1;
+    }
+    const db = values.db ?? defaultDbPath();
+    try {
+        if (values.list === true) {
+            const store = openAt(db, { intent: 'read', assemble: Declared.assemble, ...registryOf(values) });
+            return await withCommandStore(store, () => {
+                const declared = selectDeclared(store, values);
+                io.stdout.write(declared.length === 0 ? 'no declared sources\n' : `${declared.map(Declared.describe).join('\n')}\n`);
+                return 0;
+            });
+        }
+        if (values['dry-run'] === true || values.query !== undefined) {
+            // Discovery works on a private snapshot, so the dry run only reads;
+            // the overlay appends into the store's own rolled-back transaction.
+            const store = openAt(db, { intent: values.query === undefined ? 'read' : 'scratch', assemble: Declared.assemble, ...registryOf(values) });
+            return await withCommandStore(store, async () => {
+                return values.query === undefined ?
+                    await declaredDry(store, db, values, io, context) :
+                    await declaredQuery(store, db, values, io, context);
+            });
+        }
+        const store = openAt(db, { intent: 'write', ...registryOf(values) });
+        return await withCommandStore(store, async () => {
+            return values.watch === true ?
+                await declaredWatch(store, db, values, io, context) :
+                await declaredPass(store, db, values, io, context);
+        });
+    }
+    catch (error) {
+        io.stderr.write(`cave connect: ${errorMessage(error)}\n`);
+        return error instanceof LocateError ? 1 : 1;
     }
 };
 export const runConnect = async (argv, context = {}) => {
+    const signal = context.signal;
+    if (signal?.aborted === true)
+        return 0;
+    context = {
+        signal,
+        stdout: context.stdout,
+        stderr: context.stderr,
+        fetchImpl: context.fetchImpl,
+        watch: context.watch,
+        schedule: context.schedule,
+        cancelScheduled: context.cancelScheduled
+    };
     const io = {
         stdout: context.stdout ?? process.stdout,
         stderr: context.stderr ?? process.stderr,
-        ...context.signal === undefined ? {} : { signal: context.signal }
+        ...signal === undefined ? {} : { signal }
     };
+    if (Boolean(io.signal?.aborted))
+        return 0;
     const { values, positionals } = parseArgs({
         args: [...argv],
         options: {
@@ -277,6 +788,7 @@ export const runConnect = async (argv, context = {}) => {
             all: { type: 'boolean' },
             aliases: { type: 'boolean' },
             'no-prelude': { type: 'boolean' },
+            list: { type: 'boolean' },
             help: { type: 'boolean', short: 'h' }
         },
         allowPositionals: true
@@ -285,11 +797,18 @@ export const runConnect = async (argv, context = {}) => {
         io.stdout.write(`${usage}\n`);
         return 0;
     }
+    if (positionals.length === 0) {
+        return runDeclared(values, io, context);
+    }
     const [source] = positionals;
     if (source === undefined || positionals.length !== 1) {
         io.stderr.write(`cave connect: exactly one source is required\n\n${usage}\n`);
         return 1;
     }
+    if (values.list === true) {
+        io.stderr.write('cave connect: --list takes no source\n');
+        return 1;
+    }
     if (values.map === undefined) {
         io.stderr.write(`cave connect: --map <file> is required\n\n${usage}\n`);
         return 1;
@@ -318,18 +837,15 @@ export const runConnect = async (argv, context = {}) => {
             intent: 'write',
             ...values['no-prelude'] === true ? { registry: Registry.empty } : {}
         });
-        try {
+        return await withCommandStore(store, async () => {
             if (values.watch === true) {
                 return await runWatch(store, source, values, name, io, context);
             }
             return await runPass(store, source, values, name, io, context);
-        }
-        finally {
-            store.close();
-        }
+        });
     }
     catch (error) {
-        io.stderr.write(`cave connect: ${error instanceof Error ? error.message : String(error)}\n`);
+        io.stderr.write(`cave connect: ${errorMessage(error)}\n`);
         return 1;
     }
 };