@lazily-hub/lazily-js 0.6.1 → 0.7.0

package/.github/workflows/release.yml

@@ -39,9 +39,13 @@ jobs:
           node-version: 24
           registry-url: https://registry.npmjs.org
 
-      # Trusted publishing needs npm CLI >= 11.5.1; Node 24's bundled npm may lag.
-      - name: Upgrade npm for OIDC trusted publishing
-        run: npm install -g npm@latest
+      # OIDC trusted publishing (provenance) needs npm >= 9.5.0; Node 24's
+      # bundled npm 11.x already supports it. Do NOT `npm install -g npm@latest`
+      # — that global self-upgrade drops the `sigstore` dependency that
+      # libnpmpublish requires for provenance, producing
+      # `Cannot find module 'sigstore'` at publish time.
+      - name: Verify npm supports OIDC provenance
+        run: npm --version
 
       - name: Install dependencies
         working-directory: lazily-js
@@ -51,15 +55,19 @@ jobs:
         working-directory: lazily-js
         run: npm test --if-present
 
-      # Published under the `prev` dist-tag so this v0.x line does not steal
-      # `latest` from a higher already-published version; move `latest` explicitly
-      # (`npm dist-tag add @lazily-hub/lazily-js@<v> latest`) once the accidental
-      # v1.x releases are removed.
+      # Publish as `latest`. The accidental v1.x versions that forced the old
+      # `prev` dist-tag workaround have been removed (npm now shows only the
+      # 0.4.0 / 0.5.0 / 0.6.x line, latest = 0.6.1), so the v0.x line is the
+      # canonical latest again.
       - name: Publish
         working-directory: lazily-js
         run: |
           version="$(node -p "require('./package.json').version")"
-          if npm publish --access public --tag prev; then
+          # --provenance triggers the OIDC trusted-publishing exchange (the
+          # `id-token: write` permission minted a short-lived publish token).
+          # The bundled npm 11.x does not auto-enable provenance the way a
+          # freshly-upgraded npm@latest does, so it must be explicit.
+          if npm publish --provenance --access public; then
             echo "published @lazily-hub/lazily-js@${version}"
           elif npm view "@lazily-hub/lazily-js@${version}" version >/dev/null 2>&1; then
             echo "@lazily-hub/lazily-js@${version} already published — idempotent no-op"

package/README.md

@@ -46,7 +46,7 @@ notes and platform carve-outs lives in
 | Keyed cell collections (`CellMap` / `CellTree`) + reconcile | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Memoized semantic tree (`SemTree`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Stable-id alignment (manufactured identity) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Reactive queue (`QueueCell` SPSC/MPSC + `QueueStorage` adapter) | — | — | — | — | — | — | — | — |
+| Reactive queue (`QueueCell` SPSC/MPSC + `QueueStorage` adapter) | ✅ | — | ✅ | ✅ | — | ✅ | — | ✅ |
 | Free-text character CRDT (`TextCrdt`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | `TextCrdt` delta sync (`version_vector` / `delta_since` / `apply_delta`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Move-aware sequence CRDT (`SeqCrdt`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@lazily-hub/lazily-js",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Native JavaScript port of the lazily reactive core: a full reactive graph (Cell/Slot/Signal/Effect), the lazily-spec IPC wire types, keyed cell collections + LIS reconciliation, the memoized semantic tree, the move-aware sequence CRDT, the Fugue/RGA text CRDT, manufactured text identity, full-Harel state charts, and an FFI state-projection consumer.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lazily-hub/lazily-js.git"
+  },
   "type": "module",
   "main": "src/index.js",
   "types": "src/index.d.ts",
@@ -30,6 +35,10 @@
       "types": "./src/collections.d.ts",
       "default": "./src/collections.js"
     },
+    "./queue": {
+      "types": "./src/queue.d.ts",
+      "default": "./src/queue.js"
+    },
     "./sem-tree": {
       "types": "./src/sem-tree.d.ts",
       "default": "./src/sem-tree.js"
@@ -64,7 +73,7 @@
     }
   },
   "scripts": {
-    "build": "node --check src/index.js && node --check src/reactive.js && node --check src/reactive-async.js && node --check src/state-machine.js && node --check src/statechart.js && node --check src/collections.js && node --check src/sem-tree.js && node --check src/stable-id.js && node --check src/seq-crdt.js && node --check src/text-crdt.js && node --check src/utf8-offsets.js && node --check src/lossless-tree-crdt.js && node --check src/state-projection.js && node --check src/signaling.js && node --check src/distributed.js",
+    "build": "node --check src/index.js && node --check src/reactive.js && node --check src/reactive-async.js && node --check src/state-machine.js && node --check src/statechart.js && node --check src/collections.js && node --check src/queue.js && node --check src/sem-tree.js && node --check src/stable-id.js && node --check src/seq-crdt.js && node --check src/text-crdt.js && node --check src/utf8-offsets.js && node --check src/lossless-tree-crdt.js && node --check src/state-projection.js && node --check src/signaling.js && node --check src/distributed.js",
     "test:formal": "node scripts/formal-check.mjs",
     "bench": "node bench/context.bench.mjs",
     "benchmark-update": "node scripts/run-benchmarks.mjs",

package/src/queue.d.ts

@@ -0,0 +1,91 @@
+// Reactive queue: QueueCell + pluggable QueueStorage backend (#lzqueue).
+// Pure logic — no reactive graph. See queue.js for the reader-kind invalidation
+// contract and the shell / storage split.
+
+export type QueuePushErrorLabel = "Full" | "Closed";
+export type QueuePopErrorLabel = "Empty" | "Closed";
+
+export const QueuePushError: Readonly<{ Full: "Full"; Closed: "Closed" }>;
+export const QueuePopError: Readonly<{ Empty: "Empty"; Closed: "Closed" }>;
+
+/** The reader-kind invalidation matrix returned by every mutating op. */
+export type QueueInvalidates = {
+  head: boolean;
+  len: boolean;
+  is_empty: boolean;
+  is_full: boolean;
+  closed: boolean;
+};
+
+/** Result of a push op (`returns` is the error label, or `null` on success). */
+export type QueuePushResult = {
+  returns: null | QueuePushErrorLabel;
+  invalidates: QueueInvalidates;
+};
+
+/** Result of a pop op (`returns` is the element, or the error label). */
+export type QueuePopResult = {
+  returns: unknown | QueuePopErrorLabel;
+  invalidates: QueueInvalidates;
+};
+
+/** Result of a close op. */
+export type QueueCloseResult = {
+  returns: null;
+  invalidates: QueueInvalidates;
+};
+
+/** A duck-typed `QueueStorage` backend. */
+export type QueueStorage = {
+  tryPush(value: unknown): null | QueuePushErrorLabel;
+  tryPop(): unknown | QueuePopErrorLabel;
+  peek(): unknown;
+  len(): number;
+  capacity(): number | null;
+  isClosed(): boolean;
+  close(): void;
+  snapshot(): QueueStorageSnapshot;
+};
+
+export type QueueStorageSnapshot = {
+  elements: unknown[];
+  capacity: number | null;
+  closed: boolean;
+};
+
+export type QueueInitial = {
+  elements?: unknown[];
+  capacity?: number | null;
+  closed?: boolean;
+};
+
+/** The reference `QueueStorage` backend (unbounded or bounded array FIFO). */
+export class VecDequeStorage {
+  constructor(initial?: QueueInitial);
+  elements: unknown[];
+  static from(initial?: QueueInitial): VecDequeStorage;
+  tryPush(value: unknown): null | QueuePushErrorLabel;
+  tryPop(): unknown | QueuePopErrorLabel;
+  peek(): unknown;
+  len(): number;
+  capacity(): number | null;
+  isClosed(): boolean;
+  close(): void;
+  snapshot(): QueueStorageSnapshot;
+}
+
+/** A reactive FIFO queue — SPSC primitive with an MPSC usage rule. */
+export class QueueCell {
+  constructor(initial?: QueueInitial, storage?: QueueStorage);
+  static from(initial?: QueueInitial, storage?: QueueStorage): QueueCell;
+  tryPush(value: unknown): QueuePushResult;
+  tryPop(): QueuePopResult;
+  close(): QueueCloseResult;
+  head(): unknown;
+  len(): number;
+  isEmpty(): boolean;
+  isFull(): boolean;
+  isClosed(): boolean;
+  capacity(): number | null;
+  elements(): unknown[];
+}

package/src/queue.js

@@ -0,0 +1,354 @@
+// Reactive queue: QueueCell + pluggable QueueStorage backend (#lzqueue).
+//
+// Pure logic — no reactive graph. Like the keyed collections
+// (`./collections.js`), this is compute that every binding MUST implement; the
+// conformance/collections/queuecell_*.json fixtures pin behavior. To make a
+// queue live-reactive, wrap its ops in a `Context` (cells/slots/effects) and
+// use the returned `invalidates` matrix to drive reader-kind invalidation —
+// see `lazily-spec/cell-model.md` § "Reactive queues" and the distributed-queue
+// PRD for the shell / storage split.
+//
+// QueueCell is specified as a single-producer / single-consumer (SPSC)
+// primitive; MPSC (multi-producer) is a *usage rule* on the same type —
+// multiple producers push inside one logical batch, and the batch boundary
+// serializes the pushes into a deterministic order. There is no separate
+// MPSCQueueCell type (`lazily-spec/cell-model.md` § "QueueCell — SPSC
+// primitive with MPSC usage rule").
+//
+// Invalidation is scoped to **reader kind**, not individual positions. A push
+// invalidates `len` / `is_empty` readers (and `head` when transitioning from
+// empty, `is_full` when transitioning onto capacity); a pop invalidates `head`
+// / `len` / `is_empty` readers (and `is_full` when transitioning off capacity).
+// The `invalidates` matrix returned by each mutating op reports exactly which
+// reader kinds changed — the core reader-kind independence law, which mirrors
+// the `PartialEq` guard the reactive bindings implement for free.
+
+// ---------------------------------------------------------------------------
+// Error sentinels — observable rejection labels (distinct observable signals).
+// `Full` and `Closed` are the two push-rejection reasons; `Empty` and `Closed`
+// are the two pop-rejection reasons. These match the cross-language conformance
+// fixture `returns` labels (`lazily-spec/conformance/collections/queuecell_*`).
+// ---------------------------------------------------------------------------
+
+export const QueuePushError = Object.freeze({
+  /** Bounded backend at capacity (reject policy on the default backend). */
+  Full: "Full",
+  /** Queue is closed; push is rejected regardless of capacity. Terminal. */
+  Closed: "Closed",
+});
+
+export const QueuePopError = Object.freeze({
+  /** Queue is open but contains no elements. */
+  Empty: "Empty",
+  /** Queue is closed and empty (drained). Distinct from `Empty`. */
+  Closed: "Closed",
+});
+
+// ---------------------------------------------------------------------------
+// QueueStorage contract (duck-typed).
+// ---------------------------------------------------------------------------
+//
+// The shell / storage split keeps the reactive shell storage-agnostic. The
+// default backend is `VecDequeStorage` (unbounded or bounded array-backed
+// FIFO). A conforming backend MUST:
+//
+// 1. FIFO order — `tryPop()` returns elements in `tryPush()` order.
+// 2. Cardinality compatibility — native producer/consumer shape is a superset
+//    of SPSC; MPSC usage requires a multi-writer backend.
+// 3. Bounded contract (optional) — `capacity()` returns a number and
+//    `tryPush()` returns `QueuePushError.Full` at capacity.
+// 4. Position identity — invalidation is phrased over reader kind, not storage
+//    indices; the shell layers its own logical version counters above storage.
+
+// ---------------------------------------------------------------------------
+// VecDequeStorage — the reference unbounded/bounded backend.
+// ---------------------------------------------------------------------------
+
+/**
+ * The reference `QueueStorage` backend: an array-backed FIFO, optionally
+ * bounded. Serializes as a JSON array (element order = FIFO order) per
+ * `lazily-spec/cell-model.md` § "Wire and snapshot shape".
+ */
+export class VecDequeStorage {
+  /**
+   * @param {{ elements?: unknown[], capacity?: number | null, closed?: boolean }} [initial]
+   */
+  constructor(initial = {}) {
+    this.elements = Array.isArray(initial.elements) ? [...initial.elements] : [];
+    this.#capacity =
+      initial.capacity === undefined || initial.capacity === null
+        ? null
+        : initial.capacity;
+    this.#closed = Boolean(initial.closed);
+    if (this.#capacity !== null && this.#capacity <= 0) {
+      throw new RangeError("VecDequeStorage capacity must be > 0");
+    }
+    Object.freeze(this);
+  }
+
+  #capacity;
+  #closed;
+
+  static from(initial) {
+    return new VecDequeStorage(initial);
+  }
+
+  /**
+   * Append `value` to the tail.
+   * @returns {null | "Full" | "Closed"} `null` on success, else the error label.
+   */
+  tryPush(value) {
+    if (this.#closed) {
+      return QueuePushError.Closed;
+    }
+    if (this.#capacity !== null && this.elements.length >= this.#capacity) {
+      return QueuePushError.Full;
+    }
+    this.elements.push(value);
+    return null;
+  }
+
+  /**
+   * Remove and return the head element.
+   * @returns {unknown | "Empty" | "Closed"} the element, or the error label.
+   */
+  tryPop() {
+    if (this.elements.length === 0) {
+      return this.#closed ? QueuePopError.Closed : QueuePopError.Empty;
+    }
+    return this.elements.shift();
+  }
+
+  /** @returns {unknown} the head element, or `null` when empty. */
+  peek() {
+    return this.elements.length === 0 ? null : this.elements[0];
+  }
+
+  /** @returns {number} */
+  len() {
+    return this.elements.length;
+  }
+
+  /** @returns {number | null} the bounded capacity, or `null` if unbounded. */
+  capacity() {
+    return this.#capacity;
+  }
+
+  /** @returns {boolean} */
+  isClosed() {
+    return this.#closed;
+  }
+
+  /** Close the queue. Idempotent and terminal. */
+  close() {
+    this.#closed = true;
+  }
+
+  /** @returns {{ elements: unknown[], capacity: number | null, closed: boolean }} */
+  snapshot() {
+    return {
+      elements: [...this.elements],
+      capacity: this.#capacity,
+      closed: this.#closed,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// QueueCell — the reactive shell (pure logic).
+// ---------------------------------------------------------------------------
+
+/**
+ * A reactive FIFO queue — SPSC primitive with an MPSC usage rule (`#lzqueue`).
+ *
+ * Pure logic: wraps a pluggable `QueueStorage` backend and, after each op,
+ * reports which reader kinds (`head` / `len` / `is_empty` / `is_full` /
+ * `closed`) changed via the returned `invalidates` matrix. Wire the matrix to a
+ * reactive `Context` to make the queue live-reactive. The reader-kind
+ * independence law — a push to a non-empty queue does NOT invalidate the `head`
+ * reader, a pop does — falls out of the value-diff this shell computes.
+ */
+export class QueueCell {
+  /**
+   * @param {{ elements?: unknown[], capacity?: number | null, closed?: boolean }} [initial]
+   *   Passed to the default `VecDequeStorage` when no `storage` is given.
+   * @param {object} [storage] A duck-typed `QueueStorage` backend. Defaults to
+   *   a `VecDequeStorage` built from `initial`.
+   */
+  constructor(initial = {}, storage) {
+    this.#storage = storage ?? new VecDequeStorage(initial);
+    this.#prev = this.#snapshot();
+    Object.freeze(this);
+  }
+
+  #storage;
+  #prev;
+
+  static from(initial, storage) {
+    return new QueueCell(initial, storage);
+  }
+
+  // -- internal: reader-kind state + invalidation diff ----------------------
+
+  #snapshot() {
+    const len = this.#storage.len();
+    const cap = this.#storage.capacity();
+    return {
+      head: this.#storage.peek(),
+      len,
+      is_empty: len === 0,
+      is_full: cap !== null && len >= cap,
+      closed: this.#storage.isClosed(),
+    };
+  }
+
+  #diff(next) {
+    const prev = this.#prev;
+    const invalidates = {
+      head: !deepEqual(prev.head, next.head),
+      len: prev.len !== next.len,
+      is_empty: prev.is_empty !== next.is_empty,
+      is_full: prev.is_full !== next.is_full,
+      closed: prev.closed !== next.closed,
+    };
+    this.#prev = next;
+    return invalidates;
+  }
+
+  // -- mutating ops ---------------------------------------------------------
+
+  /**
+   * Append `value` to the tail.
+   * @returns {{ returns: null | "Full" | "Closed", invalidates: QueueInvalidates }}
+   *   On rejection (`Full` / `Closed`) the queue state is unchanged and the
+   *   `invalidates` matrix is all-false.
+   */
+  tryPush(value) {
+    const err = this.#storage.tryPush(value);
+    if (err !== null) {
+      return { returns: err, invalidates: emptyInvalidates() };
+    }
+    return { returns: null, invalidates: this.#diff(this.#snapshot()) };
+  }
+
+  /**
+   * Remove and return the head element. Pop on a closed *non-empty* queue
+   * drains (returns the next element); only closed+empty yields `Closed`.
+   * @returns {{ returns: unknown | "Empty" | "Closed", invalidates: QueueInvalidates }}
+   */
+  tryPop() {
+    const value = this.#storage.tryPop();
+    if (value === QueuePopError.Empty || value === QueuePopError.Closed) {
+      return { returns: value, invalidates: emptyInvalidates() };
+    }
+    return { returns: value, invalidates: this.#diff(this.#snapshot()) };
+  }
+
+  /**
+   * Close the queue. Idempotent (no-op on an already-closed queue) and
+   * terminal. After close, `tryPush` returns `Closed`; `tryPop` drains and
+   * returns `Closed` only once empty.
+   * @returns {{ returns: null, invalidates: QueueInvalidates }}
+   *   The `closed` reader is invalidated only on the open → closed transition.
+   */
+  close() {
+    if (this.#storage.isClosed()) {
+      return { returns: null, invalidates: emptyInvalidates() };
+    }
+    this.#storage.close();
+    return { returns: null, invalidates: this.#diff(this.#snapshot()) };
+  }
+
+  // -- reader-kind reads (current state, non-mutating) ----------------------
+
+  /** Current head value, or `null` when empty. */
+  head() {
+    return this.#storage.peek();
+  }
+
+  /** Number of buffered elements. */
+  len() {
+    return this.#storage.len();
+  }
+
+  /** Whether the queue is empty. */
+  isEmpty() {
+    return this.#storage.len() === 0;
+  }
+
+  /**
+   * Whether the queue is at capacity (the backpressure signal). Always `false`
+   * for an unbounded backend.
+   */
+  isFull() {
+    const cap = this.#storage.capacity();
+    return cap !== null && this.#storage.len() >= cap;
+  }
+
+  /** Whether the queue has been closed. */
+  isClosed() {
+    return this.#storage.isClosed();
+  }
+
+  /** The backend's capacity, or `null` if unbounded. */
+  capacity() {
+    return this.#storage.capacity();
+  }
+
+  /**
+   * Snapshot the buffered elements in FIFO order. There is no reactive
+   * random-access `queue[N]` reader; per-position reactivity is the domain of
+   * `CellMap`, not `QueueCell`.
+   * @returns {unknown[]}
+   */
+  elements() {
+    if (typeof this.#storage.elements === "function") {
+      return this.#storage.elements();
+    }
+    return this.#storage.snapshot().elements;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Future primitives (stubs) — documented, not in v1 conformance.
+// ---------------------------------------------------------------------------
+//
+// TopicCell (SPMC broadcast / MPMC pub-sub) and WorkQueueCell (true MPMC with
+// exclusive handoff) are genuinely distinct primitives — they differ in
+// *invalidation model and handoff semantics*, not producer/consumer
+// cardinality (see `lazily-spec/cell-model.md` § "Future queue primitives").
+//
+// - TopicCell — every subscriber receives every pushed element; each subscriber
+//   keeps its own cursor; GC bounded by the slowest cursor. Lands with the
+//   distributed-queue PRD Phase 3. Formal stub: lazily-formal/TopicCell.lean.
+//
+// - WorkQueueCell — N consumers compete for elements; each element delivered to
+//   exactly one consumer (exclusive handoff). Requires an authority (leader) to
+//   serialize pop-assignment; pure CRDT cannot provide it. Lands with the
+//   distributed-queue PRD Phase 2 (consensus core). Formal stub:
+//   lazily-formal/WorkQueueCell.lean.
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+/** @returns {QueueInvalidates} */
+function emptyInvalidates() {
+  return { head: false, len: false, is_empty: false, is_full: false, closed: false };
+}
+
+function deepEqual(a, b) {
+  if (a === b) {
+    return true;
+  }
+  if (a === null || b === null || typeof a !== "object" || typeof b !== "object") {
+    return false;
+  }
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  return (
+    aKeys.length === bKeys.length &&
+    aKeys.every((k) => Object.is(aKeys[k], bKeys[k])) &&
+    aKeys.every((k) => deepEqual(a[k], b[k]))
+  );
+}