@hraness/sponge 0.2.4 → 0.2.6

package/dist/src/store/foundation.js

@@ -0,0 +1,7 @@
+/** Sync and publishing foundation, split by concern; this barrel keeps existing imports working. See docs/decisions/sync-and-publishing.md. */
+export { applyChange, append, listChanges, mutate, seedChanges, setReviewPath, sourceRefId, maxChangeBytes } from './changes.js';
+export { backfillUris, itemUris, itemsForUri, setVisibility, syncUris, visibility } from '../identity/visibility.js';
+export { addComment, addHighlight, deleteAnnotation, importNote, listAnnotations, markdownFor, readAnnotation, setReadingState, updateAnnotation } from '../annotations/store.js';
+export { acceptedDigest, canonicalDigest, currentDigest, derivationId, findDigest, putDigest, readDigest, reviewDigest } from '../digest/store.js';
+export { currentEditorial, listEditorials, publicEditorial, putEditorial, readEditorial, reviewEditorial } from '../digest/editorial.js';
+export { publicProjection } from '../publish/projection.js';

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

@@ -1,9 +1,13 @@
 import { DatabaseSync } from 'node:sqlite';
+import * as foundation from './foundation.js';
+import * as jungle from '../importers/jungle-store.js';
 import type { JobCheckpoint } from '../../contracts/index.js';
 import { type AttemptToken, type OwnedAttempt, type BlobReference, type CommitRevision, type OwnerToken, type ReadableItem, type SourceSubmission, type StoreOptions, type Submission } from './types.js';
 import * as indexing from '../indexing/index.js';
+import * as prune from '../indexing/prune.js';
 import { hybridSearch } from '../search/hybrid.js';
 export * from './types.js';
+export declare const libraryVersion = 7;
 export declare const libraryMigrations: readonly string[];
 type Row = Record<string, any>;
 export declare function openLibrary(path: string, options?: StoreOptions): Promise<LibraryStore>;
@@ -29,20 +33,76 @@ export declare class LibraryStore {
     writeIndexBatch(id: string, fingerprint: string, batch: Parameters<typeof indexing.writeBatch>[3]): void;
     activateIndex(id: string): indexing.GenerationStatus;
     cancelIndex(id: string): void;
+    /** Retired-generation pruning; see src/indexing/prune.ts. The plan probes rollback inside a rolled-back savepoint. */
+    pruneIndexPlan(keep: number): {
+        generations: prune.PruneEntry[];
+        stats: prune.PageStats;
+    };
+    pruneIndexStep(owner: OwnerToken, id: string, keep: number): number;
+    /** VACUUM cannot run in a transaction: fences are checked under the owner token immediately before it. */
+    vacuumLibrary(owner: OwnerToken): prune.PageStats;
     searchHybrid(query: string, options?: Parameters<typeof hybridSearch>[2]): Promise<import("../search/hybrid.js").SearchResult>;
+    /** Export's view: the one annotation reader, without the redundant item id, plus reading state. */
     readAnnotations(itemId: string): {
         annotations: {
             id: string;
+            kind: "note" | "highlight" | "comment";
             revisionId: string | null;
+            parentId: string | null;
             anchor: unknown;
             body: string;
             createdAt: string;
+            updatedAt: string | null;
+            anchored?: boolean;
         }[];
         readingState: {
             state: unknown;
             updatedAt: string;
         } | null;
     };
+    /** Sync and publishing foundation; see docs/decisions/sync-and-publishing.md. */
+    identity(itemId: string): {
+        uris: import("../identity/uri.js").ItemUri[];
+        visibility: foundation.VisibilityState;
+    };
+    itemsForUri(uri: string): string[];
+    setVisibility(itemId: string, value: foundation.Visibility | null): foundation.VisibilityState;
+    addHighlight(input: Parameters<typeof foundation.addHighlight>[1]): foundation.Annotation;
+    addComment(input: Parameters<typeof foundation.addComment>[1]): foundation.Annotation;
+    updateAnnotation(id: string, body: string): foundation.Annotation;
+    deleteAnnotation(id: string): void;
+    listAnnotations(itemId: string): (foundation.Annotation & {
+        anchored?: boolean;
+    })[];
+    putDigest(input: Parameters<typeof foundation.putDigest>[1]): {
+        id: string;
+        duplicate: boolean;
+    };
+    currentDigest(itemId: string): foundation.Derivation | undefined;
+    readDigest(id: string): foundation.Derivation | undefined;
+    findDigest(revisionId: string, inputHash: string): foundation.Derivation | undefined;
+    reviewDigest(id: string, review: foundation.DigestReview): foundation.Derivation;
+    currentEditorial(itemId: string): foundation.Editorial | undefined;
+    readEditorial(id: string): foundation.Editorial | undefined;
+    reviewEditorial(id: string, status: foundation.ReviewStatus | null): foundation.Editorial;
+    /** The item an importer realm holds for one source key, with its current revision; deleted items are reported, not hidden. */
+    importedItem(realm: string, sourceKey: string): {
+        itemId: string;
+        deleted: boolean;
+        revisionId: string | null;
+    } | null;
+    importedRevision(itemId: string, bundleHash: string): string;
+    revisionMarkdown(revisionId: string): string;
+    planJungleNote(input: jungle.JungleNoteInput): jungle.JunglePlan;
+    applyJungleNote(input: jungle.JungleNoteInput): jungle.JunglePlan;
+    listChanges(after?: number, limit?: number): foundation.LoggedChange[];
+    publicProjection(): {
+        entries: foundation.PublicEntry[];
+        skipped: {
+            itemId: string;
+            reason: string;
+        }[];
+    };
     lookupImportReceipt(namespace: string, sourceKey: string, sourceHash: string): {
         itemId: string;
         outcome: string;
@@ -112,6 +172,15 @@ export declare class LibraryStore {
     finishBackup(id: string): void;
     /** Hold the SQLite writer fence across synchronous GC inspection and removal. */
     withGcFence<T>(expectedEpoch: number, callback: (references: readonly BlobReference[]) => T): T;
+    /** Runtime GC pins: recorded model artifacts and embedding helpers of active or building generations. */
+    runtimeReferences(): {
+        modelArtifacts: {
+            id: string;
+            manifest: string;
+        }[];
+        embeddingHelpers: string[];
+        unmappedSpaces: number;
+    };
     /** GC must honor both durable staging pins and active backup fences. */
     pendingCleanupCount(): number;
     hasGcFence(): boolean;

package/dist/src/store/index.js

@@ -5,18 +5,26 @@ import { randomUUID, createHash } from 'node:crypto';
 import { sql as sql1 } from '../../migrations/001.js';
 import { sql as sql2 } from '../../migrations/002.js';
 import { sql as sql3 } from '../../migrations/003.js';
-import { sql as sql4, version } from '../../migrations/004.js';
+import { sql as sql4 } from '../../migrations/004.js';
+import { sql as sql5 } from '../../migrations/005.js';
+import { sql as sql6 } from '../../migrations/006.js';
+import { sql as sql7, version } from '../../migrations/007.js';
+import * as foundation from './foundation.js';
+import * as jungle from '../importers/jungle-store.js';
 import * as indexJobs from '../indexing/jobs.js';
 import { limits } from '../../contracts/index.js';
 import { validateMetadataClaim, validateMetadataWarnings } from '../../contracts/validate.js';
 import { confinedFile, digest, hash, integer, regularFile, safeDirectory, syncDirectory, text, verifyFile, pathExists, readVerifiedFile } from './files.js';
 import { StoreError } from './types.js';
 import * as indexing from '../indexing/index.js';
+import * as prune from '../indexing/prune.js';
 import { hybridSearch } from '../search/hybrid.js';
+import { indexReadable, unindexReadable, lexicalSearch } from '../search/lexical.js';
 import { initializeVectorExtension } from '../search/extension.js';
 export * from './types.js';
 const now = () => new Date().toISOString();
-const migrations = [sql1, sql2, sql3, sql4];
+const migrations = [sql1, sql2, sql3, sql4, sql5, sql6, sql7];
+export const libraryVersion = version;
 export const libraryMigrations = Object.freeze([...migrations]);
 export async function openLibrary(path, options = {}) {
     if (path === parse(path).root)
@@ -90,35 +98,51 @@ export async function openLibrary(path, options = {}) {
                 }
                 if (actual > 0 && db.prepare('SELECT schema_version FROM library_info WHERE id=1').get()?.schema_version !== actual)
                     throw new StoreError('integrity');
-                if (actual < version) {
-                    // SQLite backup incorporates WAL; never copy the main file alone.
-                    const backupPath = join(root, 'backups', `before-schema-${version}-${randomUUID()}.sqlite`);
-                    await backup(db, backupPath);
-                    chmodSync(backupPath, 0o600);
-                    const fd = openSync(backupPath, constants.O_RDONLY);
-                    try {
-                        fsyncSync(fd);
+                let backupPath;
+                try {
+                    if (actual < version) {
+                        // SQLite backup incorporates WAL; never copy the main file alone.
+                        backupPath = join(root, 'backups', `before-schema-${version}-${randomUUID()}.sqlite`);
+                        await backup(db, backupPath);
+                        chmodSync(backupPath, 0o600);
+                        const fd = openSync(backupPath, constants.O_RDONLY);
+                        try {
+                            fsyncSync(fd);
+                        }
+                        finally {
+                            closeSync(fd);
+                        }
+                        syncDirectory(dirname(backupPath));
                     }
-                    finally {
-                        closeSync(fd);
+                    for (let target = actual + 1; target <= version; target++) {
+                        db.exec('BEGIN IMMEDIATE');
+                        try {
+                            db.exec(migrations[target - 1]);
+                            // Code steps are total per item: one hostile row never makes the library unopenable.
+                            if (target === 5) {
+                                foundation.backfillUris(db);
+                                foundation.seedChanges(db);
+                            }
+                            if (target === 1)
+                                db.prepare('INSERT INTO library_info(id,uuid,schema_version,created_by) VALUES(1,?,?,?)').run(randomUUID(), target, options.appVersion ?? 'development');
+                            else
+                                db.prepare('UPDATE library_info SET schema_version=? WHERE id=1').run(target);
+                            db.prepare('INSERT INTO schema_migrations VALUES(?,?,?)').run(target, digest(migrations[target - 1]), now());
+                            db.exec(`PRAGMA user_version=${target}; COMMIT`);
+                        }
+                        catch (error) {
+                            db.exec('ROLLBACK');
+                            throw error;
+                        }
                     }
-                    syncDirectory(dirname(backupPath));
                 }
-                for (let target = actual + 1; target <= version; target++) {
-                    db.exec('BEGIN IMMEDIATE');
-                    try {
-                        db.exec(migrations[target - 1]);
-                        if (target === 1)
-                            db.prepare('INSERT INTO library_info(id,uuid,schema_version,created_by) VALUES(1,?,?,?)').run(randomUUID(), target, options.appVersion ?? 'development');
-                        else
-                            db.prepare('UPDATE library_info SET schema_version=? WHERE id=1').run(target);
-                        db.prepare('INSERT INTO schema_migrations VALUES(?,?,?)').run(target, digest(migrations[target - 1]), now());
-                        db.exec(`PRAGMA user_version=${target}; COMMIT`);
-                    }
-                    catch (error) {
-                        db.exec('ROLLBACK');
-                        throw error;
+                catch (error) {
+                    // Nothing committed, so the library is byte-for-byte what the backup holds: drop the copy.
+                    if (backupPath && Number(db.prepare('PRAGMA user_version').get()?.user_version) === actual) {
+                        rmSync(backupPath, { force: true });
+                        syncDirectory(dirname(backupPath));
                     }
+                    throw error;
                 }
             }
             finally {
@@ -185,8 +209,43 @@ export class LibraryStore {
     writeIndexBatch(id, fingerprint, batch) { indexing.writeBatch(this.db, id, fingerprint, batch); }
     activateIndex(id) { return indexing.activateGeneration(this.db, id); }
     cancelIndex(id) { indexing.cancelGeneration(this.db, id); }
+    /** Retired-generation pruning; see src/indexing/prune.ts. The plan probes rollback inside a rolled-back savepoint. */
+    pruneIndexPlan(keep) { return this.transaction(() => ({ generations: prune.planPrune(this.db, keep), stats: prune.pageStats(this.db) })); }
+    pruneIndexStep(owner, id, keep) { text(id, 256); return this.transaction(() => { this.checkOwner(owner); if (this.pendingCleanupCount() || this.hasGcFence())
+        throw new StoreError('owner-busy'); return prune.pruneStep(this.db, id, keep); }); }
+    /** VACUUM cannot run in a transaction: fences are checked under the owner token immediately before it. */
+    vacuumLibrary(owner) { const stats = this.transaction(() => { this.checkOwner(owner); if (this.pendingCleanupCount() || this.hasGcFence())
+        throw new StoreError('owner-busy'); return prune.pageStats(this.db); }); prune.vacuumSpace(this.root, stats.bytes); this.db.exec('VACUUM'); this.db.exec('PRAGMA wal_checkpoint(TRUNCATE)'); return prune.pageStats(this.db); }
     searchHybrid(query, options = {}) { return hybridSearch(this.db, query, options); }
-    readAnnotations(itemId) { text(itemId, 256); const annotations = this.db.prepare('SELECT id,revision_id,anchor_json,body,created_at FROM annotations WHERE item_id=? ORDER BY created_at,id').all(itemId).map(row => ({ id: String(row.id), revisionId: row.revision_id === null ? null : String(row.revision_id), anchor: JSON.parse(String(row.anchor_json)), body: String(row.body), createdAt: String(row.created_at) })); const reading = this.db.prepare('SELECT state_json,updated_at FROM reading_state WHERE item_id=?').get(itemId); return { annotations, readingState: reading ? { state: JSON.parse(String(reading.state_json)), updatedAt: String(reading.updated_at) } : null }; }
+    /** Export's view: the one annotation reader, without the redundant item id, plus reading state. */
+    readAnnotations(itemId) { text(itemId, 256); const annotations = foundation.listAnnotations(this.db, itemId).map(({ itemId: _, ...a }) => a); const reading = this.db.prepare('SELECT state_json,updated_at FROM reading_state WHERE item_id=?').get(itemId); return { annotations, readingState: reading ? { state: JSON.parse(String(reading.state_json)), updatedAt: String(reading.updated_at) } : null }; }
+    /** Sync and publishing foundation; see docs/decisions/sync-and-publishing.md. */
+    identity(itemId) { text(itemId, 256); return { uris: foundation.itemUris(this.db, itemId), visibility: foundation.visibility(this.db, itemId) }; }
+    itemsForUri(uri) { return foundation.itemsForUri(this.db, uri); }
+    setVisibility(itemId, value) { text(itemId, 256); return this.transaction(() => foundation.setVisibility(this.db, itemId, value)); }
+    addHighlight(input) { text(input.itemId, 256); return this.transaction(() => foundation.addHighlight(this.db, input)); }
+    addComment(input) { text(input.itemId, 256); if (input.parentId !== undefined)
+        text(input.parentId, 256); return this.transaction(() => foundation.addComment(this.db, input)); }
+    updateAnnotation(id, body) { text(id, 256); return this.transaction(() => foundation.updateAnnotation(this.db, id, body)); }
+    deleteAnnotation(id) { text(id, 256); this.transaction(() => foundation.deleteAnnotation(this.db, id)); }
+    listAnnotations(itemId) { text(itemId, 256); return foundation.listAnnotations(this.db, itemId); }
+    putDigest(input) { text(input.itemId, 256); text(input.revisionId, 256); return this.transaction(() => foundation.putDigest(this.db, input)); }
+    currentDigest(itemId) { text(itemId, 256); return foundation.currentDigest(this.db, itemId); }
+    readDigest(id) { text(id, 256); return foundation.readDigest(this.db, id); }
+    findDigest(revisionId, inputHash) { text(revisionId, 256); return foundation.findDigest(this.db, revisionId, inputHash); }
+    reviewDigest(id, review) { text(id, 256); return this.transaction(() => foundation.reviewDigest(this.db, id, review)); }
+    currentEditorial(itemId) { text(itemId, 256); return foundation.currentEditorial(this.db, itemId); }
+    readEditorial(id) { text(id, 256); return foundation.readEditorial(this.db, id); }
+    reviewEditorial(id, status) { text(id, 256); return this.transaction(() => foundation.reviewEditorial(this.db, id, status)); }
+    /** The item an importer realm holds for one source key, with its current revision; deleted items are reported, not hidden. */
+    importedItem(realm, sourceKey) { text(realm, 256); text(sourceKey, 8192); const r = this.db.prepare('SELECT i.id,i.deleted_at,i.current_revision FROM source_refs s JOIN items i ON i.id=s.item_id WHERE s.source_key=? AND s.realm_key=?').get(sourceKey, realm); return r ? { itemId: String(r.id), deleted: r.deleted_at !== null, revisionId: r.current_revision === null ? null : String(r.current_revision) } : null; }
+    importedRevision(itemId, bundleHash) { text(itemId, 256); hash(bundleHash); const r = this.db.prepare('SELECT id FROM revisions WHERE item_id=? AND bundle_hash=?').get(itemId, bundleHash); if (!r)
+        throw new StoreError('unavailable'); return String(r.id); }
+    revisionMarkdown(revisionId) { text(revisionId, 256); return foundation.markdownFor(this.db, revisionId); }
+    planJungleNote(input) { text(input.itemId, 256); text(input.revisionId, 256); return jungle.planJungleNote(this.db, input); }
+    applyJungleNote(input) { text(input.itemId, 256); text(input.revisionId, 256); return this.transaction(() => jungle.applyJungleNote(this.db, input)); }
+    listChanges(after = 0, limit = 500) { return foundation.listChanges(this.db, after, limit); }
+    publicProjection() { return foundation.publicProjection(this.db); }
     lookupImportReceipt(namespace, sourceKey, sourceHash) {
         text(namespace, 256);
         text(sourceKey, 8192);
@@ -366,10 +425,14 @@ export class LibraryStore {
             if (source && source.kind !== input.kind)
                 throw new StoreError('invalid-input');
             if (!source) {
-                const itemId = randomUUID(), sourceId = randomUUID();
-                this.db.prepare('INSERT INTO items(id,kind,created_at) VALUES(?,?,?)').run(itemId, input.kind, now());
-                this.db.prepare('INSERT INTO source_refs(id,item_id,source_key,realm_key,locator) VALUES(?,?,?,?,?)').run(sourceId, itemId, input.sourceKey, realm, input.locator);
-                source = { id: sourceId, item_id: itemId };
+                // Devices of one library agree on the id; outsiders cannot derive it from a URL.
+                const library = String(this.db.prepare('SELECT uuid FROM library_info WHERE id=1').get()?.uuid);
+                const itemId = digest(JSON.stringify(['item-v1', library, realm, input.sourceKey]));
+                if (this.db.prepare('SELECT 1 FROM items WHERE id=?').get(itemId))
+                    throw new StoreError('integrity');
+                foundation.mutate(this.db, 'item', itemId, 'created', { kind: input.kind, sourceKey: input.sourceKey, realm, locator: input.locator, createdAt: now() });
+                foundation.syncUris(this.db, itemId);
+                source = { id: foundation.sourceRefId(itemId), item_id: itemId };
             }
             const active = this.db.prepare("SELECT id FROM jobs WHERE item_id=? AND state IN ('queued','running','delayed','cleanup-pending') ORDER BY created_at LIMIT 1").get(source.item_id);
             const jobId = active ? String(active.id) : randomUUID();
@@ -593,8 +656,9 @@ export class LibraryStore {
                     throw new StoreError('integrity');
             }
             const existing = this.db.prepare('SELECT id,payload_hash FROM revisions WHERE item_id=? AND bundle_hash=?').get(input.itemId, input.bundleHash);
-            const item = this.db.prepare('SELECT current_revision FROM items WHERE id=?').get(input.itemId);
-            const revisionId = existing ? String(existing.id) : randomUUID();
+            const item = this.db.prepare('SELECT current_revision,title FROM items WHERE id=?').get(input.itemId);
+            // Content-addressed: the same capture on two devices is the same revision object.
+            const revisionId = existing ? String(existing.id) : digest(JSON.stringify(['revision-v1', input.itemId, input.bundleHash]));
             if (!existing) {
                 this.db.prepare('INSERT INTO revisions(id,item_id,parent_id,bundle_hash,extractor_name,extractor_version,captured_at,status,warnings_json,payload_hash,metadata_warnings_json) VALUES(?,?,?,?,?,?,?,?,?,?,?)').run(revisionId, input.itemId, item.current_revision ?? null, input.bundleHash, input.extractor.name, input.extractor.version, now(), input.status, JSON.stringify(input.warnings ?? []), payloadHash, JSON.stringify(metadataWarnings));
                 for (const [ordinal, asset] of input.assets.entries()) {
@@ -617,33 +681,30 @@ export class LibraryStore {
                     throw new StoreError('integrity');
             }
             if (item.current_revision !== revisionId) {
-                this.db.prepare('UPDATE items SET current_revision=?,title=? WHERE id=?').run(revisionId, input.title ?? '', input.itemId);
-                this.db.prepare('DELETE FROM readable_fts WHERE item_id=?').run(input.itemId);
+                foundation.mutate(this.db, 'item', input.itemId, 'currentRevision', revisionId);
+                if (item.title !== (input.title ?? ''))
+                    foundation.mutate(this.db, 'item', input.itemId, 'title', input.title ?? '');
                 const stored = this.db.prepare("SELECT markdown FROM representations WHERE revision_id=? AND kind='markdown'").get(revisionId);
-                this.db.prepare('INSERT INTO readable_fts(item_id,revision_id,title,markdown) VALUES(?,?,?,?)').run(input.itemId, revisionId, input.title ?? '', String(stored.markdown));
+                indexReadable(this.db, input.itemId, revisionId, input.title ?? '', String(stored.markdown));
+                foundation.syncUris(this.db, input.itemId);
                 this.bumpEpoch();
             }
             if (imported) {
                 const receipt = this.lookupImportReceipt(imported.namespace, imported.sourceKey, imported.sourceHash);
                 if (receipt && receipt.itemId !== input.itemId)
                     throw new StoreError('integrity');
-                for (const note of imported.notes) {
-                    const id = digest(JSON.stringify(['import-note-v1', imported.namespace, imported.sourceKey, note.id]));
-                    const prior = this.db.prepare('SELECT item_id,body FROM annotations WHERE id=?').get(id);
-                    if (prior && (prior.item_id !== input.itemId || prior.body !== note.body))
-                        throw new StoreError('integrity');
-                    if (!prior)
-                        this.db.prepare('INSERT INTO annotations VALUES(?,?,?,?,?,?)').run(id, input.itemId, revisionId, JSON.stringify({ kind: 'imported-note', sourceId: note.id }), note.body, now());
-                }
+                for (const note of imported.notes)
+                    foundation.importNote(this.db, { itemId: input.itemId, revisionId, namespace: imported.namespace, sourceKey: imported.sourceKey, noteId: note.id, body: note.body });
                 const state = JSON.stringify({ ...imported.readingState, sourcePrivacy: imported.privacy });
                 const prior = this.db.prepare('SELECT state_json FROM reading_state WHERE item_id=?').get(input.itemId);
                 // Existing reading choices remain authoritative; import never overwrites them.
                 if (!prior)
-                    this.db.prepare('INSERT INTO reading_state VALUES(?,?,?)').run(input.itemId, state, now());
+                    foundation.setReadingState(this.db, input.itemId, JSON.parse(state));
                 else {
                     const existing = JSON.parse(String(prior.state_json));
                     const sourcePrivacy = existing.sourcePrivacy === 'published' && imported.privacy === 'published' ? 'published' : 'private';
-                    this.db.prepare('UPDATE reading_state SET state_json=?,updated_at=? WHERE item_id=?').run(JSON.stringify({ ...existing, sourcePrivacy }), now(), input.itemId);
+                    if (sourcePrivacy !== existing.sourcePrivacy)
+                        foundation.setReadingState(this.db, input.itemId, { ...existing, sourcePrivacy });
                 }
                 this.db.prepare('INSERT OR IGNORE INTO import_receipts VALUES(?,?,?,?,?,?)').run(imported.namespace, imported.sourceKey, imported.sourceHash, imported.importerVersion, input.itemId, 'imported');
             }
@@ -675,13 +736,14 @@ export class LibraryStore {
         const path = confinedFile(this.root, join(this.root, reference.relativePath));
         return readVerifiedFile(path, reference.sha256, reference.bytes);
     }
-    search(query, count = 20) { text(query, 4096); integer(count, 100); const literal = '"' + query.replaceAll('"', '""') + '"'; return this.db.prepare('SELECT i.id itemId,i.title,i.current_revision revisionId FROM readable_fts f JOIN items i ON i.id=f.item_id WHERE readable_fts MATCH ? AND i.deleted_at IS NULL AND i.current_revision=f.revision_id ORDER BY rank,i.id LIMIT ?').all(literal, count); }
+    search(query, count = 20) { text(query, 4096); integer(count, 100); return lexicalSearch(this.db, query, count).map(({ itemId, title, revisionId }) => ({ itemId, title, revisionId })); }
     delete(itemId) {
         text(itemId, 256);
         this.transaction(() => {
-            const row = this.db.prepare('UPDATE items SET deleted_at=? WHERE id=? AND deleted_at IS NULL').run(now(), itemId);
-            if (row.changes) {
-                this.db.prepare('DELETE FROM readable_fts WHERE item_id=?').run(itemId);
+            const row = this.db.prepare('SELECT 1 FROM items WHERE id=? AND deleted_at IS NULL').get(itemId);
+            if (row) {
+                foundation.mutate(this.db, 'item', itemId, 'deleted', now());
+                unindexReadable(this.db, itemId);
                 this.db.prepare("UPDATE jobs SET cancel_requested=1,state=CASE WHEN state IN ('queued','delayed','needs-auth','needs-permission','unsupported','failed') THEN 'cancelled' ELSE state END WHERE item_id=? AND state NOT IN ('succeeded','failed','cancelled')").run(itemId);
                 this.bumpEpoch();
             }
@@ -721,6 +783,27 @@ export class LibraryStore {
             return callback(references);
         });
     }
+    /** Runtime GC pins: recorded model artifacts and embedding helpers of active or building generations. */
+    runtimeReferences() {
+        const modelArtifacts = this.db.prepare('SELECT id,manifest_json FROM model_artifacts ORDER BY id').all().map(r => ({ id: String(r.id), manifest: String(r.manifest_json) }));
+        const helpers = new Set();
+        let unmapped = 0;
+        for (const row of this.db.prepare("SELECT DISTINCT s.identity_json FROM embedding_spaces s JOIN index_generations g ON g.fingerprint=s.fingerprint WHERE g.state='building' OR g.id IN (SELECT generation_id FROM active_indexes)").all()) {
+            let identity;
+            try {
+                identity = JSON.parse(String(row.identity_json));
+            }
+            catch {
+                throw new StoreError('integrity');
+            }
+            const sha = identity?.helperSha256;
+            if (typeof sha === 'string' && /^[a-f0-9]{64}$/.test(sha))
+                helpers.add(sha);
+            else
+                unmapped++;
+        }
+        return { modelArtifacts, embeddingHelpers: [...helpers].sort(), unmappedSpaces: unmapped };
+    }
     /** GC must honor both durable staging pins and active backup fences. */
     pendingCleanupCount() { return Number(this.db.prepare("SELECT (SELECT count(*) FROM attempts WHERE cleanup='pending')+(SELECT count(*) FROM index_attempts WHERE cleanup='pending') AS n").get()?.n); }
     hasGcFence() { return Number(this.db.prepare("SELECT (SELECT count(*) FROM staging_pins)+(SELECT count(*) FROM backup_fences WHERE state='active')+(SELECT count(*) FROM index_attempts WHERE cleanup='pending')+(SELECT count(*) FROM index_jobs WHERE state IN ('running','cleanup-pending')) n").get()?.n) > 0; }

package/dist/src/worker/runtime-gc.d.ts

@@ -0,0 +1,30 @@
+import { type LibraryStore } from '../store/index.js';
+export type RuntimeKind = 'capture' | 'model' | 'worker';
+export interface RuntimeEntry {
+    kind: RuntimeKind;
+    name: string;
+    bytes: number;
+}
+export interface RuntimeKept {
+    kind: RuntimeKind;
+    name: string;
+    reason: 'referenced' | 'in-use' | 'symlink' | 'foreign' | 'catalog-unavailable' | 'current-missing';
+}
+export interface RuntimeGcReport {
+    dryRun: boolean;
+    removed: RuntimeEntry[];
+    kept: RuntimeKept[];
+    bytes: number;
+}
+/** What the installed Sponge can load. `models: null` (catalog unavailable) keeps every model directory. */
+export interface RuntimeGcOptions {
+    dryRun?: boolean;
+    captureIds: readonly string[];
+    models: {
+        fingerprints: readonly string[];
+    } | null;
+}
+/** Remove only superseded capture runtimes, model packages and settled worker journals.
+ * Applying holds worker custody, so no worker, capture, import verification, index run or query
+ * can start or be running; each model directory is additionally taken under its setup lock. */
+export declare function collectRuntimes(store: LibraryStore, options: RuntimeGcOptions): Promise<RuntimeGcReport>;