@hraness/sponge 0.1.0 → 0.2.0

package/dist/src/portability/backup.js

@@ -0,0 +1,138 @@
+import { constants, openSync, closeSync, fstatSync, fsyncSync, unlinkSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { openLibrary } from '../store/index.js';
+import { safeDirectory } from '../store/files.js';
+import { StoreError } from '../store/types.js';
+import { inspectDatabase, neutralizeRestoredDatabase } from './database.js';
+import { bounded, exact, fileDescriptor, invalid, maximumDatabaseBytes, maximumEntries, maximumTotalBytes, openRead, readExact, transfer, writeAll, describe, newDirectory, discardOwned, syncDirectory, writePrivateExclusive } from './files.js';
+const magic = Buffer.from('SPONGE-BACKUP-1\n');
+const maxManifestBytes = 32 * 1024 ** 2;
+function manifest(value) {
+    const r = exact(value, ['format', 'version', 'schemaVersion', 'libraryId', 'revisionEpoch', 'files']);
+    if (r.format !== 'sponge-backup' || r.version !== 1 || typeof r.libraryId !== 'string' || r.libraryId.length > 256 || !Array.isArray(r.files) || r.files.length < 1 || r.files.length > maximumEntries + 1)
+        invalid();
+    const files = r.files.map(fileDescriptor);
+    if (files[0]?.path !== 'library.sqlite' || files.slice(1).some(f => f.path === 'library.sqlite') || new Set(files.map(f => f.path)).size !== files.length)
+        invalid();
+    return { format: 'sponge-backup', version: 1, schemaVersion: bounded(r.schemaVersion, Number.MAX_SAFE_INTEGER), libraryId: r.libraryId, revisionEpoch: bounded(r.revisionEpoch, Number.MAX_SAFE_INTEGER), files };
+}
+function sameSnapshot(info, m) {
+    if (info.schemaVersion !== m.schemaVersion || info.libraryId !== m.libraryId || info.revisionEpoch !== m.revisionEpoch)
+        invalid();
+    const expected = info.blobs.map(b => ({ path: b.relativePath, bytes: b.bytes, sha256: b.sha256 }));
+    if (JSON.stringify(expected) !== JSON.stringify(m.files.slice(1)))
+        invalid();
+}
+export async function backupLibrary(store, output) {
+    if (resolve(output) !== output)
+        throw new StoreError('invalid-input');
+    safeDirectory(dirname(output));
+    const snapshot = await store.createBackupSnapshot();
+    let fd, created = false;
+    try {
+        const info = inspectDatabase(snapshot.path);
+        const files = [describe(snapshot.path, 'library.sqlite', maximumDatabaseBytes), ...info.blobs.map(b => ({ path: b.relativePath, bytes: b.bytes, sha256: b.sha256 }))];
+        const m = { format: 'sponge-backup', version: 1, schemaVersion: info.schemaVersion, libraryId: info.libraryId, revisionEpoch: info.revisionEpoch, files };
+        const json = Buffer.from(JSON.stringify(m));
+        if (json.length > maxManifestBytes || files.reduce((n, f) => n + f.bytes, json.length + magic.length + 4) > maximumTotalBytes)
+            throw new StoreError('limit-exceeded');
+        fd = openSync(output, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+        created = true;
+        writeAll(fd, magic);
+        const length = Buffer.alloc(4);
+        length.writeUInt32BE(json.length);
+        writeAll(fd, length);
+        writeAll(fd, json);
+        for (const file of files) {
+            const input = openRead(file.path === 'library.sqlite' ? snapshot.path : join(store.root, file.path));
+            try {
+                if (fstatSync(input).size !== file.bytes || transfer(input, file.bytes, fd) !== file.sha256)
+                    invalid();
+            }
+            finally {
+                closeSync(input);
+            }
+        }
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = undefined;
+        syncDirectory(dirname(output));
+        const result = describe(output, 'archive', maximumTotalBytes);
+        return { output, sha256: result.sha256, bytes: result.bytes, itemsSnapshotEpoch: info.revisionEpoch };
+    }
+    catch (error) {
+        if (fd !== undefined) {
+            closeSync(fd);
+            fd = undefined;
+        }
+        if (created)
+            unlinkSync(output);
+        throw error;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+        try {
+            unlinkSync(snapshot.path);
+        }
+        finally {
+            store.finishBackup(snapshot.id);
+        }
+    }
+}
+/** Versioned length-framed archive: no tar links, executable hooks or path extraction. */
+export async function restoreLibrary(input, into) {
+    const fd = openRead(input);
+    let target;
+    try {
+        const size = bounded(fstatSync(fd).size, maximumTotalBytes);
+        if (size < magic.length + 4 || !readExact(fd, magic.length).equals(magic))
+            invalid();
+        const length = bounded(readExact(fd, 4).readUInt32BE(), maxManifestBytes);
+        if (!length)
+            invalid();
+        let parsed;
+        try {
+            parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(readExact(fd, length)));
+        }
+        catch {
+            invalid();
+        }
+        const m = manifest(parsed);
+        if (m.files.reduce((n, f) => n + f.bytes, magic.length + 4 + length) !== size)
+            invalid();
+        target = newDirectory(into);
+        for (const file of m.files) {
+            const path = join(target.root, file.path);
+            safeDirectory(dirname(path), true);
+            const out = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+            try {
+                if (transfer(fd, file.bytes, out) !== file.sha256)
+                    invalid();
+                fsyncSync(out);
+                syncDirectory(dirname(path));
+            }
+            finally {
+                closeSync(out);
+            }
+        }
+        sameSnapshot(inspectDatabase(join(into, 'library.sqlite')), m);
+        const state = neutralizeRestoredDatabase(join(into, 'library.sqlite'));
+        writePrivateExclusive(join(into, '.sponge-library'), 'sponge-library-v1\n');
+        // Mark bindings as deliberately absent. This never installs runtime/auth/model files.
+        safeDirectory(join(into, 'runtime'), true);
+        writePrivateExclusive(join(into, 'runtime', 'restore.json'), JSON.stringify({ schemaVersion: 1, libraryId: m.libraryId, ownerIncarnation: state.incarnation, connections: 'unresolved', heldJobs: state.heldJobs }) + '\n');
+        const store = await openLibrary(into);
+        store.close();
+        syncDirectory(into);
+        return { root: into, libraryId: m.libraryId, ...state };
+    }
+    catch (error) {
+        if (target)
+            discardOwned(target);
+        throw error;
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/dist/src/portability/database.d.ts

@@ -0,0 +1,14 @@
+import { type BlobReference } from '../store/types.js';
+export interface SnapshotInfo {
+    schemaVersion: number;
+    libraryId: string;
+    revisionEpoch: number;
+    blobs: BlobReference[];
+}
+/** Compare executable schema before any restored SQL mutation, not just claimed migration hashes. */
+export declare function inspectDatabase(path: string): SnapshotInfo;
+/** Only a new private restored database may be passed here. Source backup is immutable. */
+export declare function neutralizeRestoredDatabase(path: string): {
+    incarnation: string;
+    heldJobs: number;
+};

package/dist/src/portability/database.js

@@ -0,0 +1,78 @@
+import { DatabaseSync } from 'node:sqlite';
+import { randomUUID } from 'node:crypto';
+import { libraryMigrations } from '../store/index.js';
+import { digest, regularFile } from '../store/files.js';
+import { StoreError } from '../store/types.js';
+import { blobPath, bounded, digestString, invalid, maximumBlobBytes, maximumEntries } from './files.js';
+function schema(db) { return JSON.stringify(db.prepare("SELECT type,name,tbl_name,sql FROM sqlite_schema ORDER BY type,name").all()); }
+/** Compare executable schema before any restored SQL mutation, not just claimed migration hashes. */
+export function inspectDatabase(path) {
+    regularFile(path);
+    const db = new DatabaseSync(path, { readOnly: true });
+    const expected = new DatabaseSync(':memory:');
+    try {
+        db.exec('PRAGMA trusted_schema=OFF');
+        const version = bounded(db.prepare('PRAGMA user_version').get()?.user_version, Number.MAX_SAFE_INTEGER);
+        if (version > libraryMigrations.length)
+            throw new StoreError('schema-newer');
+        if (version < 1)
+            invalid();
+        for (let i = 0; i < version; i++) {
+            expected.exec(libraryMigrations[i]);
+            if (db.prepare('SELECT checksum FROM schema_migrations WHERE version=?').get(i + 1)?.checksum !== digest(libraryMigrations[i]))
+                invalid();
+        }
+        if (schema(db) !== schema(expected))
+            invalid();
+        if (db.prepare('SELECT count(*) n FROM schema_migrations').get()?.n !== version)
+            invalid();
+        if (db.prepare('PRAGMA quick_check').get()?.quick_check !== 'ok' || db.prepare('PRAGMA foreign_key_check').all().length)
+            invalid();
+        const info = db.prepare('SELECT uuid,schema_version,revision_epoch FROM library_info WHERE id=1').get();
+        if (!info || typeof info.uuid !== 'string' || info.uuid.length > 256 || info.schema_version !== version)
+            invalid();
+        const count = Number(db.prepare('SELECT count(*) n FROM assets').get()?.n);
+        if (count > maximumEntries)
+            throw new StoreError('limit-exceeded');
+        const blobs = db.prepare('SELECT sha256,bytes,relative_path FROM assets ORDER BY sha256').all().map(row => { const sha256 = digestString(row.sha256); if (row.relative_path !== blobPath(sha256))
+            invalid(); return { sha256, bytes: bounded(row.bytes, maximumBlobBytes), relativePath: String(row.relative_path) }; });
+        for (const row of db.prepare('SELECT markdown,sha256,bytes FROM representations WHERE markdown IS NOT NULL').iterate()) {
+            if (typeof row.markdown !== 'string' || digest(row.markdown) !== row.sha256 || Buffer.byteLength(row.markdown) !== row.bytes)
+                invalid();
+        }
+        return { schemaVersion: version, libraryId: info.uuid, revisionEpoch: bounded(info.revision_epoch, Number.MAX_SAFE_INTEGER), blobs };
+    }
+    finally {
+        expected.close();
+        db.close();
+    }
+}
+/** Only a new private restored database may be passed here. Source backup is immutable. */
+export function neutralizeRestoredDatabase(path) {
+    const inspected = inspectDatabase(path);
+    const db = new DatabaseSync(path);
+    const incarnation = randomUUID();
+    try {
+        db.exec('PRAGMA trusted_schema=OFF; PRAGMA foreign_keys=ON; BEGIN IMMEDIATE');
+        // Every nonterminal intent is retained but requires an explicit retry after restore.
+        const held = db.prepare(`UPDATE jobs SET state='needs-permission',reason='restore-reconciliation-required'${inspected.schemaVersion >= 2 ? ",retryable=0" : ""} WHERE state NOT IN ('succeeded','failed','cancelled','unsupported')`).run();
+        db.prepare("UPDATE attempts SET stage='restored-unexecuted',cleanup='settled',finished_at=COALESCE(finished_at,?) WHERE cleanup='pending' OR finished_at IS NULL").run(new Date().toISOString());
+        db.exec("DELETE FROM staging_pins; DELETE FROM backup_fences; UPDATE worker_owner SET incarnation=NULL,fence=fence+1; UPDATE model_artifacts SET available=0;");
+        if (inspected.schemaVersion >= 4) {
+            db.exec("UPDATE index_jobs SET state='failed',reason='restore-reconciliation-required' WHERE state NOT IN ('succeeded','failed','cancelled')");
+            db.prepare("UPDATE index_attempts SET stage='restored-unexecuted',cleanup='settled',finished_at=COALESCE(finished_at,?) WHERE cleanup='pending' OR finished_at IS NULL").run(new Date().toISOString());
+        }
+        db.exec('COMMIT; PRAGMA journal_mode=DELETE');
+        return { incarnation, heldJobs: Number(held.changes) };
+    }
+    catch (error) {
+        try {
+            db.exec('ROLLBACK');
+        }
+        catch { }
+        throw error;
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/src/portability/export.d.ts

@@ -0,0 +1,8 @@
+import type { LibraryStore } from '../store/index.js';
+/** Export a fixed revision with hash-named local assets. No network or acquisition. */
+export declare function exportItem(store: LibraryStore, itemId: string, output: string): {
+    output: string;
+    itemId: string;
+    revisionId: string;
+    assets: number;
+};

package/dist/src/portability/export.js

@@ -0,0 +1,36 @@
+import { join } from 'node:path';
+import { StoreError } from '../store/types.js';
+import { safeDirectory } from '../store/files.js';
+import { newDirectory, discardOwned, copyVerified, syncDirectory, blobPath, writePrivateExclusive } from './files.js';
+/** Export a fixed revision with hash-named local assets. No network or acquisition. */
+export function exportItem(store, itemId, output) {
+    const item = store.read(itemId);
+    if (!item)
+        throw new StoreError('invalid-input');
+    const target = newDirectory(output);
+    try {
+        safeDirectory(join(output, 'assets'), true);
+        const known = new Map();
+        for (const asset of item.assets) {
+            if (asset.relativePath !== blobPath(asset.sha256))
+                throw new StoreError('integrity');
+            const path = `assets/${asset.sha256}`;
+            if (!known.has(asset.sha256)) {
+                copyVerified(join(store.root, asset.relativePath), join(output, path), { path, bytes: asset.bytes, sha256: asset.sha256 });
+                known.set(asset.sha256, path);
+            }
+        }
+        const markdown = item.markdown.replace(/sponge-asset:([a-f0-9]{64})/gu, (_all, sha) => { const path = known.get(sha); if (!path)
+            throw new StoreError('integrity'); return path; });
+        writePrivateExclusive(join(output, 'article.md'), markdown);
+        // Metadata can contain private descriptive content; exports stay private and explicit.
+        const notes = store.readAnnotations(itemId);
+        writePrivateExclusive(join(output, 'item.json'), JSON.stringify({ schemaVersion: 1, ...notes, itemId: item.itemId, revisionId: item.revisionId, title: item.title, kind: item.kind, status: item.status, metadata: item.metadata, metadataWarnings: item.metadataWarnings, assets: item.assets.map(a => ({ sha256: a.sha256, bytes: a.bytes, mediaType: a.mediaType, relationship: a.relationship, path: known.get(a.sha256) })) }) + '\n');
+        syncDirectory(output);
+        return { output, itemId, revisionId: item.revisionId, assets: known.size };
+    }
+    catch (error) {
+        discardOwned(target);
+        throw error;
+    }
+}

package/dist/src/portability/files.d.ts

@@ -0,0 +1,33 @@
+import { syncDirectory } from '../store/files.js';
+export declare const maximumTotalBytes: number, maximumDatabaseBytes: number, maximumBlobBytes: number, maximumEntries = 100000;
+export interface FileRecord {
+    path: string;
+    bytes: number;
+    sha256: string;
+}
+export declare function invalid(): never;
+export declare function exact(value: unknown, keys: string[]): Record<string, unknown>;
+export declare function bounded(value: unknown, max: number): number;
+export declare function digestString(value: unknown): string;
+export declare function blobPath(sha: string): string;
+export declare function fileDescriptor(value: unknown): FileRecord;
+export declare function openRead(path: string): number;
+export declare function writeAll(fd: number, bytes: Uint8Array): void;
+export declare function readExact(fd: number, bytes: number): Buffer;
+/** Stream only expected bytes from one descriptor; never allocate a full PDF or archive. */
+export declare function transfer(input: number, bytes: number, output?: number): string;
+export declare function describe(path: string, relativePath: string, maximum: number): FileRecord;
+export declare function copyVerified(source: string, target: string, record: FileRecord): void;
+export declare function newDirectory(path: string): {
+    root: string;
+    device: number;
+    inode: number;
+};
+export declare function discardOwned(value: {
+    root: string;
+    device: number;
+    inode: number;
+}): void;
+export declare function assertEmptyDirectory(path: string): void;
+export { syncDirectory };
+export declare function writePrivateExclusive(path: string, value: string): void;

package/dist/src/portability/files.js

@@ -0,0 +1,78 @@
+import { createHash } from 'node:crypto';
+import { constants, openSync, closeSync, fstatSync, readSync, writeSync, fsyncSync, lstatSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { safeDirectory, regularFile, syncDirectory } from '../store/files.js';
+import { StoreError } from '../store/types.js';
+export const maximumTotalBytes = 16 * 1024 ** 3, maximumDatabaseBytes = 512 * 1024 ** 2, maximumBlobBytes = 512 * 1024 ** 2, maximumEntries = 100_000;
+export function invalid() { throw new StoreError('integrity'); }
+export function exact(value, keys) { if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).sort().join(',') !== keys.sort().join(','))
+    invalid(); return value; }
+export function bounded(value, max) { if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0 || value > max)
+    invalid(); return value; }
+export function digestString(value) { if (typeof value !== 'string' || !/^[a-f0-9]{64}$/u.test(value))
+    invalid(); return value; }
+export function blobPath(sha) { return `blobs/sha256/${sha.slice(0, 2)}/${sha}`; }
+export function fileDescriptor(value) { const r = exact(value, ['path', 'bytes', 'sha256']); const sha256 = digestString(r.sha256); if (r.path !== 'library.sqlite' && r.path !== blobPath(sha256))
+    invalid(); return { path: String(r.path), bytes: bounded(r.bytes, r.path === 'library.sqlite' ? maximumDatabaseBytes : maximumBlobBytes), sha256 }; }
+export function openRead(path) { safeDirectory(dirname(path)); regularFile(path); const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW); const stat = fstatSync(fd); if (!stat.isFile() || stat.nlink !== 1) {
+    closeSync(fd);
+    invalid();
+} return fd; }
+export function writeAll(fd, bytes) { let n = 0; while (n < bytes.length) {
+    const written = writeSync(fd, bytes, n, bytes.length - n);
+    if (!written)
+        invalid();
+    n += written;
+} }
+export function readExact(fd, bytes) { const result = Buffer.alloc(bytes); let n = 0; while (n < bytes) {
+    const read = readSync(fd, result, n, bytes - n, null);
+    if (!read)
+        invalid();
+    n += read;
+} return result; }
+/** Stream only expected bytes from one descriptor; never allocate a full PDF or archive. */
+export function transfer(input, bytes, output) { const hash = createHash('sha256'), buffer = Buffer.alloc(64 * 1024); let n = 0; while (n < bytes) {
+    const read = readSync(input, buffer, 0, Math.min(buffer.length, bytes - n), null);
+    if (!read)
+        invalid();
+    hash.update(buffer.subarray(0, read));
+    if (output !== undefined)
+        writeAll(output, buffer.subarray(0, read));
+    n += read;
+} return hash.digest('hex'); }
+export function describe(path, relativePath, maximum) { const fd = openRead(path); try {
+    const bytes = bounded(fstatSync(fd).size, maximum);
+    return { path: relativePath, bytes, sha256: transfer(fd, bytes) };
+}
+finally {
+    closeSync(fd);
+} }
+export function copyVerified(source, target, record) { const input = openRead(source); let output; try {
+    if (fstatSync(input).size !== record.bytes)
+        invalid();
+    safeDirectory(dirname(target), true);
+    output = openSync(target, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    if (transfer(input, record.bytes, output) !== record.sha256)
+        invalid();
+    fsyncSync(output);
+    syncDirectory(dirname(target));
+}
+finally {
+    closeSync(input);
+    if (output !== undefined)
+        closeSync(output);
+} }
+export function newDirectory(path) { if (resolve(path) !== path)
+    throw new StoreError('invalid-input'); safeDirectory(dirname(path)); mkdirSync(path, { mode: 0o700 }); const stat = lstatSync(path); return { root: path, device: stat.dev, inode: stat.ino }; }
+export function discardOwned(value) { const stat = lstatSync(value.root); if (!stat.isDirectory() || stat.isSymbolicLink() || stat.dev !== value.device || stat.ino !== value.inode)
+    invalid(); rmSync(value.root, { recursive: true }); syncDirectory(dirname(value.root)); }
+export function assertEmptyDirectory(path) { safeDirectory(path); if (readdirSync(path).length)
+    invalid(); }
+export { syncDirectory };
+export function writePrivateExclusive(path, value) { safeDirectory(dirname(path)); const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); try {
+    writeAll(fd, Buffer.from(value));
+    fsyncSync(fd);
+}
+finally {
+    closeSync(fd);
+} syncDirectory(dirname(path)); }

package/dist/src/portability/gc.d.ts

@@ -0,0 +1,21 @@
+import type { LibraryStore } from '../store/index.js';
+import { type FileRecord } from './files.js';
+interface Candidate extends FileRecord {
+    device: number;
+    inode: number;
+    mtimeNs: string;
+}
+export interface GcReport {
+    format: 'sponge-gc';
+    version: 1;
+    libraryId: string;
+    revisionEpoch: number;
+    createdAt: string;
+    candidates: Candidate[];
+}
+export declare function createGcReport(store: LibraryStore): GcReport;
+export declare function applyGcReport(store: LibraryStore, value: unknown): {
+    removed: number;
+    bytes: number;
+};
+export {};

package/dist/src/portability/gc.js

@@ -0,0 +1,66 @@
+import { DatabaseSync } from 'node:sqlite';
+import { lstatSync, readdirSync, unlinkSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { safeDirectory } from '../store/files.js';
+import { StoreError } from '../store/types.js';
+import { blobPath, describe, exact, fileDescriptor, invalid, bounded, maximumBlobBytes, maximumEntries, syncDirectory } from './files.js';
+function libraryId(store) { const db = new DatabaseSync(join(store.root, 'library.sqlite'), { readOnly: true }); try {
+    return String(db.prepare('SELECT uuid FROM library_info WHERE id=1').get()?.uuid);
+}
+finally {
+    db.close();
+} }
+function candidate(root, path) { const absolute = join(root, path); const record = describe(absolute, path, maximumBlobBytes); if (path !== blobPath(record.sha256))
+    invalid(); const stat = lstatSync(absolute, { bigint: true }); return { ...record, device: Number(stat.dev), inode: Number(stat.ino), mtimeNs: String(stat.mtimeNs) }; }
+function parseReport(value) {
+    const r = exact(value, ['format', 'version', 'libraryId', 'revisionEpoch', 'createdAt', 'candidates']);
+    if (r.format !== 'sponge-gc' || r.version !== 1 || typeof r.libraryId !== 'string' || r.libraryId.length > 256 || typeof r.createdAt !== 'string' || !Number.isFinite(Date.parse(r.createdAt)) || !Array.isArray(r.candidates) || r.candidates.length > maximumEntries)
+        invalid();
+    const candidates = r.candidates.map(value => { const row = exact(value, ['path', 'sha256', 'bytes', 'device', 'inode', 'mtimeNs']); const file = fileDescriptor({ path: row.path, sha256: row.sha256, bytes: row.bytes }); if (file.path === 'library.sqlite' || typeof row.mtimeNs !== 'string' || !/^\d{1,30}$/u.test(row.mtimeNs))
+        invalid(); return { ...file, device: bounded(row.device, Number.MAX_SAFE_INTEGER), inode: bounded(row.inode, Number.MAX_SAFE_INTEGER), mtimeNs: row.mtimeNs }; });
+    if (new Set(candidates.map(c => c.path)).size !== candidates.length)
+        invalid();
+    return { format: 'sponge-gc', version: 1, libraryId: r.libraryId, revisionEpoch: bounded(r.revisionEpoch, Number.MAX_SAFE_INTEGER), createdAt: r.createdAt, candidates };
+}
+export function createGcReport(store) {
+    const epoch = store.revisionEpoch;
+    return store.withGcFence(epoch, references => {
+        const known = new Set(references.map(r => r.relativePath)), candidates = [];
+        const root = join(store.root, 'blobs', 'sha256');
+        safeDirectory(root);
+        let count = 0;
+        for (const prefix of readdirSync(root).sort()) {
+            if (!/^[a-f0-9]{2}$/u.test(prefix))
+                invalid();
+            safeDirectory(join(root, prefix));
+            for (const sha of readdirSync(join(root, prefix)).sort()) {
+                if (++count > maximumEntries)
+                    throw new StoreError('limit-exceeded');
+                if (!/^[a-f0-9]{64}$/u.test(sha) || !sha.startsWith(prefix))
+                    invalid();
+                const path = blobPath(sha);
+                if (!known.has(path))
+                    candidates.push(candidate(store.root, path));
+            }
+        }
+        return { format: 'sponge-gc', version: 1, libraryId: libraryId(store), revisionEpoch: epoch, createdAt: new Date().toISOString(), candidates };
+    });
+}
+export function applyGcReport(store, value) {
+    const report = parseReport(value);
+    if (report.libraryId !== libraryId(store) || Date.now() - Date.parse(report.createdAt) > 86400_000 || Date.parse(report.createdAt) > Date.now() + 1000)
+        throw new StoreError('invalid-input');
+    return store.withGcFence(report.revisionEpoch, references => {
+        const known = new Set(references.map(r => r.relativePath));
+        // Validate the entire report before any deletion. Changes invalidate, never broaden it.
+        for (const entry of report.candidates) {
+            if (known.has(entry.path) || JSON.stringify(candidate(store.root, entry.path)) !== JSON.stringify(entry))
+                invalid();
+        }
+        for (const entry of report.candidates) {
+            unlinkSync(join(store.root, entry.path));
+            syncDirectory(dirname(join(store.root, entry.path)));
+        }
+        return { removed: report.candidates.length, bytes: report.candidates.reduce((n, c) => n + c.bytes, 0) };
+    });
+}

package/dist/src/search/extension.d.ts

@@ -0,0 +1,3 @@
+import type { DatabaseSync } from 'node:sqlite';
+/** Database must be opened with allowExtension:true; loading is disabled on every outcome. */
+export declare function initializeVectorExtension(db: DatabaseSync): boolean;

package/dist/src/search/extension.js

@@ -0,0 +1,17 @@
+import { load } from 'sqlite-vec';
+/** Database must be opened with allowExtension:true; loading is disabled on every outcome. */
+export function initializeVectorExtension(db) {
+    try {
+        load(db);
+        return db.prepare('SELECT vec_version() AS version').get()?.version === 'v0.1.9';
+    }
+    catch {
+        return false;
+    }
+    finally {
+        try {
+            db.enableLoadExtension(false);
+        }
+        catch { /* Database created without extension support is already closed to loading. */ }
+    }
+}

package/dist/src/search/hybrid.d.ts

@@ -0,0 +1,39 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { type SearchGeneration, type VectorHit } from './vector.js';
+export interface SearchHit {
+    itemId: string;
+    revisionId: string;
+    title: string;
+    score: number;
+    methods: ('lexical' | 'semantic')[];
+    anchor: {
+        kind: 'document' | 'image';
+        representationId?: string;
+        chunk?: number;
+        assetSha256?: string;
+        page?: number;
+        startMs?: number;
+    };
+}
+export interface SearchResult {
+    hits: SearchHit[];
+    warnings: ('semantic-unavailable' | 'semantic-timeout')[];
+    generation?: SearchGeneration;
+}
+export type QueryEmbedder = (query: string, pin: SearchGeneration, signal: AbortSignal) => Promise<{
+    fingerprint: string;
+    vector: readonly number[];
+}>;
+/** Reciprocal rank fusion after per-channel item collapsing; chunks cannot amplify rank. */
+export declare function fuse(lexicalHits: {
+    itemId: string;
+    revisionId: string;
+    title: string;
+}[], semanticHits: VectorHit[], limit: number): SearchHit[];
+export declare function hybridSearch(db: DatabaseSync, query: string, options?: {
+    profileId?: string;
+    limit?: number;
+    semanticTimeoutMs?: number;
+    embed?: QueryEmbedder;
+    signal?: AbortSignal;
+}): Promise<SearchResult>;