@openlfcp/storage-node 0.1.2 → 0.1.4

package/README.md

@@ -18,9 +18,9 @@ on it. The Obsidian plugin does not use it: Obsidian has its own adapter
 
 Part of the OpenLFCP TypeScript SDK, which implements the OpenLFCP MVP 0.1
 subset of [LFCP-WIRE-01](https://github.com/openlfcp/spec/blob/main/wire/LFCP-WIRE-01.md)
-at `mvp-0.1-baseline.9`, not every deferred WIRE-01 feature. It does not
+at `mvp-0.1-baseline.10`, not every deferred WIRE-01 feature. It does not
 claim full LFCP-WIRE-01 conformance. This is the MVP 0.1 release
-(`0.1.2`, npm dist-tag `latest`). Until 1.0, minor versions may change APIs.
+(`0.1.4`, npm dist-tag `latest`). Until 1.0, minor versions may change APIs.
 
 ## SQLite
 

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Durable Node.js storage for LFCP clients (LFCP-035): LfcpStorage on
+ * SQLite and a file SecretStore. Node only: for headless Node, the CLI,
+ * examples and tests. Obsidian uses its own adapter (LFCP-059), which runs
+ * the same contract suite.
+ */
+export declare const PACKAGE = "@openlfcp/storage-node";
+export { MIGRATIONS, migrate, SCHEMA_VERSION, schemaVersion } from "./schema.js";
+export { FileSecretStore } from "./secrets.js";
+export { SqliteLfcpStorage, type SqliteStorageOptions } from "./sqlite.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * Durable Node.js storage for LFCP clients (LFCP-035): LfcpStorage on
+ * SQLite and a file SecretStore. Node only: for headless Node, the CLI,
+ * examples and tests. Obsidian uses its own adapter (LFCP-059), which runs
+ * the same contract suite.
+ */
+export const PACKAGE = "@openlfcp/storage-node";
+export { MIGRATIONS, migrate, SCHEMA_VERSION, schemaVersion } from "./schema.js";
+export { FileSecretStore } from "./secrets.js";
+export { SqliteLfcpStorage } from "./sqlite.js";
+//# sourceMappingURL=index.js.map

package/dist/schema.d.ts

@@ -0,0 +1,20 @@
+import type Database from "better-sqlite3";
+/**
+ * The SQLite schema and its migrations. Version 1 is the LFCP-034 storage
+ * model; version 2 adds outbound retry state and sync state (LFCP-036);
+ * version 3 adds local marks (the crash-loop breaker's apply markers).
+ * A database at a newer version than this code knows is refused:
+ * it is never downgraded or "repaired".
+ *
+ * Conventions: IDs and exact object bytes are BLOBs (memcmp order is byte
+ * order); uint64 values (sequences, epochs, route versions) are 20-digit
+ * zero-padded decimal TEXT, so they sort numerically and never overflow
+ * SQLite's signed 64-bit INTEGER.
+ */
+export declare const MIGRATIONS: readonly (readonly [version: number, sql: string])[];
+export declare const SCHEMA_VERSION: number;
+/** The schema version of an open database (0 for a fresh one). */
+export declare function schemaVersion(db: Database.Database): number;
+/** Brings the database to SCHEMA_VERSION, one migration per transaction. */
+export declare function migrate(db: Database.Database): number;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.js

@@ -0,0 +1,185 @@
+import { LfcpError } from "@openlfcp/core";
+/**
+ * The SQLite schema and its migrations. Version 1 is the LFCP-034 storage
+ * model; version 2 adds outbound retry state and sync state (LFCP-036);
+ * version 3 adds local marks (the crash-loop breaker's apply markers).
+ * A database at a newer version than this code knows is refused:
+ * it is never downgraded or "repaired".
+ *
+ * Conventions: IDs and exact object bytes are BLOBs (memcmp order is byte
+ * order); uint64 values (sequences, epochs, route versions) are 20-digit
+ * zero-padded decimal TEXT, so they sort numerically and never overflow
+ * SQLite's signed 64-bit INTEGER.
+ */
+export const MIGRATIONS = [
+    [
+        1,
+        `
+CREATE TABLE control_records (
+  record_id     BLOB PRIMARY KEY,
+  resource_id   BLOB NOT NULL,
+  control_seq   TEXT NOT NULL,
+  prev_id       BLOB,
+  bytes         BLOB NOT NULL
+) WITHOUT ROWID;
+CREATE INDEX control_records_by_resource ON control_records (resource_id, control_seq, record_id);
+
+CREATE TABLE control_heads (
+  resource_id   BLOB PRIMARY KEY,
+  head          BLOB NOT NULL,
+  control_seq   TEXT NOT NULL
+) WITHOUT ROWID;
+
+CREATE TABLE control_conflicts (
+  resource_id   BLOB PRIMARY KEY,
+  heads         BLOB NOT NULL
+) WITHOUT ROWID;
+
+CREATE TABLE epochs (
+  resource_id     BLOB NOT NULL,
+  epoch           TEXT NOT NULL,
+  dek_commitment  BLOB NOT NULL,
+  opened_by       BLOB NOT NULL,
+  closed_by       BLOB,
+  dek_ref         TEXT,
+  PRIMARY KEY (resource_id, epoch)
+) WITHOUT ROWID;
+
+CREATE TABLE data_units (
+  unit_id       BLOB PRIMARY KEY,
+  resource_id   BLOB NOT NULL,
+  data_epoch    TEXT NOT NULL,
+  actor         BLOB NOT NULL,
+  actor_seq     TEXT NOT NULL,
+  prev_id       BLOB,
+  control_head  BLOB NOT NULL,
+  bytes         BLOB NOT NULL,
+  status        TEXT NOT NULL,
+  detail        TEXT,
+  accepted      INTEGER NOT NULL
+) WITHOUT ROWID;
+CREATE INDEX data_units_by_tuple ON data_units (resource_id, actor, actor_seq, unit_id);
+CREATE INDEX data_units_by_status ON data_units (resource_id, status);
+
+CREATE TABLE key_packages (
+  package_id    BLOB PRIMARY KEY,
+  resource_id   BLOB NOT NULL,
+  data_epoch    TEXT NOT NULL,
+  recipient     BLOB NOT NULL,
+  sender        BLOB NOT NULL,
+  bytes         BLOB NOT NULL
+) WITHOUT ROWID;
+CREATE INDEX key_packages_by_recipient ON key_packages (resource_id, data_epoch, recipient);
+
+CREATE TABLE snapshots (
+  snapshot_id   BLOB PRIMARY KEY,
+  resource_id   BLOB NOT NULL,
+  data_epoch    TEXT NOT NULL,
+  publisher     BLOB NOT NULL,
+  snapshot_seq  TEXT NOT NULL,
+  frontier      BLOB NOT NULL,
+  bytes         BLOB NOT NULL
+) WITHOUT ROWID;
+CREATE INDEX snapshots_by_epoch ON snapshots (resource_id, data_epoch, publisher, snapshot_seq);
+
+CREATE TABLE resources (
+  resource_id     BLOB PRIMARY KEY,
+  data_profile    TEXT NOT NULL,
+  local_principal BLOB,
+  signing_ref     TEXT,
+  agreement_ref   TEXT,
+  labels          TEXT NOT NULL
+) WITHOUT ROWID;
+
+CREATE TABLE routes (
+  resource_id     BLOB PRIMARY KEY,
+  route_version   TEXT NOT NULL,
+  endpoints       TEXT NOT NULL,
+  coordinator_url TEXT NOT NULL,
+  source          BLOB NOT NULL
+) WITHOUT ROWID;
+
+CREATE TABLE outbound (
+  position      INTEGER PRIMARY KEY AUTOINCREMENT,
+  item_id       BLOB NOT NULL UNIQUE,
+  resource_id   BLOB NOT NULL,
+  kind          TEXT NOT NULL,
+  bytes         BLOB NOT NULL,
+  attempts      INTEGER NOT NULL,
+  last_attempt  TEXT
+);
+
+CREATE TABLE profile_checkpoints (
+  resource_id   BLOB PRIMARY KEY,
+  data_profile  TEXT NOT NULL,
+  state         BLOB NOT NULL,
+  actor_seq     INTEGER NOT NULL,
+  units         TEXT NOT NULL
+) WITHOUT ROWID;
+
+CREATE TABLE actor_sequences (
+  resource_id   BLOB NOT NULL,
+  principal     BLOB NOT NULL,
+  last          TEXT NOT NULL,
+  PRIMARY KEY (resource_id, principal)
+) WITHOUT ROWID;
+
+CREATE TABLE snapshot_sequences (
+  resource_id   BLOB NOT NULL,
+  epoch         TEXT NOT NULL,
+  publisher     BLOB NOT NULL,
+  last          TEXT NOT NULL,
+  PRIMARY KEY (resource_id, epoch, publisher)
+) WITHOUT ROWID;
+`,
+    ],
+    [
+        // LFCP-036: retry scheduling and blocking of outbound items; per-Resource sync state.
+        2,
+        `
+ALTER TABLE outbound ADD COLUMN next_attempt TEXT;
+ALTER TABLE outbound ADD COLUMN blocked_reason TEXT;
+ALTER TABLE outbound ADD COLUMN blocked_detail TEXT;
+
+CREATE TABLE sync_state (
+  resource_id       BLOB PRIMARY KEY,
+  recently_acked    BLOB NOT NULL,
+  acked_durability  TEXT
+) WITHOUT ROWID;
+`,
+    ],
+    [
+        // Local marks: small device-local processing records (crash-loop breaker).
+        3,
+        `
+CREATE TABLE local_marks (
+  key    TEXT PRIMARY KEY,
+  value  TEXT NOT NULL
+) WITHOUT ROWID;
+`,
+    ],
+];
+export const SCHEMA_VERSION = MIGRATIONS.at(-1)?.[0] ?? 0;
+/** The schema version of an open database (0 for a fresh one). */
+export function schemaVersion(db) {
+    db.exec("CREATE TABLE IF NOT EXISTS schema_version (version INTEGER NOT NULL)");
+    const row = db.prepare("SELECT version FROM schema_version").get();
+    return row?.version ?? 0;
+}
+/** Brings the database to SCHEMA_VERSION, one migration per transaction. */
+export function migrate(db) {
+    const current = schemaVersion(db);
+    if (current > SCHEMA_VERSION)
+        throw new LfcpError("UNSUPPORTED_VALUE", `the database is at schema version ${current}, newer than this code (${SCHEMA_VERSION})`);
+    for (const [version, sql] of MIGRATIONS) {
+        if (version <= current)
+            continue;
+        db.transaction(() => {
+            db.exec(sql);
+            db.exec("DELETE FROM schema_version");
+            db.prepare("INSERT INTO schema_version (version) VALUES (?)").run(version);
+        }).immediate();
+    }
+    return SCHEMA_VERSION;
+}
+//# sourceMappingURL=schema.js.map

package/dist/secrets.d.ts

@@ -0,0 +1,32 @@
+import { type SecretRef, type SecretStore } from "@openlfcp/storage";
+/**
+ * A SecretStore in a local directory (LFCP-035), for headless Node, the
+ * CLI, examples and tests.
+ *
+ * MVP LIMITATION: secrets are stored IN PLAINTEXT, protected only by file
+ * permissions: the directory is 0700 and every file 0600, owned by the
+ * running user. Anyone who can read the files as that user (or as root, or
+ * from a backup) has the keys. OS keychain integration or passphrase
+ * encryption is a follow-up.
+ *
+ * One file per SecretRef, named by the hex of the reference (references
+ * are public names, never secret material). A write goes to a temporary
+ * file that is fsynced, renamed over the target and followed by an fsync
+ * of the directory, so a crash leaves the old value or the new one, never
+ * a torn file. There is no list operation, and the store renders as
+ * "[FileSecretStore]" so values cannot leak into logs.
+ */
+declare const INSPECT: unique symbol;
+export declare class FileSecretStore implements SecretStore {
+    #private;
+    /** Creates the directory (0700) if needed and tightens its mode. */
+    constructor(dir: string);
+    put(ref: SecretRef, value: Uint8Array): Promise<void>;
+    get(ref: SecretRef): Promise<Uint8Array | undefined>;
+    delete(ref: SecretRef): Promise<void>;
+    toJSON(): string;
+    toString(): string;
+    [INSPECT](): string;
+}
+export {};
+//# sourceMappingURL=secrets.d.ts.map

package/dist/secrets.js

@@ -0,0 +1,106 @@
+import { chmodSync, closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeSync, } from "node:fs";
+import { join } from "node:path";
+import { LfcpError } from "@openlfcp/core";
+import { isSecretRef } from "@openlfcp/storage";
+/**
+ * A SecretStore in a local directory (LFCP-035), for headless Node, the
+ * CLI, examples and tests.
+ *
+ * MVP LIMITATION: secrets are stored IN PLAINTEXT, protected only by file
+ * permissions: the directory is 0700 and every file 0600, owned by the
+ * running user. Anyone who can read the files as that user (or as root, or
+ * from a backup) has the keys. OS keychain integration or passphrase
+ * encryption is a follow-up.
+ *
+ * One file per SecretRef, named by the hex of the reference (references
+ * are public names, never secret material). A write goes to a temporary
+ * file that is fsynced, renamed over the target and followed by an fsync
+ * of the directory, so a crash leaves the old value or the new one, never
+ * a torn file. There is no list operation, and the store renders as
+ * "[FileSecretStore]" so values cannot leak into logs.
+ */
+const INSPECT = Symbol.for("nodejs.util.inspect.custom");
+const fileName = (ref) => `${Buffer.from(ref, "utf8").toString("hex")}.secret`;
+export class FileSecretStore {
+    #dir;
+    #counter = 0;
+    /** Creates the directory (0700) if needed and tightens its mode. */
+    constructor(dir) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        chmodSync(dir, 0o700);
+        if (!statSync(dir).isDirectory())
+            throw new LfcpError("UNSUPPORTED_VALUE", "the secret store location is not a directory");
+        this.#dir = dir;
+    }
+    #check(ref) {
+        if (!isSecretRef(ref))
+            throw new LfcpError("UNSUPPORTED_VALUE", "not a secret reference");
+    }
+    #syncDir() {
+        const fd = openSync(this.#dir, "r");
+        try {
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    put(ref, value) {
+        try {
+            this.#check(ref);
+            const target = join(this.#dir, fileName(ref));
+            this.#counter += 1;
+            const temp = join(this.#dir, `.tmp-${process.pid}-${this.#counter}-${fileName(ref)}`);
+            const fd = openSync(temp, "wx", 0o600);
+            try {
+                writeSync(fd, value);
+                fsyncSync(fd);
+            }
+            catch (e) {
+                closeSync(fd);
+                rmSync(temp, { force: true });
+                throw e;
+            }
+            closeSync(fd);
+            renameSync(temp, target);
+            this.#syncDir();
+            return Promise.resolve();
+        }
+        catch (e) {
+            return Promise.reject(e);
+        }
+    }
+    get(ref) {
+        try {
+            this.#check(ref);
+            return Promise.resolve(Uint8Array.from(readFileSync(join(this.#dir, fileName(ref)))));
+        }
+        catch (e) {
+            if (e.code === "ENOENT")
+                return Promise.resolve(undefined);
+            return Promise.reject(e);
+        }
+    }
+    delete(ref) {
+        try {
+            this.#check(ref);
+            unlinkSync(join(this.#dir, fileName(ref)));
+            this.#syncDir();
+        }
+        catch (e) {
+            if (e.code !== "ENOENT")
+                return Promise.reject(e);
+        }
+        return Promise.resolve();
+    }
+    toJSON() {
+        return "[FileSecretStore]";
+    }
+    toString() {
+        return "[FileSecretStore]";
+    }
+    [INSPECT]() {
+        return "[FileSecretStore]";
+    }
+}
+//# sourceMappingURL=secrets.js.map

package/dist/sqlite.d.ts

@@ -0,0 +1,31 @@
+import { type ActorSequenceReservation, type CommitResult, type ControlReader, type DataUnitReader, type KeyPackageReader, type LfcpStorage, type LocalMarkReader, type OutboundReader, type ProfileStateReader, type ResourceReader, type SnapshotReader, type SnapshotSequenceReservation, type StorageWrite, type SyncStateReader } from "@openlfcp/storage";
+export interface SqliteStorageOptions {
+    /** Milliseconds to wait for another process's write lock (default 5000). */
+    readonly busyTimeoutMs?: number;
+}
+export declare class SqliteLfcpStorage implements LfcpStorage {
+    #private;
+    /** The schema version after migration. */
+    readonly schemaVersion: number;
+    private constructor();
+    /**
+     * Opens (creating if needed) the database at `path`, migrates it to the
+     * current schema and sets the durability pragmas.
+     */
+    static open(path: string, options?: SqliteStorageOptions): SqliteLfcpStorage;
+    close(): void;
+    commit(writes: readonly StorageWrite[]): Promise<CommitResult>;
+    readonly control: ControlReader;
+    readonly dataUnits: DataUnitReader;
+    readonly keyPackages: KeyPackageReader;
+    readonly snapshots: SnapshotReader;
+    readonly resources: ResourceReader;
+    readonly outbound: OutboundReader;
+    readonly profileState: ProfileStateReader;
+    readonly syncState: SyncStateReader;
+    readonly localMarks: LocalMarkReader;
+    /** Durable before it resolves: the new value is committed (WAL, synchronous=FULL) first. */
+    readonly actorSequences: ActorSequenceReservation;
+    readonly snapshotSequences: SnapshotSequenceReservation;
+}
+//# sourceMappingURL=sqlite.d.ts.map

package/dist/sqlite.js

@@ -0,0 +1,534 @@
+import { actorSequence, bytesEqual, dataEpoch, LfcpError, toHex, UINT64_MAX, } from "@openlfcp/core";
+import { nextActorSequence, } from "@openlfcp/storage";
+import Database from "better-sqlite3";
+import { migrate } from "./schema.js";
+/** uint64 as 20-digit zero-padded TEXT (sorts numerically, never overflows). */
+const u64 = (n) => n.toString().padStart(20, "0");
+const fromU64 = (s) => BigInt(s);
+const blob = (b) => Buffer.from(b);
+/** A copy as a plain Uint8Array: nothing returned aliases SQLite's buffers. */
+const bytes = (v) => Uint8Array.from(v);
+const as = (v) => bytes(v);
+const maybeAs = (v) => (v === null ? null : as(v));
+const refused = (what, id) => {
+    throw new LfcpError("INVALID_STRUCTURE", `${what} ${toHex(id)} is stored with other bytes`);
+};
+const IDS = 32;
+const joinIds = (ids) => Buffer.concat(ids.map((i) => Buffer.from(i)));
+const splitIds = (v) => {
+    const all = bytes(v);
+    const out = [];
+    for (let i = 0; i < all.length; i += IDS)
+        out.push(all.slice(i, i + IDS));
+    return out;
+};
+const controlRecord = (r) => ({
+    recordId: as(r.record_id),
+    resourceId: as(r.resource_id),
+    controlSeq: fromU64(r.control_seq),
+    prevControlId: maybeAs(r.prev_id),
+    bytes: bytes(r.bytes),
+});
+const epochRow = (r) => ({
+    epoch: dataEpoch(fromU64(r.epoch)),
+    dekCommitment: as(r.dek_commitment),
+    openedBy: as(r.opened_by),
+    closedBy: maybeAs(r.closed_by),
+    dekRef: r.dek_ref ?? null,
+});
+const storedUnit = (r) => ({
+    unitId: as(r.unit_id),
+    resourceId: as(r.resource_id),
+    dataEpoch: dataEpoch(fromU64(r.data_epoch)),
+    actor: as(r.actor),
+    actorSeq: actorSequence(fromU64(r.actor_seq)),
+    prevDataUnitId: maybeAs(r.prev_id),
+    controlHead: as(r.control_head),
+    bytes: bytes(r.bytes),
+    status: r.status,
+    detail: r.detail ?? null,
+    accepted: r.accepted === 1,
+});
+const keyPackage = (r) => ({
+    packageId: as(r.package_id),
+    resourceId: as(r.resource_id),
+    dataEpoch: dataEpoch(fromU64(r.data_epoch)),
+    recipient: as(r.recipient),
+    sender: as(r.sender),
+    bytes: bytes(r.bytes),
+});
+const snapshot = (r) => ({
+    snapshotId: as(r.snapshot_id),
+    resourceId: as(r.resource_id),
+    dataEpoch: dataEpoch(fromU64(r.data_epoch)),
+    publisher: as(r.publisher),
+    snapshotSeq: fromU64(r.snapshot_seq),
+    frontier: bytes(r.frontier),
+    bytes: bytes(r.bytes),
+});
+const resource = (r) => ({
+    resourceId: as(r.resource_id),
+    dataProfile: r.data_profile,
+    localPrincipal: r.local_principal === null
+        ? null
+        : {
+            principalId: as(r.local_principal),
+            signingKeyRef: r.signing_ref,
+            agreementKeyRef: r.agreement_ref,
+        },
+    labels: JSON.parse(r.labels),
+});
+const route = (r) => ({
+    routeVersion: fromU64(r.route_version),
+    endpoints: JSON.parse(r.endpoints).map((e) => ({
+        url: e.url,
+        priority: BigInt(e.priority),
+        ...(e.flags === undefined ? {} : { flags: BigInt(e.flags) }),
+    })),
+    coordinatorUrl: r.coordinator_url,
+    source: as(r.source),
+});
+const outboundItem = (r) => ({
+    itemId: as(r.item_id),
+    resourceId: as(r.resource_id),
+    kind: r.kind,
+    bytes: bytes(r.bytes),
+    attempts: r.attempts,
+    lastAttempt: r.last_attempt ?? null,
+    nextAttempt: r.next_attempt ?? null,
+    blocked: r.blocked_reason === null
+        ? null
+        : {
+            reason: r.blocked_reason,
+            detail: r.blocked_detail ?? null,
+        },
+});
+const syncStateRow = (r) => ({
+    resourceId: as(r.resource_id),
+    recentlyAcked: splitIds(r.recently_acked),
+    ackedDurability: r.acked_durability === null ? null : BigInt(r.acked_durability),
+});
+const checkpointRow = (r) => ({
+    resourceId: as(r.resource_id),
+    dataProfile: r.data_profile,
+    state: bytes(r.state),
+    actorSeq: r.actor_seq,
+    units: JSON.parse(r.units).map(([unitId, ref]) => ({
+        unitId: Uint8Array.from(Buffer.from(unitId, "hex")),
+        ref,
+    })),
+});
+export class SqliteLfcpStorage {
+    #db;
+    /** The schema version after migration. */
+    schemaVersion;
+    constructor(db, version) {
+        this.#db = db;
+        this.schemaVersion = version;
+    }
+    /**
+     * Opens (creating if needed) the database at `path`, migrates it to the
+     * current schema and sets the durability pragmas.
+     */
+    static open(path, options = {}) {
+        const db = new Database(path);
+        try {
+            db.pragma("journal_mode = WAL");
+            db.pragma("synchronous = FULL");
+            db.pragma(`busy_timeout = ${Math.trunc(options.busyTimeoutMs ?? 5000)}`);
+            const version = migrate(db);
+            return new SqliteLfcpStorage(db, version);
+        }
+        catch (e) {
+            db.close();
+            throw e;
+        }
+    }
+    close() {
+        if (this.#db.open)
+            this.#db.close();
+    }
+    #all(sql, ...params) {
+        return this.#db.prepare(sql).all(...params);
+    }
+    #get(sql, ...params) {
+        return this.#db.prepare(sql).get(...params);
+    }
+    /** Runs `fn` synchronously in one BEGIN IMMEDIATE transaction and settles with its result. */
+    #tx(fn) {
+        try {
+            return Promise.resolve(this.#db.transaction(fn).immediate());
+        }
+        catch (e) {
+            return Promise.reject(e);
+        }
+    }
+    #read(fn) {
+        try {
+            return Promise.resolve(fn());
+        }
+        catch (e) {
+            return Promise.reject(e);
+        }
+    }
+    commit(writes) {
+        return this.#tx(() => {
+            for (const w of writes) {
+                if (w.op !== "set-control-head")
+                    continue;
+                const row = this.#get("SELECT head FROM control_heads WHERE resource_id = ?", blob(w.resourceId));
+                const current = row === undefined ? null : bytes(row.head);
+                const matches = current === null
+                    ? w.expected === null
+                    : w.expected !== null && bytesEqual(current, w.expected);
+                if (!matches)
+                    return Object.freeze({
+                        ok: false,
+                        reason: "CONTROL_HEAD_MISMATCH",
+                        resourceId: Uint8Array.from(w.resourceId),
+                        current: current,
+                    });
+            }
+            for (const w of writes) {
+                if (w.op !== "expect-previous-unit")
+                    continue;
+                const row = this.#get("SELECT unit_id FROM data_units WHERE resource_id = ? AND actor = ? AND accepted = 1 ORDER BY actor_seq DESC LIMIT 1", blob(w.resourceId), blob(w.actor));
+                const current = row === undefined ? null : bytes(row.unit_id);
+                const matches = current === null
+                    ? w.previous === null
+                    : w.previous !== null && bytesEqual(current, w.previous);
+                if (!matches)
+                    return Object.freeze({
+                        ok: false,
+                        reason: "PREVIOUS_UNIT_MISMATCH",
+                        resourceId: Uint8Array.from(w.resourceId),
+                        actor: Uint8Array.from(w.actor),
+                        current: current,
+                    });
+            }
+            for (const w of writes)
+                this.#apply(w);
+            return Object.freeze({ ok: true });
+        });
+    }
+    /** Inserts an immutable object; the same ID with other bytes throws (rolling the batch back). */
+    #immutable(table, idColumn, id, row, what) {
+        const columns = Object.keys(row);
+        const result = this.#db
+            .prepare(`INSERT INTO ${table} (${columns.join(", ")}) VALUES (${columns.map(() => "?").join(", ")}) ON CONFLICT (${idColumn}) DO NOTHING`)
+            .run(...Object.values(row));
+        if (result.changes === 0) {
+            const old = this.#get(`SELECT bytes FROM ${table} WHERE ${idColumn} = ?`, blob(id));
+            if (old === undefined || !bytesEqual(bytes(old.bytes), row.bytes))
+                refused(what, id);
+        }
+    }
+    #apply(w) {
+        const db = this.#db;
+        switch (w.op) {
+            case "put-control-records":
+                for (const r of w.records)
+                    this.#immutable("control_records", "record_id", r.recordId, {
+                        record_id: blob(r.recordId),
+                        resource_id: blob(r.resourceId),
+                        control_seq: u64(r.controlSeq),
+                        prev_id: r.prevControlId === null ? null : blob(r.prevControlId),
+                        bytes: blob(r.bytes),
+                    }, "Control Record");
+                return;
+            case "set-control-head":
+                db.prepare("INSERT INTO control_heads (resource_id, head, control_seq) VALUES (?, ?, ?) ON CONFLICT (resource_id) DO UPDATE SET head = excluded.head, control_seq = excluded.control_seq").run(blob(w.resourceId), blob(w.head.head), u64(w.head.controlSeq));
+                return;
+            case "set-control-conflict":
+                if (w.conflict === null)
+                    db.prepare("DELETE FROM control_conflicts WHERE resource_id = ?").run(blob(w.resourceId));
+                else
+                    db.prepare("INSERT INTO control_conflicts (resource_id, heads) VALUES (?, ?) ON CONFLICT (resource_id) DO UPDATE SET heads = excluded.heads").run(blob(w.resourceId), joinIds(w.conflict.heads));
+                return;
+            case "expect-previous-unit":
+                return; // a precondition, checked by commit()
+            case "put-epoch": {
+                const e = w.epoch;
+                db.prepare(`INSERT INTO epochs (resource_id, epoch, dek_commitment, opened_by, closed_by, dek_ref) VALUES (?, ?, ?, ?, ?, ?)
+           ON CONFLICT (resource_id, epoch) DO UPDATE SET dek_commitment = excluded.dek_commitment, opened_by = excluded.opened_by, closed_by = COALESCE(excluded.closed_by, epochs.closed_by), dek_ref = COALESCE(excluded.dek_ref, epochs.dek_ref)`).run(blob(w.resourceId), u64(BigInt(e.epoch)), blob(e.dekCommitment), blob(e.openedBy), e.closedBy === null ? null : blob(e.closedBy), e.dekRef);
+                return;
+            }
+            case "put-data-unit": {
+                const u = w.unit;
+                const old = this.#get("SELECT bytes, accepted FROM data_units WHERE unit_id = ?", blob(u.unitId));
+                if (old === undefined) {
+                    this.#insertUnit(u, w.status, w.detail ?? null, w.accepted ?? false);
+                }
+                else {
+                    if (!bytesEqual(bytes(old.bytes), u.bytes))
+                        refused("Data Unit", u.unitId);
+                    const accepted = w.accepted ?? old.accepted === 1;
+                    db.prepare("UPDATE data_units SET status = ?, detail = ?, accepted = ? WHERE unit_id = ?").run(w.status, w.detail ?? null, accepted ? 1 : 0, blob(u.unitId));
+                }
+                return;
+            }
+            case "set-data-unit-status":
+                this.#mustChange(db
+                    .prepare("UPDATE data_units SET status = ?, detail = ? WHERE unit_id = ?")
+                    .run(w.status, w.detail ?? null, blob(w.unitId)).changes, w.unitId);
+                return;
+            case "set-accepted":
+                this.#mustChange(db
+                    .prepare("UPDATE data_units SET accepted = ? WHERE unit_id = ?")
+                    .run(w.accepted ? 1 : 0, blob(w.unitId)).changes, w.unitId);
+                return;
+            case "put-key-package": {
+                const k = w.row;
+                this.#immutable("key_packages", "package_id", k.packageId, {
+                    package_id: blob(k.packageId),
+                    resource_id: blob(k.resourceId),
+                    data_epoch: u64(BigInt(k.dataEpoch)),
+                    recipient: blob(k.recipient),
+                    sender: blob(k.sender),
+                    bytes: blob(k.bytes),
+                }, "Key Package");
+                return;
+            }
+            case "delete-snapshot":
+                db.prepare("DELETE FROM snapshots WHERE snapshot_id = ?").run(blob(w.snapshotId));
+                return;
+            case "put-snapshot": {
+                const s = w.row;
+                this.#immutable("snapshots", "snapshot_id", s.snapshotId, {
+                    snapshot_id: blob(s.snapshotId),
+                    resource_id: blob(s.resourceId),
+                    data_epoch: u64(BigInt(s.dataEpoch)),
+                    publisher: blob(s.publisher),
+                    snapshot_seq: u64(s.snapshotSeq),
+                    frontier: blob(s.frontier),
+                    bytes: blob(s.bytes),
+                }, "Snapshot");
+                return;
+            }
+            case "put-resource": {
+                const r = w.row;
+                db.prepare(`INSERT INTO resources (resource_id, data_profile, local_principal, signing_ref, agreement_ref, labels) VALUES (?, ?, ?, ?, ?, ?)
+           ON CONFLICT (resource_id) DO UPDATE SET data_profile = excluded.data_profile, local_principal = excluded.local_principal, signing_ref = excluded.signing_ref, agreement_ref = excluded.agreement_ref, labels = excluded.labels`).run(blob(r.resourceId), r.dataProfile, r.localPrincipal === null ? null : blob(r.localPrincipal.principalId), r.localPrincipal?.signingKeyRef ?? null, r.localPrincipal?.agreementKeyRef ?? null, JSON.stringify(r.labels));
+                return;
+            }
+            case "put-route": {
+                const r = w.route;
+                const endpoints = r.endpoints.map((e) => ({
+                    url: e.url,
+                    priority: e.priority.toString(),
+                    ...(e.flags === undefined ? {} : { flags: e.flags.toString() }),
+                }));
+                db.prepare(`INSERT INTO routes (resource_id, route_version, endpoints, coordinator_url, source) VALUES (?, ?, ?, ?, ?)
+           ON CONFLICT (resource_id) DO UPDATE SET route_version = excluded.route_version, endpoints = excluded.endpoints, coordinator_url = excluded.coordinator_url, source = excluded.source`).run(blob(w.resourceId), u64(r.routeVersion), JSON.stringify(endpoints), r.coordinatorUrl, blob(r.source));
+                return;
+            }
+            case "enqueue": {
+                const o = w.item;
+                const old = this.#get("SELECT bytes FROM outbound WHERE item_id = ?", blob(o.itemId));
+                if (old !== undefined) {
+                    if (!bytesEqual(bytes(old.bytes), o.bytes))
+                        refused("outbound item", o.itemId);
+                    return;
+                }
+                db.prepare(`INSERT INTO outbound (item_id, resource_id, kind, bytes, attempts, last_attempt, next_attempt, blocked_reason, blocked_detail)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(blob(o.itemId), blob(o.resourceId), o.kind, blob(o.bytes), o.attempts, o.lastAttempt, o.nextAttempt, o.blocked?.reason ?? null, o.blocked?.detail ?? null);
+                return;
+            }
+            case "update-outbound": {
+                const sets = [];
+                const params = [];
+                if (w.attempts !== undefined) {
+                    sets.push("attempts = ?");
+                    params.push(w.attempts);
+                }
+                if (w.lastAttempt !== undefined) {
+                    sets.push("last_attempt = ?");
+                    params.push(w.lastAttempt);
+                }
+                if (w.nextAttempt !== undefined) {
+                    sets.push("next_attempt = ?");
+                    params.push(w.nextAttempt);
+                }
+                if (w.blocked !== undefined) {
+                    sets.push("blocked_reason = ?", "blocked_detail = ?");
+                    params.push(w.blocked?.reason ?? null, w.blocked?.detail ?? null);
+                }
+                const exists = this.#get("SELECT 1 AS x FROM outbound WHERE item_id = ?", blob(w.itemId));
+                if (exists === undefined)
+                    throw new LfcpError("INVALID_STRUCTURE", `no outbound item ${toHex(w.itemId)}`);
+                if (sets.length > 0)
+                    db.prepare(`UPDATE outbound SET ${sets.join(", ")} WHERE item_id = ?`).run(...params, blob(w.itemId));
+                return;
+            }
+            case "put-sync-state":
+                db.prepare(`INSERT INTO sync_state (resource_id, recently_acked, acked_durability) VALUES (?, ?, ?)
+           ON CONFLICT (resource_id) DO UPDATE SET recently_acked = excluded.recently_acked, acked_durability = excluded.acked_durability`).run(blob(w.row.resourceId), joinIds(w.row.recentlyAcked), w.row.ackedDurability === null ? null : w.row.ackedDurability.toString());
+                return;
+            case "dequeue":
+                db.prepare("DELETE FROM outbound WHERE item_id = ?").run(blob(w.itemId));
+                return;
+            case "put-local-mark":
+                if (w.value === null)
+                    db.prepare("DELETE FROM local_marks WHERE key = ?").run(w.key);
+                else
+                    db.prepare("INSERT INTO local_marks (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value").run(w.key, w.value);
+                return;
+            case "put-profile-checkpoint": {
+                const c = w.checkpoint;
+                db.prepare(`INSERT INTO profile_checkpoints (resource_id, data_profile, state, actor_seq, units) VALUES (?, ?, ?, ?, ?)
+           ON CONFLICT (resource_id) DO UPDATE SET data_profile = excluded.data_profile, state = excluded.state, actor_seq = excluded.actor_seq, units = excluded.units`).run(blob(c.resourceId), c.dataProfile, blob(c.state), c.actorSeq, JSON.stringify(c.units.map((u) => [toHex(u.unitId), u.ref])));
+                return;
+            }
+        }
+    }
+    #mustChange(changes, unitId) {
+        if (changes === 0)
+            throw new LfcpError("INVALID_STRUCTURE", `no Data Unit ${toHex(unitId)}`);
+    }
+    #insertUnit(u, status, detail, accepted) {
+        this.#db
+            .prepare(`INSERT INTO data_units (unit_id, resource_id, data_epoch, actor, actor_seq, prev_id, control_head, bytes, status, detail, accepted)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(blob(u.unitId), blob(u.resourceId), u64(BigInt(u.dataEpoch)), blob(u.actor), u64(BigInt(u.actorSeq)), u.prevDataUnitId === null ? null : blob(u.prevDataUnitId), blob(u.controlHead), blob(u.bytes), status, detail, accepted ? 1 : 0);
+    }
+    control = {
+        record: (id) => this.#read(() => {
+            const r = this.#get("SELECT * FROM control_records WHERE record_id = ?", blob(id));
+            return r === undefined ? undefined : controlRecord(r);
+        }),
+        records: (res) => this.#read(() => this.#all("SELECT * FROM control_records WHERE resource_id = ? ORDER BY control_seq, record_id", blob(res)).map(controlRecord)),
+        head: (res) => this.#read(() => {
+            const r = this.#get("SELECT head, control_seq FROM control_heads WHERE resource_id = ?", blob(res));
+            return r === undefined
+                ? undefined
+                : { head: as(r.head), controlSeq: fromU64(r.control_seq) };
+        }),
+        conflict: (res) => this.#read(() => {
+            const r = this.#get("SELECT heads FROM control_conflicts WHERE resource_id = ?", blob(res));
+            return r === undefined ? undefined : { heads: splitIds(r.heads) };
+        }),
+        epochs: (res) => this.#read(() => this.#all("SELECT * FROM epochs WHERE resource_id = ? ORDER BY epoch", blob(res)).map(epochRow)),
+    };
+    #at(res, actor, seq) {
+        return this.#all("SELECT * FROM data_units WHERE resource_id = ? AND actor = ? AND actor_seq = ? ORDER BY unit_id", blob(res), blob(actor), u64(BigInt(seq))).map(storedUnit);
+    }
+    dataUnits = {
+        get: (id) => this.#read(() => {
+            const r = this.#get("SELECT * FROM data_units WHERE unit_id = ?", blob(id));
+            return r === undefined ? undefined : storedUnit(r);
+        }),
+        at: (res, actor, seq) => this.#read(() => this.#at(res, actor, seq)),
+        range: (res, actor, from, to) => this.#read(() => this.#all("SELECT * FROM data_units WHERE resource_id = ? AND actor = ? AND actor_seq BETWEEN ? AND ? ORDER BY actor_seq, unit_id", blob(res), blob(actor), u64(BigInt(from)), u64(BigInt(to))).map(storedUnit)),
+        withStatus: (res, status) => this.#read(() => this.#all("SELECT * FROM data_units WHERE resource_id = ? AND status = ? ORDER BY actor, actor_seq, unit_id", blob(res), status).map(storedUnit)),
+        acceptedAt: (res, actor, seq) => this.#read(() => this.#at(res, actor, seq).find((u) => u.accepted)?.unitId),
+        recordSeen: (unit) => this.#tx(() => {
+            const old = this.#get("SELECT bytes FROM data_units WHERE unit_id = ?", blob(unit.unitId));
+            if (old !== undefined && !bytesEqual(bytes(old.bytes), unit.bytes))
+                refused("Data Unit", unit.unitId);
+            if (old === undefined)
+                this.#insertUnit(unit, "seen", null, false);
+            const unitIds = this.#at(unit.resourceId, unit.actor, unit.actorSeq).map((u) => u.unitId);
+            return Object.freeze({ unitIds: Object.freeze(unitIds), firstSeen: old === undefined });
+        }),
+    };
+    keyPackages = {
+        get: (id) => this.#read(() => {
+            const r = this.#get("SELECT * FROM key_packages WHERE package_id = ?", blob(id));
+            return r === undefined ? undefined : keyPackage(r);
+        }),
+        list: (res, filter = {}) => this.#read(() => {
+            const where = ["resource_id = ?"];
+            const params = [blob(res)];
+            if (filter.epoch !== undefined) {
+                where.push("data_epoch = ?");
+                params.push(u64(BigInt(filter.epoch)));
+            }
+            if (filter.recipient !== undefined) {
+                where.push("recipient = ?");
+                params.push(blob(filter.recipient));
+            }
+            return this.#all(`SELECT * FROM key_packages WHERE ${where.join(" AND ")} ORDER BY data_epoch, package_id`, ...params).map(keyPackage);
+        }),
+    };
+    snapshots = {
+        get: (id) => this.#read(() => {
+            const r = this.#get("SELECT * FROM snapshots WHERE snapshot_id = ?", blob(id));
+            return r === undefined ? undefined : snapshot(r);
+        }),
+        list: (res, filter = {}) => this.#read(() => filter.epoch === undefined
+            ? this.#all("SELECT * FROM snapshots WHERE resource_id = ? ORDER BY data_epoch, publisher, snapshot_seq", blob(res)).map(snapshot)
+            : this.#all("SELECT * FROM snapshots WHERE resource_id = ? AND data_epoch = ? ORDER BY data_epoch, publisher, snapshot_seq", blob(res), u64(BigInt(filter.epoch))).map(snapshot)),
+    };
+    resources = {
+        get: (res) => this.#read(() => {
+            const r = this.#get("SELECT * FROM resources WHERE resource_id = ?", blob(res));
+            return r === undefined ? undefined : resource(r);
+        }),
+        list: () => this.#read(() => this.#all("SELECT * FROM resources ORDER BY resource_id").map(resource)),
+        route: (res) => this.#read(() => {
+            const r = this.#get("SELECT * FROM routes WHERE resource_id = ?", blob(res));
+            return r === undefined ? undefined : route(r);
+        }),
+    };
+    outbound = {
+        list: (res) => this.#read(() => (res === undefined
+            ? this.#all("SELECT * FROM outbound ORDER BY position")
+            : this.#all("SELECT * FROM outbound WHERE resource_id = ? ORDER BY position", blob(res))).map(outboundItem)),
+        get: (id) => this.#read(() => {
+            const r = this.#get("SELECT * FROM outbound WHERE item_id = ?", blob(id));
+            return r === undefined ? undefined : outboundItem(r);
+        }),
+    };
+    profileState = {
+        checkpoint: (res) => this.#read(() => {
+            const r = this.#get("SELECT * FROM profile_checkpoints WHERE resource_id = ?", blob(res));
+            return r === undefined ? undefined : checkpointRow(r);
+        }),
+    };
+    syncState = {
+        get: (res) => this.#read(() => {
+            const r = this.#get("SELECT * FROM sync_state WHERE resource_id = ?", blob(res));
+            return r === undefined ? undefined : syncStateRow(r);
+        }),
+    };
+    localMarks = {
+        get: (key) => this.#read(() => this.#get("SELECT value FROM local_marks WHERE key = ?", key)?.value),
+        list: (prefix) => this.#read(() => this.#all("SELECT key, value FROM local_marks ORDER BY key")
+            .filter((r) => r.key.startsWith(prefix))
+            .map((r) => ({ key: r.key, value: r.value }))),
+    };
+    /** Durable before it resolves: the new value is committed (WAL, synchronous=FULL) first. */
+    actorSequences = {
+        reserveNext: (res, principal) => this.#tx(() => {
+            const key = [blob(res), blob(principal)];
+            const row = this.#get("SELECT last FROM actor_sequences WHERE resource_id = ? AND principal = ?", ...key);
+            const next = nextActorSequence(row === undefined ? undefined : actorSequence(fromU64(row.last)));
+            // Fail closed (§9): a counter behind this Principal's own stored units
+            // means lost or damaged sequence state; continuing could reuse a nonce.
+            const stored = this.#get("SELECT MAX(actor_seq) AS m FROM data_units WHERE resource_id = ? AND actor = ?", ...key);
+            if (stored?.m != null && next <= fromU64(stored.m))
+                throw new LfcpError("SEQUENCE_REUSE", `the actor sequence state (${next - 1n}) is behind the stored units of this Principal (${fromU64(stored.m)}); refusing to reserve (§9)`);
+            this.#db
+                .prepare("INSERT INTO actor_sequences (resource_id, principal, last) VALUES (?, ?, ?) ON CONFLICT (resource_id, principal) DO UPDATE SET last = excluded.last")
+                .run(...key, u64(next));
+            return next;
+        }),
+    };
+    snapshotSequences = {
+        reserveNext: (res, epoch, publisher) => this.#tx(() => {
+            const key = [blob(res), u64(BigInt(epoch)), blob(publisher)];
+            const row = this.#get("SELECT last FROM snapshot_sequences WHERE resource_id = ? AND epoch = ? AND publisher = ?", ...key);
+            const last = row === undefined ? 0n : fromU64(row.last);
+            const stored = this.#get("SELECT MAX(snapshot_seq) AS m FROM snapshots WHERE resource_id = ? AND data_epoch = ? AND publisher = ?", ...key);
+            if (stored?.m != null && last + 1n <= fromU64(stored.m))
+                throw new LfcpError("SEQUENCE_REUSE", `the Snapshot Sequence state (${last}) is behind the stored Snapshots of this publisher (${fromU64(stored.m)}); refusing to reserve (§29)`);
+            if (last >= UINT64_MAX)
+                throw new LfcpError("OUT_OF_RANGE", "the Snapshot Sequence space is exhausted (§29)");
+            this.#db
+                .prepare("INSERT INTO snapshot_sequences (resource_id, epoch, publisher, last) VALUES (?, ?, ?, ?) ON CONFLICT (resource_id, epoch, publisher) DO UPDATE SET last = excluded.last")
+                .run(...key, u64(last + 1n));
+            return last + 1n;
+        }),
+    };
+}
+//# sourceMappingURL=sqlite.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlfcp/storage-node",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Durable Node.js storage for LFCP clients: SQLite (better-sqlite3) and a file secret store. Node only.",
   "keywords": [
     "openlfcp",
@@ -43,8 +43,8 @@
   },
   "dependencies": {
     "better-sqlite3": "13.0.3",
-    "@openlfcp/storage": "^0.1.2",
-    "@openlfcp/core": "^0.1.2"
+    "@openlfcp/storage": "^0.1.4",
+    "@openlfcp/core": "^0.1.4"
   },
   "devDependencies": {
     "@types/better-sqlite3": "9.6.0",