@lix-js/sdk 0.5.0-preview.0 → 0.5.0

package/dist/engine/functions/random.js

@@ -0,0 +1,214 @@
+import { sql } from "kysely";
+import { LixKeyValueSchema, } from "../../key-value/schema-definition.js";
+import { isDeterministicModeSync } from "../deterministic-mode/is-deterministic-mode.js";
+import { getTimestampSync } from "./timestamp.js";
+import { updateUntrackedState } from "../../state/untracked/update-untracked-state.js";
+import { internalQueryBuilder } from "../internal-query-builder.js";
+import { withRuntimeCache } from "../with-runtime-cache.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);
+}
+/**
+ * Sync variant of {@link random}. See {@link random} for behavior and examples.
+ *
+ * @remarks
+ * - Accepts `{ engine }` (or `{ lix }`) and runs next to SQLite.
+ * - Intended for engine/router and UDFs; app code should use {@link random}.
+ *
+ * @see random
+ */
+export function randomSync(args) {
+    const engine = args.engine;
+    // Non-deterministic mode: use crypto.getRandomValues()
+    if (!isDeterministicModeSync({ engine })) {
+        return randomUnstable();
+    }
+    // Deterministic mode: use xorshift128+
+    let state = rngCache.get(engine.runtimeCacheRef);
+    /* First use on this connection → initialize from seed */
+    if (!state) {
+        // Check if we have persisted RNG state
+        const [stateRow] = engine.executeSync(internalQueryBuilder
+            .selectFrom("key_value_by_version")
+            .where("key", "=", "lix_deterministic_rng_state")
+            .where("lixcol_version_id", "=", "global")
+            .select("value")
+            .compile()).rows;
+        if (stateRow && stateRow.value) {
+            // Restore persisted state
+            // The value is stored as a JSON string in key_value_by_version 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({ engine });
+            state = seedXorshift128Plus(seed);
+        }
+        rngCache.set(engine.runtimeCacheRef, 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] = withRuntimeCache(args.engine, internalQueryBuilder
+        .selectFrom("lix_internal_state_vtable")
+        .where("entity_id", "=", "lix_deterministic_mode")
+        .where("schema_key", "=", "lix_key_value")
+        .where("snapshot_content", "is not", null)
+        .select(sql `json_extract(snapshot_content, '$.value.random_seed')`.as("random_seed"))
+        .compile()).rows;
+    if (configRow && configRow.random_seed) {
+        return configRow.random_seed;
+    }
+    // Derive default seed from lix_id
+    const [idRow] = withRuntimeCache(args.engine, internalQueryBuilder
+        .selectFrom("key_value")
+        .where("key", "=", "lix_id")
+        .select("value")
+        .compile()).rows;
+    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 engine = args.engine;
+    const state = rngCache.get(engine.runtimeCacheRef);
+    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 ?? getTimestampSync({ engine });
+    updateUntrackedState({
+        engine: engine,
+        changes: [
+            {
+                entity_id: "lix_deterministic_rng_state",
+                schema_key: LixKeyValueSchema["x-lix-key"],
+                file_id: "lix",
+                plugin_key: "lix_sdk",
+                snapshot_content: newValue,
+                schema_version: LixKeyValueSchema["x-lix-version"],
+                created_at: now,
+                lixcol_version_id: "global",
+            },
+        ],
+    });
+}
+/**
+ * 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().
+ *
+ * - Normal mode: cryptographic quality via crypto.getRandomValues().
+ * - Deterministic mode: xorshift128+ PRNG (same as V8/Chrome's Math.random()).
+ * - Default seed: `lix_id` unless `lix_deterministic_rng_seed` is set.
+ * - State persisted via `lix_deterministic_rng_state`.
+ * - Returns 53-bit precision floats in both modes.
+ * - For ID generation, consider {@link uuidV7} or {@link nanoId} instead.
+ *
+ * @example Normal mode – cryptographically secure randomness
+ * ```ts
+ * const lix = await openLix();
+ * const r1 = await random({ lix }) // 0.823...
+ * const r2 = await random({ lix }) // 0.156...
+ * ```
+ *
+ * @example Deterministic mode – reproducible randomness
+ * ```ts
+ * const lix = await openLix({ keyValues: [{ key: "lix_deterministic_mode", value: { enabled: true } }] });
+ * await random({ lix }) // 0.318...
+ * await random({ lix }) // 0.937...
+ * await random({ lix }) // 0.543...
+ * ```
+ */
+export async function random(args) {
+    const res = await args.lix.call("lix_random");
+    return Number(res);
+}
+//# sourceMappingURL=random.js.map

package/dist/engine/functions/random.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"random.js","sourceRoot":"","sources":["../../../src/engine/functions/random.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAC7B,OAAO,EACN,iBAAiB,GAEjB,MAAM,sCAAsC,CAAC;AAG9C,OAAO,EAAE,uBAAuB,EAAE,MAAM,gDAAgD,CAAC;AACzF,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,oBAAoB,EAAE,MAAM,iDAAiD,CAAC;AACvF,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAS5D,MAAM,QAAQ,GAAG,IAAI,OAAO,EAAoB,CAAC;AAEjD;;;GAGG;AACH,SAAS,cAAc;IACtB,MAAM,GAAG,GAAG,IAAI,WAAW,CAAC,CAAC,CAAC,CAAC;IAC/B,IAAI,OAAO,MAAM,KAAK,WAAW,IAAI,MAAM,CAAC,eAAe,EAAE,CAAC;QAC7D,MAAM,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;SAAM,CAAC;QACP,+CAA+C;QAC/C,+DAA+D;QAC/D,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,UAAU,CAAC,CAAC;QAChD,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,UAAU,CAAC,CAAC;IACjD,CAAC;IACD,gEAAgE;IAChE,MAAM,IAAI,GAAG,GAAG,CAAC,CAAC,CAAE,KAAK,CAAC,CAAC,CAAC,UAAU;IACtC,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,CAAE,KAAK,CAAC,CAAC,CAAC,UAAU;IACrC,oDAAoD;IACpD,OAAO,CAAC,IAAI,GAAG,SAAS,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,IAE1B;IACA,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC3B,uDAAuD;IACvD,IAAI,CAAC,uBAAuB,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC;QAC1C,OAAO,cAAc,EAAE,CAAC;IACzB,CAAC;IAED,uCAAuC;IACvC,IAAI,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;IAEjD,yDAAyD;IACzD,IAAI,CAAC,KAAK,EAAE,CAAC;QACZ,uCAAuC;QACvC,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,CAAC,WAAW,CACpC,oBAAoB;aAClB,UAAU,CAAC,sBAAsB,CAAC;aAClC,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,6BAA6B,CAAC;aAChD,KAAK,CAAC,mBAAmB,EAAE,GAAG,EAAE,QAAQ,CAAC;aACzC,MAAM,CAAC,OAAO,CAAC;aACf,OAAO,EAAE,CACX,CAAC,IAAI,CAAC;QAEP,IAAI,QAAQ,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;YAChC,0BAA0B;YAC1B,oEAAoE;YACpE,MAAM,SAAS,GACd,OAAO,QAAQ,CAAC,KAAK,KAAK,QAAQ;gBACjC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC;gBAC5B,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC;YAEnB,uCAAuC;YACvC,KAAK,GAAG;gBACP,EAAE,EAAE,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;gBACxB,EAAE,EAAE,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;gBACxB,KAAK,EAAE,KAAK;aACZ,CAAC;QACH,CAAC;aAAM,CAAC;YACP,uBAAuB;YACvB,MAAM,IAAI,GAAG,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;YACpC,KAAK,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;QACnC,CAAC;QAED,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;IAC7C,CAAC;IAED,gDAAgD;IAChD,MAAM,MAAM,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;IAC1C,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;IACnB,OAAO,MAAM,CAAC;AACf,CAAC;AAED;;GAEG;AACH,SAAS,UAAU,CAAC,IAEnB;IACA,kDAAkD;IAClD,MAAM,CAAC,SAAS,CAAC,GAAG,gBAAgB,CACnC,IAAI,CAAC,MAAM,EACX,oBAAoB;SAClB,UAAU,CAAC,2BAA2B,CAAC;SACvC,KAAK,CAAC,WAAW,EAAE,GAAG,EAAE,wBAAwB,CAAC;SACjD,KAAK,CAAC,YAAY,EAAE,GAAG,EAAE,eAAe,CAAC;SACzC,KAAK,CAAC,kBAAkB,EAAE,QAAQ,EAAE,IAAI,CAAC;SACzC,MAAM,CACN,GAAG,CAAA,uDAAuD,CAAC,EAAE,CAC5D,aAAa,CACb,CACD;SACA,OAAO,EAAE,CACX,CAAC,IAAI,CAAC;IAEP,IAAI,SAAS,IAAI,SAAS,CAAC,WAAW,EAAE,CAAC;QACxC,OAAO,SAAS,CAAC,WAAqB,CAAC;IACxC,CAAC;IAED,kCAAkC;IAClC,MAAM,CAAC,KAAK,CAAC,GAAG,gBAAgB,CAC/B,IAAI,CAAC,MAAM,EACX,oBAAoB;SAClB,UAAU,CAAC,WAAW,CAAC;SACvB,KAAK,CAAC,KAAK,EAAE,GAAG,EAAE,QAAQ,CAAC;SAC3B,MAAM,CAAC,OAAO,CAAC;SACf,OAAO,EAAE,CACX,CAAC,IAAI,CAAC;IAEP,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACvD,CAAC;IAED,gDAAgD;IAChD,OAAO,KAAK,CAAC,KAAe,CAAC;AAC9B,CAAC;AAED;;GAEG;AACH,SAAS,mBAAmB,CAAC,IAAY;IACxC,mCAAmC;IACnC,IAAI,CAAC,GAAG,mBAAmB,CAAC;IAC5B,KAAK,MAAM,EAAE,IAAI,IAAI,EAAE,CAAC;QACvB,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,GAAG,mBAAmB,CAAC;IAC7E,CAAC;IAED,+CAA+C;IAC/C,MAAM,IAAI,GAAG,GAAW,EAAE;QACzB,CAAC,GAAG,CAAC,CAAC,GAAG,mBAAmB,CAAC,GAAG,mBAAmB,CAAC;QACpD,IAAI,CAAC,GAAG,CAAC,CAAC;QACV,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,mBAAmB,CAAC,GAAG,mBAAmB,CAAC;QACnE,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,mBAAmB,CAAC,GAAG,mBAAmB,CAAC;QACnE,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;IACvB,CAAC,CAAC;IAEF,OAAO;QACN,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE;QAChB,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE;QAChB,KAAK,EAAE,IAAI,EAAE,wCAAwC;KACrD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,mBAAmB,CAAC,KAAe;IAC3C,IAAI,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC;IAClB,MAAM,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,GAAG,EAAE,CAAC;IACd,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,CAAC,GAAG,mBAAmB,CAAC;IACxC,KAAK,CAAC,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,GAAG,CAAC,EAAE,IAAI,GAAG,CAAC,CAAC,GAAG,mBAAmB,CAAC;IACvE,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,KAAK,CAAC,EAAE,CAAC,GAAG,mBAAmB,CAAC;IACxD,0CAA0C;IAC1C,OAAO,MAAM,CAAC,GAAG,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,2BAA2B,CAAC,IAG3C;IACA,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IAC3B,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;IACnD,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,KAAK;QAAE,OAAO,CAAC,gBAAgB;IAEpD,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,sCAAsC;IAE3D,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC;QAC/B,GAAG,EAAE,6BAA6B;QAClC,KAAK,EAAE;YACN,EAAE,EAAE,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE;YACvB,EAAE,EAAE,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE;SACvB;KACqB,CAAC,CAAC;IAEzB,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,IAAI,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3D,oBAAoB,CAAC;QACpB,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACR;gBACC,SAAS,EAAE,6BAA6B;gBACxC,UAAU,EAAE,iBAAiB,CAAC,WAAW,CAAC;gBAC1C,OAAO,EAAE,KAAK;gBACd,UAAU,EAAE,SAAS;gBACrB,gBAAgB,EAAE,QAAQ;gBAC1B,cAAc,EAAE,iBAAiB,CAAC,eAAe,CAAC;gBAClD,UAAU,EAAE,GAAG;gBACf,iBAAiB,EAAE,QAAQ;aAC3B;SACD;KACD,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAE5B;IACA,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAC9C,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACpB,CAAC"}

package/dist/engine/functions/random.test.d.ts

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

package/dist/engine/functions/random.test.d.ts.map

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

package/dist/engine/functions/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 = await 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 = await 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(await 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(await 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(await 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(await 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(await 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(await 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(await 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(await random({ lix: lix2 }));
+    }
+    const blob = await lix2.toBlob();
+    const lix3 = await openLix({ blob });
+    const afterBlob = [];
+    for (let i = 0; i < 3; i++) {
+        afterBlob.push(await 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(await random({ lix: lix1 }));
+        sequence2.push(await 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(await random({ lix: lix1 }));
+        sequence2.push(await 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 = await 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(await 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(await 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 = await 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/engine/functions/random.test.js.map

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

package/dist/engine/functions/register-builtins.d.ts

@@ -0,0 +1,9 @@
+import type { RegisteredFunctionDefinition } from "./function-registry.js";
+import type { LixEngine } from "../boot.js";
+type RegisterBuiltinArgs = {
+    register: (def: RegisteredFunctionDefinition) => void;
+    engine: Pick<LixEngine, "sqlite" | "hooks" | "executeSync" | "runtimeCacheRef" | "call" | "preprocessQuery">;
+};
+export declare function registerBuiltinFunctions({ register, engine, }: RegisterBuiltinArgs): void;
+export {};
+//# sourceMappingURL=register-builtins.d.ts.map

package/dist/engine/functions/register-builtins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-builtins.d.ts","sourceRoot":"","sources":["../../../src/engine/functions/register-builtins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,wBAAwB,CAAC;AAgB3E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,KAAK,mBAAmB,GAAG;IAC1B,QAAQ,EAAE,CAAC,GAAG,EAAE,4BAA4B,KAAK,IAAI,CAAC;IACtD,MAAM,EAAE,IAAI,CACX,SAAS,EACP,QAAQ,GACR,OAAO,GACP,aAAa,GACb,iBAAiB,GACjB,MAAM,GACN,iBAAiB,CACnB,CAAC;CACF,CAAC;AAEF,wBAAgB,wBAAwB,CAAC,EACxC,QAAQ,EACR,MAAM,GACN,EAAE,mBAAmB,GAAG,IAAI,CAsH5B"}

package/dist/engine/functions/register-builtins.js

@@ -0,0 +1,110 @@
+import { uuidV7Sync } from "./uuid-v7.js";
+import { nanoIdSync } from "./nano-id.js";
+import { getTimestampSync } from "./timestamp.js";
+import { humanIdSync } from "./generate-human-id.js";
+import { randomSync, commitDeterministicRngState } from "./random.js";
+import { commitSequenceNumberSync, nextSequenceNumberSync, } from "./sequence.js";
+import { updateStateCache } from "../../state/cache/update-state-cache.js";
+import { markStateCacheAsFresh } from "../../state/cache/mark-state-cache-as-stale.js";
+import { refreshWorkingChangeSet, } from "../../state/working-change-set/refresh-working-change-set.js";
+import { createExplainQuery } from "../explain-query.js";
+export function registerBuiltinFunctions({ register, engine, }) {
+    const explain = createExplainQuery({ engine });
+    register({
+        name: "lix_uuid_v7",
+        handler: (ctx) => uuidV7Sync({ engine: ctx.engine }),
+    });
+    register({
+        name: "lix_nano_id",
+        handler: (ctx, args) => nanoIdSync({ engine: ctx.engine, length: args?.length }),
+    });
+    register({
+        name: "lix_timestamp",
+        handler: (ctx) => getTimestampSync({ engine: ctx.engine }),
+    });
+    register({
+        name: "lix_human_id",
+        handler: (ctx, args) => {
+            return humanIdSync({
+                engine: ctx.engine,
+                ...args,
+            });
+        },
+    });
+    register({
+        name: "lix_random",
+        handler: (ctx) => randomSync({ engine: ctx.engine }),
+    });
+    // TODO likely remove from public API
+    register({
+        name: "lix_next_sequence_number",
+        handler: (ctx) => nextSequenceNumberSync({ engine: ctx.engine }),
+    });
+    // TODO likely remove from public API
+    register({
+        name: "lix_commit_deterministic_rng_state",
+        handler: (ctx, args) => {
+            commitDeterministicRngState({
+                engine: ctx.engine,
+                ...args,
+            });
+            return null;
+        },
+    });
+    // TODO likely remove from public API
+    register({
+        name: "lix_commit_sequence_number",
+        handler: (ctx, args) => {
+            commitSequenceNumberSync({
+                engine: ctx.engine,
+                ...args,
+            });
+            return null;
+        },
+    });
+    // TODO likely remove from public API
+    register({
+        name: "lix_update_state_cache",
+        handler: (ctx, args) => {
+            updateStateCache({
+                engine: ctx.engine,
+                ...args,
+            });
+            return null;
+        },
+    });
+    // TODO likely remove from public API
+    register({
+        name: "lix_mark_state_cache_as_fresh",
+        handler: (ctx) => {
+            markStateCacheAsFresh({ engine: ctx.engine });
+            return null;
+        },
+    });
+    register({
+        name: "lix_refresh_working_change_set",
+        handler: (ctx, args) => {
+            const payload = (args ?? {});
+            refreshWorkingChangeSet({
+                engine: ctx.engine,
+                version: {
+                    id: payload.versionId,
+                    commit_id: payload.commitId ?? null,
+                    working_commit_id: payload.workingCommitId ?? null,
+                },
+                timestamp: payload.timestamp,
+                changes: payload.changes ?? [],
+            });
+            return null;
+        },
+    });
+    register({
+        name: "lix_execute_sync",
+        handler: (ctx, args) => ctx.engine.executeSync(args),
+    });
+    register({
+        name: "lix_explain_query",
+        handler: (_ctx, args) => explain(args),
+    });
+}
+//# sourceMappingURL=register-builtins.js.map

package/dist/engine/functions/register-builtins.js.map

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