@graphrefly/graphrefly 0.17.0 → 0.19.0

package/dist/{meta-BV4pj9ML.d.ts → meta-BnG7XAaE.d.ts}

@@ -1,3 +1,206 @@
+/**
+ * GraphReFly message protocol — §1 `~/src/graphrefly/GRAPHREFLY-SPEC.md`.
+ * Emissions are always `[[Type, Data?], ...]` (no single-tuple shorthand).
+ *
+ * ## Canonical message ordering (within a composite batch)
+ *
+ * When multiple message types appear in a single `down()` call, the canonical
+ * delivery order is determined by **signal tier**:
+ *
+ * | Tier | Signals                | Role              | Batch behavior                      |
+ * |------|------------------------|-------------------|-------------------------------------|
+ * |  0   | START                  | Subscribe handshake | Immediate (never deferred)        |
+ * |  1   | DIRTY, INVALIDATE      | Notification      | Immediate (never deferred)          |
+ * |  2   | PAUSE, RESUME          | Flow control      | Immediate (never deferred)          |
+ * |  3   | DATA, RESOLVED         | Value settlement  | Deferred inside `batch()`           |
+ * |  4   | COMPLETE, ERROR        | Terminal lifecycle | Deferred to after phase-2          |
+ * |  5   | TEARDOWN               | Destruction       | Immediate (usually sent alone)      |
+ *
+ * **Rule:** Within `downWithBatch`, messages are partitioned by tier and delivered
+ * in tier order. This ensures phase-2 values (DATA/RESOLVED) reach sinks before
+ * terminal signals (COMPLETE/ERROR) mark the node as done, preventing the
+ * "COMPLETE-before-DATA" class of bugs. Sources that emit in canonical order
+ * naturally partition correctly with zero overhead.
+ *
+ * Unknown message types (forward-compat) are tier 1 (immediate).
+ *
+ * ## Meta node bypass rules (centralized — GRAPHREFLY-SPEC §2.3)
+ *
+ * - **INVALIDATE** via `graph.signal()` — no-op on meta nodes (cached values preserved).
+ * - **COMPLETE / ERROR** — not propagated from parent to meta (meta outlives terminal
+ *   state for post-mortem writes like setting `meta.error` after ERROR).
+ * - **TEARDOWN** — propagated from parent to meta, releasing meta resources.
+ */
+/**
+ * Subscribe-time handshake (`START`). Delivered to each new sink at the top of
+ * `subscribe()` — `[[START]]` for a SENTINEL (no cached value) node or
+ * `[[START], [DATA, cached]]` for a node with a cached value.
+ *
+ * Semantics: "upstream connected and ready to flow." A new sink receiving
+ * `[[START]]` alone knows the upstream is alive but has no current value; a
+ * sink receiving `[[START], [DATA, v]]` knows the upstream is ready
+ * with value `v`. Absence of `START` before any other message means the
+ * subscription was either never established or the node is terminal.
+ *
+ * Tier 0 — immediate, delivered before any DIRTY/DATA in the same batch.
+ * Not forwarded through nodes — each node emits its own `START` to its own
+ * new sinks.
+ */
+declare const START: unique symbol;
+/** Value delivery (`DATA`, value). Tier 3 — deferred inside `batch()`. */
+declare const DATA: unique symbol;
+/** Phase 1: value about to change. Tier 1 — immediate. */
+declare const DIRTY: unique symbol;
+/** Phase 2: dirty pass completed, value unchanged. Tier 3 — deferred inside `batch()`. */
+declare const RESOLVED: unique symbol;
+/** Clear cached state; do not auto-emit. Tier 1 — immediate. */
+declare const INVALIDATE: unique symbol;
+/** Suspend activity. Tier 2 — immediate. */
+declare const PAUSE: unique symbol;
+/** Resume after pause. Tier 2 — immediate. */
+declare const RESUME: unique symbol;
+/** Permanent cleanup. Tier 5 — immediate (usually sent alone). */
+declare const TEARDOWN: unique symbol;
+/** Clean termination. Tier 4 — delivered after phase-2 in the same batch. */
+declare const COMPLETE: unique symbol;
+/** Error termination. Tier 4 — delivered after phase-2 in the same batch. */
+declare const ERROR: unique symbol;
+/** Known protocol type symbols (open set — other symbols are valid and forward). */
+declare const knownMessageTypes: readonly symbol[];
+/** One protocol tuple: `[Type, optional payload]`. */
+type Message = readonly [symbol, unknown?];
+/**
+ * A batch of tuples — the wire shape for `node.down()` / `node.up()`.
+ */
+type Messages = readonly Message[];
+/**
+ * Whether `t` is one of the built-in protocol symbols in this module.
+ *
+ * @param t — Message type symbol (unknown types are still valid; they must forward).
+ * @returns `true` for `DATA`, `DIRTY`, `RESOLVED`, etc.
+ *
+ * @example
+ * ```ts
+ * import { DATA, DIRTY, isKnownMessageType } from "@graphrefly/graphrefly-ts";
+ *
+ * isKnownMessageType(DATA);             // true
+ * isKnownMessageType(Symbol("custom")); // false
+ * ```
+ */
+declare function isKnownMessageType(t: symbol): boolean;
+/**
+ * Returns the signal tier for a message type (see module-level ordering table).
+ *
+ * - 0: subscribe handshake (START) — immediate, first in canonical order
+ * - 1: notification (DIRTY, INVALIDATE) — immediate
+ * - 2: flow control (PAUSE, RESUME) — immediate
+ * - 3: value (DATA, RESOLVED) — deferred inside `batch()`
+ * - 4: terminal (COMPLETE, ERROR) — delivered after phase-3
+ * - 5: destruction (TEARDOWN) — immediate, usually alone
+ * - 1 for unknown types (forward-compat: immediate)
+ *
+ * @param t — Message type symbol.
+ * @returns Tier number (0–5).
+ *
+ * @example
+ * ```ts
+ * import { DATA, DIRTY, COMPLETE, TEARDOWN, messageTier, START } from "@graphrefly/graphrefly-ts";
+ *
+ * messageTier(START);    // 0
+ * messageTier(DIRTY);    // 1
+ * messageTier(DATA);     // 3
+ * messageTier(COMPLETE); // 4
+ * messageTier(TEARDOWN); // 5
+ * ```
+ */
+declare function messageTier(t: symbol): number;
+/**
+ * Returns whether this tuple is deferred by `batch()` (phase 2: `DATA` or `RESOLVED`).
+ *
+ * @param msg — Single message tuple.
+ * @returns `true` if `msg` is `DATA` or `RESOLVED`.
+ *
+ * @example
+ * ```ts
+ * import { DATA, RESOLVED, DIRTY, isPhase2Message } from "@graphrefly/graphrefly-ts";
+ *
+ * isPhase2Message([DATA, 42]);   // true
+ * isPhase2Message([RESOLVED]);   // true
+ * isPhase2Message([DIRTY]);      // false
+ * ```
+ */
+declare function isPhase2Message(msg: Message): boolean;
+/**
+ * Returns whether this message type is terminal (COMPLETE or ERROR).
+ * Terminal messages are delivered after phase-2 in the same batch to prevent
+ * the node from becoming terminal before value messages reach sinks.
+ *
+ * @param t — Message type symbol.
+ * @returns `true` for `COMPLETE` or `ERROR`.
+ *
+ * @example
+ * ```ts
+ * import { COMPLETE, ERROR, DATA, isTerminalMessage } from "@graphrefly/graphrefly-ts";
+ *
+ * isTerminalMessage(COMPLETE); // true
+ * isTerminalMessage(ERROR);    // true
+ * isTerminalMessage(DATA);     // false
+ * ```
+ */
+declare function isTerminalMessage(t: symbol): boolean;
+/**
+ * Whether `t` is a graph-local signal that should NOT cross a wire/transport
+ * boundary (SSE, WebSocket, worker bridge, persistence sinks).
+ *
+ * Local-only signals (tier 0–2): START, DIRTY, INVALIDATE, PAUSE, RESUME.
+ * These are internal to the reactive graph — subscribe handshakes,
+ * notification phases, and flow control have no semantics for remote consumers.
+ *
+ * Wire-crossing signals (tier 3+): DATA, RESOLVED, COMPLETE, ERROR, TEARDOWN.
+ * Unknown message types (spec §1.3.6 forward-compat) also cross the wire.
+ *
+ * Individual adapters may further opt-in to local signals for observability
+ * (e.g. SSE `includeDirty`, `includeResolved` options). Storage/persistence
+ * adapters that need INVALIDATE for remote cache-clear should explicitly
+ * forward it despite `isLocalOnly(INVALIDATE) === true`. The default is to
+ * skip all local-only signals at the boundary.
+ *
+ * @param t — Message type symbol.
+ * @returns `true` if the message should be kept local (not sent over wire).
+ *
+ * @example
+ * ```ts
+ * import { START, DIRTY, DATA, COMPLETE, isLocalOnly } from "@graphrefly/graphrefly-ts";
+ *
+ * isLocalOnly(START);    // true  — subscribe handshake
+ * isLocalOnly(DIRTY);    // true  — notification phase
+ * isLocalOnly(RESOLVED); // false — value settlement crosses wire
+ * isLocalOnly(DATA);     // false — value crosses wire
+ * isLocalOnly(COMPLETE); // false — terminal crosses wire
+ * ```
+ *
+ * @category core
+ */
+declare function isLocalOnly(t: symbol): boolean;
+/**
+ * Whether `t` should be propagated from a parent node to its companion meta nodes.
+ * Only TEARDOWN propagates; COMPLETE/ERROR/INVALIDATE do not (meta outlives parent
+ * terminal state for post-mortem writes).
+ *
+ * @param t — Message type symbol.
+ * @returns `true` if the signal should reach meta nodes.
+ *
+ * @example
+ * ```ts
+ * import { TEARDOWN, COMPLETE, ERROR, propagatesToMeta } from "@graphrefly/graphrefly-ts";
+ *
+ * propagatesToMeta(TEARDOWN); // true
+ * propagatesToMeta(COMPLETE); // false
+ * propagatesToMeta(ERROR);    // false
+ * ```
+ */
+declare function propagatesToMeta(t: symbol): boolean;
+
 /**
  * Who is performing an operation (attribution + ABAC input).
  *
@@ -131,156 +334,6 @@ declare function policyFromRules(rules: readonly PolicyRuleData[]): NodeGuard;
  */
 declare function accessHintForGuard(guard: NodeGuard): string;
 
-/**
- * GraphReFly message protocol — §1 `~/src/graphrefly/GRAPHREFLY-SPEC.md`.
- * Emissions are always `[[Type, Data?], ...]` (no single-tuple shorthand).
- *
- * ## Canonical message ordering (within a composite batch)
- *
- * When multiple message types appear in a single `down()` call, the canonical
- * delivery order is determined by **signal tier**:
- *
- * | Tier | Signals                | Role              | Batch behavior                      |
- * |------|------------------------|-------------------|-------------------------------------|
- * |  0   | DIRTY, INVALIDATE      | Notification      | Immediate (never deferred)          |
- * |  1   | PAUSE, RESUME          | Flow control      | Immediate (never deferred)          |
- * |  2   | DATA, RESOLVED         | Value settlement  | Deferred inside `batch()`           |
- * |  3   | COMPLETE, ERROR        | Terminal lifecycle | Deferred to after phase-2           |
- * |  4   | TEARDOWN               | Destruction       | Immediate (usually sent alone)      |
- *
- * **Rule:** Within `downWithBatch`, messages are partitioned by tier and delivered
- * in tier order. This ensures phase-2 values (DATA/RESOLVED) reach sinks before
- * terminal signals (COMPLETE/ERROR) mark the node as done, preventing the
- * "COMPLETE-before-DATA" class of bugs. Sources that emit in canonical order
- * naturally partition correctly with zero overhead.
- *
- * Unknown message types (forward-compat) are tier 0 (immediate).
- *
- * ## Meta node bypass rules (centralized — GRAPHREFLY-SPEC §2.3)
- *
- * - **INVALIDATE** via `graph.signal()` — no-op on meta nodes (cached values preserved).
- * - **COMPLETE / ERROR** — not propagated from parent to meta (meta outlives terminal
- *   state for post-mortem writes like setting `meta.error` after ERROR).
- * - **TEARDOWN** — propagated from parent to meta, releasing meta resources.
- */
-/** Value delivery (`DATA`, value). Tier 2 — deferred inside `batch()`. */
-declare const DATA: unique symbol;
-/** Phase 1: value about to change. Tier 0 — immediate. */
-declare const DIRTY: unique symbol;
-/** Phase 2: dirty pass completed, value unchanged. Tier 2 — deferred inside `batch()`. */
-declare const RESOLVED: unique symbol;
-/** Clear cached state; do not auto-emit. Tier 0 — immediate. */
-declare const INVALIDATE: unique symbol;
-/** Suspend activity. Tier 1 — immediate. */
-declare const PAUSE: unique symbol;
-/** Resume after pause. Tier 1 — immediate. */
-declare const RESUME: unique symbol;
-/** Permanent cleanup. Tier 4 — immediate (usually sent alone). */
-declare const TEARDOWN: unique symbol;
-/** Clean termination. Tier 3 — delivered after phase-2 in the same batch. */
-declare const COMPLETE: unique symbol;
-/** Error termination. Tier 3 — delivered after phase-2 in the same batch. */
-declare const ERROR: unique symbol;
-/** Known protocol type symbols (open set — other symbols are valid and forward). */
-declare const knownMessageTypes: readonly symbol[];
-/** One protocol tuple: `[Type, optional payload]`. */
-type Message = readonly [symbol, unknown?];
-/**
- * A batch of tuples — the wire shape for `node.down()` / `node.up()`.
- */
-type Messages = readonly Message[];
-/**
- * Whether `t` is one of the built-in protocol symbols in this module.
- *
- * @param t — Message type symbol (unknown types are still valid; they must forward).
- * @returns `true` for `DATA`, `DIRTY`, `RESOLVED`, etc.
- *
- * @example
- * ```ts
- * import { DATA, DIRTY, isKnownMessageType } from "@graphrefly/graphrefly-ts";
- *
- * isKnownMessageType(DATA);             // true
- * isKnownMessageType(Symbol("custom")); // false
- * ```
- */
-declare function isKnownMessageType(t: symbol): boolean;
-/**
- * Returns the signal tier for a message type (see module-level ordering table).
- *
- * - 0: notification (DIRTY, INVALIDATE) — immediate
- * - 1: flow control (PAUSE, RESUME) — immediate
- * - 2: value (DATA, RESOLVED) — deferred inside `batch()`
- * - 3: terminal (COMPLETE, ERROR) — delivered after phase-2
- * - 4: destruction (TEARDOWN) — immediate, usually alone
- * - 0 for unknown types (forward-compat: immediate)
- *
- * @param t — Message type symbol.
- * @returns Tier number (0–4).
- *
- * @example
- * ```ts
- * import { DATA, DIRTY, COMPLETE, TEARDOWN, messageTier } from "@graphrefly/graphrefly-ts";
- *
- * messageTier(DIRTY);    // 0
- * messageTier(DATA);     // 2
- * messageTier(COMPLETE); // 3
- * messageTier(TEARDOWN); // 4
- * ```
- */
-declare function messageTier(t: symbol): number;
-/**
- * Returns whether this tuple is deferred by `batch()` (phase 2: `DATA` or `RESOLVED`).
- *
- * @param msg — Single message tuple.
- * @returns `true` if `msg` is `DATA` or `RESOLVED`.
- *
- * @example
- * ```ts
- * import { DATA, RESOLVED, DIRTY, isPhase2Message } from "@graphrefly/graphrefly-ts";
- *
- * isPhase2Message([DATA, 42]);   // true
- * isPhase2Message([RESOLVED]);   // true
- * isPhase2Message([DIRTY]);      // false
- * ```
- */
-declare function isPhase2Message(msg: Message): boolean;
-/**
- * Returns whether this message type is terminal (COMPLETE or ERROR).
- * Terminal messages are delivered after phase-2 in the same batch to prevent
- * the node from becoming terminal before value messages reach sinks.
- *
- * @param t — Message type symbol.
- * @returns `true` for `COMPLETE` or `ERROR`.
- *
- * @example
- * ```ts
- * import { COMPLETE, ERROR, DATA, isTerminalMessage } from "@graphrefly/graphrefly-ts";
- *
- * isTerminalMessage(COMPLETE); // true
- * isTerminalMessage(ERROR);    // true
- * isTerminalMessage(DATA);     // false
- * ```
- */
-declare function isTerminalMessage(t: symbol): boolean;
-/**
- * Whether `t` should be propagated from a parent node to its companion meta nodes.
- * Only TEARDOWN propagates; COMPLETE/ERROR/INVALIDATE do not (meta outlives parent
- * terminal state for post-mortem writes).
- *
- * @param t — Message type symbol.
- * @returns `true` if the signal should reach meta nodes.
- *
- * @example
- * ```ts
- * import { TEARDOWN, COMPLETE, ERROR, propagatesToMeta } from "@graphrefly/graphrefly-ts";
- *
- * propagatesToMeta(TEARDOWN); // true
- * propagatesToMeta(COMPLETE); // false
- * propagatesToMeta(ERROR);    // false
- * ```
- */
-declare function propagatesToMeta(t: symbol): boolean;
-
 /**
  * Node versioning — GRAPHREFLY-SPEC §7.
  *
@@ -346,23 +399,44 @@ declare function advanceVersion(info: NodeVersionInfo, newValue: unknown, hashFn
 declare function isV1(info: NodeVersionInfo): info is V1;
 
 /**
- * Branded symbol that marks a {@link CleanupResult} wrapper.
- * Used internally by {@link cleanupResult} — prevents duck-type collisions
- * with domain objects that happen to have a `cleanup` property.
+ * `NodeBase` — abstract class implementing the {@link Node} protocol with
+ * lifecycle machinery shared between {@link NodeImpl} (static deps) and
+ * {@link DynamicNodeImpl} (runtime-tracked deps).
+ *
+ * **Responsibilities (shared):**
+ * - Identity (name, describeKind, meta, guard, versioning)
+ * - Cache + status lifecycle (`_cached`, `_status`, `_terminal`)
+ * - Sink storage (null / single / Set fast paths)
+ * - `subscribe()` with START handshake + first-subscriber activation
+ * - `_downInternal` → `_downToSinks` delivery pipeline (via `downWithBatch`)
+ * - `_downAutoValue` (value → protocol framing with equals)
+ * - `_handleLocalLifecycle` (cached/status/terminal updates + meta propagation)
+ *
+ * **Subclass hooks (abstract):**
+ * - `_onActivate()` — called when sinkCount transitions 0 → 1
+ * - `_doDeactivate()` — cleanup on deactivation (at-most-once, guarded by `_onDeactivate`)
+ * - `up()` / `unsubscribe()` / `_upInternal()` — dep-iteration specifics
+ * - `_createMetaNode()` — meta companion factory (avoids circular imports)
+ *
+ * See GRAPHREFLY-SPEC §2 and COMPOSITION-GUIDE §1 for protocol contracts.
+ */
+
+/**
+ * Internal sentinel value: "no cached value has been set or emitted."
+ * Used instead of `undefined` so that `undefined` can be a valid emitted value.
+ */
+declare const NO_VALUE: unique symbol;
+/**
+ * Branded symbol that marks a {@link CleanupResult} wrapper — prevents
+ * duck-type collisions with domain objects that happen to have a `cleanup`
+ * property.
  */
 declare const CLEANUP_RESULT: unique symbol;
-/** Lifecycle status of a node. */
-type NodeStatus = "disconnected" | "dirty" | "settled" | "resolved" | "completed" | "errored";
+/** Lifecycle status of a node (GRAPHREFLY-SPEC §2.2). */
+type NodeStatus = "disconnected" | "pending" | "dirty" | "settled" | "resolved" | "completed" | "errored";
 /** Callback that receives downstream message batches. */
 type NodeSink = (messages: Messages) => void;
-/**
- * Compute function passed to `node()`.
- *
- * @returns A value to emit, `undefined` to skip emission, or a cleanup
- *   function invoked before the next run or on teardown.
- */
-type NodeFn<T = unknown> = (deps: readonly unknown[], actions: NodeActions) => T | undefined | (() => void);
-/** Imperative actions available inside a {@link NodeFn}. */
+/** Imperative actions available inside a node's compute function. */
 interface NodeActions {
     /** Emit raw messages downstream. */
     down(messages: Messages): void;
@@ -372,14 +446,10 @@ interface NodeActions {
     up(messages: Messages): void;
 }
 /**
- * Callback for intercepting messages before the default dispatch.
- *
- * Called for every message from every dep. Return `true` to consume the
- * message (skip default handling), or `false` to let default dispatch run.
+ * Callback for intercepting messages before the default dispatch (§2.6).
  *
- * @param msg      — The message tuple `[Type, Data?]`.
- * @param depIndex — Which dep sent it (index into the deps array).
- * @param actions  — `{ down(), emit(), up() }` — same as `NodeFn` receives.
+ * Called for every message from every dep. Return `true` to consume
+ * (skip default handling), or `false` to let default dispatch run.
  */
 type OnMessageHandler = (msg: Message, depIndex: number, actions: NodeActions) => boolean;
 /**
@@ -395,9 +465,9 @@ type NodeInspectorHookEvent = {
     depValues: readonly unknown[];
 };
 type NodeInspectorHook = (event: NodeInspectorHookEvent) => void;
-/** Explicit describe `type` for {@link Graph.describe} / {@link describeNode} (GRAPHREFLY-SPEC Appendix B). */
+/** Explicit describe `type` for {@link Graph.describe} (GRAPHREFLY-SPEC Appendix B). */
 type NodeDescribeKind = "state" | "derived" | "producer" | "operator" | "effect";
-/** Options for {@link node}. */
+/** Options accepted by every node constructor. */
 interface NodeOptions {
     name?: string;
     /**
@@ -411,7 +481,7 @@ interface NodeOptions {
     /**
      * Each key becomes an independently subscribable companion node.
      * Meta nodes outlive the parent's subscription lifecycle: when all sinks
-     * unsubscribe the parent disconnects upstream but meta nodes stay alive.
+     * unsubscribe the parent deactivates but meta nodes stay alive.
      * Send `[[TEARDOWN]]` to the parent to release meta node resources.
      */
     meta?: Record<string, unknown>;
@@ -442,20 +512,14 @@ interface NodeOptions {
      * Companion {@link NodeOptions.meta | meta} nodes inherit this guard from the primary.
      */
     guard?: NodeGuard;
-    /**
-     * Opt-in versioning level (GRAPHREFLY-SPEC §7).
-     * - `0` (V0): `id` + `version` — identity & change detection.
-     * - `1` (V1): + `cid` + `prev` — content addressing & linked history.
-     */
+    /** Opt-in versioning level (GRAPHREFLY-SPEC §7). */
     versioning?: VersioningLevel;
     /** Override auto-generated versioning id. */
     versioningId?: string;
     /** Custom hash function for V1 cid computation. */
     versioningHash?: HashFn;
 }
-/**
- * Options for {@link Node.down} / {@link Node.up} (actor context, graph delivery mode, internal bypass).
- */
+/** Actor/delivery context for {@link Node.down} and {@link Node.up}. */
 type NodeTransportOptions = {
     actor?: Actor;
     /**
@@ -464,25 +528,23 @@ type NodeTransportOptions = {
      */
     internal?: boolean;
     /**
-     * `signal` for {@link Graph.signal} deliveries; default `write` for {@link Graph.set} and direct `down`.
+     * `signal` for {@link Graph.signal} deliveries; default `write` for {@link Graph.set}
+     * and direct `down`.
      */
     delivery?: "write" | "signal";
 };
-/**
- * Optional hints passed to {@link Node.subscribe} to enable per-sink
- * optimizations.
- */
+/** Optional hints passed to {@link Node.subscribe}. */
 interface SubscribeHints {
     /**
      * Subscriber has exactly one dep with `fn` — the source may skip DIRTY
      * dispatch when this is the sole subscriber. The subscriber synthesizes
-     * dirty state locally via `onDepSettled`.
+     * dirty state locally.
      */
     singleDep?: boolean;
     /**
-     * Actor to check against the node's `observe` guard.
-     * When set, `subscribe()` throws {@link GuardDenied} if the actor is not
-     * permitted to observe this node. Aligned with graphrefly-py `subscribe(actor=)`.
+     * Actor to check against the node's `observe` guard. When set,
+     * `subscribe()` throws {@link GuardDenied} if the actor is not permitted
+     * to observe this node.
      */
     actor?: Actor;
 }
@@ -512,7 +574,7 @@ interface Node<T = unknown> {
         actor: Actor;
         timestamp_ns: number;
     }>;
-    /** Whether {@link NodeTransportOptions.actor | actor} may {@link Graph.observe | observe} this node. */
+    /** Whether `actor` may {@link Graph.observe} this node. */
     allowsObserve(actor: Actor): boolean;
     /** Whether a {@link NodeOptions.guard | guard} is installed. */
     hasGuard(): boolean;
@@ -524,60 +586,154 @@ interface Node<T = unknown> {
  * `cleanup` is registered as the teardown/recompute cleanup and `value`
  * (if present) is emitted as data. This avoids the ambiguity where returning
  * a plain function is silently consumed as cleanup instead of emitted as data.
- *
- * Use the {@link cleanupResult} factory to create instances — it stamps the
- * branded {@link CLEANUP_RESULT} symbol so that domain objects with a `cleanup`
- * property are never misinterpreted.
- *
- * Plain function returns are still treated as cleanup for backward compatibility.
  */
 type CleanupResult<T = unknown> = {
     readonly [CLEANUP_RESULT]: true;
     cleanup: () => void;
     value?: T;
 };
-/**
- * Create a branded {@link CleanupResult}.
- *
- * ```ts
- * node([dep], () => cleanupResult(() => release(), computedValue))
- * ```
- */
+/** Create a branded {@link CleanupResult}. */
 declare function cleanupResult<T>(cleanup: () => void): CleanupResult<T>;
 declare function cleanupResult<T>(cleanup: () => void, value: T): CleanupResult<T>;
 /**
- * Creates a reactive {@link Node} — the single GraphReFly primitive (GRAPHREFLY-SPEC §2).
- *
- * Typical shapes: `node([])` / `node([], opts)` for a manual source; `node(producerFn, opts)` for a
- * producer; `node(deps, computeFn, opts)` for derived nodes and operators.
- *
- * @param depsOrFn - Dependency nodes, a {@link NodeFn} (producer), or {@link NodeOptions} alone.
- * @param fnOrOpts - With deps: compute function or options. Omitted for producer-only form.
- * @param optsArg - Options when both `deps` and `fn` are provided.
- * @returns `Node<T>` - Configured node instance (lazy until subscribed).
- *
- * @remarks
- * **Protocol:** DIRTY / DATA / RESOLVED ordering, completion, and batch deferral follow `~/src/graphrefly/GRAPHREFLY-SPEC.md`.
- *
- * **`equals` and mutable values:** The default `Object.is` identity check is
- * correct for the common immutable-value case. If your node produces mutable
- * objects (e.g. arrays or maps mutated in place), provide a custom `equals`
- * function — otherwise `Object.is` will always return `true` for the same
- * reference and the node will emit `RESOLVED` instead of `DATA`.
- *
- * @example
- * ```ts
- * import { node, state } from "@graphrefly/graphrefly-ts";
- *
- * const a = state(1);
- * const b = node([a], ([x]) => (x as number) + 1);
- * ```
- *
- * @seeAlso [Specification](/spec)
- *
- * @category core
- */
-declare function node<T = unknown>(depsOrFn?: readonly Node[] | NodeFn<T> | NodeOptions, fnOrOpts?: NodeFn<T> | NodeOptions, optsArg?: NodeOptions): Node<T>;
+ * Abstract base class for every node in the graph. Both {@link NodeImpl}
+ * (static deps) and {@link DynamicNodeImpl} (runtime-tracked deps) extend
+ * this to share subscribe/sink/lifecycle machinery.
+ *
+ * Invariants (see GRAPHREFLY-SPEC §2.2):
+ * - `_sinkCount` always reflects the size of `_sinks`.
+ * - `_cached === NO_VALUE` iff the node has never produced a value (SENTINEL).
+ * - `_terminal` is set exactly once (per subscription cycle for resubscribable).
+ * - `_onActivate` runs exactly once per activation cycle; `_doDeactivate`
+ *   runs at most once per deactivation (guarded by `_active` flag).
+ *
+ * ROM/RAM rule (GRAPHREFLY-SPEC §2.2): state nodes (no fn) preserve `_cached`
+ * across disconnect — intrinsic, non-volatile. Compute nodes (derived,
+ * producer, dynamic) clear `_cached` on disconnect in their subclass
+ * `_doDeactivate` — their value is a function of live subscriptions.
+ */
+declare abstract class NodeBase<T = unknown> implements Node<T> {
+    protected readonly _optsName: string | undefined;
+    private _registryName;
+    /** @internal Read by `describeNode` before inference. */
+    readonly _describeKind: NodeDescribeKind | undefined;
+    readonly meta: Record<string, Node>;
+    protected readonly _equals: (a: unknown, b: unknown) => boolean;
+    protected readonly _resubscribable: boolean;
+    protected readonly _resetOnTeardown: boolean;
+    protected readonly _onResubscribe: (() => void) | undefined;
+    protected readonly _onMessage: OnMessageHandler | undefined;
+    /** @internal Read by `describeNode` for `accessHintForGuard`. */
+    readonly _guard: NodeGuard | undefined;
+    /** @internal Subclasses update this through {@link _recordMutation}. */
+    protected _lastMutation: {
+        actor: Actor;
+        timestamp_ns: number;
+    } | undefined;
+    protected _hashFn: HashFn;
+    private _versioning;
+    /** @internal Read by `describeNode` and `graph.ts`. */
+    _cached: T | typeof NO_VALUE;
+    /** @internal Read externally via `get status()`. */
+    _status: NodeStatus;
+    protected _terminal: boolean;
+    private _active;
+    /** @internal Read by `graph/profile.ts` for subscriber counts. */
+    _sinkCount: number;
+    protected _singleDepSinkCount: number;
+    protected _singleDepSinks: WeakSet<NodeSink>;
+    protected _sinks: NodeSink | Set<NodeSink> | null;
+    protected readonly _actions: NodeActions;
+    protected readonly _boundDownToSinks: (messages: Messages) => void;
+    private _inspectorHook;
+    constructor(opts: NodeOptions);
+    /**
+     * Subclass hook invoked by `actions.down` / `actions.emit`. Default no-op;
+     * {@link NodeImpl} overrides to set `_manualEmitUsed`.
+     */
+    protected _onManualEmit(): void;
+    /**
+     * Create a companion meta node. Called from the base constructor; must
+     * not touch subclass fields that haven't been initialized yet (safe to
+     * read from `opts`).
+     */
+    protected abstract _createMetaNode(key: string, initialValue: unknown, opts: NodeOptions): Node;
+    get name(): string | undefined;
+    /** @internal Assigned by `Graph.add` when registered without an options `name`. */
+    _assignRegistryName(localName: string): void;
+    /**
+     * @internal Attach/remove inspector hook for graph-level observability.
+     * Returns a disposer that restores the previous hook.
+     */
+    _setInspectorHook(hook?: NodeInspectorHook): () => void;
+    /** @internal Used by subclasses to surface inspector events. */
+    protected _emitInspectorHook(event: NodeInspectorHookEvent): void;
+    get status(): NodeStatus;
+    get lastMutation(): Readonly<{
+        actor: Actor;
+        timestamp_ns: number;
+    }> | undefined;
+    get v(): Readonly<NodeVersionInfo> | undefined;
+    /** @internal Used by `Graph.setVersioning` to retroactively apply versioning. */
+    _applyVersioning(level: VersioningLevel, opts?: {
+        id?: string;
+        hash?: HashFn;
+    }): void;
+    hasGuard(): boolean;
+    allowsObserve(actor: Actor): boolean;
+    get(): T | undefined;
+    down(messages: Messages, options?: NodeTransportOptions): void;
+    /** @internal Record a successful guarded mutation (called by `down` and subclass `up`). */
+    protected _recordMutation(actor: Actor): void;
+    /** Abstract — subclasses forward messages to dependencies (or no-op for sources). */
+    abstract up(messages: Messages, options?: NodeTransportOptions): void;
+    /** Abstract — subclasses release upstream subscriptions (or no-op for sources). */
+    abstract unsubscribe(): void;
+    /** Internal upstream-send used by `actions.up`. */
+    protected abstract _upInternal(messages: Messages): void;
+    /** Called when `_sinkCount` transitions 0 → 1. */
+    protected abstract _onActivate(): void;
+    /**
+     * At-most-once deactivation guard. Both TEARDOWN (eager) and
+     * unsubscribe-body (lazy) call this. The `_active` flag ensures
+     * `_doDeactivate` runs exactly once per activation cycle.
+     */
+    protected _onDeactivate(): void;
+    /** Subclass hook: cleanup on deactivation (called at most once). */
+    protected abstract _doDeactivate(): void;
+    subscribe(sink: NodeSink, hints?: SubscribeHints): () => void;
+    /**
+     * Core outgoing dispatch. Applies terminal filter + local lifecycle
+     * update, then hands messages to `downWithBatch` for tier-aware delivery.
+     */
+    protected _downInternal(messages: Messages): void;
+    protected _canSkipDirty(): boolean;
+    protected _downToSinks(messages: Messages): void;
+    /**
+     * Update `_cached`, `_status`, `_terminal` from message batch before
+     * delivery. Subclass hooks `_onInvalidate` / `_onTeardown` let
+     * {@link NodeImpl} clear `_lastDepValues` and invoke cleanup fns.
+     */
+    protected _handleLocalLifecycle(messages: Messages): void;
+    /**
+     * Subclass hook: invoked when INVALIDATE arrives (before `_cached` is
+     * cleared). {@link NodeImpl} uses this to run the fn cleanup fn and
+     * drop `_lastDepValues` so the next wave re-runs fn.
+     */
+    protected _onInvalidate(): void;
+    /**
+     * Subclass hook: invoked when TEARDOWN arrives, before `_onDeactivate`.
+     * {@link NodeImpl} uses this to run any pending cleanup fn.
+     */
+    protected _onTeardown(): void;
+    /** Forward a signal to all companion meta nodes (best-effort). */
+    protected _propagateToMeta(t: symbol): void;
+    /**
+     * Frame a computed value into the right protocol messages and dispatch
+     * via `_downInternal`. Used by `_runFn` and `actions.emit`.
+     */
+    protected _downAutoValue(value: unknown): void;
+}
 
 /** JSON-shaped slice of a node for Phase 1 `Graph.describe()` (GRAPHREFLY-SPEC §3.6, Appendix B). */
 type DescribeNodeOutput = {
@@ -587,6 +743,8 @@ type DescribeNodeOutput = {
     meta?: Record<string, unknown>;
     name?: string;
     value?: unknown;
+    /** True when the node has never received or been initialized with a value (cache holds SENTINEL). */
+    sentinel?: boolean;
     /** Node versioning info (GRAPHREFLY-SPEC §7). Present only when versioning is enabled. */
     v?: {
         id: string;
@@ -616,57 +774,5 @@ type DescribeDetail = "minimal" | "standard" | "full";
 type DescribeField = "type" | "status" | "value" | "deps" | "meta" | "v" | "guard" | "lastMutation" | `meta.${string}`;
 /** Resolve which fields to include based on detail level or explicit field list. */
 declare function resolveDescribeFields(detail?: DescribeDetail, fields?: readonly DescribeField[]): Set<string> | null;
-/**
- * Reads the current cached value of every companion meta field on a node,
- * suitable for merging into `describe()`-style JSON (GRAPHREFLY-SPEC §2.3, §3.6).
- *
- * @remarks
- * Values come from {@link Node.get}, which returns the **last settled** cache.
- * If a meta field is in `"dirty"` status (DIRTY received, DATA pending), the
- * snapshot contains the *previous* value — check `node.meta[key].status` when
- * freshness matters. Avoid calling mid-batch for the same reason.
- *
- * Meta nodes are **not** terminated when their parent receives COMPLETE or
- * ERROR — they remain writable so callers can record post-mortem metadata
- * (e.g. `meta.error`). They *are* torn down when the parent receives TEARDOWN.
- *
- * @param node - The node whose meta fields to snapshot.
- * @returns Plain object of `{ key: value }` pairs (empty if no meta defined).
- * Keys whose companion node's {@link Node.get} throws are omitted.
- *
- * @example
- * ```ts
- * import { core } from "@graphrefly/graphrefly-ts";
- *
- * const n = core.node({ initial: 0, meta: { tag: "a" } });
- * core.metaSnapshot(n); // { tag: "a" }
- * ```
- */
-declare function metaSnapshot(node: Node): Record<string, unknown>;
-/**
- * Builds a single-node slice of `Graph.describe()` JSON (structure + `meta` snapshot).
- * Parity with graphrefly-py `describe_node`.
- *
- * `type` is inferred from factory configuration, optional `describeKind` in node options,
- * and the last `manualEmitUsed` hint (operator vs derived). {@link effect} sets
- * `describeKind: "effect"`. Nodes not created by {@link node} fall back to `type: "state"` and empty `deps`.
- *
- * @param node - Any `Node` to introspect.
- * @returns `DescribeNodeOutput` suitable for merging into graph describe maps.
- *
- * @example
- * ```ts
- * import { describeNode, state } from "@graphrefly/graphrefly-ts";
- *
- * describeNode(state(0));
- * ```
- */
-/**
- * Builds a single-node slice for `Graph.describe()`.
- *
- * @param node - Node to introspect.
- * @param includeFields - Set of fields to include, or `null` for all. When omitted, all fields are included (legacy behavior).
- */
-declare function describeNode(node: Node, includeFields?: Set<string> | null): DescribeNodeOutput;
 
-export { metaSnapshot as $, type Actor as A, accessHintForGuard as B, CLEANUP_RESULT as C, DATA as D, ERROR as E, advanceVersion as F, type GuardAction as G, type HashFn as H, INVALIDATE as I, cleanupResult as J, createVersioning as K, defaultHash as L, type Message as M, type Node as N, type OnMessageHandler as O, PAUSE as P, describeNode as Q, RESOLVED as R, type SubscribeHints as S, TEARDOWN as T, isKnownMessageType as U, type V0 as V, isPhase2Message as W, isTerminalMessage as X, isV1 as Y, knownMessageTypes as Z, messageTier as _, type NodeOptions as a, node as a0, normalizeActor as a1, policy as a2, policyFromRules as a3, propagatesToMeta as a4, resolveDescribeFields as a5, type NodeInspectorHook as a6, type NodeActions as b, type NodeFn as c, COMPLETE as d, type CleanupResult as e, DEFAULT_ACTOR as f, DIRTY as g, type DescribeDetail as h, type DescribeField as i, type DescribeNodeOutput as j, GuardDenied as k, type GuardDeniedDetails as l, type Messages as m, type NodeDescribeKind as n, type NodeGuard as o, type NodeSink as p, type NodeStatus as q, type NodeTransportOptions as r, type NodeVersionInfo as s, type PolicyAllow as t, type PolicyDeny as u, type PolicyRuleData as v, RESUME as w, type V1 as x, type VersioningLevel as y, type VersioningOptions as z };
+export { normalizeActor as $, type Actor as A, accessHintForGuard as B, CLEANUP_RESULT as C, DATA as D, ERROR as E, advanceVersion as F, type GuardAction as G, type HashFn as H, INVALIDATE as I, cleanupResult as J, createVersioning as K, defaultHash as L, type Message as M, type Node as N, type OnMessageHandler as O, PAUSE as P, isKnownMessageType as Q, RESOLVED as R, START as S, TEARDOWN as T, isLocalOnly as U, type V0 as V, isPhase2Message as W, isTerminalMessage as X, isV1 as Y, knownMessageTypes as Z, messageTier as _, type NodeOptions as a, policy as a0, policyFromRules as a1, propagatesToMeta as a2, resolveDescribeFields as a3, NodeBase as a4, type NodeActions as b, COMPLETE as c, type CleanupResult as d, DEFAULT_ACTOR as e, DIRTY as f, type DescribeDetail as g, type DescribeField as h, type DescribeNodeOutput as i, GuardDenied as j, type GuardDeniedDetails as k, type Messages as l, type NodeDescribeKind as m, type NodeGuard as n, type NodeSink as o, type NodeStatus as p, type NodeTransportOptions as q, type NodeVersionInfo as r, type PolicyAllow as s, type PolicyDeny as t, type PolicyRuleData as u, RESUME as v, type SubscribeHints as w, type V1 as x, type VersioningLevel as y, type VersioningOptions as z };