@openlfcp/storage-node 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,100 @@
+# @openlfcp/storage-node
+
+Durable Node.js storage for LFCP clients (LFCP-035):
+
+- `SqliteLfcpStorage`, the `LfcpStorage` interface of `@openlfcp/storage` on
+  SQLite through [better-sqlite3](https://github.com/WiseLibs/better-sqlite3)
+  13.0.3;
+- `FileSecretStore`, a `SecretStore` in a local directory.
+
+**This package is Node only.** It is meant for headless Node clients, the CLI,
+the examples and tests. It is the only sdk-ts package allowed to use `node:*`
+modules (`scripts/check-boundaries.mjs`), and no portable package may depend
+on it. The Obsidian plugin does not use it: Obsidian has its own adapter
+(LFCP-059), which runs the same contract suite (`runStorageContract` from
+`@openlfcp/storage/contract`).
+
+## Scope
+
+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.8`, not every deferred WIRE-01 feature. It does not
+claim full LFCP-WIRE-01 conformance. This is a release candidate
+(`0.1.0-rc.1`, npm dist-tag `next`): APIs may still change.
+
+## SQLite
+
+```ts
+const storage = SqliteLfcpStorage.open("/path/to/lfcp.sqlite");
+// ... storage.commit([...]), storage.dataUnits.get(id), ...
+storage.close();
+```
+
+- **Durability.** WAL journal with `synchronous=FULL`: a transaction is on disk
+  when it commits, and every promise resolves after its transaction committed.
+  These are SQLite's guarantees on a local filesystem whose `fsync` works,
+  nothing more.
+- **Atomicity.** One `commit()` is one `BEGIN IMMEDIATE` transaction: every
+  write or none, with the Control Head compare-and-set checked inside it.
+- **Sequences.** Actor and Snapshot sequence reservations read and advance
+  their counter inside one `BEGIN IMMEDIATE` transaction, which holds the write
+  lock across processes. No two callers ever get the same value, in this
+  process or another. A crash after a reservation committed skips that value;
+  it never reuses it.
+- **Exact bytes.** Control Records, Data Units, Key Packages and Snapshots are
+  stored as their exact bytes; the other columns are indexes. Storing an ID
+  again with other bytes fails the whole batch. Bytes are copied out, so callers
+  never share SQLite's buffers.
+- **Indexes.** Data Units are indexed by `(resource, actor, sequence)`, which
+  serves equivocation checks, held-unit retries and anti-entropy ranges, and by
+  `(resource, status)`.
+- **Schema.** A `schema_version` table and ordered migrations, from version 1.
+  A database from a newer schema is refused, never downgraded.
+- uint64 values (sequences, epochs, route versions) are stored as 20-digit
+  zero-padded text, so they sort numerically and never overflow SQLite's
+  signed 64-bit integers.
+
+The driver ships prebuilt Node-API binaries for macOS, Linux (glibc and musl)
+and Windows on x64 and arm64. Installing needs no compiler and no install
+script, and the same binary loads in Electron's main process.
+
+## Secrets
+
+```ts
+const secrets = new FileSecretStore("/path/to/secrets");
+await secrets.put(dekSecretRef(resource, epoch), dekBytes);
+```
+
+> **MVP limitation: secrets are stored in plaintext on disk.** They are
+> protected only by file permissions: the directory is `0700` and every file
+> `0600`, owned by the user running the client. Anyone who can read those files
+> as that user, as root, or from a backup has the keys. OS keychain integration
+> or passphrase-based encryption is a follow-up.
+
+- One file per `SecretRef`, named by the hex of the reference (references are
+  public names, never secret material).
+- Writes go to a temporary file that is fsynced, renamed over the target and
+  followed by a directory fsync. A crash leaves the old value or the new one,
+  never a torn file.
+- There is no list operation, and the store prints as `[FileSecretStore]`, so
+  values cannot leak into logs.
+- Write a secret before committing the row that references it (see
+  `@openlfcp/storage`).
+
+## Tests
+
+`test/contract.test.ts` runs the shared storage contract, including a reopen,
+against SQLite and the file store. `test/crash.test.ts` kills a writing child
+process with `SIGKILL` and checks the reopened database: no sequence reuse, no
+torn batch, every committed batch present. Every test uses its own temporary
+directory and deletes it.
+
+## Links
+
+- Specification: [openlfcp/spec](https://github.com/openlfcp/spec)
+- Source and the other SDK packages: [openlfcp/sdk-ts](https://github.com/openlfcp/sdk-ts)
+- Issues: [openlfcp/sdk-ts/issues](https://github.com/openlfcp/sdk-ts/issues)
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

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

@@ -0,0 +1,53 @@
+{
+  "name": "@openlfcp/storage-node",
+  "version": "0.1.0-rc.1",
+  "description": "Durable Node.js storage for LFCP clients: SQLite (better-sqlite3) and a file secret store. Node only.",
+  "keywords": [
+    "openlfcp",
+    "lfcp",
+    "local-first",
+    "end-to-end-encryption",
+    "storage",
+    "sqlite",
+    "node"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/openlfcp/sdk-ts/tree/main/packages/storage-node#readme",
+  "bugs": {
+    "url": "https://github.com/openlfcp/sdk-ts/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openlfcp/sdk-ts.git",
+    "directory": "packages/storage-node"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "dependencies": {
+    "better-sqlite3": "13.0.3",
+    "@openlfcp/core": "^0.1.0-rc.1",
+    "@openlfcp/storage": "^0.1.0-rc.1"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "9.6.0",
+    "@types/node": "24.19.1"
+  }
+}