liepoch 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 deathg0d
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,122 @@
+# liepoch
+
+**Distributed timestamps that actually mean something.**
+
+Timestamps in distributed systems are lies. Two machines clock a simultaneous event, and due to NTP drift, one says it happened 47 milliseconds before the other. This breaks log causality, scrambles trace ordering, and silently destroys data in Last-Write-Wins databases.
+
+`liepoch` is a zero-dependency, zero-ceremony **Hybrid Logical Clock (HLC)** for Node.js and TypeScript. It packs a physical timestamp and a logical causality counter into a single 64-bit integer, serialized as a safe, universally sortable string. 
+
+If `liepoch` becomes the standard, suddenly all your microservices, background workers, and distributed databases speak the exact same temporal language.
+
+## Installation
+
+```bash
+npm install liepoch
+```
+
+## The "Zero Ceremony" Guarantees
+Every distributed system rolls its own HLC, usually with fatal edge cases. `liepoch` is designed to be a foolproof drop-in primitive:
+* **JSON Safe:** Returns fixed-width hex strings (`"0000018f2a1b0001"`). No `TypeError: Do not know how to serialize a BigInt` crashes.
+* **Database Safe:** Because they are zero-padded 16-character strings, they **sort natively and correctly** in standard `VARCHAR` columns, MongoDB strings, and Redis sorted sets without needing custom comparison logic.
+* **Type Safe:** Explicitly rejects standard JavaScript `Number` types (like `Date.now()`) to prevent silent precision loss beyond 53 bits.
+* **Drift Protected:** Bounds severe backward NTP drift and malicious future-dated messages.
+
+---
+
+## Quick Start
+
+By default, `liepoch` exports a singleton. You use `stamp()` when an event happens, and `receive()` when you get a message from another machine.
+
+### Service A (The Sender)
+```typescript
+import { stamp } from 'liepoch';
+
+app.post('/checkout', (req, res) => {
+    // Generate a causal timestamp for this event
+    const eventTime = stamp(); 
+    
+    // Send to Kafka/RabbitMQ/Redis/etc
+    messageQueue.publish('orders', {
+        id: 'order_123',
+        _causality: eventTime, 
+        data: req.body
+    });
+});
+```
+
+### Service B (The Receiver)
+```typescript
+import { receive } from 'liepoch';
+
+messageQueue.subscribe('orders', (msg) => {
+    // Absorb the timestamp from Service A.
+    // If Service B's physical clock is running slightly slow, 
+    // receive() forces Service B's clock into the correct causal future.
+    const localTime = receive(msg._causality);
+    
+    // localTime is strictly causally > msg._causality
+    db.save({
+        ...msg.data,
+        updated_at: localTime 
+    });
+});
+```
+
+---
+
+## Use Cases
+
+### 1. Correcting Microservice Logs (No More Time Travel)
+If Service A logs an event, forwards it to Worker B, and Worker B's clock is 15ms behind, standard logs will show the worker processing the event *before* the user even clicked the button. 
+
+By passing `liepoch` timestamps between services via HTTP headers or queue payloads, and calling `receive()` on the worker, cause will **always** sort strictly before effect in Datadog, Splunk, or ElasticSearch.
+
+### 2. Preventing Silent Data Loss (Last-Write-Wins)
+In a distributed database (Cassandra, DynamoDB, or multi-writer Postgres), conflict resolution often relies on timestamps. If a user updates their profile on a server with a fast clock, and immediately fixes a typo on a server with an accurate clock, the database will incorrectly keep the older data because its physical timestamp is higher.
+
+Using `liepoch` ensures that the second write is causally stamped higher than the first write, preserving the user's intent perfectly.
+
+### 3. Same-Millisecond Collisions
+If a busy Node.js loop processes 50 events in a single millisecond, `Date.now()` gives them all the exact same timestamp. When saved to a database, their order is permanently lost. 
+
+`liepoch` uses the bottom 16 bits as a logical counter. All 50 events get the same physical time, but mathematically unique, strictly incrementing logical counters. Order is preserved flawlessly.
+
+---
+
+## API Reference
+
+### `stamp(): string`
+Generates a new timestamp string representing "now". Call this when a local event occurs.
+
+### `receive(incoming: string | bigint): string`
+Absorbs a remote timestamp, ensuring the local clock advances past it. Call this whenever you receive a message/request from another node.
+
+### `before(a: string | bigint, b: string | bigint): boolean`
+Returns `true` if event `a` happened causally before event `b`. Safely handles mixed inputs (raw hex, `0x`-prefixed hex, or BigInts).
+
+### `unpack(stamp: string | bigint): { time_ms: number, logical: number, date: Date }`
+Unpacks a `liepoch` timestamp into its physical millisecond time and its logical counter. Useful for human-readable debugging.
+
+### `clock: Liepoch`
+The underlying singleton instance. You can instantiate your own (`new Liepoch()`) if you need isolated clocks for unit testing, but 99% of applications should use the default singleton to maintain correct causality across the entire Node process.
+
+---
+
+## How it works under the hood
+
+A `liepoch` timestamp is a 64-bit integer:
+* **Top 48 bits**: Physical wall-clock time in milliseconds since the UNIX epoch (safe until the year 10,889 AD).
+* **Bottom 16 bits**: Logical counter (allows 65,536 causal events within the exact same millisecond).
+
+Because 64-bit integers lose precision in JavaScript's floating-point numbers, the public API deals entirely in 16-character, zero-padded hex strings. 
+
+```
+0000018f2a1b0001
+[ time ms  ][log]
+```
+
+## Ephemeral State & Restarts
+The singleton's state resides in memory. If your Node process crashes and restarts, it forgets its previous logical state. To guarantee absolute causality across process restarts in a high-throughput microservice, you should fetch the last known `liepoch` timestamp for this node from your database/store on boot, and pass it to `receive()` before processing new events.
+
+## License
+MIT

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+export declare class LiepochError extends Error {
+    constructor(message: string);
+}
+export declare class Liepoch {
+    private wallTime;
+    private logical;
+    private static readonly MAX_LOGICAL;
+    private static readonly MAX_DRIFT_MS;
+    private static readonly PAD_LENGTH;
+    private now;
+    /**
+     * Serialize a BigInt stamp to a fixed-width, zero-padded lowercase hex string.
+     * 16 hex chars = 64 bits. Sorts correctly lexicographically in any DB or index.
+     * Safe round-trip via deserialize().
+     */
+    static serialize(stamp: bigint): string;
+    /**
+     * Deserialize a stamp string back to BigInt.
+     * Accepts bare hex ("0000018f..."), prefixed ("0x0000018f..."),
+     * and uppercase hex ("0000018F...").
+     */
+    static deserialize(stamp: string): bigint;
+    /**
+     * Used primarily for testing to explicitly set the internal clock.
+     */
+    _setTestingState(wallTime: bigint, logical: bigint): void;
+    stamp(): bigint;
+    receive(incoming: bigint | string): bigint;
+    /**
+     * Unpack a timestamp into human-readable components.
+     */
+    static unpack(stamp: bigint | string): {
+        time_ms: number;
+        logical: number;
+        date: Date;
+    };
+}
+export declare const clock: Liepoch;
+export declare const stamp: () => string;
+export declare const receive: (ts: string | bigint) => string;
+export declare const unpack: typeof Liepoch.unpack;
+export declare const serialize: typeof Liepoch.serialize;
+export declare const deserialize: typeof Liepoch.deserialize;
+export declare const before: (a: string | bigint, b: string | bigint) => boolean;

package/dist/index.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.before = exports.deserialize = exports.serialize = exports.unpack = exports.receive = exports.stamp = exports.clock = exports.Liepoch = exports.LiepochError = void 0;
+class LiepochError extends Error {
+    constructor(message) {
+        super(`Liepoch: ${message}`);
+        this.name = 'LiepochError';
+    }
+}
+exports.LiepochError = LiepochError;
+class Liepoch {
+    wallTime = 0n;
+    logical = 0n;
+    static MAX_LOGICAL = 0xffffn;
+    static MAX_DRIFT_MS = 300000n;
+    static PAD_LENGTH = 16;
+    now() {
+        return BigInt(Date.now());
+    }
+    /**
+     * Serialize a BigInt stamp to a fixed-width, zero-padded lowercase hex string.
+     * 16 hex chars = 64 bits. Sorts correctly lexicographically in any DB or index.
+     * Safe round-trip via deserialize().
+     */
+    static serialize(stamp) {
+        return stamp.toString(16).padStart(Liepoch.PAD_LENGTH, '0');
+    }
+    /**
+     * Deserialize a stamp string back to BigInt.
+     * Accepts bare hex ("0000018f..."), prefixed ("0x0000018f..."),
+     * and uppercase hex ("0000018F...").
+     */
+    static deserialize(stamp) {
+        const clean = stamp.replace(/^0x/i, '');
+        if (!/^[0-9a-f]+$/i.test(clean)) {
+            throw new LiepochError("Invalid hex string provided to deserialize().");
+        }
+        return BigInt('0x' + clean);
+    }
+    /**
+     * Used primarily for testing to explicitly set the internal clock.
+     */
+    _setTestingState(wallTime, logical) {
+        this.wallTime = wallTime;
+        this.logical = logical;
+    }
+    stamp() {
+        const currentWall = this.now();
+        let nextWall = this.wallTime;
+        let nextLogical = this.logical;
+        if (currentWall > this.wallTime) {
+            nextWall = currentWall;
+            nextLogical = 0n;
+        }
+        else {
+            if (this.wallTime - currentWall > Liepoch.MAX_DRIFT_MS) {
+                throw new LiepochError(`Local physical clock is ${this.wallTime - currentWall}ms behind the last ` +
+                    `recorded wall time, exceeding MAX_DRIFT_MS (${Liepoch.MAX_DRIFT_MS}ms). ` +
+                    `This usually means NTP jumped the clock backward. ` +
+                    `Restart the process once the clock stabilizes.`);
+            }
+            nextLogical++;
+            if (nextLogical > Liepoch.MAX_LOGICAL) {
+                throw new LiepochError("Logical clock overflow in stamp(). Throughput too high for 16-bit counter.");
+            }
+        }
+        this.wallTime = nextWall;
+        this.logical = nextLogical;
+        return (this.wallTime << 16n) | this.logical;
+    }
+    receive(incoming) {
+        if (typeof incoming !== 'bigint' && typeof incoming !== 'string') {
+            throw new LiepochError(`receive() requires a BigInt or String. Got: ${typeof incoming}. ` +
+                `If reading from a JSON payload, the sender must serialize the timestamp ` +
+                `as a string before JSON.stringify(). Wrapping an already-parsed number ` +
+                `in String() will not recover lost precision.`);
+        }
+        const inc = typeof incoming === 'string' ? Liepoch.deserialize(incoming) : incoming;
+        const currentWall = this.now();
+        const msgTime = inc >> 16n;
+        const msgLogical = inc & 0xffffn;
+        if (msgTime > currentWall && msgTime - currentWall > Liepoch.MAX_DRIFT_MS) {
+            throw new LiepochError(`Incoming timestamp is ${msgTime - currentWall}ms in the future, ` +
+                `exceeding MAX_DRIFT_MS (${Liepoch.MAX_DRIFT_MS}ms).`);
+        }
+        let maxTime = currentWall;
+        if (this.wallTime > maxTime)
+            maxTime = this.wallTime;
+        if (msgTime > maxTime)
+            maxTime = msgTime;
+        let nextLogical;
+        if (maxTime === this.wallTime && maxTime === msgTime) {
+            nextLogical = (this.logical > msgLogical ? this.logical : msgLogical) + 1n;
+        }
+        else if (maxTime === this.wallTime) {
+            nextLogical = this.logical + 1n;
+        }
+        else if (maxTime === msgTime) {
+            nextLogical = msgLogical + 1n;
+        }
+        else {
+            nextLogical = 0n;
+        }
+        if (nextLogical > Liepoch.MAX_LOGICAL) {
+            throw new LiepochError("Logical clock overflow in receive(). State has not been mutated.");
+        }
+        this.wallTime = maxTime;
+        this.logical = nextLogical;
+        return (this.wallTime << 16n) | this.logical;
+    }
+    /**
+     * Unpack a timestamp into human-readable components.
+     */
+    static unpack(stamp) {
+        const val = typeof stamp === 'string' ? Liepoch.deserialize(stamp) : stamp;
+        const time_ms = Number(val >> 16n);
+        return {
+            time_ms,
+            logical: Number(val & 0xffffn),
+            date: new Date(time_ms)
+        };
+    }
+}
+exports.Liepoch = Liepoch;
+// ---------------------------------------------------------
+// Default singleton + ergonomic string API
+// ---------------------------------------------------------
+exports.clock = new Liepoch();
+const stamp = () => Liepoch.serialize(exports.clock.stamp());
+exports.stamp = stamp;
+const receive = (ts) => Liepoch.serialize(exports.clock.receive(ts));
+exports.receive = receive;
+exports.unpack = Liepoch.unpack;
+exports.serialize = Liepoch.serialize;
+exports.deserialize = Liepoch.deserialize;
+const before = (a, b) => {
+    const valA = typeof a === 'bigint' ? a : Liepoch.deserialize(a);
+    const valB = typeof b === 'bigint' ? b : Liepoch.deserialize(b);
+    return valA < valB;
+};
+exports.before = before;

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "liepoch",
+  "version": "1.0.0",
+  "description": "Distributed timestamps that actually mean something. A zero-dependency Hybrid Logical Clock (HLC).",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "node --import tsx --test test/**/*.test.ts",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "timestamp",
+    "distributed-systems",
+    "hlc",
+    "clock",
+    "causality",
+    "microservices",
+    "logs"
+  ],
+  "author": "Open Source Community",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "tsx": "^4.7.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,161 @@
+export class LiepochError extends Error {
+    constructor(message: string) {
+        super(`Liepoch: ${message}`);
+        this.name = 'LiepochError';
+    }
+}
+
+export class Liepoch {
+    private wallTime: bigint = 0n;
+    private logical: bigint = 0n;
+
+    private static readonly MAX_LOGICAL  = 0xFFFFn;
+    private static readonly MAX_DRIFT_MS = 300000n;
+    private static readonly PAD_LENGTH   = 16;
+
+    private now(): bigint {
+        return BigInt(Date.now());
+    }
+
+    /**
+     * Serialize a BigInt stamp to a fixed-width, zero-padded lowercase hex string.
+     * 16 hex chars = 64 bits. Sorts correctly lexicographically in any DB or index.
+     * Safe round-trip via deserialize().
+     */
+    public static serialize(stamp: bigint): string {
+        return stamp.toString(16).padStart(Liepoch.PAD_LENGTH, '0');
+    }
+
+    /**
+     * Deserialize a stamp string back to BigInt.
+     * Accepts bare hex ("0000018f..."), prefixed ("0x0000018f..."),
+     * and uppercase hex ("0000018F...").
+     */
+    public static deserialize(stamp: string): bigint {
+        const clean = stamp.replace(/^0x/i, '');
+        if (!/^[0-9a-f]+$/i.test(clean)) {
+            throw new LiepochError("Invalid hex string provided to deserialize().");
+        }
+        return BigInt('0x' + clean);
+    }
+
+    /**
+     * Used primarily for testing to explicitly set the internal clock.
+     */
+    public _setTestingState(wallTime: bigint, logical: bigint): void {
+        this.wallTime = wallTime;
+        this.logical = logical;
+    }
+
+    public stamp(): bigint {
+        const currentWall = this.now();
+
+        let nextWall    = this.wallTime;
+        let nextLogical = this.logical;
+
+        if (currentWall > this.wallTime) {
+            nextWall    = currentWall;
+            nextLogical = 0n;
+        } else {
+            if (this.wallTime - currentWall > Liepoch.MAX_DRIFT_MS) {
+                throw new LiepochError(
+                    `Local physical clock is ${this.wallTime - currentWall}ms behind the last ` +
+                    `recorded wall time, exceeding MAX_DRIFT_MS (${Liepoch.MAX_DRIFT_MS}ms). ` +
+                    `This usually means NTP jumped the clock backward. ` +
+                    `Restart the process once the clock stabilizes.`
+                );
+            }
+            nextLogical++;
+            if (nextLogical > Liepoch.MAX_LOGICAL) {
+                throw new LiepochError(
+                    "Logical clock overflow in stamp(). Throughput too high for 16-bit counter."
+                );
+            }
+        }
+
+        this.wallTime = nextWall;
+        this.logical  = nextLogical;
+
+        return (this.wallTime << 16n) | this.logical;
+    }
+
+    public receive(incoming: bigint | string): bigint {
+        if (typeof incoming !== 'bigint' && typeof incoming !== 'string') {
+            throw new LiepochError(
+                `receive() requires a BigInt or String. Got: ${typeof incoming}. ` +
+                `If reading from a JSON payload, the sender must serialize the timestamp ` +
+                `as a string before JSON.stringify(). Wrapping an already-parsed number ` +
+                `in String() will not recover lost precision.`
+            );
+        }
+
+        const inc         = typeof incoming === 'string' ? Liepoch.deserialize(incoming) : incoming;
+        const currentWall = this.now();
+        const msgTime     = inc >> 16n;
+        const msgLogical  = inc & 0xFFFFn;
+
+        if (msgTime > currentWall && msgTime - currentWall > Liepoch.MAX_DRIFT_MS) {
+            throw new LiepochError(
+                `Incoming timestamp is ${msgTime - currentWall}ms in the future, ` +
+                `exceeding MAX_DRIFT_MS (${Liepoch.MAX_DRIFT_MS}ms).`
+            );
+        }
+
+        let maxTime = currentWall;
+        if (this.wallTime > maxTime) maxTime = this.wallTime;
+        if (msgTime > maxTime)       maxTime = msgTime;
+
+        let nextLogical: bigint;
+
+        if (maxTime === this.wallTime && maxTime === msgTime) {
+            nextLogical = (this.logical > msgLogical ? this.logical : msgLogical) + 1n;
+        } else if (maxTime === this.wallTime) {
+            nextLogical = this.logical + 1n;
+        } else if (maxTime === msgTime) {
+            nextLogical = msgLogical + 1n;
+        } else {
+            nextLogical = 0n;
+        }
+
+        if (nextLogical > Liepoch.MAX_LOGICAL) {
+            throw new LiepochError(
+                "Logical clock overflow in receive(). State has not been mutated."
+            );
+        }
+
+        this.wallTime = maxTime;
+        this.logical  = nextLogical;
+
+        return (this.wallTime << 16n) | this.logical;
+    }
+
+    /**
+     * Unpack a timestamp into human-readable components.
+     */
+    public static unpack(stamp: bigint | string): { time_ms: number; logical: number; date: Date } {
+        const val     = typeof stamp === 'string' ? Liepoch.deserialize(stamp) : stamp;
+        const time_ms = Number(val >> 16n);
+        return {
+            time_ms,
+            logical : Number(val & 0xFFFFn),
+            date    : new Date(time_ms)
+        };
+    }
+}
+
+// ---------------------------------------------------------
+// Default singleton + ergonomic string API
+// ---------------------------------------------------------
+export const clock = new Liepoch();
+
+export const stamp       = ():                    string  => Liepoch.serialize(clock.stamp());
+export const receive     = (ts: string | bigint): string  => Liepoch.serialize(clock.receive(ts));
+export const unpack      = Liepoch.unpack;
+export const serialize   = Liepoch.serialize;
+export const deserialize = Liepoch.deserialize;
+
+export const before = (a: string | bigint, b: string | bigint): boolean => {
+    const valA = typeof a === 'bigint' ? a : Liepoch.deserialize(a);
+    const valB = typeof b === 'bigint' ? b : Liepoch.deserialize(b);
+    return valA < valB;
+};

package/test/liepoch.test.ts

@@ -0,0 +1,140 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { Liepoch, LiepochError, serialize, deserialize, before, unpack } from '../src/index';
+
+test('Liepoch Core Functionality', async (t) => {
+    
+    await t.test('Basic stamping advances time', () => {
+        let mockTimeMs = 1718838420000;
+        const originalNow = Date.now;
+        Date.now = () => mockTimeMs;
+
+        const clock = new Liepoch();
+        const s1 = clock.stamp();
+        mockTimeMs += 10;
+        const s2 = clock.stamp();
+        
+        assert.ok(s1 < s2, "s2 should be strictly greater than s1");
+        
+        Date.now = originalNow;
+    });
+
+    await t.test('Logical clock increments on same ms', () => {
+        let mockTimeMs = 1000;
+        const originalNow = Date.now;
+        Date.now = () => mockTimeMs;
+
+        const clock = new Liepoch();
+        const s1 = clock.stamp();
+        const s2 = clock.stamp();
+        
+        const unpacked1 = Liepoch.unpack(s1);
+        const unpacked2 = Liepoch.unpack(s2);
+        
+        assert.equal(unpacked1.time_ms, 1000);
+        assert.equal(unpacked1.logical, 0);
+        
+        assert.equal(unpacked2.time_ms, 1000);
+        assert.equal(unpacked2.logical, 1);
+        
+        Date.now = originalNow;
+    });
+
+    await t.test('Serialization and Deserialization', () => {
+        const stamp = (1000n << 16n) | 5n;
+        const hex = serialize(stamp);
+        
+        assert.equal(hex.length, 16, "Should be 16 chars long");
+        assert.equal(deserialize(hex), stamp, "Deserialization should be symmetric");
+        assert.equal(deserialize("0x" + hex), stamp, "Deserialization should handle 0x prefix");
+        assert.equal(deserialize(hex.toUpperCase()), stamp, "Deserialization should handle uppercase hex");
+        
+        assert.throws(() => deserialize("not-hex"), LiepochError, "Should throw on invalid hex");
+    });
+
+    await t.test('receive() absorbs future time', () => {
+        let mockTimeMs = 1000;
+        const originalNow = Date.now;
+        Date.now = () => mockTimeMs;
+
+        const clock = new Liepoch();
+        clock.stamp(); // internal time is now 1000, 0
+        
+        const remoteStamp = (1050n << 16n) | 0n; // Remote is at 1050ms
+        const r1 = clock.receive(remoteStamp);
+        const unpackedR1 = Liepoch.unpack(r1);
+        
+        assert.equal(unpackedR1.time_ms, 1050);
+        assert.equal(unpackedR1.logical, 1, "Logical should increment remote logical because max == remote");
+        
+        Date.now = originalNow;
+    });
+
+    await t.test('receive() with same time takes max logical', () => {
+        let mockTimeMs = 1000;
+        const originalNow = Date.now;
+        Date.now = () => mockTimeMs;
+
+        const clock = new Liepoch();
+        clock.stamp();
+        clock.stamp(); // internal is 1000, 1
+        
+        const remoteStamp = (1000n << 16n) | 5n; // Remote is at 1000ms, logical 5
+        const r2 = clock.receive(remoteStamp);
+        const unpackedR2 = Liepoch.unpack(r2);
+        
+        assert.equal(unpackedR2.time_ms, 1000);
+        assert.equal(unpackedR2.logical, 6, "Should take max(local, remote) logical + 1");
+        
+        Date.now = originalNow;
+    });
+
+    await t.test('Logical overflow protection', () => {
+        let mockTimeMs = 1000;
+        const originalNow = Date.now;
+        Date.now = () => mockTimeMs;
+
+        const clock = new Liepoch();
+        clock._setTestingState(1000n, 0xFFFFn); // set to max logical
+        
+        assert.throws(() => clock.stamp(), LiepochError, "Should throw on overflow");
+        
+        Date.now = originalNow;
+    });
+
+    await t.test('Max drift protection', () => {
+        let mockTimeMs = 1000;
+        const originalNow = Date.now;
+        Date.now = () => mockTimeMs;
+
+        const clock = new Liepoch();
+        clock.stamp();
+        
+        // Simulate local clock jumping back severely
+        clock._setTestingState(BigInt(mockTimeMs + 300000 + 10), 0n);
+        assert.throws(() => clock.stamp(), LiepochError, "Should throw on severe backward drift");
+
+        // Forward drift from remote
+        clock._setTestingState(1000n, 0n);
+        const farFuture = (BigInt(mockTimeMs + 300000 + 10) << 16n) | 0n;
+        assert.throws(() => clock.receive(farFuture), LiepochError, "Should throw on incoming severe forward drift");
+        
+        Date.now = originalNow;
+    });
+
+    await t.test('before() function handling', () => {
+        const b1 = (1000n << 16n) | 5n;
+        const b2 = (1000n << 16n) | 6n;
+        
+        assert.ok(before(b1, b2), "b1 before b2");
+        assert.ok(before(serialize(b1), serialize(b2)), "string serialization before works");
+        assert.ok(before("0x" + serialize(b1), serialize(b2)), "handles mixed prefixes safely");
+        assert.ok(!before("0x" + serialize(b2), serialize(b1)), "handles mixed prefixes correctly for false");
+    });
+
+    await t.test('Reject JS Numbers', () => {
+        const clock = new Liepoch();
+        // @ts-ignore
+        assert.throws(() => clock.receive(123), LiepochError, "Should reject JS Number");
+    });
+});

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "CommonJS",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "test"]
+}