@hraness/sponge 0.2.5 → 0.3.0

package/dist/src/store/changes.js

@@ -1,19 +1,27 @@
 import { randomUUID } from 'node:crypto';
-import { StoreError } from './types.js';
-import { digest } from './files.js';
+import { sha256 } from '../util/hash.js';
+import { kindOf } from '../derivations/kinds.js';
+import { SpongeError } from '../errors.js';
+import { indexReadable } from '../search/lexical.js';
+import { isFileLocator } from './ids.js';
 const now = () => new Date().toISOString();
-const fail = (code = 'invalid-input') => { throw new StoreError(code); };
+const fail = (code = 'invalid-input') => {
+    throw new SpongeError(code);
+};
 /** Bound on one change's JSON; imported note bodies (64 KiB) plus anchors fit with room for escaping. */
-export const maxChangeBytes = 262144;
+const maxChangeBytes = 262144;
 /** Hybrid logical clock `ms.counter.device`: zero-padded so every device sorts the strings alike. */
 function tick(db) {
     const row = db.prepare('SELECT device_id,clock_ms,clock_counter FROM device WHERE id=1').get() ?? fail('integrity');
     const wall = Date.now(), prior = Number(row.clock_ms), ms = Math.max(wall, prior), counter = ms === prior ? Number(row.clock_counter) + 1 : 0;
     db.prepare('UPDATE device SET clock_ms=?,clock_counter=? WHERE id=1').run(ms, counter);
-    return { deviceId: String(row.device_id), hlc: `${String(ms).padStart(15, '0')}.${String(counter).padStart(9, '0')}.${row.device_id}` };
+    return {
+        deviceId: String(row.device_id),
+        hlc: `${String(ms).padStart(15, '0')}.${String(counter).padStart(9, '0')}.${row.device_id}`,
+    };
 }
 /** Append without applying: for state that already exists (seeding). Callers hold the write transaction. */
-export function append(db, change) {
+function append(db, change) {
     const { deviceId, hlc } = tick(db);
     db.prepare('INSERT INTO changes(id,device_id,hlc,entity,entity_id,field,value_json,created_at) VALUES(?,?,?,?,?,?,?,?)').run(randomUUID(), deviceId, hlc, change.entity, change.entityId, change.field, JSON.stringify(change.value ?? null), now());
 }
@@ -28,54 +36,38 @@ export function mutate(db, entity, entityId, field, value) {
 export function listChanges(db, after = 0, limit = 500) {
     if (!Number.isSafeInteger(after) || after < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > 5000)
         fail();
-    return db.prepare('SELECT * FROM changes WHERE seq>? ORDER BY seq LIMIT ?').all(after, limit).map(r => ({ seq: Number(r.seq), id: String(r.id), deviceId: String(r.device_id), hlc: String(r.hlc), entity: r.entity, entityId: String(r.entity_id), field: String(r.field), value: JSON.parse(String(r.value_json)) }));
+    return db
+        .prepare('SELECT * FROM changes WHERE seq>? ORDER BY seq LIMIT ?')
+        .all(after, limit)
+        .map((r) => ({
+        seq: Number(r.seq),
+        id: String(r.id),
+        deviceId: String(r.device_id),
+        hlc: String(r.hlc),
+        entity: r.entity,
+        entityId: String(r.entity_id),
+        field: String(r.field),
+        value: JSON.parse(String(r.value_json)),
+    }));
 }
 const object = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
 const str = (v, max = 65536) => typeof v === 'string' && v.length > 0 && Buffer.byteLength(v) <= max;
 const optional = (v, max = 256) => v === null || str(v, max);
 const status = (v) => v === null || v === 'accepted' || v === 'rejected';
 /** Deterministic source-ref id, so replayed item creation yields the same row on every device. */
-export const sourceRefId = (itemId) => digest(JSON.stringify(['source-ref-v1', itemId]));
-const parsed = (json) => { try {
-    return JSON.parse(String(json));
-}
-catch {
-    return String(json);
-} };
-const changed = (r) => { if (!Number(r.changes))
-    fail('unavailable'); };
-/**
- * Review JSON in one canonical shape, whatever order its paths were written in. A digest is reviewed per field;
- * an editorial derivation (a reviewed source note kept whole) has one path, `review.note`.
- */
-export function setReviewPath(review, output, path, value, kind = 'digest') {
-    if (kind === 'editorial') {
-        if (path !== 'review.note')
-            fail();
-        return value ? { note: value } : {};
+export const sourceRefId = (itemId) => sha256(JSON.stringify(['source-ref-v1', itemId]));
+const parsed = (json) => {
+    try {
+        return JSON.parse(String(json));
     }
-    if (kind !== 'digest')
-        fail();
-    const ideas = output.ideas.map((_, i) => review.ideas?.[i] ?? null);
-    const quotes = output.ideas.map((idea, i) => idea.quotes.map((_, j) => review.quotes?.[i]?.[j] ?? null));
-    let gist = review.gist ?? null;
-    const m = /^review\.(?:(gist)|ideas\.(\d{1,2})|quotes\.(\d{1,2})\.(\d{1,2}))$/.exec(path) ?? fail();
-    if (m[1])
-        gist = value;
-    else if (m[2] !== undefined) {
-        const i = Number(m[2]);
-        if (i >= ideas.length)
-            fail();
-        ideas[i] = value;
+    catch {
+        return String(json);
     }
-    else {
-        const i = Number(m[3]), j = Number(m[4]);
-        if (i >= quotes.length || j >= quotes[i].length)
-            fail();
-        quotes[i][j] = value;
-    }
-    return { ...(gist ? { gist } : {}), ...(ideas.some(v => v) ? { ideas } : {}), ...(quotes.some(q => q.some(v => v)) ? { quotes } : {}) };
-}
+};
+const changed = (r) => {
+    if (!Number(r.changes))
+        fail('unavailable');
+};
 /**
  * Map one change onto its row. Table-driven: every user-state field Sponge writes is listed here,
  * and nothing else writes those columns. Objects (revisions, derivation outputs) must already exist.
@@ -87,7 +79,13 @@ export function applyChange(db, change) {
         fail();
     switch (`${entity}.${field.startsWith('review.') ? 'review' : field}`) {
         case 'item.created': {
-            if (!object(v) || !['article', 'pdf', 'media'].includes(v.kind) || !str(v.createdAt, 64) || !optional(v.sourceKey, 8192) || !(v.realm === null || typeof v.realm === 'string' && Buffer.byteLength(v.realm) <= 256) || !optional(v.locator, 16384))
+            if (!object(v) ||
+                !['article', 'pdf', 'media'].includes(v.kind) ||
+                !str(v.createdAt, 64) ||
+                !optional(v.sourceKey, 8192) ||
+                !(v.realm === null || (typeof v.realm === 'string' && Buffer.byteLength(v.realm) <= 256)) ||
+                !optional(v.locator, 16384) ||
+                (v.locator !== null && isFileLocator(v.locator)))
                 fail();
             db.prepare('INSERT INTO items(id,kind,created_at) VALUES(?,?,?) ON CONFLICT(id) DO NOTHING').run(id, v.kind, v.createdAt);
             if (v.sourceKey !== null && v.locator !== null)
@@ -100,10 +98,19 @@ export function applyChange(db, change) {
             if (v !== null && !db.prepare('SELECT 1 FROM revisions WHERE id=? AND item_id=?').get(v, id))
                 fail('unavailable');
             return changed(db.prepare('UPDATE items SET current_revision=? WHERE id=?').run(v, id));
-        case 'item.title':
+        case 'item.capturedTitle':
             if (typeof v !== 'string' || Buffer.byteLength(v) > 4096)
                 fail();
-            return changed(db.prepare('UPDATE items SET title=? WHERE id=?').run(v, id));
+            changed(db.prepare('UPDATE items SET title_captured=? WHERE id=?').run(v, id));
+            return refreshTitle(db, id);
+        case 'item.noteTitle':
+        case 'item.titleOverride':
+            if (!optional(v, 4096))
+                fail();
+            changed(db
+                .prepare(`UPDATE items SET ${field === 'noteTitle' ? 'title_note' : 'title_override'}=? WHERE id=?`)
+                .run(v, id));
+            return refreshTitle(db, id);
         case 'item.visibility':
             if (v !== null && v !== 'public' && v !== 'private')
                 fail();
@@ -113,7 +120,14 @@ export function applyChange(db, change) {
                 fail();
             return changed(db.prepare('UPDATE items SET deleted_at=COALESCE(deleted_at,?) WHERE id=?').run(v, id));
         case 'annotation.created':
-            if (!object(v) || !str(v.itemId, 256) || !['note', 'highlight', 'comment'].includes(v.kind) || !optional(v.revisionId) || !optional(v.parentId) || typeof v.body !== 'string' || !str(v.createdAt, 64) || !('anchor' in v))
+            if (!object(v) ||
+                !str(v.itemId, 256) ||
+                !['note', 'highlight', 'comment'].includes(v.kind) ||
+                !optional(v.revisionId) ||
+                !optional(v.parentId) ||
+                typeof v.body !== 'string' ||
+                !str(v.createdAt, 64) ||
+                !('anchor' in v))
                 fail();
             db.prepare('INSERT INTO annotations(id,item_id,revision_id,anchor_json,body,created_at,kind,parent_id) VALUES(?,?,?,?,?,?,?,?) ON CONFLICT(id) DO NOTHING').run(id, v.itemId, v.revisionId, JSON.stringify(v.anchor), v.body, v.createdAt, v.kind, v.parentId);
             return;
@@ -134,12 +148,31 @@ export function applyChange(db, change) {
             if (!status(v))
                 fail();
             const row = db.prepare('SELECT kind,output_json,review_json FROM derivations WHERE id=?').get(id) ?? fail('unavailable');
-            db.prepare('UPDATE derivations SET review_json=? WHERE id=?').run(JSON.stringify(setReviewPath(JSON.parse(String(row.review_json)), JSON.parse(String(row.output_json)), field, v, String(row.kind))), id);
+            db.prepare('UPDATE derivations SET review_json=? WHERE id=?').run(JSON.stringify(kindOf(row.kind).applyReview(JSON.parse(String(row.review_json)), JSON.parse(String(row.output_json)), field, v)), id);
             return;
         }
-        default: fail();
+        default:
+            fail();
     }
 }
+/**
+ * `items.title` is derived: the user's override, else an importer's owner title, else the captured title. A changed title
+ * is re-indexed for lexical search at once; replay on a device without the FTS row leaves indexing to capture.
+ */
+export function refreshTitle(db, id) {
+    const row = db.prepare('SELECT title,COALESCE(title_override,title_note,title_captured) next FROM items WHERE id=?').get(id) ??
+        fail('unavailable');
+    if (row.title === row.next)
+        return;
+    db.prepare('UPDATE items SET title=? WHERE id=?').run(String(row.next), id);
+    const fts = db
+        .prepare("SELECT m.revision_id,p.markdown FROM readable_fts_rows m JOIN representations p ON p.revision_id=m.revision_id AND p.kind='markdown' WHERE m.item_id=?")
+        .get(id);
+    if (fts && typeof fts.markdown === 'string')
+        indexReadable(db, id, String(fts.revision_id), String(row.next), fts.markdown);
+}
+/** Title fields across schemas: schema 5 logged `title`, schema 9 split it (migration 9 renames the old entries). */
+const titleFields = ['title', 'capturedTitle', 'noteTitle', 'titleOverride'];
 /**
  * Seed the log with user state written before schema 5, so another device can rebuild it.
  * Idempotent: a field that already has a change is never seeded again. Rows already exist, so this appends only.
@@ -147,14 +180,25 @@ export function applyChange(db, change) {
 export function seedChanges(db) {
     let count = 0;
     const seed = (entity, entityId, field, value) => {
-        if (db.prepare('SELECT 1 FROM changes WHERE entity=? AND entity_id=? AND field=? LIMIT 1').get(entity, entityId, field))
+        const fields = field === 'title' ? titleFields : [field];
+        if (db
+            .prepare(`SELECT 1 FROM changes WHERE entity=? AND entity_id=? AND field IN (${fields.map(() => '?').join(',')}) LIMIT 1`)
+            .get(entity, entityId, ...fields))
             return;
         append(db, { entity, entityId, field, value });
         count++;
     };
     for (const i of db.prepare('SELECT * FROM items ORDER BY created_at,rowid').all()) {
-        const id = String(i.id), source = db.prepare('SELECT source_key,realm_key,locator FROM source_refs WHERE item_id=? ORDER BY rowid LIMIT 1').get(id);
-        seed('item', id, 'created', { kind: i.kind, sourceKey: source ? String(source.source_key) : null, realm: source ? String(source.realm_key) : null, locator: source ? String(source.locator) : null, createdAt: String(i.created_at) });
+        const id = String(i.id), source = db
+            .prepare('SELECT source_key,realm_key,locator FROM source_refs WHERE item_id=? ORDER BY rowid LIMIT 1')
+            .get(id);
+        seed('item', id, 'created', {
+            kind: i.kind,
+            sourceKey: source ? String(source.source_key) : null,
+            realm: source ? String(source.realm_key) : null,
+            locator: source ? String(source.locator) : null,
+            createdAt: String(i.created_at),
+        });
         if (i.current_revision !== null)
             seed('item', id, 'currentRevision', String(i.current_revision));
         if (i.title !== '')
@@ -166,7 +210,15 @@ export function seedChanges(db) {
     }
     for (const a of db.prepare('SELECT * FROM annotations ORDER BY parent_id IS NOT NULL,created_at,rowid').all()) {
         const id = String(a.id);
-        seed('annotation', id, 'created', { itemId: String(a.item_id), kind: a.kind, revisionId: a.revision_id ?? null, parentId: a.parent_id ?? null, anchor: parsed(a.anchor_json), body: String(a.body), createdAt: String(a.created_at) });
+        seed('annotation', id, 'created', {
+            itemId: String(a.item_id),
+            kind: a.kind,
+            revisionId: a.revision_id ?? null,
+            parentId: a.parent_id ?? null,
+            anchor: parsed(a.anchor_json),
+            body: String(a.body),
+            createdAt: String(a.created_at),
+        });
         if (a.updated_at !== null)
             seed('annotation', id, 'body', { body: String(a.body), updatedAt: String(a.updated_at) });
         if (a.deleted_at !== null)

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

@@ -0,0 +1,15 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { StoreOptions } from './types.js';
+export type Row = Record<string, any>;
+export declare const now: () => string;
+/** What every store module shares: the canonical library root, the one connection, and the fault hooks. */
+export interface Context {
+    readonly root: string;
+    readonly db: DatabaseSync;
+    readonly options: StoreOptions;
+}
+/** The store's write boundary: one `BEGIN IMMEDIATE` per call, committed only if `fn` returns. Never nested. */
+export declare function transaction<T>(db: DatabaseSync, fn: () => T): T;
+/** Increases with readable revision changes and tombstones, never with an identical refresh. */
+export declare const revisionEpoch: (db: DatabaseSync) => number;
+export declare const bumpEpoch: (db: DatabaseSync) => void;

package/dist/src/store/context.js

@@ -0,0 +1,19 @@
+export const now = () => new Date().toISOString();
+/** The store's write boundary: one `BEGIN IMMEDIATE` per call, committed only if `fn` returns. Never nested. */
+export function transaction(db, fn) {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const result = fn();
+        db.exec('COMMIT');
+        return result;
+    }
+    catch (error) {
+        db.exec('ROLLBACK');
+        throw error;
+    }
+}
+/** Increases with readable revision changes and tombstones, never with an identical refresh. */
+export const revisionEpoch = (db) => Number(db.prepare('SELECT revision_epoch FROM library_info WHERE id=1').get()?.revision_epoch);
+export const bumpEpoch = (db) => {
+    db.exec('UPDATE library_info SET revision_epoch=revision_epoch+1 WHERE id=1');
+};

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

@@ -0,0 +1,42 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { type DerivationOf, type Kind, type KindTypes } from '../derivations/kinds.js';
+import type { PublicDigest } from '../derivations/types.js';
+import { type Context } from './context.js';
+/** What storing a derivation of kind `K` takes: its item, revision and producer, plus the kind's own candidate. */
+export type PutDerivation<K extends Kind> = {
+    itemId: string;
+    revisionId: string;
+    producer: Record<string, unknown>;
+} & KindTypes[K]['candidate'];
+/** Content address of a derivation: the same output from the same input is the same immutable object on every device. */
+export declare const derivationId: (revisionId: string, kind: string, inputHash: string, output: string) => string;
+/**
+ * Store a derivation the kind admits against the revision it was made from. Derivations are immutable data, not change-log
+ * entries: a different output is a new object, the same output a duplicate.
+ */
+export declare function putDerivation<K extends Kind>(db: DatabaseSync, kind: K, input: PutDerivation<K>): {
+    id: string;
+    duplicate: boolean;
+};
+/** Review fields of a derivation: each changed path the kind names is its own logged change. */
+export declare function reviewDerivation<K extends Kind>(db: DatabaseSync, kind: K, id: string, input: KindTypes[K]['review']): DerivationOf<K>;
+/**
+ * The public digest of an item, from the first kind in `publishOrder` with a current derivation and never from two: the
+ * accepted fields of the current digest (v2, or a stored v1), else the public subset of an accepted editorial note (lead,
+ * claims, verbatim quotes within the v2 limits). Never attributions, and never the note's other content.
+ */
+export declare function publicDerivation(db: DatabaseSync, itemId: string): PublicDigest | undefined;
+/** Derived objects (digests, editorial notes) of the library's revisions, by kind. */
+export declare class Derivations {
+    private readonly c;
+    constructor(c: Context);
+    put<K extends Kind>(kind: K, input: PutDerivation<K>): {
+        id: string;
+        duplicate: boolean;
+    };
+    read<K extends Kind>(kind: K, id: string): DerivationOf<K> | undefined;
+    current<K extends Kind>(kind: K, itemId: string): DerivationOf<K> | undefined;
+    /** The newest stored derivation for exactly these inputs, so a rerun reuses it instead of asking the model again. */
+    find<K extends Kind>(kind: K, revisionId: string, inputHash: string): DerivationOf<K> | undefined;
+    review<K extends Kind>(kind: K, id: string, input: KindTypes[K]['review']): DerivationOf<K>;
+}

package/dist/src/store/derivations.js

@@ -0,0 +1,104 @@
+import { markdownFor } from '../annotations/store.js';
+import { derivationKinds, publishOrder } from '../derivations/kinds.js';
+import { hash, text } from './files.js';
+import { sha256 } from '../util/hash.js';
+import { mutate } from './changes.js';
+import { now, transaction } from './context.js';
+import { SpongeError } from '../errors.js';
+const fail = (code = 'invalid-input') => {
+    throw new SpongeError(code);
+};
+/** Content address of a derivation: the same output from the same input is the same immutable object on every device. */
+export const derivationId = (revisionId, kind, inputHash, output) => sha256(JSON.stringify(['derivation-v1', revisionId, kind, inputHash, output]));
+const row = (r) => ({
+    id: String(r.id),
+    itemId: String(r.item_id),
+    revisionId: String(r.revision_id),
+    kind: String(r.kind),
+    producer: JSON.parse(String(r.producer_json)),
+    inputHash: String(r.input_hash),
+    output: JSON.parse(String(r.output_json)),
+    review: JSON.parse(String(r.review_json)),
+    createdAt: String(r.created_at),
+});
+/**
+ * Store a derivation the kind admits against the revision it was made from. Derivations are immutable data, not change-log
+ * entries: a different output is a new object, the same output a duplicate.
+ */
+export function putDerivation(db, kind, input) {
+    const producer = JSON.stringify(input.producer);
+    if (!producer || Buffer.byteLength(producer) > 4096)
+        fail();
+    if (db.prepare('SELECT item_id FROM revisions WHERE id=?').get(input.revisionId)?.item_id !== input.itemId)
+        fail('unavailable');
+    const admitted = derivationKinds[kind].admit(input, () => markdownFor(db, input.revisionId));
+    const id = derivationId(input.revisionId, kind, admitted.inputHash, admitted.output);
+    if (db.prepare('SELECT 1 FROM derivations WHERE id=?').get(id))
+        return { id, duplicate: true };
+    db.prepare('INSERT INTO derivations(id,item_id,revision_id,kind,schema_version,producer_json,input_hash,output_json,created_at) VALUES(?,?,?,?,?,?,?,?,?)').run(id, input.itemId, input.revisionId, kind, admitted.schemaVersion, producer, admitted.inputHash, admitted.output, now());
+    return { id, duplicate: false };
+}
+function readDerivation(db, kind, id) {
+    const r = db.prepare('SELECT * FROM derivations WHERE id=? AND kind=?').get(id, kind);
+    return r ? row(r) : undefined;
+}
+/** The newest derivation of this kind made from the item's current revision. */
+function currentDerivation(db, kind, itemId) {
+    const r = db
+        .prepare('SELECT d.* FROM derivations d JOIN items i ON i.id=d.item_id AND i.current_revision=d.revision_id WHERE d.item_id=? AND d.kind=? ORDER BY d.created_at DESC,d.rowid DESC LIMIT 1')
+        .get(itemId, kind);
+    return r ? row(r) : undefined;
+}
+/** Review fields of a derivation: each changed path the kind names is its own logged change. */
+export function reviewDerivation(db, kind, id, input) {
+    const d = readDerivation(db, kind, id) ?? fail('unavailable');
+    for (const [path, value] of derivationKinds[kind].reviewPaths(d, input))
+        mutate(db, 'derivation', id, path, value);
+    return readDerivation(db, kind, id);
+}
+/**
+ * The public digest of an item, from the first kind in `publishOrder` with a current derivation and never from two: the
+ * accepted fields of the current digest (v2, or a stored v1), else the public subset of an accepted editorial note (lead,
+ * claims, verbatim quotes within the v2 limits). Never attributions, and never the note's other content.
+ */
+export function publicDerivation(db, itemId) {
+    for (const kind of publishOrder) {
+        const d = currentDerivation(db, kind, itemId);
+        if (d)
+            return derivationKinds[kind].publish?.(d, () => markdownFor(db, d.revisionId));
+    }
+    return undefined;
+}
+/** Derived objects (digests, editorial notes) of the library's revisions, by kind. */
+export class Derivations {
+    c;
+    constructor(c) {
+        this.c = c;
+    }
+    put(kind, input) {
+        text(input.itemId, 256);
+        text(input.revisionId, 256);
+        return transaction(this.c.db, () => putDerivation(this.c.db, kind, input));
+    }
+    read(kind, id) {
+        text(id, 256);
+        return readDerivation(this.c.db, kind, id);
+    }
+    current(kind, itemId) {
+        text(itemId, 256);
+        return currentDerivation(this.c.db, kind, itemId);
+    }
+    /** The newest stored derivation for exactly these inputs, so a rerun reuses it instead of asking the model again. */
+    find(kind, revisionId, inputHash) {
+        text(revisionId, 256);
+        hash(inputHash);
+        const r = this.c.db
+            .prepare('SELECT * FROM derivations WHERE revision_id=? AND kind=? AND input_hash=? ORDER BY created_at DESC,rowid DESC LIMIT 1')
+            .get(revisionId, kind, inputHash);
+        return r ? row(r) : undefined;
+    }
+    review(kind, id, input) {
+        text(id, 256);
+        return transaction(this.c.db, () => reviewDerivation(this.c.db, kind, id, input));
+    }
+}

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

@@ -1,8 +1,6 @@
-export declare const digest: (value: string | Uint8Array) => string;
 export declare function hash(value: string): void;
 export declare function text(value: string, max?: number): void;
 export declare function integer(value: number, maximum?: number): void;
-export declare function syncDirectory(path: string): void;
 /** Reject symlinks in every existing component; callers use canonical /private/tmp on macOS. */
 export declare function safeDirectory(path: string, create?: boolean): string;
 export declare function confinedFile(root: string, path: string): string;

package/dist/src/store/files.js

@@ -1,40 +1,31 @@
-import { constants, closeSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readSync, realpathSync } from 'node:fs';
+import { constants, closeSync, fstatSync, lstatSync, mkdirSync, openSync, readSync, realpathSync } from 'node:fs';
 import { dirname, isAbsolute, join, parse, relative, sep } from 'node:path';
 import { createHash } from 'node:crypto';
-import { StoreError } from './types.js';
-export const digest = (value) => createHash('sha256').update(value).digest('hex');
+import { syncDirectory } from '../util/fsync.js';
+import { SpongeError } from '../errors.js';
 export function hash(value) {
     if (!/^[a-f0-9]{64}$/.test(value))
-        throw new StoreError('invalid-input');
+        throw new SpongeError('invalid-input');
 }
 export function text(value, max = 4096) {
     if (typeof value !== 'string' || value.length === 0 || Buffer.byteLength(value) > max || value.includes('\0'))
-        throw new StoreError('invalid-input');
+        throw new SpongeError('invalid-input');
 }
 export function integer(value, maximum = Number.MAX_SAFE_INTEGER) {
     if (!Number.isSafeInteger(value) || value < 0 || value > maximum)
-        throw new StoreError('invalid-input');
-}
-export function syncDirectory(path) {
-    const fd = openSync(path, constants.O_RDONLY);
-    try {
-        fsyncSync(fd);
-    }
-    finally {
-        closeSync(fd);
-    }
+        throw new SpongeError('invalid-input');
 }
 /** Reject symlinks in every existing component; callers use canonical /private/tmp on macOS. */
 export function safeDirectory(path, create = false) {
     if (!isAbsolute(path) || path.includes('\0') || path.split(sep).includes('..'))
-        throw new StoreError('invalid-input');
+        throw new SpongeError('invalid-input');
     let current = parse(path).root;
     for (const part of path.slice(current.length).split(sep).filter(Boolean)) {
         current = join(current, part);
         try {
             const stat = lstatSync(current);
             if (!stat.isDirectory() || stat.isSymbolicLink())
-                throw new StoreError('integrity');
+                throw new SpongeError('integrity');
         }
         catch (error) {
             if (error.code !== 'ENOENT' || !create)
@@ -48,14 +39,14 @@ export function safeDirectory(path, create = false) {
 export function confinedFile(root, path) {
     const rel = relative(root, path);
     if (!rel || rel.startsWith('..' + sep) || rel === '..' || isAbsolute(rel))
-        throw new StoreError('integrity');
+        throw new SpongeError('integrity');
     safeDirectory(dirname(path));
     return path;
 }
 export function regularFile(path) {
     const stat = lstatSync(path);
     if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1)
-        throw new StoreError('integrity');
+        throw new SpongeError('integrity');
 }
 function checkedFile(path, expectedHash, expectedBytes, retain) {
     regularFile(path);
@@ -63,7 +54,7 @@ function checkedFile(path, expectedHash, expectedBytes, retain) {
     try {
         const stat = fstatSync(fd);
         if (!stat.isFile() || stat.size !== expectedBytes || stat.nlink !== 1)
-            throw new StoreError('integrity');
+            throw new SpongeError('integrity');
         const h = createHash('sha256'), buffer = Buffer.allocUnsafe(64 * 1024);
         let count = 0;
         const chunks = [];
@@ -73,13 +64,13 @@ function checkedFile(path, expectedHash, expectedBytes, retain) {
                 break;
             count += read;
             if (count > expectedBytes)
-                throw new StoreError('integrity');
+                throw new SpongeError('integrity');
             h.update(buffer.subarray(0, read));
             if (retain)
                 chunks.push(Buffer.from(buffer.subarray(0, read)));
         }
         if (count !== expectedBytes || h.digest('hex') !== expectedHash)
-            throw new StoreError('integrity');
+            throw new SpongeError('integrity');
         return Buffer.concat(chunks);
     }
     finally {
@@ -97,5 +88,9 @@ export function pathExists(path) {
         throw error;
     }
 }
-export function verifyFile(path, expectedHash, expectedBytes) { checkedFile(path, expectedHash, expectedBytes, false); }
-export function readVerifiedFile(path, expectedHash, expectedBytes) { return checkedFile(path, expectedHash, expectedBytes, true); }
+export function verifyFile(path, expectedHash, expectedBytes) {
+    checkedFile(path, expectedHash, expectedBytes, false);
+}
+export function readVerifiedFile(path, expectedHash, expectedBytes) {
+    return checkedFile(path, expectedHash, expectedBytes, true);
+}

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

@@ -0,0 +1,30 @@
+import type { MetadataClaim } from '../../contracts/index.js';
+/**
+ * Ids of immutable captured objects: domain-tagged content addresses scoped by their (content-addressed) revision, so two
+ * devices capturing the same bytes write the same rows. See docs/decisions/content-ids.md.
+ */
+export declare const representationId: (revisionId: string, kind: string, mimeType: string, contentSha256: string) => string;
+export declare const blockId: (revisionId: string, ordinal: number, kind: string, text: string) => string;
+export type ClaimColumns = [
+    field: string,
+    valueJson: string,
+    source: string,
+    observedAt: string,
+    rule: string | null,
+    timezoneKnown: number | null,
+    observedJson: string | null,
+    locator: string | null,
+    selected: number | null,
+    extractionVersion: string | null,
+    datePrecision: string | null
+];
+/** The stored columns of a claim after `id` and `revision_id`, in table order: what capture inserts and what its id hashes. */
+export declare const claimColumns: (claim: MetadataClaim) => ClaimColumns;
+export declare const claimId: (revisionId: string, ordinal: number, columns: readonly (string | number | null)[]) => string;
+/** A locator that names a file on this device. Only `file:` locators carry a path; `local:` is their portable form. */
+export declare const isFileLocator: (locator: string) => boolean;
+/**
+ * What syncs in place of a `file:` locator: `local:<domain-tagged hash of the URL>/<basename>`. The same path gives the same
+ * locator; the path itself is kept only in `local_sources`. Total: any other locator is returned unchanged.
+ */
+export declare function portableLocator(locator: string): string;

package/dist/src/store/ids.js

@@ -0,0 +1,34 @@
+import { contentId, sha256 } from '../util/hash.js';
+/**
+ * Ids of immutable captured objects: domain-tagged content addresses scoped by their (content-addressed) revision, so two
+ * devices capturing the same bytes write the same rows. See docs/decisions/content-ids.md.
+ */
+export const representationId = (revisionId, kind, mimeType, contentSha256) => contentId('representation-v1', [revisionId, kind, mimeType, contentSha256]);
+export const blockId = (revisionId, ordinal, kind, text) => contentId('block-v1', [revisionId, ordinal, kind, sha256(text)]);
+/** The stored columns of a claim after `id` and `revision_id`, in table order: what capture inserts and what its id hashes. */
+export const claimColumns = (claim) => [
+    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,
+];
+export const claimId = (revisionId, ordinal, columns) => contentId('metadata-claim-v1', [revisionId, ordinal, ...columns]);
+/** A locator that names a file on this device. Only `file:` locators carry a path; `local:` is their portable form. */
+export const isFileLocator = (locator) => /^file:/i.test(locator);
+/**
+ * What syncs in place of a `file:` locator: `local:<domain-tagged hash of the URL>/<basename>`. The same path gives the same
+ * locator; the path itself is kept only in `local_sources`. Total: any other locator is returned unchanged.
+ */
+export function portableLocator(locator) {
+    if (!isFileLocator(locator))
+        return locator;
+    const name = locator.split(/[?#]/)[0].split('/').filter(Boolean).pop() ?? '';
+    return `local:${contentId('local-path-v1', locator)}/${name.slice(0, 1024)}`;
+}

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

@@ -0,0 +1,26 @@
+import type { DatabaseSync } from 'node:sqlite';
+import * as jungle from '../importers/jungle-store.js';
+import { type Context } from './context.js';
+/** The receipt an importer left for exactly this source state, if any. */
+export declare function importReceipt(db: DatabaseSync, namespace: string, sourceKey: string, sourceHash: string): {
+    itemId: string;
+    outcome: string;
+} | null;
+/** What importers read and write: their realm's items and revisions, their receipts, and Jungle Reading notes. */
+export declare class Imports {
+    private readonly c;
+    constructor(c: Context);
+    /** The item an importer realm holds for one source key, with its current revision; deleted items are reported, not hidden. */
+    item(realm: string, sourceKey: string): {
+        itemId: string;
+        deleted: boolean;
+        revisionId: string | null;
+    } | null;
+    revision(itemId: string, bundleHash: string): string;
+    receipt(namespace: string, sourceKey: string, sourceHash: string): {
+        itemId: string;
+        outcome: string;
+    } | null;
+    planJungleNote(input: jungle.JungleNoteInput): jungle.JunglePlan;
+    applyJungleNote(input: jungle.JungleNoteInput): jungle.JunglePlan;
+}