@hraness/sponge 0.2.6 → 0.3.0

package/dist/src/store/index.js

@@ -1,810 +1,3 @@
-import { DatabaseSync, backup } from 'node:sqlite';
-import { chmodSync, closeSync, constants, readFileSync, fstatSync, readdirSync, fsyncSync, linkSync, mkdirSync, openSync, writeFileSync, rmSync, statfsSync, unlinkSync, writeSync } from 'node:fs';
-import { join, dirname, parse } from 'node:path';
-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 } 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 { LibraryStore } from './library.js';
+export { openLibrary, keptSchemaBackups, libraryVersion } from './open.js';
 export * from './types.js';
-const now = () => new Date().toISOString();
-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)
-        throw new StoreError('invalid-input');
-    const root = safeDirectory(path, true);
-    if (root === parse(root).root)
-        throw new StoreError('invalid-input');
-    const marker = join(root, '.sponge-library'), dbPath = confinedFile(root, join(root, 'library.sqlite'));
-    if (pathExists(marker)) {
-        regularFile(marker);
-        verifyFile(marker, digest('sponge-library-v1\n'), Buffer.byteLength('sponge-library-v1\n'));
-    }
-    else if (readdirSync(root).length)
-        throw new StoreError('invalid-input');
-    for (const suffix of ['', '-wal', '-shm'])
-        if (pathExists(dbPath + suffix))
-            regularFile(dbPath + suffix);
-    if (pathExists(dbPath)) {
-        const inspect = new DatabaseSync(dbPath, { readOnly: true });
-        try {
-            if (Number(inspect.prepare('PRAGMA user_version').get()?.user_version) > version)
-                throw new StoreError('schema-newer');
-        }
-        finally {
-            inspect.close();
-        }
-    }
-    chmodSync(root, 0o700);
-    if (!pathExists(marker)) {
-        writeFileSync(marker, 'sponge-library-v1\n', { flag: 'wx', mode: 0o600 });
-        const fd = openSync(marker, constants.O_RDONLY | constants.O_NOFOLLOW);
-        try {
-            fsyncSync(fd);
-        }
-        finally {
-            closeSync(fd);
-        }
-        syncDirectory(root);
-    }
-    for (const part of ['runtime', 'staging', 'blobs', 'blobs/sha256', 'backups']) {
-        const p = safeDirectory(join(root, part), true);
-        chmodSync(p, 0o700);
-    }
-    const db = new DatabaseSync(dbPath, { allowExtension: true });
-    chmodSync(dbPath, 0o600);
-    try {
-        db.exec('PRAGMA foreign_keys=ON; PRAGMA busy_timeout=5000;');
-        const current = Number(db.prepare('PRAGMA user_version').get()?.user_version);
-        if (current > version)
-            throw new StoreError('schema-newer');
-        if (current < version) {
-            const lock = join(root, 'runtime', 'migration.lock');
-            try {
-                mkdirSync(lock, { mode: 0o700 });
-            }
-            catch (error) {
-                if (error.code === 'EEXIST')
-                    throw new StoreError('owner-busy');
-                throw error;
-            }
-            try {
-                // Recheck under the migration lock: another opener may already have migrated.
-                const actual = Number(db.prepare('PRAGMA user_version').get()?.user_version);
-                if (actual > version)
-                    throw new StoreError('schema-newer');
-                if (actual === 0 && db.prepare("SELECT name FROM sqlite_schema WHERE name NOT LIKE 'sqlite_%'").all().length)
-                    throw new StoreError('integrity');
-                for (let prior = 1; prior <= actual; prior++) {
-                    if (db.prepare('SELECT checksum FROM schema_migrations WHERE version=?').get(prior)?.checksum !== digest(migrations[prior - 1]))
-                        throw new StoreError('integrity');
-                }
-                if (actual > 0 && db.prepare('SELECT schema_version FROM library_info WHERE id=1').get()?.schema_version !== actual)
-                    throw new StoreError('integrity');
-                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));
-                    }
-                    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;
-                        }
-                    }
-                }
-                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 {
-                rmSync(lock, { recursive: true });
-                syncDirectory(join(root, 'runtime'));
-            }
-        }
-        for (let applied = 1; applied <= version; applied++)
-            if (db.prepare('SELECT checksum FROM schema_migrations WHERE version=?').get(applied)?.checksum !== digest(migrations[applied - 1]))
-                throw new StoreError('integrity');
-        if (db.prepare('SELECT schema_version FROM library_info WHERE id=1').get()?.schema_version !== version)
-            throw new StoreError('integrity');
-        db.exec('PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;');
-        for (const suffix of ['', '-wal', '-shm'])
-            if (pathExists(dbPath + suffix))
-                chmodSync(dbPath + suffix, 0o600);
-        syncDirectory(root);
-        initializeVectorExtension(db);
-        return new LibraryStore(root, db, options);
-    }
-    catch (error) {
-        db.close();
-        throw error;
-    }
-}
-/** Storage CAS authority only. The worker separately establishes OS/process custody. */
-export class LibraryStore {
-    root;
-    db;
-    options;
-    closed = false;
-    constructor(root, db, options) {
-        this.root = root;
-        this.db = db;
-        this.options = options;
-    }
-    createIndexGeneration(options) { return indexing.createGeneration(this.db, options); }
-    submitIndexJob(generationId) { return indexJobs.submitIndexJob(this.db, generationId); }
-    indexJob(id) { return indexJobs.indexJob(this.db, id); }
-    claimIndexJob(owner, id) { return indexJobs.claimIndexJob(this.db, owner, id); }
-    checkpointIndexAttempt(token, stage) { indexJobs.checkpointIndexAttempt(this.db, token, stage); }
-    writeIndexAttemptBatch(token, fingerprint, batch) { indexJobs.withIndexAttempt(this.db, token, id => indexing.writeBatch(this.db, id, fingerprint, batch)); }
-    completeIndexAttempt(token) { return indexJobs.withIndexAttempt(this.db, token, id => { const status = indexing.activateGeneration(this.db, id); indexJobs.finishIndexAttempt(this.db, token); return status; }); }
-    failIndexAttempt(token, reason) { indexJobs.finishIndexAttempt(this.db, token, reason); }
-    settleIndexAttempt(token) { this.transaction(() => { this.checkOwner(token); const a = this.db.prepare('SELECT * FROM index_attempts WHERE id=? AND job_id=?').get(token.attemptId, token.jobId); if (!a || a.owner_incarnation !== token.ownerIncarnation || a.fence !== token.fence || a.finished_at === null)
-        throw new StoreError('owner-busy'); const path = join(this.root, 'staging', token.attemptId); if (pathExists(path)) {
-        this.checkIndexStaging(token, path);
-        rmSync(path, { recursive: true });
-        syncDirectory(dirname(path));
-    } indexJobs.settleIndexAttempt(this.db, token); }); }
-    checkIndexStaging(token, path) { safeDirectory(path); const fd = openSync(join(path, 'ownership.json'), constants.O_RDONLY | constants.O_NOFOLLOW); try {
-        const stat = fstatSync(fd);
-        if (!stat.isFile() || stat.size > 65536 || (stat.mode & 0o077) !== 0)
-            throw new StoreError('integrity');
-        const marker = JSON.parse(readFileSync(fd, 'utf8'));
-        if (marker.schemaVersion !== 1 || marker.requestId !== token.attemptId || marker.ownerIncarnation !== token.ownerIncarnation)
-            throw new StoreError('integrity');
-    }
-    finally {
-        closeSync(fd);
-    } }
-    indexStatus(id) { return indexing.generationStatus(this.db, id); }
-    indexInputs(id, limit = 16) { return indexing.pendingInputs(this.db, id, limit); }
-    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); }
-    /** 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);
-        hash(sourceHash);
-        const row = this.db.prepare('SELECT item_id itemId,outcome FROM import_receipts WHERE namespace=? AND source_key=? AND source_hash=?').get(namespace, sourceKey, sourceHash);
-        return row ? { itemId: String(row.itemId), outcome: String(row.outcome) } : null;
-    }
-    close() {
-        if (!this.closed) {
-            this.db.close();
-            this.closed = true;
-        }
-    }
-    transaction(fn) {
-        this.db.exec('BEGIN IMMEDIATE');
-        try {
-            const result = fn();
-            this.db.exec('COMMIT');
-            return result;
-        }
-        catch (error) {
-            this.db.exec('ROLLBACK');
-            throw error;
-        }
-    }
-    get revisionEpoch() { return Number(this.db.prepare('SELECT revision_epoch FROM library_info WHERE id=1').get()?.revision_epoch); }
-    bumpEpoch() { this.db.exec('UPDATE library_info SET revision_epoch=revision_epoch+1 WHERE id=1'); }
-    acquireOwner(ownerIncarnation) {
-        text(ownerIncarnation, 256);
-        return this.transaction(() => {
-            const old = this.db.prepare('SELECT * FROM worker_owner WHERE id=1').get();
-            if (old.incarnation !== null && old.incarnation !== ownerIncarnation)
-                throw new StoreError('owner-busy');
-            if (old.incarnation === ownerIncarnation)
-                return { ownerIncarnation, fence: Number(old.fence) };
-            this.db.prepare('UPDATE worker_owner SET incarnation=?,fence=fence+1 WHERE id=1').run(ownerIncarnation);
-            return { ownerIncarnation, fence: Number(old.fence) + 1 };
-        });
-    }
-    releaseOwner(token) {
-        this.transaction(() => {
-            this.checkOwner(token);
-            if (this.ownerAttempts(token).some(attempt => attempt.cleanup === 'pending'))
-                throw new StoreError('owner-busy');
-            this.db.prepare('UPDATE worker_owner SET incarnation=NULL WHERE id=1').run();
-        });
-    }
-    ownerSnapshot() {
-        const row = this.db.prepare('SELECT incarnation,fence FROM worker_owner WHERE id=1').get();
-        return row.incarnation === null ? null : { ownerIncarnation: String(row.incarnation), fence: Number(row.fence) };
-    }
-    ownerAttempts(token) {
-        this.checkOwner(token);
-        return [...this.db.prepare('SELECT a.*,j.state,j.cancel_requested FROM attempts a JOIN jobs j ON j.id=a.job_id WHERE a.owner_incarnation=? AND a.fence=? ORDER BY a.created_at,a.id').all(token.ownerIncarnation, token.fence).map(a => ({
-                ...token, attemptId: String(a.id), jobId: String(a.job_id), stage: String(a.stage), cleanup: a.cleanup, finished: a.finished_at !== null, jobState: String(a.state), cancelRequested: a.cancel_requested === 1,
-            })), ...indexJobs.indexOwnerAttempts(this.db, token)];
-    }
-    /** Requires external custody proof for EVERY pending attempt, even after its job committed.
-     * IDs are acknowledgements from the custody owner, never evidence inferred from PID/timeouts here. */
-    recoverOwner(expected, provedAttemptIds) {
-        if (!Array.isArray(provedAttemptIds) || new Set(provedAttemptIds).size !== provedAttemptIds.length)
-            throw new StoreError('invalid-input');
-        for (const id of provedAttemptIds)
-            text(id, 256);
-        this.transaction(() => {
-            this.checkOwner(expected);
-            const pending = this.ownerAttempts(expected).filter(a => a.cleanup === 'pending');
-            const proof = new Set(provedAttemptIds);
-            if (proof.size !== pending.length || pending.some(a => !proof.has(a.attemptId)))
-                throw new StoreError('owner-busy');
-            for (const attempt of pending) {
-                const path = join(this.root, 'staging', attempt.attemptId);
-                if (pathExists(path)) {
-                    if (attempt.kind === 'index')
-                        this.checkIndexStaging(attempt, path);
-                    else
-                        safeDirectory(path);
-                    rmSync(path, { recursive: true });
-                    syncDirectory(dirname(path));
-                }
-                if (attempt.kind === 'index') {
-                    indexJobs.recoverIndexAttempt(this.db, attempt);
-                    continue;
-                }
-                this.db.prepare('DELETE FROM staging_pins WHERE attempt_id=?').run(attempt.attemptId);
-                this.db.prepare("UPDATE attempts SET cleanup='settled',stage='settled',finished_at=COALESCE(finished_at,?) WHERE id=?").run(now(), attempt.attemptId);
-                if (!attempt.finished)
-                    this.db.prepare("UPDATE jobs SET state=CASE WHEN cancel_requested=1 THEN 'cancelled' ELSE 'failed' END,reason='unclassified',retryable=0,retry_after_ms=NULL WHERE id=? AND state IN ('running','cleanup-pending')").run(attempt.jobId);
-            }
-            this.db.prepare('UPDATE worker_owner SET incarnation=NULL,fence=fence+1 WHERE id=1').run();
-        });
-    }
-    checkpointAttempt(token, stage) {
-        const stages = ['queued', 'acquiring', 'extracting', 'indexing', 'promoting', 'cleanup', 'settled'];
-        if (!stages.includes(stage) || stage === 'settled')
-            throw new StoreError('invalid-input');
-        this.transaction(() => {
-            const attempt = this.checkAttempt(token);
-            if (stages.indexOf(stage) < stages.indexOf(String(attempt.stage)) || !stages.includes(String(attempt.stage)))
-                throw new StoreError('invalid-input');
-            this.db.prepare('UPDATE attempts SET stage=? WHERE id=?').run(stage, token.attemptId);
-        });
-    }
-    jobCancellationRequested(jobId) {
-        text(jobId, 256);
-        const index = indexJobs.indexJob(this.db, jobId);
-        if (index)
-            return index.cancel_requested === 1;
-        const row = this.db.prepare('SELECT j.cancel_requested,i.deleted_at FROM jobs j JOIN items i ON i.id=j.item_id WHERE j.id=?').get(jobId);
-        if (!row)
-            throw new StoreError('unavailable');
-        return row.cancel_requested === 1 || row.deleted_at !== null;
-    }
-    retryJob(jobId, options = {}) {
-        if (indexJobs.indexJob(this.db, jobId)) {
-            if (options.automatic || options.notBefore !== undefined)
-                throw new StoreError('invalid-input');
-            indexJobs.retryIndexJob(this.db, jobId);
-            return;
-        }
-        text(jobId, 256);
-        if (options.automatic !== undefined && typeof options.automatic !== 'boolean')
-            throw new StoreError('invalid-input');
-        if (options.notBefore !== undefined && (typeof options.notBefore !== 'string' || !Number.isFinite(Date.parse(options.notBefore))))
-            throw new StoreError('invalid-input');
-        this.transaction(() => {
-            const job = this.db.prepare('SELECT j.*,i.deleted_at FROM jobs j JOIN items i ON i.id=j.item_id WHERE j.id=?').get(jobId);
-            if (!job || job.deleted_at || job.cancel_requested || !['failed', 'needs-auth', 'needs-permission', 'unsupported'].includes(String(job.state)))
-                throw new StoreError('unavailable');
-            if (this.db.prepare("SELECT count(*) n FROM attempts WHERE job_id=? AND (cleanup='pending' OR finished_at IS NULL)").get(jobId)?.n)
-                throw new StoreError('owner-busy');
-            if (this.db.prepare("SELECT count(*) n FROM jobs WHERE item_id=? AND id<>? AND state IN ('queued','running','delayed','cleanup-pending')").get(String(job.item_id), jobId)?.n)
-                throw new StoreError('owner-busy');
-            let due = options.notBefore === undefined ? Date.now() : Date.parse(options.notBefore);
-            if (options.automatic) {
-                if (job.retryable !== 1 || !['unavailable', 'rate-limited'].includes(String(job.reason)) || Number(job.attempt_count) >= 3)
-                    throw new StoreError('unavailable');
-                const backoff = Math.max(Number(job.retry_after_ms ?? 0), 1000 * 2 ** Math.max(0, Number(job.attempt_count) - 1));
-                due = Math.max(due, Date.now() + backoff);
-            }
-            const notBefore = new Date(due).toISOString();
-            this.db.prepare("UPDATE jobs SET state=?,not_before=?,reason=NULL,retryable=0,retry_after_ms=NULL WHERE id=?").run(due > Date.now() ? 'delayed' : 'queued', notBefore, jobId);
-        });
-    }
-    checkOwner(token) {
-        text(token.ownerIncarnation, 256);
-        integer(token.fence);
-        const owner = this.db.prepare('SELECT * FROM worker_owner WHERE id=1').get();
-        if (owner?.incarnation !== token.ownerIncarnation || owner?.fence !== token.fence)
-            throw new StoreError('owner-busy');
-    }
-    submitSource(input) {
-        text(input.sourceKey);
-        text(input.locator, 16384);
-        text(input.idempotencyKey, 256);
-        if (!['article', 'pdf', 'media'].includes(input.kind))
-            throw new StoreError('invalid-input');
-        const realm = input.realm ?? '';
-        if (realm)
-            text(realm, 256);
-        if (input.intent !== undefined && !['save', 'refresh'].includes(input.intent))
-            throw new StoreError('invalid-input');
-        return this.transaction(() => {
-            const prior = this.db.prepare('SELECT s.*,r.source_key,r.realm_key,i.kind,i.deleted_at FROM submissions s JOIN source_refs r ON r.id=s.source_id JOIN items i ON i.id=s.item_id WHERE idempotency_key=?').get(input.idempotencyKey);
-            if (prior) {
-                if (prior.deleted_at)
-                    throw new StoreError('unavailable');
-                if (prior.kind !== input.kind)
-                    throw new StoreError('invalid-input');
-                if (prior.source_key !== input.sourceKey || prior.realm_key !== realm || prior.intent !== (input.intent ?? 'save'))
-                    throw new StoreError('invalid-input');
-                return { itemId: prior.item_id, jobId: prior.job_id, submissionId: prior.id, duplicate: true };
-            }
-            let source = this.db.prepare('SELECT r.*,i.deleted_at,i.kind FROM source_refs r JOIN items i ON i.id=r.item_id WHERE source_key=? AND realm_key=?').get(input.sourceKey, realm);
-            if (source?.deleted_at)
-                throw new StoreError('unavailable');
-            if (source && source.kind !== input.kind)
-                throw new StoreError('invalid-input');
-            if (!source) {
-                // 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();
-            if (!active)
-                this.db.prepare("INSERT INTO jobs(id,item_id,state,created_at) VALUES(?,?,'queued',?)").run(jobId, source.item_id, now());
-            const submissionId = randomUUID();
-            this.db.prepare('INSERT INTO submissions VALUES(?,?,?,?,?,?,?)').run(submissionId, input.idempotencyKey, source.id, source.item_id, jobId, now(), input.intent ?? 'save');
-            return { itemId: source.item_id, jobId, submissionId, duplicate: false };
-        });
-    }
-    listJobs() { return [...this.db.prepare('SELECT j.* FROM jobs j JOIN items i ON i.id=j.item_id WHERE i.deleted_at IS NULL ORDER BY j.created_at,j.id').all(), ...indexJobs.listIndexJobs(this.db)].sort((a, b) => String(a.created_at).localeCompare(String(b.created_at)) || String(a.id).localeCompare(String(b.id))); }
-    sourceForJob(jobId) { text(jobId, 256); const row = this.db.prepare('SELECT i.id itemId,i.kind,r.source_key sourceKey,r.locator,r.realm_key realm FROM jobs j JOIN items i ON i.id=j.item_id JOIN source_refs r ON r.item_id=i.id WHERE j.id=? AND i.deleted_at IS NULL ORDER BY r.id LIMIT 1').get(jobId); return row ?? null; }
-    claimNext(token) { this.checkOwner(token); const row = this.db.prepare("SELECT j.id FROM jobs j JOIN items i ON i.id=j.item_id WHERE j.state IN ('queued','delayed') AND j.cancel_requested=0 AND i.deleted_at IS NULL AND (j.not_before IS NULL OR j.not_before<=?) ORDER BY j.priority DESC,j.created_at,j.id LIMIT 1").get(now()); return row ? this.claimJob(token, String(row.id)) : null; }
-    claimJob(token, jobId) {
-        text(jobId, 256);
-        return this.transaction(() => {
-            this.checkOwner(token);
-            if (this.db.prepare("SELECT count(*) AS n FROM index_attempts WHERE cleanup='pending'").get()?.n)
-                throw new StoreError('owner-busy');
-            const job = this.db.prepare('SELECT j.*,i.deleted_at FROM jobs j JOIN items i ON i.id=j.item_id WHERE j.id=?').get(jobId);
-            if (!job || !['queued', 'delayed'].includes(String(job.state)) || job.cancel_requested || job.deleted_at || (job.not_before && String(job.not_before) > now()))
-                throw new StoreError('unavailable');
-            const attemptId = randomUUID();
-            this.db.prepare("UPDATE jobs SET state='running',attempt_count=attempt_count+1 WHERE id=?").run(jobId);
-            this.db.prepare("INSERT INTO attempts(id,job_id,owner_incarnation,fence,stage,cleanup,created_at) VALUES(?,?,?,?,'acquiring','pending',?)").run(attemptId, jobId, token.ownerIncarnation, token.fence, now());
-            return { ...token, jobId, attemptId };
-        });
-    }
-    checkAttempt(token, itemId) {
-        this.checkOwner(token);
-        text(token.attemptId, 256);
-        text(token.jobId, 256);
-        const row = this.db.prepare('SELECT a.*,j.item_id,j.state,j.cancel_requested,i.deleted_at FROM attempts a JOIN jobs j ON j.id=a.job_id JOIN items i ON i.id=j.item_id WHERE a.id=? AND a.job_id=?').get(token.attemptId, token.jobId);
-        if (!row || row.owner_incarnation !== token.ownerIncarnation || row.fence !== token.fence || row.finished_at || row.state !== 'running')
-            throw new StoreError('owner-busy');
-        if (row.cancel_requested || row.deleted_at)
-            throw new StoreError('cancelled');
-        if (itemId && row.item_id !== itemId)
-            throw new StoreError('invalid-input');
-        return row;
-    }
-    requestCancellation(jobId) {
-        text(jobId, 256);
-        if (indexJobs.indexJob(this.db, jobId)) {
-            indexJobs.cancelIndexJob(this.db, jobId);
-            return;
-        }
-        this.transaction(() => {
-            const job = this.db.prepare('SELECT state FROM jobs WHERE id=?').get(jobId);
-            if (!job)
-                throw new StoreError('unavailable');
-            if (['succeeded', 'cancelled'].includes(String(job.state)))
-                return;
-            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 id=?").run(jobId);
-        });
-    }
-    failAttempt(token, reason = 'unclassified', options = {}) {
-        if (options.retryable !== undefined && typeof options.retryable !== 'boolean')
-            throw new StoreError('invalid-input');
-        if (options.retryAfterMs !== undefined)
-            integer(options.retryAfterMs, 86400000);
-        if (!/^[a-z][a-z-]{0,63}$/.test(reason))
-            throw new StoreError('invalid-input');
-        this.transaction(() => {
-            this.checkOwner(token);
-            const a = this.db.prepare('SELECT a.*,j.cancel_requested FROM attempts a JOIN jobs j ON j.id=a.job_id WHERE a.id=? AND a.job_id=?').get(token.attemptId, token.jobId);
-            if (!a || a.owner_incarnation !== token.ownerIncarnation || a.fence !== token.fence || a.finished_at)
-                throw new StoreError('owner-busy');
-            this.db.prepare("UPDATE jobs SET state=?,reason=?,retryable=?,retry_after_ms=? WHERE id=?").run(a.cancel_requested ? 'cancelled' : reason === 'repair-auth' ? 'needs-auth' : reason === 'grant-permission' ? 'needs-permission' : reason === 'unsupported' ? 'unsupported' : 'failed', reason, Number(options.retryable === true), options.retryAfterMs ?? null, token.jobId);
-            this.db.prepare("UPDATE attempts SET stage='cleanup',finished_at=? WHERE id=?").run(now(), token.attemptId);
-        });
-    }
-    /** Caller must first settle owned external children. This only releases storage staging pins. */
-    settleAttempt(token) {
-        this.transaction(() => {
-            this.checkOwner(token);
-            const a = this.db.prepare('SELECT * FROM attempts WHERE id=? AND job_id=?').get(token.attemptId, token.jobId);
-            if (!a || a.owner_incarnation !== token.ownerIncarnation || a.fence !== token.fence || !a.finished_at)
-                throw new StoreError('owner-busy');
-            const path = join(this.root, 'staging', token.attemptId);
-            if (pathExists(path)) {
-                safeDirectory(path);
-                rmSync(path, { recursive: true });
-                syncDirectory(dirname(path));
-            }
-            this.db.prepare('DELETE FROM staging_pins WHERE attempt_id=?').run(token.attemptId);
-            this.db.prepare("UPDATE attempts SET cleanup='settled',stage='settled' WHERE id=?").run(token.attemptId);
-        });
-    }
-    async putBlob(token, expectedHash, expectedBytes, source) {
-        hash(expectedHash);
-        integer(expectedBytes, limits.pdfBytes);
-        const relativePath = `blobs/sha256/${expectedHash.slice(0, 2)}/${expectedHash}`;
-        this.transaction(() => {
-            this.checkAttempt(token);
-            const pins = this.db.prepare("SELECT COALESCE(sum(bytes),0) n FROM staging_pins").get();
-            if (Number(pins.n) + expectedBytes > limits.stagingBytes)
-                throw new StoreError('limit-exceeded');
-            const free = statfsSync(this.root);
-            if (free.bavail * free.bsize < limits.freeReserveBytes + expectedBytes)
-                throw new StoreError('limit-exceeded');
-            const existing = this.db.prepare('SELECT bytes FROM staging_pins WHERE attempt_id=? AND sha256=?').get(token.attemptId, expectedHash);
-            if (existing && existing.bytes !== expectedBytes)
-                throw new StoreError('integrity');
-            this.db.prepare("INSERT OR IGNORE INTO staging_pins VALUES(?,?,?,'staging')").run(token.attemptId, expectedHash, expectedBytes);
-        });
-        const stage = safeDirectory(join(this.root, 'staging', token.attemptId), true), temp = join(stage, randomUUID() + '.tmp');
-        const fd = openSync(temp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
-        let count = 0;
-        const h = createHash('sha256');
-        try {
-            for await (const chunk of source) {
-                if (!(chunk instanceof Uint8Array))
-                    throw new StoreError('invalid-input');
-                count += chunk.byteLength;
-                if (count > expectedBytes)
-                    throw new StoreError('limit-exceeded');
-                h.update(chunk);
-                let offset = 0;
-                while (offset < chunk.byteLength)
-                    offset += writeSync(fd, chunk, offset, chunk.byteLength - offset);
-            }
-            if (count !== expectedBytes || h.digest('hex') !== expectedHash)
-                throw new StoreError('integrity');
-            fsyncSync(fd);
-        }
-        catch (error) {
-            closeSync(fd);
-            unlinkSync(temp);
-            throw error;
-        }
-        closeSync(fd);
-        syncDirectory(stage);
-        this.options.fault?.('staged');
-        const target = join(this.root, relativePath);
-        safeDirectory(dirname(target), true);
-        // Atomic create-if-absent publication. A hard-link plus unlink avoids rename overwriting immutable bytes.
-        this.transaction(() => {
-            this.checkAttempt(token);
-            try {
-                linkSync(temp, target);
-            }
-            catch (error) {
-                if (error.code !== 'EEXIST')
-                    throw error;
-                verifyFile(target, expectedHash, expectedBytes);
-            }
-            unlinkSync(temp);
-            syncDirectory(dirname(target));
-            syncDirectory(stage);
-            verifyFile(target, expectedHash, expectedBytes);
-            this.db.prepare("UPDATE staging_pins SET state='published' WHERE attempt_id=? AND sha256=?").run(token.attemptId, expectedHash);
-        });
-        this.options.fault?.('published');
-        return { sha256: expectedHash, bytes: expectedBytes, relativePath };
-    }
-    commitRevision(input) {
-        hash(input.bundleHash);
-        if (typeof input.markdown !== 'string' || Buffer.byteLength(input.markdown) > limits.markdownBytes)
-            throw new StoreError('limit-exceeded');
-        text(input.itemId, 256);
-        text(input.extractor.name, 256);
-        text(input.extractor.version, 128);
-        if (input.title)
-            text(input.title, 4096);
-        if (!['complete', 'partial'].includes(input.status) || input.assets.length > limits.imagesPerItem + 1)
-            throw new StoreError('invalid-input');
-        const metadata = input.metadata ?? [];
-        if (metadata.length > limits.metadataClaims || Buffer.byteLength(JSON.stringify(metadata)) > limits.metadataBytes)
-            throw new StoreError('limit-exceeded');
-        for (const claim of metadata) {
-            try {
-                validateMetadataClaim(claim);
-            }
-            catch {
-                throw new StoreError('invalid-input');
-            }
-        }
-        const metadataWarnings = input.metadataWarnings ?? [];
-        try {
-            validateMetadataWarnings(metadataWarnings);
-        }
-        catch {
-            throw new StoreError('invalid-input');
-        }
-        const imported = input.importedState;
-        if (imported) {
-            text(imported.namespace, 256);
-            text(imported.sourceKey, 8192);
-            hash(imported.sourceHash);
-            text(imported.importerVersion, 128);
-            if (!['private', 'published'].includes(imported.privacy) || !Array.isArray(imported.notes) || imported.notes.length > 1000 || Buffer.byteLength(JSON.stringify(imported)) > 4 * 1024 ** 2)
-                throw new StoreError('limit-exceeded');
-            const noteIds = new Set();
-            for (const note of imported.notes) {
-                text(note.id, 256);
-                text(note.body, 65536);
-                if (noteIds.has(note.id))
-                    throw new StoreError('invalid-input');
-                noteIds.add(note.id);
-            }
-            if (imported.readingState !== undefined && (!imported.readingState || Array.isArray(imported.readingState) || typeof imported.readingState !== 'object'))
-                throw new StoreError('invalid-input');
-        }
-        for (const asset of input.assets) {
-            hash(asset.sha256);
-            const transcript = asset.mediaType === 'application/json' && asset.relationship === 'transcript';
-            integer(asset.bytes, transcript ? 4 * 1024 ** 2 : asset.mediaType === 'application/pdf' ? limits.pdfBytes : limits.imageBytes);
-            if (!/^image\/[a-z0-9.+-]+$/.test(asset.mediaType) && asset.mediaType !== 'application/pdf' && !transcript)
-                throw new StoreError('invalid-input');
-            if (asset.relativePath !== `blobs/sha256/${asset.sha256.slice(0, 2)}/${asset.sha256}`)
-                throw new StoreError('integrity');
-            verifyFile(confinedFile(this.root, join(this.root, asset.relativePath)), asset.sha256, asset.bytes);
-        }
-        const payloadHash = digest(JSON.stringify({ markdown: input.markdown, title: input.title ?? '', extractor: input.extractor, status: input.status, assets: input.assets, metadata, warnings: input.warnings ?? [], ...(metadataWarnings.length ? { metadataWarnings } : {}) }));
-        const result = this.transaction(() => {
-            this.checkAttempt(input, input.itemId);
-            for (const asset of input.assets) {
-                const pin = this.db.prepare("SELECT bytes FROM staging_pins WHERE attempt_id=? AND sha256=? AND state='published'").get(input.attemptId, asset.sha256);
-                if (!pin || pin.bytes !== asset.bytes)
-                    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,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()) {
-                    const existingAsset = this.db.prepare('SELECT bytes FROM assets WHERE sha256=?').get(asset.sha256);
-                    if (existingAsset && existingAsset.bytes !== asset.bytes)
-                        throw new StoreError('integrity');
-                    this.db.prepare('INSERT OR IGNORE INTO assets VALUES(?,?,?,?)').run(asset.sha256, asset.bytes, asset.mediaType, asset.relativePath);
-                    this.db.prepare('INSERT INTO revision_assets VALUES(?,?,?,?,?,?,?)').run(revisionId, asset.sha256, ordinal, asset.relationship ?? 'image', null, asset.alt ?? null, asset.caption ?? null);
-                }
-                this.db.prepare('INSERT INTO representations(id,revision_id,kind,mime_type,sha256,bytes,markdown,extractor_version) VALUES(?,?,?,?,?,?,?,?)').run(randomUUID(), revisionId, 'markdown', 'text/markdown', digest(input.markdown), Buffer.byteLength(input.markdown), input.markdown, input.extractor.version);
-                for (const claim of metadata)
-                    this.db.prepare('INSERT INTO metadata_claims(id,revision_id,field,value_json,source,observed_at,rule,timezone_known,observed_json,locator,selected,extraction_version,date_precision) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?)').run(randomUUID(), revisionId, claim.field, JSON.stringify(claim.value), claim.source, claim.observedAt, claim.rule ?? null, claim.timezoneKnown === undefined ? null : Number(claim.timezoneKnown), claim.observed === undefined ? null : JSON.stringify(claim.observed), claim.locator ?? null, claim.selected === undefined ? null : Number(claim.selected), claim.extractionVersion ?? null, claim.datePrecision ?? null);
-                this.db.prepare('INSERT INTO blocks(id,revision_id,ordinal,kind,text) VALUES(?,?,0,?,?)').run(randomUUID(), revisionId, 'document', input.markdown);
-            }
-            else {
-                if (existing.payload_hash !== payloadHash)
-                    throw new StoreError('integrity');
-                const prior = this.db.prepare("SELECT sha256 FROM representations WHERE revision_id=? AND kind='markdown'").get(revisionId);
-                if (prior?.sha256 !== digest(input.markdown))
-                    throw new StoreError('integrity');
-            }
-            if (item.current_revision !== revisionId) {
-                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);
-                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)
-                    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)
-                    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';
-                    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');
-            }
-            this.db.prepare("UPDATE jobs SET state='succeeded',reason=NULL WHERE id=?").run(input.jobId);
-            this.db.prepare("UPDATE attempts SET stage='cleanup',finished_at=? WHERE id=?").run(now(), input.attemptId);
-            this.options.fault?.('transaction');
-            return { revisionId, duplicate: !!existing };
-        });
-        this.options.fault?.('committed');
-        return result;
-    }
-    list() { return this.db.prepare('SELECT id itemId,kind,title,current_revision revisionId FROM items WHERE deleted_at IS NULL ORDER BY created_at,id').all(); }
-    read(itemId) {
-        text(itemId, 256);
-        const item = this.db.prepare("SELECT i.id itemId,i.kind,i.title,r.id revisionId,r.status,p.markdown FROM items i JOIN revisions r ON r.id=i.current_revision JOIN representations p ON p.revision_id=r.id AND p.kind='markdown' WHERE i.id=? AND i.deleted_at IS NULL").get(itemId);
-        if (!item)
-            return null;
-        const assets = this.db.prepare('SELECT a.*,r.relationship,r.alt,r.caption FROM revision_assets r JOIN assets a ON a.sha256=r.sha256 WHERE r.revision_id=? ORDER BY r.ordinal').all(item.revisionId).map(a => ({ sha256: String(a.sha256), bytes: Number(a.bytes), relativePath: String(a.relative_path), mediaType: String(a.media_type), relationship: String(a.relationship), ...(a.alt ? { alt: String(a.alt) } : {}), ...(a.caption ? { caption: String(a.caption) } : {}) }));
-        const metadata = this.db.prepare('SELECT * FROM metadata_claims WHERE revision_id=? ORDER BY rowid').all(item.revisionId).map(c => ({ field: String(c.field), value: JSON.parse(String(c.value_json)), source: String(c.source), observedAt: String(c.observed_at), ...(c.rule ? { rule: String(c.rule) } : {}), ...(c.timezone_known === null ? {} : { timezoneKnown: !!c.timezone_known }), ...(c.observed_json === null ? {} : { observed: JSON.parse(String(c.observed_json)) }), ...(c.locator === null ? {} : { locator: String(c.locator) }), ...(c.selected === null ? {} : { selected: !!c.selected }), ...(c.extraction_version === null ? {} : { extractionVersion: String(c.extraction_version) }), ...(c.date_precision === null ? {} : { datePrecision: String(c.date_precision) }) }));
-        const metadataWarnings = JSON.parse(String(this.db.prepare('SELECT metadata_warnings_json FROM revisions WHERE id=?').get(item.revisionId)?.metadata_warnings_json));
-        validateMetadataWarnings(metadataWarnings);
-        return { ...item, assets, metadata, metadataWarnings };
-    }
-    readBlob(reference) {
-        hash(reference.sha256);
-        integer(reference.bytes, limits.pdfBytes);
-        if (reference.relativePath !== `blobs/sha256/${reference.sha256.slice(0, 2)}/${reference.sha256}`)
-            throw new StoreError('integrity');
-        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); 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('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();
-            }
-        });
-    }
-    /** Online DB snapshot only; P12 pairs this with blobs while the returned fence remains active. */
-    async createBackupSnapshot() {
-        const id = randomUUID();
-        const epoch = this.transaction(() => { const e = this.revisionEpoch; this.db.prepare("INSERT INTO backup_fences VALUES(?,?,'active',?)").run(id, e, now()); return e; });
-        const path = join(this.root, 'backups', id + '.sqlite');
-        try {
-            await backup(this.db, path);
-            chmodSync(path, 0o600);
-            const fd = openSync(path, constants.O_RDONLY);
-            try {
-                fsyncSync(fd);
-            }
-            finally {
-                closeSync(fd);
-            }
-            syncDirectory(dirname(path));
-            return { id, path, revisionEpoch: epoch };
-        }
-        catch (error) {
-            this.db.prepare('DELETE FROM backup_fences WHERE id=?').run(id);
-            throw error;
-        }
-    }
-    finishBackup(id) { text(id, 256); this.db.prepare("UPDATE backup_fences SET state='complete' WHERE id=?").run(id); }
-    /** Hold the SQLite writer fence across synchronous GC inspection and removal. */
-    withGcFence(expectedEpoch, callback) {
-        integer(expectedEpoch);
-        return this.transaction(() => {
-            if (this.revisionEpoch !== expectedEpoch || this.ownerSnapshot() !== null || this.pendingCleanupCount() > 0 || this.hasGcFence())
-                throw new StoreError('owner-busy');
-            const references = this.db.prepare('SELECT sha256,bytes,relative_path relativePath FROM assets ORDER BY sha256').all();
-            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; }
-}