@lazily-hub/lazily-js 0.7.0 → 0.9.0

package/README.md

@@ -39,6 +39,7 @@ notes and platform carve-outs lives in
 | Feature | Rust | Python | Kotlin | JS | Dart | Zig | Go | C++ |
 | --------- | :----: | :------: | :------: | :--: | :----: | :---: | :--: | :---: |
 | Reactive graph — `Cell` / `Slot` / `Signal` / `Effect` / memo / batch | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Reactive family (`ReactiveFamily`) — keyed cell/slot family + materialization mode (`#lzmatmode`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Thread-safe context (lock-backed) | ✅ | ✅ | ✅ | — | — | ✅ | ✅ | ✅ |
 | Async reactive context | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Flat state machine | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
@@ -46,21 +47,22 @@ 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`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Lossless tree CRDT core (`LosslessTreeCrdt`, M1) | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
-| Lossless tree — dotted-frontier anti-entropy | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
-| Lossless tree — concurrent merge convergence | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
+| Lossless tree CRDT core (`LosslessTreeCrdt`, M1) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Lossless tree — dotted-frontier anti-entropy | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| Lossless tree — concurrent merge convergence | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Registers (LWW / MV) + `PnCounter` + `CellCrdt` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | IPC wire — `Snapshot` + `Delta` + `CrdtSync` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Shared-memory blob path (`ShmBlobArena`) | ✅ | ✅ | ✅ | ~ | ~ | ✅ | ✅ | ✅ |
+| Shared-memory blob path (`ShmBlobArena`) | ✅ | ✅ | ✅ | ✅ | ~ | ✅ | ✅ | ✅ |
+| Cross-process zero-copy transport (`BlobBackend` / shm / arrow) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Distributed CRDT plane (`CrdtPlaneRuntime` / anti-entropy) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Distributed plane — WebRTC transport + signaling | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | State projection / mirror | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Causal receipts (`CausalReceipts` outcome projection) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Message-passing + RPC command plane (`command-plane-v1`) | ✅ | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
+| Message-passing + RPC command plane (`command-plane-v1`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | C-ABI FFI boundary | ✅ | ✅ | ✅ | — | ✅ | ✅ | ✅ | ✅ |
 | Permission boundary (`PeerPermissions` / `RemoteOp`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
 | Capability negotiation (`SessionHandshake`) | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
@@ -74,8 +76,10 @@ and JSON Schemas in `lazily-spec` and the Lean models in `lazily-formal`.
 | Import | What it is |
 |--------|------------|
 | `@lazily-hub/lazily-js` | `lazily-spec` IPC wire types: `Snapshot`, `Delta`, `DeltaOp`, `IpcMessage` (`Snapshot` / `Delta` / `CrdtSync`), `NodeState`, `IpcValue`, `PeerPermissions`, `SessionHandshake`, `BINDING_CAPABILITIES` |
+| `@lazily-hub/lazily-js/transport` | Cross-process zero-copy transport (`#lzzcpy`): `ShmBlobArena`, `InProcessBackend` / `ArrowBackend`, `BlobRouter`, `spillMessage` / `resolveValue`, and the FFI-gated `createShmBackend` (Node/Bun/Deno). Isomorphic — no FFI import; browser-safe |
 | `@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/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 |
@@ -155,6 +159,44 @@ ctx.setCell(userId, 2); // supersedes any in-flight compute; slot re-resolves
 await ctx.getAsync(profile); // the profile for user 2
 ```
 
+## Reactive family and materialization mode
+
+`ReactiveFamily` (from `@lazily-hub/lazily-js/reactive-family`) is the unified
+**keyed reactive family** (`#lzmatmode`): it maps keys to per-entry reactive
+nodes and abstracts over the entry's handle kind. Two orthogonal axes:
+
+- **Entry kind** — `EntryKind.Cell` entries are input cells (**always
+  materialized**, any mode); `EntryKind.Slot` entries are derived slots (what
+  materialization governs). `cellFamily(...)` is the input-cell specialization.
+- **Materialization mode** — `MaterializationMode.Eager` (**default**) allocates
+  every derived node up front; `MaterializationMode.Lazy` (opt-in) allocates a
+  derived node on its **first read** ("materialize on pull") and caches it.
+
+Mode is **observationally transparent**: a read returns the same value under
+either mode — it changes allocation timing and memory, never results. Lazy pays
+off only for sparsely-touched large keyed address spaces.
+
+```js
+import { Context } from "@lazily-hub/lazily-js/reactive";
+import { ReactiveFamily } from "@lazily-hub/lazily-js/reactive-family";
+
+const ctx = new Context();
+
+// A derived (slot) family of key*3 over a large address space, built lazily:
+// nothing is allocated until a key is read.
+const fam = ReactiveFamily.lazy(ctx, range(0, 1_000_000), (k) => k * 3);
+fam.presentCount(); // 0
+
+fam.observe(5); // 15 — first read materializes just this entry
+fam.presentCount(); // 1
+fam.isPresent(5); // true
+fam.isPresent(6); // false
+
+// Eager builds the same values up front — observationally identical.
+const eager = ReactiveFamily.eager(ctx, [0, 1, 2, 3], (k) => k * 3);
+eager.observe(2) === fam.observe(2); // true
+```
+
 ## State machine and state charts
 
 `StateMachine` is the flat finite-state-machine kernel: a pure
@@ -344,6 +386,69 @@ signaling, and the WebRTC transport are shipped; C-ABI FFI is `none` because
 browser/Worker JS cannot host a native in-process ABI. The same payload types
 can still be carried by any transport a host application owns.
 
+## Cross-process zero-copy transport
+
+`@lazily-hub/lazily-js/transport` implements the pluggable blob-backend
+transport (`#lzzcpy`). A large payload is not copied through the wire codec: the
+producer **spills** it to a backend (which mints a `ShmBlobRef` descriptor) and
+ships only the descriptor; the receiver **routes** the descriptor by its
+`backend` discriminator and **resolves** it zero-copy — reading the backend's own
+bytes in place. `ShmBlobRef` gained an optional `backend` field (`shm` | `arrow`
+| `in_process`) that defaults to `shm` and is omitted from the wire, so every
+pre-transport descriptor round-trips byte-for-byte.
+
+The module is **isomorphic**: it imports no FFI, so it bundles and runs in the
+browser. `InProcessBackend`, `ArrowBackend`, the `BlobRouter`, and the
+spill/resolve policy are pure JS and available everywhere (including a
+main-thread ↔ Web Worker deployment).
+
+```js
+import {
+  BlobRouter,
+  InProcessBackend,
+  ArrowBackend,
+  spillMessage,
+} from "@lazily-hub/lazily-js/transport";
+import { Delta, DeltaOp, IpcMessage, IpcValue } from "@lazily-hub/lazily-js";
+
+const backend = new InProcessBackend(); // or ArrowBackend for columnar payloads
+const big = IpcValue.inline(new Uint8Array(4096));
+const { message, spilledBytes } = spillMessage(
+  IpcMessage.delta(new Delta({ baseEpoch: 0, epoch: 1, ops: [DeltaOp.slotValue(7, big)] })),
+  backend,
+); // message now carries a small SharedBlob descriptor; spilledBytes === 4096
+
+const router = new BlobRouter().register(backend);
+router.resolve(message.delta.ops[0].payload); // Uint8Array view, zero copy
+```
+
+The genuine **cross-process** `shm` backend (POSIX `shm_open` + `mmap`) is loaded
+lazily and only where a runtime provides FFI — Node (via `koffi`), Bun (`bun:ffi`),
+or Deno (`Deno.dlopen`, needs `--allow-ffi --unstable-ffi`). A peer process on the
+same host that attaches the same name resolves the descriptor without copying
+across the process boundary. In the browser (or any runtime without FFI)
+`createShmBackend` rejects with `ShmUnavailableError`; guard with `shmSupported()`
+and fall back to `InProcessBackend` / `ArrowBackend`.
+
+```js
+import { createShmBackend, shmSupported } from "@lazily-hub/lazily-js/transport";
+
+if (shmSupported()) {
+  const shm = await createShmBackend("my-session", { capacity: 1 << 20 });
+  const ref = shm.write(new Uint8Array([1, 2, 3])); // ref.backend === "shm"
+  // ...ship `ref` to a peer; the peer attaches `createShmBackend("my-session",
+  // { capacity: 1 << 20, create: false })` and calls `shm.readView(ref)`.
+  shm.close();
+}
+```
+
+All three runtimes are verified end-to-end, including cross-runtime interop: a
+Node process writes a region that a separate Deno process attaches and resolves,
+proving the layout is byte-identical across FFI implementations. The `shm` region
+is a bump-allocated arena with a fixed header (magic / version / capacity / epoch
+/ generation / cursor) and per-entry `{ generation, epoch, len, checksum }`
+validation.
+
 ## Distributed plane
 
 The `@lazily-hub/lazily-js/signaling` and `@lazily-hub/lazily-js/distributed`
@@ -384,7 +489,11 @@ lazily-js replays the shared `lazily-spec` fixtures for IPC, agent-doc state,
 keyed collections (`CellMap`, `CellTree`, LIS reconciliation), semantic tree,
 sequence and text CRDTs (incl. `TextCrdt` delta sync, `#lztextsync`:
 `textcrdt_convergence.json` + `textcrdt_delta_sync.json`), manufactured text
-identity, Harel state charts, the signaling protocol (`signaling/frames.json`,
+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
+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`).
 It also validates generated wire values against the canonical JSON Schemas.
@@ -404,6 +513,7 @@ names the Lean theorems it mirrors:
 | `Reactive` | `reactive-properties.test.js` | `setCell_equal_preserves_graph`, `setCell_different_invalidates_dependents`, `recomputeSlot_equal_preserves_dependents`, `recomputeSlot_different_invalidates_dependents`, `signal_materialized_after_recompute` |
 | `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` |
 | `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` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazily-hub/lazily-js",
-  "version": "0.7.0",
+  "version": "0.9.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": {
@@ -15,6 +15,10 @@
       "types": "./src/index.d.ts",
       "default": "./src/index.js"
     },
+    "./transport": {
+      "types": "./src/transport.d.ts",
+      "default": "./src/transport.js"
+    },
     "./reactive": {
       "types": "./src/reactive.d.ts",
       "default": "./src/reactive.js"
@@ -23,6 +27,10 @@
       "types": "./src/reactive-async.d.ts",
       "default": "./src/reactive-async.js"
     },
+    "./reactive-family": {
+      "types": "./src/reactive-family.d.ts",
+      "default": "./src/reactive-family.js"
+    },
     "./state-machine": {
       "types": "./src/state-machine.d.ts",
       "default": "./src/state-machine.js"
@@ -73,7 +81,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/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/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/index.d.ts

@@ -2,6 +2,14 @@ export type NodeId = number;
 export type PeerId = number;
 export type WireBytes = readonly number[] | Uint8Array;
 
+export type BlobBackendKindValue = "shm" | "arrow" | "in_process";
+
+export const BlobBackendKind: {
+  readonly Shm: "shm";
+  readonly Arrow: "arrow";
+  readonly InProcess: "in_process";
+};
+
 export class ShmBlobRef {
   constructor(fields: {
     offset: number;
@@ -9,12 +17,15 @@ export class ShmBlobRef {
     generation: number;
     epoch: number;
     checksum: number;
+    backend?: BlobBackendKindValue;
   });
   readonly offset: number;
   readonly len: number;
   readonly generation: number;
   readonly epoch: number;
   readonly checksum: number;
+  readonly backend: BlobBackendKindValue;
+  withBackend(backend: BlobBackendKindValue): ShmBlobRef;
   toWire(): ShmBlobRefWire;
   static fromWire(value: ShmBlobRefWire): ShmBlobRef;
 }
@@ -25,6 +36,7 @@ export type ShmBlobRefWire = {
   generation: number;
   epoch: number;
   checksum: number;
+  backend?: BlobBackendKindValue;
 };
 
 export class NodeStatePayload {

package/src/index.js

@@ -73,24 +73,62 @@ function normalizeNodeKey(key) {
   return key;
 }
 
+// The pluggable blob backends a descriptor may name (zero-copy transport,
+// `#lzzcpy`). `shm` is the default and is omitted from the wire so legacy
+// descriptors round-trip byte-for-byte. See src/transport.js and
+// lazily-spec/docs/zero-copy-transport.md.
+export const BlobBackendKind = Object.freeze({
+  Shm: "shm",
+  Arrow: "arrow",
+  InProcess: "in_process",
+});
+
+const BLOB_BACKEND_KINDS = new Set(Object.values(BlobBackendKind));
+
 export class ShmBlobRef {
-  constructor({ offset, len, generation, epoch, checksum }) {
+  constructor({ offset, len, generation, epoch, checksum, backend }) {
     this.offset = assertInteger(offset, "offset");
     this.len = assertInteger(len, "len");
     this.generation = assertInteger(generation, "generation");
     this.epoch = assertInteger(epoch, "epoch");
     this.checksum = assertInteger(checksum, "checksum");
+    // Optional pluggable-backend discriminator. Defaults to `shm` so every
+    // pre-transport descriptor keeps meaning "POSIX shared memory".
+    const kind = backend ?? BlobBackendKind.Shm;
+    if (!BLOB_BACKEND_KINDS.has(kind)) {
+      throw new TypeError(`unknown blob backend: ${kind}`);
+    }
+    this.backend = kind;
     Object.freeze(this);
   }
 
+  // Return a copy of this descriptor tagged for `backend`. Backends stamp their
+  // own kind onto an arena-minted descriptor via this helper.
+  withBackend(backend) {
+    return new ShmBlobRef({
+      offset: this.offset,
+      len: this.len,
+      generation: this.generation,
+      epoch: this.epoch,
+      checksum: this.checksum,
+      backend,
+    });
+  }
+
   toWire() {
-    return {
+    const wire = {
       offset: this.offset,
       len: this.len,
       generation: this.generation,
       epoch: this.epoch,
       checksum: this.checksum,
     };
+    // Omit the default `shm` so the descriptor stays byte-compatible with the
+    // pre-`#lzzcpy` wire form (the `backend`-absent conformance fixture).
+    if (this.backend !== BlobBackendKind.Shm) {
+      wire.backend = this.backend;
+    }
+    return wire;
   }
 
   static fromWire(value) {
@@ -101,6 +139,7 @@ export class ShmBlobRef {
       generation: object.generation,
       epoch: object.epoch,
       checksum: object.checksum,
+      backend: object.backend ?? BlobBackendKind.Shm,
     });
   }
 }

package/src/reactive-family.d.ts

@@ -0,0 +1,100 @@
+import type { CellHandle, Context, SlotHandle } from "./reactive.js";
+
+/**
+ * Which kind of reactive node a {@link ReactiveFamily} entry is — the
+ * handle-kind axis the family abstracts over, orthogonal to
+ * {@link MaterializationMode}.
+ */
+export const EntryKind: {
+  /** An input cell — always materialized, any mode. */
+  readonly Cell: "cell";
+  /** A derived slot — materialized eagerly, or lazily on first read. */
+  readonly Slot: "slot";
+};
+export type EntryKind = (typeof EntryKind)[keyof typeof EntryKind];
+
+/**
+ * When a {@link ReactiveFamily}'s derived (slot) entries are allocated.
+ * Orthogonal to {@link EntryKind}; never observable on the value axis.
+ */
+export const MaterializationMode: {
+  /** Allocate every derived node up front at build time. Required default. */
+  readonly Eager: "eager";
+  /** Allocate a derived node on its first read, keyed rather than held. */
+  readonly Lazy: "lazy";
+};
+export type MaterializationMode =
+  (typeof MaterializationMode)[keyof typeof MaterializationMode];
+
+/** The default materialization mode (eager). */
+export const DEFAULT_MATERIALIZATION_MODE: MaterializationMode;
+
+export type EntryKindResolver<K> = EntryKind | ((key: K) => EntryKind);
+export type FamilyHandle<V> = CellHandle<V> | SlotHandle<V>;
+
+/**
+ * The unified keyed reactive family (`#lzmatmode`): keys map to per-entry
+ * reactive nodes (input cells or derived slots), allocated per the family's
+ * {@link MaterializationMode}.
+ */
+export class ReactiveFamily<K = unknown, V = unknown> {
+  constructor(
+    ctx: Context,
+    mode: MaterializationMode,
+    keys: Iterable<K>,
+    factory: (key: K) => V,
+    entryKind?: EntryKindResolver<K>,
+  );
+
+  /** Build an eager family: every declared key's node is allocated now. */
+  static eager<K, V>(
+    ctx: Context,
+    keys: Iterable<K>,
+    factory: (key: K) => V,
+    entryKind?: EntryKindResolver<K>,
+  ): ReactiveFamily<K, V>;
+
+  /** Build a lazy family: derived (slot) entries are deferred to first read. */
+  static lazy<K, V>(
+    ctx: Context,
+    keys: Iterable<K>,
+    factory: (key: K) => V,
+    entryKind?: EntryKindResolver<K>,
+  ): ReactiveFamily<K, V>;
+
+  /** Build a family in the default (eager) mode. */
+  static create<K, V>(
+    ctx: Context,
+    keys: Iterable<K>,
+    factory: (key: K) => V,
+    entryKind?: EntryKindResolver<K>,
+  ): ReactiveFamily<K, V>;
+
+  /** Materialize (lazy pull) and return the entry handle for `key`. */
+  get(key: K): FamilyHandle<V>;
+  /** Observe `key`'s value — identical under either mode. */
+  observe(key: K): 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 ReactiveFamily}: a keyed family whose
+ * entries are all input cells (always materialized).
+ */
+export function cellFamily<K, V>(
+  ctx: Context,
+  keys: Iterable<K>,
+  factory: (key: K) => V,
+  mode?: MaterializationMode,
+): ReactiveFamily<K, V>;