@hraness/sponge 0.2.5 → 0.3.0

package/dist/src/cli/main.js

@@ -4,412 +4,73 @@ import { lstat } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
 import { terminalSafe } from './terminal.js';
 import { parseArguments } from './arguments.js';
-import { readConnections } from './config.js';
-import { pdfSource } from '../pdf/index.js';
-import { articleSource, mediaSource, InputError } from '../app/source.js';
-import { openLibrary, StoreError } from '../store/index.js';
-import { defaultCapturePins, inspectCaptureRuntime, provisionCapture, captureSetupPlan } from '../acquisition/index.js';
-import { queueAction } from './queue.js';
-import { portabilityAction, restoreAction } from './portability.js';
-import { workerAction, serveWorker, hasDueAcquisition } from './worker.js';
-import { nativeSetupPlan, provisionNative, inspectNative } from '../models/runtime.js';
-import { nativeDownloadAuthGuidance } from '../models/download.js';
-import { drainIndexQueue } from '../indexing/runner.js';
-import { indexAction } from './indexing.js';
-import { pruneText } from '../indexing/prune-run.js';
-import { importAction, jungleAction, jungleText } from './import.js';
-import { digestText, reviewFromSpec } from './digest.js';
-import { connectEndpoint } from '../digest/endpoint.js';
-import { createDigest } from '../digest/pipeline.js';
-import { createQueryEmbedder, createTextEmbedder } from '../search/query.js';
-import { runtimeGcAction, runtimeGcText, setupRuntimeGc } from './runtimes.js';
-import { drainLibrary } from '../worker/basic.js';
-import { minAge, publishSite } from '../publish/index.js';
+import { command, usageOf } from './commands.js';
+import { openLibrary } from '../store/index.js';
+import { defaultCapturePins } from '../acquisition/index.js';
 import { failure } from '../acquisition/errors.js';
-const help = `sponge — a local article library
-
-  init                          Create a private library
-  setup --capture|--asr|--embedding  Download one pinned runtime
-  add URL_OR_PDF [--kind article|pdf|media] [--connection ID] [--wait]
-  run --drain                   Process queued articles sequentially
-  queue status                  Show jobs and their states
-  queue cancel JOB              Cancel a queued or active job
-  queue retry JOB               Retry a failed job after resolving its cause
-  queue recover                 Reconcile a stopped worker after cleanup
-  list                          List saved and queued items
-  show ITEM [--format markdown|json]
-  asset ITEM SHA                Write a verified asset to stdout
-  search QUERY [--mode hybrid|lexical] [--profile default] [--limit 20]
-  refresh ITEM [--wait]         Capture a new revision
-  delete ITEM                   Hide an item and remove it from search
-  index create [--profile default]  Queue a new embedding generation
-  index status GENERATION       Inspect generation coverage
-  index run                     Drain queued embedding jobs
-  index rollback GENERATION     Reactivate a compatible complete generation
-  index prune [--keep 1] [--dry-run] [--vacuum]  Delete vectors of retired generations
-  doctor                        Check library and runtime states
-  export ITEM --output DIR      Export Markdown and local assets
-  backup --output FILE          Save a verified offline backup
-  restore FILE --into NEW_DIR   Restore into a new private library
-  gc --dry-run                  Write a report of unreferenced blobs
-  gc --apply REPORT             Recheck and remove reported blobs
-  gc --runtimes [--dry-run]     Remove superseded runtimes, models and worker journals
-  worker install [--language en] Enable the optional background worker
-  worker status                 Inspect the background worker
-  worker uninstall              Stop it and preserve the library
-  import MANIFEST [--apply]     Preview or import existing Wordcell captures
-  import jungle DIR [--apply]   Preview or import Jungle Reading notes, their captures and published state
-  visibility ITEM public|private|default  Override or restore the default
-  highlight ITEM TEXT [--note BODY] [--occurrence N]  Anchor a verbatim quote
-  comment ITEM BODY [--on ANNOTATION]  Comment on an item or reply
-  publish --dry-run [--min-age-days N]  Show the public reading-list entries
-  publish --output DIR [--title T] [--base-url https://...] [--min-age-days N]
-                                Write a signed static feed site with <sponge-list>
-  digest ITEM --endpoint http://127.0.0.1:PORT --model NAME [--check-support]
-                                Draft a digest with a local model server you started
-  digest ITEM                   Show the current digest and its review state
-  review DIGEST --accept SPEC --reject SPEC  Review fields: all, gist, idea:N, quote:N.M
-
-Global flags: --library /absolute/path --json
-Items are public by default only when captured from a public source.
-Use -- before an option-like search query. Capture setup is explicit.
-Digest endpoints must be literal loopback HTTP (127.0.0.1 or [::1]); Sponge never starts a model server.
-Media: --language en enables local English ASR; --force-local bypasses captions.
-These flags apply to --wait, run --drain, or worker serve.
-worker install --language en saves the English ASR choice for background work.
-For trusted local sources, use --allow-private-network with --wait or run.
-`;
-const codes = new Set(['grant-permission', 'repair-auth', 'unsupported', 'unavailable', 'rate-limited', 'partial', 'cleanup-required', 'cancelled', 'invalid-input', 'unclassified', 'integrity', 'limit-exceeded', 'runtime-missing', 'schema-newer', 'owner-busy']);
-function errorCode(error, fallback) { const code = error?.code; return code && codes.has(code) ? code : fallback; }
-function exitFor(code) { return code === 'cancelled' ? 130 : code === 'invalid-input' ? 2 : code === 'partial' ? 3 : ['grant-permission', 'repair-auth', 'cleanup-required', 'runtime-missing', 'owner-busy'].includes(code) ? 4 : 1; }
+import { SpongeError, codeOf, publicCode, exitFor, hints, debugChain } from '../errors.js';
+/** Failures print one categorical JSON line: the public code, its specific `reason` when narrower, and a fixed hint.
+ * Causes, details, paths and upstream messages appear only with --debug or SPONGE_DEBUG=1. */
+function report(error, requestId, debug) {
+    const reason = codeOf(error), code = publicCode(reason), issues = error?.issues, usage = error?.detail?.command;
+    if (Array.isArray(issues))
+        process.stderr.write(JSON.stringify({ issues }) + '\n');
+    const hint = code === 'invalid-input' && typeof usage === 'string' && command(usage)
+        ? `Usage: ${usageOf(usage).replace(/\n/g, ' | ')}`
+        : hints[code];
+    process.stderr.write(JSON.stringify({ ...failure(requestId, code), ...(reason !== code ? { reason } : {}), hint }) + '\n');
+    if (debug)
+        process.stderr.write(debugChain(error));
+    return exitFor(code);
+}
 export async function main(argv, version) {
     const requestId = randomUUID();
-    let store;
+    let store, args;
     const controller = new AbortController();
     const cancel = () => controller.abort();
     process.on('SIGINT', cancel);
     process.on('SIGTERM', cancel);
     try {
-        const args = parseArguments(argv), emit = (data, text) => { const output = args.json ? JSON.stringify({ schemaVersion: 1, requestId, ok: true, ...data }) + '\n' : (text ?? JSON.stringify(data)) + '\n'; process.stdout.write(process.stdout.isTTY ? terminalSafe(output) : output); };
-        if (args.command === 'help') {
-            process.stdout.write(help);
-            return 0;
-        }
-        if (args.command === 'version') {
-            process.stdout.write(version + '\n');
-            return 0;
-        }
-        if (args.command === 'restore') {
-            emit(await restoreAction(args.positional[0], String(args.flags.into)));
-            return 0;
-        }
+        args = parseArguments(argv);
+        const json = args.json, spec = command(args.command);
+        const emit = (data, text) => {
+            const output = json
+                ? JSON.stringify({ schemaVersion: 1, requestId, ok: true, ...data }) + '\n'
+                : (text ?? JSON.stringify(data)) + '\n';
+            process.stdout.write(process.stdout.isTTY ? terminalSafe(output) : output);
+        };
+        const context = {
+            args,
+            version,
+            signal: controller.signal,
+            emit,
+            write: (text) => {
+                process.stdout.write(text);
+            },
+        };
+        if (spec.library === 'none')
+            return await spec.handler(context);
         const root = args.library ?? join(homedir(), '.local', 'share', 'sponge');
-        if (args.command !== 'init') {
+        if (spec.library === 'open') {
             try {
                 await lstat(join(root, '.sponge-library'));
             }
             catch (error) {
                 if (error.code === 'ENOENT')
-                    throw new StoreError('unavailable');
+                    throw new SpongeError('unavailable', { cause: error });
                 throw error;
             }
         }
         store = await openLibrary(root);
-        if (args.command === 'init') {
-            emit({ library: store.root }, `Library: ${store.root}`);
-            return 0;
-        }
-        if (args.command === 'worker' && args.positional[0] !== 'serve') {
-            emit(await workerAction(store, args.positional[0], version, undefined, { language: args.flags.language }));
-            return 0;
-        }
-        if (args.command === 'gc' && args.flags.runtimes) {
-            const report = await runtimeGcAction(store, version, args.flags['dry-run'] === true);
-            emit(report, runtimeGcText(report));
-            return 0;
-        }
-        if (args.command === 'export' || args.command === 'backup' || args.command === 'gc') {
-            emit(await portabilityAction(store, args.command, { itemId: args.positional[0], output: args.flags.output, dryRun: args.flags['dry-run'] === true, report: args.flags.apply }));
-            return 0;
-        }
-        const runtimeRoot = join(store.root, 'runtime', 'capture', defaultCapturePins.id);
-        const nativeRoot = join(store.root, 'runtime', 'models');
-        if (args.command === 'setup' && !args.flags.capture) {
-            const kind = args.flags.asr ? 'asr' : 'embedding', plan = await nativeSetupPlan(kind, version);
-            process.stderr.write(JSON.stringify({ setup: kind, ...plan }) + '\n');
-            try {
-                await provisionNative(kind, nativeRoot, version, controller.signal);
-            }
-            catch (error) {
-                if (error.code === 'repair-auth' && !args.json)
-                    process.stderr.write(nativeDownloadAuthGuidance + '\n');
-                throw error;
-            }
-            const gc = await setupRuntimeGc(store, version);
-            emit({ [kind]: 'ready', gc });
-            return 0;
-        }
-        if (args.command === 'setup') {
-            const plan = captureSetupPlan(defaultCapturePins);
-            process.stderr.write(`Capture setup: ${plan.downloadBytes} pinned artifact bytes, plus frozen dependency downloads. Temporary installation limit: ${plan.stagingBudgetBytes} bytes; retained runtime limit: ${plan.installationBudgetBytes} bytes; dependency installation deadline: ${plan.installationDeadlineMs / 60000} minutes. ${plan.requiredFreeBytes} free bytes required.\n`);
-            await provisionCapture({ runtimeRoot: join(store.root, 'runtime', 'capture'), pins: defaultCapturePins, signal: controller.signal });
-            const gc = await setupRuntimeGc(store, version);
-            emit({ capture: 'ready', gc }, 'skipped' in gc ? `Capture ready\nRuntime GC skipped: ${gc.skipped}` : `Capture ready\n${runtimeGcText(gc)}`);
-            return 0;
-        }
-        if (args.command === 'list') {
-            const items = store.list();
-            emit({ items }, items.map(item => `${item.itemId}\t${item.title}`).join('\n'));
-            return 0;
-        }
-        if (args.command === 'show') {
-            const item = store.read(args.positional[0]);
-            if (!item)
-                throw new StoreError('unavailable');
-            emit({ item, identity: store.identity(item.itemId), annotations: store.listAnnotations(item.itemId), digest: store.currentDigest(item.itemId) ?? null, editorial: store.currentEditorial(item.itemId) ?? null }, item.markdown);
-            return item.status === 'partial' ? 3 : 0;
-        }
-        if (args.command === 'asset') {
-            const item = store.read(args.positional[0]), asset = item?.assets.find(a => a.sha256 === args.positional[1]);
-            if (!asset)
-                throw new StoreError('unavailable');
-            const bytes = store.readBlob(asset);
-            if (args.json)
-                emit({ asset });
-            else {
-                if (process.stdout.isTTY)
-                    throw new InputError();
-                process.stdout.write(bytes);
-            }
-            return 0;
-        }
-        if (args.command === 'index') {
-            const action = args.positional[0], runtime = ['create', 'run'].includes(action) ? await inspectNative('embedding', nativeRoot, version) : undefined;
-            const result = await indexAction(store, action, args.positional[1], { runtime, profile: args.flags.profile, signal: controller.signal, ...(action === 'prune' ? { keep: args.flags.keep === undefined ? undefined : Number(args.flags.keep), dryRun: args.flags['dry-run'] === true, vacuum: args.flags.vacuum === true } : {}) });
-            emit(result, result.prune ? pruneText(result.prune) : undefined);
-            const failed = result.results?.find(r => !r.ok);
-            return failed ? exitFor(failed.code) : 0;
-        }
-        if (args.command === 'search') {
-            if (args.flags.mode === 'lexical') {
-                const items = store.search(args.positional[0], Number(args.flags.limit ?? 20));
-                emit({ items }, items.map(item => `${item.itemId}\t${item.title}`).join('\n'));
-                return 0;
-            }
-            let embedding;
-            try {
-                embedding = await inspectNative('embedding', nativeRoot, version);
-            }
-            catch { /* Hybrid explicitly reports semantic unavailability and preserves lexical results. */ }
-            const result = await store.searchHybrid(args.positional[0], { profileId: args.flags.profile, limit: Number(args.flags.limit ?? 20), signal: controller.signal, ...(embedding ? { embed: createQueryEmbedder(store, embedding) } : {}) });
-            emit({ items: result.hits, warnings: result.warnings, generation: result.generation }, [...result.hits.map(item => `${item.itemId}\t${item.title}`), ...result.warnings.map(warning => `Warning: ${warning}`)].join('\n'));
-            return controller.signal.aborted ? 130 : 0;
-        }
-        if (args.command === 'visibility') {
-            const value = args.positional[1] === 'default' ? null : args.positional[1];
-            const state = store.setVisibility(args.positional[0], value);
-            emit({ itemId: args.positional[0], visibility: state }, `${state.effective}${state.override ? ' (set)' : ' (default)'}`);
-            return 0;
-        }
-        if (args.command === 'highlight') {
-            const annotation = store.addHighlight({ itemId: args.positional[0], quote: args.positional[1], ...(typeof args.flags.note === 'string' ? { note: args.flags.note } : {}), ...(args.flags.occurrence !== undefined ? { occurrence: Number(args.flags.occurrence) } : {}) });
-            emit({ annotation }, annotation.id);
-            return 0;
-        }
-        if (args.command === 'comment') {
-            const annotation = store.addComment({ itemId: args.positional[0], body: args.positional[1], ...(typeof args.flags.on === 'string' ? { parentId: args.flags.on } : {}) });
-            emit({ annotation }, annotation.id);
-            return 0;
-        }
-        if (args.command === 'publish') {
-            const minAgeDays = Number(args.flags['min-age-days'] ?? 0);
-            if (typeof args.flags.output === 'string') {
-                const result = publishSite(store, { output: args.flags.output, minAgeDays, ...(typeof args.flags.title === 'string' ? { title: args.flags.title } : {}), ...(typeof args.flags['base-url'] === 'string' ? { baseUrl: args.flags['base-url'] } : {}) });
-                emit(result, `Published ${result.entries} entr${result.entries === 1 ? 'y' : 'ies'} to ${result.output}`);
-                return 0;
-            }
-            const all = store.publicProjection(), projection = { ...all, entries: minAge(all.entries, minAgeDays) };
-            emit({ dryRun: true, ...projection, ...(minAgeDays ? { held: all.entries.length - projection.entries.length } : {}) }, [...projection.entries.map(entry => `${entry.uri}\t${entry.title}`), ...(projection.skipped.length ? [`Skipped ${projection.skipped.length} public item(s) without a public link`] : [])].join('\n') || 'Nothing public');
-            return 0;
-        }
-        if (args.command === 'digest') {
-            if (!args.flags.endpoint) {
-                const digest = store.currentDigest(args.positional[0]);
-                if (!digest)
-                    throw new StoreError('unavailable');
-                emit({ digest }, digestText(digest));
-                return 0;
-            }
-            const model = await connectEndpoint({ endpoint: String(args.flags.endpoint), model: String(args.flags.model), signal: controller.signal });
-            const embed = args.flags['check-support'] ? createTextEmbedder(store, await inspectNative('embedding', nativeRoot, version)) : undefined;
-            const result = await createDigest(store, args.positional[0], model, { signal: controller.signal, ...(embed ? { embed } : {}) });
-            emit({ digest: result.derivation, duplicate: result.duplicate, ...(result.trace ? { trace: result.trace } : {}) }, digestText(result.derivation));
-            return 0;
-        }
-        if (args.command === 'review') {
-            const prior = store.readDigest(args.positional[0]);
-            if (!prior)
-                throw new StoreError('unavailable');
-            const digest = store.reviewDigest(prior.id, reviewFromSpec(prior, args.flags.accept, args.flags.reject));
-            emit({ digest }, digestText(digest));
-            return 0;
-        }
-        if (args.command === 'delete') {
-            store.delete(args.positional[0]);
-            emit({ itemId: args.positional[0], deleted: true }, 'Deleted');
-            return 0;
-        }
-        if (args.command === 'queue') {
-            const result = await queueAction(store, args.positional[0], args.positional[1]);
-            emit(result);
-            return 0;
-        }
-        if (args.command === 'doctor') {
-            let capture = 'ready';
-            try {
-                await inspectCaptureRuntime(runtimeRoot, defaultCapturePins);
-            }
-            catch (error) {
-                capture = errorCode(error, 'runtime-missing');
-            }
-            const states = {};
-            for (const kind of ['asr', 'embedding']) {
-                try {
-                    await inspectNative(kind, nativeRoot, version);
-                    states[kind] = 'ready';
-                }
-                catch (error) {
-                    states[kind] = errorCode(error, 'runtime-missing');
-                }
-            }
-            const cleanup = store.pendingCleanupCount();
-            emit({ library: 'ready', capture, ...states, pendingCleanup: cleanup }, `Library: ready\nCapture: ${capture}\nASR: ${states.asr}\nEmbedding: ${states.embedding}\nPending cleanup: ${cleanup}`);
-            return cleanup || capture !== 'ready' ? 4 : 0;
-        }
-        if (args.command === 'run' && !hasDueAcquisition(store)) {
-            if (store.ownerSnapshot())
-                throw new StoreError('owner-busy');
-            if (store.pendingCleanupCount())
-                throw Object.assign(Error('cleanup-required'), { code: 'cleanup-required' });
-            if (!store.listJobs().some(job => job.operation === 'index' && job.state === 'queued')) {
-                emit({ results: [], indexResults: [] }, 'Queue empty');
-                return 0;
-            }
-            const runtime = await inspectNative('embedding', nativeRoot, version), indexResults = await drainIndexQueue(store, { runtime, signal: controller.signal });
-            emit({ results: [], indexResults });
-            const failed = indexResults.find(result => !result.ok);
-            return failed && !failed.ok ? exitFor(failed.code) : controller.signal.aborted ? 130 : 0;
-        }
-        const connections = await readConnections(store.root);
-        let jobId, itemId;
-        if (args.command === 'add') {
-            const connection = args.flags.connection ? connections.find(c => c.id === args.flags.connection) : undefined;
-            if (args.flags.connection && !connection)
-                throw new InputError();
-            const input = args.positional[0], kind = (args.flags.kind ?? (/\.pdf(?:[?#]|$)/i.test(input) || input.startsWith('file:') ? 'pdf' : 'article'));
-            const source = (kind === 'pdf' ? pdfSource : kind === 'media' ? mediaSource : articleSource)(input, connection?.realm ?? 'public');
-            const submission = store.submitSource({ kind, ...source, idempotencyKey: 'save:' + source.sourceKey });
-            jobId = submission.jobId;
-            itemId = submission.itemId;
-            const job = store.listJobs().find(j => j.id === jobId);
-            if (!args.flags.wait) {
-                emit({ ...submission, state: job?.state ?? 'queued' }, `${itemId}\t${job?.state ?? 'queued'}`);
-                return 0;
-            }
-            if (job?.state === 'succeeded') {
-                const item = store.read(itemId);
-                emit({ itemId, jobId, status: item.status }, `${itemId}\t${item.status}`);
-                return item.status === 'partial' ? 3 : 0;
-            }
-        }
-        else if (args.command === 'refresh') {
-            const previous = store.listJobs().find(j => j.item_id === args.positional[0]), source = previous && store.sourceForJob(String(previous.id));
-            if (!source || !['article', 'pdf', 'media'].includes(source.kind))
-                throw new StoreError('unavailable');
-            const submission = store.submitSource({ ...source, kind: source.kind, intent: 'refresh', idempotencyKey: randomUUID() });
-            jobId = submission.jobId;
-            itemId = submission.itemId;
-            if (!args.flags.wait) {
-                emit(submission, `${itemId}\tqueued`);
-                return 0;
-            }
-        }
-        if (jobId) {
-            const job = store.listJobs().find(j => j.id === jobId);
-            if (job && job.state !== 'queued') {
-                const code = job.state === 'cancelled' ? 'cancelled' : job.state === 'cleanup-pending' ? 'cleanup-required' : job.state === 'running' ? 'owner-busy' : errorCode({ code: job.reason }, 'unclassified');
-                throw Object.assign(Error(code), { code });
-            }
-        }
-        if (args.command === 'worker') {
-            emit(await serveWorker(store, { signal: controller.signal, language: args.flags.language, forceLocal: args.flags['force-local'] === true, resolveCaptureRuntime: () => inspectCaptureRuntime(runtimeRoot, defaultCapturePins), resolveConnection: (realm) => { if (realm === 'public')
-                    return undefined; const connection = connections.find(c => c.realm === realm); if (!connection)
-                    throw Object.assign(Error('repair-auth'), { code: 'repair-auth' }); return connection.capture; } }, version));
-            return 0;
-        }
-        if (args.command === 'import' && args.positional[0] === 'jungle') {
-            // A dry run reads Jungle and the library only; applying reverifies every capture with the released verifier.
-            const dryRun = args.flags.apply !== true, runtime = dryRun ? undefined : await inspectCaptureRuntime(runtimeRoot, defaultCapturePins).catch(error => { const code = errorCode(error, 'runtime-missing'); throw Object.assign(Error(code), { code }); });
-            const report = await jungleAction(store, args.positional[1], { dryRun, runtime, limit: Number(args.flags.limit ?? 1000), offset: Number(args.flags.offset ?? 0), signal: controller.signal });
-            emit({ report }, jungleText(report));
-            return controller.signal.aborted ? 130 : report.counts.skipped['capture-failed'] || report.counts.skipped['capture-unsupported'] ? 3 : 0;
-        }
-        let runtime;
-        try {
-            runtime = await inspectCaptureRuntime(runtimeRoot, defaultCapturePins);
-        }
-        catch (error) {
-            const code = errorCode(error, 'runtime-missing');
-            throw Object.assign(Error(code), { code });
-        }
-        if (args.command === 'import') {
-            const report = await importAction(store, args.positional[0], { runtime, dryRun: args.flags.apply !== true, limit: Number(args.flags.limit ?? 20), offset: Number(args.flags.offset ?? 0), signal: controller.signal });
-            emit({ report });
-            return controller.signal.aborted ? 130 : report.entries.some(entry => entry.status === 'failed' || entry.status === 'unsupported') ? 3 : 0;
-        }
-        let asrRuntime;
-        try {
-            asrRuntime = await inspectNative('asr', nativeRoot, version);
-        }
-        catch (error) {
-            if (!['runtime-missing', 'unsupported'].includes(errorCode(error, 'integrity')))
-                throw error;
-        }
-        const workerOptions = { asrRuntime, language: args.flags.language, forceLocal: args.flags['force-local'] === true, runtime, jobId, signal: controller.signal, allowPrivateNetwork: args.flags['allow-private-network'] === true, resolveConnection: (realm) => { if (realm === 'public')
-                return undefined; const connection = connections.find(c => c.realm === realm); if (!connection)
-                throw Object.assign(Error('repair-auth'), { code: 'repair-auth' }); return connection.capture; } };
-        const results = await drainLibrary(store, workerOptions);
-        if (jobId && !results.length && !controller.signal.aborted) {
-            const job = store.listJobs().find(j => j.id === jobId);
-            const code = job?.state === 'cancelled' ? 'cancelled' : job?.state === 'cleanup-pending' ? 'cleanup-required' : job?.state === 'running' ? 'owner-busy' : errorCode({ code: job?.reason }, 'unclassified');
-            throw Object.assign(Error(code), { code });
-        }
-        let indexResults = [];
-        if (args.command === 'run' && !controller.signal.aborted && store.listJobs().some(job => job.operation === 'index' && job.state === 'queued')) {
-            const embedding = await inspectNative('embedding', nativeRoot, version);
-            indexResults = await drainIndexQueue(store, { runtime: embedding, signal: controller.signal });
-            const indexFailed = indexResults.find(result => !result.ok);
-            if (indexFailed && !indexFailed.ok) {
-                process.stderr.write(JSON.stringify(indexFailed) + '\n');
-                return exitFor(indexFailed.code);
-            }
-        }
-        const failed = results.find(result => !result.ok);
-        if (failed && !failed.ok) {
-            process.stderr.write(JSON.stringify(failed) + '\n');
-            return exitFor(failed.code);
-        }
-        if (controller.signal.aborted)
-            return 130;
-        emit({ results, indexResults }, results.map(result => result.ok ? `${result.itemId}\t${result.status}` : '').join('\n') || 'Queue empty');
-        return results.some(result => result.ok && result.status === 'partial') ? 3 : 0;
+        return await spec.handler({
+            ...context,
+            store,
+            captureRoot: join(store.root, 'runtime', 'capture', defaultCapturePins.id),
+            nativeRoot: join(store.root, 'runtime', 'models'),
+        });
     }
     catch (error) {
-        const value = error?.code, code = value && codes.has(value) ? value : 'unclassified', issues = error?.issues;
-        if (Array.isArray(issues))
-            process.stderr.write(JSON.stringify({ issues }) + '\n');
-        process.stderr.write(JSON.stringify(failure(requestId, code)) + '\n');
-        return exitFor(code);
+        return report(error, requestId, process.env.SPONGE_DEBUG === '1' || (args ? args.debug : argv.includes('--debug')));
     }
     finally {
         store?.close();

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

@@ -1,9 +1,7 @@
 import type { LibraryStore } from '../store/index.js';
-import { restoreLibrary } from '../portability/backup.js';
 export declare function portabilityAction(store: LibraryStore, action: 'export' | 'backup' | 'gc', options: {
     itemId?: string;
     output?: string;
     dryRun?: boolean;
     report?: string;
 }): Promise<Record<string, unknown>>;
-export declare const restoreAction: typeof restoreLibrary;

package/dist/src/cli/portability.js

@@ -1,34 +1,40 @@
 import { fstatSync, closeSync } from 'node:fs';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
-import { StoreError } from '../store/types.js';
 import { openRead, readExact, writePrivateExclusive } from '../portability/files.js';
-import { backupLibrary, restoreLibrary } from '../portability/backup.js';
+import { backupLibrary } from '../portability/backup.js';
 import { exportItem } from '../portability/export.js';
 import { createGcReport, applyGcReport } from '../portability/gc.js';
+import { SpongeError } from '../errors.js';
 export async function portabilityAction(store, action, options) {
     if (action === 'export') {
         if (!options.itemId || !options.output)
-            throw new StoreError('invalid-input');
+            throw new SpongeError('invalid-input');
         return exportItem(store, options.itemId, options.output);
     }
     if (action === 'backup') {
         if (!options.output)
-            throw new StoreError('invalid-input');
+            throw new SpongeError('invalid-input');
         return backupLibrary(store, options.output);
     }
     if (action !== 'gc' || Boolean(options.dryRun) === Boolean(options.report))
-        throw new StoreError('invalid-input');
+        throw new SpongeError('invalid-input');
+    // A backup that crashed must not fence collection forever: expire fences whose holder is provably dead.
+    await store.backups.expireFences();
     if (options.dryRun) {
         const report = createGcReport(store), path = join(store.root, 'runtime', `gc-${randomUUID()}.json`);
         writePrivateExclusive(path, JSON.stringify(report) + '\n');
-        return { report: path, candidates: report.candidates.length, bytes: report.candidates.reduce((n, c) => n + c.bytes, 0) };
+        return {
+            report: path,
+            candidates: report.candidates.length,
+            bytes: report.candidates.reduce((n, c) => n + c.bytes, 0),
+        };
     }
     const fd = openRead(options.report);
     try {
         const bytes = fstatSync(fd).size;
         if (bytes > 32 * 1024 ** 2)
-            throw new StoreError('limit-exceeded');
+            throw new SpongeError('limit-exceeded');
         return applyGcReport(store, JSON.parse(readExact(fd, bytes).toString('utf8')));
     }
     finally {
@@ -36,4 +42,3 @@ export async function portabilityAction(store, action, options) {
     }
 }
 // Restore must dispatch before opening the normal library; it never targets the default root.
-export const restoreAction = restoreLibrary;

package/dist/src/cli/queue.js

@@ -1,23 +1,27 @@
-import { StoreError } from '../store/index.js';
 import { recoverWorker } from '../worker/custody.js';
+import { SpongeError } from '../errors.js';
 export async function queueAction(store, action, jobId) {
     if (action === 'status') {
         if (jobId)
-            return { jobs: store.listJobs().filter(j => j.id === jobId) };
-        return { jobs: store.listJobs(), owner: store.ownerSnapshot(), pendingCleanup: store.pendingCleanupCount() };
+            return { jobs: store.queue.list().filter((j) => j.id === jobId) };
+        return {
+            jobs: store.queue.list(),
+            owner: store.queue.ownerSnapshot(),
+            pendingCleanup: store.queue.pendingCleanup(),
+        };
     }
     if (action === 'recover') {
         if (jobId)
-            throw new StoreError('invalid-input');
+            throw new SpongeError('invalid-input');
         return await recoverWorker(store);
     }
     if (!jobId)
-        throw new StoreError('invalid-input');
+        throw new SpongeError('invalid-input');
     if (action === 'cancel')
-        store.requestCancellation(jobId);
+        store.queue.cancel(jobId);
     else if (action === 'retry')
-        store.retryJob(jobId, { automatic: false });
+        store.queue.retry(jobId, { automatic: false });
     else
-        throw new StoreError('invalid-input');
+        throw new SpongeError('invalid-input');
     return { jobId, action };
 }

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

@@ -1,7 +1,5 @@
 import type { LibraryStore } from '../store/index.js';
-import { type RuntimeGcOptions, type RuntimeGcReport } from '../worker/runtime-gc.js';
-/** References of this installed Sponge: its capture pin and its catalog's model packages. */
-export declare function installedReferences(version: string): Promise<Omit<RuntimeGcOptions, 'dryRun'>>;
+import { type RuntimeGcReport } from '../worker/runtime-gc.js';
 export declare function runtimeGcAction(store: LibraryStore, version: string, dryRun: boolean): Promise<RuntimeGcReport>;
 export declare function runtimeGcText(report: RuntimeGcReport): string;
 /** Setup collection follows a verified install and never fails that install. */

package/dist/src/cli/runtimes.js

@@ -2,19 +2,26 @@ import { defaultCapturePins } from '../acquisition/index.js';
 import { loadNativeCatalog, nativeModelPackage } from '../models/catalog.js';
 import { modelSetupPlan } from '../models/artifacts.js';
 import { collectRuntimes } from '../worker/runtime-gc.js';
+import { codeOf } from '../errors.js';
 /** References of this installed Sponge: its capture pin and its catalog's model packages. */
-export async function installedReferences(version) {
+async function installedReferences(version) {
     let models = null;
     try {
         const catalog = await loadNativeCatalog(version);
-        models = { fingerprints: ['asr', 'embedding'].map(kind => modelSetupPlan(nativeModelPackage(catalog, kind)).fingerprint) };
+        models = {
+            fingerprints: ['asr', 'embedding'].map((kind) => modelSetupPlan(nativeModelPackage(catalog, kind)).fingerprint),
+        };
+    }
+    catch {
+        /* Without the catalog no model directory is provably superseded. */
     }
-    catch { /* Without the catalog no model directory is provably superseded. */ }
     return { captureIds: [defaultCapturePins.id], models };
 }
-export async function runtimeGcAction(store, version, dryRun) { return collectRuntimes(store, { ...await installedReferences(version), dryRun }); }
+export async function runtimeGcAction(store, version, dryRun) {
+    return collectRuntimes(store, { ...(await installedReferences(version)), dryRun });
+}
 export function runtimeGcText(report) {
-    const lines = report.removed.map(e => `${report.dryRun ? 'would remove' : 'removed'}\t${e.kind}\t${e.name}\t${e.bytes}`);
+    const lines = report.removed.map((e) => `${report.dryRun ? 'would remove' : 'removed'}\t${e.kind}\t${e.name}\t${e.bytes}`);
     for (const e of report.kept)
         if (e.reason !== 'referenced')
             lines.push(`kept\t${e.kind}\t${e.name}\t${e.reason}`);
@@ -27,6 +34,6 @@ export async function setupRuntimeGc(store, version) {
         return await runtimeGcAction(store, version, false);
     }
     catch (error) {
-        return { skipped: String(error?.code ?? 'unclassified') };
+        return { skipped: codeOf(error) };
     }
 }

package/dist/src/cli/terminal.js

@@ -1,4 +1,4 @@
 /** Neutralize terminal commands without changing redirected Markdown or stored content. */
 export function terminalSafe(value) {
-    return value.replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/gu, c => '\\u' + c.charCodeAt(0).toString(16).padStart(4, '0'));
+    return value.replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/gu, (c) => '\\u' + c.charCodeAt(0).toString(16).padStart(4, '0'));
 }

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

@@ -4,6 +4,13 @@ import { type ServiceEnvironment } from '../service/launch-agent.js';
 export declare function workerAction(store: LibraryStore, action: 'install' | 'status' | 'uninstall', version: string, environment?: ServiceEnvironment, options?: {
     language?: 'en';
 }): Promise<Record<string, unknown>>;
+/** Doctor's read-only view of the background worker: never installs, repairs or signals anything. */
+export declare function workerDoctor(store: LibraryStore, version: string, environment?: ServiceEnvironment): Promise<{
+    worker: string;
+    drift?: unknown;
+    repair?: unknown;
+    lastExit?: unknown;
+}>;
 type DrainOptions = Parameters<typeof drainLibrary>[1];
 export type ServiceDrainOptions = Omit<DrainOptions, 'runtime'> & {
     runtime?: DrainOptions['runtime'];