@lazily-hub/lazily-js 0.10.0 → 0.12.0

package/README.md

@@ -40,10 +40,10 @@ notes and platform carve-outs lives in
 | --------- | :----: | :------: | :------: | :--: | :----: | :---: | :--: | :---: |
 | Reactive graph — `Cell` / `Slot` / `Signal` / `Effect` / memo / batch | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Reactive family (`ReactiveFamily`) — keyed cell/slot family + materialization mode (`#lzmatmode`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Thread-safe reactive family (`ThreadSafeReactiveFamily`) — `Send + Sync` keyed family + materialization confluence (`#lzmatmode`) | ✅ | — | — | — | — | — | — | — |
-| Async reactive family (`AsyncReactiveFamily`) — keyed family + eventual transparency (`#lzmatmode`) | ✅ | — | — | — | — | — | — | — |
-| Reactive family sync — membership propagation + materialize-on-ingest + derived-aggregate transparency (`#lzfamilysync`) | ✅ | — | ✅ | ✅ | — | — | — | — |
-| Thread-safe context (lock-backed) | ✅ | ✅ | ✅ | — | — | ✅ | ✅ | ✅ |
+| Thread-safe reactive family (`ThreadSafeReactiveFamily`) — `Send + Sync` keyed family + materialization confluence (`#lzmatmode`) | ✅ | — | — | ✅ | — | ✅ | — | ✅ |
+| Async reactive family (`AsyncReactiveFamily`) — keyed family + eventual transparency (`#lzmatmode`) | ✅ | — | — | ✅ | — | ✅ | — | ✅ |
+| Reactive family sync — membership propagation + materialize-on-ingest + derived-aggregate transparency (`#lzfamilysync`) | ✅ | — | ✅ | ✅ | — | ✅ | — | ✅ |
+| Thread-safe context (lock-backed) | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ |
 | Async reactive context | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Flat state machine | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Harel state charts | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
@@ -66,10 +66,10 @@ notes and platform carve-outs lives in
 | State projection / mirror | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Causal receipts (`CausalReceipts` outcome projection) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Message-passing + RPC command plane (`command-plane-v1`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| C-ABI FFI boundary | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ |
+| C-ABI FFI boundary | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Permission boundary (`PeerPermissions` / `RemoteOp`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Capability negotiation (`SessionHandshake`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Instrumentation / benchmarks | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ |
+| Instrumentation / benchmarks | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 <!-- coverage-table:end -->
 
 CRDT convergence and the wire protocol are pinned by the shared conformance fixtures
@@ -83,6 +83,11 @@ and JSON Schemas in `lazily-spec` and the Lean models in `lazily-formal`.
 | `@lazily-hub/lazily-js/reactive` | Reactive dependency graph: `Context`, `Cell`, `Slot`, `Signal`, `Effect` |
 | `@lazily-hub/lazily-js/reactive-async` | Async reactive graph: `AsyncContext` — Promise-driven slots/effects with revision-guarded stale-completion discard, in-flight dedup, and cancellation |
 | `@lazily-hub/lazily-js/reactive-family` | Unified keyed reactive family: `ReactiveFamily` (`EntryKind` cell/slot × `MaterializationMode` eager/lazy) + `cellFamily` input-cell specialization (`#lzmatmode`) |
+| `@lazily-hub/lazily-js/async-reactive-family` | Async keyed reactive family: `AsyncReactiveFamily` + `asyncCellFamily` over `AsyncContext` — eventual transparency (a pending slot observes `undefined` and resolves to the canonical value; eager ≡ lazy once resolved) (`#lzmatmode`) |
+| `@lazily-hub/lazily-js/thread-safe` | Lock-backed reactive context: `ThreadSafeContext` (`Send + Sync` flavor of `Context`) + `AtomicMutex` — a real `SharedArrayBuffer` + `Atomics` reentrant mutex giving cross-worker mutual exclusion; degrades to a single-realm guard where shared memory is unavailable |
+| `@lazily-hub/lazily-js/thread-safe-reactive-family` | Thread-safe keyed reactive family: `ThreadSafeReactiveFamily` + `threadSafeCellFamily` — mutex-guarded present set with first-writer-wins materialization confluence (`#lzmatmode`) |
+| `@lazily-hub/lazily-js/ffi` | C-ABI FFI boundary (`schemas/ffi.json`): message codec (`encodeMessage` / `decodeMessage` / `validateMessage` / `kindOf`, `LazilyFfiStatus` / `LazilyFfiMessageKind`) + `FfiChannel` FIFO. Isomorphic core (browser shim); the Node build additionally exposes `NativeFfiChannel` / `loadNativeChannel` over the real `lazily_ffi_channel_*` C ABI via koffi |
+| `@lazily-hub/lazily-js/instrumentation` | In-library instrumentation/benchmark API: `benchmark`, `runBenchmarkSuite`, `BenchmarkResult`, `withInstrumentation` — plus opt-in reactive-core counters via `new Context({ instrument: true })` / `instrumentationSnapshot()` |
 | `@lazily-hub/lazily-js/state-machine` | Flat finite-state-machine kernel backed by a reactive `Cell` |
 | `@lazily-hub/lazily-js/statechart` | Harel/SCXML chart interpreter plus `ChartBuilder`, `StateBuilder`, `TransitionBuilder` |
 | `@lazily-hub/lazily-js/collections` | `CellMap`, `CellTree`, keyed reconciliation, and LIS move minimization |
@@ -495,7 +500,10 @@ sequence and text CRDTs (incl. `TextCrdt` delta sync, `#lztextsync`:
 identity, the reactive family / materialization mode (`#lzmatmode`:
 `materialization/observational_transparency.json`,
 `materialization/deferral_not_deallocation.json`,
-`materialization/entry_kind_orthogonal_to_mode.json`), Harel state charts, the
+`materialization/entry_kind_orthogonal_to_mode.json` — replayed through the
+single-threaded, async, and thread-safe families), the C-ABI FFI boundary
+(`schemas/ffi.json`: message codec + channel round-trip over `snapshot_*` /
+`delta_*` wire), Harel state charts, the
 signaling protocol (`signaling/frames.json`,
 `signaling/anti_spoof_session.json`), and the distributed CRDT plane
 (`distributed/crdt_sync_frames.json`, `distributed/anti_entropy_converge.json`).
@@ -517,13 +525,18 @@ names the Lean theorems it mirrors:
 | `Collection` | `collection-properties.test.js` | `setEntryValue_preserves_{membership,order,siblings}`, `moveKey_preserves_{membership,values}`, `moveKey_advances_order`, `addKey_advances_membership_and_order`, `Family.get_idempotent_after_first` |
 | `Tree` | `tree-properties.test.js` | `setNodeValue_preserves_{other_nodes,node_signals}`, `moveChild_preserves_{non_parent,parent_value}`, `moveChild_advances_order_signal_only` |
 | `Materialization` | `reactive-family.test.js` | `observe_canonical`, `eager_lazy_observationally_equivalent`, `eager_materializes_all`, `lazy_defers_slots`, `materialize_present_monotone`, `lazy_present_subset_eager`, `materialize_preserves_observe`, `cell_entries_materialized_in_every_mode`, `slot_entries_deferred_under_lazy` |
+| `Materialization` (thread-safe) | `thread-safe-reactive-family.test.js` | `materialize_present_comm`, `materialize_observe_comm` (materialization confluence) + the base materialization laws replayed through `ThreadSafeReactiveFamily` |
+| `AsyncMaterialization` | `async-reactive-family.test.js` | eventual transparency (a driven async slot resolves to the canonical value; eager ≡ lazy) + present-set monotonicity through `AsyncReactiveFamily` |
+| `ThreadSafe` | `thread-safe.test.js` | `flushBatch_empty`, `flushBatch_singleton_eq_setCell` (thread-safe batch refines `setCell`), `flushBatch_dependent_dirty`, `flushBatch_preserves_nondependent_dirty` |
 | `Reconciliation` | `reconciliation-properties.test.js` | `lisBy_longest`, `reconcile_move_minimized`, `reconcile_stable_not_invalidated` |
 | `AsyncSlotState` | `reactive-async.test.js` | `stale_completeOk_discarded`, `current_completeOk_publishes`, `current_completeErr_to_error` |
 | `AsyncEffect` | `reactive-async.test.js` | `fire_blocked_during_cleanup`, `invalidate_from_idle_schedules`, `cleanupDone_resumes_deferred`, `dispose_absorbing`, `disposed_terminal` |
 
-Thread-safe context theorems are not mirrored because JavaScript is
-single-threaded (one event loop): a lock-backed context has no meaning on this
-runtime — the concurrency-layer platform carve-out. The `Signaling` /
+The thread-safe context IS mirrored on this runtime: JavaScript is
+single-threaded per realm but shares memory across Web Workers via
+`SharedArrayBuffer` + `Atomics`, so `ThreadSafeContext` guards every operation
+with a real reentrant Atomics mutex (cross-worker mutual exclusion, degrading to
+a single-realm guard where shared memory is unavailable). The `Signaling` /
 `SignalingRoster` formal models are exercised through the `SignalingRoom`
 fixture replay (`signaling/anti_spoof_session.json`) rather than a named-theorem
 property test.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lazily-hub/lazily-js",
-  "version": "0.10.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.",
+  "version": "0.12.0",
+  "description": "Native JavaScript port of the lazily reactive core: a full reactive graph (Cell/Slot/Signal/Effect), sync/async/thread-safe keyed reactive families with materialization mode, the lazily-spec IPC wire types + C-ABI FFI boundary (isomorphic channel + Node native binding), 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, an FFI state-projection consumer, and an in-library instrumentation/benchmark API.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -31,6 +31,28 @@
       "types": "./src/reactive-family.d.ts",
       "default": "./src/reactive-family.js"
     },
+    "./async-reactive-family": {
+      "types": "./src/async-reactive-family.d.ts",
+      "default": "./src/async-reactive-family.js"
+    },
+    "./thread-safe": {
+      "types": "./src/thread-safe.d.ts",
+      "default": "./src/thread-safe.js"
+    },
+    "./thread-safe-reactive-family": {
+      "types": "./src/thread-safe-reactive-family.d.ts",
+      "default": "./src/thread-safe-reactive-family.js"
+    },
+    "./ffi": {
+      "types": "./src/ffi.d.ts",
+      "node": "./src/ffi-node.js",
+      "browser": "./src/ffi.js",
+      "default": "./src/ffi.js"
+    },
+    "./instrumentation": {
+      "types": "./src/instrumentation.d.ts",
+      "default": "./src/instrumentation.js"
+    },
     "./state-machine": {
       "types": "./src/state-machine.d.ts",
       "default": "./src/state-machine.js"
@@ -81,7 +103,7 @@
     }
   },
   "scripts": {
-    "build": "node --check src/index.js && node --check src/transport.js && node --check src/shm-backend.js && node --check src/reactive.js && node --check src/reactive-async.js && node --check src/reactive-family.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",
+    "build": "node --check src/index.js && node --check src/transport.js && node --check src/shm-backend.js && node --check src/reactive.js && node --check src/reactive-async.js && node --check src/reactive-family.js && node --check src/async-reactive-family.js && node --check src/thread-safe.js && node --check src/thread-safe-reactive-family.js && node --check src/ffi.js && node --check src/ffi-node.js && node --check src/instrumentation.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",
     "bench:scale": "node --max-old-space-size=8192 bench/scale.bench.mjs",

package/src/async-reactive-family.d.ts

@@ -0,0 +1,78 @@
+import type { AsyncCellHandle, AsyncContext, AsyncSlotHandle } from "./reactive-async.js";
+import type { EntryKind, MaterializationMode } from "./reactive-family.js";
+
+export { EntryKind, MaterializationMode, DEFAULT_MATERIALIZATION_MODE } from "./reactive-family.js";
+
+export type EntryKindResolver<K> = EntryKind | ((key: K) => EntryKind);
+export type AsyncFamilyHandle = AsyncCellHandle | AsyncSlotHandle;
+
+/**
+ * The async keyed reactive family (`#lzmatmode`, async flavor): keys map to
+ * per-entry async reactive nodes (input cells resolved synchronously, or derived
+ * slots resolved asynchronously), allocated per the family's
+ * {@link MaterializationMode}. The transparency law is EVENTUAL — a pending slot
+ * observes as `undefined` and resolves to the canonical value.
+ */
+export class AsyncReactiveFamily<K = unknown, V = unknown> {
+  constructor(
+    ctx: AsyncContext,
+    mode: MaterializationMode,
+    keys: Iterable<K>,
+    factory: (key: K) => V,
+    entryKind?: EntryKindResolver<K>,
+  );
+
+  /** Build an eager async family: every declared key's node is allocated now. */
+  static eager<K, V>(
+    ctx: AsyncContext,
+    keys: Iterable<K>,
+    factory: (key: K) => V,
+    entryKind?: EntryKindResolver<K>,
+  ): AsyncReactiveFamily<K, V>;
+
+  /** Build a lazy async family: derived (slot) entries deferred to first read. */
+  static lazy<K, V>(
+    ctx: AsyncContext,
+    keys: Iterable<K>,
+    factory: (key: K) => V,
+    entryKind?: EntryKindResolver<K>,
+  ): AsyncReactiveFamily<K, V>;
+
+  /** Build an async family in the default (eager) mode. */
+  static create<K, V>(
+    ctx: AsyncContext,
+    keys: Iterable<K>,
+    factory: (key: K) => V,
+    entryKind?: EntryKindResolver<K>,
+  ): AsyncReactiveFamily<K, V>;
+
+  /** Materialize (lazy pull) and return the entry handle for `key`. */
+  get(key: K): AsyncFamilyHandle;
+  /** Non-blocking observe: value for a cell/resolved slot, `undefined` if pending. */
+  observe(key: K): V | undefined;
+  /** Drive `key` to resolution and return its canonical value. */
+  resolve(key: K): Promise<V>;
+  /** Set a cell entry's value (input entries only). */
+  setCell(key: K, value: V): void;
+  /** Whether `key` is currently materialized. Non-reactive. */
+  isPresent(key: K): boolean;
+  /** Currently-materialized keys, in first-materialization order. */
+  presentKeys(): K[];
+  /** Number of currently-materialized entries. */
+  presentCount(): number;
+  /** This family's entry kind for `key`. */
+  entryKind(key: K): EntryKind;
+  /** This family's materialization mode. */
+  readonly mode: MaterializationMode;
+}
+
+/**
+ * The input-cell specialization of {@link AsyncReactiveFamily}: a keyed async
+ * family whose entries are all input cells (always materialized, always resolved).
+ */
+export function asyncCellFamily<K, V>(
+  ctx: AsyncContext,
+  keys: Iterable<K>,
+  factory: (key: K) => V,
+  mode?: MaterializationMode,
+): AsyncReactiveFamily<K, V>;

package/src/async-reactive-family.js

@@ -0,0 +1,249 @@
+// The async keyed reactive family (`AsyncReactiveFamily`, `#lzmatmode` async
+// flavor) — the {@link AsyncContext} analog of {@link ReactiveFamily}.
+//
+// Keys `K` map to per-entry async reactive nodes: {@link EntryKind.Cell} input
+// cells ({@link AsyncCellHandle}, always resolved) or {@link EntryKind.Slot}
+// derived slots ({@link AsyncSlotHandle}, resolved asynchronously), allocated per
+// the family's {@link MaterializationMode}.
+//
+// The eager/lazy contract and present-set monotonicity are identical to the
+// single-threaded family. The transparency law here is EVENTUAL: an async derived
+// slot read is `undefined` while pending and resolves to the canonical value — so
+// `observe` returns `V | undefined`. Input cells are always resolved. Drive a slot
+// to resolution with {@link AsyncReactiveFamily#resolve} (or
+// `ctx.getAsync(fam.get(key))`).
+//
+// To keep the sync/thread-safe/async families API-parallel the per-key factory is
+// the same sync `(key) => V`; a derived slot wraps it in a ready async
+// recomputation. Mirrors the async materialization case in lazily-spec and the
+// `AsyncMaterialization` proofs (eventual transparency) in lazily-formal.
+//
+// Rust reference: `lazily-rs/src/async_reactive_family.rs`.
+
+import { EntryKind, MaterializationMode, DEFAULT_MATERIALIZATION_MODE } from "./reactive-family.js";
+
+export { EntryKind, MaterializationMode, DEFAULT_MATERIALIZATION_MODE };
+
+function resolveKind(entryKind, key) {
+  const kind = typeof entryKind === "function" ? entryKind(key) : entryKind;
+  if (kind !== EntryKind.Cell && kind !== EntryKind.Slot) {
+    throw new TypeError(`entry kind for key ${String(key)} must be EntryKind.Cell or EntryKind.Slot`);
+  }
+  return kind;
+}
+
+/**
+ * The async unified keyed reactive family (`#lzmatmode`): keys map to per-entry
+ * async reactive nodes ({@link EntryKind.Cell} input cells resolved
+ * synchronously, or {@link EntryKind.Slot} derived slots resolved
+ * asynchronously), allocated per the family's {@link MaterializationMode}.
+ *
+ * Operations run against an owning `AsyncContext` (from `./reactive-async.js`).
+ *
+ * @template K, V
+ */
+export class AsyncReactiveFamily {
+  /** @type {import("./reactive-async.js").AsyncContext} */
+  #ctx;
+  /** @type {string} */
+  #mode;
+  /** @type {(key: K) => V} */
+  #factory;
+  /** @type {EntryKind | ((key: K) => EntryKind)} */
+  #entryKind;
+  /** Present (materialized) entries: key -> { kind, handle }. */
+  #materialized = new Map();
+  /** First-materialization order of the present set. */
+  #order = [];
+
+  /**
+   * @param {import("./reactive-async.js").AsyncContext} ctx owning async context
+   * @param {string} mode {@link MaterializationMode}
+   * @param {Iterable<K>} keys declared keys
+   * @param {(key: K) => V} factory canonical per-key value producer
+   * @param {EntryKind | ((key: K) => EntryKind)} [entryKind] entry kind (or per-key resolver); defaults to Slot
+   */
+  constructor(ctx, mode, keys, factory, entryKind = EntryKind.Slot) {
+    if (mode !== MaterializationMode.Eager && mode !== MaterializationMode.Lazy) {
+      throw new TypeError("mode must be a MaterializationMode");
+    }
+    if (typeof factory !== "function") {
+      throw new TypeError("factory must be a function");
+    }
+    this.#ctx = ctx;
+    this.#mode = mode;
+    this.#factory = factory;
+    this.#entryKind = entryKind;
+
+    for (const key of keys) {
+      // A cell entry is always materialized regardless of mode; a slot entry
+      // only under eager.
+      if (resolveKind(entryKind, key) === EntryKind.Cell || mode === MaterializationMode.Eager) {
+        this.#materializeKey(key);
+      }
+    }
+  }
+
+  /**
+   * Build an eager async family: every declared key's node is allocated now. The
+   * default mode.
+   * @template K, V
+   * @param {import("./reactive-async.js").AsyncContext} ctx
+   * @param {Iterable<K>} keys
+   * @param {(key: K) => V} factory
+   * @param {EntryKind | ((key: K) => EntryKind)} [entryKind]
+   * @returns {AsyncReactiveFamily<K, V>}
+   */
+  static eager(ctx, keys, factory, entryKind = EntryKind.Slot) {
+    return new AsyncReactiveFamily(ctx, MaterializationMode.Eager, keys, factory, entryKind);
+  }
+
+  /**
+   * Build a lazy async family: derived (slot) entries deferred to first read;
+   * input (cell) entries in `keys` are still materialized at build.
+   * @template K, V
+   * @param {import("./reactive-async.js").AsyncContext} ctx
+   * @param {Iterable<K>} keys
+   * @param {(key: K) => V} factory
+   * @param {EntryKind | ((key: K) => EntryKind)} [entryKind]
+   * @returns {AsyncReactiveFamily<K, V>}
+   */
+  static lazy(ctx, keys, factory, entryKind = EntryKind.Slot) {
+    return new AsyncReactiveFamily(ctx, MaterializationMode.Lazy, keys, factory, entryKind);
+  }
+
+  /**
+   * Build an async family in the default mode (eager). Alias for
+   * {@link AsyncReactiveFamily.eager}.
+   * @template K, V
+   * @param {import("./reactive-async.js").AsyncContext} ctx
+   * @param {Iterable<K>} keys
+   * @param {(key: K) => V} factory
+   * @param {EntryKind | ((key: K) => EntryKind)} [entryKind]
+   * @returns {AsyncReactiveFamily<K, V>}
+   */
+  static create(ctx, keys, factory, entryKind = EntryKind.Slot) {
+    return AsyncReactiveFamily.eager(ctx, keys, factory, entryKind);
+  }
+
+  #materializeKey(key) {
+    const existing = this.#materialized.get(key);
+    if (existing !== undefined) {
+      return existing; // warm: already allocated (first-writer-wins, stable handle).
+    }
+    const kind = resolveKind(this.#entryKind, key);
+    const factory = this.#factory;
+    // A cell entry sets its value directly (always resolved); a derived slot
+    // wraps the factory as a ready async recomputation — the same node an eager
+    // build would allocate.
+    const handle =
+      kind === EntryKind.Cell
+        ? this.#ctx.cell(factory(key))
+        : this.#ctx.computedAsync(async () => factory(key));
+    const entry = { kind, handle };
+    this.#materialized.set(key, entry);
+    this.#order.push(key);
+    return entry;
+  }
+
+  /**
+   * Get the entry handle for `key`, materializing it on first access (the lazy
+   * pull) and caching it. For a slot family this is the {@link AsyncSlotHandle}
+   * to drive with `ctx.getAsync` or {@link AsyncReactiveFamily#resolve}.
+   * @param {K} key
+   * @returns {import("./reactive-async.js").AsyncCellHandle | import("./reactive-async.js").AsyncSlotHandle}
+   */
+  get(key) {
+    return this.#materializeKey(key).handle;
+  }
+
+  /**
+   * Non-blocking observe: the resolved value for a cell or resolved slot, or
+   * `undefined` for a slot still pending. The EVENTUAL-transparency law: once
+   * resolved this equals the canonical value under either mode. Materializes the
+   * entry if absent.
+   * @param {K} key
+   * @returns {V | undefined}
+   */
+  observe(key) {
+    const { kind, handle } = this.#materializeKey(key);
+    return kind === EntryKind.Cell ? this.#ctx.getCell(handle) : this.#ctx.get(handle);
+  }
+
+  /**
+   * Drive `key` to resolution and return its canonical value. For a cell this is
+   * immediate; for a slot it awaits the async recomputation. Materializes the
+   * entry if absent.
+   * @param {K} key
+   * @returns {Promise<V>}
+   */
+  async resolve(key) {
+    const { kind, handle } = this.#materializeKey(key);
+    return kind === EntryKind.Cell ? this.#ctx.getCell(handle) : this.#ctx.getAsync(handle);
+  }
+
+  /**
+   * Set a cell entry's value (input entries only). Materializes it if absent.
+   * @param {K} key
+   * @param {V} value
+   */
+  setCell(key, value) {
+    const { kind, handle } = this.#materializeKey(key);
+    if (kind !== EntryKind.Cell) {
+      throw new TypeError(`key ${String(key)} is a derived slot, not a writable input cell`);
+    }
+    this.#ctx.setCell(handle, value);
+  }
+
+  /**
+   * Whether `key` is currently materialized (present). Non-reactive.
+   * @param {K} key
+   * @returns {boolean}
+   */
+  isPresent(key) {
+    return this.#materialized.has(key);
+  }
+
+  /**
+   * The currently-materialized keys, in first-materialization order. The present
+   * set only grows (deferral, not de-allocation).
+   * @returns {K[]}
+   */
+  presentKeys() {
+    return [...this.#order];
+  }
+
+  /** Number of currently-materialized entries. @returns {number} */
+  presentCount() {
+    return this.#order.length;
+  }
+
+  /**
+   * This family's entry kind for `key`.
+   * @param {K} key
+   * @returns {EntryKind}
+   */
+  entryKind(key) {
+    return resolveKind(this.#entryKind, key);
+  }
+
+  /** This family's materialization mode. @returns {MaterializationMode} */
+  get mode() {
+    return this.#mode;
+  }
+}
+
+/**
+ * The input-cell specialization of {@link AsyncReactiveFamily}: a keyed async
+ * family whose entries are all input cells ({@link EntryKind.Cell} — always
+ * materialized, always resolved).
+ * @template K, V
+ * @param {import("./reactive-async.js").AsyncContext} ctx
+ * @param {Iterable<K>} keys
+ * @param {(key: K) => V} factory
+ * @param {string} [mode] {@link MaterializationMode} (cell entries materialize under either)
+ * @returns {AsyncReactiveFamily<K, V>}
+ */
+export function asyncCellFamily(ctx, keys, factory, mode = DEFAULT_MATERIALIZATION_MODE) {
+  return new AsyncReactiveFamily(ctx, mode, keys, factory, EntryKind.Cell);
+}

package/src/ffi-node.d.ts

@@ -0,0 +1,35 @@
+import type { IpcMessage } from "./index.js";
+import type { DecodeResult, LazilyFfiStatus, RecvBytesResult } from "./ffi.js";
+
+export {
+  FfiChannel,
+  IpcMessage,
+  LazilyFfiMessageKind,
+  LazilyFfiStatus,
+  decodeMessage,
+  encodeMessage,
+  kindOf,
+  validateMessage,
+} from "./ffi.js";
+export type { EncodeResult, DecodeResult, RecvBytesResult } from "./ffi.js";
+
+/** Whether koffi is installed so a native binding can be established. */
+export function hasNativeBinding(): boolean;
+
+/**
+ * A native C-ABI channel backed by a `lazily` shared library. Interface-parallel
+ * to the in-process `FfiChannel`.
+ */
+export class NativeFfiChannel {
+  constructor(libPath?: string);
+  sendJson(payload: Uint8Array | string): LazilyFfiStatus;
+  send(message: IpcMessage): LazilyFfiStatus;
+  recvJson(): RecvBytesResult;
+  recv(): DecodeResult;
+  len(): number;
+  readonly isEmpty: boolean;
+  free(): void;
+}
+
+/** Open a native C-ABI channel to a `lazily` shared library. */
+export function loadNativeChannel(libPath?: string): NativeFfiChannel;