@zakkster/lite-o1 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,120 @@ All notable changes to `@zakkster/lite-o1` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-09-15
+
+The third member of the O(1) family: a disjoint-set forest with near-O(1)
+amortized find / union -- the family's amortized-honesty member. Tree-shakeable
+alongside SparseSet and RingDeque (the three share no mutable module state).
+
+### Added
+
+- **`UnionFind(n)`** -- a zero-GC near-O(1) (amortized alpha(n)) disjoint-set
+  forest over TWO flat `Uint32Array` columns (parent + subtree size), fixed
+  element count `n` (elements are `[0, n)`):
+  - `find(x)` / `union(a, b)` / `connected(a, b)` / `componentSize(x)` -- all
+    O(1)-AMORTIZED, zero allocation after construction. `count` getter (live
+    component count, maintained in O(1) -- never scanned) and `capacity` getter
+    (the fixed universe `n`; there is deliberately NO `size` getter).
+  - PATH HALVING on `find` (iterative, no recursion / no stack array -- the tree
+    flattens as a side effect of querying it) + UNION BY SIZE (smaller root
+    attached under larger). `count` decrements EXACTLY once per real merge.
+  - `reset()` -- the HONEST O(n) exception: re-singleton every element in a single
+    bulk pass over the existing arrays (allocates nothing, but is O(n), NOT a
+    zero-alloc-per-op hot path; named `reset()`, not `clear()`, to flag the cost).
+  - `forEachRoots(fn)` -- an O(n) alloc-free full scan of the current roots
+    (documented exception, excluded from the zero-alloc-per-op claims). `roots()`
+    -- a convenience generator that ALLOCATES per protocol (like
+    `[Symbol.iterator]`), kept out of the zero-alloc claims.
+  - Ceiling: `n` in `[1, 2^32-1]`. Fail closed: a non-integer / out-of-range /
+    non-number `n` throws a `[lite-o1]` `RangeError`; a bad element to any op
+    throws `[lite-o1]` (typeof-guarded BEFORE the coercing `>>>`, so a Symbol /
+    BigInt never triggers a raw `TypeError`). `null` is not zero.
+- **`O1.d.ts`** -- UnionFind ambient types added.
+- **The O(1) Witness** (`test/witness.mjs`) -- a UnionFind amortized-find sweep
+  `[1e3, 1e4, 1e5]` vs a NAIVE disjoint-set foil (no path compression, no
+  union-by-size -> a degenerate chain, O(n) find); UnionFind flatness `>= 0.70`,
+  naive foil `<= 0.55`, ratio `>= 1.5x`.
+- **Torture gate** -- UnionFind find / union / connected / componentSize cycles at
+  0 B/op, 0 major GC, tracker size 0, arrayBuffers delta 0 (a `ufBpc` metric
+  alongside the SparseSet / RingDeque per-op figures).
+- **Perf gate** (`test/perf/PerfGate.test.mjs`) -- UnionFind find-heavy,
+  union-churn (real merges), connected, and componentSize scenarios at 0
+  scavenges / 0 old-gen / 0 arrayBuffers and a 0-delta grows-counter on the two
+  `Uint32Array` columns, plus a `roots()`-into-fresh-array must-fail teeth case.
+- **UnionFind `node:test` cases** -- contract + boundary (reject Symbol / BigInt /
+  NaN / null / undefined / -1 / n / 1.5; ctor rejects a bad n) + a path-halving
+  depth-shrink proof (test-only `_parent` peek) + a >= 1e5-op mixed
+  union/find/connected differential fuzz against a trivial no-compression /
+  no-union-by-size oracle (0 divergences; count exact once per true merge).
+- ADR [`0007`](./decisions/0007-unionfind-path-halving-union-by-size.md)
+  (path halving + union by size, the O(n) reset / forEachRoots honesty exception,
+  and the 2^32-1 ceiling).
+
+### Changed
+
+- `VERSION` bumped to `'0.3.0'` (synced across `package.json`, the `VERSION` const
+  in `O1.js`, and `llms.txt`).
+- **Witness gate hardened (internal, `test/witness.mjs` -- not part of the
+  published surface).** The SparseSet flatness gate flaked ~15-20% of fresh runs;
+  the cause was the flatness DENOMINATOR `n=1e3`, a pure-L1 micro-case that
+  turbo-spikes (40% spread), not any O(1) violation. Fix: the full `[1e3..1e7]`
+  sweep is still DISPLAYED (both the `1e3` micro-case and the `1e7` memory wall
+  tagged), but the flatness + ratio gates are now computed over the steady,
+  cache-resident window `1e4 <= n <= 1e6`; measurement stiffened to two warm-ups +
+  median of 9. The `0.70` / `0.55` / `1.5x` thresholds are UNCHANGED (domain, not
+  floor). 30 consecutive fresh runs, 0 failures (min flatness 0.90). See the
+  amendment to ADR [`0004`](./decisions/0004-witness-flatness-gate.md).
+
+[0.3.0]: https://www.npmjs.com/package/@zakkster/lite-o1/v/0.3.0
+
+## [0.2.0] - 2026-09-15
+
+The second member of the O(1) family: a fixed-capacity double-ended queue that
+kills the `Array.prototype.shift` O(n) trap. Tree-shakeable alongside SparseSet
+(the two share no mutable module state).
+
+### Added
+
+- **`RingDeque(capacity)`** -- a zero-GC O(1) fixed-capacity double-ended queue
+  over ONE `Float64Array` (numeric values only), head + count representation:
+  - `pushFront(v)` / `pushBack(v)` / `popFront()` / `popBack()` / `peekFront()` /
+    `peekBack()` / `clear()` / `forEach(fn)` / `[Symbol.iterator]` -- all O(1)
+    worst-case, zero allocation after construction. `size` and `capacity` getters.
+  - Capacity ROUNDS UP to the next power of two (`>= requested`); the ring wraps
+    by a single `& (capacity - 1)`. The `capacity` getter reports the rounded
+    value. Ceiling: 2^31 elements (a 16 GiB `Float64Array`).
+  - `clear()` is O(1): resets head + count and zeroes NO store (numbers retain no
+    references, so there is nothing to reclaim).
+  - Fail closed: push on a FULL ring throws a `[lite-o1]` error as a
+    byte-identical no-op; a non-clean value (non-number or NaN; `+/-Infinity`
+    accepted) throws `[lite-o1]` (typeof-guarded before any coercion, so a Symbol
+    / BigInt never triggers a raw `TypeError`). `pop*` / `peek*` on an EMPTY ring
+    return `undefined` and never throw.
+- **`O1.d.ts`** -- RingDeque ambient types added.
+- **The O(1) Witness** (`test/witness.mjs`) -- a RingDeque FIFO-churn sweep
+  `[1e3, 1e4, 1e5]` vs an `Array.prototype.shift` foil (O(n)); RingDeque flatness
+  `>= 0.70`, shift foil `<= 0.55`, ratio `>= 1.5x`.
+- **Torture gate** -- RingDeque fill/drain + both-ends interleave cycles at 0 B/op,
+  0 major GC, tracker size 0, arrayBuffers delta 0.
+- **Perf gate** (`test/perf/PerfGate.test.mjs`) -- RingDeque FIFO, LIFO, and
+  both-ends interleave scenarios at 0 scavenges / 0 old-gen / 0 arrayBuffers and a
+  0-delta grows-counter on the `Float64Array` backing.
+- **RingDeque `node:test` cases** -- contract + boundary + a 1,000,000-op
+  differential fuzz at both ends against a plain-`Array` reference deque (0
+  divergences; the full-throw and empty-undefined edges both exercised).
+- ADRs [`0005`](./decisions/0005-ring-capacity-fail-closed.md) (fixed power-of-two
+  capacity, fail closed on full) and
+  [`0006`](./decisions/0006-numeric-ring-substrate.md) (numeric Float64Array
+  substrate, undefined-on-empty, clear-untouched).
+
+### Changed
+
+- `VERSION` bumped to `'0.2.0'` (synced across `package.json`, the `VERSION` const
+  in `O1.js`, and `llms.txt`).
+
+[0.2.0]: https://www.npmjs.com/package/@zakkster/lite-o1/v/0.2.0
+
 ## [0.1.0] - 2026-09-15
 
 Initial release. The headline member of the O(1) family, plus the analytical

package/O1.d.ts

@@ -49,3 +49,100 @@ export class SparseSet {
     /** Iterate present keys in insertion order. */
     [Symbol.iterator](): IterableIterator<number>;
 }
+
+/**
+ * A zero-GC O(1) fixed-capacity double-ended queue over ONE Float64Array
+ * (numeric values only). pushFront / pushBack / popFront / popBack / peekFront /
+ * peekBack / clear / iterate are all O(1) worst-case and allocate nothing after
+ * construction. The requested capacity rounds UP to the next power of two, so the
+ * ring wraps by a single `& (capacity - 1)`. Fail closed: push* on a full deque
+ * or of a non-clean number (non-number or NaN; +/-Infinity accepted) throws a
+ * [lite-o1] error; pop* / peek* on an empty deque return `undefined` and never
+ * throw. `clear()` is O(1) and touches no store.
+ */
+export class RingDeque {
+    /**
+     * @param capacity  requested max elements; an integer in [1, 2^31]. Rounded
+     *                  UP to the next power of two.
+     */
+    constructor(capacity: number);
+
+    /** Number of live elements. */
+    readonly size: number;
+
+    /** Max elements this ring holds (power-of-two, rounded up from requested). */
+    readonly capacity: number;
+
+    /** Push v onto the front. Throws a [lite-o1] error when full or on a bad value. */
+    pushFront(v: number): this;
+
+    /** Push v onto the back. Throws a [lite-o1] error when full or on a bad value. */
+    pushBack(v: number): this;
+
+    /** Remove and return the front element, or `undefined` when empty. Never throws. */
+    popFront(): number | undefined;
+
+    /** Remove and return the back element, or `undefined` when empty. Never throws. */
+    popBack(): number | undefined;
+
+    /** Peek the front element, or `undefined` when empty. Never throws. */
+    peekFront(): number | undefined;
+
+    /** Peek the back element, or `undefined` when empty. Never throws. */
+    peekBack(): number | undefined;
+
+    /** Empty the deque in O(1) (resets head + count; zeroes no store). */
+    clear(): void;
+
+    /** Iterate live elements front -> back, alloc-free. */
+    forEach(fn: (value: number, index: number, deque: RingDeque) => void): void;
+
+    /** Iterate live elements front -> back. */
+    [Symbol.iterator](): IterableIterator<number>;
+}
+
+/**
+ * A zero-GC near-O(1) (amortized alpha(n)) disjoint-set forest over TWO
+ * Uint32Array columns (parent + subtree size), with a fixed element count `n`
+ * (elements are [0, n)). find / union / connected / componentSize are
+ * O(1)-amortized (path halving + union by size) and allocate nothing after
+ * construction. `count` is the live component count, maintained in O(1).
+ * `reset()` and `forEachRoots(fn)` are O(n) full-scan primitives (alloc-free but
+ * NOT per-op hot paths); `roots()` allocates a generator per protocol. Fail
+ * closed: a bad element (non-integer, NaN, null, negative, >= n, Symbol, BigInt)
+ * throws a [lite-o1] error.
+ */
+export class UnionFind {
+    /**
+     * @param n  fixed element count; an integer in [1, 2^32-1]. Elements are [0, n).
+     */
+    constructor(n: number);
+
+    /** Live component count (maintained in O(1); never scanned). */
+    readonly count: number;
+
+    /** Fixed element universe [0, n). (No `size` getter -- it would collide with
+     *  the live-count meaning `size` has on SparseSet / RingDeque.) */
+    readonly capacity: number;
+
+    /** Return the root of x's component. O(1)-amortized. Throws on a bad element. */
+    find(x: number): number;
+
+    /** Merge a and b. Returns true iff they were merged this call. Throws on a bad element. */
+    union(a: number, b: number): boolean;
+
+    /** True iff a and b share a component. O(1)-amortized. Throws on a bad element. */
+    connected(a: number, b: number): boolean;
+
+    /** Size of x's component. O(1)-amortized. Throws on a bad element. */
+    componentSize(x: number): number;
+
+    /** Re-singleton every element (O(n) bulk pass; allocates nothing). */
+    reset(): void;
+
+    /** Invoke fn for every current root, alloc-free (O(n) full scan). */
+    forEachRoots(fn: (root: number, uf: UnionFind) => void): void;
+
+    /** Yield every current root (O(n) scan; allocates a generator per protocol). */
+    roots(): IterableIterator<number>;
+}

package/O1.js

@@ -3,18 +3,20 @@
  * that doubles as a teachable textbook: each member solves a real problem AND
  * proves its constant is real (the O(1) Witness -- see test/witness.mjs).
  *
- * v0.1.0 ships the headline member, SparseSet, plus its `VERSION` const.
+ * v0.3.0 ships three members -- SparseSet, RingDeque, and UnionFind -- plus its
+ * `VERSION` const. The three are independent (no shared mutable module state), so
+ * a bundler that imports one drops the others (`sideEffects: false`).
  *
  * The complexity class IS the product: every hot op below is O(1) worst-case and
  * allocates ZERO bytes after construction. The witness harness (never imported
  * here) proves the throughput stays FLAT from n=1e3 to n=1e7 while a native Set
- * decays -- that flat line is the theorem made visible.
+ * (or Array.prototype.shift) decays -- that flat line is the theorem made visible.
  *
  * @license MIT
  */
 
 /** Package version. One of the three version sites (package.json / VERSION / llms.txt). */
-export const VERSION = '0.1.0';
+export const VERSION = '0.3.0';
 
 /** Largest universe the Uint32 substrate + the (k >>> 0) key check can honor. */
 const MAX_UNIVERSE = 0x100000000; // 2^32
@@ -146,3 +148,375 @@ export class SparseSet {
         throw new RangeError('[lite-o1] SparseSet full (capacity ' + this._cap + ')');
     }
 }
+
+/** Largest element count a Float64Array ring can honor (2^31 slots = 16 GiB). */
+const MAX_CAPACITY = 0x80000000; // 2^31
+
+/**
+ * Round `c` (an integer >= 1) UP to the next power of two >= c. Cold path only
+ * (constructor), so a plain doubling loop -- not a bit trick -- is used: `1 << 31`
+ * would overflow int32 to a negative, but `p *= 2` walks the double cleanly up to
+ * 2^31 in at most 31 steps.
+ * @param {number} c
+ * @returns {number}
+ */
+function _roundPow2(c) {
+    let p = 1;
+    while (p < c) p *= 2;
+    return p;
+}
+
+/**
+ * RingDeque -- a zero-GC O(1) fixed-capacity double-ended queue over ONE
+ * `Float64Array` (numeric values only).
+ *
+ * pushFront / pushBack / popFront / popBack / peekFront / peekBack / clear /
+ * iterate are ALL O(1) worst-case. The buffer is a CIRCULAR ring: the live window
+ * is described by `head` (the index of the front element) and `count` (how many
+ * are live). The physical slot for logical offset `i` from the front is:
+ *
+ *     store[(head + i) & MASK]
+ *
+ * `MASK = capacity - 1`, and `capacity` is a power of two, so the modulo that
+ * wraps the index is a single `& MASK` -- no branch, no division. The requested
+ * capacity ROUNDS UP to the next power of two (>= requested), and the `capacity`
+ * getter reports that rounded value. A pushFront off slot 0 wraps to the top via
+ * `(head - 1) & MASK` (int32 `-1 & MASK === MASK`).
+ *
+ * Fail closed, mirroring SparseSet's discipline exactly:
+ *   - push* on a FULL deque THROWS a [lite-o1] error, as a byte-identical no-op
+ *     (store + head + count unchanged -- the throw precedes every write). Cold path.
+ *   - push* of a value that is not a CLEAN number THROWS [lite-o1]. Rejected:
+ *     `typeof v !== 'number'` (null, undefined, string, Symbol, BigInt, object)
+ *     AND NaN (`v !== v`). The typeof guard runs FIRST so a Symbol / BigInt never
+ *     reaches arithmetic (`+`/`>>>`/template literals THROW a raw TypeError on
+ *     those -- the recurring cross-package footgun); the cold builder names the
+ *     value via `String(v)`, which is Symbol/BigInt-safe. +Infinity / -Infinity
+ *     are CLEAN numbers (typeof number, not NaN) and are ACCEPTED.
+ *   - pop* / peek* on an EMPTY deque return `undefined`, NEVER throw (mirrors
+ *     has()'s never-throw query contract). The sentinel is unambiguous because
+ *     every stored value is a real number, never `undefined`.
+ *
+ * clear() is O(1) and touches NOTHING: `head = 0; count = 0`. The stale numbers
+ * left in the store are unreachable (every read is bounded by `count`), and being
+ * numbers they retain no references -- so there is no retention risk and no reason
+ * to zero the buffer (mirrors SparseSet.clear()).
+ *
+ * NOTE: a RingLog / overwrite-oldest preset (pushBack that evicts the front when
+ * full instead of throwing) is a DEFERRED future variant -- see decisions/0005.
+ */
+export class RingDeque {
+    /**
+     * @param {number} capacity  requested max elements; an integer in [1, 2^31].
+     *                           Rounded UP to the next power of two.
+     */
+    constructor(capacity) {
+        // typeof guard BEFORE any coercion: Number.isInteger never coerces (false
+        // on a Symbol/BigInt), and String(x) in the cold message is Symbol-safe.
+        if (typeof capacity !== 'number' || !Number.isInteger(capacity) ||
+            capacity < 1 || capacity > MAX_CAPACITY) {
+            throw new RangeError(
+                '[lite-o1] RingDeque capacity must be an integer in [1, 2^31], got ' + String(capacity));
+        }
+        const cap = _roundPow2(capacity);
+        this._store = new Float64Array(cap); // the ring buffer (numeric slots)
+        this._cap = cap;                     // power-of-two capacity (rounded)
+        this._mask = cap - 1;                // wrap mask: (i & MASK) is the physical slot
+        this._head = 0;                      // index of the front element
+        this._count = 0;                     // number of live elements
+    }
+
+    /** Number of live elements. O(1). */
+    get size() { return this._count; }
+
+    /** Max elements this ring can hold (power-of-two, rounded up from requested). O(1). */
+    get capacity() { return this._cap; }
+
+    /**
+     * Push v onto the FRONT. O(1). Fails closed: a non-clean value throws via
+     * _bad; a full deque throws via _full (byte-identical no-op). Guard typeof
+     * FIRST so a Symbol / BigInt never reaches the arithmetic below.
+     * @param {number} v  a clean number (not NaN; +/-Infinity accepted)
+     * @returns {RingDeque} this
+     */
+    pushFront(v) {
+        if (typeof v !== 'number' || v !== v) return this._bad(v); // v !== v -> NaN
+        if (this._count === this._cap) return this._full();
+        const h = (this._head - 1) & this._mask; // -1 & MASK wraps to the top slot
+        this._store[h] = v;
+        this._head = h;
+        this._count++;
+        return this;
+    }
+
+    /**
+     * Push v onto the BACK. O(1). Fail-closed identical to pushFront.
+     * @param {number} v  a clean number (not NaN; +/-Infinity accepted)
+     * @returns {RingDeque} this
+     */
+    pushBack(v) {
+        if (typeof v !== 'number' || v !== v) return this._bad(v); // v !== v -> NaN
+        if (this._count === this._cap) return this._full();
+        this._store[(this._head + this._count) & this._mask] = v;
+        this._count++;
+        return this;
+    }
+
+    /**
+     * Remove and return the FRONT element. O(1). Returns `undefined` on an empty
+     * deque (never throws) -- unambiguous because every stored value is a number.
+     * @returns {number|undefined}
+     */
+    popFront() {
+        if (this._count === 0) return undefined;
+        const v = this._store[this._head];
+        this._head = (this._head + 1) & this._mask;
+        this._count--;
+        return v;
+    }
+
+    /**
+     * Remove and return the BACK element. O(1). Returns `undefined` on empty.
+     * @returns {number|undefined}
+     */
+    popBack() {
+        if (this._count === 0) return undefined;
+        this._count--;
+        return this._store[(this._head + this._count) & this._mask];
+    }
+
+    /** Peek the FRONT element without removing it. O(1). `undefined` on empty. */
+    peekFront() {
+        if (this._count === 0) return undefined;
+        return this._store[this._head];
+    }
+
+    /** Peek the BACK element without removing it. O(1). `undefined` on empty. */
+    peekBack() {
+        if (this._count === 0) return undefined;
+        return this._store[(this._head + this._count - 1) & this._mask];
+    }
+
+    /**
+     * Empty the deque in O(1). Resets head + count only -- the store is left
+     * UNTOUCHED. The stale numbers are unreachable (reads are bounded by count)
+     * and retain no references, so there is nothing to zero (mirrors SparseSet).
+     */
+    clear() { this._head = 0; this._count = 0; }
+
+    /**
+     * Iterate live elements FRONT -> BACK, alloc-free. O(size). A HOISTED callback
+     * makes this a zero-allocation drain.
+     * @param {(value:number, index:number, deque:RingDeque)=>void} fn
+     */
+    forEach(fn) {
+        const store = this._store;
+        const mask = this._mask;
+        const head = this._head;
+        const count = this._count;
+        for (let i = 0; i < count; i++) fn(store[(head + i) & mask], i, this);
+    }
+
+    /** Iterate live elements FRONT -> BACK. O(size). */
+    *[Symbol.iterator]() {
+        const store = this._store;
+        const mask = this._mask;
+        const head = this._head;
+        const count = this._count;
+        for (let i = 0; i < count; i++) yield store[(head + i) & mask];
+    }
+
+    // ---- cold path only: throw builders (string concat lives here, off the hot body) ----
+
+    /** @private */
+    _bad(v) {
+        // String(v) -- NOT '+ v' / a template literal: those THROW on a Symbol or
+        // BigInt, which would turn a fail-closed reject into a different crash.
+        throw new TypeError(
+            '[lite-o1] RingDeque value must be a number and not NaN, got ' + String(v));
+    }
+
+    /** @private */
+    _full() {
+        throw new RangeError('[lite-o1] RingDeque full (capacity ' + this._cap + ')');
+    }
+}
+
+/**
+ * Largest disjoint-set universe UnionFind can honor. Every parent / root index
+ * is stored in a Uint32Array slot, so an element must fit a uint32; the fixed
+ * count `n` is an integer in [1, 2^32-1] (0xFFFFFFFF), leaving every legal
+ * element in [0, n) inside the uint32 range.
+ */
+const MAX_NODES = 0xFFFFFFFF; // 2^32 - 1
+
+/**
+ * UnionFind -- a zero-GC near-O(1) disjoint-set forest over TWO flat
+ * `Uint32Array` columns (parent + subtree size), with a fixed element count `n`.
+ *
+ * find / union / connected / componentSize are ALL O(1)-AMORTIZED (inverse
+ * Ackermann alpha(n) <= 4 for any n that fits this universe -- effectively a
+ * small constant) and allocate ZERO bytes after construction. The two classic
+ * near-constant tricks are both applied:
+ *
+ *   - PATH HALVING on find: every other node on the walk to the root is
+ *     re-pointed at its grandparent (`parent[x] = parent[parent[x]]`), so the
+ *     tree flattens as a side effect of querying it -- iterative, NO recursion
+ *     and NO stack array, so the hot body allocates nothing.
+ *   - UNION BY SIZE: the smaller-rooted tree is attached under the larger, so
+ *     the forest never grows taller than log n before halving flattens it.
+ *
+ * Together these bound any single op at O(alpha(n)) amortized. HONESTY: a single
+ * find is NOT worst-case O(1) -- an adversarial pre-halving chain is O(depth);
+ * the guarantee is amortized. The witness reports the amortized throughput
+ * staying flat while a no-compression / no-union-by-size foil degrades.
+ *
+ * Elements are [0, n); `count` is the live component count, maintained in O(1)
+ * (decremented once per real merge -- NO scan). Fail closed, mirroring the other
+ * members: a non-integer / out-of-range / non-number element throws a
+ * [lite-o1]-tagged error via _oob (typeof-guarded BEFORE the coercing `>>>`, so a
+ * Symbol / BigInt never reaches arithmetic). `null` is not zero --
+ * `(null >>> 0) === null` is false, so null is rejected.
+ *
+ * `reset()` and `forEachRoots(fn)` are the documented O(n) full-scan exceptions
+ * (a single bulk pass over the existing arrays -- they still allocate NOTHING but
+ * are NOT per-op hot paths); `roots()` is a convenience generator that ALLOCATES
+ * per protocol (like `[Symbol.iterator]`) and is kept OUT of the zero-alloc claim.
+ */
+export class UnionFind {
+    /**
+     * @param {number} n  fixed element count; an integer in [1, 2^32-1].
+     *                    Elements are [0, n).
+     */
+    constructor(n) {
+        // Number.isInteger never coerces (false on a Symbol / BigInt), and
+        // String(n) in the cold message is Symbol/BigInt-safe -- so a bad type
+        // fails closed with a [lite-o1] error, never a raw TypeError.
+        if (!Number.isInteger(n) || n < 1 || n > MAX_NODES) {
+            throw new RangeError(
+                '[lite-o1] UnionFind n must be an integer in [1, 2^32-1], got ' + String(n));
+        }
+        const parent = new Uint32Array(n); // parent[i] = i's parent (i itself iff root)
+        for (let i = 0; i < n; i++) parent[i] = i;
+        this._parent = parent;
+        this._size = new Uint32Array(n).fill(1); // size[root] = elements in that tree
+        this._count = n;                          // live component count (O(1)-maintained)
+        this._n = n;                              // fixed universe (the capacity getter)
+    }
+
+    /** Live component count. O(1) -- maintained, never scanned. */
+    get count() { return this._count; }
+
+    /** Fixed element universe [0, n). O(1). (No `size` getter -- would collide
+     *  with the "live element count" meaning the other members give `size`.) */
+    get capacity() { return this._n; }
+
+    /**
+     * Return the root of x's component. O(1)-AMORTIZED. Path-halving flattens the
+     * walk in place (no recursion, no stack array -- zero allocation). Fails
+     * closed: a bad element throws via _oob. The `typeof` short-circuits BEFORE
+     * `>>>` runs, because `>>>` coerces its operand first and that coercion THROWS
+     * on a Symbol or BigInt; `(x >>> 0) !== x` then rejects every non-uint32
+     * number, and `x >= n` rejects an in-range uint32 past the universe.
+     * @param {number} x
+     * @returns {number} the component root
+     */
+    find(x) {
+        if (typeof x !== 'number' || (x >>> 0) !== x || x >= this._n) return this._oob(x);
+        const parent = this._parent;
+        while (parent[x] !== x) {
+            parent[x] = parent[parent[x]]; // path halving: point x at its grandparent
+            x = parent[x];
+        }
+        return x;
+    }
+
+    /**
+     * Merge the components of a and b. O(1)-AMORTIZED. Returns `true` iff a real
+     * merge happened (they were in different components), `false` if already
+     * joined. Union by size: the smaller-rooted tree is attached under the larger.
+     * Fails closed on either bad element (typeof-guarded before any coercion).
+     * @param {number} a
+     * @param {number} b
+     * @returns {boolean} true iff a and b were merged this call
+     */
+    union(a, b) {
+        if (typeof a !== 'number' || (a >>> 0) !== a || a >= this._n) return this._oob(a);
+        if (typeof b !== 'number' || (b >>> 0) !== b || b >= this._n) return this._oob(b);
+        let ra = this.find(a);
+        let rb = this.find(b);
+        if (ra === rb) return false;
+        const size = this._size;
+        if (size[ra] < size[rb]) { const t = ra; ra = rb; rb = t; } // attach smaller under larger
+        this._parent[rb] = ra;
+        size[ra] += size[rb];
+        this._count--; // exactly one component disappears per real merge
+        return true;
+    }
+
+    /**
+     * True iff a and b are in the same component. O(1)-AMORTIZED. Both elements
+     * are guarded via find (a bad element throws [lite-o1]).
+     * @param {number} a
+     * @param {number} b
+     * @returns {boolean}
+     */
+    connected(a, b) {
+        return this.find(a) === this.find(b);
+    }
+
+    /**
+     * Size of the component containing x. O(1)-AMORTIZED. x is guarded via find.
+     * @param {number} x
+     * @returns {number}
+     */
+    componentSize(x) {
+        return this._size[this.find(x)];
+    }
+
+    /**
+     * Re-singleton every element: parent[i] = i, size[i] = 1, count = n. This is
+     * the HONEST O(n) exception -- a single bulk pass over the existing arrays. It
+     * allocates NOTHING (no new store), but it is O(n), NOT a zero-alloc-per-op
+     * hot path; named reset() (not clear()) to flag that cost.
+     */
+    reset() {
+        const parent = this._parent;
+        const size = this._size;
+        const n = this._n;
+        for (let i = 0; i < n; i++) { parent[i] = i; size[i] = 1; }
+        this._count = n;
+    }
+
+    /**
+     * Invoke fn(root, uf) for every current root, alloc-free. O(n) FULL SCAN --
+     * a documented exception, EXCLUDED from the zero-alloc-per-op claims (it is a
+     * bulk primitive, not a hot op). A HOISTED callback keeps it allocation-free.
+     * @param {(root:number, uf:UnionFind)=>void} fn
+     */
+    forEachRoots(fn) {
+        const parent = this._parent;
+        const n = this._n;
+        for (let i = 0; i < n; i++) if (parent[i] === i) fn(i, this);
+    }
+
+    /**
+     * Yield every current root. O(n) scan. ALLOCATES a generator + a {value,done}
+     * object per step by protocol -- kept OUT of the zero-alloc claims (use
+     * forEachRoots for the alloc-free scan).
+     */
+    *roots() {
+        const parent = this._parent;
+        const n = this._n;
+        for (let i = 0; i < n; i++) if (parent[i] === i) yield i;
+    }
+
+    // ---- cold path only: throw builder (string concat lives here, off the hot body) ----
+
+    /** @private */
+    _oob(x) {
+        // String(x) -- NOT '+ x' / a template literal: those THROW on a Symbol or
+        // BigInt, which would turn a fail-closed reject into a different crash.
+        throw new RangeError('[lite-o1] node out of range [0, ' + this._n + '): ' + String(x));
+    }
+}

package/README.md

@@ -1,12 +1,14 @@
 # @zakkster/lite-o1
 
-> Zero-GC, O(1) data structures that PROVE their constant. v0.1.0 ships SparseSet: an integer set with O(1) add / has / delete / iterate and an O(1) clear() that zeroes nothing -- plus a throughput-invariance witness that shows the flat cost curve while a native Set decays.
+> Zero-GC, O(1) data structures that PROVE their constant. v0.3.0 ships SparseSet (an integer set with O(1) add / has / delete / iterate and an O(1) clear() that zeroes nothing), RingDeque (a fixed-capacity numeric double-ended queue with O(1) push/pop at both ends), and UnionFind (a disjoint-set forest with near-O(1) amortized find / union) -- plus a throughput-invariance witness that shows the flat cost curve while a native Set, Array.prototype.shift, or a naive disjoint-set decays.
 
 [![npm version](https://img.shields.io/npm/v/@zakkster/lite-o1.svg?style=for-the-badge&color=latest)](https://www.npmjs.com/package/@zakkster/lite-o1)
 [![sponsor](https://img.shields.io/badge/sponsor-PeshoVurtoleta-ea4aaa.svg?logo=github)](https://github.com/sponsors/PeshoVurtoleta)
 ![Zero-GC](https://img.shields.io/badge/Zero--GC-Engine-00C853?style=for-the-badge&logo=leaf&logoColor=white)
 [![npm bundle size](https://img.shields.io/bundlephobia/minzip/@zakkster/lite-o1?style=for-the-badge)](https://bundlephobia.com/result?p=@zakkster/lite-o1)
 [![npm downloads](https://img.shields.io/npm/dm/@zakkster/lite-o1?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-o1)
+[![npm total downloads](https://img.shields.io/npm/dt/@zakkster/lite-o1?style=for-the-badge&color=blue)](https://www.npmjs.com/package/@zakkster/lite-o1)
+![Tree-Shakeable](https://img.shields.io/badge/tree--shakeable-yes-brightgreen)
 ![TypeScript](https://img.shields.io/badge/TypeScript-Types-informational)
 ![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
 [![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](./LICENSE)
@@ -15,7 +17,7 @@
 
 Almost no JavaScript data-structure library ships the evidence that its Big-O claim survives contact with a real engine -- megamorphic call sites, GC pauses, cache misses, deopts. `lite-o1` is a curated, tree-shakeable family of the O(1) structures that actually matter, each zero-GC, each written to teach the trick that buys the constant, and each shipped with a harness that DEMONSTRATES the flat cost curve rather than asserting it. The complexity class IS the product.
 
-v0.1.0 is the headline member: **SparseSet**, the textbook O(1) integer set (a dense + sparse array pair) whose `clear()` runs in O(1) by resetting a count and zeroing nothing at all.
+v0.3.0 ships three members. **SparseSet**, the textbook O(1) integer set (a dense + sparse array pair) whose `clear()` runs in O(1) by resetting a count and zeroing nothing at all. **RingDeque**, a fixed-capacity double-ended queue of numbers over one circular `Float64Array` -- O(1) push/pop at both ends, the zero-GC answer to the `Array.prototype.shift` O(n) trap. And **UnionFind**, a disjoint-set forest over two `Uint32Array` columns -- near-O(1) amortized `find` / `union` via path halving + union by size, the family's amortized-honesty member. They share no mutable module state, so a bundler that imports one drops the others.
 
 ```bash
 npm install @zakkster/lite-o1
@@ -57,6 +59,12 @@ Every op above is O(1) worst-case and allocates zero bytes after construction. T
   - [SparseSet](#sparseset)
   - [Constants](#constants)
 - [The O(1) Witness](#the-o1-witness)
+- [RingDeque](#ringdeque)
+  - [How RingDeque works](#how-ringdeque-works)
+  - [RingDeque API reference](#ringdeque-api-reference)
+- [UnionFind](#unionfind)
+  - [How UnionFind works](#how-unionfind-works)
+  - [UnionFind API reference](#unionfind-api-reference)
 - [Composability with the ecosystem](#composability-with-the-ecosystem)
 - [Zero-GC design notes](#zero-gc-design-notes)
 - [Design decisions worth knowing](#design-decisions-worth-knowing)
@@ -88,8 +96,22 @@ Existing options: a native `Set` (arbitrary keys, but a hash table that decays a
   - **`clear()`** -- empty in O(1): resets the live count, zeroes no store.
   - **`forEach(fn)` / `[Symbol.iterator]`** -- iterate present keys in insertion order, alloc-free.
   - **`size` / `capacity`** -- getters.
+- **`RingDeque(capacity)`** -- a zero-GC O(1) fixed-capacity double-ended queue of numbers over one circular `Float64Array`. Capacity rounds up to the next power of two. The hot surface is eight ops plus two getters:
+  - **`pushFront(v)` / `pushBack(v)`** -- push at either end. O(1). Throw a `[lite-o1]` error when full (a byte-identical no-op) or on a non-clean value.
+  - **`popFront()` / `popBack()`** -- remove + return from either end. O(1). Return `undefined` on empty -- never a throw.
+  - **`peekFront()` / `peekBack()`** -- read either end without removing. O(1). `undefined` on empty.
+  - **`clear()`** -- empty in O(1): resets head + count, zeroes no store.
+  - **`forEach(fn)` / `[Symbol.iterator]`** -- iterate live elements front -> back, alloc-free.
+  - **`size` / `capacity`** -- getters (`capacity` reports the rounded power of two).
+- **`UnionFind(n)`** -- a zero-GC near-O(1) (amortized alpha(n)) disjoint-set forest over two `Uint32Array` columns (parent + subtree size), fixed element count `n` (elements are `[0, n)`). The hot surface is four ops plus two getters and two O(n) scan primitives:
+  - **`find(x)`** -- the root of x's component. O(1)-amortized. Path halving flattens the walk in place. Throws a `[lite-o1]` error on a bad element.
+  - **`union(a, b)`** -- merge two components (union by size). O(1)-amortized. Returns `true` iff a real merge happened.
+  - **`connected(a, b)` / `componentSize(x)`** -- same-component test / component size. O(1)-amortized.
+  - **`count` / `capacity`** -- getters (`count` is the live component count, maintained in O(1); `capacity` is the fixed `n`).
+  - **`reset()`** -- re-singleton every element. O(n) (the honest exception; allocates nothing, but is a bulk op, not a per-op hot path).
+  - **`forEachRoots(fn)` / `roots()`** -- visit the current roots; `forEachRoots` is an O(n) alloc-free scan, `roots()` is an allocating generator.
 - **`VERSION`** -- the package version string.
-- **The O(1) Witness** (`npm run witness`) -- an offline harness that times a fixed batch of the membership op across an n-sweep, reports ops/ms + a flatness ratio for SparseSet against a native `Set` foil, and fails if the constant regressed.
+- **The O(1) Witness** (`npm run witness`) -- an offline harness that times a fixed batch of each member's hot op across an n-sweep, reports ops/ms + a flatness ratio (SparseSet vs a native `Set`, RingDeque vs `Array.prototype.shift`, UnionFind vs a naive disjoint-set), and fails if the constant regressed.
 
 Full types ship in [`O1.d.ts`](./O1.d.ts). Tree-shakeable named exports (`sideEffects: false`) -- import only what you use.
 
@@ -156,34 +178,219 @@ get capacity: number        // max live members as constructed
 
 | Constant   | Value     | Meaning                                            |
 | ---------- | --------- | -------------------------------------------------- |
-| `VERSION`  | `'0.1.0'` | Package version string.                            |
+| `VERSION`  | `'0.3.0'` | Package version string.                            |
 
 Contract bounds (validated, not exported):
 
-| Bound      | Rule                                             |
-| ---------- | ------------------------------------------------ |
-| `universe` | integer in `[1, 2^32]`                           |
-| `capacity` | integer in `[1, universe]`, default `universe`   |
-| valid key  | integer in `[0, universe)`                       |
+| Bound               | Rule                                             |
+| ------------------- | ------------------------------------------------ |
+| SparseSet `universe`| integer in `[1, 2^32]`                           |
+| SparseSet `capacity`| integer in `[1, universe]`, default `universe`   |
+| SparseSet valid key | integer in `[0, universe)`                       |
+| RingDeque `capacity`| integer in `[1, 2^31]`, rounded up to a power of two |
+| RingDeque value     | `typeof 'number'` and not `NaN` (`+/-Infinity` OK) |
+| UnionFind `n`       | integer in `[1, 2^32-1]`                          |
+| UnionFind element   | integer in `[0, n)`                               |
 
 ---
 
 ## The O(1) Witness
 
-The analytical anchor: **ops/ms that stays flat as n grows is the proof of O(1).** `npm run witness` fills a SparseSet of size `n` and times a fixed batch (1e6) of the membership op at each `n` in a geometric sweep `[1e3, 1e4, 1e5, 1e6, 1e7]`, with a warm-up and the median of 5 reps to reject a loaded-runner stall. It runs a native `Set` foil on the identical key sweep -- the thing a working programmer reaches for by default -- and reports both curves plus a flatness ratio (`opsPerMs(n_max) / opsPerMs(n_min)`):
+The analytical anchor: **ops/ms that stays flat as n grows is the proof of O(1).** `npm run witness` fills a SparseSet of size `n` and times a fixed batch (1e6) of the membership op at each `n` in a geometric sweep `[1e3, 1e4, 1e5, 1e6, 1e7]`, with two warm-ups and the median of 9 reps to reject a loaded-runner stall. It runs a native `Set` foil on the identical key sweep -- the thing a working programmer reaches for by default -- and reports both curves plus a flatness ratio (`opsPerMs(last) / opsPerMs(first)`):
 
 ```
   n         SparseSet ops/ms   Set ops/ms   ratio
   --------  ----------------   ----------   -----
-  1e3             ~552753.40    ~178964.22   ~3.09x
-  1e7             ~443852.64     ~15834.00  ~28.03x
+  1e3             ~378483.23    ~169062.91   ~2.24x   <- L1 micro-case (shown, not gated)
+  1e4             ~401472.12    ~114038.09   ~3.52x
+  1e6             ~404626.17     ~44210.86   ~9.15x
+  1e7             ~402030.25     ~19032.79  ~21.12x   <- memory wall (shown, not gated)
+
+  SparseSet flatness (n=1e4..1e6):  ~1.00   (gate >= 0.70)
+  Set foil  flatness (n=1e4..1e6):  ~0.39   (gate <= 0.55)
+  min SparseSet/Set ratio (n=1e4..1e6): ~3.5x   (gate >= 1.50x)
+```
+
+SparseSet's contiguous typed-array layout streams flat -- its ops/ms barely moves from n=1e3 to n=1e7 -- while the `Set`'s hash table scatters across an ever-larger backing store until each lookup is a cache miss, so its ops/ms falls ~9x across the sweep and SparseSet's lead *grows* with n (2x to 21x). **Honest gate domain:** ops/ms is a hardware signal, so the two unrepresentative endpoints are displayed but excluded from the gate -- n=1e3 is a pure-L1 micro-case that turbo-spikes (an unstable flatness denominator), and n=1e7 is the memory wall, where the 8*n-byte arrays exceed cache and you measure DRAM latency rather than the algorithm. The gate is computed over the steady, cache-resident window `1e4 <= n <= 1e6` and fails the build if SparseSet flatness drops below `0.70`, the foil fails to decay below `0.55`, or the ratio falls under `1.5x` at any gated size -- so a regression that quietly ruins the constant fails as loudly as a broken test. (Absolute ops/ms is machine-specific; reproduce on your own hardware.)
+
+---
+
+## RingDeque
+
+The second member: a **fixed-capacity double-ended queue of numbers** over one circular `Float64Array`. Push and pop at BOTH ends are O(1) worst-case and allocate zero bytes -- the zero-GC answer to the `Array.prototype.shift` / `unshift` O(n) trap, where every element re-indexes on each end operation.
+
+```js
+import { RingDeque } from '@zakkster/lite-o1';
+
+// Requested 1000 -> capacity rounds UP to the next power of two (1024).
+const q = new RingDeque(1000);
+q.capacity;              // -> 1024
+
+q.pushBack(1);
+q.pushBack(2);
+q.pushFront(0);         // [0, 1, 2]
+
+q.peekFront();          // -> 0
+q.peekBack();           // -> 2
+
+q.popFront();           // -> 0  (FIFO with pushBack)
+q.popBack();            // -> 2  (LIFO with pushBack)
+q.size;                 // -> 1
+
+for (const v of q) console.log(v);   // 1   (front -> back, alloc-free)
+
+q.pushBack(Infinity);   // OK: +/-Infinity are clean numbers
+// q.pushBack(NaN);     // throws [lite-o1]: NaN is rejected
+// q.pushBack('3');     // throws [lite-o1]: not a number
+
+q.clear();              // O(1): resets head + count, touches NO store
+q.popFront();           // -> undefined  (empty never throws)
+```
+
+Every op is O(1) worst-case and zero-allocation after construction. `pop*` / `peek*` on an empty ring return `undefined` (never throw); the sentinel is unambiguous because every stored value is a real number. A push on a full ring throws a `[lite-o1]` error as a byte-identical no-op -- fail closed, no silent drop or overwrite. The `witness` harness proves RingDeque's FIFO churn holds its ops/ms while `Array.prototype.shift` collapses as `n` grows.
+
+### How RingDeque works
+
+<details>
+<summary>The circular buffer, head + count, and why clear() is free.</summary>
+
+A RingDeque holds one `Float64Array` (the ring), a `head` (the index of the front element), and a `count` (how many elements are live). The physical slot for logical offset `i` from the front is:
+
+```
+store[(head + i) & MASK]      MASK = capacity - 1
+```
+
+Because `capacity` is a power of two, the modulo that wraps the index is a single bitwise `& MASK` -- no branch, no division. The requested capacity rounds UP to the next power of two (so `new RingDeque(1000)` gives capacity 1024), and the `capacity` getter reports that rounded value.
+
+- **`pushBack(v)`** writes `store[(head + count) & MASK] = v; count++`.
+- **`pushFront(v)`** moves the head back one slot (`head = (head - 1) & MASK`, where int32 `-1 & MASK === MASK` wraps off slot 0 to the top), writes `store[head] = v`, then `count++`.
+- **`popFront()`** reads `store[head]`, advances `head = (head + 1) & MASK`, `count--`.
+- **`popBack()`** does `count--` and reads `store[(head + count) & MASK]`.
+
+Using **head + count** (not a head/tail pair) makes "full" a single test (`count === capacity`) and "empty" a single test (`count === 0`), with no ambiguous `head === tail` state to disambiguate.
+
+- **`clear()`** is `head = 0; count = 0`. The store is left byte-identical. The stale numbers are unreachable (every read is bounded by `count`) and retain no references (they are numbers), so there is nothing to zero -- clearing a full ring costs the same as clearing an empty one. This is the same teachable gem as SparseSet's cross-checked clear.
+
+The cost of the constant is the value domain: a `Float64Array` holds numbers only. To queue objects, queue their integer handles / indices and keep the payloads in a parallel column or `@zakkster/lite-arena`.
+
+</details>
+
+### RingDeque API reference
+
+```ts
+new RingDeque(capacity: number)   // capacity rounds up to the next power of two
+```
+
+- **`capacity`** -- the requested maximum number of live elements; an integer in `[1, 2^31]`. Rounded UP to the next power of two (`>= requested`); the `capacity` getter reports the rounded value. The constructor throws a `[lite-o1]`-tagged `RangeError` on a non-integer, out-of-range, or non-number argument (typeof-guarded before any coercion, so a Symbol / BigInt fails closed rather than crashing raw).
 
-  SparseSet flatness (last/first):  ~0.80   (gate >= 0.70)
-  Set foil  flatness (last/first):  ~0.09   (gate <= 0.55)
-  min SparseSet/Set ratio:          ~3.09x  (gate >= 1.50x)
+```ts
+pushFront(v: number): this        // push at the front; throws when full / on a bad value
+pushBack(v: number): this         // push at the back;  throws when full / on a bad value
+popFront(): number | undefined    // remove + return the front; undefined on empty
+popBack(): number | undefined     // remove + return the back;  undefined on empty
+peekFront(): number | undefined   // read the front; undefined on empty
+peekBack(): number | undefined    // read the back;  undefined on empty
+clear(): void                     // O(1) empty; zeroes no store
+forEach(fn: (value: number, index: number, deque: RingDeque) => void): void  // front -> back
+[Symbol.iterator](): IterableIterator<number>                                 // front -> back
+get size: number                  // live element count
+get capacity: number              // max elements (power-of-two, rounded up)
 ```
 
-SparseSet's contiguous typed-array layout streams flat; the `Set`'s hash table scatters across an ever-larger backing store until each lookup is a cache miss, so its ops/ms falls ~11x across the sweep. The gate fails the build if SparseSet flatness drops below `0.70`, the foil fails to decay below `0.55`, or the ratio falls under `1.5x` at any size -- so a regression that quietly ruins the constant fails as loudly as a broken test. (Absolute ops/ms is machine-specific; reproduce on your own hardware.)
+- **`pushFront(v)` / `pushBack(v)`** throw `[lite-o1] RingDeque full ...` when the ring is at capacity (a byte-identical no-op -- store + head + count unchanged), and `[lite-o1] RingDeque value must be a number ...` on a value that is not a clean number. A value is clean iff `typeof v === 'number'` AND it is not `NaN`; `+Infinity` / `-Infinity` are accepted, while `null`, `undefined`, strings, Symbols, BigInts, objects, and `NaN` are rejected. The `typeof` guard runs first so a Symbol / BigInt never reaches arithmetic.
+- **`popFront()` / `popBack()` / `peekFront()` / `peekBack()`** never throw: an empty ring returns `undefined`. Because every stored value is a real number, `undefined` unambiguously means "empty".
+
+**Reach for RingDeque when** you need FIFO / LIFO / sliding-window push-pop at O(1) with zero per-op allocation over a bounded numeric domain (ring buffers, bounded work queues, rolling windows). **Avoid it when** you need to queue non-numbers (queue their handles instead), or need the queue to grow past a bound you cannot set up front (it fails closed on a full push rather than resizing). See [`GUIDE.md`](./GUIDE.md) for the full reach-for / avoid / measure-it.
+
+---
+
+## UnionFind
+
+The third member: a **disjoint-set (union-find) forest** over two `Uint32Array` columns (parent + subtree size), fixed element count `n`. `find` / `union` / `connected` / `componentSize` are near-O(1) **amortized** (inverse Ackermann alpha(n) <= ~4) and allocate zero bytes -- the family's amortized-honesty member, and the zero-GC answer to a naive disjoint-set whose `find` degrades to O(n) as its trees deepen.
+
+```js
+import { UnionFind } from '@zakkster/lite-o1';
+
+// A forest of 10 singletons: elements 0..9, each its own component.
+const uf = new UnionFind(10);
+uf.count;               // -> 10  (live component count, maintained in O(1))
+uf.capacity;            // -> 10  (the fixed universe n)
+
+uf.union(0, 1);         // -> true  (a real merge)
+uf.union(1, 2);         // -> true  (2 joins {0,1})
+uf.union(0, 2);         // -> false (already connected -- no-op)
+uf.count;               // -> 8
+
+uf.connected(0, 2);     // -> true
+uf.connected(0, 5);     // -> false
+uf.componentSize(1);    // -> 3   ({0,1,2})
+uf.find(2);             // -> the component root (path-halved on the way)
+
+// uf.find(10);         // throws [lite-o1]: element out of [0, 10)
+// uf.find(1.5);        // throws [lite-o1]: not an integer element
+// uf.union(0, Symbol());// throws [lite-o1]: fail-closed, never a raw TypeError
+
+uf.reset();             // O(n): re-singleton every element (the honest exception)
+uf.count;               // -> 10
+```
+
+Every query / merge above is O(1)-amortized and zero-allocation after construction. Fail closed: a bad element (non-integer, out of `[0, n)`, `NaN`, `null`, a Symbol, a BigInt) throws a `[lite-o1]` error -- never a raw `TypeError`, and `null` is never coerced to element `0`. The `witness` harness proves UnionFind's amortized `find` holds its ops/ms while a naive disjoint-set (no path compression, no union-by-size) collapses as `n` grows.
+
+### How UnionFind works
+
+<details>
+<summary>Path halving, union by size, and why a single find is amortized -- not worst-case -- O(1).</summary>
+
+A UnionFind holds two `Uint32Array`s and a live component count:
+
+- **`parent`** -- `parent[i]` is `i`'s parent in its tree; `i` is a ROOT iff `parent[i] === i`. Two elements are in the same component iff they reach the same root.
+- **`size`** -- `size[root]` is the number of elements in that tree. It drives union-by-size AND answers `componentSize` for free.
+
+The two near-constant tricks are both applied:
+
+- **Path halving on `find`.** Walking `x` up to its root, every other node is repointed at its grandparent:
+
+  ```
+  while (parent[x] !== x) { parent[x] = parent[parent[x]]; x = parent[x]; }
+  ```
+
+  The tree flattens as a side effect of querying it. This is ITERATIVE -- no recursion, no stack array -- so the hot body allocates nothing (full compression would need a second pass or a stack; halving gets the same amortized bound in one alloc-free pass).
+
+- **Union by size.** `union` attaches the smaller-rooted tree under the larger (`if (size[ra] < size[rb]) swap; parent[rb] = ra; size[ra] += size[rb]`), so a tree never grows taller than log n before halving flattens it. `count` is decremented exactly once per REAL merge (never a scan), and `union` returns `true` iff it actually merged.
+
+Together these bound any single op at O(alpha(n)) AMORTIZED. **Honesty:** a single `find` is NOT worst-case O(1) -- an adversarial chain that has not yet been halved is O(depth). The guarantee is amortized alpha(n) (effectively a small constant), and the [witness](#the-o1-witness) proves the amortized throughput stays flat while a naive disjoint-set foil (no compression, no union-by-size -> a degenerate chain) decays toward O(n).
+
+`reset()` (re-singleton everything) and `forEachRoots(fn)` (visit every root) are the O(n) exceptions: there is no cross-check trick to make them O(1) because every element's parent must actually be read / rewritten. They still allocate nothing (a single bulk pass over the existing arrays), but they are bulk ops, not per-op hot paths -- `reset()` is named `reset()`, not `clear()`, precisely to flag that different cost class.
+
+The cost of the constant is memory: two `n`-sized `Uint32Array` columns, allocated eagerly at construction. UnionFind is the right tool when elements are a known, bounded integer range and you merge groups incrementally -- not for a huge / unbounded or non-integer element domain.
+
+</details>
+
+### UnionFind API reference
+
+```ts
+new UnionFind(n: number)   // n elements [0, n); n an integer in [1, 2^32-1]
+```
+
+- **`n`** -- the fixed element count; valid elements are integers in `[0, n)`. An integer in `[1, 2^32-1]`. Sizes both `Uint32Array` columns. The constructor throws a `[lite-o1]`-tagged `RangeError` on a non-integer / out-of-range / non-number argument (`Number.isInteger` never coerces, so a Symbol / BigInt fails closed rather than crashing raw). All scratch is allocated here; every method afterward allocates nothing (except `roots()`).
+
+```ts
+find(x: number): number              // component root; O(1)-amortized (path halving)
+union(a: number, b: number): boolean // merge (union by size); true iff a real merge
+connected(a: number, b: number): boolean // same-component test; O(1)-amortized
+componentSize(x: number): number     // size of x's component; O(1)-amortized
+reset(): void                        // O(n): re-singleton every element (allocates nothing)
+forEachRoots(fn: (root: number, uf: UnionFind) => void): void  // O(n) alloc-free scan
+roots(): IterableIterator<number>    // O(n) scan; ALLOCATES a generator per protocol
+get count: number                    // live component count (maintained in O(1))
+get capacity: number                 // the fixed element universe n
+```
+
+- **`find` / `union` / `connected` / `componentSize`** throw `[lite-o1] node out of range [0, n): ...` for an element that is not an integer in `[0, n)` (this includes `-1`, `1.5`, `NaN`, `null`, `x === n`, a Symbol, and a BigInt). The `typeof` guard runs BEFORE the coercing `>>>`, so a Symbol / BigInt never reaches arithmetic. `null` is rejected as `null`, never coerced to element `0`.
+- **`union(a, b)`** returns `true` iff a and b were in DIFFERENT components (a real merge, `count` drops by one); `false` if already joined (a no-op). `union(x, x)` is always `false`.
+- **`reset()` / `forEachRoots()` / `roots()`** are O(n), NOT per-op hot paths. `reset()` and `forEachRoots()` allocate nothing; `roots()` allocates a generator + a `{value, done}` per step by protocol -- use `forEachRoots` for the alloc-free scan. There is no public `size` getter (it would collide with the live-element-count meaning `size` has on the other members); use `count` (live components) and `capacity` (fixed universe).
+
+**Reach for UnionFind when** you track "which things are in the same group" over a fixed integer element set and merge groups incrementally (connected components, Kruskal MST, percolation, cycle detection, equivalence classes) at near-constant amortized cost with zero per-op allocation. **Avoid it when** you need to SPLIT / un-merge (union-find is merge-only; `reset()` re-singletons everything in O(n)), your elements are not a bounded integer range, or you are on a strict per-op WORST-CASE budget (a single `find` is amortized alpha(n), not worst-case O(1)). See [`GUIDE.md`](./GUIDE.md) for the full reach-for / avoid / measure-it.
 
 ---
 
@@ -244,6 +451,34 @@ The only cold branches are constructor validation and the `_oob` / `_full` throw
 
 The torture gate (`@zakkster/lite-leak` + `@zakkster/lite-gc-profiler`, run under `--expose-gc`) proves it: **0 B/op** on the add/has/delete hot path (per-call allocation measured to the sampling floor), **0 major GCs** and a max pause `<= 2ms` across a 2,000,000-op run, and 100 fill/clear cycles that leave the leak tracker at `size() = 0` (every tracked instance reclaimed -- proven non-vacuously by asserting the tracker held them first) with zero arrayBuffers growth (`clear()` allocates nothing; the reused set grows no backing store). `[Symbol.iterator]` is the one op that allocates -- a single iterator object per `for...of`, not per element -- so a per-frame hot loop uses `forEach`, which is allocation-free.
 
+**RingDeque** allocates its single `Float64Array` once, at construction:
+
+| Operation                        | Steady-state allocations |
+| -------------------------------- | ------------------------ |
+| `pushFront(v)` / `pushBack(v)`   | **0**                    |
+| `popFront()` / `popBack()`       | **0**                    |
+| `peekFront()` / `peekBack()`     | **0**                    |
+| `clear()`                        | **0** (head + count = 0) |
+| `forEach(fn)`                    | **0**                    |
+| `new RingDeque(...)`             | once, at construction (one typed array) |
+
+The value guard is a two-test branchless check on the hot body -- `typeof v !== 'number' || v !== v` (the second catches NaN once the type is known) -- with the message-building `_bad` / `_full` throw builders on the cold path (again using `String(v)`, never a template literal, so a Symbol / BigInt value fails closed rather than crashing raw). The torture and perf gates prove RingDeque at **0 B/op** across FIFO / LIFO / both-ends interleave churn, with a 0-delta on the `Float64Array` backing (fixed capacity -- no resize) and the leak tracker back at `size() = 0`.
+
+**UnionFind** allocates its two `Uint32Array` columns once, at construction:
+
+| Operation                        | Steady-state allocations |
+| -------------------------------- | ------------------------ |
+| `find(x)`                        | **0** (path halving, iterative) |
+| `union(a, b)`                    | **0**                    |
+| `connected(a, b)`                | **0**                    |
+| `componentSize(x)`               | **0**                    |
+| `reset()`                        | **0** (O(n) bulk pass, no new store) |
+| `forEachRoots(fn)`               | **0** (O(n) scan)        |
+| `roots()`                        | a generator + `{value,done}` per step (protocol) |
+| `new UnionFind(...)`             | once, at construction (both typed arrays) |
+
+`find` is path-halving and ITERATIVE -- no recursion and no stack array -- so the flattening that buys the amortized constant costs zero allocation. The element guard is the same branchless typeof-first check as the other members (`typeof x !== 'number' || (x >>> 0) !== x || x >= n`), with the `_oob` throw builder (using `String(x)`) on the cold path. The torture gate proves UnionFind at **0 B/op** across `find` / `union` / `connected` / `componentSize` churn (with real merges and O(n) `reset` / `forEachRoots` cycles exercised), 0 major GCs, a 0-delta on the two-column backing, and the leak tracker back at `size() = 0`. `reset()` and `forEachRoots()` are O(n) bulk primitives (still alloc-free) and are excluded from the zero-alloc-**per-op** claim; `roots()` is the one op that allocates, by generator protocol.
+
 </details>
 
 ---
@@ -255,31 +490,36 @@ The torture gate (`@zakkster/lite-leak` + `@zakkster/lite-gc-profiler`, run unde
 - **Fail closed on add, absent on query.** A bad key to `add` throws (you asked to store something invalid -- a bug). A bad key to `has` / `delete` is simply absent (a query about a non-member is a legitimate `false`). `null` is never coerced to `0`.
 - **Fixed capacity, no silent growth.** A new key past `capacity` throws rather than reallocating. A structure that advertises worst-case O(1) must not hide an amortized O(n) resize; growth, if ever offered, will be opt-in and labeled. See [`decisions/0003`](./decisions/0003-slotpool-deferred.md).
 - **The witness is a first-class deliverable, with a gated floor.** SparseSet flatness `>= 0.70`, the `Set` foil `<= 0.55`, ratio `>= 1.5x` -- a regression in the constant fails the build. See [`decisions/0004`](./decisions/0004-witness-flatness-gate.md).
+- **RingDeque is fixed-capacity (power-of-two), fail closed on full, and stores numbers only.** A power-of-two capacity buys the single-`& MASK` wrap; head + count makes full / empty single tests; a full push throws (no silent drop / overwrite); the numeric substrate keeps it zero-GC and makes `undefined`-on-empty unambiguous. See [`decisions/0005`](./decisions/0005-ring-capacity-fail-closed.md) and [`decisions/0006`](./decisions/0006-numeric-ring-substrate.md).
+- **UnionFind is amortized, not worst-case, and honest about it.** Path halving (iterative, no stack -- so zero-alloc) plus union by size bound any single op at O(alpha(n)) amortized; a single `find` is O(depth) worst-case, and the witness proves the amortized line against a naive-disjoint-set foil. `reset()` and `forEachRoots()` are the O(n) exceptions (named `reset()`, not `clear()`, to flag the cost); `roots()` is the one allocating op. See [`decisions/0007`](./decisions/0007-unionfind-path-halving-union-by-size.md).
 
 ---
 
 ## Testing
 
-**19 deterministic `node:test` cases**, plus a torture gate and the O(1) witness gate.
+**83 deterministic `node:test` cases**, plus a torture gate, a hard perf gate, and the O(1) witness gate.
 
 ```bash
-npm test           # 19 node:test cases (contract + boundary + differential fuzz)
+npm test           # 83 node:test cases (contract + boundary + differential fuzz)
 npm run test:types # tsc --noEmit against O1.d.ts
 npm run torture    # @zakkster/lite-leak + lite-gc-profiler: 0 B/op + leak-free
-npm run witness    # the O(1) throughput-invariance harness + Set foil + flatness gate
-npm run verify     # all four, the publish gate
+npm run witness    # the O(1) throughput-invariance harness + foils + flatness gate
+npm run test:perf  # @zakkster/lite-perf-gate: hard zero-alloc scavenge-scaling gate
+npm run verify     # all five, the publish gate
 ```
 
-The suite covers: constructor validation (every bad `universe` / `capacity`), the add/has/delete/clear/iterate surface, the delete-swap back-pointer, idempotent add, insertion-order iteration, the full fail-closed key surface (`add` throws `/^\[lite-o1\]/`, `has` never throws), `null is not zero`, a **byte-identical** proof that `clear()` leaves the dense + sparse `ArrayBuffer`s untouched (snapshot the raw bytes, clear, assert equality, confirm every prior key is absent and a stale pointer cannot masquerade as present), and a **1,000,000-op differential fuzz** of mixed add/delete/has against a native `Set` oracle with zero divergences. No gate output is a FAIL.
+For SparseSet the suite covers: constructor validation (every bad `universe` / `capacity`), the add/has/delete/clear/iterate surface, the delete-swap back-pointer, idempotent add, insertion-order iteration, the full fail-closed key surface (`add` throws `/^\[lite-o1\]/`, `has` never throws), `null is not zero`, a **byte-identical** proof that `clear()` leaves the dense + sparse `ArrayBuffer`s untouched, and a **1,000,000-op differential fuzz** of mixed add/delete/has against a native `Set` oracle. For RingDeque: power-of-two capacity rounding, push/pop/peek at both ends, wrap-around across the `& MASK` seam, the fail-closed surface (full push throws as a byte-identical no-op; a non-number or NaN throws; a Symbol / BigInt fails closed, not raw; `+/-Infinity` accepted; empty pop/peek returns `undefined`), a byte-identical `clear()` proof, and a **1,000,000-op both-ends differential fuzz** against a plain-`Array` reference deque (0 divergences, with the full-throw and empty-undefined edges both exercised). For UnionFind: constructor validation (every bad `n`), the find/union/connected/componentSize/count/reset/forEachRoots/roots surface, `count` decrementing exactly once per true merge, a **path-halving depth-shrink proof** (a test-only peek at `_parent`), the full fail-closed element surface (a bad element -- including a Symbol / BigInt -- throws `/^\[lite-o1\]/`, never raw; `null is not zero`), and a **>= 100,000-op mixed union/find/connected differential fuzz** against a trivial no-compression / no-union-by-size oracle (0 divergences on connectivity, component size, and live count). No gate output is a FAIL.
 
 ---
 
 ## What this is not
 
-- **Not a general-purpose set.** Keys are integers in a known, bounded `[0, universe)`. For arbitrary keys (strings, objects, huge sparse integer domains), use a native `Set` / `Map` -- SparseSet trades universe-sized memory for the flat constant and the O(1) clear.
-- **Not a growable collection.** Capacity is fixed at construction; a new key past it throws. This is deliberate (worst-case O(1), fail closed), not a missing feature.
-- **Not a payload store.** SparseSet holds membership, not values. Store component data in a parallel SoA column or `@zakkster/lite-arena` keyed by the same ids.
-- **Not the full family yet.** v0.1.0 is SparseSet only. RingDeque, SlotPool, UnionFind, and the eight-dimension benchmark suite are on the roadmap, not in this release.
+- **Not a general-purpose set.** SparseSet keys are integers in a known, bounded `[0, universe)`. For arbitrary keys (strings, objects, huge sparse integer domains), use a native `Set` / `Map` -- SparseSet trades universe-sized memory for the flat constant and the O(1) clear.
+- **Not a general-purpose queue.** RingDeque stores numbers only. To queue objects / strings, queue their integer handles and keep the payloads in a parallel column or `@zakkster/lite-arena`.
+- **Not a splittable disjoint-set.** UnionFind is merge-only: there is no per-element un-merge / undo. `reset()` re-singletons the whole forest in O(n); rollback means keeping your own edge log and rebuilding. It also eagerly allocates two `n`-sized `Uint32Array` columns at construction, so it is not for a huge / unbounded or non-integer element domain -- and a single `find` is amortized alpha(n), not worst-case O(1).
+- **Not a growable collection.** All three members are fixed-capacity: a SparseSet key past capacity, or a RingDeque push on a full ring, throws; UnionFind's element universe `n` is fixed at construction. This is deliberate (worst-case / amortized bounds, fail closed -- no hidden resize), not a missing feature. An overwrite-oldest RingDeque preset (RingLog) is a deferred future variant, not the current default.
+- **Not a payload store.** SparseSet holds membership, RingDeque holds numbers, UnionFind holds connectivity -- none holds object payloads. Store component data in a parallel SoA column or `@zakkster/lite-arena` keyed by the same ids / handles.
+- **Not the full family yet.** v0.3.0 is SparseSet + RingDeque + UnionFind. SlotPool, MonoDeque, and the eight-dimension benchmark suite are on the roadmap, not in this release.
 - **Not a benchmark suite.** The witness proves throughput invariance (one axis); the full latency/memory/cache/GC benchmark suite is a separate, planned deliverable.
 
 ---

package/llms.txt

@@ -1,6 +1,6 @@
 # @zakkster/lite-o1
 
-Version: 0.1.0
+Version: 0.3.0
 License: MIT (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
 Runtime dependencies: none. ESM only. ASCII-only source. sideEffects: false.
 Node: >= 18.
@@ -12,12 +12,15 @@ constant instead of asserting it. The complexity class is the product: every hot
 op is O(1) worst-case and allocates zero bytes after construction, and a shipped
 witness harness demonstrates the flat throughput curve against a built-in foil.
 
-v0.1.0 ships one member: SparseSet.
+v0.3.0 ships three members: SparseSet, RingDeque, and UnionFind. They share no
+mutable module state, so a bundler that imports one drops the others (tree-shakeable).
 
 ## Exports (from the single main file O1.js)
 
 - `SparseSet` -- class. A zero-GC O(1) integer set over [0, universe).
-- `VERSION` -- string, '0.1.0'.
+- `RingDeque` -- class. A zero-GC O(1) fixed-capacity numeric double-ended queue.
+- `UnionFind` -- class. A zero-GC near-O(1) amortized disjoint-set forest.
+- `VERSION` -- string, '0.3.0'.
 
 ## SparseSet
 
@@ -53,28 +56,123 @@ Membership invariant (the whole trick):
 The cross-check rejects stale sparse pointers, which is why clear() can be O(1)
 and never zero a store.
 
+## RingDeque
+
+    new RingDeque(capacity)
+
+- capacity: requested max elements; integer in [1, 2^31]. ROUNDS UP to the next
+  power of two (>= requested); the capacity getter reports the rounded value.
+- Constructor throws a [lite-o1] RangeError on a non-integer / out-of-range /
+  non-number arg (typeof-guarded before any coercion; message via String(x)).
+- Substrate: ONE Float64Array (numeric values only), head + count representation.
+  The physical slot for logical offset i from the front is store[(head + i) & MASK],
+  MASK = capacity - 1; wrap is a single & (power-of-two modulo), no branch.
+
+Hot surface (all O(1) worst-case, zero allocation):
+
+- pushFront(v) -> this   Push v onto the front. Throws [lite-o1] when FULL (a
+                         byte-identical no-op) or on a non-clean value.
+- pushBack(v) -> this    Push v onto the back. Same fail-closed policy.
+- popFront() -> number|undefined  Remove+return the front; undefined on empty (never throws).
+- popBack()  -> number|undefined  Remove+return the back; undefined on empty (never throws).
+- peekFront() -> number|undefined Front without removing; undefined on empty.
+- peekBack()  -> number|undefined Back without removing; undefined on empty.
+- clear() -> void        Empty in O(1): resets head + count, touches NO store
+                         (numbers retain no references, so nothing to zero).
+- forEach(fn) -> void    Iterate live elements front->back, alloc-free.
+                         fn is (value, index, deque).
+- [Symbol.iterator]()    Iterate live elements front->back.
+- size (getter)          Live element count.
+- capacity (getter)      Max elements (power-of-two, rounded up from requested).
+
+Value contract (LOCKED): a pushed value must be typeof 'number' AND not NaN.
+Rejected (throws [lite-o1]): null, undefined, string, Symbol, BigInt, object, NaN.
+Accepted: any finite number, and +Infinity / -Infinity (typeof number, not NaN).
+The typeof guard runs FIRST so a Symbol / BigInt never reaches arithmetic.
+
+## UnionFind
+
+    new UnionFind(n)
+
+- n: fixed element count; integer in [1, 2^32-1]. Elements are [0, n).
+- Constructor throws a [lite-o1] RangeError on a non-integer / out-of-range arg
+  (Number.isInteger never coerces; message via String(n), Symbol/BigInt-safe).
+- Substrate: TWO flat Uint32Array columns -- parent[i] (i's parent; i itself iff
+  root) and size[root] (elements in that tree). Path halving on find + union by
+  size bound any single op at O(alpha(n)) amortized (inverse Ackermann, <= ~4).
+
+Hot surface (all O(1)-AMORTIZED, zero allocation):
+
+- find(x) -> number      Root of x's component. Path halving flattens the walk in
+                         place (no recursion, no stack array). Throws [lite-o1] on
+                         a bad element (typeof-guarded before the coercing >>>).
+- union(a,b) -> boolean  Merge a and b. true iff a real merge happened (they were
+                         separate); false if already joined. Union by size. Guards
+                         both endpoints. count-- exactly once per true merge.
+- connected(a,b) -> boolean  find(a) === find(b). Both guarded via find.
+- componentSize(x) -> number size[find(x)]. Guarded via find.
+- count (getter)         Live component count. O(1), maintained (never scanned).
+- capacity (getter)      Fixed element universe n. (No `size` getter -- it would
+                         collide with the live-count meaning size has elsewhere.)
+- reset() -> void        O(n) HONEST EXCEPTION: re-singleton every element
+                         (parent[i]=i, size[i]=1, count=n). A single bulk pass over
+                         the existing arrays -- allocates NOTHING, but is O(n), NOT
+                         a zero-alloc-per-op hot path. Named reset(), not clear().
+- forEachRoots(fn) -> void  O(n) FULL SCAN, alloc-free: fn(root, uf) per current
+                         root. Documented exception, EXCLUDED from the
+                         zero-alloc-per-op claims. fn is hoisted for zero alloc.
+- roots() -> generator   O(n) scan; ALLOCATES a generator + {value,done} per step
+                         by protocol (like [Symbol.iterator]) -- OUT of zero-alloc
+                         claims. Use forEachRoots for the alloc-free scan.
+
+Amortized honesty: a single find is NOT worst-case O(1) -- an adversarial
+pre-halving chain is O(depth). The guarantee is AMORTIZED alpha(n); the witness
+reports amortized throughput staying flat while a no-compression / no-union-by-size
+foil (a degenerate chain) collapses.
+
 ## Design bounds
 
-- valid key: integer in [0, universe).
-- Fixed capacity: no silent growth; a new key past capacity throws (fail closed).
-- Fail closed on add, absent on query. null is never coerced to key 0.
+- SparseSet valid key: integer in [0, universe).
+- SparseSet fixed capacity: no silent growth; a new key past capacity throws.
+- SparseSet fail closed on add, absent on query. null is never coerced to key 0.
+- RingDeque fixed capacity (power-of-two, rounded up): push past full throws
+  (fail closed); pop/peek on empty returns undefined. Numeric values only.
+- RingDeque value: typeof 'number' and not NaN (+/-Infinity accepted).
+- UnionFind element: integer in [0, n); fixed n, no growth. Fail closed on a bad
+  element (throws [lite-o1]); reset() and forEachRoots() are the O(n) exceptions.
 
 ## Scripts
 
-- npm test           -- 19 node:test cases (contract + boundary + differential fuzz).
+- npm test           -- 83 node:test cases (contract + boundary + differential fuzz).
 - npm run test:types -- tsc --noEmit against O1.d.ts.
 - npm run torture    -- lite-leak + lite-gc-profiler: 0 B/op, 0 major GC, leak-free.
-- npm run witness    -- O(1) throughput-invariance harness + Set foil + flatness gate.
-- npm run verify     -- all four (publish gate).
+- npm run witness    -- O(1) throughput-invariance harness + foils + flatness gate.
+- npm run test:perf  -- lite-perf-gate hard zero-alloc scavenge-scaling gate.
+- npm run verify     -- all five (publish gate).
 
 ## Witness gate (locked)
 
-- n-sweep [1e3, 1e4, 1e5, 1e6, 1e7], batch 1e6, warm-up + median of 5.
-- SparseSet flatness (opsPerMs last/first) >= 0.70.
-- Native Set foil flatness <= 0.55 AND SparseSet/Set ops-per-ms ratio >= 1.5x.
-
-## Not in v0.1.0
-
-RingDeque, SlotPool, UnionFind, MonoDeque, and the eight-dimension benchmark
-suite are on the roadmap, not this release. SparseSet holds membership, not
-payloads (store values in a parallel SoA column or @zakkster/lite-arena).
+- SparseSet: n-sweep [1e3..1e7] DISPLAYED, batch 1e6, two warm-ups + median of 9.
+  The gate is computed over the STEADY window 1e4 <= n <= 1e6: below it (n=1e3) is
+  an L1 micro-case that turbo-spikes, above it (n=1e7) is the memory wall where the
+  8*n-byte arrays exceed cache and ops/ms measures DRAM, not the algorithm -- both
+  are shown but excluded from the gate. SparseSet flatness (opsPerMs last/first over
+  the window) >= 0.70; native Set foil flatness <= 0.55 AND SparseSet/Set ops-per-ms
+  ratio >= 1.5x at every gated size. (The 0.70 floor is unchanged; only the gate's
+  domain is pinned to where ops/ms means O(1).)
+- RingDeque: n-sweep [1e3, 1e4, 1e5], FIFO churn vs Array.prototype.shift foil
+  (O(n)); ops/ms is a rate, so the ring (batch 5e5) and foil (batch 2e3) use
+  different batches yet compare directly. RingDeque flatness >= 0.70; shift foil
+  flatness <= 0.55; RingDeque/shift ratio >= 1.5x.
+- UnionFind: n-sweep [1e3, 1e4, 1e5], amortized find (coalesced + flattened) vs a
+  NAIVE disjoint-set foil (no path compression, no union-by-size -> a degenerate
+  chain, O(n) find). ops/ms is a rate (uf batch 5e5, naive batch 2e3). UnionFind
+  flatness >= 0.70; naive foil flatness <= 0.55; UnionFind/naive ratio >= 1.5x.
+
+## Not yet shipped
+
+SlotPool, MonoDeque, and the eight-dimension benchmark suite are on the roadmap,
+not this release. A RingLog / overwrite-oldest RingDeque preset is a deferred
+future variant. SparseSet holds membership, not payloads (store values in a
+parallel SoA column or @zakkster/lite-arena); RingDeque holds numbers only;
+UnionFind holds disjoint-set connectivity over [0, n), not payloads.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@zakkster/lite-o1",
   "author": "Zahary Shinikchiev <shinikchiev@yahoo.com>",
-  "version": "0.1.0",
-  "description": "Zero-dependency, zero-GC family of O(1) data structures that proves its constant: SparseSet (O(1) add/has/delete/clear/iterate) with a throughput-invariance witness harness. Tree-shakeable named exports.",
+  "version": "0.3.0",
+  "description": "Zero-dependency, zero-GC family of O(1) data structures that proves its constant: SparseSet (O(1) add/has/delete/clear/iterate), RingDeque (O(1) fixed-capacity numeric double-ended queue), and UnionFind (near-O(1) amortized disjoint-set) with a throughput-invariance witness harness. Tree-shakeable named exports.",
   "type": "module",
   "main": "./O1.js",
   "module": "./O1.js",
@@ -28,12 +28,20 @@
     "test:types": "tsc -p test/types/tsconfig.json",
     "torture": "node --expose-gc test/torture.mjs",
     "witness": "node test/witness.mjs",
-    "verify": "npm test && npm run test:types && npm run torture && npm run witness"
+    "test:perf": "node --expose-gc --max-semi-space-size=4 --test test/perf/PerfGate.test.mjs",
+    "verify": "npm test && npm run test:types && npm run torture && npm run witness && npm run test:perf"
   },
   "keywords": [
     "o1",
     "big-o",
     "sparse-set",
+    "ring-buffer",
+    "circular-buffer",
+    "deque",
+    "ringdeque",
+    "union-find",
+    "disjoint-set",
+    "dsu",
     "data-structures",
     "zero-gc",
     "gc",
@@ -51,10 +59,24 @@
   "devDependencies": {
     "@zakkster/lite-gc-profiler": "^1.16.0",
     "@zakkster/lite-leak": "^1.10.0",
+    "@zakkster/lite-perf-gate": "^1.4.2",
     "typescript": "^7.0.2"
   },
+  "homepage": "https://github.com/PeshoVurtoleta/lite-o1#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PeshoVurtoleta/lite-o1.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PeshoVurtoleta/lite-o1/issues",
+    "email": "shinikchiev@yahoo.com"
+  },
   "engines": {
     "node": ">=18"
   },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/PeshoVurtoleta"
+  },
   "sideEffects": false
 }