@hraness/sponge 0.2.6 → 0.3.1

package/dist/src/store/queue.js

@@ -0,0 +1,327 @@
+import { randomUUID } from 'node:crypto';
+import { integer, safeDirectory, text } from './files.js';
+import { mutate, sourceRefId } from './changes.js';
+import { isFileLocator, portableLocator } from './ids.js';
+import { syncUris } from '../identity/visibility.js';
+import { sha256 } from '../util/hash.js';
+import { checkAttempt, checkOwner, ownerSnapshot, pendingCleanup, removeStaging } from './lease.js';
+import { now, transaction } from './context.js';
+import { SpongeError } from '../errors.js';
+const stages = ['queued', 'acquiring', 'extracting', 'indexing', 'promoting', 'cleanup', 'settled'];
+const activeStates = "('queued','running','delayed','cleanup-pending')";
+/** Capture jobs (acquire, extract, commit one source) and the owner lease shared with every other job kind. */
+export class Queue {
+    c;
+    index;
+    capture;
+    constructor(c, index) {
+        this.c = c;
+        this.index = index;
+        const db = c.db;
+        this.capture = {
+            owns: (id) => !!db.prepare('SELECT 1 FROM jobs WHERE id=?').get(id),
+            list: () => 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(),
+            attempts: (token) => 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,
+            })),
+            cancel: (jobId) => transaction(db, () => {
+                const job = db.prepare('SELECT state FROM jobs WHERE id=?').get(jobId);
+                if (!job)
+                    throw new SpongeError('unavailable');
+                if (['succeeded', 'cancelled'].includes(String(job.state)))
+                    return;
+                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);
+            }),
+            retry: (jobId, options) => {
+                if (options.automatic !== undefined && typeof options.automatic !== 'boolean')
+                    throw new SpongeError('invalid-input');
+                if (options.notBefore !== undefined &&
+                    (typeof options.notBefore !== 'string' || !Number.isFinite(Date.parse(options.notBefore))))
+                    throw new SpongeError('invalid-input');
+                transaction(db, () => {
+                    const job = 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 SpongeError('unavailable');
+                    if (db
+                        .prepare("SELECT count(*) n FROM attempts WHERE job_id=? AND (cleanup='pending' OR finished_at IS NULL)")
+                        .get(jobId)?.n)
+                        throw new SpongeError('owner-busy');
+                    if (db
+                        .prepare(`SELECT count(*) n FROM jobs WHERE item_id=? AND id<>? AND state IN ${activeStates}`)
+                        .get(String(job.item_id), jobId)?.n)
+                        throw new SpongeError('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 SpongeError('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();
+                    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);
+                });
+            },
+            cancelRequested: (jobId) => {
+                const row = 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 SpongeError('unavailable');
+                return row.cancel_requested === 1 || row.deleted_at !== null;
+            },
+            recover: (attempt) => {
+                removeStaging(c.root, attempt.attemptId, (path) => {
+                    safeDirectory(path);
+                });
+                db.prepare('DELETE FROM staging_pins WHERE attempt_id=?').run(attempt.attemptId);
+                db.prepare("UPDATE attempts SET cleanup='settled',stage='settled',finished_at=COALESCE(finished_at,?) WHERE id=?").run(now(), attempt.attemptId);
+                if (!attempt.finished)
+                    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);
+            },
+        };
+    }
+    /** Index jobs are checked first; any other id is a capture job (which reports `unavailable` when it does not exist). */
+    kindOf(jobId) {
+        return this.index.owns(jobId) ? this.index : this.capture;
+    }
+    acquireOwner(ownerIncarnation) {
+        text(ownerIncarnation, 256);
+        const db = this.c.db;
+        return transaction(db, () => {
+            const old = db.prepare('SELECT * FROM worker_owner WHERE id=1').get();
+            if (old.incarnation !== null && old.incarnation !== ownerIncarnation)
+                throw new SpongeError('owner-busy');
+            if (old.incarnation === ownerIncarnation)
+                return { ownerIncarnation, fence: Number(old.fence) };
+            db.prepare('UPDATE worker_owner SET incarnation=?,fence=fence+1 WHERE id=1').run(ownerIncarnation);
+            return { ownerIncarnation, fence: Number(old.fence) + 1 };
+        });
+    }
+    releaseOwner(token) {
+        transaction(this.c.db, () => {
+            checkOwner(this.c.db, token);
+            if (this.ownerAttempts(token).some((attempt) => attempt.cleanup === 'pending'))
+                throw new SpongeError('owner-busy');
+            this.c.db.prepare('UPDATE worker_owner SET incarnation=NULL WHERE id=1').run();
+        });
+    }
+    ownerSnapshot() {
+        return ownerSnapshot(this.c.db);
+    }
+    /** Every attempt the owner claimed, capture first, then index. */
+    ownerAttempts(token) {
+        checkOwner(this.c.db, token);
+        return [...this.capture.attempts(token), ...this.index.attempts(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 SpongeError('invalid-input');
+        for (const id of provedAttemptIds)
+            text(id, 256);
+        transaction(this.c.db, () => {
+            checkOwner(this.c.db, 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 SpongeError('owner-busy');
+            for (const attempt of pending)
+                (attempt.kind === 'index' ? this.index : this.capture).recover(attempt);
+            this.c.db.prepare('UPDATE worker_owner SET incarnation=NULL,fence=fence+1 WHERE id=1').run();
+        });
+    }
+    /** Deduplicates source identity including realm and persists an idempotent submission and queued job. */
+    submit(input) {
+        text(input.sourceKey);
+        text(input.locator, 16384);
+        text(input.idempotencyKey, 256);
+        if (!['article', 'pdf', 'media'].includes(input.kind))
+            throw new SpongeError('invalid-input');
+        const realm = input.realm ?? '';
+        if (realm)
+            text(realm, 256);
+        if (input.intent !== undefined && !['save', 'refresh'].includes(input.intent))
+            throw new SpongeError('invalid-input');
+        const db = this.c.db;
+        return transaction(db, () => {
+            const prior = 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 SpongeError('unavailable');
+                if (prior.kind !== input.kind)
+                    throw new SpongeError('invalid-input');
+                if (prior.source_key !== input.sourceKey ||
+                    prior.realm_key !== realm ||
+                    prior.intent !== (input.intent ?? 'save'))
+                    throw new SpongeError('invalid-input');
+                return { itemId: prior.item_id, jobId: prior.job_id, submissionId: prior.id, duplicate: true };
+            }
+            let source = 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 SpongeError('unavailable');
+            if (source && source.kind !== input.kind)
+                throw new SpongeError('invalid-input');
+            if (!source) {
+                // Devices of one library agree on the id; outsiders cannot derive it from a URL.
+                const library = String(db.prepare('SELECT uuid FROM library_info WHERE id=1').get()?.uuid);
+                const itemId = sha256(JSON.stringify(['item-v1', library, realm, input.sourceKey]));
+                if (db.prepare('SELECT 1 FROM items WHERE id=?').get(itemId))
+                    throw new SpongeError('integrity');
+                // A local path never enters the log: the portable locator syncs, the path stays in `local_sources`.
+                mutate(db, 'item', itemId, 'created', {
+                    kind: input.kind,
+                    sourceKey: input.sourceKey,
+                    realm,
+                    locator: portableLocator(input.locator),
+                    createdAt: now(),
+                });
+                syncUris(db, itemId);
+                source = { id: sourceRefId(itemId), item_id: itemId };
+            }
+            if (isFileLocator(input.locator))
+                db.prepare('INSERT INTO local_sources(item_id,locator) VALUES(?,?) ON CONFLICT(item_id) DO UPDATE SET locator=excluded.locator').run(source.item_id, input.locator);
+            const active = db
+                .prepare(`SELECT id FROM jobs WHERE item_id=? AND state IN ${activeStates} ORDER BY created_at LIMIT 1`)
+                .get(source.item_id);
+            const jobId = active ? String(active.id) : randomUUID();
+            if (!active)
+                db.prepare("INSERT INTO jobs(id,item_id,state,created_at) VALUES(?,?,'queued',?)").run(jobId, source.item_id, now());
+            const submissionId = randomUUID();
+            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 };
+        });
+    }
+    /** Jobs of every kind, oldest first. */
+    list() {
+        return [...this.capture.list(), ...this.index.list()].sort((a, b) => String(a.created_at).localeCompare(String(b.created_at)) || String(a.id).localeCompare(String(b.id)));
+    }
+    /** Acquisition data for a capture job. A local file's locator is its path on this device (`local_sources`), never the synced form. */
+    source(jobId) {
+        text(jobId, 256);
+        const row = this.c.db
+            .prepare('SELECT i.id itemId,i.kind,r.source_key sourceKey,COALESCE(l.locator,r.locator) 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 LEFT JOIN local_sources l ON l.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) {
+        checkOwner(this.c.db, token);
+        const row = this.c.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.claim(token, String(row.id)) : null;
+    }
+    claim(token, jobId) {
+        text(jobId, 256);
+        const db = this.c.db;
+        return transaction(db, () => {
+            checkOwner(db, token);
+            if (db.prepare("SELECT count(*) AS n FROM index_attempts WHERE cleanup='pending'").get()?.n)
+                throw new SpongeError('owner-busy');
+            const job = 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 SpongeError('unavailable');
+            const attemptId = randomUUID();
+            db.prepare("UPDATE jobs SET state='running',attempt_count=attempt_count+1 WHERE id=?").run(jobId);
+            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 };
+        });
+    }
+    checkpoint(token, stage) {
+        if (!stages.includes(stage) || stage === 'settled')
+            throw new SpongeError('invalid-input');
+        transaction(this.c.db, () => {
+            const attempt = checkAttempt(this.c.db, token);
+            if (stages.indexOf(stage) < stages.indexOf(String(attempt.stage)) || !stages.includes(String(attempt.stage)))
+                throw new SpongeError('invalid-input');
+            this.c.db.prepare('UPDATE attempts SET stage=? WHERE id=?').run(stage, token.attemptId);
+        });
+    }
+    cancelRequested(jobId) {
+        text(jobId, 256);
+        return this.kindOf(jobId).cancelRequested(jobId);
+    }
+    retry(jobId, options = {}) {
+        text(jobId, 256);
+        this.kindOf(jobId).retry(jobId, options);
+    }
+    cancel(jobId) {
+        text(jobId, 256);
+        this.kindOf(jobId).cancel(jobId);
+    }
+    fail(token, reason = 'unclassified', options = {}) {
+        if (options.retryable !== undefined && typeof options.retryable !== 'boolean')
+            throw new SpongeError('invalid-input');
+        if (options.retryAfterMs !== undefined)
+            integer(options.retryAfterMs, 86400000);
+        if (!/^[a-z][a-z-]{0,63}$/.test(reason))
+            throw new SpongeError('invalid-input');
+        const db = this.c.db;
+        transaction(db, () => {
+            checkOwner(db, token);
+            const a = 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 SpongeError('owner-busy');
+            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);
+            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. */
+    settle(token) {
+        const db = this.c.db;
+        transaction(db, () => {
+            checkOwner(db, token);
+            const a = 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 SpongeError('owner-busy');
+            removeStaging(this.c.root, token.attemptId, (path) => {
+                safeDirectory(path);
+            });
+            db.prepare('DELETE FROM staging_pins WHERE attempt_id=?').run(token.attemptId);
+            db.prepare("UPDATE attempts SET cleanup='settled',stage='settled' WHERE id=?").run(token.attemptId);
+        });
+    }
+    /** Attempts of any kind whose cleanup is pending; GC and pruning wait for zero. */
+    pendingCleanup() {
+        return pendingCleanup(this.c.db);
+    }
+}

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

@@ -0,0 +1,12 @@
+import { type Context } from './context.js';
+import type { CommitRevision } from './types.js';
+/** Captured revisions: content-addressed, immutable once committed, and the item's readable pointer. */
+export declare class Revisions {
+    private readonly c;
+    constructor(c: Context);
+    markdown(revisionId: string): string;
+    commit(input: CommitRevision): {
+        revisionId: string;
+        duplicate: boolean;
+    };
+}

package/dist/src/store/revisions.js

@@ -0,0 +1,189 @@
+import { join } from 'node:path';
+import { limits } from '../../contracts/index.js';
+import { validateMetadataClaim, validateMetadataWarnings } from '../../contracts/validate.js';
+import { confinedFile, hash, integer, text, verifyFile } from './files.js';
+import { sha256 } from '../util/hash.js';
+import { mutate } from './changes.js';
+import { blockId, claimColumns, claimId, representationId } from './ids.js';
+import { syncUris } from '../identity/visibility.js';
+import { importNote, markdownFor, setReadingState } from '../annotations/store.js';
+import { indexReadable } from '../search/lexical.js';
+import { trackLibrary } from '../indexing/index.js';
+import { checkAttempt } from './lease.js';
+import { importReceipt } from './imports.js';
+import { bumpEpoch, now, transaction } from './context.js';
+import { SpongeError } from '../errors.js';
+/** Captured revisions: content-addressed, immutable once committed, and the item's readable pointer. */
+export class Revisions {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    markdown(revisionId) {
+        text(revisionId, 256);
+        return markdownFor(this.c.db, revisionId);
+    }
+    commit(input) {
+        const { root, db, options } = this.c;
+        hash(input.bundleHash);
+        if (typeof input.markdown !== 'string' || Buffer.byteLength(input.markdown) > limits.markdownBytes)
+            throw new SpongeError('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 SpongeError('invalid-input');
+        const metadata = input.metadata ?? [];
+        if (metadata.length > limits.metadataClaims || Buffer.byteLength(JSON.stringify(metadata)) > limits.metadataBytes)
+            throw new SpongeError('limit-exceeded');
+        for (const claim of metadata) {
+            try {
+                validateMetadataClaim(claim);
+            }
+            catch {
+                throw new SpongeError('invalid-input');
+            }
+        }
+        const metadataWarnings = input.metadataWarnings ?? [];
+        try {
+            validateMetadataWarnings(metadataWarnings);
+        }
+        catch {
+            throw new SpongeError('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 SpongeError('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 SpongeError('invalid-input');
+                noteIds.add(note.id);
+            }
+            if (imported.readingState !== undefined &&
+                (!imported.readingState || Array.isArray(imported.readingState) || typeof imported.readingState !== 'object'))
+                throw new SpongeError('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 SpongeError('invalid-input');
+            if (asset.relativePath !== `blobs/sha256/${asset.sha256.slice(0, 2)}/${asset.sha256}`)
+                throw new SpongeError('integrity');
+            verifyFile(confinedFile(root, join(root, asset.relativePath)), asset.sha256, asset.bytes);
+        }
+        const payloadHash = sha256(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 = transaction(db, () => {
+            checkAttempt(db, input, input.itemId);
+            for (const asset of input.assets) {
+                const pin = 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 SpongeError('integrity');
+            }
+            const existing = db
+                .prepare('SELECT id,payload_hash FROM revisions WHERE item_id=? AND bundle_hash=?')
+                .get(input.itemId, input.bundleHash);
+            const item = db.prepare('SELECT current_revision,title_captured 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)
+                : sha256(JSON.stringify(['revision-v1', input.itemId, input.bundleHash]));
+            if (!existing) {
+                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 = db.prepare('SELECT bytes FROM assets WHERE sha256=?').get(asset.sha256);
+                    if (existingAsset && existingAsset.bytes !== asset.bytes)
+                        throw new SpongeError('integrity');
+                    db.prepare('INSERT OR IGNORE INTO assets VALUES(?,?,?,?)').run(asset.sha256, asset.bytes, asset.mediaType, asset.relativePath);
+                    db.prepare('INSERT INTO revision_assets VALUES(?,?,?,?,?,?,?)').run(revisionId, asset.sha256, ordinal, asset.relationship ?? 'image', null, asset.alt ?? null, asset.caption ?? null);
+                }
+                db.prepare('INSERT INTO representations(id,revision_id,kind,mime_type,sha256,bytes,markdown,extractor_version) VALUES(?,?,?,?,?,?,?,?)').run(representationId(revisionId, 'markdown', 'text/markdown', sha256(input.markdown)), revisionId, 'markdown', 'text/markdown', sha256(input.markdown), Buffer.byteLength(input.markdown), input.markdown, input.extractor.version);
+                for (const [ordinal, claim] of metadata.entries()) {
+                    const columns = claimColumns(claim);
+                    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(claimId(revisionId, ordinal, columns), revisionId, ...columns);
+                }
+                db.prepare('INSERT INTO blocks(id,revision_id,ordinal,kind,text) VALUES(?,?,0,?,?)').run(blockId(revisionId, 0, 'document', input.markdown), revisionId, 'document', input.markdown);
+            }
+            else {
+                if (existing.payload_hash !== payloadHash)
+                    throw new SpongeError('integrity');
+                const prior = db
+                    .prepare("SELECT sha256 FROM representations WHERE revision_id=? AND kind='markdown'")
+                    .get(revisionId);
+                if (prior?.sha256 !== sha256(input.markdown))
+                    throw new SpongeError('integrity');
+            }
+            if (item.current_revision !== revisionId) {
+                mutate(db, 'item', input.itemId, 'currentRevision', revisionId);
+                // Only the captured default: a note title or the user's override still wins (`items.title`, see changes.ts).
+                if (item.title_captured !== (input.title ?? ''))
+                    mutate(db, 'item', input.itemId, 'capturedTitle', input.title ?? '');
+                const stored = db
+                    .prepare("SELECT markdown FROM representations WHERE revision_id=? AND kind='markdown'")
+                    .get(revisionId);
+                indexReadable(db, input.itemId, revisionId, String(db.prepare('SELECT title FROM items WHERE id=?').get(input.itemId).title), String(stored.markdown));
+                syncUris(db, input.itemId);
+                bumpEpoch(db);
+                // Active indexes follow the new revision; only its new chunks are queued for embedding.
+                trackLibrary(db);
+            }
+            if (imported) {
+                const receipt = importReceipt(db, imported.namespace, imported.sourceKey, imported.sourceHash);
+                if (receipt && receipt.itemId !== input.itemId)
+                    throw new SpongeError('integrity');
+                for (const note of imported.notes)
+                    importNote(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 = 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)
+                    setReadingState(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)
+                        setReadingState(db, input.itemId, { ...existing, sourcePrivacy });
+                }
+                db.prepare('INSERT OR IGNORE INTO import_receipts VALUES(?,?,?,?,?,?)').run(imported.namespace, imported.sourceKey, imported.sourceHash, imported.importerVersion, input.itemId, 'imported');
+            }
+            db.prepare("UPDATE jobs SET state='succeeded',reason=NULL WHERE id=?").run(input.jobId);
+            db.prepare("UPDATE attempts SET stage='cleanup',finished_at=? WHERE id=?").run(now(), input.attemptId);
+            options.fault?.('transaction');
+            return { revisionId, duplicate: !!existing };
+        });
+        options.fault?.('committed');
+        return result;
+    }
+}

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

@@ -0,0 +1,63 @@
+import * as indexing from '../indexing/index.js';
+import * as prune from '../indexing/prune.js';
+import { hybridSearch } from '../search/hybrid.js';
+import { type Context } from './context.js';
+import type { JobKind } from './queue.js';
+import type { AttemptToken, OwnerToken } from './types.js';
+/**
+ * Embedding index generations, the index jobs that build them under the shared worker lease, retired-generation pruning
+ * and hybrid search. The generation and job SQL lives in `src/indexing/`; this is its store surface.
+ */
+export declare class SearchIndex {
+    private readonly c;
+    /** Index jobs as one `JobKind` of the queue. */
+    readonly jobs: JobKind;
+    constructor(c: Context);
+    create(options: Parameters<typeof indexing.createGeneration>[1]): indexing.GenerationStatus;
+    status(id: string): indexing.GenerationStatus;
+    inputs(id: string, limit?: number): indexing.IndexInput[];
+    writeBatch(id: string, fingerprint: string, batch: Parameters<typeof indexing.writeBatch>[3]): void;
+    activate(id: string): indexing.GenerationStatus;
+    cancel(id: string): void;
+    submitJob(generationId: string): string;
+    job(id: string): Record<string, import("node:sqlite").SQLOutputValue> | undefined;
+    claim(owner: OwnerToken, id?: string): AttemptToken | null;
+    checkpoint(token: AttemptToken, stage: string): void;
+    writeAttemptBatch(token: AttemptToken, fingerprint: string, batch: Parameters<typeof indexing.writeBatch>[3]): void;
+    /** Coverage catches up with the library before a run reads its pending inputs. */
+    refresh(token: AttemptToken): number;
+    /** A complete building generation activates; an active one stays active. Content still pending (a capture after the last
+     * batch) queues the job again, so the same drain picks it up. */
+    complete(token: AttemptToken): indexing.GenerationStatus;
+    /** The profile's active generation with its coverage and pending counts and its index job, or nulls when none is active. */
+    overview(profileId?: string): {
+        generation: null;
+        job: null;
+    } | {
+        generation: indexing.GenerationStatus;
+        job: {
+            id: string;
+            state: string;
+            reason: string | null;
+        } | null;
+    };
+    fail(token: AttemptToken, reason: string): void;
+    settle(token: AttemptToken): void;
+    /** An index attempt's staging directory is removed only when its private ownership marker names this attempt and owner. */
+    private checkStaging;
+    /** Retired-generation pruning; see src/indexing/prune.ts. The plan probes rollback inside a rolled-back savepoint. */
+    prunePlan(keep: number): {
+        generations: prune.PruneEntry[];
+        orphans: {
+            vectors: number;
+            bytes: number;
+        };
+        stats: prune.PageStats;
+    };
+    pruneStep(owner: OwnerToken, id: string, keep: number): number;
+    /** One bounded batch of embeddings no retained generation covers. Returns rows deleted; 0 means done. */
+    gcStep(owner: OwnerToken): number;
+    /** VACUUM cannot run in a transaction: fences are checked under the owner token immediately before it. */
+    vacuum(owner: OwnerToken): prune.PageStats;
+    search(query: string, options?: Parameters<typeof hybridSearch>[2]): Promise<import("../search/hybrid.js").SearchResult>;
+}