@hraness/sponge 0.2.3 → 0.2.5

package/dist/src/acquisition/pins.js

@@ -1,9 +1,9 @@
 import { captureLockfile } from './lock.js';
 /** Immutable released media/PDF capability pins; installed qualification is recorded separately. */
 export const defaultCapturePins = {
-    id: 'capture-ghostget-0.18.101-bun-1.3.14-darwin-arm64',
-    ghostget: { version: '0.18.101', url: 'https://github.com/hraness/ghostget/releases/download/v0.18.101/hraness-ghostget-0.18.101.tgz', bytes: 12493207, sha256: 'ae62e2792b429b1e9c38292046e4223801ec5a5f7fb36076dfcbd137d4ca4c87' },
+    id: 'capture-ghostget-0.18.102-bun-1.3.14-darwin-arm64',
+    ghostget: { version: '0.18.102', url: 'https://github.com/hraness/ghostget/releases/download/v0.18.102/hraness-ghostget-0.18.102.tgz', bytes: 12493537, sha256: '68edcad50b72f77b2ed73e9affba3b49e6b683622cdec9e2fabdffa90e3a0bdb' },
     wordcell: { version: '0.27.0', url: 'https://github.com/hraness/wordcell/releases/download/v0.27.0/hraness-wordcell-0.27.0.tgz', bytes: 1465897, sha256: 'df47868147cda46d741895d3cd1ddcbec14a563b341aa09052545be7696c9262' },
     bun: { version: '1.3.14', url: 'https://github.com/oven-sh/bun/releases/download/bun-v1.3.14/bun-darwin-aarch64.zip', bytes: 23586433, sha256: 'd8b96221828ad6f97ac7ac0ab7e95872341af763001e8803e8267652c2652620', executableSha256: 'e0c90ec15d33363e6b70713d56bc3b2c7585c17f40a0fe0f8fd9305901d4e233', archiveExecutable: 'bun-darwin-aarch64/bun' },
-    lockfile: captureLockfile, lockSha256: "afa317a4fdda77ceb8d104bb23bbb2d8d5bef62cda5630e5fcc8d0b299b6c357",
+    lockfile: captureLockfile, lockSha256: "456370c26a7286bab70307595745f4be382a684a11223e848dbb0032761d59d0",
 };

package/dist/src/annotations/quote.d.ts

@@ -0,0 +1,32 @@
+/** A located quotation: raw offsets into the revision's Markdown plus context that survives re-capture. */
+export interface TextQuote {
+    type: 'text-quote';
+    exact: string;
+    prefix: string;
+    suffix: string;
+    start: number;
+    end: number;
+}
+export declare function foldText(value: string): string;
+/** Every occurrence of `quote` in `source`, compared after folding. */
+export declare function locateAll(source: string, quote: string): {
+    start: number;
+    end: number;
+}[];
+export declare function textQuote(source: string, start: number, end: number): TextQuote;
+/** The single match for `quote`, or undefined when absent or ambiguous. */
+export declare function locateQuote(source: string, quote: string): TextQuote | undefined;
+/** A stored selector still names its exact text in `source`. */
+export declare function anchorHolds(source: string, anchor: TextQuote): boolean;
+export declare function words(value: string): number;
+/**
+ * Every occurrence of `quote` in `source` ignoring inline Markdown and case, within optional raw bounds.
+ * Use only to snap a model's near-verbatim quote to the exact raw span; checking still uses `locateAll`.
+ */
+export declare function locateLoose(source: string, quote: string, bounds?: {
+    start: number;
+    end: number;
+}): {
+    start: number;
+    end: number;
+}[];

package/dist/src/annotations/quote.js

@@ -0,0 +1,135 @@
+const context = 32;
+const graphemes = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+const escapable = /^[\\`*_{}[\]()#+\-.!|>~<"']$/;
+/**
+ * Fold the differences a reader cannot see: Markdown escapes, curly quotes, dashes, runs of
+ * whitespace and Unicode normalization. Folding works on grapheme clusters, each NFC-normalized;
+ * every folded code unit of a cluster maps to the cluster's raw bounds, so `map[i]` and `ends[i]`
+ * bound the raw text of folded unit i and matches map back exactly.
+ */
+function fold(raw) {
+    let text = '', space = false;
+    const map = [], ends = [], clusters = [...graphemes.segment(raw)];
+    const emit = (out, start, end) => { text += out; for (let k = 0; k < out.length; k++) {
+        map.push(start);
+        ends.push(end);
+    } };
+    for (let c = 0; c < clusters.length; c++) {
+        const { segment, index } = clusters[c];
+        // An escaped character maps to its backslash, so a match starting there keeps the escape.
+        let ch = segment, end = index + segment.length;
+        if (segment === '\\' && c + 1 < clusters.length && escapable.test(clusters[c + 1].segment)) {
+            ch = clusters[++c].segment;
+            end = clusters[c].index + ch.length;
+        }
+        if (/^\s+$/.test(ch)) {
+            if (!space && text.length)
+                emit(' ', index, end);
+            space = true;
+            continue;
+        }
+        space = false;
+        emit(ch.replace(/[‘’‚′]/g, "'").replace(/[“”„″]/g, '"').replace(/[\u2010-\u2015\u2212]/g, '-').normalize('NFC'), index, end);
+    }
+    if (text.endsWith(' ')) {
+        text = text.slice(0, -1);
+        map.pop();
+        ends.pop();
+    }
+    return { text, map, ends };
+}
+export function foldText(value) { return fold(value).text; }
+/** Every occurrence of `quote` in `source`, compared after folding. */
+export function locateAll(source, quote) {
+    const s = fold(source), q = fold(quote).text, out = [];
+    if (!q)
+        return out;
+    for (let at = s.text.indexOf(q); at >= 0; at = s.text.indexOf(q, at + 1)) {
+        // A match must start and end on cluster boundaries; half a cluster has no raw offsets.
+        const last = at + q.length - 1;
+        if (at > 0 && s.map[at - 1] === s.map[at] || last + 1 < s.text.length && s.map[last + 1] === s.map[last])
+            continue;
+        out.push({ start: s.map[at], end: s.ends[last] });
+    }
+    return out;
+}
+export function textQuote(source, start, end) {
+    return { type: 'text-quote', exact: source.slice(start, end), prefix: source.slice(Math.max(0, start - context), start), suffix: source.slice(end, end + context), start, end };
+}
+/** The single match for `quote`, or undefined when absent or ambiguous. */
+export function locateQuote(source, quote) {
+    const all = locateAll(source, quote);
+    return all.length === 1 ? textQuote(source, all[0].start, all[0].end) : undefined;
+}
+/** A stored selector still names its exact text in `source`. */
+export function anchorHolds(source, anchor) {
+    return Number.isSafeInteger(anchor.start) && Number.isSafeInteger(anchor.end) && anchor.start >= 0 && anchor.end > anchor.start && source.slice(anchor.start, anchor.end) === anchor.exact;
+}
+export function words(value) { const t = foldText(value); return t ? t.split(' ').length : 0; }
+/**
+ * Rendered-text projection for snapping a near-verbatim quote: drops inline Markdown syntax (link targets, brackets,
+ * emphasis, code ticks, line-start block markers), folds like `fold`, and lowercases. Offsets map back to raw text.
+ */
+function rendered(raw) {
+    let text = '', map = [], ends = [], space = false, lineStart = true;
+    for (let i = 0; i < raw.length; i++) {
+        let ch = raw[i], at = i;
+        if (lineStart) {
+            const m = /^[ \t]*(?:>[ \t]?|#{1,6}[ \t]+|[-*+][ \t]+|\d{1,3}[.)][ \t]+)*/.exec(raw.slice(i, i + 64));
+            if (m[0].length) {
+                i += m[0].length - 1;
+                lineStart = false;
+                continue;
+            }
+        }
+        lineStart = ch === '\n';
+        if (ch === ']' && raw[i + 1] === '(') {
+            const close = raw.indexOf(')', i + 2);
+            if (close > 0 && close - i < 2048 && !raw.slice(i + 2, close).includes('\n')) {
+                i = close;
+                continue;
+            }
+        }
+        if (ch === '!' && raw[i + 1] === '[' || /[[\]*_`]/.test(ch))
+            continue;
+        if (ch === '\\' && i + 1 < raw.length && /[\\`*_{}[\]()#+\-.!|>~<"']/.test(raw[i + 1])) {
+            ch = raw[++i];
+        }
+        if (/\s/.test(ch)) {
+            if (!space && text.length) {
+                text += ' ';
+                map.push(i);
+                ends.push(i + 1);
+            }
+            space = true;
+            continue;
+        }
+        space = false;
+        ch = ch.replace(/[‘’‚′]/g, "'").replace(/[“”„″]/g, '"').replace(/[‐-―−]/g, '-').normalize('NFC').toLowerCase();
+        // One entry per output code unit: normalization and case mapping may change the length.
+        text += ch;
+        for (let k = 0; k < ch.length; k++) {
+            map.push(at);
+            ends.push(i + 1);
+        }
+    }
+    if (text.endsWith(' ')) {
+        text = text.slice(0, -1);
+        map.pop();
+        ends.pop();
+    }
+    return { text, map, ends };
+}
+/**
+ * Every occurrence of `quote` in `source` ignoring inline Markdown and case, within optional raw bounds.
+ * Use only to snap a model's near-verbatim quote to the exact raw span; checking still uses `locateAll`.
+ */
+export function locateLoose(source, quote, bounds = { start: 0, end: source.length }) {
+    const q = rendered(quote).text.replace(/^["'\s]+|["'\s]+$/g, ''), out = [];
+    if (q.length < 8)
+        return out;
+    const s = rendered(source.slice(bounds.start, bounds.end));
+    for (let at = s.text.indexOf(q); at >= 0; at = s.text.indexOf(q, at + 1))
+        out.push({ start: bounds.start + s.map[at], end: bounds.start + s.ends[at + q.length - 1] });
+    return out;
+}

package/dist/src/annotations/store.d.ts

@@ -0,0 +1,50 @@
+import type { DatabaseSync } from 'node:sqlite';
+export interface Annotation {
+    id: string;
+    itemId: string;
+    kind: 'note' | 'highlight' | 'comment';
+    revisionId: string | null;
+    parentId: string | null;
+    anchor: unknown;
+    body: string;
+    createdAt: string;
+    updatedAt: string | null;
+}
+export declare function markdownFor(db: DatabaseSync, revisionId: string): string;
+/**
+ * Highlight `quote` in the item's current revision. An ambiguous quote needs `occurrence` (0-based),
+ * so a highlight never silently lands on the wrong passage.
+ */
+export declare function addHighlight(db: DatabaseSync, input: {
+    itemId: string;
+    quote: string;
+    occurrence?: number;
+    note?: string;
+}): Annotation;
+export declare function addComment(db: DatabaseSync, input: {
+    itemId: string;
+    body: string;
+    parentId?: string;
+}): Annotation;
+/**
+ * An imported note keeps a stable id per source note. Re-importing an unchanged note is a no-op;
+ * once the user edits or deletes it, the user's choice wins and the import skips it.
+ */
+export declare function importNote(db: DatabaseSync, input: {
+    itemId: string;
+    revisionId: string;
+    namespace: string;
+    sourceKey: string;
+    noteId: string;
+    body: string;
+}): void;
+export declare function updateAnnotation(db: DatabaseSync, id: string, body: string): Annotation;
+/** Tombstone, never a row delete, so another device learns the deletion. */
+export declare function deleteAnnotation(db: DatabaseSync, id: string): void;
+/** Reading state is one field per item; `updatedAt` travels with it. */
+export declare function setReadingState(db: DatabaseSync, itemId: string, state: unknown): void;
+export declare function readAnnotation(db: DatabaseSync, id: string): Annotation | undefined;
+/** The one annotation reader: live annotations in creation order, highlights checked against their revision. */
+export declare function listAnnotations(db: DatabaseSync, itemId: string): (Annotation & {
+    anchored?: boolean;
+})[];

package/dist/src/annotations/store.js

@@ -0,0 +1,89 @@
+import { randomUUID } from 'node:crypto';
+import { anchorHolds, locateAll, textQuote } from './quote.js';
+import { mutate } from '../store/changes.js';
+import { StoreError } from '../store/types.js';
+import { digest, text } from '../store/files.js';
+const now = () => new Date().toISOString();
+const fail = (code = 'invalid-input') => { throw new StoreError(code); };
+export function markdownFor(db, revisionId) {
+    const row = db.prepare("SELECT markdown FROM representations WHERE revision_id=? AND kind='markdown'").get(revisionId);
+    return typeof row?.markdown === 'string' ? row.markdown : fail('unavailable');
+}
+/** Create through the log with the full row image, so a replay rebuilds the same row. */
+function create(db, id, row) { mutate(db, 'annotation', id, 'created', row); }
+/**
+ * Highlight `quote` in the item's current revision. An ambiguous quote needs `occurrence` (0-based),
+ * so a highlight never silently lands on the wrong passage.
+ */
+export function addHighlight(db, input) {
+    text(input.quote, 4000);
+    if (input.note !== undefined)
+        text(input.note, 16384);
+    const item = db.prepare('SELECT current_revision FROM items WHERE id=? AND deleted_at IS NULL').get(input.itemId);
+    if (!item?.current_revision)
+        fail('unavailable');
+    const revisionId = String(item.current_revision), source = markdownFor(db, revisionId), matches = locateAll(source, input.quote);
+    const index = input.occurrence ?? (matches.length === 1 ? 0 : -1);
+    if (!Number.isSafeInteger(index) || index < 0 || index >= matches.length)
+        fail();
+    const anchor = textQuote(source, matches[index].start, matches[index].end), id = randomUUID();
+    create(db, id, { itemId: input.itemId, kind: 'highlight', revisionId, parentId: null, anchor, body: input.note ?? '', createdAt: now() });
+    return readAnnotation(db, id);
+}
+export function addComment(db, input) {
+    text(input.body, 16384);
+    if (!db.prepare('SELECT 1 FROM items WHERE id=? AND deleted_at IS NULL').get(input.itemId))
+        fail('unavailable');
+    if (input.parentId !== undefined) {
+        const parent = db.prepare('SELECT item_id,deleted_at FROM annotations WHERE id=?').get(input.parentId);
+        if (!parent || parent.item_id !== input.itemId || parent.deleted_at)
+            fail('unavailable');
+    }
+    const id = randomUUID();
+    create(db, id, { itemId: input.itemId, kind: 'comment', revisionId: null, parentId: input.parentId ?? null, anchor: null, body: input.body, createdAt: now() });
+    return readAnnotation(db, id);
+}
+/**
+ * An imported note keeps a stable id per source note. Re-importing an unchanged note is a no-op;
+ * once the user edits or deletes it, the user's choice wins and the import skips it.
+ */
+export function importNote(db, input) {
+    const id = digest(JSON.stringify(['import-note-v1', input.namespace, input.sourceKey, input.noteId]));
+    const prior = db.prepare('SELECT item_id,body,updated_at,deleted_at FROM annotations WHERE id=?').get(id);
+    if (prior) {
+        if (prior.item_id !== input.itemId || prior.body !== input.body && prior.updated_at === null && prior.deleted_at === null)
+            fail('integrity');
+        return;
+    }
+    create(db, id, { itemId: input.itemId, kind: 'note', revisionId: input.revisionId, parentId: null, anchor: { kind: 'imported-note', sourceId: input.noteId }, body: input.body, createdAt: now() });
+}
+export function updateAnnotation(db, id, body) {
+    text(body, 16384);
+    const row = db.prepare('SELECT body,deleted_at FROM annotations WHERE id=?').get(id);
+    if (!row || row.deleted_at)
+        fail('unavailable');
+    if (row.body !== body)
+        mutate(db, 'annotation', id, 'body', { body, updatedAt: now() });
+    return readAnnotation(db, id);
+}
+/** Tombstone, never a row delete, so another device learns the deletion. */
+export function deleteAnnotation(db, id) {
+    const row = db.prepare('SELECT deleted_at FROM annotations WHERE id=?').get(id);
+    if (!row)
+        fail('unavailable');
+    if (!row.deleted_at)
+        mutate(db, 'annotation', id, 'deleted', now());
+}
+/** Reading state is one field per item; `updatedAt` travels with it. */
+export function setReadingState(db, itemId, state) { mutate(db, 'reading', itemId, 'state', { state, updatedAt: now() }); }
+function annotationRow(r) { return { id: String(r.id), itemId: String(r.item_id), kind: r.kind, revisionId: r.revision_id === null ? null : String(r.revision_id), parentId: r.parent_id === null ? null : String(r.parent_id), anchor: JSON.parse(String(r.anchor_json)), body: String(r.body), createdAt: String(r.created_at), updatedAt: r.updated_at === null ? null : String(r.updated_at) }; }
+export function readAnnotation(db, id) { const r = db.prepare('SELECT * FROM annotations WHERE id=? AND deleted_at IS NULL').get(id); return r ? annotationRow(r) : undefined; }
+/** The one annotation reader: live annotations in creation order, highlights checked against their revision. */
+export function listAnnotations(db, itemId) {
+    return db.prepare('SELECT * FROM annotations WHERE item_id=? AND deleted_at IS NULL ORDER BY created_at,rowid').all(itemId).map(r => {
+        const a = annotationRow(r);
+        if (a.kind !== 'highlight' || !a.revisionId)
+            return a;
+        return { ...a, anchored: anchorHolds(markdownFor(db, a.revisionId), a.anchor) };
+    });
+}

package/dist/src/app/source.d.ts

@@ -2,6 +2,8 @@ export declare class InputError extends Error {
     readonly code = "invalid-input";
     constructor();
 }
+/** The identity form of an http(s) locator; source keys and shareable URIs both use it. Its output pins every existing source key. */
+export declare function normalizeWebLocator(locator: string): string;
 export declare function articleSource(locator: string, realm?: string): {
     sourceKey: string;
     locator: string;

package/dist/src/app/source.js

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { campaignFields, filterQuery } from '../identity/query-policy.js';
 export class InputError extends Error {
     code = 'invalid-input';
     constructor() { super('invalid-input'); }
@@ -7,6 +8,14 @@ export class InputError extends Error {
 function webSource(locator, realm, kind) {
     if (Buffer.byteLength(locator) > 8192 || !realm || Buffer.byteLength(realm) > 256 || /[\u0000-\u001f\u007f]/u.test(locator + realm))
         throw new InputError();
+    const normalized = normalizeWebLocator(locator);
+    const sourceKey = createHash('sha256').update(JSON.stringify([kind, realm, normalized])).digest('hex');
+    return { sourceKey, locator, realm };
+}
+/** The identity form of an http(s) locator; source keys and shareable URIs both use it. Its output pins every existing source key. */
+export function normalizeWebLocator(locator) {
+    if (Buffer.byteLength(locator) > 8192 || /[\u0000-\u001f\u007f]/u.test(locator))
+        throw new InputError();
     let url;
     try {
         url = new URL(locator);
@@ -16,24 +25,11 @@ function webSource(locator, realm, kind) {
     }
     if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || !url.hostname)
         throw new InputError();
-    // Filter raw fields: URLSearchParams mutation rewrites unknown signed query bytes.
-    if (url.search) {
-        const fields = url.search.slice(1).split('&').filter(field => {
-            let key;
-            try {
-                key = decodeURIComponent(field.split('=', 1)[0].replaceAll('+', ' '));
-            }
-            catch {
-                return true;
-            }
-            return !['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'utm_id'].includes(key.toLowerCase());
-        });
-        url.search = fields.length ? '?' + fields.join('&') : '';
-    }
+    // Undecodable keys are kept: they cannot be campaign fields.
+    if (url.search)
+        url.search = filterQuery(url.search, key => campaignFields.has(key));
     // URL normalizes host casing/default ports. Preserve query order, unknown fields and fragments.
-    const normalized = url.href;
-    const sourceKey = createHash('sha256').update(JSON.stringify([kind, realm, normalized])).digest('hex');
-    return { sourceKey, locator, realm };
+    return url.href;
 }
 export function articleSource(locator, realm = 'public') { return webSource(locator, realm, 'article'); }
 /** A page and its media can be saved independently without changing existing article identities. */

package/dist/src/cli/arguments.js

@@ -1,5 +1,6 @@
 import { isAbsolute } from 'node:path';
 import { InputError } from '../app/source.js';
+import { reviewSpec } from './digest.js';
 const specifications = {
     init: { count: 0, flags: {} },
     add: { count: 1, flags: { connection: 'value', kind: 'value', wait: 'boolean', language: 'value', 'force-local': 'boolean', 'allow-private-network': 'boolean' } },
@@ -16,10 +17,16 @@ const specifications = {
     export: { count: 1, flags: { output: 'value' } },
     backup: { count: 0, flags: { output: 'value' } },
     restore: { count: 1, flags: { into: 'value' } },
-    gc: { count: 0, flags: { 'dry-run': 'boolean', apply: 'value' } },
+    gc: { count: 0, flags: { 'dry-run': 'boolean', apply: 'value', runtimes: 'boolean' } },
     worker: { count: 1, flags: { language: 'value', 'force-local': 'boolean' } },
-    index: { count: -1, flags: { profile: 'value' } },
-    import: { count: 1, flags: { apply: 'boolean', 'dry-run': 'boolean', limit: 'value', offset: 'value' } },
+    index: { count: -1, flags: { profile: 'value', keep: 'value', 'dry-run': 'boolean', vacuum: 'boolean' } },
+    visibility: { count: 2, flags: {} },
+    highlight: { count: 2, flags: { note: 'value', occurrence: 'value' } },
+    comment: { count: 2, flags: { on: 'value' } },
+    publish: { count: 0, flags: { 'dry-run': 'boolean', output: 'value', 'min-age-days': 'value', title: 'value', 'base-url': 'value' } },
+    digest: { count: 1, flags: { endpoint: 'value', model: 'value', 'check-support': 'boolean' } },
+    review: { count: 1, flags: { accept: 'value', reject: 'value' } },
+    import: { count: -1, flags: { apply: 'boolean', 'dry-run': 'boolean', limit: 'value', offset: 'value' } },
 };
 /** No shell grammar, implicit option coercion, duplicate flags, or unbounded argv. */
 export function parseArguments(argv) {
@@ -63,7 +70,7 @@ export function parseArguments(argv) {
             positional.push(arg);
     }
     const spec = command && specifications[command];
-    if (!command || !spec || (command === 'queue' ? !(['status', 'recover'].includes(positional[0]) && positional.length === 1 || ['cancel', 'retry'].includes(positional[0]) && positional.length === 2) : command === 'index' ? !(['create', 'run'].includes(positional[0]) && positional.length === 1 || ['status', 'rollback'].includes(positional[0]) && positional.length === 2) : positional.length !== spec.count))
+    if (!command || !spec || (command === 'queue' ? !(['status', 'recover'].includes(positional[0]) && positional.length === 1 || ['cancel', 'retry'].includes(positional[0]) && positional.length === 2) : command === 'import' ? !(positional.length === 1 || positional[0] === 'jungle' && positional.length === 2) : command === 'index' ? !(['create', 'run', 'prune'].includes(positional[0]) && positional.length === 1 || ['status', 'rollback'].includes(positional[0]) && positional.length === 2) : positional.length !== spec.count))
         throw new InputError();
     if (Object.keys(flags).some(key => !['library', 'json'].includes(key) && !Object.hasOwn(spec.flags, key)))
         throw new InputError();
@@ -76,7 +83,7 @@ export function parseArguments(argv) {
         throw new InputError();
     if (flags.mode && !['lexical', 'hybrid'].includes(String(flags.mode)))
         throw new InputError();
-    if (flags.limit && (!/^[1-9]\d{0,2}$/u.test(String(flags.limit)) || Number(flags.limit) > 100))
+    if (flags.limit && (!/^[1-9]\d{0,3}$/u.test(String(flags.limit)) || Number(flags.limit) > (command === 'import' && positional[0] === 'jungle' ? 1000 : 100)))
         throw new InputError();
     if (command === 'run' && !flags.drain || command === 'setup' && [flags.capture, flags.asr, flags.embedding].filter(Boolean).length !== 1)
         throw new InputError();
@@ -86,11 +93,19 @@ export function parseArguments(argv) {
         throw new InputError();
     if (command === 'restore' && (typeof flags.into !== 'string' || !isAbsolute(flags.into) || flags.library !== undefined || !isAbsolute(positional[0])))
         throw new InputError();
-    if (command === 'gc' && (Boolean(flags['dry-run']) === Boolean(flags.apply) || flags.apply !== undefined && !isAbsolute(String(flags.apply))))
+    if (command === 'gc' && (flags.runtimes ? flags.apply !== undefined : Boolean(flags['dry-run']) === Boolean(flags.apply) || flags.apply !== undefined && !isAbsolute(String(flags.apply))))
         throw new InputError();
     if (command === 'worker' && !['install', 'status', 'uninstall', 'serve'].includes(positional[0]))
         throw new InputError();
-    if (command === 'import' && (!isAbsolute(positional[0]) || flags.apply && flags['dry-run'] || flags.offset !== undefined && !/^(0|[1-9][0-9]{0,5})$/.test(String(flags.offset))))
+    if (command === 'import' && (!isAbsolute(positional.at(-1)) || flags.apply && flags['dry-run'] || flags.offset !== undefined && !/^(0|[1-9][0-9]{0,5})$/.test(String(flags.offset))))
+        throw new InputError();
+    if (command === 'visibility' && !['public', 'private', 'default'].includes(positional[1]) || command === 'publish' && (Boolean(flags['dry-run']) === Boolean(flags.output) || flags.output !== undefined && (typeof flags.output !== 'string' || !isAbsolute(flags.output)) || (flags.title !== undefined || flags['base-url'] !== undefined) && !flags.output || flags['min-age-days'] !== undefined && !/^(0|[1-9][0-9]{0,3})$/.test(String(flags['min-age-days'])) || Number(flags['min-age-days'] ?? 0) > 3650 || flags.title !== undefined && String(flags.title).length > 200 || flags['base-url'] !== undefined && !/^https:\/\//.test(String(flags['base-url']))))
+        throw new InputError();
+    if (command === 'digest' && (Boolean(flags.endpoint) !== Boolean(flags.model) || flags['check-support'] && !flags.endpoint || flags.model !== undefined && !/^[\w.:/@+-]{1,256}$/.test(String(flags.model))))
+        throw new InputError();
+    if (command === 'review' && (flags.accept === undefined && flags.reject === undefined || [flags.accept, flags.reject].some(v => v !== undefined && !reviewSpec.test(String(v)))))
+        throw new InputError();
+    if (flags.occurrence !== undefined && !/^(0|[1-9][0-9]{0,4})$/.test(String(flags.occurrence)))
         throw new InputError();
     if (flags.language !== undefined && flags.language !== 'en')
         throw new InputError();
@@ -100,6 +115,8 @@ export function parseArguments(argv) {
         throw new InputError();
     if ((flags.language || flags['force-local']) && (['add', 'refresh'].includes(command) && !flags.wait || command === 'worker' && !['serve', 'install'].includes(positional[0])))
         throw new InputError();
+    if (command === 'index' && positional[0] !== 'prune' && (flags.keep !== undefined || flags['dry-run'] || flags.vacuum) || flags.keep !== undefined && !/^(0|[1-9]|1[0-6])$/.test(String(flags.keep)))
+        throw new InputError();
     if (flags.profile && (!(command === 'search' || command === 'index' && positional[0] === 'create') || !/^[a-zA-Z0-9_-]{1,128}$/.test(String(flags.profile))))
         throw new InputError();
     return { command, positional, flags, library: library, json: flags.json === true || flags.format === 'json' };

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

@@ -0,0 +1,10 @@
+import type { Derivation, DigestReview } from '../store/foundation.js';
+/** Review targets: `all`, `gist`, `idea:N` or `quote:N.M` (0-based), comma-separated. */
+export declare const reviewSpec: RegExp;
+/**
+ * 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 declare function reviewFromSpec(d: Derivation, accept?: string, reject?: string): DigestReview;
+/** Plain-text digest with the review targets `sponge review` accepts. */
+export declare function digestText(d: Derivation): string;

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.type === 'author' ? 'author' : `${idea.voice.type}: ${idea.voice.name}`}`, `  ${idea.detail}`);
+        idea.quotes.forEach((q, j) => lines.push(`  quote:${i}.${j} ${mark(d.review.quotes?.[i]?.[j])} “${q.text.replace(/\s+/g, ' ')}”${q.speaker ? ` (${q.speaker})` : ''}`));
+    });
+    lines.push('', `Tags: ${o.tags.join(', ')}`);
+    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 v1: ${tally(r.counts.v1)}`, `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 }) };