@zakkster/lite-o1 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,53 @@ 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.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,54 @@ 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>;
+}

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.2.0 ships two members -- SparseSet and RingDeque -- plus its `VERSION`
+ * const. The two are independent (no shared mutable module state), so a bundler
+ * that imports one drops the other (`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.2.0';
 
 /** Largest universe the Uint32 substrate + the (k >>> 0) key check can honor. */
 const MAX_UNIVERSE = 0x100000000; // 2^32
@@ -146,3 +148,196 @@ 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 + ')');
+    }
+}

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.2.0 ships SparseSet (an integer set with O(1) add / has / delete / iterate and an O(1) clear() that zeroes nothing) and RingDeque (a fixed-capacity numeric double-ended queue with O(1) push/pop at both ends) -- plus a throughput-invariance witness that shows the flat cost curve while a native Set (or Array.prototype.shift) 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.2.0 ships two 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. And **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. They share no mutable module state, so a bundler that imports one drops the other.
 
 ```bash
 npm install @zakkster/lite-o1
@@ -57,6 +59,9 @@ 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)
 - [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 +93,15 @@ 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).
 - **`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`), 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,15 +168,17 @@ get capacity: number        // max live members as constructed
 
 | Constant   | Value     | Meaning                                            |
 | ---------- | --------- | -------------------------------------------------- |
-| `VERSION`  | `'0.1.0'` | Package version string.                            |
+| `VERSION`  | `'0.2.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) |
 
 ---
 
@@ -187,6 +201,95 @@ SparseSet's contiguous typed-array layout streams flat; the `Set`'s hash table s
 
 ---
 
+## 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).
+
+```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)
+```
+
+- **`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.
+
+---
+
 ## Composability with the ecosystem
 
 SparseSet is the dense-integer membership primitive under an ECS-style loop. A common pattern: a `SparseSet` per component tracks which entity ids currently have that component; a `@zakkster/lite-arena` `Arena` owns the component payloads by generational handle. Membership and iteration are O(1) and alloc-free; the per-frame `clear()` of a scratch set (visited masks, this-frame-touched ids) is free.
@@ -244,6 +347,19 @@ 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`.
+
 </details>
 
 ---
@@ -255,31 +371,34 @@ 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).
 
 ---
 
 ## Testing
 
-**19 deterministic `node:test` cases**, plus a torture gate and the O(1) witness gate.
+**58 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           # 58 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). 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 growable collection.** Both members are fixed-capacity: a SparseSet key past capacity, or a RingDeque push on a full ring, throws. This is deliberate (worst-case O(1), fail closed -- no hidden amortized 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 -- neither 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.2.0 is SparseSet + RingDeque. SlotPool, UnionFind, 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.2.0
 License: MIT (c) Zahary Shinikchiev <shinikchiev@yahoo.com>
 Runtime dependencies: none. ESM only. ASCII-only source. sideEffects: false.
 Node: >= 18.
@@ -12,12 +12,14 @@ 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.2.0 ships two members: SparseSet and RingDeque. They share no mutable module
+state, so a bundler that imports one drops the other (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.
+- `VERSION` -- string, '0.2.0'.
 
 ## SparseSet
 
@@ -53,28 +55,71 @@ 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.
+
 ## 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).
 
 ## Scripts
 
-- npm test           -- 19 node:test cases (contract + boundary + differential fuzz).
+- npm test           -- 58 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.
+- SparseSet: n-sweep [1e3..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.
+- 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.
 
-## Not in v0.1.0
+## Not yet shipped
 
-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).
+SlotPool, UnionFind, 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.

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.2.0",
+  "description": "Zero-dependency, zero-GC family of O(1) data structures that proves its constant: SparseSet (O(1) add/has/delete/clear/iterate) and RingDeque (O(1) fixed-capacity numeric double-ended queue) with a throughput-invariance witness harness. Tree-shakeable named exports.",
   "type": "module",
   "main": "./O1.js",
   "module": "./O1.js",
@@ -28,12 +28,17 @@
     "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",
     "data-structures",
     "zero-gc",
     "gc",
@@ -51,10 +56,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
 }