@hraness/sponge 0.2.6 → 0.3.1

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

@@ -0,0 +1,20 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { AttemptToken, OwnerToken } from './types.js';
+import type { Row } from './context.js';
+/**
+ * The one worker lease every job kind shares: `worker_owner` names the incarnation that may run attempts, and its `fence`
+ * increases on every acquisition and recovery. Every attempt records the owner and fence that claimed it, so a stale owner's
+ * write fails `owner-busy`. Storage CAS authority only: the worker separately establishes OS/process custody.
+ */
+export declare function ownerMatches(db: DatabaseSync, token: OwnerToken): void;
+/** `ownerMatches` for a caller-supplied token: its shape is checked first. */
+export declare function checkOwner(db: DatabaseSync, token: OwnerToken): void;
+export declare function ownerSnapshot(db: DatabaseSync): OwnerToken | null;
+/** A running capture attempt of the current owner, not cancelled and (with `itemId`) for that item. */
+export declare function checkAttempt(db: DatabaseSync, token: AttemptToken, itemId?: string): Row;
+/** Attempts of any kind whose cleanup is still pending. */
+export declare const pendingCleanup: (db: DatabaseSync) => number;
+/** GC must honor durable staging pins, active backup fences and every index attempt or job still in flight. */
+export declare const hasGcFence: (db: DatabaseSync) => boolean;
+/** Remove an attempt's staging directory after `check` accepts it. */
+export declare function removeStaging(root: string, attemptId: string, check: (path: string) => void): void;

package/dist/src/store/lease.js

@@ -0,0 +1,62 @@
+import { rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { integer, pathExists, text } from './files.js';
+import { syncDirectory } from '../util/fsync.js';
+import { SpongeError } from '../errors.js';
+/**
+ * The one worker lease every job kind shares: `worker_owner` names the incarnation that may run attempts, and its `fence`
+ * increases on every acquisition and recovery. Every attempt records the owner and fence that claimed it, so a stale owner's
+ * write fails `owner-busy`. Storage CAS authority only: the worker separately establishes OS/process custody.
+ */
+export function ownerMatches(db, token) {
+    const owner = db.prepare('SELECT * FROM worker_owner WHERE id=1').get();
+    if (owner?.incarnation !== token.ownerIncarnation || owner?.fence !== token.fence)
+        throw new SpongeError('owner-busy');
+}
+/** `ownerMatches` for a caller-supplied token: its shape is checked first. */
+export function checkOwner(db, token) {
+    text(token.ownerIncarnation, 256);
+    integer(token.fence);
+    ownerMatches(db, token);
+}
+export function ownerSnapshot(db) {
+    const row = 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) };
+}
+/** A running capture attempt of the current owner, not cancelled and (with `itemId`) for that item. */
+export function checkAttempt(db, token, itemId) {
+    checkOwner(db, token);
+    text(token.attemptId, 256);
+    text(token.jobId, 256);
+    const row = 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 SpongeError('owner-busy');
+    if (row.cancel_requested || row.deleted_at)
+        throw new SpongeError('cancelled');
+    if (itemId && row.item_id !== itemId)
+        throw new SpongeError('invalid-input');
+    return row;
+}
+/** Attempts of any kind whose cleanup is still pending. */
+export const pendingCleanup = (db) => Number(db
+    .prepare("SELECT (SELECT count(*) FROM attempts WHERE cleanup='pending')+(SELECT count(*) FROM index_attempts WHERE cleanup='pending') AS n")
+    .get()?.n);
+/** GC must honor durable staging pins, active backup fences and every index attempt or job still in flight. */
+export const hasGcFence = (db) => Number(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;
+/** Remove an attempt's staging directory after `check` accepts it. */
+export function removeStaging(root, attemptId, check) {
+    const path = join(root, 'staging', attemptId);
+    if (pathExists(path)) {
+        check(path);
+        rmSync(path, { recursive: true });
+        syncDirectory(dirname(path));
+    }
+}

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

@@ -0,0 +1,75 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { type Visibility } from '../identity/visibility.js';
+import { Queue } from './queue.js';
+import { Blobs } from './blobs.js';
+import { Revisions } from './revisions.js';
+import { Derivations } from './derivations.js';
+import { Annotations } from './annotations.js';
+import { SearchIndex } from './search-index.js';
+import { Backups } from './backups.js';
+import { Imports } from './imports.js';
+import type { ReadableItem, StoreOptions } from './types.js';
+export interface TitleState {
+    title: string;
+    override: string | null;
+    default: string;
+    source: 'override' | 'note' | 'capture';
+}
+/**
+ * The library: items at the top level, and one module per concern, each owning its SQL. Every module shares the one
+ * connection; user-state writes go through `mutate` (src/store/changes.ts) inside the module's own transaction.
+ * Storage CAS authority only. The worker separately establishes OS/process custody.
+ */
+export declare class LibraryStore {
+    readonly root: string;
+    private closed;
+    private readonly db;
+    /** Capture jobs and the worker lease shared by every job kind. */
+    readonly queue: Queue;
+    readonly blobs: Blobs;
+    readonly revisions: Revisions;
+    readonly derivations: Derivations;
+    readonly annotations: Annotations;
+    /** Embedding index generations, index jobs, pruning and hybrid search. */
+    readonly index: SearchIndex;
+    readonly backups: Backups;
+    readonly imports: Imports;
+    constructor(root: string, db: DatabaseSync, options: StoreOptions);
+    close(): void;
+    /** Increases with readable revision changes and tombstones, never with an identical refresh. */
+    get revisionEpoch(): number;
+    list(): {
+        itemId: string;
+        kind: string;
+        title: string;
+        revisionId: string | null;
+    }[];
+    read(itemId: string): ReadableItem | null;
+    /** Lexical search; the query is a literal FTS phrase. Hybrid search is `index.search`. */
+    search(query: string, count?: number): {
+        itemId: string;
+        title: string;
+        revisionId: string;
+    }[];
+    /** Tombstone the item and cancel its open jobs. Blobs stay until GC. */
+    delete(itemId: string): void;
+    /** Sync and publishing foundation; see docs/decisions/sync-and-publishing.md. */
+    identity(itemId: string): {
+        uris: import("../identity/uri.js").ItemUri[];
+        visibility: import("../identity/visibility.js").VisibilityState;
+    };
+    itemsForUri(uri: string): string[];
+    setVisibility(itemId: string, value: Visibility | null): import("../identity/visibility.js").VisibilityState;
+    /** The shown title and where it comes from: the user's override, else the importer's note title, else the captured title. */
+    title(itemId: string): TitleState;
+    /** Set the user's title (`null` restores the default). Logged as `item.titleOverride`; refresh and import never change it. */
+    setTitle(itemId: string, value: string | null): TitleState;
+    listChanges(after?: number, limit?: number): import("./changes.js").LoggedChange[];
+    publicProjection(): {
+        entries: import("../publish/projection.js").PublicEntry[];
+        skipped: {
+            itemId: string;
+            reason: string;
+        }[];
+    };
+}

package/dist/src/store/library.js

@@ -0,0 +1,174 @@
+import { integer, text } from './files.js';
+import { listChanges, mutate } from './changes.js';
+import { itemUris, itemsForUri, setVisibility, visibility } from '../identity/visibility.js';
+import { publicProjection } from '../publish/projection.js';
+import { lexicalSearch, unindexReadable } from '../search/lexical.js';
+import { trackLibrary } from '../indexing/index.js';
+import { bumpEpoch, now, revisionEpoch, transaction } from './context.js';
+import { Queue } from './queue.js';
+import { Blobs } from './blobs.js';
+import { Revisions } from './revisions.js';
+import { Derivations } from './derivations.js';
+import { Annotations } from './annotations.js';
+import { SearchIndex } from './search-index.js';
+import { Backups } from './backups.js';
+import { Imports } from './imports.js';
+import { validateMetadataWarnings } from '../../contracts/validate.js';
+import { SpongeError } from '../errors.js';
+/**
+ * The library: items at the top level, and one module per concern, each owning its SQL. Every module shares the one
+ * connection; user-state writes go through `mutate` (src/store/changes.ts) inside the module's own transaction.
+ * Storage CAS authority only. The worker separately establishes OS/process custody.
+ */
+export class LibraryStore {
+    root;
+    closed = false;
+    db;
+    /** Capture jobs and the worker lease shared by every job kind. */
+    queue;
+    blobs;
+    revisions;
+    derivations;
+    annotations;
+    /** Embedding index generations, index jobs, pruning and hybrid search. */
+    index;
+    backups;
+    imports;
+    constructor(root, db, options) {
+        this.root = root;
+        const c = { root, db, options };
+        this.db = db;
+        this.index = new SearchIndex(c);
+        this.queue = new Queue(c, this.index.jobs);
+        this.blobs = new Blobs(c);
+        this.revisions = new Revisions(c);
+        this.derivations = new Derivations(c);
+        this.annotations = new Annotations(c);
+        this.backups = new Backups(c);
+        this.imports = new Imports(c);
+    }
+    close() {
+        if (!this.closed) {
+            this.db.close();
+            this.closed = true;
+        }
+    }
+    /** Increases with readable revision changes and tombstones, never with an identical refresh. */
+    get revisionEpoch() {
+        return revisionEpoch(this.db);
+    }
+    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 };
+    }
+    /** Lexical search; the query is a literal FTS phrase. Hybrid search is `index.search`. */
+    search(query, count = 20) {
+        text(query, 4096);
+        integer(count, 100);
+        return lexicalSearch(this.db, query, count).map(({ itemId, title, revisionId }) => ({ itemId, title, revisionId }));
+    }
+    /** Tombstone the item and cancel its open jobs. Blobs stay until GC. */
+    delete(itemId) {
+        text(itemId, 256);
+        transaction(this.db, () => {
+            const row = this.db.prepare('SELECT 1 FROM items WHERE id=? AND deleted_at IS NULL').get(itemId);
+            if (row) {
+                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);
+                bumpEpoch(this.db);
+                trackLibrary(this.db);
+            }
+        });
+    }
+    /** Sync and publishing foundation; see docs/decisions/sync-and-publishing.md. */
+    identity(itemId) {
+        text(itemId, 256);
+        return { uris: itemUris(this.db, itemId), visibility: visibility(this.db, itemId) };
+    }
+    itemsForUri(uri) {
+        return itemsForUri(this.db, uri);
+    }
+    setVisibility(itemId, value) {
+        text(itemId, 256);
+        return transaction(this.db, () => setVisibility(this.db, itemId, value));
+    }
+    /** The shown title and where it comes from: the user's override, else the importer's note title, else the captured title. */
+    title(itemId) {
+        text(itemId, 256);
+        const r = this.db
+            .prepare('SELECT title,title_captured,title_note,title_override FROM items WHERE id=? AND deleted_at IS NULL')
+            .get(itemId);
+        if (!r)
+            throw new SpongeError('unavailable');
+        return {
+            title: String(r.title),
+            override: r.title_override === null ? null : String(r.title_override),
+            default: String(r.title_note ?? r.title_captured),
+            source: r.title_override !== null ? 'override' : r.title_note !== null ? 'note' : 'capture',
+        };
+    }
+    /** Set the user's title (`null` restores the default). Logged as `item.titleOverride`; refresh and import never change it. */
+    setTitle(itemId, value) {
+        text(itemId, 256);
+        const title = value === null ? null : value.trim();
+        if (title !== null)
+            text(title, 4096);
+        return transaction(this.db, () => {
+            if (this.title(itemId).override !== title)
+                mutate(this.db, 'item', itemId, 'titleOverride', title);
+            return this.title(itemId);
+        });
+    }
+    listChanges(after = 0, limit = 500) {
+        return listChanges(this.db, after, limit);
+    }
+    publicProjection() {
+        return publicProjection(this.db);
+    }
+}

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

@@ -0,0 +1,7 @@
+import { LibraryStore } from './library.js';
+import type { StoreOptions } from './types.js';
+/** Pre-migration snapshots kept after a successful upgrade; older ones are pruned only then. */
+export declare const keptSchemaBackups = 3;
+/** The schema version this build reads and writes. */
+export declare const libraryVersion: number;
+export declare function openLibrary(path: string, options?: StoreOptions): Promise<LibraryStore>;

package/dist/src/store/open.js

@@ -0,0 +1,183 @@
+import { DatabaseSync, backup } from 'node:sqlite';
+import { chmodSync, closeSync, constants, fsyncSync, lstatSync, openSync, readdirSync, rmSync, writeFileSync, } from 'node:fs';
+import { join, dirname, parse } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { migrations, schemaVersion } from '../../migrations/index.js';
+import { confinedFile, pathExists, regularFile, safeDirectory, verifyFile } from './files.js';
+import { sha256 } from '../util/hash.js';
+import { syncDirectory } from '../util/fsync.js';
+import { now } from './context.js';
+import { LibraryStore } from './library.js';
+import { initializeVectorExtension } from '../search/extension.js';
+import { acquireIdentityLock } from '../worker/lock.js';
+import { SpongeError } from '../errors.js';
+/** Pre-migration snapshots kept after a successful upgrade; older ones are pruned only then. */
+export const keptSchemaBackups = 3;
+/** The schema version this build reads and writes. */
+export const libraryVersion = schemaVersion;
+const checksum = (version) => sha256(migrations[version - 1].sql);
+export async function openLibrary(path, options = {}) {
+    if (path === parse(path).root)
+        throw new SpongeError('invalid-input');
+    const root = safeDirectory(path, true);
+    if (root === parse(root).root)
+        throw new SpongeError('invalid-input');
+    const marker = join(root, '.sponge-library'), dbPath = confinedFile(root, join(root, 'library.sqlite'));
+    if (pathExists(marker)) {
+        regularFile(marker);
+        verifyFile(marker, sha256('sponge-library-v1\n'), Buffer.byteLength('sponge-library-v1\n'));
+    }
+    else if (readdirSync(root).length)
+        throw new SpongeError('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) > schemaVersion)
+                throw new SpongeError('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 > schemaVersion)
+            throw new SpongeError('schema-newer');
+        if (current < schemaVersion) {
+            // The lock names its holder; only exact proof that the holder died lets a later opener take it over.
+            let lock;
+            try {
+                lock = await acquireIdentityLock(join(root, 'runtime', 'migration.lock'));
+            }
+            catch (error) {
+                const code = error.code;
+                if (code === 'owner-busy' || code === 'unavailable')
+                    throw new SpongeError(code);
+                throw error;
+            }
+            let migrated = false;
+            try {
+                options.fault?.('migration');
+                // Recheck under the migration lock: another opener may already have migrated.
+                const actual = Number(db.prepare('PRAGMA user_version').get()?.user_version);
+                if (actual > schemaVersion)
+                    throw new SpongeError('schema-newer');
+                if (actual === 0 && db.prepare("SELECT name FROM sqlite_schema WHERE name NOT LIKE 'sqlite_%'").all().length)
+                    throw new SpongeError('integrity');
+                for (let prior = 1; prior <= actual; prior++) {
+                    if (db.prepare('SELECT checksum FROM schema_migrations WHERE version=?').get(prior)?.checksum !==
+                        checksum(prior))
+                        throw new SpongeError('integrity');
+                }
+                if (actual > 0 &&
+                    db.prepare('SELECT schema_version FROM library_info WHERE id=1').get()?.schema_version !== actual)
+                    throw new SpongeError('integrity');
+                let backupPath;
+                try {
+                    if (actual < schemaVersion) {
+                        // SQLite backup incorporates WAL; never copy the main file alone.
+                        backupPath = join(root, 'backups', `before-schema-${schemaVersion}-${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 (const migration of migrations.slice(actual)) {
+                        const target = migration.version;
+                        db.exec('BEGIN IMMEDIATE');
+                        try {
+                            // A taken-over lock is a CAS on files only; the schema step itself must still start from target-1.
+                            if (Number(db.prepare('PRAGMA user_version').get()?.user_version) !== target - 1)
+                                throw new SpongeError('owner-busy');
+                            db.exec(migration.sql);
+                            migration.step?.(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, checksum(target), now());
+                            db.exec(`PRAGMA user_version=${target}; COMMIT`);
+                        }
+                        catch (error) {
+                            db.exec('ROLLBACK');
+                            throw error;
+                        }
+                    }
+                    migrated = true;
+                }
+                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 {
+                await lock.release();
+            }
+            if (migrated)
+                pruneSchemaBackups(root);
+        }
+        for (let applied = 1; applied <= schemaVersion; applied++)
+            if (db.prepare('SELECT checksum FROM schema_migrations WHERE version=?').get(applied)?.checksum !==
+                checksum(applied))
+                throw new SpongeError('integrity');
+        if (db.prepare('SELECT schema_version FROM library_info WHERE id=1').get()?.schema_version !== schemaVersion)
+            throw new SpongeError('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);
+        const store = new LibraryStore(root, db, options);
+        await store.backups.expireFences();
+        return store;
+    }
+    catch (error) {
+        db.close();
+        throw error;
+    }
+}
+/** Keep the newest `keptSchemaBackups` pre-migration snapshots (by mtime, then name); remove older ones and their sidecars. */
+function pruneSchemaBackups(root) {
+    const dir = join(root, 'backups'), files = readdirSync(dir)
+        .filter((n) => /^before-schema-\d+-[0-9a-f-]{36}\.sqlite$/.test(n))
+        .map((name) => ({ name, mtime: lstatSync(join(dir, name)).mtimeMs }));
+    files.sort((a, b) => b.mtime - a.mtime || b.name.localeCompare(a.name));
+    for (const { name } of files.slice(keptSchemaBackups))
+        for (const suffix of ['', '-wal', '-shm'])
+            rmSync(join(dir, name + suffix), { force: true });
+    if (files.length > keptSchemaBackups)
+        syncDirectory(dir);
+}

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

@@ -0,0 +1,65 @@
+import type { JobCheckpoint } from '../../contracts/index.js';
+import { type Context, type Row } from './context.js';
+import type { AttemptToken, OwnedAttempt, OwnerToken, SourceSubmission, Submission } from './types.js';
+export interface RetryOptions {
+    notBefore?: string;
+    automatic?: boolean;
+}
+/**
+ * One kind of job under the shared worker lease. Capture jobs live here; index jobs in `search-index.ts`. The queue dispatches
+ * listing, cancellation, retry and owner recovery through this interface, so a new job kind plugs in without new branches.
+ */
+export interface JobKind {
+    owns(jobId: string): boolean;
+    list(): Row[];
+    /** Attempts claimed by `token` (the owner is already checked). */
+    attempts(token: OwnerToken): OwnedAttempt[];
+    cancel(jobId: string): void;
+    retry(jobId: string, options: RetryOptions): void;
+    cancelRequested(jobId: string): boolean;
+    /** Inside `recoverOwner`'s transaction, once custody of the attempt is proved: remove its staging and settle it. */
+    recover(attempt: OwnedAttempt): void;
+}
+/** Capture jobs (acquire, extract, commit one source) and the owner lease shared with every other job kind. */
+export declare class Queue {
+    private readonly c;
+    private readonly index;
+    private readonly capture;
+    constructor(c: Context, index: JobKind);
+    /** Index jobs are checked first; any other id is a capture job (which reports `unavailable` when it does not exist). */
+    private kindOf;
+    acquireOwner(ownerIncarnation: string): OwnerToken;
+    releaseOwner(token: OwnerToken): void;
+    ownerSnapshot(): OwnerToken | null;
+    /** Every attempt the owner claimed, capture first, then index. */
+    ownerAttempts(token: OwnerToken): OwnedAttempt[];
+    /** 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: OwnerToken, provedAttemptIds: readonly string[]): void;
+    /** Deduplicates source identity including realm and persists an idempotent submission and queued job. */
+    submit(input: SourceSubmission): Submission;
+    /** Jobs of every kind, oldest first. */
+    list(): Row[];
+    /** 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: string): {
+        itemId: string;
+        kind: string;
+        sourceKey: string;
+        locator: string;
+        realm: string;
+    } | null;
+    claimNext(token: OwnerToken): AttemptToken | null;
+    claim(token: OwnerToken, jobId: string): AttemptToken;
+    checkpoint(token: AttemptToken, stage: JobCheckpoint['stage']): void;
+    cancelRequested(jobId: string): boolean;
+    retry(jobId: string, options?: RetryOptions): void;
+    cancel(jobId: string): void;
+    fail(token: AttemptToken, reason?: string, options?: {
+        retryable?: boolean;
+        retryAfterMs?: number;
+    }): void;
+    /** Caller must first settle owned external children. This only releases storage staging pins. */
+    settle(token: AttemptToken): void;
+    /** Attempts of any kind whose cleanup is pending; GC and pruning wait for zero. */
+    pendingCleanup(): number;
+}