@hraness/sponge 0.1.2 → 0.2.0

package/dist/src/store/index.js

@@ -0,0 +1,727 @@
+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, version } from '../../migrations/004.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 { hybridSearch } from '../search/hybrid.js';
+import { initializeVectorExtension } from '../search/extension.js';
+export * from './types.js';
+const now = () => new Date().toISOString();
+const migrations = [sql1, sql2, sql3, sql4];
+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');
+                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);
+                    }
+                    finally {
+                        closeSync(fd);
+                    }
+                    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;
+                    }
+                }
+            }
+            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); }
+    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 }; }
+    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) {
+                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 };
+            }
+            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 FROM items WHERE id=?').get(input.itemId);
+            const revisionId = existing ? String(existing.id) : randomUUID();
+            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) {
+                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);
+                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));
+                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());
+                }
+                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());
+                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);
+                }
+                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); 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); }
+    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);
+                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);
+        });
+    }
+    /** 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; }
+}