@hraness/sponge 0.2.3 → 0.2.5

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>;

package/dist/src/worker/runtime-gc.js

@@ -0,0 +1,296 @@
+import { constants } from 'node:fs';
+import { lstat, readdir, realpath, rename, rm, link, unlink, open } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { StoreError } from '../store/index.js';
+import { modelSetupPlan } from '../models/artifacts.js';
+import { acquireWorkerCustody } from './custody.js';
+import { readJournal, writeJournal, syncDir } from './journal.js';
+import { processIdentity, identityAlive } from './identity.js';
+const uuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const patterns = { capture: /^capture-[a-z0-9][a-z0-9.-]{0,99}$/, model: /^[a-f0-9]{64}$/, worker: uuid };
+const helperNames = ['sponge-speech', 'sponge-embedding'];
+const trash = /^\.gc-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+// A worker writes owner.json just after creating its directory; a young unreadable directory may be mid-acquisition.
+const youngMs = 10 * 60 * 1000;
+const integrity = () => new StoreError('integrity');
+const missing = (error) => error.code === 'ENOENT';
+/** Disk blocks removing one tree frees, never following links: each inode once, and a file only when all of its
+ * hard links are inside the tree (a model artifact shared with a kept package frees nothing). */
+async function diskBytes(root) {
+    let total = 0;
+    const files = new Map();
+    const visit = async (path) => {
+        let stat;
+        try {
+            stat = await lstat(path);
+        }
+        catch (error) {
+            if (missing(error))
+                return;
+            throw error;
+        }
+        if (stat.isDirectory()) {
+            total += stat.blocks * 512;
+            for (const name of await readdir(path))
+                await visit(join(path, name));
+            return;
+        }
+        const key = `${stat.dev}:${stat.ino}`, file = files.get(key);
+        if (file)
+            file.seen++;
+        else
+            files.set(key, { blocks: stat.blocks, nlink: stat.nlink, seen: 1 });
+    };
+    await visit(root);
+    for (const file of files.values())
+        if (file.seen >= file.nlink)
+            total += file.blocks * 512;
+    return total;
+}
+/** The expected parent: a real, private, owned directory at its canonical path, or absent. */
+async function parent(path) {
+    let stat;
+    try {
+        stat = await lstat(path);
+    }
+    catch (error) {
+        if (missing(error))
+            return null;
+        throw error;
+    }
+    if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0 || await realpath(path) !== path)
+        throw integrity();
+    return path;
+}
+async function exists(path) { try {
+    await lstat(path);
+    return true;
+}
+catch (error) {
+    if (missing(error))
+        return false;
+    throw error;
+} }
+async function fileSha256(path, maxBytes) {
+    let file;
+    try {
+        file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch {
+        return null;
+    }
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size > maxBytes)
+            return null;
+        return createHash('sha256').update(await file.readFile()).digest('hex');
+    }
+    finally {
+        await file.close();
+    }
+}
+/** Direct children whose names match the kind's pattern; symlinks and foreign entries are reported, never followed. */
+async function children(kind, dir, kept) {
+    if (!dir)
+        return [];
+    const result = [];
+    for (const name of (await readdir(dir)).sort()) {
+        if (!patterns[kind].test(name) && !trash.test(name))
+            continue;
+        const stat = await lstat(join(dir, name));
+        if (stat.isSymbolicLink()) {
+            kept.push({ kind, name, reason: 'symlink' });
+            continue;
+        }
+        if (!stat.isDirectory() || stat.uid !== process.getuid?.()) {
+            kept.push({ kind, name, reason: 'foreign' });
+            continue;
+        }
+        result.push({ kind, dir, name });
+    }
+    return result;
+}
+/** Rename first so a swapped-in link is caught before recursive removal; rm never follows links inside. */
+async function remove(candidate) {
+    const path = join(candidate.dir, candidate.name), moved = join(candidate.dir, `.gc-${randomUUID()}`);
+    const before = await lstat(path);
+    if (before.isSymbolicLink() || !before.isDirectory())
+        return false;
+    await rename(path, moved);
+    const after = await lstat(moved);
+    if (after.isSymbolicLink() || !after.isDirectory() || after.ino !== before.ino || after.dev !== before.dev) {
+        await rename(moved, path);
+        return false;
+    }
+    await syncDir(candidate.dir);
+    await rm(moved, { recursive: true });
+    await syncDir(candidate.dir);
+    return true;
+}
+async function workerInUse(dir, name) {
+    try {
+        const owner = await readJournal(join(dir, name, 'owner.json'));
+        if (owner?.schemaVersion !== 1 || owner.incarnation !== name || !owner.identity)
+            return true;
+        return await identityAlive(owner.identity);
+    }
+    catch (error) {
+        if (!missing(error))
+            return true;
+        try {
+            return Date.now() - (await lstat(join(dir, name))).mtimeMs < youngMs;
+        }
+        catch {
+            return true;
+        }
+    }
+}
+/** 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 async function collectRuntimes(store, options) {
+    const dryRun = options.dryRun === true, base = await realpath(store.root), runtime = await parent(join(base, 'runtime'));
+    if (store.ownerSnapshot())
+        throw new StoreError('owner-busy');
+    if (store.pendingCleanupCount())
+        throw Object.assign(Error('cleanup-required'), { code: 'cleanup-required' });
+    const lockPath = join(base, 'runtime', 'worker.lock');
+    // Checked first so a refused collection leaves no custody journal; acquisition stays the authority.
+    if (await exists(lockPath))
+        throw new StoreError('owner-busy');
+    const custody = dryRun || !runtime ? undefined : await acquireWorkerCustody(base);
+    const removed = [], kept = [];
+    try {
+        if (!runtime)
+            return { dryRun, removed, kept, bytes: 0 };
+        // Recheck under custody: an owner that appeared before our lock still blocks.
+        if (store.ownerSnapshot())
+            throw new StoreError('owner-busy');
+        if (store.pendingCleanupCount())
+            throw Object.assign(Error('cleanup-required'), { code: 'cleanup-required' });
+        const dirs = { capture: await parent(join(runtime, 'capture')), model: await parent(join(runtime, 'models')), worker: await parent(join(runtime, 'workers')) };
+        const references = store.runtimeReferences(), models = options.models;
+        const modelKeep = new Set(models?.fingerprints ?? []);
+        for (const artifact of references.modelArtifacts) {
+            if (patterns.model.test(artifact.id))
+                modelKeep.add(artifact.id);
+            try {
+                modelKeep.add(modelSetupPlan(JSON.parse(artifact.manifest)).fingerprint);
+            }
+            catch { /* An unparsable row still pins its id. */ }
+        }
+        // A generation's helper is satisfied only by an installed kept package, never by an uninstalled catalog entry.
+        const helpers = new Set(references.embeddingHelpers), installed = new Set();
+        for (const fp of modelKeep) {
+            if (!dirs.model || !await exists(join(dirs.model, fp)))
+                continue;
+            for (const helper of helperNames) {
+                if (await exists(join(dirs.model, fp, helper)))
+                    installed.add(helper);
+            }
+            helpers.delete(await fileSha256(join(dirs.model, fp, 'sponge-embedding'), 32 * 1024 ** 2) ?? '');
+        }
+        const take = async (candidate) => {
+            const bytes = await diskBytes(join(candidate.dir, candidate.name));
+            if (dryRun || await remove(candidate))
+                removed.push({ kind: candidate.kind, name: candidate.name, bytes });
+            else
+                kept.push({ kind: candidate.kind, name: candidate.name, reason: 'symlink' });
+        };
+        for (const candidate of await children('capture', dirs.capture, kept)) {
+            if (options.captureIds.includes(candidate.name))
+                kept.push({ kind: 'capture', name: candidate.name, reason: 'referenced' });
+            else
+                await take(candidate);
+        }
+        for (const candidate of await children('model', dirs.model, kept)) {
+            const { name, dir } = candidate;
+            if (trash.test(name)) {
+                await take(candidate);
+                continue;
+            }
+            if (!models) {
+                kept.push({ kind: 'model', name, reason: 'catalog-unavailable' });
+                continue;
+            }
+            if (modelKeep.has(name)) {
+                kept.push({ kind: 'model', name, reason: 'referenced' });
+                continue;
+            }
+            const helper = join(dir, name, 'sponge-embedding');
+            if ((references.unmappedSpaces && await exists(helper)) || helpers.size && helpers.has(await fileSha256(helper, 32 * 1024 ** 2) ?? '')) {
+                kept.push({ kind: 'model', name, reason: 'referenced' });
+                continue;
+            }
+            // Until this Sponge's package of a kind is installed, older packages of that kind are its only local copy.
+            let missingKind = false;
+            for (const helper of helperNames)
+                if (!installed.has(helper) && await exists(join(dir, name, helper)))
+                    missingKind = true;
+            if (missingKind) {
+                kept.push({ kind: 'model', name, reason: 'current-missing' });
+                continue;
+            }
+            const lock = join(dir, `.${name}.lock`);
+            if (await exists(lock) || await exists(join(dir, `.${name}.recovery-lock`))) {
+                kept.push({ kind: 'model', name, reason: 'in-use' });
+                continue;
+            }
+            if (dryRun) {
+                await take(candidate);
+                continue;
+            }
+            // The model setup lock: a concurrent setup or recovery of this fingerprint sees owner-busy.
+            const identity = await processIdentity(process.pid);
+            if (!identity)
+                throw integrity();
+            const incarnation = randomUUID(), ownerFile = join(dir, `.model-owner-${incarnation}.json`);
+            await writeJournal(ownerFile, { schemaVersion: 1, incarnation, fingerprint: name, stage: '.model-install-' + incarnation, identity });
+            try {
+                try {
+                    await link(ownerFile, lock);
+                }
+                catch (error) {
+                    if (error.code === 'EEXIST') {
+                        kept.push({ kind: 'model', name, reason: 'in-use' });
+                        continue;
+                    }
+                    throw error;
+                }
+                try {
+                    await syncDir(dir);
+                    await take(candidate);
+                }
+                finally {
+                    await unlink(lock);
+                }
+            }
+            finally {
+                await unlink(ownerFile);
+                await syncDir(dir);
+            }
+        }
+        for (const candidate of await children('worker', dirs.worker, kept)) {
+            const { name, dir } = candidate;
+            if (name === custody?.incarnation)
+                continue;
+            if (!trash.test(name) && await workerInUse(dir, name)) {
+                kept.push({ kind: 'worker', name, reason: 'in-use' });
+                continue;
+            }
+            await take(candidate);
+        }
+        return { dryRun, removed, kept, bytes: removed.reduce((n, e) => n + e.bytes, 0) };
+    }
+    finally {
+        if (custody) {
+            await custody.release();
+            try {
+                await rm(custody.directory, { recursive: true });
+                await syncDir(join(base, 'runtime', 'workers'));
+            }
+            catch { /* The next collection removes this settled journal. */ }
+        }
+    }
+}

package/native/runtime-manifest.json

@@ -27,14 +27,14 @@
     }
   ],
   "build": {
-    "asrSourceSha256": "d0047cce6c54d23aea9921b6de0a94c40853191fca65a3709bbc83db20a46187",
+    "asrSourceSha256": "1cb743b39e76666adc814306e06c02ae1c59ca3b784a6bb8f186270387f59ee9",
     "clangVersion": "Apple clang version 21.0.0 (clang-2100.1.1.101)",
-    "embeddingSourceSha256": "7849bd7a82f90daac544f342002f07e624c0486ea452f2d8437a2dbdeca02bc1",
+    "embeddingSourceSha256": "7e499ea896cd9805daca51bb6489c0856acad4edbaf7e76b07ff1e63d5766457",
     "swiftVersion": "Apple Swift version 6.3.3 (swiftlang-6.3.3.1.3 clang-2100.1.1.101)"
   },
   "minimumMacOS": "26.0",
-  "packageVersion": "0.2.3",
+  "packageVersion": "0.2.5",
   "platform": "darwin",
   "schemaVersion": 1,
-  "sourceCommit": "8a81581be84426c678295f8ec928bf7d306d0cb0"
+  "sourceCommit": "e69bea289723e18288322257ffff269b7fe16bac"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/sponge",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "A local library for captured articles and verified offline assets.",
   "repository": {
     "type": "git",