@hraness/sponge 0.2.4 → 0.2.6

package/dist/src/cli/digest.js

@@ -0,0 +1,63 @@
+import { InputError } from '../app/source.js';
+/** Review targets: `all`, `gist`, `idea:N` or `quote:N.M` (0-based), comma-separated. */
+export const reviewSpec = /^(?:all|gist|idea:\d{1,2}|quote:\d{1,2}\.\d)(?:,(?:all|gist|idea:\d{1,2}|quote:\d{1,2}\.\d)){0,63}$/;
+/**
+ * Merge `--accept` and `--reject` targets into the derivation's existing review. `all` applies first and specific
+ * targets override it; a target named under both flags is ambiguous and rejected.
+ */
+export function reviewFromSpec(d, accept, reject) {
+    if (accept === undefined && reject === undefined)
+        throw new InputError();
+    const ideas = d.output.ideas, review = { gist: d.review.gist, ideas: ideas.map((_, i) => d.review.ideas?.[i] ?? null), quotes: ideas.map((idea, i) => idea.quotes.map((_, j) => d.review.quotes?.[i]?.[j] ?? null)) };
+    const parse = (spec) => { if (spec === undefined)
+        return []; if (!reviewSpec.test(spec))
+        throw new InputError(); return [...new Set(spec.split(','))]; };
+    const a = parse(accept), r = parse(reject);
+    if (a.some(t => r.includes(t)))
+        throw new InputError();
+    const set = (target, status) => {
+        if (target === 'all') {
+            review.gist = status;
+            review.ideas = review.ideas.map(() => status);
+            review.quotes = review.quotes.map(q => q.map(() => status));
+            return;
+        }
+        if (target === 'gist') {
+            review.gist = status;
+            return;
+        }
+        const [, kind, i, j] = /^(idea|quote):(\d+)(?:\.(\d+))?$/.exec(target), n = Number(i);
+        if (n >= ideas.length)
+            throw new InputError();
+        if (kind === 'idea') {
+            review.ideas[n] = status;
+            return;
+        }
+        if (Number(j) >= ideas[n].quotes.length)
+            throw new InputError();
+        review.quotes[n][Number(j)] = status;
+    };
+    for (const [targets, status] of [[a, 'accepted'], [r, 'rejected']])
+        for (const t of targets)
+            if (t === 'all')
+                set(t, status);
+    for (const [targets, status] of [[a, 'accepted'], [r, 'rejected']])
+        for (const t of targets)
+            if (t !== 'all')
+                set(t, status);
+    return { ...(review.gist ? { gist: review.gist } : {}), ideas: review.ideas, quotes: review.quotes };
+}
+const mark = (s) => s === 'accepted' ? '[accepted]' : s === 'rejected' ? '[rejected]' : '[draft]';
+/** Plain-text digest with the review targets `sponge review` accepts. */
+export function digestText(d) {
+    const o = d.output, producer = d.producer;
+    const lines = [`Digest ${d.id} (${o.form}${producer?.model?.model ? `, ${producer.model.model}` : ''}${producer?.promptVersion ? `, ${producer.promptVersion}` : ''})`, '', `gist ${mark(d.review.gist)} ${o.gist.lead}`];
+    if (o.gist.context)
+        lines.push(`  ${o.gist.context}`);
+    o.ideas.forEach((idea, i) => {
+        lines.push('', `idea:${i} ${mark(d.review.ideas?.[i])} ${idea.claim}`, ...(idea.kind || idea.voice ? [`  ${[idea.kind, idea.voice && (idea.voice.type === 'author' ? 'author' : `${idea.voice.type}: ${idea.voice.name}`)].filter(Boolean).join('; ')}`] : []), `  ${idea.detail}`);
+        idea.quotes.forEach((q, j) => lines.push(`  quote:${i}.${j} ${mark(d.review.quotes?.[i]?.[j])} “${q.text.replace(/\s+/g, ' ')}”${q.attribution ?? q.speaker ? ` (${q.attribution ?? q.speaker})` : ''}`));
+    });
+    lines.push('', `Tags: ${o.tags.join(', ') || 'none'}`);
+    return lines.join('\n');
+}

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

@@ -1,4 +1,15 @@
 import type { LibraryStore } from '../store/index.js';
+import type { CaptureRuntime } from '../acquisition/index.js';
 import { type ImportOptions, type ImportReport } from '../importers/apply.js';
+import { type JungleImportReport } from '../importers/jungle.js';
 /** A source manifest is explicit; default execution produces a private dry-run report. */
 export declare function importAction(store: LibraryStore, path: string, options: ImportOptions): Promise<ImportReport>;
+/** Jungle is read in place; only an applied import needs the capture runtime, to reverify each bundle. */
+export declare function jungleAction(store: LibraryStore, path: string, options: {
+    dryRun: boolean;
+    runtime?: CaptureRuntime;
+    limit: number;
+    offset: number;
+    signal?: AbortSignal;
+}): Promise<JungleImportReport>;
+export declare function jungleText(r: JungleImportReport): string;

package/dist/src/cli/import.js

@@ -1,3 +1,13 @@
 import { importManifest } from '../importers/apply.js';
+import { releasedBundleVerifier } from '../importers/inspect.js';
+import { importJungle } from '../importers/jungle.js';
 /** A source manifest is explicit; default execution produces a private dry-run report. */
 export function importAction(store, path, options) { return importManifest(store, path, options); }
+/** Jungle is read in place; only an applied import needs the capture runtime, to reverify each bundle. */
+export function jungleAction(store, path, options) {
+    return importJungle(store, path, { dryRun: options.dryRun, limit: options.limit, offset: options.offset, ...(options.signal ? { signal: options.signal } : {}), ...(options.runtime ? { verify: releasedBundleVerifier(options.runtime, store.root, options.signal) } : {}) });
+}
+const tally = (m) => Object.entries(m).sort().map(([k, n]) => `${k} ${n}`).join(', ') || 'none';
+export function jungleText(r) {
+    return [`Jungle ${r.dryRun ? 'dry run (captures verified on --apply)' : 'import'}: ${r.entries.length} of ${r.notes} notes`, `Items: ${r.counts.newItems} new, ${r.counts.existingItems} existing`, `Editorial: ${tally(r.counts.editorial)}`, `Digest v2: ${tally(r.counts.digest)}`, ...(Object.keys(r.counts.digestIssues).length ? [`Not convertible because: ${tally(r.counts.digestIssues)}`] : []), `Quotes: ${r.counts.quotes.assigned} assigned, dropped ${tally(r.counts.quotes.dropped)}`, `Visibility: ${tally(r.counts.visibility)}`, `Skipped: ${tally(r.counts.skipped)}`, ...(r.nextOffset !== null ? [`Next offset: ${r.nextOffset}`] : [])].join('\n');
+}

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

@@ -4,4 +4,7 @@ export declare function indexAction(store: LibraryStore, action: string, id: str
     runtime?: EmbeddingRuntime;
     profile?: string;
     signal?: AbortSignal;
+    keep?: number;
+    dryRun?: boolean;
+    vacuum?: boolean;
 }): Promise<Record<string, unknown>>;

package/dist/src/cli/indexing.js

@@ -1,7 +1,8 @@
-import { embeddingIdentity, embeddingFingerprint } from '../inference/embedding/index.js';
+import { indexSpace } from '../inference/embedding/index.js';
 import { drainIndexQueue } from '../indexing/runner.js';
 import { StoreError } from '../store/index.js';
 import { NativeCatalogError } from '../models/catalog.js';
+import { pruneIndex } from '../indexing/prune-run.js';
 export async function indexAction(store, action, id, options = {}) {
     if (action === 'status')
         return { generation: store.indexStatus(id) };
@@ -11,10 +12,12 @@ export async function indexAction(store, action, id, options = {}) {
             throw new StoreError('invalid-input');
         return { generation: store.activateIndex(id) };
     }
+    if (action === 'prune')
+        return { prune: await pruneIndex(store, { keep: options.keep, dryRun: options.dryRun, vacuum: options.vacuum }) };
     if (!options.runtime)
         throw new NativeCatalogError('runtime-missing');
     if (action === 'create') {
-        const runtime = options.runtime, generation = store.createIndexGeneration({ profileId: options.profile ?? 'default', fingerprint: embeddingFingerprint(runtime.helperSha256), identity: { ...embeddingIdentity, helperSha256: runtime.helperSha256 }, dimensions: embeddingIdentity.dimensions });
+        const space = indexSpace(options.runtime.helperSha256), generation = store.createIndexGeneration({ profileId: options.profile ?? 'default', fingerprint: space.fingerprint, identity: space.identity, dimensions: space.dimensions });
         return { generation, job: store.submitIndexJob(generation.id) };
     }
     return { results: await drainIndexQueue(store, { runtime: options.runtime, signal: options.signal }) };

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,54 @@
+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'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 and within Digest v2's limits: a lead only
+ * when the note's first sentence fits the lead limit (never cut), claims with detail, and quotes that occur verbatim in the
+ * capture with 4-25 words, assigned to ideas as the importer assigns them (at most 2 per idea and 6 in all), within the
+ * 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,87 @@
+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 and within Digest v2's limits: a lead only
+ * when the note's first sentence fits the lead limit (never cut), claims with detail, and quotes that occur verbatim in the
+ * capture with 4-25 words, assigned to ideas as the importer assigns them (at most 2 per idea and 6 in all), within the
+ * 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 = [], texts = [];
+        for (const q of o.quotes) {
+            const match = locateAll(source, q.text).find(m => !taken.some(t => m.start < t.end && t.start < m.end));
+            if (!match)
+                continue;
+            const text = source.slice(match.start, match.end), n = words(text);
+            if (n >= L.minQuoteWords && n <= L.quoteWords) {
+                taken.push(match);
+                texts.push(text);
+            }
+        }
+        let used = 0, count = 0;
+        assignQuotes(ideas, texts.map(text => ({ text }))).forEach((idea, k) => {
+            const n = words(texts[k]);
+            if (idea === null || count >= L.maxQuotes || used + n > budget)
+                return;
+            used += n;
+            count++;
+            ideas[idea].quotes.push(texts[k]);
+        });
+    }
+    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;
+}