@openlfcp/storage-idb 0.0.0-stage → 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

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# @openlfcp/storage-idb
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Durable portable storage for LFCP clients (LFCP-059): `IdbLfcpStorage`, the
+`LfcpStorage` interface of `@openlfcp/storage` on IndexedDB. It runs in
+browsers, Electron (Obsidian desktop) and mobile WebViews. It uses no Node
+built-ins (`scripts/check-boundaries.mjs`), and it passes the shared contract
+suite (`runStorageContract` from `@openlfcp/storage/contract`).
+
+```ts
+const storage = await IdbLfcpStorage.open(`openlfcp-v1-${installId}`, {
+  onReserved: ({ kind, key, value }) => mirrorHighWater(kind, key, value),
+});
+// ... storage.commit([...]), storage.dataUnits.get(id), ...
+storage.close();
+```
+
+The application names the database. Use one per client install: an IndexedDB
+origin is often shared (all Obsidian vaults share `app://obsidian.md`), and two
+installs must never share sequence counters.
+
+## 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.
+
+## Guarantees
+
+- **Atomicity.** One `commit()` is one readwrite transaction over every object
+  store. The Control Head compare-and-set is read inside it, and any failure
+  aborts the whole transaction: every write or none.
+- **Durability.** Every readwrite transaction asks for `durability: "strict"`
+  (Chromium's default is `relaxed`), and every promise resolves only on the
+  transaction's `complete` event.
+- **Sequences.** A reservation reads its counter, checks it against this
+  Principal's own stored units or Snapshots, and writes it, all in one strict
+  transaction. A counter behind them fails closed with `SEQUENCE_REUSE`. A
+  value is returned only after its transaction completed, and only after
+  `onReserved` returned. If `onReserved` throws, the value is abandoned and
+  never reissued.
+- **Exact bytes.** Control Records, Data Units, Key Packages and Snapshots are
+  stored as their exact bytes; the other fields are indexes. Storing an ID again
+  with other bytes fails the batch. Values come out as frozen copies.
+- **No foreign awaits.** A transaction awaits only IndexedDB requests, so it
+  cannot auto-commit half way.
+
+`counters()` lists the reservation counters (`actor:<resource>:<principal>`,
+`snapshot:<resource>:<epoch>:<publisher>`). `meta.get`/`meta.put` keep small,
+durable application metadata, such as an install marker. Never put secrets
+there: secrets belong in a `SecretStore`.
+
+## Limits
+
+- **Strict durability is the runtime's promise, not ours.** The tests run on
+  [fake-indexeddb](https://github.com/dumbmatter/fakeIndexedDB) (6.2.5, a test
+  dependency only). The tests check that every readwrite transaction asks for
+  `strict`, but they cannot show that a real browser flushed to disk. How
+  durable the data is depends on the browser's IndexedDB implementation and
+  the device's storage.
+- **Eviction.** Browsers may evict IndexedDB under storage pressure unless the
+  origin's storage is persistent. Applications should call
+  `navigator.storage.persist()` and tell the user when it is denied. An
+  evicted database loses the sequence counters, so the application must not
+  keep writing as the same Principal (for example, check an install marker
+  kept elsewhere).
+- **One writer.** IndexedDB transactions serialize the reservations, but two
+  application instances writing the same database is not a supported
+  configuration. Hold a Web Lock (`navigator.locks`) for the lifetime of the
+  writer.
+- **Plaintext.** Profile checkpoints are plaintext CRDT state. They are
+  protected at rest only by the runtime's profile directory.
+
+## 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/idb.d.ts

@@ -0,0 +1,91 @@
+import { type ActorSequence, type ControlRecordId, type DataEpoch, type DataUnitId, type Hash32, type PrincipalId, type ResourceId } from "@openlfcp/core";
+import { type ActorSequenceReservation, type CommitResult, type ControlConflictRow, type ControlHeadRow, type ControlRecordRow, type DataUnitRow, type DataUnitStatus, type EpochRow, type KeyPackageRow, type LfcpStorage, type OutboundItem, type ProfileCheckpoint, type ResourceRow, type RouteRow, type SeenRecord, type SnapshotRow, type SnapshotSequenceReservation, type StorageWrite, type StoredDataUnit, type SyncStateRow } from "@openlfcp/storage";
+/** A reservation that is durable and about to be returned. */
+export interface ReservedSequence {
+    readonly kind: "actor" | "snapshot";
+    /** The counter's key, as counters() lists it. */
+    readonly key: string;
+    readonly value: bigint;
+}
+export interface IdbStorageOptions {
+    /** The IndexedDB factory (default: globalThis.indexedDB). */
+    readonly indexedDB?: IDBFactory;
+    /**
+     * Called after a reservation is durable and before it is returned (e.g.
+     * to mirror a high-water mark elsewhere). If it throws, the reservation
+     * fails and its value is abandoned, never reissued.
+     */
+    readonly onReserved?: (reserved: ReservedSequence) => void;
+}
+export declare class IdbLfcpStorage implements LfcpStorage {
+    #private;
+    private constructor();
+    /** Opens (creating or upgrading) the database `name`. */
+    static open(name: string, options?: IdbStorageOptions): Promise<IdbLfcpStorage>;
+    /** Closes the connection; later calls fail. */
+    close(): void;
+    commit(writes: readonly StorageWrite[]): Promise<CommitResult>;
+    readonly actorSequences: ActorSequenceReservation;
+    readonly snapshotSequences: SnapshotSequenceReservation;
+    /** Every reservation counter: `actor:<resource>:<principal>` and `snapshot:<resource>:<epoch>:<publisher>`. */
+    counters(): Promise<ReadonlyMap<string, bigint>>;
+    /**
+     * Adapter-local metadata for the application (e.g. an install marker):
+     * structured-cloneable values, durable like everything else. Never secrets.
+     */
+    readonly meta: {
+        get: (key: string) => Promise<unknown>;
+        put: (key: string, value: unknown) => Promise<void>;
+    };
+    readonly control: {
+        record: (id: ControlRecordId) => Promise<ControlRecordRow | undefined>;
+        records: (resource: ResourceId) => Promise<ControlRecordRow[]>;
+        head: (resource: ResourceId) => Promise<ControlHeadRow | undefined>;
+        conflict: (resource: ResourceId) => Promise<ControlConflictRow | undefined>;
+        epochs: (resource: ResourceId) => Promise<EpochRow[]>;
+    };
+    readonly dataUnits: {
+        get: (id: DataUnitId) => Promise<StoredDataUnit | undefined>;
+        at: (resource: ResourceId, actor: PrincipalId, seq: ActorSequence) => Promise<StoredDataUnit[]>;
+        range: (resource: ResourceId, actor: PrincipalId, from: ActorSequence, to: ActorSequence) => Promise<StoredDataUnit[]>;
+        withStatus: (resource: ResourceId, status: DataUnitStatus) => Promise<StoredDataUnit[]>;
+        acceptedAt: (resource: ResourceId, actor: PrincipalId, seq: ActorSequence) => Promise<DataUnitId | undefined>;
+        recordSeen: (unit: DataUnitRow) => Promise<SeenRecord>;
+    };
+    readonly keyPackages: {
+        get: (id: Hash32) => Promise<KeyPackageRow | undefined>;
+        list: (resource: ResourceId, filter?: {
+            readonly epoch?: DataEpoch;
+            readonly recipient?: PrincipalId;
+        }) => Promise<KeyPackageRow[]>;
+    };
+    readonly snapshots: {
+        get: (id: Hash32) => Promise<SnapshotRow | undefined>;
+        list: (resource: ResourceId, filter?: {
+            readonly epoch?: DataEpoch;
+        }) => Promise<SnapshotRow[]>;
+    };
+    readonly resources: {
+        get: (resource: ResourceId) => Promise<ResourceRow | undefined>;
+        list: () => Promise<ResourceRow[]>;
+        route: (resource: ResourceId) => Promise<RouteRow | undefined>;
+    };
+    readonly outbound: {
+        list: (resource?: ResourceId) => Promise<OutboundItem[]>;
+        get: (id: Hash32) => Promise<OutboundItem | undefined>;
+    };
+    readonly profileState: {
+        checkpoint: (resource: ResourceId) => Promise<ProfileCheckpoint | undefined>;
+    };
+    readonly syncState: {
+        get: (resource: ResourceId) => Promise<SyncStateRow | undefined>;
+    };
+    readonly localMarks: {
+        get: (key: string) => Promise<string | undefined>;
+        list: (prefix: string) => Promise<{
+            key: string;
+            value: string;
+        }[]>;
+    };
+}
+//# sourceMappingURL=idb.d.ts.map

package/dist/idb.js

@@ -0,0 +1,541 @@
+/// <reference lib="dom" />
+import { bytesEqual, LfcpError, toHex, UINT64_MAX, } from "@openlfcp/core";
+import { nextActorSequence, } from "@openlfcp/storage";
+/**
+ * LfcpStorage on IndexedDB (LFCP-059): one database per client install,
+ * named by the caller. Portable: browsers, Electron, mobile WebViews.
+ *
+ * - Atomicity: one commit() is one readwrite transaction over every object
+ *   store; the Control Head compare-and-set is read inside it, and any
+ *   failure aborts the whole transaction.
+ * - Durability: every readwrite transaction asks for durability "strict"
+ *   (Chromium's default is relaxed), and a promise resolves only on the
+ *   transaction's complete event.
+ * - Sequences: a reservation reads the counter, checks it against this
+ *   Principal's own stored objects (fail closed, SEQUENCE_REUSE) and writes
+ *   it in one strict transaction, then calls onReserved before returning.
+ * - Exact bytes: signed objects are stored as their exact bytes; other
+ *   fields are indexes. Values are structured clones, so nothing returned
+ *   aliases a stored buffer or a caller's.
+ *
+ * A transaction only awaits IndexedDB requests (never other promises), so it
+ * cannot auto-commit half way.
+ */
+const VERSION = 1;
+const STORES = [
+    "records",
+    "heads",
+    "conflicts",
+    "epochs",
+    "units",
+    "keyPackages",
+    "snapshots",
+    "resources",
+    "routes",
+    "outbound",
+    "checkpoints",
+    "syncStates",
+    "counters",
+    "meta",
+];
+const hex = toHex;
+/** uint64 as a fixed-width decimal string, so key order is numeric order. */
+const pad = (n) => n.toString().padStart(20, "0");
+/** Local marks share the meta store under this key prefix. */
+const MARK = "mark:";
+const LOW = "";
+const HIGH = "￿";
+const actorKey = (r, p) => `actor:${hex(r)}:${hex(p)}`;
+const snapshotKey = (r, e, p) => `snapshot:${hex(r)}:${e}:${hex(p)}`;
+const ORDER_KEY = "order:outbound";
+/** A deep copy, frozen; structured clones are already copies, this freezes them. */
+function own(value) {
+    if (value instanceof Uint8Array)
+        return Uint8Array.from(value);
+    if (Array.isArray(value))
+        return Object.freeze(value.map(own));
+    if (value !== null && typeof value === "object")
+        return Object.freeze(Object.fromEntries(Object.entries(value).map(([k, v]) => [k, own(v)])));
+    return value;
+}
+const copyOf = (value) => value === undefined ? undefined : own(value);
+const byHex = (a, b) => {
+    const [x, y] = [hex(a), hex(b)];
+    return x < y ? -1 : x > y ? 1 : 0;
+};
+const byBig = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+const UNIT_ORDER = (a, b) => byHex(a.actor, b.actor) || byBig(a.actorSeq, b.actorSeq) || byHex(a.unitId, b.unitId);
+function req(r) {
+    return new Promise((resolve, reject) => {
+        r.onsuccess = () => resolve(r.result);
+        r.onerror = () => reject(r.error);
+    });
+}
+const pickUnit = (u) => ({
+    unitId: u.unitId,
+    resourceId: u.resourceId,
+    dataEpoch: u.dataEpoch,
+    actor: u.actor,
+    actorSeq: u.actorSeq,
+    prevDataUnitId: u.prevDataUnitId,
+    controlHead: u.controlHead,
+    bytes: u.bytes,
+});
+const unitValue = (row) => ({
+    r: hex(row.resourceId),
+    a: hex(row.actor),
+    s: pad(row.actorSeq),
+    st: row.status,
+    row,
+});
+class HeadMismatch {
+    result;
+    constructor(result) {
+        this.result = result;
+    }
+}
+function upgrade(db) {
+    const plain = (name) => db.createObjectStore(name);
+    db.createObjectStore("records").createIndex("r", "r");
+    plain("heads");
+    plain("conflicts");
+    db.createObjectStore("epochs").createIndex("r", "r");
+    const units = db.createObjectStore("units");
+    units.createIndex("ras", ["r", "a", "s"]);
+    units.createIndex("rst", ["r", "st"]);
+    db.createObjectStore("keyPackages").createIndex("r", "r");
+    const snapshots = db.createObjectStore("snapshots");
+    snapshots.createIndex("r", "r");
+    snapshots.createIndex("rep", ["r", "e", "p", "n"]);
+    plain("resources");
+    plain("routes");
+    db.createObjectStore("outbound").createIndex("n", "n");
+    plain("checkpoints");
+    plain("syncStates");
+    plain("counters");
+    plain("meta");
+}
+export class IdbLfcpStorage {
+    #db;
+    #onReserved;
+    constructor(db, options) {
+        this.#db = db;
+        this.#onReserved = options.onReserved;
+    }
+    /** Opens (creating or upgrading) the database `name`. */
+    static async open(name, options = {}) {
+        const factory = options.indexedDB ?? globalThis.indexedDB;
+        if (factory === undefined)
+            throw new LfcpError("UNSUPPORTED_VALUE", "IndexedDB is not available in this runtime");
+        const open = factory.open(name, VERSION);
+        open.onupgradeneeded = () => upgrade(open.result);
+        const db = await new Promise((resolve, reject) => {
+            open.onsuccess = () => resolve(open.result);
+            open.onerror = () => reject(open.error);
+            open.onblocked = () => reject(new LfcpError("UNSUPPORTED_VALUE", `IndexedDB ${name} is blocked by another connection`));
+        });
+        return new IdbLfcpStorage(db, options);
+    }
+    /** Closes the connection; later calls fail. */
+    close() {
+        this.#db.close();
+    }
+    async #tx(stores, mode, body) {
+        const tx = mode === "readwrite"
+            ? this.#db.transaction([...stores], mode, { durability: "strict" })
+            : this.#db.transaction([...stores], mode);
+        const done = new Promise((resolve, reject) => {
+            tx.oncomplete = () => resolve();
+            tx.onabort = () => reject(tx.error ?? new LfcpError("UNSUPPORTED_VALUE", "the transaction was aborted"));
+        });
+        let result;
+        try {
+            result = await body(tx);
+        }
+        catch (e) {
+            try {
+                tx.abort();
+            }
+            catch {
+                // already aborting or finished
+            }
+            await done.catch(() => undefined);
+            throw e;
+        }
+        await done;
+        return result;
+    }
+    // -------------------------------------------------------------------------
+    // Writes
+    async commit(writes) {
+        try {
+            return await this.#tx(STORES, "readwrite", async (tx) => {
+                for (const w of writes) {
+                    if (w.op !== "set-control-head")
+                        continue;
+                    const head = (await req(tx.objectStore("heads").get(hex(w.resourceId))));
+                    const current = head?.head ?? null;
+                    const matches = current === null
+                        ? w.expected === null
+                        : w.expected !== null && bytesEqual(current, w.expected);
+                    if (!matches)
+                        throw new HeadMismatch(Object.freeze({
+                            ok: false,
+                            reason: "CONTROL_HEAD_MISMATCH",
+                            resourceId: own(w.resourceId),
+                            current: current === null ? null : own(current),
+                        }));
+                }
+                for (const w of writes) {
+                    if (w.op !== "expect-previous-unit")
+                        continue;
+                    const [r, a] = [hex(w.resourceId), hex(w.actor)];
+                    let cursor = await req(tx
+                        .objectStore("units")
+                        .index("ras")
+                        .openCursor(IDBKeyRange.bound([r, a, LOW], [r, a, HIGH]), "prev"));
+                    while (cursor !== null && !cursor.value.row.accepted) {
+                        cursor.continue();
+                        cursor = await req(cursor.request);
+                    }
+                    const current = cursor === null ? null : cursor.value.row.unitId;
+                    const matches = current === null
+                        ? w.previous === null
+                        : w.previous !== null && bytesEqual(current, w.previous);
+                    if (!matches)
+                        throw new HeadMismatch(Object.freeze({
+                            ok: false,
+                            reason: "PREVIOUS_UNIT_MISMATCH",
+                            resourceId: own(w.resourceId),
+                            actor: own(w.actor),
+                            current: current === null ? null : own(current),
+                        }));
+                }
+                for (const w of writes)
+                    await this.#apply(tx, w);
+                return Object.freeze({ ok: true });
+            });
+        }
+        catch (e) {
+            if (e instanceof HeadMismatch)
+                return e.result;
+            throw e;
+        }
+    }
+    async #putImmutable(store, id, value, what) {
+        const old = (await req(store.get(hex(id))));
+        if (old !== undefined) {
+            if (!bytesEqual(old.row.bytes, value.row.bytes))
+                throw new LfcpError("INVALID_STRUCTURE", `${what} ${hex(id)} is stored with other bytes`);
+            return;
+        }
+        await req(store.put(value, hex(id)));
+    }
+    async #knownUnit(tx, unitId) {
+        const v = (await req(tx.objectStore("units").get(hex(unitId))));
+        if (v === undefined)
+            throw new LfcpError("INVALID_STRUCTURE", `no Data Unit ${hex(unitId)}`);
+        return v.row;
+    }
+    async #apply(tx, w) {
+        const s = (name) => tx.objectStore(name);
+        switch (w.op) {
+            case "put-control-records":
+                for (const r of w.records)
+                    await this.#putImmutable(s("records"), r.recordId, { r: hex(r.resourceId), row: r }, "Control Record");
+                return;
+            case "set-control-head":
+                await req(s("heads").put(w.head, hex(w.resourceId)));
+                return;
+            case "set-control-conflict":
+                if (w.conflict === null)
+                    await req(s("conflicts").delete(hex(w.resourceId)));
+                else
+                    await req(s("conflicts").put(w.conflict, hex(w.resourceId)));
+                return;
+            case "expect-previous-unit":
+                return; // a precondition, checked by commit()
+            case "put-epoch": {
+                const key = `${hex(w.resourceId)}:${pad(BigInt(w.epoch.epoch))}`;
+                // A null dekRef or closedBy never clears a stored one (read and write
+                // in this transaction).
+                const stored = (await req(s("epochs").get(key)));
+                const row = {
+                    ...w.epoch,
+                    closedBy: w.epoch.closedBy ?? stored?.row.closedBy ?? null,
+                    dekRef: w.epoch.dekRef ?? stored?.row.dekRef ?? null,
+                };
+                await req(s("epochs").put({ r: hex(w.resourceId), row }, key));
+                return;
+            }
+            case "put-data-unit": {
+                const old = (await req(s("units").get(hex(w.unit.unitId))));
+                if (old !== undefined && !bytesEqual(old.row.bytes, w.unit.bytes))
+                    throw new LfcpError("INVALID_STRUCTURE", `Data Unit ${hex(w.unit.unitId)} is stored with other bytes`);
+                const row = {
+                    ...pickUnit(old?.row ?? w.unit),
+                    status: w.status,
+                    detail: w.detail ?? null,
+                    accepted: w.accepted ?? old?.row.accepted ?? false,
+                };
+                await req(s("units").put(unitValue(row), hex(w.unit.unitId)));
+                return;
+            }
+            case "set-data-unit-status": {
+                const old = await this.#knownUnit(tx, w.unitId);
+                const row = { ...old, status: w.status, detail: w.detail ?? null };
+                await req(s("units").put(unitValue(row), hex(w.unitId)));
+                return;
+            }
+            case "set-accepted": {
+                const old = await this.#knownUnit(tx, w.unitId);
+                await req(s("units").put(unitValue({ ...old, accepted: w.accepted }), hex(w.unitId)));
+                return;
+            }
+            case "put-key-package":
+                await this.#putImmutable(s("keyPackages"), w.row.packageId, { r: hex(w.row.resourceId), row: w.row }, "Key Package");
+                return;
+            case "put-snapshot":
+                await this.#putImmutable(s("snapshots"), w.row.snapshotId, {
+                    r: hex(w.row.resourceId),
+                    e: pad(BigInt(w.row.dataEpoch)),
+                    p: hex(w.row.publisher),
+                    n: pad(w.row.snapshotSeq),
+                    row: w.row,
+                }, "Snapshot");
+                return;
+            case "delete-snapshot":
+                await req(s("snapshots").delete(hex(w.snapshotId)));
+                return;
+            case "put-resource":
+                await req(s("resources").put(w.row, hex(w.row.resourceId)));
+                return;
+            case "put-route":
+                await req(s("routes").put(w.route, hex(w.resourceId)));
+                return;
+            case "enqueue": {
+                const old = (await req(s("outbound").get(hex(w.item.itemId))));
+                if (old !== undefined) {
+                    if (!bytesEqual(old.row.bytes, w.item.bytes))
+                        throw new LfcpError("INVALID_STRUCTURE", `outbound item ${hex(w.item.itemId)} is stored with other bytes`);
+                    return;
+                }
+                const n = (await req(s("counters").get(ORDER_KEY))) ?? 0;
+                await req(s("counters").put(n + 1, ORDER_KEY));
+                await req(s("outbound").put({ r: hex(w.item.resourceId), n: n + 1, row: w.item }, hex(w.item.itemId)));
+                return;
+            }
+            case "update-outbound": {
+                const old = (await req(s("outbound").get(hex(w.itemId))));
+                if (old === undefined)
+                    throw new LfcpError("INVALID_STRUCTURE", `no outbound item ${hex(w.itemId)}`);
+                const row = {
+                    ...old.row,
+                    ...(w.attempts === undefined ? {} : { attempts: w.attempts }),
+                    ...(w.lastAttempt === undefined ? {} : { lastAttempt: w.lastAttempt }),
+                    ...(w.nextAttempt === undefined ? {} : { nextAttempt: w.nextAttempt }),
+                    ...(w.blocked === undefined ? {} : { blocked: w.blocked }),
+                };
+                await req(s("outbound").put({ ...old, row }, hex(w.itemId)));
+                return;
+            }
+            case "dequeue":
+                await req(s("outbound").delete(hex(w.itemId)));
+                return;
+            case "put-profile-checkpoint":
+                await req(s("checkpoints").put(w.checkpoint, hex(w.checkpoint.resourceId)));
+                return;
+            case "put-sync-state":
+                await req(s("syncStates").put(w.row, hex(w.row.resourceId)));
+                return;
+            case "put-local-mark": {
+                // Kept in the meta store under "mark:" (no schema change).
+                const key = `${MARK}${w.key}`;
+                if (w.value === null)
+                    await req(s("meta").delete(key));
+                else
+                    await req(s("meta").put(w.value, key));
+                return;
+            }
+        }
+    }
+    // -------------------------------------------------------------------------
+    // Sequence reservations
+    actorSequences = {
+        reserveNext: async (resource, principal) => {
+            const key = actorKey(resource, principal);
+            const next = await this.#tx(["counters", "units"], "readwrite", async (tx) => {
+                const last = (await req(tx.objectStore("counters").get(key)));
+                const next = nextActorSequence(last);
+                const [r, a] = [hex(resource), hex(principal)];
+                const top = await req(tx
+                    .objectStore("units")
+                    .index("ras")
+                    .openCursor(IDBKeyRange.bound([r, a, LOW], [r, a, HIGH]), "prev"));
+                const max = top === null ? 0n : top.value.row.actorSeq;
+                // Fail closed (§9): a counter behind this Principal's own stored units
+                // (a restored backup, a lost row) must never hand out a used sequence.
+                if (next <= max)
+                    throw new LfcpError("SEQUENCE_REUSE", `the actor sequence state (${next - 1n}) is behind the stored units of this Principal (${max}); refusing to reserve (§9)`);
+                await req(tx.objectStore("counters").put(next, key));
+                return next;
+            });
+            this.#onReserved?.({ kind: "actor", key, value: next });
+            return next;
+        },
+    };
+    snapshotSequences = {
+        reserveNext: async (resource, epoch, publisher) => {
+            const key = snapshotKey(resource, epoch, publisher);
+            const next = await this.#tx(["counters", "snapshots"], "readwrite", async (tx) => {
+                const last = (await req(tx.objectStore("counters").get(key))) ?? 0n;
+                if (last >= UINT64_MAX)
+                    throw new LfcpError("OUT_OF_RANGE", "the Snapshot Sequence space is exhausted (§29)");
+                const [r, e, p] = [hex(resource), pad(BigInt(epoch)), hex(publisher)];
+                const top = await req(tx
+                    .objectStore("snapshots")
+                    .index("rep")
+                    .openCursor(IDBKeyRange.bound([r, e, p, LOW], [r, e, p, HIGH]), "prev"));
+                const max = top === null ? 0n : top.value.row.snapshotSeq;
+                if (last + 1n <= max)
+                    throw new LfcpError("SEQUENCE_REUSE", `the Snapshot Sequence state (${last}) is behind the stored Snapshots of this publisher (${max}); refusing to reserve (§29)`);
+                await req(tx.objectStore("counters").put(last + 1n, key));
+                return last + 1n;
+            });
+            this.#onReserved?.({ kind: "snapshot", key, value: next });
+            return next;
+        },
+    };
+    /** Every reservation counter: `actor:<resource>:<principal>` and `snapshot:<resource>:<epoch>:<publisher>`. */
+    async counters() {
+        return this.#tx(["counters"], "readonly", async (tx) => {
+            const store = tx.objectStore("counters");
+            const [keys, values] = await Promise.all([req(store.getAllKeys()), req(store.getAll())]);
+            const out = new Map();
+            keys.forEach((k, i) => {
+                if (typeof k === "string" && (k.startsWith("actor:") || k.startsWith("snapshot:")))
+                    out.set(k, values[i]);
+            });
+            return out;
+        });
+    }
+    /**
+     * Adapter-local metadata for the application (e.g. an install marker):
+     * structured-cloneable values, durable like everything else. Never secrets.
+     */
+    meta = {
+        get: (key) => this.#tx(["meta"], "readonly", async (tx) => copyOf(await req(tx.objectStore("meta").get(key)))),
+        put: (key, value) => this.#tx(["meta"], "readwrite", async (tx) => {
+            await req(tx.objectStore("meta").put(value, key));
+        }),
+    };
+    // -------------------------------------------------------------------------
+    // Readers
+    #get(store, key) {
+        return this.#tx([store], "readonly", async (tx) => {
+            const v = (await req(tx.objectStore(store).get(key)));
+            return copyOf(v);
+        });
+    }
+    #byResource(store, resource) {
+        return this.#tx([store], "readonly", async (tx) => (await req(tx.objectStore(store).index("r").getAll(hex(resource)))).map((v) => v.row));
+    }
+    #unitsWhere(range, index) {
+        return this.#tx(["units"], "readonly", async (tx) => (await req(tx.objectStore("units").index(index).getAll(range))).map((v) => v.row));
+    }
+    #at(resource, actor, seq) {
+        return this.#unitsWhere(IDBKeyRange.only([hex(resource), hex(actor), pad(seq)]), "ras").then((us) => us.sort((a, b) => byHex(a.unitId, b.unitId)));
+    }
+    control = {
+        record: (id) => this.#get("records", hex(id)).then((v) => v?.row),
+        records: async (resource) => (await this.#byResource("records", resource))
+            .sort((a, b) => byBig(a.controlSeq, b.controlSeq) || byHex(a.recordId, b.recordId))
+            .map(own),
+        head: (resource) => this.#get("heads", hex(resource)),
+        conflict: (resource) => this.#get("conflicts", hex(resource)),
+        epochs: async (resource) => (await this.#byResource("epochs", resource))
+            .sort((a, b) => byBig(a.epoch, b.epoch))
+            .map(own),
+    };
+    dataUnits = {
+        get: (id) => this.#get("units", hex(id)).then((v) => v?.row),
+        at: async (resource, actor, seq) => (await this.#at(resource, actor, seq)).map(own),
+        range: async (resource, actor, from, to) => {
+            if (from > to)
+                return [];
+            const [r, a] = [hex(resource), hex(actor)];
+            return (await this.#unitsWhere(IDBKeyRange.bound([r, a, pad(from)], [r, a, pad(to)]), "ras"))
+                .sort(UNIT_ORDER)
+                .map(own);
+        },
+        withStatus: async (resource, status) => (await this.#unitsWhere(IDBKeyRange.only([hex(resource), status]), "rst"))
+            .sort(UNIT_ORDER)
+            .map(own),
+        acceptedAt: async (resource, actor, seq) => copyOf((await this.#at(resource, actor, seq)).find((u) => u.accepted)?.unitId),
+        recordSeen: (unit) => this.#tx(["units"], "readwrite", async (tx) => {
+            const store = tx.objectStore("units");
+            const old = (await req(store.get(hex(unit.unitId))));
+            if (old !== undefined && !bytesEqual(old.row.bytes, unit.bytes))
+                throw new LfcpError("INVALID_STRUCTURE", `Data Unit ${hex(unit.unitId)} is stored with other bytes`);
+            if (old === undefined)
+                await req(store.put(unitValue({ ...pickUnit(unit), status: "seen", detail: null, accepted: false }), hex(unit.unitId)));
+            const all = (await req(store
+                .index("ras")
+                .getAll(IDBKeyRange.only([hex(unit.resourceId), hex(unit.actor), pad(unit.actorSeq)]))));
+            const unitIds = all.map((v) => own(v.row.unitId)).sort(byHex);
+            return Object.freeze({ unitIds: Object.freeze(unitIds), firstSeen: old === undefined });
+        }),
+    };
+    keyPackages = {
+        get: (id) => this.#get("keyPackages", hex(id)).then((v) => v?.row),
+        list: async (resource, filter = {}) => (await this.#byResource("keyPackages", resource))
+            .filter((k) => (filter.epoch === undefined || k.dataEpoch === filter.epoch) &&
+            (filter.recipient === undefined || bytesEqual(k.recipient, filter.recipient)))
+            .sort((a, b) => byBig(a.dataEpoch, b.dataEpoch) || byHex(a.packageId, b.packageId))
+            .map(own),
+    };
+    snapshots = {
+        get: (id) => this.#get("snapshots", hex(id)).then((v) => v?.row),
+        list: async (resource, filter = {}) => (await this.#byResource("snapshots", resource))
+            .filter((x) => filter.epoch === undefined || x.dataEpoch === filter.epoch)
+            .sort((a, b) => byBig(a.dataEpoch, b.dataEpoch) ||
+            byHex(a.publisher, b.publisher) ||
+            byBig(a.snapshotSeq, b.snapshotSeq))
+            .map(own),
+    };
+    resources = {
+        get: (resource) => this.#get("resources", hex(resource)),
+        list: () => this.#tx(["resources"], "readonly", async (tx) => (await req(tx.objectStore("resources").getAll()))
+            .sort((a, b) => byHex(a.resourceId, b.resourceId))
+            .map(own)),
+        route: (resource) => this.#get("routes", hex(resource)),
+    };
+    outbound = {
+        list: (resource) => this.#tx(["outbound"], "readonly", async (tx) => (await req(tx.objectStore("outbound").index("n").getAll()))
+            .filter((v) => resource === undefined || v.r === hex(resource))
+            .map((v) => own(v.row))),
+        get: (id) => this.#get("outbound", hex(id)).then((v) => v?.row),
+    };
+    profileState = {
+        checkpoint: (resource) => this.#get("checkpoints", hex(resource)),
+    };
+    syncState = {
+        get: (resource) => this.#get("syncStates", hex(resource)),
+    };
+    localMarks = {
+        get: (key) => this.#get("meta", `${MARK}${key}`),
+        list: (prefix) => this.#tx(["meta"], "readonly", async (tx) => {
+            const range = IDBKeyRange.bound(`${MARK}${prefix}`, `${MARK}${prefix}${HIGH}`);
+            const store = tx.objectStore("meta");
+            const [keys, values] = await Promise.all([
+                req(store.getAllKeys(range)),
+                req(store.getAll(range)),
+            ]);
+            return keys.map((k, i) => ({
+                key: k.slice(MARK.length),
+                value: values[i],
+            }));
+        }),
+    };
+}
+//# sourceMappingURL=idb.js.map

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Durable portable storage for LFCP clients (LFCP-059): LfcpStorage on
+ * IndexedDB, for browsers, Electron and mobile WebViews. The application
+ * names the database (one per client install) and keeps secrets in its own
+ * SecretStore.
+ */
+export declare const PACKAGE = "@openlfcp/storage-idb";
+export { IdbLfcpStorage, type IdbStorageOptions, type ReservedSequence } from "./idb.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * Durable portable storage for LFCP clients (LFCP-059): LfcpStorage on
+ * IndexedDB, for browsers, Electron and mobile WebViews. The application
+ * names the database (one per client install) and keeps secrets in its own
+ * SecretStore.
+ */
+export const PACKAGE = "@openlfcp/storage-idb";
+export { IdbLfcpStorage } from "./idb.js";
+//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,51 @@
 {
   "name": "@openlfcp/storage-idb",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-rc.1",
+  "description": "Durable portable storage for LFCP clients on IndexedDB (browsers, Electron, mobile WebViews).",
+  "keywords": [
+    "openlfcp",
+    "lfcp",
+    "local-first",
+    "end-to-end-encryption",
+    "storage",
+    "indexeddb",
+    "browser"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/openlfcp/sdk-ts/tree/main/packages/storage-idb#readme",
+  "bugs": {
+    "url": "https://github.com/openlfcp/sdk-ts/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openlfcp/sdk-ts.git",
+    "directory": "packages/storage-idb"
+  },
+  "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": {
+    "@openlfcp/core": "^0.1.0-rc.1",
+    "@openlfcp/storage": "^0.1.0-rc.1"
+  },
+  "devDependencies": {
+    "fake-indexeddb": "6.2.5"
+  }
 }