@hraness/sponge 0.2.3 → 0.2.5

package/dist/src/cli/main.js

@@ -15,10 +15,16 @@ 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 { createQueryEmbedder } from '../search/query.js';
 import { indexAction } from './indexing.js';
-import { importAction } from './import.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 { failure } from '../acquisition/errors.js';
 const help = `sponge — a local article library
 
@@ -40,19 +46,34 @@ const help = `sponge — a local article library
   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.
@@ -102,6 +123,11 @@ export async function main(argv, version) {
             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;
@@ -119,14 +145,16 @@ export async function main(argv, version) {
                     process.stderr.write(nativeDownloadAuthGuidance + '\n');
                 throw error;
             }
-            emit({ [kind]: 'ready' });
+            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 });
-            emit({ capture: 'ready' }, 'Capture ready');
+            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') {
@@ -138,7 +166,7 @@ export async function main(argv, version) {
             const item = store.read(args.positional[0]);
             if (!item)
                 throw new StoreError('unavailable');
-            emit({ item }, item.markdown);
+            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') {
@@ -157,8 +185,8 @@ export async function main(argv, version) {
         }
         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 });
-            emit(result);
+            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;
         }
@@ -177,6 +205,55 @@ export async function main(argv, version) {
             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');
@@ -270,6 +347,13 @@ export async function main(argv, version) {
                     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);
@@ -321,7 +405,9 @@ export async function main(argv, version) {
         return results.some(result => result.ok && result.status === 'partial') ? 3 : 0;
     }
     catch (error) {
-        const value = error?.code, code = value && codes.has(value) ? value : 'unclassified';
+        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);
     }

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

@@ -0,0 +1,10 @@
+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'>>;
+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. */
+export declare function setupRuntimeGc(store: LibraryStore, version: string): Promise<RuntimeGcReport | {
+    skipped: string;
+}>;

package/dist/src/cli/runtimes.js

@@ -0,0 +1,32 @@
+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';
+/** References of this installed Sponge: its capture pin and its catalog's model packages. */
+export async function installedReferences(version) {
+    let models = null;
+    try {
+        const catalog = await loadNativeCatalog(version);
+        models = { fingerprints: ['asr', 'embedding'].map(kind => modelSetupPlan(nativeModelPackage(catalog, kind)).fingerprint) };
+    }
+    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 function runtimeGcText(report) {
+    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}`);
+    lines.push(`${report.dryRun ? 'Would reclaim' : 'Reclaimed'} ${report.bytes} bytes`);
+    return lines.join('\n');
+}
+/** Setup collection follows a verified install and never fails that install. */
+export async function setupRuntimeGc(store, version) {
+    try {
+        return await runtimeGcAction(store, version, false);
+    }
+    catch (error) {
+        return { skipped: String(error?.code ?? 'unclassified') };
+    }
+}

package/dist/src/digest/editorial.d.ts

@@ -0,0 +1,53 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { type JungleEditorial } from '../importers/jungle-digest.js';
+import { type ReviewStatus } from '../store/changes.js';
+/**
+ * An editorial derivation keeps a reviewed source note whole (today: one Jungle Reading note of any form), without
+ * Digest v1's limits. It is immutable data addressed like a digest; its review is one logged path, `review.note`.
+ */
+export interface Editorial {
+    id: string;
+    itemId: string;
+    revisionId: string;
+    kind: 'editorial';
+    producer: unknown;
+    inputHash: string;
+    output: JungleEditorial;
+    review: {
+        note?: ReviewStatus;
+    };
+    createdAt: string;
+}
+/** Bound on one editorial object: Jungle's largest notes (full transcripts) are a few hundred KiB. */
+export declare const editorialBytes: number;
+/** Fixed key order, so the same note is the same object on every device. */
+export declare function canonicalEditorial(e: JungleEditorial): string;
+/** The input hash is the note's own Markdown hash: an edited note is a new object, an unchanged one a duplicate. */
+export declare function putEditorial(db: DatabaseSync, input: {
+    itemId: string;
+    revisionId: string;
+    producer: Record<string, unknown>;
+    output: JungleEditorial;
+}): {
+    id: string;
+    duplicate: boolean;
+};
+export declare function readEditorial(db: DatabaseSync, id: string): Editorial | undefined;
+/** The newest editorial derivation of the item's current revision. */
+export declare function currentEditorial(db: DatabaseSync, itemId: string): Editorial | undefined;
+export declare function listEditorials(db: DatabaseSync, itemId: string): Editorial[];
+/** One logged change, and only when the status differs. */
+export declare function reviewEditorial(db: DatabaseSync, id: string, status: ReviewStatus | null): Editorial;
+/**
+ * The public subset of an accepted editorial note, in the public digest shape: a lead only when the note's first
+ * sentence fits the v1 lead limit (never cut), claims with detail, and quotes that occur verbatim in the capture,
+ * each at most 25 words, within the v1 per-entry budget (150 words, and the 10% source share with its 25-word floor).
+ */
+export declare function publicEditorial(db: DatabaseSync, e: Editorial): {
+    lead?: string;
+    ideas: {
+        claim: string;
+        detail: string;
+        quotes: string[];
+    }[];
+} | undefined;

package/dist/src/digest/editorial.js

@@ -0,0 +1,81 @@
+import { locateAll, words } from '../annotations/quote.js';
+import { markdownFor } from '../annotations/store.js';
+import { assignQuotes, firstSentence } from '../importers/jungle-digest.js';
+import { mutate } from '../store/changes.js';
+import { StoreError } from '../store/types.js';
+import { digest } from '../store/files.js';
+import { derivationId } from './store.js';
+import { digestLimits as L } from './schema.js';
+const now = () => new Date().toISOString();
+const fail = (code = 'invalid-input') => { throw new StoreError(code); };
+/** Bound on one editorial object: Jungle's largest notes (full transcripts) are a few hundred KiB. */
+export const editorialBytes = 1024 ** 2;
+const str = (v, max = 65536) => typeof v === 'string' && Buffer.byteLength(v) <= max;
+/** Fixed key order, so the same note is the same object on every device. */
+export function canonicalEditorial(e) {
+    return JSON.stringify({ schemaVersion: e.schemaVersion, source: e.source, form: e.form, slug: e.slug, status: e.status, title: e.title, sourceUrl: e.sourceUrl, capture: e.capture, frontmatter: e.frontmatter, ...(e.gist !== undefined ? { gist: e.gist } : {}), ...(e.ideas ? { ideas: e.ideas.map(i => ({ claim: i.claim, detail: i.detail })) } : {}), ...(e.quotes ? { quotes: e.quotes.map(q => ({ text: q.text, attribution: q.attribution, speaker: q.speaker })) } : {}), markdownSha256: e.markdownSha256, markdown: e.markdown });
+}
+/** The input hash is the note's own Markdown hash: an edited note is a new object, an unchanged one a duplicate. */
+export function putEditorial(db, input) {
+    const e = input.output, producer = JSON.stringify(input.producer);
+    if (!producer || Buffer.byteLength(producer) > 4096)
+        fail();
+    if (db.prepare('SELECT item_id FROM revisions WHERE id=?').get(input.revisionId)?.item_id !== input.itemId)
+        fail('unavailable');
+    if (e?.schemaVersion !== 1 || e.source !== 'jungle-reading' || ![e.form, e.slug, e.status, e.title, e.sourceUrl, e.capture].every(v => str(v, 16384)) || !str(e.markdown, 4 * 1024 ** 2) || digest(e.markdown) !== e.markdownSha256)
+        fail();
+    const output = canonicalEditorial(e);
+    if (Buffer.byteLength(output) > editorialBytes)
+        fail();
+    const id = derivationId(input.revisionId, 'editorial', e.markdownSha256, output);
+    if (db.prepare('SELECT 1 FROM derivations WHERE id=?').get(id))
+        return { id, duplicate: true };
+    db.prepare("INSERT INTO derivations(id,item_id,revision_id,kind,schema_version,producer_json,input_hash,output_json,created_at) VALUES(?,?,?,'editorial',1,?,?,?,?)").run(id, input.itemId, input.revisionId, producer, e.markdownSha256, output, now());
+    return { id, duplicate: false };
+}
+function editorialRow(r) { return { id: String(r.id), itemId: String(r.item_id), revisionId: String(r.revision_id), kind: 'editorial', producer: JSON.parse(String(r.producer_json)), inputHash: String(r.input_hash), output: JSON.parse(String(r.output_json)), review: JSON.parse(String(r.review_json)), createdAt: String(r.created_at) }; }
+export function readEditorial(db, id) { const r = db.prepare("SELECT * FROM derivations WHERE id=? AND kind='editorial'").get(id); return r ? editorialRow(r) : undefined; }
+/** The newest editorial derivation of the item's current revision. */
+export function currentEditorial(db, itemId) {
+    const r = db.prepare("SELECT d.* FROM derivations d JOIN items i ON i.id=d.item_id AND i.current_revision=d.revision_id WHERE d.item_id=? AND d.kind='editorial' ORDER BY d.created_at DESC,d.rowid DESC LIMIT 1").get(itemId);
+    return r ? editorialRow(r) : undefined;
+}
+export function listEditorials(db, itemId) { return db.prepare("SELECT * FROM derivations WHERE item_id=? AND kind='editorial' ORDER BY created_at,rowid").all(itemId).map(editorialRow); }
+/** One logged change, and only when the status differs. */
+export function reviewEditorial(db, id, status) {
+    const d = readEditorial(db, id) ?? fail('unavailable');
+    if (status !== null && status !== 'accepted' && status !== 'rejected')
+        fail();
+    if ((d.review.note ?? null) !== status)
+        mutate(db, 'derivation', id, 'review.note', status);
+    return readEditorial(db, id);
+}
+/**
+ * The public subset of an accepted editorial note, in the public digest shape: a lead only when the note's first
+ * sentence fits the v1 lead limit (never cut), claims with detail, and quotes that occur verbatim in the capture,
+ * each at most 25 words, within the v1 per-entry budget (150 words, and the 10% source share with its 25-word floor).
+ */
+export function publicEditorial(db, e) {
+    if (e.review.note !== 'accepted')
+        return undefined;
+    const o = e.output, [first] = firstSentence(o.gist ?? ''), lead = first && first.length <= L.leadChars ? first : undefined;
+    const ideas = (o.ideas ?? []).map(i => ({ claim: i.claim, detail: i.detail, quotes: [] }));
+    if (ideas.length && o.quotes?.length) {
+        const source = markdownFor(db, e.revisionId), budget = Math.min(L.totalQuoteWords, Math.max(L.quoteWords, Math.floor(words(source) * L.sourceQuoteShare))), taken = [];
+        let used = 0;
+        assignQuotes(ideas, o.quotes).forEach((idea, k) => {
+            if (idea === null || ideas[idea].quotes.length >= L.maxQuotesPerIdea)
+                return;
+            const match = locateAll(source, o.quotes[k].text).find(m => !taken.some(t => m.start < t.end && t.start < m.end));
+            if (!match)
+                return;
+            const text = source.slice(match.start, match.end), n = words(text);
+            if (n < L.minQuoteWords || n > L.quoteWords || used + n > budget)
+                return;
+            used += n;
+            taken.push(match);
+            ideas[idea].quotes.push(text);
+        });
+    }
+    return lead || ideas.length ? { ...(lead ? { lead } : {}), ideas } : undefined;
+}

package/dist/src/digest/endpoint.d.ts

@@ -0,0 +1,20 @@
+import { type DigestModel } from './pipeline.js';
+/**
+ * A user-started local OpenAI-compatible server (llama.cpp `llama-server`, LM Studio, Ollama). Captured text must not
+ * leave the machine, so only literal loopback HTTP origins are accepted, redirects are refused, and Sponge never starts a server.
+ */
+export declare function loopbackEndpoint(value: string): URL;
+/** GGUF quantization from a model filename, e.g. `gemma-4-12b-it-Q4_K_M.gguf` → `Q4_K_M`. */
+export declare function quantizationOf(path: string): string | undefined;
+export interface EndpointOptions {
+    endpoint: string;
+    model: string;
+    signal?: AbortSignal;
+    fetch?: typeof fetch;
+    probeTimeoutMs?: number;
+}
+/**
+ * Confirm the server lists `model`, read what identity it exposes (llama.cpp `/props`, Ollama `/api/version`),
+ * and return a DigestModel that requests JSON-schema-constrained chat completions.
+ */
+export declare function connectEndpoint(options: EndpointOptions): Promise<DigestModel>;

package/dist/src/digest/endpoint.js

@@ -0,0 +1,103 @@
+import { DigestError } from './pipeline.js';
+/**
+ * A user-started local OpenAI-compatible server (llama.cpp `llama-server`, LM Studio, Ollama). Captured text must not
+ * leave the machine, so only literal loopback HTTP origins are accepted, redirects are refused, and Sponge never starts a server.
+ */
+export function loopbackEndpoint(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new DigestError('invalid-input');
+    }
+    // A hostname such as `localhost` resolves through configuration Sponge does not control; only literal addresses pass.
+    if (url.protocol !== 'http:' || !['127.0.0.1', '[::1]'].includes(url.hostname) || url.username || url.password || url.search || url.hash || !['', '/', '/v1', '/v1/'].includes(url.pathname))
+        throw new DigestError('invalid-input');
+    return new URL(url.origin);
+}
+async function readCapped(response, max) {
+    const reader = response.body?.getReader(), chunks = [];
+    if (!reader)
+        throw new DigestError('unavailable');
+    let size = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        size += value.byteLength;
+        if (size > max) {
+            await reader.cancel().catch(() => undefined);
+            throw new DigestError('limit-exceeded');
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+const label = (v, max = 128) => typeof v === 'string' && v.trim() && v.length <= max && !/[\u0000-\u001f\u007f]/.test(v) ? v.trim() : undefined;
+/** GGUF quantization from a model filename, e.g. `gemma-4-12b-it-Q4_K_M.gguf` → `Q4_K_M`. */
+export function quantizationOf(path) {
+    return /(?:^|[-_.])((?:IQ|Q)\d(?:_[A-Z0-9]+)*|BF16|F16|F32)(?=\.gguf$|[-_.])/i.exec(path.split('/').pop() ?? '')?.[1]?.toUpperCase();
+}
+/**
+ * Confirm the server lists `model`, read what identity it exposes (llama.cpp `/props`, Ollama `/api/version`),
+ * and return a DigestModel that requests JSON-schema-constrained chat completions.
+ */
+export async function connectEndpoint(options) {
+    const origin = loopbackEndpoint(options.endpoint), request = options.fetch ?? fetch, model = label(options.model, 256);
+    if (!model)
+        throw new DigestError('invalid-input');
+    const get = async (path) => {
+        const signal = AbortSignal.any([options.signal ?? new AbortController().signal, AbortSignal.timeout(options.probeTimeoutMs ?? 10000)]);
+        try {
+            const r = await request(new URL(path, origin), { signal, redirect: 'error', headers: { accept: 'application/json' } });
+            return r.ok ? JSON.parse(await readCapped(r, 1 << 20)) : undefined;
+        }
+        catch (error) {
+            if (options.signal?.aborted)
+                throw new DigestError('cancelled');
+            if (error instanceof DigestError)
+                throw error;
+            return undefined;
+        }
+    };
+    const models = await get('/v1/models');
+    if (!Array.isArray(models?.data))
+        throw new DigestError('unavailable');
+    if (!models.data.some(m => m?.id === model))
+        throw new DigestError('invalid-input');
+    const props = await get('/props'), build = label(props?.build_info);
+    let runtime = build ? `llama.cpp ${build}` : undefined;
+    if (!runtime) {
+        const ollama = label((await get('/api/version'))?.version);
+        runtime = ollama ? `ollama ${ollama}` : 'openai-compatible';
+    }
+    const identity = { model, quantization: (typeof props?.model_path === 'string' && quantizationOf(props.model_path)) || quantizationOf(model) || 'unknown', runtime };
+    return { identity, generate: (messages, schema, generate) => complete(origin, request, model, messages, schema, generate) };
+}
+async function complete(origin, request, model, messages, schema, o) {
+    const body = JSON.stringify({ model, messages, stream: false, temperature: o.temperature, seed: o.seed, max_tokens: o.maxTokens, response_format: { type: 'json_schema', json_schema: { name: 'sponge_digest', strict: true, schema } } });
+    const response = await request(new URL('/v1/chat/completions', origin), { method: 'POST', signal: o.signal, redirect: 'error', headers: { 'content-type': 'application/json', accept: 'application/json' }, body });
+    if (!response.ok) {
+        await response.body?.cancel().catch(() => undefined);
+        throw new DigestError('unavailable');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(await readCapped(response, o.maxOutputBytes * 2 + 65536));
+    }
+    catch (error) {
+        if (error instanceof DigestError)
+            throw error;
+        throw new DigestError('unavailable');
+    }
+    const choice = parsed?.choices?.[0];
+    if (choice?.finish_reason === 'length')
+        throw new DigestError('limit-exceeded');
+    const content = choice?.message?.content;
+    if (typeof content !== 'string' || !content.trim())
+        throw new DigestError('unavailable');
+    if (Buffer.byteLength(content) > o.maxOutputBytes)
+        throw new DigestError('limit-exceeded');
+    return content;
+}

package/dist/src/digest/pipeline.d.ts

@@ -0,0 +1,148 @@
+import { forms, type DigestIssue, type DigestOptions, type DigestV1 } from './schema.js';
+import type { LibraryStore } from '../store/index.js';
+import type { Derivation } from '../store/foundation.js';
+/**
+ * Model-agnostic Digest v1 drafting. The model sees numbered passages and cites a passage id plus a short exact
+ * span; code snaps, orders, prunes and checks. Nothing leaves this module except through the injected model.
+ */
+export declare const PROMPT_VERSION = "sponge-digest-prompt-v1";
+export type ChatMessage = {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+};
+export type JsonSchema = Record<string, unknown>;
+/** Stable identity recorded in the producer and the input hash. Unknown parts are the literal 'unknown'. */
+export interface ModelIdentity {
+    model: string;
+    quantization: string;
+    runtime: string;
+}
+export interface GenerateOptions {
+    signal: AbortSignal;
+    maxOutputBytes: number;
+    maxTokens: number;
+    temperature: number;
+    seed: number;
+}
+export interface DigestModel {
+    identity: ModelIdentity;
+    generate(messages: ChatMessage[], schema: JsonSchema, options: GenerateOptions): Promise<string>;
+}
+/** Output-shaping parameters are hashed; time and byte bounds are not, because they only decide whether a run finishes. */
+export interface DigestParams {
+    temperature: number;
+    seed: number;
+    maxTokens: number;
+    contextChars: number;
+    maxSections: number;
+    timeoutMs: number;
+    deadlineMs: number;
+    maxOutputBytes: number;
+}
+/** 24k characters is roughly 6k tokens of passages, leaving room for instructions and output in an 8k context on an 8 GB Mac. */
+export declare const defaultDigestParams: DigestParams;
+export type DigestErrorCode = 'invalid-input' | 'unavailable' | 'cancelled' | 'limit-exceeded';
+export declare class DigestError extends Error {
+    readonly code: DigestErrorCode;
+    readonly issues?: DigestIssue[] | undefined;
+    constructor(code: DigestErrorCode, issues?: DigestIssue[] | undefined);
+}
+export type Form = typeof forms[number];
+/** Quotes under this many words carry no evidence; the checker is gaining the same floor. */
+export declare const minQuoteWords = 4;
+export interface Passage {
+    id: number;
+    start: number;
+    end: number;
+    heading: string;
+    text: string;
+}
+export interface Highlight {
+    text: string;
+    start?: number;
+}
+/** Sorted-key JSON; the only serialization that enters input hashes. */
+export declare function canonicalJson(value: unknown): string;
+/** Paragraph-level passages with raw offsets. Headings label passages; code fences and image-only blocks are not quotable. */
+export declare function passages(markdown: string, maxChars?: number): Passage[];
+/** Pack passages into sections of at most `budget` display characters, preferring heading boundaries past half a budget. */
+export declare function sectionsOf(list: Passage[], budget: number): Passage[][];
+export declare const quoteBudget: (markdown: string) => number;
+/** JSON Schema for the model's draft. Tags become an enum when a vocabulary is given. */
+export declare function draftSchema(passageCount: number, vocabulary?: readonly string[]): JsonSchema;
+export declare function notesSchema(first: number, last: number): JsonSchema;
+interface Draft {
+    digest: DigestV1;
+    cites: (number | undefined)[][];
+}
+export interface QuoteStats {
+    exact: number;
+    folded: number;
+    snapped: number;
+    missing: number;
+    short: number;
+}
+export type QuoteMatch = 'exact' | 'folded' | 'snapped' | 'missing';
+/**
+ * Make a quote exactly verbatim when that is unambiguous: a unique folded or Markdown-insensitive match, inside
+ * `within` first, becomes the raw source span. Ambiguous folded matches keep their text for the checker; absent ones are 'missing'.
+ */
+export declare function snapQuote(source: string, text: string, within?: {
+    start: number;
+    end: number;
+}): {
+    text: string;
+    match: QuoteMatch;
+};
+/** Snap every quote in place and drop quotes under `minQuoteWords`. */
+export declare function snapQuotes(draft: Draft, source: string, list: Passage[]): QuoteStats;
+export interface DraftInput {
+    revisionId: string;
+    markdown: string;
+    title?: string;
+    form: Form;
+    model: DigestModel;
+    highlights?: readonly Highlight[];
+    vocabulary?: readonly string[];
+    params?: Partial<DigestParams>;
+    signal?: AbortSignal;
+    /** Unit-normalized embeddings for short texts; when given, quotes must support their claims by cosine. */
+    embed?: (texts: string[], signal: AbortSignal) => Promise<number[][]>;
+    supportThreshold?: number;
+}
+export interface DraftTrace {
+    strategy: 'single' | 'sections';
+    sections: number;
+    calls: number;
+    repaired: boolean;
+    attempts: {
+        issues: DigestIssue[];
+        quotes?: QuoteStats;
+    }[];
+    dropped: {
+        quotes: number;
+        ideas: number;
+        tags: number;
+    };
+}
+export interface DraftResult {
+    output: DigestV1;
+    inputHash: string;
+    producer: Record<string, unknown>;
+    options: DigestOptions;
+    trace: DraftTrace;
+}
+/** sha256 over canonical JSON of the revision, its Markdown, the prompt version, the model identity and every output-shaping input. */
+export declare function digestInputHash(input: Pick<DraftInput, 'revisionId' | 'markdown' | 'form' | 'highlights' | 'vocabulary' | 'params' | 'supportThreshold' | 'embed'> & {
+    model: ModelIdentity;
+}): string;
+/** Unqualified on real claims: a deliberately low bar that only catches quotes unrelated to their claim. */
+export declare const defaultSupportThreshold = 0.35;
+export declare function draftDigest(input: DraftInput): Promise<DraftResult>;
+/** Draft and store a digest for the item's current revision. A matching input hash returns the stored draft without calling the model. */
+export declare function createDigest(store: LibraryStore, itemId: string, model: DigestModel, options?: Omit<DraftInput, 'revisionId' | 'markdown' | 'title' | 'form' | 'model' | 'highlights'>): Promise<{
+    derivation: Derivation;
+    duplicate: boolean;
+    trace?: DraftTrace;
+}>;
+export {};