@lix-js/sdk 0.4.7 → 0.5.0-preview.1

package/dist/deterministic/random.js

@@ -0,0 +1,225 @@
+import { sql } from "kysely";
+import { executeSync } from "../database/execute-sync.js";
+import { LixKeyValueSchema } from "../key-value/schema.js";
+import { isDeterministicMode } from "./is-deterministic-mode.js";
+import { timestamp } from "./timestamp.js";
+import { updateUntrackedState } from "../state/untracked/update-untracked-state.js";
+const rngCache = new WeakMap();
+/**
+ * Non-deterministic random number generator using crypto.getRandomValues().
+ * Returns a 53-bit precision float in [0, 1).
+ */
+function randomUnstable() {
+    const buf = new Uint32Array(2);
+    if (typeof crypto !== "undefined" && crypto.getRandomValues) {
+        crypto.getRandomValues(buf);
+    }
+    else {
+        // Fallback for environments without crypto API
+        // This is not cryptographically secure but better than failing
+        buf[0] = Math.floor(Math.random() * 0xffffffff);
+        buf[1] = Math.floor(Math.random() * 0xffffffff);
+    }
+    // 53-bit float in [0,1) - standard technique for full precision
+    const high = buf[0] >>> 5; // 27 bits
+    const low = buf[1] >>> 6; // 26 bits
+    // Combine to get 53 bits total, then divide by 2^53
+    return (high * 0x4000000 + low) / Math.pow(2, 53);
+}
+/**
+ * Returns a random float between 0 (inclusive) and 1 (exclusive).
+ *
+ * In deterministic mode, generates reproducible values using xorshift128+ PRNG
+ * (the same algorithm used by V8/Chrome for Math.random()).
+ * In normal mode, uses crypto.getRandomValues() for cryptographically secure randomness.
+ *
+ * - Normal mode: Uses crypto.getRandomValues() for cryptographic quality
+ * - Deterministic mode: Uses xorshift128+ PRNG (same as V8/Chrome's Math.random())
+ * - Default seed: Uses `lix_id` value unless `lix_deterministic_rng_seed` is set
+ * - State persisted via `lix_deterministic_rng_state` key value
+ * - Both modes return 53-bit precision floats for consistency
+ * - For ID generation, consider {@link uuidV7} or {@link nanoId} instead
+ *
+ * @example Normal mode - cryptographically secure randomness
+ * ```ts
+ * const lix = await openLix();
+ * const r1 = random({ lix }); // 0.823... (unpredictable)
+ * const r2 = random({ lix }); // 0.156... (unpredictable)
+ * ```
+ *
+ * @example Deterministic mode - reproducible randomness
+ * ```ts
+ * const lix = await openLix({
+ *   keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }]
+ * });
+ * const r1 = random({ lix }); // 0.318... (always same sequence)
+ * const r2 = random({ lix }); // 0.937... (for same seed)
+ * const r3 = random({ lix }); // 0.543...
+ * ```
+ *
+ * @example Sampling and shuffling
+ * ```ts
+ * // Random selection
+ * const items = ["a", "b", "c", "d"];
+ * const idx = Math.floor(random({ lix }) * items.length);
+ * const selected = items[idx];
+ *
+ * // Fisher-Yates shuffle
+ * function shuffle<T>(array: T[], lix: Lix): T[] {
+ *   const result = [...array];
+ *   for (let i = result.length - 1; i > 0; i--) {
+ *     const j = Math.floor(random({ lix }) * (i + 1));
+ *     [result[i], result[j]] = [result[j], result[i]];
+ *   }
+ *   return result;
+ * }
+ * ```
+ *
+ * @param args.lix - The Lix instance with sqlite and db connections
+ * @returns Random float between 0 (inclusive) and 1 (exclusive) with 53-bit precision
+ */
+export function random(args) {
+    // Non-deterministic mode: use crypto.getRandomValues()
+    if (!isDeterministicMode({ lix: args.lix })) {
+        return randomUnstable();
+    }
+    // Deterministic mode: use xorshift128+
+    let state = rngCache.get(args.lix.sqlite);
+    /* First use on this connection → initialize from seed */
+    if (!state) {
+        // Check if we have persisted RNG state
+        const [stateRow] = executeSync({
+            lix: { sqlite: args.lix.sqlite },
+            query: args.lix.db
+                .selectFrom("key_value_all")
+                .where("key", "=", "lix_deterministic_rng_state")
+                .where("lixcol_version_id", "=", "global")
+                .select("value"),
+        });
+        if (stateRow && stateRow.value) {
+            // Restore persisted state
+            // The value is stored as a JSON string in key_value_all view
+            const stateData = typeof stateRow.value === "string"
+                ? JSON.parse(stateRow.value)
+                : stateRow.value;
+            // Handle both string and direct values
+            state = {
+                hi: BigInt(stateData.hi),
+                lo: BigInt(stateData.lo),
+                dirty: false,
+            };
+        }
+        else {
+            // Initialize from seed
+            const seed = getRngSeed(args);
+            state = seedXorshift128Plus(seed);
+        }
+        rngCache.set(args.lix.sqlite, state);
+    }
+    // Generate next random value using xorshift128+
+    const result = nextXorshift128Plus(state);
+    state.dirty = true;
+    return result;
+}
+/**
+ * Get the RNG seed - either from deterministic mode config or derive from lix_id
+ */
+function getRngSeed(args) {
+    // Check for seed in the deterministic mode config
+    const [configRow] = executeSync({
+        lix: { sqlite: args.lix.sqlite },
+        query: args.lix.db
+            .selectFrom("internal_resolved_state_all")
+            .where("entity_id", "=", "lix_deterministic_mode")
+            .where("schema_key", "=", "lix_key_value")
+            .select(sql `json_extract(snapshot_content, '$.value.random_seed')`.as("random_seed")),
+    });
+    if (configRow && configRow.random_seed) {
+        return configRow.random_seed;
+    }
+    // Derive default seed from lix_id
+    const [idRow] = executeSync({
+        lix: { sqlite: args.lix.sqlite },
+        query: args.lix.db
+            .selectFrom("key_value")
+            .where("key", "=", "lix_id")
+            .select("value"),
+    });
+    if (!idRow || !idRow.value) {
+        throw new Error("Could not find lix_id for RNG seed");
+    }
+    // Use lix_id as the seed - no need to insert it
+    return idRow.value;
+}
+/**
+ * Initialize state from a 64-bit hash of the seed string (SplitMix64-style)
+ */
+function seedXorshift128Plus(seed) {
+    // FNV-1a hash to get initial value
+    let z = 0xcbf29ce484222325n;
+    for (const ch of seed) {
+        z = ((z ^ BigInt(ch.charCodeAt(0))) * 0x100000001b3n) & 0xffffffffffffffffn;
+    }
+    // SplitMix64 to expand into two non-zero words
+    const next = () => {
+        z = (z + 0x9e3779b97f4a7c15n) & 0xffffffffffffffffn;
+        let t = z;
+        t = ((t ^ (t >> 30n)) * 0xbf58476d1ce4e5b9n) & 0xffffffffffffffffn;
+        t = ((t ^ (t >> 27n)) * 0x94d049bb133111ebn) & 0xffffffffffffffffn;
+        return t ^ (t >> 31n);
+    };
+    return {
+        hi: next() || 1n,
+        lo: next() || 2n,
+        dirty: true, // New seed always needs to be persisted
+    };
+}
+/**
+ * One xorshift128+ step → returns 53-bit float in [0,1)
+ * This is the same algorithm used by V8/Chrome for Math.random()
+ */
+function nextXorshift128Plus(state) {
+    let s1 = state.lo;
+    const s0 = state.hi;
+    state.lo = s0;
+    s1 ^= (s1 << 23n) & 0xffffffffffffffffn;
+    state.hi = (s1 ^ s0 ^ (s1 >> 17n) ^ (s0 >> 26n)) & 0xffffffffffffffffn;
+    const sum = (state.hi + state.lo) & 0xffffffffffffffffn;
+    // 53 high bits → IEEE-754 double in [0,1)
+    return Number(sum >> 11n) / Math.pow(2, 53);
+}
+/**
+ * @internal
+ * Flush the in-memory RNG state to persistent storage.
+ *
+ * Called automatically by Lix after each committing write and during
+ * `lix.toBlob()` / `lix.close()`. **Not part of the public API.**
+ */
+export function commitDeterministicRngState(args) {
+    const state = rngCache.get(args.lix.sqlite);
+    if (!state || !state.dirty)
+        return; // nothing to do
+    state.dirty = false; // mark clean _before_ we try to write
+    const newValue = JSON.stringify({
+        key: "lix_deterministic_rng_state",
+        value: {
+            hi: state.hi.toString(),
+            lo: state.lo.toString(),
+        },
+    });
+    const now = args.timestamp ?? timestamp({ lix: args.lix });
+    updateUntrackedState({
+        lix: args.lix,
+        change: {
+            entity_id: "lix_deterministic_rng_state",
+            schema_key: LixKeyValueSchema["x-lix-key"],
+            file_id: "lix",
+            plugin_key: "lix_own_entity",
+            snapshot_content: newValue,
+            schema_version: LixKeyValueSchema["x-lix-version"],
+            created_at: now,
+        },
+        version_id: "global",
+    });
+}
+//# sourceMappingURL=random.js.map

package/dist/deterministic/random.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"random.js","sourceRoot":"","sources":["../../src/deterministic/random.ts"],"names":[],"mappings":"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"}

package/dist/deterministic/random.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=random.test.d.ts.map

package/dist/deterministic/random.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"random.test.d.ts","sourceRoot":"","sources":["../../src/deterministic/random.test.ts"],"names":[],"mappings":""}

package/dist/deterministic/random.test.js

@@ -0,0 +1,244 @@
+import { expect, test } from "vitest";
+import { openLix } from "../lix/open-lix.js";
+import { random } from "./random.js";
+test("random works in non-deterministic mode", async () => {
+    const lix = await openLix({
+        keyValues: [{ key: "lix_deterministic_mode", value: { enabled: false } }],
+    });
+    const values = new Set();
+    for (let i = 0; i < 1000; i++) {
+        const r = random({ lix });
+        expect(r).toBeGreaterThanOrEqual(0);
+        expect(r).toBeLessThan(1);
+        values.add(r);
+    }
+    // With a good RNG generating 1000 floats, the probability of getting
+    // more than 50 duplicates is astronomically small (birthday paradox).
+    // This threshold prevents flaky tests while still catching bad RNGs.
+    expect(values.size).toBeGreaterThan(950);
+});
+test("random works in deterministic mode", async () => {
+    const lix = await openLix({
+        keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+    });
+    const sequence1 = [];
+    for (let i = 0; i < 10; i++) {
+        const r = random({ lix });
+        expect(r).toBeGreaterThanOrEqual(0);
+        expect(r).toBeLessThan(1);
+        sequence1.push(r);
+    }
+    // All 10 values should be unique - deterministic doesn't mean constant
+    const uniqueValues = new Set(sequence1);
+    expect(uniqueValues.size).toBe(10);
+    const blob = await lix.toBlob();
+    const lix2 = await openLix({ blob });
+    const sequence2 = [];
+    for (let i = 0; i < 10; i++) {
+        sequence2.push(random({ lix: lix2 }));
+    }
+    // After blob restore, sequence should continue from where it left off,
+    // not restart from the beginning
+    expect(sequence2).not.toEqual(sequence1);
+    expect(sequence2[0]).not.toBe(sequence1[0]);
+});
+test("deterministic mode produces same sequence with same seed", async () => {
+    const lix1 = await openLix({
+        keyValues: [
+            {
+                key: "lix_deterministic_mode",
+                value: {
+                    enabled: true,
+                    random_seed: "test-seed",
+                },
+            },
+        ],
+    });
+    const sequence1 = [];
+    for (let i = 0; i < 5; i++) {
+        sequence1.push(random({ lix: lix1 }));
+    }
+    // Test state persistence - continue generating after blob save/restore
+    const blob = await lix1.toBlob();
+    const lix1b = await openLix({ blob });
+    for (let i = 0; i < 5; i++) {
+        sequence1.push(random({ lix: lix1b }));
+    }
+    const lix2 = await openLix({
+        keyValues: [
+            {
+                key: "lix_deterministic_mode",
+                value: {
+                    enabled: true,
+                    random_seed: "test-seed",
+                },
+            },
+        ],
+    });
+    const sequence2 = [];
+    for (let i = 0; i < 10; i++) {
+        sequence2.push(random({ lix: lix2 }));
+    }
+    // Same seed should produce identical 10-number sequence,
+    // including numbers generated after blob persistence
+    expect(sequence1).toEqual(sequence2);
+});
+test("deterministic mode produces different sequences with different seeds", async () => {
+    const lix1 = await openLix({
+        keyValues: [
+            {
+                key: "lix_deterministic_mode",
+                value: {
+                    enabled: true,
+                    random_seed: "seed-1",
+                },
+            },
+        ],
+    });
+    const sequence1 = [];
+    for (let i = 0; i < 100; i++) {
+        sequence1.push(random({ lix: lix1 }));
+    }
+    const lix2 = await openLix({
+        keyValues: [
+            {
+                key: "lix_deterministic_mode",
+                value: {
+                    enabled: true,
+                    random_seed: "seed-2",
+                },
+            },
+        ],
+    });
+    const sequence2 = [];
+    for (let i = 0; i < 100; i++) {
+        sequence2.push(random({ lix: lix2 }));
+    }
+    // Different seeds should produce completely different sequences.
+    // With 100 samples each, any overlap would indicate poor seeding.
+    const overlap = sequence1.some((x) => sequence2.includes(x));
+    expect(overlap).toBe(false);
+});
+test("random state persists across blob operations", async () => {
+    const lix1 = await openLix({
+        keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+    });
+    const fullSequence = [];
+    for (let i = 0; i < 6; i++) {
+        fullSequence.push(random({ lix: lix1 }));
+    }
+    const lix2 = await openLix({
+        keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+    });
+    const beforeBlob = [];
+    for (let i = 0; i < 3; i++) {
+        beforeBlob.push(random({ lix: lix2 }));
+    }
+    const blob = await lix2.toBlob();
+    const lix3 = await openLix({ blob });
+    const afterBlob = [];
+    for (let i = 0; i < 3; i++) {
+        afterBlob.push(random({ lix: lix3 }));
+    }
+    // The state should persist through blob serialization.
+    // The two instances should produce the exact same sequence
+    // as if it was one continuous instance.
+    expect(beforeBlob).toEqual(fullSequence.slice(0, 3));
+    expect(afterBlob).toEqual(fullSequence.slice(3, 6));
+});
+test("random uses lix_id as default seed when no seed specified", async () => {
+    // Create two instances with randomLixId: true to get different lix_ids
+    const lix1 = await openLix({
+        keyValues: [
+            {
+                key: "lix_deterministic_mode",
+                value: { enabled: true, randomLixId: true },
+            },
+        ],
+    });
+    const lix2 = await openLix({
+        keyValues: [
+            {
+                key: "lix_deterministic_mode",
+                value: { enabled: true, randomLixId: true },
+            },
+        ],
+    });
+    const sequence1 = [];
+    const sequence2 = [];
+    // Generate values from each instance
+    for (let i = 0; i < 10; i++) {
+        sequence1.push(random({ lix: lix1 }));
+        sequence2.push(random({ lix: lix2 }));
+    }
+    // With randomLixId: true, each instance gets a different lix_id,
+    // so they will produce different sequences when using lix_id as default seed
+    expect(sequence1).not.toEqual(sequence2);
+    // But each sequence should be deterministic (verified by other tests)
+});
+test("random produces same sequence with deterministic mode", async () => {
+    // Create two instances with deterministic mode enabled
+    const lix1 = await openLix({
+        keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+    });
+    const lix2 = await openLix({
+        keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }],
+    });
+    const sequence1 = [];
+    const sequence2 = [];
+    // Generate values from each instance
+    for (let i = 0; i < 10; i++) {
+        sequence1.push(random({ lix: lix1 }));
+        sequence2.push(random({ lix: lix2 }));
+    }
+    // With deterministic mode, both instances get the same lix_id (deterministic-lix-id),
+    // so they will produce the same sequence when using lix_id as default seed
+    expect(sequence1).toEqual(sequence2);
+});
+test("random works after enabling deterministic mode", async () => {
+    const lix = await openLix({});
+    // Use random in non-deterministic mode first
+    const nonDeterministicValue = random({ lix });
+    expect(nonDeterministicValue).toBeGreaterThanOrEqual(0);
+    expect(nonDeterministicValue).toBeLessThan(1);
+    // Enable deterministic mode
+    await lix.db
+        .insertInto("key_value")
+        .values({ key: "lix_deterministic_mode", value: { enabled: true } })
+        .execute();
+    // Generate deterministic values
+    const sequence1 = [];
+    for (let i = 0; i < 5; i++) {
+        sequence1.push(random({ lix }));
+    }
+    // Save state and reload
+    const blob = await lix.toBlob();
+    const lix2 = await openLix({ blob });
+    // Continue generating values
+    const sequence2 = [];
+    for (let i = 0; i < 5; i++) {
+        sequence2.push(random({ lix: lix2 }));
+    }
+    // Values should continue from where they left off (deterministic state persisted)
+    expect(sequence2[0]).not.toBe(sequence1[0]);
+    // All values should be valid random numbers
+    const allValues = [...sequence1, ...sequence2];
+    for (const val of allValues) {
+        expect(val).toBeGreaterThanOrEqual(0);
+        expect(val).toBeLessThan(1);
+    }
+});
+test("non-deterministic mode without key specified", async () => {
+    const lix = await openLix({});
+    const values = new Set();
+    for (let i = 0; i < 100; i++) {
+        const r = random({ lix });
+        expect(r).toBeGreaterThanOrEqual(0);
+        expect(r).toBeLessThan(1);
+        values.add(r);
+    }
+    // Even with only 100 samples, we expect high uniqueness
+    // This also verifies that omitting the key defaults to non-deterministic
+    expect(values.size).toBeGreaterThan(80);
+});
+//# sourceMappingURL=random.test.js.map

package/dist/deterministic/random.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"random.test.js","sourceRoot":"","sources":["../../src/deterministic/random.test.ts"],"names":[],"mappings":"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"}

package/dist/deterministic/sequence.d.ts

@@ -0,0 +1,56 @@
+import type { Lix } from "../lix/open-lix.js";
+/**
+ * Returns the next monotonic sequence number, starting at 0.
+ *
+ * Only available in deterministic mode. Provides a simple counter for cases where
+ * you need sequential integers rather than timestamps or random values.
+ *
+ * - Requires `lix_deterministic_mode = true`
+ * - Increments by exactly 1 per call (no gaps or duplicates)
+ * - State persisted via `lix_deterministic_sequence_number` key value
+ * - Clones continue from where the sequence left off
+ * - Consider using {@link timestamp}, {@link uuidV7}, or {@link nanoId} for most ID generation needs
+ *
+ * @example Basic usage (deterministic mode required)
+ * ```ts
+ * const lix = await openLix({
+ *   keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }]
+ * });
+ * const n1 = nextDeterministicSequenceNumber({ lix }); // 0
+ * const n2 = nextDeterministicSequenceNumber({ lix }); // 1
+ * const n3 = nextDeterministicSequenceNumber({ lix }); // 2
+ * ```
+ *
+ * @example Collision-free IDs
+ * ```ts
+ * const n = nextDeterministicSequenceNumber({ lix }); // e.g. 7
+ * const id = `ENTITY_${n}`;              // "ENTITY_7"
+ * ```
+ *
+ * @example Pagination cursors
+ * ```ts
+ * const cursor = nextDeterministicSequenceNumber({ lix });
+ * await lix.db.insertInto("page_view")
+ *   .values({ cursor, page_id: "home" })
+ *   .execute();
+ * ```
+ *
+ * @param args.lix - The Lix instance with sqlite and db connections
+ * @returns The next number in the sequence (starting from 0)
+ * @throws {Error} If `lix_deterministic_mode` is not enabled
+ */
+export declare function nextDeterministicSequenceNumber(args: {
+    lix: Pick<Lix, "sqlite" | "db">;
+}): number;
+/**
+ * @internal
+ * Flush the in-memory deterministic counter to persistent storage.
+ *
+ * Called automatically by Lix after each committing write and during
+ * `lix.toBlob()` / `lix.close()`.  **Not part of the public API.**
+ */
+export declare function commitDeterministicSequenceNumber(args: {
+    lix: Pick<Lix, "sqlite" | "db">;
+    timestamp?: string;
+}): void;
+//# sourceMappingURL=sequence.d.ts.map

package/dist/deterministic/sequence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequence.d.ts","sourceRoot":"","sources":["../../src/deterministic/sequence.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,oBAAoB,CAAC;AAc9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,+BAA+B,CAAC,IAAI,EAAE;IACrD,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC,CAAC;CAChC,GAAG,MAAM,CAmCT;AAED;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAAC,IAAI,EAAE;IACvD,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,GAAG,IAAI,CAAC,CAAC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,IAAI,CAyBP"}

package/dist/deterministic/sequence.js

@@ -0,0 +1,107 @@
+import { executeSync } from "../database/execute-sync.js";
+import { LixKeyValueSchema } from "../key-value/schema.js";
+import { isDeterministicMode } from "./is-deterministic-mode.js";
+import { timestamp } from "./timestamp.js";
+import { updateUntrackedState } from "../state/untracked/update-untracked-state.js";
+const counterCache = new WeakMap();
+/**
+ * Returns the next monotonic sequence number, starting at 0.
+ *
+ * Only available in deterministic mode. Provides a simple counter for cases where
+ * you need sequential integers rather than timestamps or random values.
+ *
+ * - Requires `lix_deterministic_mode = true`
+ * - Increments by exactly 1 per call (no gaps or duplicates)
+ * - State persisted via `lix_deterministic_sequence_number` key value
+ * - Clones continue from where the sequence left off
+ * - Consider using {@link timestamp}, {@link uuidV7}, or {@link nanoId} for most ID generation needs
+ *
+ * @example Basic usage (deterministic mode required)
+ * ```ts
+ * const lix = await openLix({
+ *   keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }]
+ * });
+ * const n1 = nextDeterministicSequenceNumber({ lix }); // 0
+ * const n2 = nextDeterministicSequenceNumber({ lix }); // 1
+ * const n3 = nextDeterministicSequenceNumber({ lix }); // 2
+ * ```
+ *
+ * @example Collision-free IDs
+ * ```ts
+ * const n = nextDeterministicSequenceNumber({ lix }); // e.g. 7
+ * const id = `ENTITY_${n}`;              // "ENTITY_7"
+ * ```
+ *
+ * @example Pagination cursors
+ * ```ts
+ * const cursor = nextDeterministicSequenceNumber({ lix });
+ * await lix.db.insertInto("page_view")
+ *   .values({ cursor, page_id: "home" })
+ *   .execute();
+ * ```
+ *
+ * @param args.lix - The Lix instance with sqlite and db connections
+ * @returns The next number in the sequence (starting from 0)
+ * @throws {Error} If `lix_deterministic_mode` is not enabled
+ */
+export function nextDeterministicSequenceNumber(args) {
+    // Check if deterministic mode is enabled
+    if (!isDeterministicMode({ lix: args.lix })) {
+        throw new Error("nextDeterministicSequenceNumber() is available only when lix_deterministic_mode = true");
+    }
+    let state = counterCache.get(args.lix.sqlite);
+    /* First use on this connection → pull initial value from DB */
+    if (!state) {
+        const [row] = executeSync({
+            lix: { sqlite: args.lix.sqlite },
+            // querying from key_value_all is fine here because its a view
+            // that hits the internal_state_all_untracked table
+            query: args.lix.db
+                .selectFrom("key_value_all")
+                .where("key", "=", "lix_deterministic_sequence_number")
+                .where("lixcol_version_id", "=", "global")
+                .select("value"),
+        });
+        // The persisted value is the next counter to use
+        const start = row ? Number(row.value) + 1 : 0;
+        state = { next: start, highestSeen: start - 1, dirty: false };
+        counterCache.set(args.lix.sqlite, state);
+    }
+    /* Hand out current, then bump for the next call */
+    const count = state.next++;
+    state.highestSeen = count;
+    state.dirty = true;
+    return count;
+}
+/**
+ * @internal
+ * Flush the in-memory deterministic counter to persistent storage.
+ *
+ * Called automatically by Lix after each committing write and during
+ * `lix.toBlob()` / `lix.close()`.  **Not part of the public API.**
+ */
+export function commitDeterministicSequenceNumber(args) {
+    const state = counterCache.get(args.lix.sqlite);
+    if (!state || !state.dirty)
+        return; // nothing to do
+    state.dirty = false; // mark clean _before_ we try to write
+    const newValue = JSON.stringify({
+        key: "lix_deterministic_sequence_number",
+        value: state.highestSeen,
+    });
+    const now = args.timestamp ?? timestamp({ lix: args.lix });
+    updateUntrackedState({
+        lix: args.lix,
+        change: {
+            entity_id: "lix_deterministic_sequence_number",
+            schema_key: LixKeyValueSchema["x-lix-key"],
+            file_id: "lix",
+            plugin_key: "lix_own_entity",
+            snapshot_content: newValue,
+            schema_version: LixKeyValueSchema["x-lix-version"],
+            created_at: now,
+        },
+        version_id: "global",
+    });
+}
+//# sourceMappingURL=sequence.js.map