@openlfcp/storage 0.1.0-rc.1

package/dist/memory.js

@@ -0,0 +1,367 @@
+import { bytesEqual, LfcpError, toHex, } from "@openlfcp/core";
+import { InMemoryActorSequenceReservation } from "./sequence.js";
+import { InMemorySnapshotSequenceReservation, } from "./snapshot-sequence.js";
+/** A deep copy: every Uint8Array copied, everything frozen. Nothing stored aliases a caller's buffer. */
+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 hex = toHex;
+const byBytes = (a, b) => {
+    const [x, y] = [hex(a), hex(b)];
+    return x < y ? -1 : x > y ? 1 : 0;
+};
+const tuple = (resource, actor, seq) => `${hex(resource)}:${hex(actor)}:${seq}`;
+const emptyState = () => ({
+    records: new Map(),
+    heads: new Map(),
+    conflicts: new Map(),
+    epochs: new Map(),
+    units: new Map(),
+    keyPackages: new Map(),
+    snapshots: new Map(),
+    resources: new Map(),
+    routes: new Map(),
+    outbound: new Map(),
+    checkpoints: new Map(),
+    syncStates: new Map(),
+    marks: new Map(),
+});
+/** Rows are immutable, so a staged copy of the maps is enough for all-or-nothing batches. */
+const stage = (s) => ({
+    records: new Map(s.records),
+    heads: new Map(s.heads),
+    conflicts: new Map(s.conflicts),
+    epochs: new Map([...s.epochs].map(([k, v]) => [k, new Map(v)])),
+    units: new Map(s.units),
+    keyPackages: new Map(s.keyPackages),
+    snapshots: new Map(s.snapshots),
+    resources: new Map(s.resources),
+    routes: new Map(s.routes),
+    outbound: new Map(s.outbound),
+    checkpoints: new Map(s.checkpoints),
+    syncStates: new Map(s.syncStates),
+    marks: new Map(s.marks),
+});
+/** Stores an immutable object under its ID; the same ID with other bytes is refused. */
+function putImmutable(map, id, row, what) {
+    const old = map.get(hex(id));
+    if (old !== undefined) {
+        if (!bytesEqual(old.bytes, row.bytes))
+            throw new LfcpError("INVALID_STRUCTURE", `${what} ${hex(id)} is stored with other bytes`);
+        return;
+    }
+    map.set(hex(id), own(row));
+}
+function apply(s, w) {
+    switch (w.op) {
+        case "put-control-records":
+            for (const r of w.records)
+                putImmutable(s.records, r.recordId, r, "Control Record");
+            return;
+        case "set-control-head":
+            s.heads.set(hex(w.resourceId), own(w.head));
+            return;
+        case "set-control-conflict":
+            if (w.conflict === null)
+                s.conflicts.delete(hex(w.resourceId));
+            else
+                s.conflicts.set(hex(w.resourceId), own(w.conflict));
+            return;
+        case "put-epoch": {
+            const key = hex(w.resourceId);
+            const epochs = s.epochs.get(key) ?? new Map();
+            const stored = epochs.get(BigInt(w.epoch.epoch));
+            epochs.set(BigInt(w.epoch.epoch), own({
+                ...w.epoch,
+                closedBy: w.epoch.closedBy ?? stored?.closedBy ?? null,
+                dekRef: w.epoch.dekRef ?? stored?.dekRef ?? null,
+            }));
+            s.epochs.set(key, epochs);
+            return;
+        }
+        case "expect-previous-unit":
+            return; // a precondition, checked by commit()
+        case "put-data-unit": {
+            const old = s.units.get(hex(w.unit.unitId));
+            if (old !== undefined && !bytesEqual(old.bytes, w.unit.bytes))
+                throw new LfcpError("INVALID_STRUCTURE", `Data Unit ${hex(w.unit.unitId)} is stored with other bytes`);
+            const base = old ?? w.unit;
+            s.units.set(hex(w.unit.unitId), own({
+                ...pickUnit(base),
+                status: w.status,
+                detail: w.detail ?? null,
+                accepted: w.accepted ?? old?.accepted ?? false,
+            }));
+            return;
+        }
+        case "set-data-unit-status": {
+            const old = known(s, w.unitId);
+            s.units.set(hex(w.unitId), own({ ...old, status: w.status, detail: w.detail ?? null }));
+            return;
+        }
+        case "set-accepted": {
+            const old = known(s, w.unitId);
+            s.units.set(hex(w.unitId), own({ ...old, accepted: w.accepted }));
+            return;
+        }
+        case "put-key-package":
+            putImmutable(s.keyPackages, w.row.packageId, w.row, "Key Package");
+            return;
+        case "delete-snapshot":
+            s.snapshots.delete(hex(w.snapshotId));
+            return;
+        case "put-snapshot":
+            putImmutable(s.snapshots, w.row.snapshotId, w.row, "Snapshot");
+            return;
+        case "put-resource":
+            s.resources.set(hex(w.row.resourceId), own(w.row));
+            return;
+        case "put-route":
+            s.routes.set(hex(w.resourceId), own(w.route));
+            return;
+        case "enqueue":
+            putImmutable(s.outbound, w.item.itemId, w.item, "outbound item");
+            return;
+        case "update-outbound": {
+            const old = s.outbound.get(hex(w.itemId));
+            if (old === undefined)
+                throw new LfcpError("INVALID_STRUCTURE", `no outbound item ${hex(w.itemId)}`);
+            s.outbound.set(hex(w.itemId), own({
+                ...old,
+                ...(w.attempts === undefined ? {} : { attempts: w.attempts }),
+                ...(w.lastAttempt === undefined ? {} : { lastAttempt: w.lastAttempt }),
+                ...(w.nextAttempt === undefined ? {} : { nextAttempt: w.nextAttempt }),
+                ...(w.blocked === undefined ? {} : { blocked: w.blocked }),
+            }));
+            return;
+        }
+        case "dequeue":
+            s.outbound.delete(hex(w.itemId));
+            return;
+        case "put-profile-checkpoint":
+            s.checkpoints.set(hex(w.checkpoint.resourceId), own(w.checkpoint));
+            return;
+        case "put-sync-state":
+            s.syncStates.set(hex(w.row.resourceId), own(w.row));
+            return;
+        case "put-local-mark":
+            if (w.value === null)
+                s.marks.delete(w.key);
+            else
+                s.marks.set(w.key, w.value);
+            return;
+    }
+}
+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,
+});
+function known(s, unitId) {
+    const u = s.units.get(hex(unitId));
+    if (u === undefined)
+        throw new LfcpError("INVALID_STRUCTURE", `no Data Unit ${hex(unitId)}`);
+    return u;
+}
+const ACCEPTED_ORDER = (a, b) => byBytes(a.actor, b.actor) ||
+    (a.actorSeq < b.actorSeq ? -1 : a.actorSeq > b.actorSeq ? 1 : 0) ||
+    byBytes(a.unitId, b.unitId);
+/**
+ * FOR TESTS AND DEVELOPMENT ONLY: an LfcpStorage in process memory, lost on
+ * restart, with the same semantic contracts as a durable adapter (exact
+ * bytes copied in and out, immutable objects, all-or-nothing batches with
+ * their preconditions). Deterministic: no clock, no randomness, ordered
+ * results.
+ */
+export class InMemoryLfcpStorage {
+    #state = emptyState();
+    #actorCounter = new InMemoryActorSequenceReservation();
+    #snapshotCounter = new InMemorySnapshotSequenceReservation();
+    /** Reservations fail closed when the counter is behind this Principal's own stored objects (§9, §29). */
+    actorSequences = {
+        reserveNext: async (resource, principal) => {
+            const next = await this.#actorCounter.reserveNext(resource, principal);
+            const max = [...this.#state.units.values()]
+                .filter((u) => bytesEqual(u.resourceId, resource) && bytesEqual(u.actor, principal))
+                .reduce((m, u) => (u.actorSeq > m ? BigInt(u.actorSeq) : m), 0n);
+            if (next <= max)
+                throw new LfcpError("SEQUENCE_REUSE", `the actor sequence state is behind the stored units of this Principal (${max}); refusing to reserve (§9)`);
+            return next;
+        },
+    };
+    snapshotSequences = {
+        reserveNext: async (resource, epoch, publisher) => {
+            const next = await this.#snapshotCounter.reserveNext(resource, epoch, publisher);
+            const max = [...this.#state.snapshots.values()]
+                .filter((x) => bytesEqual(x.resourceId, resource) &&
+                x.dataEpoch === epoch &&
+                bytesEqual(x.publisher, publisher))
+                .reduce((m, x) => (x.snapshotSeq > m ? x.snapshotSeq : m), 0n);
+            if (next <= max)
+                throw new LfcpError("SEQUENCE_REUSE", `the Snapshot Sequence state is behind the stored Snapshots of this publisher (${max}); refusing to reserve (§29)`);
+            return next;
+        },
+    };
+    commit(writes) {
+        const next = stage(this.#state);
+        for (const w of writes) {
+            if (w.op !== "set-control-head")
+                continue;
+            const current = next.heads.get(hex(w.resourceId))?.head ?? null;
+            const matches = current === null
+                ? w.expected === null
+                : w.expected !== null && bytesEqual(current, w.expected);
+            if (!matches)
+                return Promise.resolve(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;
+            let latest;
+            for (const u of next.units.values())
+                if (u.accepted &&
+                    bytesEqual(u.resourceId, w.resourceId) &&
+                    bytesEqual(u.actor, w.actor) &&
+                    (latest === undefined || u.actorSeq > latest.actorSeq))
+                    latest = u;
+            const current = latest?.unitId ?? null;
+            const matches = current === null
+                ? w.previous === null
+                : w.previous !== null && bytesEqual(current, w.previous);
+            if (!matches)
+                return Promise.resolve(Object.freeze({
+                    ok: false,
+                    reason: "PREVIOUS_UNIT_MISMATCH",
+                    resourceId: own(w.resourceId),
+                    actor: own(w.actor),
+                    current: current === null ? null : own(current),
+                }));
+        }
+        try {
+            for (const w of writes)
+                apply(next, w);
+        }
+        catch (e) {
+            return Promise.reject(e);
+        }
+        this.#state = next;
+        return Promise.resolve(Object.freeze({ ok: true }));
+    }
+    control = {
+        record: (id) => Promise.resolve(copyOf(this.#state.records.get(hex(id)))),
+        records: (resource) => Promise.resolve([...this.#state.records.values()]
+            .filter((r) => bytesEqual(r.resourceId, resource))
+            .sort((a, b) => a.controlSeq < b.controlSeq
+            ? -1
+            : a.controlSeq > b.controlSeq
+                ? 1
+                : byBytes(a.recordId, b.recordId))
+            .map(own)),
+        head: (resource) => Promise.resolve(copyOf(this.#state.heads.get(hex(resource)))),
+        conflict: (resource) => Promise.resolve(copyOf(this.#state.conflicts.get(hex(resource)))),
+        epochs: (resource) => Promise.resolve([...(this.#state.epochs.get(hex(resource))?.values() ?? [])]
+            .sort((a, b) => (a.epoch < b.epoch ? -1 : a.epoch > b.epoch ? 1 : 0))
+            .map(own)),
+    };
+    dataUnits = {
+        get: (id) => Promise.resolve(copyOf(this.#state.units.get(hex(id)))),
+        at: (resource, actor, seq) => Promise.resolve(this.#at(resource, actor, seq).map(own)),
+        range: (resource, actor, from, to) => Promise.resolve(this.#units((u) => bytesEqual(u.resourceId, resource) &&
+            bytesEqual(u.actor, actor) &&
+            u.actorSeq >= from &&
+            u.actorSeq <= to)),
+        withStatus: (resource, status) => Promise.resolve(this.#units((u) => bytesEqual(u.resourceId, resource) && u.status === status)),
+        acceptedAt: (resource, actor, seq) => Promise.resolve(copyOf(this.#at(resource, actor, seq).find((u) => u.accepted)?.unitId)),
+        recordSeen: (unit) => {
+            const firstSeen = !this.#state.units.has(hex(unit.unitId));
+            if (firstSeen) {
+                const next = stage(this.#state);
+                apply(next, { op: "put-data-unit", unit, status: "seen" });
+                this.#state = next;
+            }
+            else if (!bytesEqual(this.#state.units.get(hex(unit.unitId)).bytes, unit.bytes)) {
+                return Promise.reject(new LfcpError("INVALID_STRUCTURE", `Data Unit ${hex(unit.unitId)} is stored with other bytes`));
+            }
+            const unitIds = this.#at(unit.resourceId, unit.actor, unit.actorSeq)
+                .map((u) => own(u.unitId))
+                .sort(byBytes);
+            return Promise.resolve(Object.freeze({ unitIds: Object.freeze(unitIds), firstSeen }));
+        },
+    };
+    #at(resource, actor, seq) {
+        const key = tuple(resource, actor, seq);
+        return [...this.#state.units.values()]
+            .filter((u) => tuple(u.resourceId, u.actor, u.actorSeq) === key)
+            .sort((a, b) => byBytes(a.unitId, b.unitId));
+    }
+    #units(keep) {
+        return [...this.#state.units.values()].filter(keep).sort(ACCEPTED_ORDER).map(own);
+    }
+    keyPackages = {
+        get: (id) => Promise.resolve(copyOf(this.#state.keyPackages.get(hex(id)))),
+        list: (resource, filter = {}) => Promise.resolve([...this.#state.keyPackages.values()]
+            .filter((k) => bytesEqual(k.resourceId, resource) &&
+            (filter.epoch === undefined || k.dataEpoch === filter.epoch) &&
+            (filter.recipient === undefined || bytesEqual(k.recipient, filter.recipient)))
+            .sort((a, b) => a.dataEpoch < b.dataEpoch
+            ? -1
+            : a.dataEpoch > b.dataEpoch
+                ? 1
+                : byBytes(a.packageId, b.packageId))
+            .map(own)),
+    };
+    snapshots = {
+        get: (id) => Promise.resolve(copyOf(this.#state.snapshots.get(hex(id)))),
+        list: (resource, filter = {}) => Promise.resolve([...this.#state.snapshots.values()]
+            .filter((s) => bytesEqual(s.resourceId, resource) &&
+            (filter.epoch === undefined || s.dataEpoch === filter.epoch))
+            .sort((a, b) => (a.dataEpoch < b.dataEpoch ? -1 : a.dataEpoch > b.dataEpoch ? 1 : 0) ||
+            byBytes(a.publisher, b.publisher) ||
+            (a.snapshotSeq < b.snapshotSeq ? -1 : a.snapshotSeq > b.snapshotSeq ? 1 : 0))
+            .map(own)),
+    };
+    resources = {
+        get: (resource) => Promise.resolve(copyOf(this.#state.resources.get(hex(resource)))),
+        list: () => Promise.resolve([...this.#state.resources.values()]
+            .sort((a, b) => byBytes(a.resourceId, b.resourceId))
+            .map(own)),
+        route: (resource) => Promise.resolve(copyOf(this.#state.routes.get(hex(resource)))),
+    };
+    outbound = {
+        list: (resource) => Promise.resolve([...this.#state.outbound.values()]
+            .filter((o) => resource === undefined || bytesEqual(o.resourceId, resource))
+            .map(own)),
+        get: (id) => Promise.resolve(copyOf(this.#state.outbound.get(hex(id)))),
+    };
+    profileState = {
+        checkpoint: (resource) => Promise.resolve(copyOf(this.#state.checkpoints.get(hex(resource)))),
+    };
+    syncState = {
+        get: (resource) => Promise.resolve(copyOf(this.#state.syncStates.get(hex(resource)))),
+    };
+    localMarks = {
+        get: (key) => Promise.resolve(this.#state.marks.get(key)),
+        list: (prefix) => Promise.resolve([...this.#state.marks]
+            .filter(([key]) => key.startsWith(prefix))
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([key, value]) => ({ key, value }))),
+    };
+}
+const copyOf = (value) => value === undefined ? undefined : own(value);
+//# sourceMappingURL=memory.js.map

package/dist/secrets.d.ts

@@ -0,0 +1,53 @@
+import { type DataEpoch, type PrincipalId, type ResourceId } from "@openlfcp/core";
+/**
+ * Client secret material (LFCP-034): Principal private keys, Resource DEKs
+ * and invitation secrets live only in a SecretStore. Public storage rows
+ * hold a SecretRef, a name that reveals nothing about the value.
+ *
+ * A SecretStore cannot be enumerated: there is no list operation, so no
+ * caller can dump its contents into a log or a diagnostic. Backends are
+ * platform specific: app.secretStorage in Obsidian (LFCP-059), a file
+ * keystore in Node (LFCP-035). No cloud KMS is required.
+ *
+ * Ordering rule, since a SecretStore is usually a different backend from
+ * the public rows and cannot join their atomic batch: write the secret
+ * first, then commit the row that references it. A reference without a
+ * value is a recoverable gap; a value without a reference is harmless.
+ */
+export type SecretKind = "principal-signing-key" | "principal-agreement-key" | "resource-dek" | "invitation-secret";
+/** The name of a secret: "lfcp-secret:<kind>:<id>". It never contains secret material. */
+export type SecretRef = string & {
+    readonly __secretRef: true;
+};
+/** A secret reference; `id` is a public name such as hex IDs joined with ".". */
+export declare function secretRef(kind: SecretKind, id: string): SecretRef;
+/** True when `text` is a well-formed secret reference. */
+export declare function isSecretRef(text: unknown): text is SecretRef;
+/** The reference of the DEK of `epoch` of `resource`. */
+export declare const dekSecretRef: (resource: ResourceId, epoch: DataEpoch) => SecretRef;
+/** The reference of a local Principal's private signing or agreement key. */
+export declare const principalKeySecretRef: (principal: PrincipalId, which: "signing" | "agreement") => SecretRef;
+export interface SecretStore {
+    /** Stores a copy of `value` under `ref`, replacing any previous value. Durable before it resolves. */
+    put(ref: SecretRef, value: Uint8Array): Promise<void>;
+    /** A copy of the value, or undefined. */
+    get(ref: SecretRef): Promise<Uint8Array | undefined>;
+    delete(ref: SecretRef): Promise<void>;
+}
+declare const INSPECT: unique symbol;
+/**
+ * FOR TESTS AND DEVELOPMENT ONLY: secrets in plain process memory, lost on
+ * restart. Renders as "[InMemorySecretStore]" in JSON and inspection, so it
+ * cannot leak values into logs by accident.
+ */
+export declare class InMemorySecretStore implements SecretStore {
+    #private;
+    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,60 @@
+import { dataEpoch, LfcpError, toHex, } from "@openlfcp/core";
+const KINDS = new Set([
+    "principal-signing-key",
+    "principal-agreement-key",
+    "resource-dek",
+    "invitation-secret",
+]);
+const ID = /^[A-Za-z0-9._-]{1,200}$/;
+/** A secret reference; `id` is a public name such as hex IDs joined with ".". */
+export function secretRef(kind, id) {
+    if (!KINDS.has(kind))
+        throw new LfcpError("UNSUPPORTED_VALUE", `unknown secret kind ${kind}`);
+    if (!ID.test(id))
+        throw new LfcpError("UNSUPPORTED_VALUE", "a secret reference id is [A-Za-z0-9._-]{1,200}");
+    return `lfcp-secret:${kind}:${id}`;
+}
+/** True when `text` is a well-formed secret reference. */
+export function isSecretRef(text) {
+    if (typeof text !== "string")
+        return false;
+    const m = /^lfcp-secret:([a-z-]+):(.+)$/.exec(text);
+    return m !== null && KINDS.has(m[1]) && ID.test(m[2]);
+}
+/** The reference of the DEK of `epoch` of `resource`. */
+export const dekSecretRef = (resource, epoch) => secretRef("resource-dek", `${toHex(resource)}.${dataEpoch(epoch)}`);
+/** The reference of a local Principal's private signing or agreement key. */
+export const principalKeySecretRef = (principal, which) => secretRef(which === "signing" ? "principal-signing-key" : "principal-agreement-key", toHex(principal));
+const INSPECT = Symbol.for("nodejs.util.inspect.custom");
+/**
+ * FOR TESTS AND DEVELOPMENT ONLY: secrets in plain process memory, lost on
+ * restart. Renders as "[InMemorySecretStore]" in JSON and inspection, so it
+ * cannot leak values into logs by accident.
+ */
+export class InMemorySecretStore {
+    #values = new Map();
+    put(ref, value) {
+        if (!isSecretRef(ref))
+            return Promise.reject(new LfcpError("UNSUPPORTED_VALUE", "not a secret reference"));
+        this.#values.set(ref, Uint8Array.from(value));
+        return Promise.resolve();
+    }
+    get(ref) {
+        const v = this.#values.get(ref);
+        return Promise.resolve(v === undefined ? undefined : Uint8Array.from(v));
+    }
+    delete(ref) {
+        this.#values.delete(ref);
+        return Promise.resolve();
+    }
+    toJSON() {
+        return "[InMemorySecretStore]";
+    }
+    toString() {
+        return "[InMemorySecretStore]";
+    }
+    [INSPECT]() {
+        return "[InMemorySecretStore]";
+    }
+}
+//# sourceMappingURL=secrets.js.map

package/dist/sequence.d.ts

@@ -0,0 +1,55 @@
+import { type ActorSequence, type PrincipalId, type ResourceId } from "@openlfcp/core";
+/**
+ * Actor sequence allocation (LFCP-WIRE-01 §8, §12).
+ *
+ * A writer's Data Unit nonce is 0x00000000 || uint64_be(seq) under a key
+ * that depends on (Resource, Data Epoch, Principal). A sequence used twice
+ * for one (Resource, Principal) can reuse a nonce under the same key, so
+ * sequences are scoped to (Resource, Principal), start at 1, and never go
+ * back, not even when the Data Epoch changes.
+ */
+export interface ActorSequenceReservation {
+    /**
+     * Reserves the next actor sequence for `principal` writing to `resource`.
+     *
+     * Contract: the reservation is durable before the promise resolves (a
+     * crash after it resolves can never hand out the same value again), and
+     * the same (resource, principal, seq) is never returned twice, across
+     * Data Epochs, restarts and concurrent callers. A caller that cannot use
+     * a reserved sequence abandons it; it is never returned to the pool.
+     *
+     * When the state is lost and cannot be reconstructed safely, the writer
+     * must switch to a new Principal for that Resource (§8). When the space
+     * is exhausted (2^64 - 1 was handed out) it rejects with OUT_OF_RANGE.
+     *
+     * The durable implementations belong to the storage tasks: LFCP-034
+     * (storage abstraction), LFCP-035 (Node persistence adapter, "atomic
+     * enough to prevent sequence reuse") and LFCP-036 (pending outbound
+     * queue: a retry never regenerates a Data Unit with the same sequence).
+     */
+    reserveNext(resource: ResourceId, principal: PrincipalId): Promise<ActorSequence>;
+}
+/** The sequence after `last` (1 when nothing was reserved yet); OUT_OF_RANGE after 2^64 - 1. */
+export declare function nextActorSequence(last: ActorSequence | undefined): ActorSequence;
+/**
+ * FOR TESTS AND DEVELOPMENT ONLY. NOT CRASH-SAFE: the state lives in
+ * memory, so a restart starts again at 1 and reuses nonces. Production
+ * writers need a durable ActorSequenceReservation (LFCP-034, LFCP-035).
+ */
+export declare class InMemoryActorSequenceReservation implements ActorSequenceReservation {
+    #private;
+    reserveNext(resource: ResourceId, principal: PrincipalId): Promise<ActorSequence>;
+}
+/**
+ * A local check that no (resource, principal, seq) is used twice, as a
+ * second line of defence where Data Units are created. It remembers what
+ * it has seen in memory only; it does not replace a durable reservation.
+ */
+export declare class SequenceReuseGuard {
+    #private;
+    /** Records the tuple, or throws SEQUENCE_REUSE when it was recorded before. */
+    claim(resource: ResourceId, principal: PrincipalId, seq: ActorSequence): void;
+    /** True when the tuple was claimed before. */
+    has(resource: ResourceId, principal: PrincipalId, seq: ActorSequence): boolean;
+}
+//# sourceMappingURL=sequence.d.ts.map

package/dist/sequence.js

@@ -0,0 +1,55 @@
+import { actorSequence, LfcpError, toHex, UINT64_MAX, } from "@openlfcp/core";
+/** The sequence after `last` (1 when nothing was reserved yet); OUT_OF_RANGE after 2^64 - 1. */
+export function nextActorSequence(last) {
+    if (last === undefined)
+        return actorSequence(1n);
+    if (last >= UINT64_MAX)
+        throw new LfcpError("OUT_OF_RANGE", "the actor sequence space is exhausted; use a new Principal for this Resource (§8)");
+    return actorSequence(last + 1n);
+}
+const tupleKey = (resource, principal) => `${toHex(resource)}:${toHex(principal)}`;
+/**
+ * FOR TESTS AND DEVELOPMENT ONLY. NOT CRASH-SAFE: the state lives in
+ * memory, so a restart starts again at 1 and reuses nonces. Production
+ * writers need a durable ActorSequenceReservation (LFCP-034, LFCP-035).
+ */
+export class InMemoryActorSequenceReservation {
+    #last = new Map();
+    reserveNext(resource, principal) {
+        try {
+            const key = tupleKey(resource, principal);
+            const next = nextActorSequence(this.#last.get(key));
+            this.#last.set(key, next);
+            return Promise.resolve(next);
+        }
+        catch (e) {
+            return Promise.reject(e);
+        }
+    }
+}
+/**
+ * A local check that no (resource, principal, seq) is used twice, as a
+ * second line of defence where Data Units are created. It remembers what
+ * it has seen in memory only; it does not replace a durable reservation.
+ */
+export class SequenceReuseGuard {
+    #seen = new Map();
+    /** Records the tuple, or throws SEQUENCE_REUSE when it was recorded before. */
+    claim(resource, principal, seq) {
+        const s = actorSequence(seq);
+        const key = tupleKey(resource, principal);
+        let used = this.#seen.get(key);
+        if (used === undefined) {
+            used = new Set();
+            this.#seen.set(key, used);
+        }
+        if (used.has(s))
+            throw new LfcpError("SEQUENCE_REUSE", `actor sequence ${s} was already used for this (Resource, Principal) (§8)`);
+        used.add(s);
+    }
+    /** True when the tuple was claimed before. */
+    has(resource, principal, seq) {
+        return this.#seen.get(tupleKey(resource, principal))?.has(seq) ?? false;
+    }
+}
+//# sourceMappingURL=sequence.js.map

package/dist/snapshot-sequence.d.ts

@@ -0,0 +1,39 @@
+import { type DataEpoch, type PrincipalId, type ResourceId } from "@openlfcp/core";
+/**
+ * Snapshot Sequence allocation (LFCP-WIRE-01 §29, §29.1.2). A Snapshot's
+ * nonce is 0x00000000 || uint64_be(snapshot_sequence) under a key that
+ * depends on (Resource, Data Epoch, publisher), so a sequence used twice
+ * for one (resource, data_epoch, publisher) can reuse a nonce. Sequences
+ * start at 1 and never go back.
+ */
+export interface SnapshotSequenceReservation {
+    /**
+     * Reserves the next Snapshot Sequence for `publisher` in `epoch` of
+     * `resource`. Same contract as ActorSequenceReservation: durable before
+     * the promise resolves, never the same value twice for one tuple, across
+     * restarts and concurrent callers; an unused reservation is abandoned,
+     * never returned. OUT_OF_RANGE once 2^64 - 1 was handed out. Durable
+     * implementations belong to LFCP-034 and LFCP-035.
+     */
+    reserveNext(resource: ResourceId, epoch: DataEpoch, publisher: PrincipalId): Promise<bigint>;
+}
+/**
+ * FOR TESTS AND DEVELOPMENT ONLY. NOT CRASH-SAFE: a restart starts again at
+ * 1 and reuses nonces. Production publishers need a durable
+ * SnapshotSequenceReservation (LFCP-034, LFCP-035).
+ */
+export declare class InMemorySnapshotSequenceReservation implements SnapshotSequenceReservation {
+    #private;
+    reserveNext(resource: ResourceId, epoch: DataEpoch, publisher: PrincipalId): Promise<bigint>;
+}
+/**
+ * A local check that no (resource, data_epoch, publisher, sequence) is used
+ * twice, as a second line of defence where Snapshots are created. In memory
+ * only; it does not replace a durable reservation.
+ */
+export declare class SnapshotSequenceGuard {
+    #private;
+    /** Records the tuple, or throws SEQUENCE_REUSE when it was recorded before. */
+    claim(resource: ResourceId, epoch: DataEpoch, publisher: PrincipalId, seq: bigint): void;
+}
+//# sourceMappingURL=snapshot-sequence.d.ts.map

package/dist/snapshot-sequence.js

@@ -0,0 +1,34 @@
+import { dataEpoch, LfcpError, toHex, UINT64_MAX, } from "@openlfcp/core";
+const tupleKey = (resource, epoch, publisher) => `${toHex(resource)}:${dataEpoch(epoch)}:${toHex(publisher)}`;
+/**
+ * FOR TESTS AND DEVELOPMENT ONLY. NOT CRASH-SAFE: a restart starts again at
+ * 1 and reuses nonces. Production publishers need a durable
+ * SnapshotSequenceReservation (LFCP-034, LFCP-035).
+ */
+export class InMemorySnapshotSequenceReservation {
+    #last = new Map();
+    reserveNext(resource, epoch, publisher) {
+        const key = tupleKey(resource, epoch, publisher);
+        const last = this.#last.get(key) ?? 0n;
+        if (last >= UINT64_MAX)
+            return Promise.reject(new LfcpError("OUT_OF_RANGE", "the Snapshot Sequence space is exhausted (§29)"));
+        this.#last.set(key, last + 1n);
+        return Promise.resolve(last + 1n);
+    }
+}
+/**
+ * A local check that no (resource, data_epoch, publisher, sequence) is used
+ * twice, as a second line of defence where Snapshots are created. In memory
+ * only; it does not replace a durable reservation.
+ */
+export class SnapshotSequenceGuard {
+    #seen = new Set();
+    /** Records the tuple, or throws SEQUENCE_REUSE when it was recorded before. */
+    claim(resource, epoch, publisher, seq) {
+        const key = `${tupleKey(resource, epoch, publisher)}:${seq}`;
+        if (this.#seen.has(key))
+            throw new LfcpError("SEQUENCE_REUSE", `Snapshot Sequence ${seq} was already used for this (Resource, epoch, publisher) (§29)`);
+        this.#seen.add(key);
+    }
+}
+//# sourceMappingURL=snapshot-sequence.js.map