anchordb 0.2.0

package/dist/esm/core/hlc.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Hybrid Logical Clock.
+ *
+ * Wall clocks on phones are wrong often enough that ordering cannot be built on them: users change
+ * the date, timezones shift, DST jumps, and devices sit offline for days. An HLC keeps the *useful*
+ * property of a wall clock (roughly tracks real time, so it stays human-interpretable) while adding
+ * the property a wall clock lacks (it never goes backwards, and it advances whenever it observes a
+ * newer clock elsewhere).
+ *
+ * Encoded form is fixed-width and lexicographically sortable, so it can be compared as TEXT in SQL
+ * and used directly as a sort key:
+ *
+ *   000001756616340000-00000-cli_7f3a
+ *   \______wall_____/ \cnt/ \_node_/
+ */
+export interface Hlc {
+    /** Physical time in epoch milliseconds (skew-corrected where an offset is known). */
+    readonly wall: number;
+    /** Logical counter, breaks ties inside a single millisecond. */
+    readonly counter: number;
+    /** Node identity — the client id. Guarantees a total order with no ties. */
+    readonly node: string;
+}
+export declare function encodeHlc(hlc: Hlc): string;
+export declare function decodeHlc(encoded: string): Hlc;
+/**
+ * Total order over HLC stamps: wall, then counter, then node.
+ *
+ * The node tiebreak is what makes this a *total* order rather than a partial one. Without it two
+ * devices could produce genuinely equal stamps and "last write wins" would have no answer — the
+ * outcome would depend on map iteration order, which is how a sync engine ends up non-deterministic
+ * and different devices converge to different documents.
+ */
+export declare function compareHlc(a: Hlc, b: Hlc): number;
+export declare function compareHlcStamps(a: string, b: string): number;
+export interface HlcOptions {
+    node: string;
+    /** Injected so the sync engine can supply server-skew-corrected time. Defaults to Date.now. */
+    now?: () => number;
+    /**
+     * How far ahead of local time an *untrusted* peer stamp may be before it is ignored (default
+     * 1 hour). Guards against one device with a broken clock dragging the whole fleet forward.
+     *
+     * Deliberately does NOT apply to trusted stamps — see `update()`.
+     */
+    maxDriftMs?: number;
+}
+export declare class HybridLogicalClock {
+    /**
+     * Not `readonly`: the client id is only known for certain after storage has been opened and the
+     * persisted one restored. See setNode().
+     */
+    node: string;
+    private wall;
+    private counter;
+    private readonly nowFn;
+    private readonly maxDriftMs;
+    constructor(opts: HlcOptions);
+    /** Stamp a local event. Never returns a value <= the previous one. */
+    tick(): Hlc;
+    /** Stamp a local event and return the encoded form. */
+    tickStamp(): string;
+    /**
+     * Merge an observed remote stamp, then stamp a local event. This is what lets a device with a
+     * wrong clock self-correct: after one sync it is ordered relative to everyone else.
+     *
+     * `trusted` matters more than it looks. The drift guard compares the remote stamp against the
+     * *local* clock — but the whole reason we need an HLC is that the local clock may be the wrong
+     * one. A device sitting an hour behind would see every legitimate stamp as an "absurd future" and
+     * reject all of them, permanently isolating itself in the ordering: the guard would defeat the
+     * mechanism it is protecting.
+     *
+     * So the server, which is the time authority, is always adopted (`trusted: true`). The guard
+     * applies only to peer stamps, where we genuinely cannot tell whose clock is broken.
+     */
+    update(remote: Hlc | string, opts?: {
+        trusted?: boolean;
+    }): Hlc;
+    updateStamp(remote: Hlc | string, opts?: {
+        trusted?: boolean;
+    }): string;
+    /** Current value without advancing. */
+    peek(): Hlc;
+    /**
+     * Correct the node identity before any stamp is issued.
+     *
+     * AnchorDB generates a client id synchronously in its constructor, but the *persisted* id is only
+     * available after the adapter opens. Without this, a restarted app would stamp with a fresh node
+     * id while presenting the restored one as its clientId — the HLC tiebreak and the device identity
+     * would disagree, and two runs of the same device would order as if they were different devices.
+     */
+    setNode(node: string): void;
+    /** Restore across an app restart, so ordering survives process death. */
+    restore(stamp: Hlc | string): void;
+}
+//# sourceMappingURL=hlc.d.ts.map

package/dist/esm/core/hlc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hlc.d.ts","sourceRoot":"","sources":["../../../src/core/hlc.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,GAAG;IAClB,qFAAqF;IACrF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAMD,wBAAgB,SAAS,CAAC,GAAG,EAAE,GAAG,GAAG,MAAM,CAQ1C;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,GAAG,CAW9C;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG,GAAG,MAAM,CAKjD;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAG7D;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,+FAA+F;IAC/F,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,kBAAkB;IAC7B;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,IAAI,EAAE,UAAU;IAQ5B,sEAAsE;IACtE,IAAI,IAAI,GAAG;IAgBX,uDAAuD;IACvD,SAAS,IAAI,MAAM;IAInB;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,MAAM,EAAE,GAAG,GAAG,MAAM,EAAE,IAAI,GAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,GAAG;IA0BnE,WAAW,CAAC,MAAM,EAAE,GAAG,GAAG,MAAM,EAAE,IAAI,GAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,MAAM;IAI3E,uCAAuC;IACvC,IAAI,IAAI,GAAG;IAIX;;;;;;;OAOG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI3B,yEAAyE;IACzE,OAAO,CAAC,KAAK,EAAE,GAAG,GAAG,MAAM,GAAG,IAAI;CAOnC"}

package/dist/esm/core/hlc.js

@@ -0,0 +1,153 @@
+/**
+ * Hybrid Logical Clock.
+ *
+ * Wall clocks on phones are wrong often enough that ordering cannot be built on them: users change
+ * the date, timezones shift, DST jumps, and devices sit offline for days. An HLC keeps the *useful*
+ * property of a wall clock (roughly tracks real time, so it stays human-interpretable) while adding
+ * the property a wall clock lacks (it never goes backwards, and it advances whenever it observes a
+ * newer clock elsewhere).
+ *
+ * Encoded form is fixed-width and lexicographically sortable, so it can be compared as TEXT in SQL
+ * and used directly as a sort key:
+ *
+ *   000001756616340000-00000-cli_7f3a
+ *   \______wall_____/ \cnt/ \_node_/
+ */
+const WALL_DIGITS = 15;
+const COUNTER_DIGITS = 5;
+const MAX_COUNTER = 99_999;
+export function encodeHlc(hlc) {
+    return (String(hlc.wall).padStart(WALL_DIGITS, "0") +
+        "-" +
+        String(hlc.counter).padStart(COUNTER_DIGITS, "0") +
+        "-" +
+        hlc.node);
+}
+export function decodeHlc(encoded) {
+    const first = encoded.indexOf("-");
+    const second = encoded.indexOf("-", first + 1);
+    if (first < 0 || second < 0) {
+        throw new TypeError(`Malformed HLC stamp: "${encoded}"`);
+    }
+    return {
+        wall: Number(encoded.slice(0, first)),
+        counter: Number(encoded.slice(first + 1, second)),
+        node: encoded.slice(second + 1),
+    };
+}
+/**
+ * Total order over HLC stamps: wall, then counter, then node.
+ *
+ * The node tiebreak is what makes this a *total* order rather than a partial one. Without it two
+ * devices could produce genuinely equal stamps and "last write wins" would have no answer — the
+ * outcome would depend on map iteration order, which is how a sync engine ends up non-deterministic
+ * and different devices converge to different documents.
+ */
+export function compareHlc(a, b) {
+    if (a.wall !== b.wall)
+        return a.wall < b.wall ? -1 : 1;
+    if (a.counter !== b.counter)
+        return a.counter < b.counter ? -1 : 1;
+    if (a.node === b.node)
+        return 0;
+    return a.node < b.node ? -1 : 1;
+}
+export function compareHlcStamps(a, b) {
+    // Fixed-width encoding means plain string comparison is already the correct order.
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+export class HybridLogicalClock {
+    constructor(opts) {
+        this.node = opts.node;
+        this.nowFn = opts.now ?? (() => Date.now());
+        this.maxDriftMs = opts.maxDriftMs ?? 3_600_000;
+        this.wall = 0;
+        this.counter = 0;
+    }
+    /** Stamp a local event. Never returns a value <= the previous one. */
+    tick() {
+        const physical = this.nowFn();
+        if (physical > this.wall) {
+            this.wall = physical;
+            this.counter = 0;
+        }
+        else {
+            // Physical clock stalled or went backwards; keep moving via the logical counter.
+            this.counter += 1;
+            if (this.counter > MAX_COUNTER) {
+                this.wall += 1;
+                this.counter = 0;
+            }
+        }
+        return { wall: this.wall, counter: this.counter, node: this.node };
+    }
+    /** Stamp a local event and return the encoded form. */
+    tickStamp() {
+        return encodeHlc(this.tick());
+    }
+    /**
+     * Merge an observed remote stamp, then stamp a local event. This is what lets a device with a
+     * wrong clock self-correct: after one sync it is ordered relative to everyone else.
+     *
+     * `trusted` matters more than it looks. The drift guard compares the remote stamp against the
+     * *local* clock — but the whole reason we need an HLC is that the local clock may be the wrong
+     * one. A device sitting an hour behind would see every legitimate stamp as an "absurd future" and
+     * reject all of them, permanently isolating itself in the ordering: the guard would defeat the
+     * mechanism it is protecting.
+     *
+     * So the server, which is the time authority, is always adopted (`trusted: true`). The guard
+     * applies only to peer stamps, where we genuinely cannot tell whose clock is broken.
+     */
+    update(remote, opts = {}) {
+        const r = typeof remote === "string" ? decodeHlc(remote) : remote;
+        const physical = this.nowFn();
+        const tooFarAhead = !opts.trusted && r.wall > physical + this.maxDriftMs;
+        const remoteWall = tooFarAhead ? this.wall : r.wall;
+        if (physical > this.wall && physical > remoteWall) {
+            this.wall = physical;
+            this.counter = 0;
+        }
+        else if (remoteWall > this.wall) {
+            this.wall = remoteWall;
+            this.counter = r.counter + 1;
+        }
+        else if (this.wall === remoteWall) {
+            this.counter = Math.max(this.counter, r.counter) + 1;
+        }
+        else {
+            this.counter += 1;
+        }
+        if (this.counter > MAX_COUNTER) {
+            this.wall += 1;
+            this.counter = 0;
+        }
+        return { wall: this.wall, counter: this.counter, node: this.node };
+    }
+    updateStamp(remote, opts = {}) {
+        return encodeHlc(this.update(remote, opts));
+    }
+    /** Current value without advancing. */
+    peek() {
+        return { wall: this.wall, counter: this.counter, node: this.node };
+    }
+    /**
+     * Correct the node identity before any stamp is issued.
+     *
+     * AnchorDB generates a client id synchronously in its constructor, but the *persisted* id is only
+     * available after the adapter opens. Without this, a restarted app would stamp with a fresh node
+     * id while presenting the restored one as its clientId — the HLC tiebreak and the device identity
+     * would disagree, and two runs of the same device would order as if they were different devices.
+     */
+    setNode(node) {
+        this.node = node;
+    }
+    /** Restore across an app restart, so ordering survives process death. */
+    restore(stamp) {
+        const h = typeof stamp === "string" ? decodeHlc(stamp) : stamp;
+        if (h.wall > this.wall || (h.wall === this.wall && h.counter > this.counter)) {
+            this.wall = h.wall;
+            this.counter = h.counter;
+        }
+    }
+}
+//# sourceMappingURL=hlc.js.map

package/dist/esm/core/hlc.js.map

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

package/dist/esm/core/object-id.d.ts

@@ -0,0 +1,38 @@
+export type ObjectIdLike = ObjectId | string | Uint8Array | {
+    toHexString(): string;
+};
+/**
+ * A note on numbers: bson (and therefore Mongoose) rejects `new ObjectId(1234)` outright with
+ * "Argument passed in does not match the accepted types". AnchorDB rejects it too, rather than
+ * offering a friendlier overload, because a convenience that exists only here is exactly the kind
+ * of drift that stops code porting cleanly. Build from a time with `createFromTime()`.
+ */
+export declare class ObjectId {
+    /** Marks the value for BSON/Mongoose consumers that brand-check instead of instanceof. */
+    readonly _bsontype = "ObjectId";
+    private readonly bytes;
+    private cachedHex;
+    constructor(value?: ObjectIdLike | null);
+    /** Raw 12 bytes. Copied, so callers cannot mutate an id in place. */
+    get id(): Uint8Array;
+    toHexString(): string;
+    toString(): string;
+    /** Serialises to the plain hex string, matching Mongoose — not to `{ $oid }`. */
+    toJSON(): string;
+    /** Second-precision creation time. Useful, but never the canonical `createdAt`. */
+    getTimestamp(): Date;
+    equals(other: ObjectIdLike | null | undefined): boolean;
+    inspect(): string;
+    /** Raw 12-byte generator. `time` is seconds since the epoch; defaults to now. */
+    static generate(time?: number): Uint8Array;
+    static createFromHexString(hex: string): ObjectId;
+    static createFromTime(seconds: number): ObjectId;
+    /**
+     * Mirrors the driver's `isValid`: accepts a 24-char hex string, 12 raw bytes, an ObjectId, or
+     * anything exposing `toHexString()`. Notably it does *not* accept arbitrary 12-char strings.
+     */
+    static isValid(value: unknown): boolean;
+    /** Test seam so counter-rollover behaviour can be exercised deterministically. */
+    static __setCounter(value: number): void;
+}
+//# sourceMappingURL=object-id.d.ts.map

package/dist/esm/core/object-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-id.d.ts","sourceRoot":"","sources":["../../../src/core/object-id.ts"],"names":[],"mappings":"AA+BA,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG;IAAE,WAAW,IAAI,MAAM,CAAA;CAAE,CAAC;AAEtF;;;;;GAKG;AAEH,qBAAa,QAAQ;IACnB,0FAA0F;IAC1F,QAAQ,CAAC,SAAS,cAAc;IAEhC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,SAAS,CAAuB;gBAE5B,KAAK,CAAC,EAAE,YAAY,GAAG,IAAI;IAqCvC,qEAAqE;IACrE,IAAI,EAAE,IAAI,UAAU,CAEnB;IAED,WAAW,IAAI,MAAM;IAKrB,QAAQ,IAAI,MAAM;IAIlB,iFAAiF;IACjF,MAAM,IAAI,MAAM;IAIhB,mFAAmF;IACnF,YAAY,IAAI,IAAI;IAKpB,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO;IAgBvD,OAAO,IAAI,MAAM;IAIjB,iFAAiF;IACjF,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU;IAmB1C,MAAM,CAAC,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ;IAIjD,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ;IAShD;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAWvC,kFAAkF;IAClF,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAGzC"}

package/dist/esm/core/object-id.js

@@ -0,0 +1,163 @@
+import { bytesToHex, hexToBytes } from "./hex.js";
+import { randomBytes, randomInt } from "./random.js";
+/**
+ * A real MongoDB ObjectId — not a lookalike.
+ *
+ * Layout is exactly the BSON spec, which is what makes documents portable to a real database
+ * without translation:
+ *
+ *   bytes 0-3   4-byte big-endian seconds since the Unix epoch
+ *   bytes 4-8   5-byte value random per process
+ *   bytes 9-11  3-byte big-endian counter, randomly seeded
+ *
+ * Two consequences we rely on elsewhere:
+ *
+ *  - Because the timestamp leads and is big-endian, the lowercase hex form sorts in the same order
+ *    as the raw bytes. So `_id` can be the SQLite TEXT primary key and still give creation-ordered
+ *    scans and cheap cursor pagination, with no separate sort column.
+ *  - The per-process random block is what keeps two devices generating ids offline from colliding,
+ *    which is why `random.ts` refuses to run without a real CSPRNG.
+ */
+const PROCESS_RANDOM = randomBytes(5);
+const COUNTER_MAX = 0xffffff;
+let counter = randomInt(COUNTER_MAX + 1);
+function nextCounter() {
+    counter = (counter + 1) % (COUNTER_MAX + 1); // wraps at 2^24, as the spec requires
+    return counter;
+}
+/**
+ * A note on numbers: bson (and therefore Mongoose) rejects `new ObjectId(1234)` outright with
+ * "Argument passed in does not match the accepted types". AnchorDB rejects it too, rather than
+ * offering a friendlier overload, because a convenience that exists only here is exactly the kind
+ * of drift that stops code porting cleanly. Build from a time with `createFromTime()`.
+ */
+export class ObjectId {
+    constructor(value) {
+        /** Marks the value for BSON/Mongoose consumers that brand-check instead of instanceof. */
+        this._bsontype = "ObjectId";
+        this.cachedHex = null;
+        if (value === undefined || value === null) {
+            this.bytes = ObjectId.generate();
+            return;
+        }
+        if (value instanceof ObjectId) {
+            this.bytes = value.bytes.slice();
+            return;
+        }
+        if (typeof value === "string") {
+            const parsed = hexToBytes(value, 12);
+            if (!parsed) {
+                throw new TypeError(`Argument passed in must be a string of 12 bytes or a string of 24 hex characters, got "${value}"`);
+            }
+            this.bytes = parsed;
+            return;
+        }
+        if (value instanceof Uint8Array) {
+            if (value.length !== 12) {
+                throw new TypeError(`Argument passed in must be 12 bytes, got ${value.length}`);
+            }
+            this.bytes = value.slice();
+            return;
+        }
+        if (typeof value.toHexString === "function") {
+            // Accepts a foreign ObjectId (e.g. from the official `bson` package) without importing it.
+            const parsed = hexToBytes(value.toHexString(), 12);
+            if (parsed) {
+                this.bytes = parsed;
+                return;
+            }
+        }
+        throw new TypeError("Argument passed in does not match the accepted types");
+    }
+    /** Raw 12 bytes. Copied, so callers cannot mutate an id in place. */
+    get id() {
+        return this.bytes.slice();
+    }
+    toHexString() {
+        this.cachedHex ??= bytesToHex(this.bytes);
+        return this.cachedHex;
+    }
+    toString() {
+        return this.toHexString();
+    }
+    /** Serialises to the plain hex string, matching Mongoose — not to `{ $oid }`. */
+    toJSON() {
+        return this.toHexString();
+    }
+    /** Second-precision creation time. Useful, but never the canonical `createdAt`. */
+    getTimestamp() {
+        const seconds = (this.bytes[0] << 24) | (this.bytes[1] << 16) | (this.bytes[2] << 8) | this.bytes[3];
+        return new Date((seconds >>> 0) * 1000);
+    }
+    equals(other) {
+        if (other === null || other === undefined)
+            return false;
+        if (other instanceof ObjectId)
+            return this.toHexString() === other.toHexString();
+        if (typeof other === "string")
+            return this.toHexString() === other.toLowerCase();
+        if (other instanceof Uint8Array) {
+            if (other.length !== 12)
+                return false;
+            return this.toHexString() === bytesToHex(other);
+        }
+        if (typeof other.toHexString === "function")
+            return this.toHexString() === other.toHexString().toLowerCase();
+        return false;
+    }
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        return `new ObjectId("${this.toHexString()}")`;
+    }
+    inspect() {
+        return `new ObjectId("${this.toHexString()}")`;
+    }
+    /** Raw 12-byte generator. `time` is seconds since the epoch; defaults to now. */
+    static generate(time) {
+        const seconds = Math.floor(time ?? Date.now() / 1000);
+        const out = new Uint8Array(12);
+        out[0] = (seconds >> 24) & 0xff;
+        out[1] = (seconds >> 16) & 0xff;
+        out[2] = (seconds >> 8) & 0xff;
+        out[3] = seconds & 0xff;
+        out.set(PROCESS_RANDOM, 4);
+        const c = nextCounter();
+        out[9] = (c >> 16) & 0xff;
+        out[10] = (c >> 8) & 0xff;
+        out[11] = c & 0xff;
+        return out;
+    }
+    static createFromHexString(hex) {
+        return new ObjectId(hex);
+    }
+    static createFromTime(seconds) {
+        const bytes = new Uint8Array(12);
+        bytes[0] = (seconds >> 24) & 0xff;
+        bytes[1] = (seconds >> 16) & 0xff;
+        bytes[2] = (seconds >> 8) & 0xff;
+        bytes[3] = seconds & 0xff;
+        return new ObjectId(bytes);
+    }
+    /**
+     * Mirrors the driver's `isValid`: accepts a 24-char hex string, 12 raw bytes, an ObjectId, or
+     * anything exposing `toHexString()`. Notably it does *not* accept arbitrary 12-char strings.
+     */
+    static isValid(value) {
+        if (value === null || value === undefined)
+            return false;
+        if (value instanceof ObjectId)
+            return true;
+        if (typeof value === "string")
+            return hexToBytes(value, 12) !== null;
+        if (value instanceof Uint8Array)
+            return value.length === 12;
+        if (typeof value.toHexString === "function") {
+            return hexToBytes(value.toHexString(), 12) !== null;
+        }
+        return false;
+    }
+    /** Test seam so counter-rollover behaviour can be exercised deterministically. */
+    static __setCounter(value) {
+        counter = value % (COUNTER_MAX + 1);
+    }
+}
+//# sourceMappingURL=object-id.js.map

package/dist/esm/core/object-id.js.map

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

package/dist/esm/core/random.d.ts

@@ -0,0 +1,6 @@
+/** Test seam, and the escape hatch for exotic runtimes. Pass `null` to restore platform crypto. */
+export declare function setRandomBytesSource(fn: ((size: number) => Uint8Array) | null): void;
+export declare function randomBytes(size: number): Uint8Array;
+/** Uniform integer in [0, maxExclusive). Used to seed the ObjectId counter. */
+export declare function randomInt(maxExclusive: number): number;
+//# sourceMappingURL=random.d.ts.map

package/dist/esm/core/random.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"random.d.ts","sourceRoot":"","sources":["../../../src/core/random.ts"],"names":[],"mappings":"AAYA,mGAAmG;AACnG,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,UAAU,CAAC,GAAG,IAAI,GAAG,IAAI,CAEpF;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAepD;AAED,+EAA+E;AAC/E,wBAAgB,SAAS,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAItD"}

package/dist/esm/core/random.js

@@ -0,0 +1,34 @@
+import { AnchorConfigError } from "./errors.js";
+/**
+ * Cryptographically secure random bytes.
+ *
+ * ObjectId collision resistance depends on this being a real CSPRNG, so there is deliberately no
+ * `Math.random()` fallback: on a platform without one we throw a message that names the fix. A
+ * silent downgrade would raise collision risk across devices in exactly the offline, multi-device
+ * scenario AnchorDB exists to serve, and would do so invisibly.
+ */
+let override = null;
+/** Test seam, and the escape hatch for exotic runtimes. Pass `null` to restore platform crypto. */
+export function setRandomBytesSource(fn) {
+    override = fn;
+}
+export function randomBytes(size) {
+    if (override)
+        return override(size);
+    const out = new Uint8Array(size);
+    const c = globalThis.crypto;
+    if (c && typeof c.getRandomValues === "function") {
+        c.getRandomValues(out);
+        return out;
+    }
+    throw new AnchorConfigError("No cryptographically secure random source is available (globalThis.crypto.getRandomValues is missing). " +
+        "On React Native, install and import `react-native-get-random-values` at the top of your entry file. " +
+        "AnchorDB refuses to fall back to Math.random() because ObjectId uniqueness depends on real entropy.");
+}
+/** Uniform integer in [0, maxExclusive). Used to seed the ObjectId counter. */
+export function randomInt(maxExclusive) {
+    const bytes = randomBytes(4);
+    const value = ((bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3]) >>> 0;
+    return value % maxExclusive;
+}
+//# sourceMappingURL=random.js.map

package/dist/esm/core/random.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"random.js","sourceRoot":"","sources":["../../../src/core/random.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;;GAOG;AACH,IAAI,QAAQ,GAA0C,IAAI,CAAC;AAE3D,mGAAmG;AACnG,MAAM,UAAU,oBAAoB,CAAC,EAAyC;IAC5E,QAAQ,GAAG,EAAE,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC;IAEpC,MAAM,GAAG,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,CAAC,GAAuB,UAAU,CAAC,MAAM,CAAC;IAChD,IAAI,CAAC,IAAI,OAAO,CAAC,CAAC,eAAe,KAAK,UAAU,EAAE,CAAC;QACjD,CAAC,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;QACvB,OAAO,GAAG,CAAC;IACb,CAAC;IAED,MAAM,IAAI,iBAAiB,CACzB,yGAAyG;QACvG,sGAAsG;QACtG,qGAAqG,CACxG,CAAC;AACJ,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,SAAS,CAAC,YAAoB;IAC5C,MAAM,KAAK,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;IAC7B,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAE,IAAI,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAE,IAAI,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAE,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC,CAAC;IAC3F,OAAO,KAAK,GAAG,YAAY,CAAC;AAC9B,CAAC"}

package/dist/esm/core/runtime.d.ts

@@ -0,0 +1,96 @@
+import type { HybridLogicalClock } from "./hlc.js";
+import type { TimeService } from "../timestamps/index.js";
+import type { TypedEmitter } from "../events/emitter.js";
+import type { DatabaseAdapter, WriteOp } from "../storage/types.js";
+import type { Model } from "../model/model.js";
+/** Events the SDK emits. Local events fire in both modes; sync events only in synced mode. */
+export interface AnchorEvents extends Record<string, unknown> {
+    change: {
+        collection: string;
+        modelName: string;
+        operation: "insert" | "update" | "replace" | "delete";
+        documentId: string;
+        document: Record<string, unknown> | null;
+    };
+    "queue:changed": {
+        pending: number;
+        failed: number;
+    };
+    online: {
+        at: string;
+    };
+    offline: {
+        at: string;
+    };
+    "sync:start": {
+        pending: number;
+    };
+    "sync:progress": {
+        pushed: number;
+        pulled: number;
+    };
+    "sync:complete": {
+        pushed: number;
+        pulled: number;
+        conflicts: number;
+        durationMs: number;
+    };
+    "sync:error": {
+        error: Error;
+        phase: "push" | "pull";
+    };
+    conflict: {
+        collection: string;
+        documentId: string;
+        strategy: string;
+        winner: "local" | "remote" | "merged";
+        local: Record<string, unknown>;
+        remote: Record<string, unknown>;
+        base?: Record<string, unknown>;
+        resolved: Record<string, unknown>;
+    };
+    "conflict:unresolvable": {
+        collection: string;
+        documentId: string;
+        attempts: number;
+    };
+    "duplicate-key": {
+        collection: string;
+        documentId: string;
+        index: string;
+        keyValue: Record<string, unknown>;
+    };
+    "auth:expired": {
+        at: string;
+    };
+}
+/**
+ * The shared services a Model needs, passed as one object so Model never reaches back into AnchorDB.
+ *
+ * `syncEnabled` is the single flag that distinguishes the two modes. It is read at write time rather
+ * than branching into a different code path, which is what keeps local-only and synced behaviour
+ * identical everywhere except where they genuinely must differ (queueing and tombstones).
+ */
+export interface AnchorRuntime {
+    readonly adapter: DatabaseAdapter;
+    readonly time: TimeService;
+    readonly clock: HybridLogicalClock;
+    readonly events: TypedEmitter<AnchorEvents>;
+    readonly syncEnabled: boolean;
+    readonly clientId: string;
+    readonly onMissingRef: "null" | "keep-id" | "throw";
+    getModel(name: string): Model;
+    /** Resolve a storage collection name to its model, if one is registered. Used by $lookup. */
+    getModelByCollection?(collection: string): Model | undefined;
+    /**
+     * Resolves once the adapter is open.
+     *
+     * AnchorDB opens lazily so construction never does I/O, which means every Model operation must
+     * await this first. MemoryAdapter tolerates being used unopened; a SQLite adapter does not, so
+     * without this the file-backed path fails while the in-memory tests pass.
+     */
+    ready(): Promise<void>;
+    /** No-op in local-only mode; the sync engine installs the real implementation. */
+    recordMutations(collection: string, ops: WriteOp[]): Promise<void>;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/esm/core/runtime.d.ts.map

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

package/dist/esm/core/runtime.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=runtime.js.map

package/dist/esm/core/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../../src/core/runtime.ts"],"names":[],"mappings":""}