@graphrefly/graphrefly 0.21.0 → 0.23.0

package/dist/node-C7PD3sn9.d.cts

@@ -0,0 +1,1188 @@
+/**
+ * Who is performing an operation (attribution + ABAC input).
+ *
+ * @see GRAPHREFLY-SPEC — roadmap Phase 1.5 (Actor & Guard).
+ */
+type Actor = {
+    type: "human" | "llm" | "wallet" | "system" | string;
+    id: string;
+} & Record<string, unknown>;
+/** Default actor when none is passed ({@link normalizeActor}). */
+declare const DEFAULT_ACTOR: Actor;
+/**
+ * Fills missing `type` / `id` on an actor and returns {@link DEFAULT_ACTOR} when input is undefined.
+ *
+ * @param actor - Optional partial actor from a transport hint.
+ * @returns A normalized `Actor` safe to pass to guards and graph APIs.
+ *
+ * @example
+ * ```ts
+ * import { normalizeActor } from "@graphrefly/graphrefly-ts";
+ *
+ * normalizeActor({ type: "human", id: "u1" });
+ * ```
+ */
+declare function normalizeActor(actor?: Actor): Actor;
+
+/**
+ * GraphReFly message protocol — §1 `~/src/graphrefly/GRAPHREFLY-SPEC.md`.
+ * Emissions are always `[[Type, Data?], ...]` (no single-tuple shorthand).
+ *
+ * This file is protocol-pure:
+ * - Message type symbols (10 built-ins).
+ * - `Message` / `Messages` tuple types.
+ * - `MessageTypeRegistration` interface (shape of a registry entry).
+ *
+ * It does NOT own the registry, tier lookups, or any cross-cutting singleton
+ * state — that lives in `GraphReFlyConfig` (see `config.ts`) so custom
+ * protocols can build isolated instances. Import this module when you need
+ * the symbol constants or the tuple types; import `config.ts` when you need
+ * tier / wire-crossing / registry lookups.
+ */
+/** Subscribe-time handshake. Delivered to each new sink at the top of `subscribe()`. Tier 0. */
+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 — deferred to batch phase 4. */
+declare const TEARDOWN: unique symbol;
+/** Clean termination. Tier 4 — deferred to batch phase 3. */
+declare const COMPLETE: unique symbol;
+/** Error termination. Tier 4 — deferred to batch phase 3. */
+declare const ERROR: unique 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[];
+/** Singleton `[DIRTY]` tuple — payload-free, interned. */
+declare const DIRTY_MSG: Message;
+/** Singleton `[RESOLVED]` tuple — payload-free, interned. */
+declare const RESOLVED_MSG: Message;
+/** Singleton `[INVALIDATE]` tuple — payload-free, interned. */
+declare const INVALIDATE_MSG: Message;
+/** Singleton `[START]` tuple — payload-free, interned. */
+declare const START_MSG: Message;
+/** Singleton `[COMPLETE]` tuple — payload-free, interned. */
+declare const COMPLETE_MSG: Message;
+/** Singleton `[TEARDOWN]` tuple — payload-free, interned. */
+declare const TEARDOWN_MSG: Message;
+/** Pre-wrapped `[[DIRTY]]` for `_emit([DIRTY_ONLY_BATCH])`-style callers. */
+declare const DIRTY_ONLY_BATCH: Messages;
+/** Pre-wrapped `[[RESOLVED]]`. */
+declare const RESOLVED_ONLY_BATCH: Messages;
+/** Pre-wrapped `[[INVALIDATE]]`. */
+declare const INVALIDATE_ONLY_BATCH: Messages;
+/** Pre-wrapped `[[COMPLETE]]`. */
+declare const COMPLETE_ONLY_BATCH: Messages;
+/** Pre-wrapped `[[TEARDOWN]]`. */
+declare const TEARDOWN_ONLY_BATCH: Messages;
+/**
+ * Per-type record stored in a {@link GraphReFlyConfig}'s registry.
+ *
+ * - `tier` — signal tier (0–5 built-in; custom tiers allowed but should fit
+ *   the phase model used by `batch.ts`).
+ * - `wireCrossing` — when `true`, forwarded across SSE/WebSocket/worker
+ *   adapters. Defaults to `tier >= 3` if omitted in registration input.
+ * - `metaPassthrough` — when `false`, this message type is filtered out of
+ *   `Graph.signal` deliveries to meta companion nodes (spec §2.3). Meta
+ *   companions still receive everything via their primary's own cascade.
+ *   Defaults to `true` (meta receives the message).
+ */
+interface MessageTypeRegistration {
+    tier: number;
+    wireCrossing: boolean;
+    metaPassthrough: boolean;
+}
+/**
+ * Input accepted by {@link GraphReFlyConfig.registerMessageType}. Only `tier`
+ * is required; `wireCrossing` defaults to `tier >= 3`; `metaPassthrough`
+ * defaults to `true`.
+ */
+interface MessageTypeRegistrationInput {
+    tier: number;
+    wireCrossing?: boolean;
+    metaPassthrough?: boolean;
+}
+
+/**
+ * Node versioning — GRAPHREFLY-SPEC §7.
+ *
+ * Progressive, optional versioning for node identity and change tracking.
+ *
+ * - **V0**: `id` + `version` — identity & change detection (~16 bytes overhead)
+ * - **V1**: + `cid` + `prev` — content addressing & linked history (~60 bytes overhead)
+ *
+ * **Lifecycle notes:**
+ * - Version advances only on DATA (not RESOLVED, INVALIDATE, or TEARDOWN).
+ * - `resetOnTeardown` clears the cached value but does NOT reset versioning state.
+ *   After teardown, `v.cid` still reflects the last DATA value, not the cleared cache.
+ *   The invariant `hash(node.cache) === v.cid` only holds in `settled`/`resolved` status.
+ * - Resubscribable nodes preserve versioning across subscription lifetimes (monotonic counter).
+ */
+/** V0: identity + monotonic version counter. */
+type V0 = {
+    readonly id: string;
+    version: number;
+};
+/** V1: V0 + content-addressed identifier + previous cid link. */
+type V1 = V0 & {
+    cid: string;
+    prev: string | null;
+};
+/** Union of all versioning info shapes. */
+type NodeVersionInfo = V0 | V1;
+/** Supported versioning levels (extensible to 2, 3 later). */
+type VersioningLevel = 0 | 1;
+/** Function that hashes a value to a hex string (for V1 cid). */
+type HashFn = (value: unknown) => string;
+interface VersioningOptions {
+    /** Override auto-generated id. */
+    id?: string;
+    /** Custom hash function for V1 cid (default: SHA-256 truncated to 16 hex chars). */
+    hash?: HashFn;
+}
+/**
+ * Default content hash: SHA-256 of deterministic JSON, truncated to 16 hex
+ * chars (~64-bit). Uses {@link canonicalizeForHash} for cross-language parity
+ * with Python `default_hash`.
+ */
+declare function defaultHash(value: unknown): string;
+/**
+ * Create initial versioning state for a node.
+ *
+ * @param level - 0 for V0, 1 for V1.
+ * @param initialValue - The node's initial cached value (used for V1 cid).
+ * @param opts - Optional overrides (id, hash).
+ */
+declare function createVersioning(level: VersioningLevel, initialValue: unknown, opts?: VersioningOptions): NodeVersionInfo;
+/**
+ * Advance versioning state after a DATA emission (value changed).
+ *
+ * Mutates `info` in place for performance (called on every DATA).
+ * Only call when the cached value has actually changed (not on RESOLVED).
+ *
+ * @param info - The node's current versioning state.
+ * @param newValue - The new cached value.
+ * @param hashFn - Hash function (only used for V1).
+ */
+declare function advanceVersion(info: NodeVersionInfo, newValue: unknown, hashFn: HashFn): void;
+/** Type guard: is this V1 versioning info? */
+declare function isV1(info: NodeVersionInfo): info is V1;
+
+/**
+ * Singleton protocol config. Holds the message-type registry, the
+ * `onMessage` / `onSubscribe` hooks, versioning defaults, and the freeze flag.
+ *
+ * Layering: this file is protocol-pure. It imports only from `messages.ts`
+ * and declares opaque type shapes for handlers — the concrete default
+ * implementations and the `defaultConfig` instance live in `node.ts` so that
+ * handler bodies can touch `NodeImpl` internals without creating a cycle.
+ *
+ * Two access paths:
+ * 1. **Default instance** (`defaultConfig` in `node.ts`) — use
+ *    `configure((cfg) => ...)` at app startup; every node implicitly binds to it.
+ * 2. **Isolated instance** (`new GraphReFlyConfig(...)`) — pass via
+ *    `opts.config` for test isolation or custom protocol stacks.
+ *
+ * A config **freezes on first getter read** of any hook (`onMessage`,
+ * `onSubscribe`). `NodeImpl`'s constructor intentionally touches one of these
+ * on first use so configuration cannot drift once nodes exist.
+ */
+
+/**
+ * Minimal node surface visible to default handlers. Concrete `NodeImpl`
+ * implements this plus a large set of package-private fields; handlers that
+ * need the richer surface cast to the concrete type in `node.ts`.
+ */
+interface NodeCtx {
+    readonly name?: string;
+    readonly status: string;
+    readonly cache: unknown;
+}
+/** Imperative actions available inside a node's compute function (§5). */
+interface NodeActions {
+    /**
+     * Sugar for `down([[DATA, value]])`. One call = one wave with a
+     * single DATA payload. The emit pipeline auto-prefixes `[DIRTY]`,
+     * runs equals substitution against the live cache, and dispatches
+     * to sinks with phase deferral. Diamond-safe by construction.
+     */
+    emit(value: unknown): void;
+    /**
+     * Send one or more messages downstream. Accepts either a single
+     * {@link Message} tuple or a {@link Messages} array of tuples. One
+     * call = one wave: the emit pipeline tier-sorts the input,
+     * auto-prefixes `[DIRTY]` when a tier-3 payload is present and the
+     * node isn't already dirty, runs equals substitution, then
+     * dispatches. Multiple calls produce multiple waves.
+     */
+    down(messageOrMessages: Message | Messages): void;
+    /**
+     * Send one or more messages upstream. Accepts the same shapes as
+     * {@link down}. Tier 3 (DATA/RESOLVED) and tier 4 (COMPLETE/ERROR)
+     * are downstream-only and will throw — up is for DIRTY, INVALIDATE,
+     * PAUSE, RESUME, and TEARDOWN only. No cache advance, no equals,
+     * no framing — a plain forward to every dep.
+     */
+    up(messageOrMessages: Message | Messages): void;
+}
+/**
+ * Message-flow context passed to {@link OnMessageHandler}.
+ *
+ * - `"down-in"` — message arriving from a dep (identified by `depIndex`).
+ * - `"up-in"` — message arriving from a sink.
+ */
+type MessageContext = {
+    direction: "down-in";
+    depIndex: number;
+} | {
+    direction: "up-in";
+};
+/**
+ * Per-sink context passed to {@link OnSubscribeHandler}.
+ */
+interface SubscribeContext {
+    /** Post-subscribe sink count. `1` means first subscriber after 0. */
+    sinkCount: number;
+    /** True when this subscribe cleared a resubscribable terminal state. */
+    afterTerminalReset: boolean;
+}
+/**
+ * Singleton message interceptor. Called for every message in either direction
+ * before the default per-tier dispatch runs. Return `"consume"` to suppress
+ * default handling.
+ */
+type OnMessageHandler = (node: NodeCtx, msg: Message, ctx: MessageContext, actions: NodeActions) => "consume" | undefined;
+/**
+ * Singleton subscribe ceremony. Fires for every sink subscribe on every node.
+ * Default implementation emits the START handshake (+ cached DATA when
+ * present) to the new sink. Return a cleanup function to run on unsubscribe.
+ */
+type OnSubscribeHandler = (node: NodeCtx, sink: (messages: Messages) => void, ctx: SubscribeContext, actions: NodeActions) => (() => void) | undefined;
+/**
+ * Event payload for {@link GlobalInspectorHook}. One event fires per outgoing
+ * message batch from any node bound to the config.
+ *
+ * - `kind: "emit"` — fires after equals substitution (`finalMessages`) and
+ *   before sink dispatch. `messages` is the exact batch sinks see.
+ */
+type GlobalInspectorEvent = {
+    kind: "emit";
+    node: NodeCtx;
+    messages: Messages;
+};
+/**
+ * Process-global observability hook for full-graph tracing
+ * (Redux-DevTools-style action history). Fires from every node's `_emit`
+ * waist whenever {@link GraphReFlyConfig.inspectorEnabled} is `true`.
+ *
+ * Distinct from per-node `_setInspectorHook` (which is the dep-message /
+ * fn-run causal trace used by `Graph.observe(path, { causal, derived })`).
+ * Use the global hook to record every emission across every node — useful for
+ * time-travel debuggers, tracers, and replay tooling. Use the per-node hook
+ * to attribute a single subscribed path's wave to its driving deps.
+ *
+ * Errors thrown from the hook are swallowed — instrumentation must not break
+ * the data plane.
+ */
+type GlobalInspectorHook = (event: GlobalInspectorEvent) => void;
+/**
+ * Singleton protocol config.
+ *
+ * A config freezes on first getter read of any hook. After freeze, any
+ * attempt to mutate (register a message type, set a hook) throws.
+ */
+declare class GraphReFlyConfig {
+    private _messageTypes;
+    private _codecs;
+    private _onMessage;
+    private _onSubscribe;
+    private _defaultVersioning;
+    private _defaultHashFn;
+    private _inspectorEnabled;
+    private _globalInspector?;
+    private _frozen;
+    /**
+     * Pre-bound tier lookup — shared by every node bound to this config. Since
+     * the registry is frozen on first hook access, this closure can be built
+     * once in the constructor and handed directly to `downWithBatch` /
+     * `_frameBatch` paths without per-node or per-emission `.bind(config)`
+     * allocation.
+     */
+    readonly tierOf: (t: symbol) => number;
+    constructor(init: {
+        onMessage: OnMessageHandler;
+        onSubscribe: OnSubscribeHandler;
+        defaultVersioning?: VersioningLevel;
+        defaultHashFn?: HashFn;
+    });
+    get onMessage(): OnMessageHandler;
+    get onSubscribe(): OnSubscribeHandler;
+    set onMessage(v: OnMessageHandler);
+    set onSubscribe(v: OnSubscribeHandler);
+    /**
+     * Default versioning level applied to every node bound to this config,
+     * unless the node's own `opts.versioning` provides an explicit override.
+     * Setting this is only allowed before the config freezes (i.e., before
+     * the first node is created) so every node in the graph sees a
+     * consistent starting level. Individual nodes can still opt into a
+     * higher level via `opts.versioning`, or post-hoc via
+     * `NodeImpl._applyVersioning(level)` when the node is quiescent.
+     *
+     * v0 is the minimum opt-in — unversioned nodes (`undefined`) skip
+     * the version counter entirely. v1 adds content-addressed cid.
+     * Future levels (v2, v3) are reserved for linked-history and
+     * cryptographic attestation extensions.
+     */
+    get defaultVersioning(): VersioningLevel | undefined;
+    set defaultVersioning(v: VersioningLevel | undefined);
+    /**
+     * Default content-hash function applied to every versioned node bound
+     * to this config, unless the node's own `opts.versioningHash` provides
+     * an explicit override. Use this when a graph needs a non-default hash
+     * — e.g., swap the vendored sync SHA-256 for a faster non-crypto hash
+     * (xxHash, FNV-1a) in hot-path workloads, or a stronger hash when
+     * versioning v1 cids are used as audit anchors.
+     *
+     * Only settable before the config freezes. Individual nodes can still
+     * override via `opts.versioningHash`.
+     */
+    get defaultHashFn(): HashFn | undefined;
+    set defaultHashFn(v: HashFn | undefined);
+    /**
+     * When `false`, structured observation options (`causal`, `timeline`)
+     * and `Graph.trace()` writes are no-ops. Raw `Graph.observe()` always
+     * works. Default: `true` outside production (`NODE_ENV !== "production"`).
+     *
+     * Settable at any time — inspector gating is an operational concern, not
+     * a protocol invariant, so it does NOT require freeze before node creation.
+     */
+    get inspectorEnabled(): boolean;
+    set inspectorEnabled(v: boolean);
+    /**
+     * Process-global observability hook (Redux-DevTools-style full-graph
+     * tracer). Fires once per outgoing batch from every node bound to this
+     * config, gated by {@link inspectorEnabled}. See {@link GlobalInspectorHook}.
+     *
+     * Settable at any time — like {@link inspectorEnabled} this is operational,
+     * not protocol-shaping, so it does NOT trigger config freeze.
+     */
+    get globalInspector(): GlobalInspectorHook | undefined;
+    set globalInspector(v: GlobalInspectorHook | undefined);
+    /**
+     * Register a custom message type. Must be called before any node that
+     * uses this config has been created — otherwise throws. Default
+     * `wireCrossing` is `tier >= 3`.
+     */
+    registerMessageType(t: symbol, input: MessageTypeRegistrationInput): this;
+    /** Tier for `t`. Unknown types default to tier 1 (immediate, after START). */
+    messageTier(t: symbol): number;
+    /**
+     * Whether `t` is registered as wire-crossing. Unknown types default to
+     * `true` (spec §1.3.6 forward-compat — unknowns cross the wire).
+     */
+    isWireCrossing(t: symbol): boolean;
+    /** Convenience inverse of {@link isWireCrossing}. */
+    isLocalOnly(t: symbol): boolean;
+    /**
+     * Whether `t` is forwarded to meta companions by `Graph.signal`. Defaults
+     * to `true` for unknowns (forward-compat — new types pass through meta by
+     * default; opt-in filter via `registerMessageType({metaPassthrough: false})`).
+     */
+    isMetaPassthrough(t: symbol): boolean;
+    /** Whether `t` is a registered (built-in or custom) type. */
+    isKnownMessageType(t: symbol): boolean;
+    /**
+     * Register a graph codec by `codec.name`. Used by the envelope-based
+     * `graph.snapshot({format: "bytes", codec: name})` path and
+     * `Graph.decode(bytes)` auto-dispatch. Must be called before any node
+     * bound to this config is created — otherwise throws.
+     *
+     * Re-registering the same name overwrites, so user codecs can shadow
+     * built-in ones before freeze (e.g., to swap a zstd-wrapped dag-cbor in
+     * for `"dag-cbor"`).
+     */
+    registerCodec<T extends {
+        readonly name: string;
+        readonly version: number;
+    }>(codec: T): this;
+    /**
+     * Resolve a registered codec by name. Returns `undefined` for unknown
+     * names. Typed callers cast to their concrete codec interface (e.g.,
+     * `config.lookupCodec<GraphCodec>("json")`) — this method stays
+     * layer-pure (no import of graph-layer types into `core/`).
+     */
+    lookupCodec<T = {
+        readonly name: string;
+        readonly version: number;
+    }>(name: string): T | undefined;
+    /** @internal Used by tests and dev tooling — check freeze state without triggering it. */
+    _isFrozen(): boolean;
+    private _assertUnfrozen;
+}
+/**
+ * Register the 10 built-in message types on a fresh config. Called by
+ * `node.ts` when it constructs `defaultConfig` and by test code / advanced
+ * users after `new GraphReFlyConfig(...)`.
+ */
+declare function registerBuiltins(cfg: GraphReFlyConfig): void;
+
+/**
+ * Actions checked by {@link NodeGuard}. `write` covers both {@link Node.down} and
+ * {@link Node.up} today; finer-grained strings may be added later (e.g. `"write.data"`).
+ */
+type GuardAction = "write" | "signal" | "observe" | (string & {});
+type NodeGuard = (actor: Actor, action: GuardAction) => boolean;
+type GuardDeniedDetails = {
+    actor: Actor;
+    action: GuardAction;
+    /** Registry or options name when known */
+    nodeName?: string;
+};
+/**
+ * Thrown when a {@link NodeGuard} denies an action for a given actor.
+ *
+ * Carries the rejected `actor`, `action`, and optional `nodeName` for diagnostic
+ * messages and middleware error handling.
+ *
+ * @example
+ * ```ts
+ * import { GuardDenied, policy } from "@graphrefly/graphrefly-ts";
+ *
+ * const guard = policy((allow) => { allow("observe"); });
+ * try {
+ *   if (!guard({ type: "llm", id: "agent-1" }, "write")) {
+ *     throw new GuardDenied(
+ *       { actor: { type: "llm", id: "agent-1" }, action: "write", nodeName: "userInput" },
+ *     );
+ *   }
+ * } catch (e) {
+ *   if (e instanceof GuardDenied) console.error(e.action, e.actor.type); // "write" "llm"
+ * }
+ * ```
+ */
+declare class GuardDenied extends Error {
+    readonly actor: Actor;
+    readonly action: GuardAction;
+    readonly nodeName?: string;
+    /**
+     * @param details - Actor, action, and optional node name for the denial.
+     * @param message - Optional override for the default error message.
+     */
+    constructor(details: GuardDeniedDetails, message?: string);
+    /** Qualified registry path when known (roadmap diagnostics: same as {@link nodeName}). */
+    get node(): string | undefined;
+}
+type Where = (actor: Actor) => boolean;
+type PolicyAllow = (action: GuardAction | readonly GuardAction[], opts?: {
+    where?: Where;
+}) => void;
+type PolicyDeny = (action: GuardAction | readonly GuardAction[], opts?: {
+    where?: Where;
+}) => void;
+type PolicyRuleData = {
+    effect: "allow" | "deny";
+    action: GuardAction | readonly GuardAction[];
+    actorType?: string | readonly string[];
+    actorId?: string | readonly string[];
+    claims?: Record<string, unknown>;
+};
+/**
+ * Declarative guard builder. Precedence: any matching **deny** blocks even if an allow also matches.
+ * If no rule matches, the guard returns `false` (deny-by-default). Aligned with graphrefly-py `policy()`.
+ *
+ * @param build - Callback that registers `allow(...)` / `deny(...)` rules in order.
+ * @returns A `NodeGuard` for use as `node({ guard })`.
+ *
+ * @example
+ * ```ts
+ * const guard = policy((allow, deny) => {
+ *   allow("observe");
+ *   deny("write", { where: (a) => a.type === "llm" });
+ * });
+ * ```
+ */
+declare function policy(build: (allow: PolicyAllow, deny: PolicyDeny) => void): NodeGuard;
+/**
+ * Rebuild a declarative guard from persisted policy data (snapshot-safe).
+ *
+ * Rules are deny-overrides, same semantics as {@link policy}.
+ */
+declare function policyFromRules(rules: readonly PolicyRuleData[]): NodeGuard;
+/**
+ * Derives a best-effort `meta.access` hint string by probing `guard` with the
+ * standard actor types `human`, `llm`, `wallet`, `system` for the `"write"` action
+ * (roadmap 1.5). Aligned with graphrefly-py `access_hint_for_guard`.
+ *
+ * @param guard - Guard function to probe (typically from {@link policy}).
+ * @returns `"restricted"` when no standard type is allowed; `"both"` when both
+ *   `human` and `llm` are allowed (plus optionally `system`); the single allowed
+ *   type name when only one passes; or a `"+"` joined list otherwise.
+ *
+ * @example
+ * ```ts
+ * import { policy, accessHintForGuard } from "@graphrefly/graphrefly-ts";
+ *
+ * const guardBoth = policy((allow) => { allow("write"); });
+ * accessHintForGuard(guardBoth); // "both"
+ *
+ * const guardHuman = policy((allow) => {
+ *   allow("write", { where: (a) => a.type === "human" });
+ * });
+ * accessHintForGuard(guardHuman); // "human"
+ * ```
+ */
+declare function accessHintForGuard(guard: NodeGuard): string;
+
+/**
+ * `NodeImpl` — the single GraphReFly node primitive.
+ *
+ * Per-dep state lives in a `DepRecord[]` — one entry per declared dep —
+ * consolidating subscription cleanup, latest-data tracking, dirty/settled
+ * flags, and terminal state into a single structure per dep.
+ *
+ * This file also owns the default singleton handlers (`defaultOnMessage`,
+ * `defaultOnSubscribe`), the `defaultConfig` instance, and the public
+ * `configure(...)` entry point. They live here because their bodies touch
+ * `NodeImpl` internals; `config.ts` stays NodeImpl-agnostic.
+ *
+ * See GRAPHREFLY-SPEC §2 and COMPOSITION-GUIDE §1/§9 for the behavior
+ * contract. See SESSION-foundation-redesign.md §§1–10 for design history.
+ */
+
+/** Lifecycle status of a node (GRAPHREFLY-SPEC §2.2). */
+type NodeStatus = "sentinel" | "pending" | "dirty" | "settled" | "resolved" | "completed" | "errored";
+/** Callback that receives downstream message batches. */
+type NodeSink = (messages: Messages) => void;
+/**
+ * Observability hook events fired by a per-node inspector. Used by
+ * `Graph.observe(path, { causal, derived })` to build causal traces.
+ *
+ * - `"dep_message"` — fires in `_onDepMessage` before default dispatch,
+ *   one event per message received from a dep. Includes `depIndex` and
+ *   the raw `Message` tuple.
+ * - `"run"` — fires in `_execFn` just before the user fn runs. Includes
+ *   the per-dep `prevData` snapshot that will be passed to fn.
+ */
+type NodeInspectorHookEvent = {
+    kind: "dep_message";
+    depIndex: number;
+    message: Message;
+} | {
+    kind: "run";
+    batchData: readonly (readonly unknown[] | undefined)[];
+    prevData: readonly unknown[];
+};
+/** Callback attached to a node for per-message/per-run inspection. */
+type NodeInspectorHook = (event: NodeInspectorHookEvent) => void;
+/** Describe `type` for `Graph.describe` (GRAPHREFLY-SPEC Appendix B). */
+type NodeDescribeKind = "state" | "derived" | "producer" | "effect";
+/** Actor/delivery context for {@link Node.down} and {@link Node.up}. */
+type NodeTransportOptions = {
+    actor?: Actor;
+    /** When `true`, skips guard checks. */
+    internal?: boolean;
+    /** `signal` for `Graph.signal` deliveries; default `write`. */
+    delivery?: "write" | "signal";
+};
+/**
+ * Cleanup return shape from a node {@link NodeFn}.
+ * - `() => void` — fires before the next fn run AND on deactivation (default).
+ * - `{ deactivation: () => void }` — fires only on deactivation (persistent
+ *   resources that should survive across fn re-runs).
+ */
+type NodeFnCleanup = (() => void) | {
+    deactivation: () => void;
+};
+/**
+ * Fn-time context exposing per-wave metadata and a per-node persistent
+ * scratch pad.
+ *
+ * - `prevData[i]` — last DATA value from dep `i` as of the END of the
+ *   previous wave (i.e. the value that was stable before this wave started).
+ *   Use as the fallback when `data[i]` is `undefined` (not involved) or
+ *   `[]` (RESOLVED, no new values this wave).
+ *   `undefined` means dep `i` has never produced DATA (sentinel state).
+ *   `null` is a valid DATA value. `undefined` is not a valid DATA value —
+ *   the protocol reserves it as the "never sent" sentinel.
+ *   - `ctx.prevData[i] === undefined` → dep has never produced DATA
+ *   - `ctx.prevData[i] !== undefined` → last DATA value (may be `null`)
+ * - `terminalDeps[i]` — runtime shape:
+ *   - `undefined` → dep `i` is still live.
+ *   - `true` → dep `i` sent COMPLETE.
+ *   - anything else → dep `i` sent ERROR, value is the error payload.
+ *   Type is `readonly unknown[]` because `true | unknown` collapses to
+ *   `unknown` anyway; the three states are documented contract, not type.
+ * - `store` — mutable bag that persists across fn runs within one activation
+ *   cycle. Wiped on deactivation and on resubscribable terminal reset.
+ */
+interface FnCtx {
+    readonly prevData: readonly unknown[];
+    readonly terminalDeps: readonly unknown[];
+    readonly store: Record<string, unknown>;
+}
+/**
+ * Compute function passed to `node(deps, fn, opts?)`.
+ *
+ * `data[i]` holds the batch of DATA values received from dep `i` during the
+ * current wave. Shape contract:
+ * - `undefined` — dep `i` was not involved in this wave (no DIRTY received).
+ * - `[]` — dep `i` was involved (dirtied), but settled as RESOLVED (value
+ *   unchanged). Use `ctx.prevData[i]` to read its last known value from the
+ *   previous wave.
+ * - `[v1, v2, ...]` — dep `i` sent one or more DATA values. `at(-1)` gives
+ *   the latest; iterate for multi-emission processing.
+ *
+ * Emission is explicit via `actions.emit(v)` (sugar: equals + framing) or
+ * `actions.down(msgs)` (raw). Return a cleanup function (or
+ * `{ deactivation }`) to register teardown — any non-cleanup return value
+ * is ignored. The `| void` leg lets arrow-block bodies satisfy `NodeFn`
+ * without an explicit `return undefined`.
+ *
+ * Sugar constructors (`derived`, `effect`, `dynamicNode`) unwrap `data[i]`
+ * to a single scalar (`at(-1)` with `ctx.prevData[i]` fallback) so their
+ * user-facing fn signatures stay unchanged. Use raw `node()` when you need
+ * the full batch array.
+ */
+type NodeFn = (data: readonly (readonly unknown[] | undefined)[], actions: NodeActions, ctx: FnCtx) => NodeFnCleanup | void;
+/** Options accepted by every node constructor. */
+interface NodeOptions<T = unknown> {
+    name?: string;
+    describeKind?: NodeDescribeKind;
+    equals?: (a: T, b: T) => boolean;
+    /**
+     * Pre-populate the cache at construction. `null` is a valid initial value.
+     * `undefined` is treated as absent (not a valid DATA payload).
+     */
+    initial?: T | null;
+    meta?: Record<string, unknown>;
+    resubscribable?: boolean;
+    resetOnTeardown?: boolean;
+    /** Auto-emit `[[COMPLETE]]` when all deps complete. Default `true`. */
+    completeWhenDepsComplete?: boolean;
+    /**
+     * Auto-propagate `[[ERROR]]` when any dep errors. Default `true`.
+     * Set `false` only for rescue/catchError operators that handle errors
+     * explicitly via `ctx.terminalDeps`.
+     */
+    errorWhenDepsError?: boolean;
+    /**
+     * Tier-2 PAUSE/RESUME handling.
+     * - `true` (default): wave completion suppressed while paused; fn fires
+     *   once on RESUME if gate is satisfied.
+     * - `false`: node ignores PAUSE (sources like timers that must keep running).
+     * - `"resumeAll"`: on RESUME, replay every buffered DATA (future).
+     */
+    pausable?: boolean | "resumeAll";
+    guard?: NodeGuard;
+    versioning?: VersioningLevel;
+    versioningId?: string;
+    versioningHash?: HashFn;
+    /**
+     * Override the config instance this node binds to. Defaults to
+     * {@link defaultConfig}. Useful for test isolation and custom protocol
+     * stacks. The first node that reads any hook on the config freezes it.
+     */
+    config?: GraphReFlyConfig;
+}
+/** A reactive node in the GraphReFly protocol. */
+interface Node<T = unknown> {
+    readonly name?: string;
+    readonly status: NodeStatus;
+    /**
+     * Current cached value. Returns `undefined` when the node is in
+     * `"sentinel"` state (no DATA ever emitted). v5 reserves `undefined`
+     * globally as the sentinel value — the valid DATA type is `T | null`.
+     * Therefore `node.cache === undefined` is a valid "never emitted" guard.
+     * `node.status` distinguishes the richer states (`"sentinel"`,
+     * `"settled"`, `"errored"`, etc.) when you need more than has-value.
+     */
+    readonly cache: T | null | undefined;
+    readonly meta: Record<string, Node>;
+    readonly lastMutation: Readonly<{
+        actor: Actor;
+        timestamp_ns: number;
+    }> | undefined;
+    readonly v: Readonly<NodeVersionInfo> | undefined;
+    /**
+     * Send one or more messages downstream. Accepts either a single
+     * {@link Message} tuple (e.g. `node.down([DATA, 42])`) or a
+     * {@link Messages} array of tuples (e.g.
+     * `node.down([[DIRTY], [DATA, 42]])`). One call = one wave: the
+     * emit pipeline tier-sorts the input, auto-prefixes `[DIRTY]` when
+     * any tier-3 payload is present and the node is not already dirty,
+     * runs equals substitution against the live cache (§3.5.1), then
+     * dispatches to sinks with phase deferral.
+     */
+    down(messageOrMessages: Message | Messages, options?: NodeTransportOptions): void;
+    /**
+     * Sugar for `down([[DATA, value]])`. One wave with a single DATA
+     * payload — the pipeline adds the synthetic DIRTY prefix and runs
+     * equals substitution against the live cache.
+     */
+    emit(value: T | undefined | null, options?: NodeTransportOptions): void;
+    /**
+     * Send one or more messages upstream. Accepts the same shapes as
+     * {@link down}. Upstream messages are tier <3 + tier 5 only
+     * (DIRTY, INVALIDATE, PAUSE, RESUME, TEARDOWN); tier-3/4 payloads
+     * throw — DATA/RESOLVED/COMPLETE/ERROR are downstream-only in this
+     * protocol. No equals substitution, no cache advance, no DIRTY
+     * auto-prefix — the up direction just forwards to every dep.
+     */
+    up?(messageOrMessages: Message | Messages, options?: NodeTransportOptions): void;
+    subscribe(sink: NodeSink, actor?: Actor): () => void;
+    allowsObserve(actor: Actor): boolean;
+    hasGuard(): boolean;
+}
+/**
+ * Per-dep runtime state. One entry per upstream node.
+ *
+ * `terminal` is the single terminal-state slot, shaped to match
+ * {@link FnCtx.terminalDeps}:
+ * - `undefined` — dep is still live.
+ * - `true` — dep sent COMPLETE.
+ * - anything else — dep sent ERROR with that payload.
+ *
+ * Edge case: an ERROR carrying an `undefined` payload is indistinguishable
+ * from "live". Pass meaningful error values (Error objects, domain tags).
+ */
+interface DepRecord {
+    readonly node: Node;
+    unsub: (() => void) | null;
+    /**
+     * Last DATA value from this dep as of the end of the previous completed
+     * wave. `undefined` until dep has produced at least one DATA (sentinel).
+     * Committed by `_execFn` after snapshotting `ctx.prevData` and before
+     * `_clearWaveFlags`. `undefined` is reserved as the "never sent" sentinel —
+     * `undefined` is not a valid DATA payload.
+     */
+    prevData: unknown;
+    /** True while awaiting DATA/RESOLVED for the current wave. */
+    dirty: boolean;
+    /**
+     * True if this dep was dirtied in the current wave (set in `_depDirtied`,
+     * cleared in `_clearWaveFlags`). Distinguishes "RESOLVED" (`involvedThisWave
+     * && dataBatch.length === 0`) from "not involved" (`!involvedThisWave`) in
+     * the `data[i]` batch snapshot passed to fn.
+     */
+    involvedThisWave: boolean;
+    /**
+     * DATA values accumulated from this dep during the current wave.
+     * Populated by `_depSettledAsData`, cleared by `_clearWaveFlags`.
+     * Snapshotted (copied) by `_execFn` before `_clearWaveFlags` runs so
+     * that fn always sees the full wave batch.
+     */
+    dataBatch: unknown[];
+    /** Terminal-state slot — see JSDoc on {@link DepRecord}. */
+    terminal: unknown;
+}
+/**
+ * Default {@link GraphReFlyConfig} instance. Every `NodeImpl` constructed
+ * without an explicit `opts.config` binds to this instance and freezes it
+ * on first hook access.
+ */
+declare const defaultConfig: GraphReFlyConfig;
+/**
+ * Apply configuration to {@link defaultConfig}. Must be called before the
+ * first node is created — otherwise throws. Custom message types, hook
+ * overrides, etc. go through here at app startup.
+ *
+ * ```ts
+ * configure((cfg) => {
+ *   cfg.registerMessageType(MY_TYPE, { tier: 3 });
+ *   cfg.onMessage = (node, msg, ctx, actions) => { ... };
+ * });
+ * ```
+ */
+declare function configure(fn: (cfg: GraphReFlyConfig) => void): void;
+
+/**
+ * Single-class node implementation. Covers state, producer, derived, effect,
+ * and passthrough shapes. See `sugar.ts` for ergonomic factories and
+ * `dynamicNode()` (sugar-level wrapper around plain `NodeImpl`).
+ */
+declare class NodeImpl<T = unknown> implements Node<T> {
+    readonly _optsName: string | undefined;
+    readonly _describeKind: NodeDescribeKind | undefined;
+    readonly meta: Record<string, Node>;
+    /**
+     * Cached `Object.keys(meta).length > 0` check. `meta` is frozen at
+     * construction so this boolean never flips. Used by `_emit` to skip
+     * the meta TEARDOWN fan-out block allocation on the common "no meta"
+     * hot path.
+     */
+    readonly _hasMeta: boolean;
+    readonly _config: GraphReFlyConfig;
+    /** Mutable for autoTrackNode / Graph.connect() post-construction dep addition. */
+    _deps: DepRecord[];
+    _sinks: NodeSink | Set<NodeSink> | null;
+    _sinkCount: number;
+    _cached: T | undefined;
+    _status: NodeStatus;
+    _cleanup: NodeFnCleanup | undefined;
+    _store: Record<string, unknown>;
+    _waveHasNewData: boolean;
+    _hasNewTerminal: boolean;
+    _hasCalledFnOnce: boolean;
+    _paused: boolean;
+    _pendingWave: boolean;
+    _isExecutingFn: boolean;
+    _pendingRerun: boolean;
+    _rerunDepth: number;
+    /**
+     * Count of deps currently in `dirty === true`. `_maybeRunFnOnSettlement`
+     * treats `0` as "wave settled" — O(1) check for full dep settlement.
+     */
+    _dirtyDepCount: number;
+    /**
+     * Inside an explicit `batch(() => ...)` scope, every `_emit` accumulates
+     * its already-framed messages here instead of dispatching synchronously.
+     * At batch end, `_flushBatchPending` runs (registered via
+     * `registerBatchFlushHook`) and delivers the whole accumulated batch as
+     * one `downWithBatch` call — collapsing what would otherwise be K
+     * separate sink invocations into one. This is the fix for the diamond
+     * fan-in K+1 over-fire.
+     *
+     * `null` outside batch (or after flush). Only ever appended to within
+     * a single explicit batch lifetime; reset to `null` on flush. State
+     * updates (cache, version, status) still happen per-emit via
+     * `_updateState` — only the downstream delivery is coalesced.
+     */
+    _batchPendingMessages: Message[] | null;
+    /**
+     * Set of active pause locks held against this node. Every `[PAUSE, lockId]`
+     * adds its `lockId` to the set; every `[RESUME, lockId]` removes it.
+     * `_paused` is a derived quantity: `_pauseLocks.size > 0`. Multi-pauser
+     * correctness — one controller releasing its lock does NOT resume the
+     * node while another controller still holds its lock.
+     */
+    _pauseLocks: Set<unknown> | null;
+    /**
+     * Buffered DATA messages held while paused. Only populated when
+     * `_pausable === "resumeAll"` (bufferAll mode). On final lock release
+     * the buffer is replayed through the node's outgoing pipeline in the
+     * order received. Non-bufferAll pause mode drops DATA on the floor
+     * (upstream is expected to honor PAUSE by suppressing production).
+     */
+    _pauseBuffer: Message[] | null;
+    readonly _fn: NodeFn | undefined;
+    readonly _equals: (a: T, b: T) => boolean;
+    readonly _resubscribable: boolean;
+    readonly _resetOnTeardown: boolean;
+    readonly _autoComplete: boolean;
+    readonly _autoError: boolean;
+    readonly _pausable: boolean | "resumeAll";
+    readonly _guard: NodeGuard | undefined;
+    _hashFn: HashFn;
+    _versioning: NodeVersionInfo | undefined;
+    /**
+     * Explicit versioning level, tracked separately from `_versioning` so
+     * monotonicity checks and future v2/v3 extensions don't rely on the
+     * fragile `"cid" in _versioning` shape discriminator. `undefined` means
+     * the node has no versioning attached; `0` / `1` / future levels name
+     * the tier. Mutated in lockstep with `_versioning` by the constructor
+     * and by `_applyVersioning`.
+     */
+    _versioningLevel: VersioningLevel | undefined;
+    _lastMutation: {
+        actor: Actor;
+        timestamp_ns: number;
+    } | undefined;
+    /**
+     * @internal Per-node inspector hooks for `Graph.observe(path,
+     * { causal, derived })`. Fires in `_onDepMessage` and `_execFn`.
+     * Attached via `_setInspectorHook` (returns a disposer). Multiple
+     * observers can attach simultaneously — all registered hooks fire for
+     * every event.
+     */
+    _inspectorHooks: Set<NodeInspectorHook> | undefined;
+    readonly _actions: NodeActions;
+    constructor(deps: readonly Node[], fn: NodeFn | undefined, opts: NodeOptions<T>);
+    private get _isTerminal();
+    get name(): string | undefined;
+    get status(): NodeStatus;
+    get cache(): T | undefined | null;
+    get lastMutation(): Readonly<{
+        actor: Actor;
+        timestamp_ns: number;
+    }> | undefined;
+    get v(): Readonly<NodeVersionInfo> | undefined;
+    hasGuard(): boolean;
+    /**
+     * @internal Retroactively attach (or upgrade) versioning state on this
+     * node. Intended for `Graph.setVersioning(level)` bulk application and
+     * for rare cases where a specific node needs to be bumped to a higher
+     * level (e.g., `v0 → v1`) after construction.
+     *
+     * **Safety:** the mutation is rejected mid-wave. Specifically,
+     * throws if the node is currently executing its fn (`_isExecutingFn`).
+     * Callers at quiescent points — before the first sink subscribes, or
+     * after all sinks unsubscribe, or between external `down()` / `emit()`
+     * invocations — are safe. The re-entrance window that motivated §10.6.4
+     * removal was the "transition `_versioning` from `undefined` to a fresh
+     * object mid-`_updateState`" case; that path is now guarded.
+     *
+     * **Monotonicity:** levels can only go up. Downgrade (e.g., `v1 → v0`)
+     * is a no-op — once a node carries higher-level metadata, dropping it
+     * mid-graph would tear the linked-history invariant for v1 and above.
+     *
+     * **Linked-history boundary (D1, 2026-04-13):** upgrading v0 → v1
+     * produces a **fresh history root**. The new v1 state has `cid =
+     * hash(currentCachedValue)` and `prev = null`, not a synthetic `prev`
+     * anchored to any previous v0 value. The v0 monotonic `version` counter
+     * is preserved across the upgrade, but the linked-cid chain (spec §7)
+     * starts fresh at the upgrade point. Downstream audit tools that walk
+     * `v.cid.prev` backwards through time will see a `null` boundary at
+     * the upgrade — **this is intentional**: v0 had no cid to link to, and
+     * fabricating one would lie about the hash. Callers that require an
+     * unbroken cid chain from birth must attach versioning at construction
+     * via `opts.versioning` or `config.defaultVersioning`, not retroactively.
+     *
+     * @param level - New minimum versioning level.
+     * @param opts - Optional id / hash overrides; applied only if the
+     *   node currently has no versioning state.
+     */
+    _applyVersioning(level: VersioningLevel, opts?: {
+        id?: string;
+        hash?: HashFn;
+    }): void;
+    /**
+     * @internal Attach an inspector hook. Returns a disposer that removes
+     * the hook. Used by `Graph.observe(path, { causal, derived })` to build
+     * causal traces. Multiple hooks may be attached concurrently — all fire
+     * for every event in registration order. Passing `undefined` is a no-op
+     * and returns a no-op disposer.
+     */
+    _setInspectorHook(hook?: NodeInspectorHook): () => void;
+    allowsObserve(actor: Actor): boolean;
+    private _checkGuard;
+    down(messageOrMessages: Message | Messages, options?: NodeTransportOptions): void;
+    emit(value: T | undefined | null, options?: NodeTransportOptions): void;
+    up(messageOrMessages: Message | Messages, options?: NodeTransportOptions): void;
+    /**
+     * @internal Internal up-path used by `actions.up(...)` from inside fn.
+     * Same tier validation as public `up`, but bypasses the guard check
+     * since the fn context is already inside an authorized operation.
+     */
+    private _emitUp;
+    /**
+     * @internal Enforce spec §1.2 — up-direction messages are restricted to
+     * tier 0–2 and tier 5 (START, DIRTY, INVALIDATE, PAUSE, RESUME,
+     * TEARDOWN). Tier 3 (DATA/RESOLVED) and tier 4 (COMPLETE/ERROR) are
+     * downstream-only. Emitting tier-3/4 via `up` would bypass equals
+     * substitution and cache advance entirely and is a protocol bug.
+     */
+    private _validateUpTiers;
+    subscribe(sink: NodeSink, actor?: Actor): () => void;
+    private _removeSink;
+    /**
+     * @internal First-sink activation. For a producer (no deps + fn),
+     * invokes fn once. For a compute node (has deps), subscribes to every
+     * dep with the pre-set-dirty trick so the first-run gate waits for
+     * every dep to settle at least once.
+     */
+    _activate(): void;
+    /**
+     * @internal Append a dep post-construction. Used by `autoTrackNode`
+     * (runtime dep discovery) and `Graph.connect()` (post-construction
+     * wiring). Subscribes immediately — if DATA arrives synchronously
+     * during subscribe and fn is currently executing, the re-run is
+     * deferred via `_pendingRerun` flag (see `_execFn` guard).
+     *
+     * **Dedup:** idempotent on duplicate `depNode` — if `depNode` is
+     * already in `_deps`, returns the existing index without mutating
+     * state. Callers can safely invoke `_addDep` without their own
+     * "already added" check. `autoTrackNode` still keeps a `depIndexMap`
+     * as a fast-path lookup for known deps (returning cached `data[idx]`
+     * without calling `_addDep` at all); this internal dedup is the
+     * backstop for any caller that doesn't track its own dep set.
+     *
+     * @returns The index of the new dep in `_deps`, or the existing index
+     *   if the dep was already present.
+     */
+    _addDep(depNode: Node): number;
+    /**
+     * @internal Unsubscribes from deps, fires fn cleanup (both shapes),
+     * clears wave/store state, and (for compute nodes) drops `_cached` per
+     * the ROM/RAM rule. Idempotent: second call is a no-op.
+     *
+     * @param skipStatusUpdate — When `true`, the caller takes responsibility
+     *   for setting `_status` after deactivation (e.g. TEARDOWN always sets
+     *   `"sentinel"` unconditionally). When `false` (default), deactivation
+     *   applies the ROM rule: compute nodes → `"sentinel"`, state nodes
+     *   preserve their current status.
+     */
+    _deactivate(skipStatusUpdate?: boolean): void;
+    /**
+     * @internal Default per-tier dispatch for incoming dep messages. Called
+     * by `defaultOnMessage`. Updates the DepRecord, triggers wave
+     * completion, and forwards passthrough traffic.
+     */
+    _onDepMessage(depIndex: number, msg: Message): void;
+    /**
+     * Called when a dep transitions `dirty: false → true` (either from an
+     * incoming DIRTY, or pre-set during `_activate` / `_addDep` /
+     * `_depInvalidated`). No-op if the dep is already dirty. Fires the
+     * downstream DIRTY emit if we're the first to dirty this wave.
+     */
+    private _depDirtied;
+    /**
+     * Called when a dep delivers new DATA: clears dirty, stores the payload,
+     * marks wave-has-data, and — if this is the dep's first DATA — clears
+     * its sentinel slot so the first-run gate can open.
+     */
+    private _depSettledAsData;
+    /**
+     * Called when a dep emits RESOLVED (wave settled, value unchanged).
+     * Clears dirty; does NOT touch `prevData` / `terminal` / sentinel
+     * count — sentinel only exits on first DATA or terminal, not RESOLVED.
+     */
+    private _depSettledAsResolved;
+    /**
+     * Called when a dep delivers COMPLETE (`terminal = true`) or ERROR
+     * (`terminal = errorPayload`). Clears dirty, stores the terminal, and
+     * — if the dep had never contributed a DATA yet — leaves sentinel
+     * since the gate treats "terminated without data" as gate-open too.
+     */
+    private _depSettledAsTerminal;
+    /**
+     * Called when a dep emits INVALIDATE: clears prevData, terminal, and
+     * dataBatch. The dep is now back in the "never delivered a real value"
+     * state — `prevData === undefined` so the sentinel check in fn will fire.
+     */
+    private _depInvalidated;
+    private _maybeRunFnOnSettlement;
+    private _maybeAutoTerminalAfterWave;
+    /**
+     * @internal Runs the node fn once. Default cleanup (function form) fires
+     * before the new run; `{ deactivation }` cleanup survives.
+     */
+    private _execFn;
+    private _clearWaveFlags;
+    private _wrapFnError;
+    /**
+     * @internal Stable tier sort + synthetic DIRTY prefix for an outgoing
+     * batch. Fast path: already-monotone single-tier batches (the common
+     * case from interned singletons like `DIRTY_ONLY_BATCH`) return the
+     * input unchanged. General path: decorate-sort-undecorate into a new
+     * array, then prepend `[DIRTY]` after any tier-0 START entries when
+     * a tier-3 payload is present and the node isn't already dirty.
+     *
+     * Single source of truth for the spec §1.3.1 framing invariant. Every
+     * outgoing path hits `_frameBatch` exactly once via `_emit`.
+     */
+    private _frameBatch;
+    /**
+     * @internal The unified dispatch waist — one call = one wave.
+     *
+     * Pipeline stages, in order:
+     *
+     *   1. Early-return on empty batch.
+     *   2. Terminal filter — post-COMPLETE/ERROR only TEARDOWN/INVALIDATE
+     *      still propagate so graph teardown and cache-clear still work.
+     *   3. Tier sort (stable) — the batch can be in any order when it
+     *      arrives; the walker downstream (`downWithBatch`) assumes
+     *      ascending tier monotone, and so does `_updateState`'s tier-3
+     *      slice walk. This is the single source of truth for ordering.
+     *   4. Synthetic DIRTY prefix — if a tier-3 payload is present, no
+     *      DIRTY is already in the batch, and the node isn't already in
+     *      `"dirty"` status, prepend `[DIRTY]` after any tier-0 START
+     *      entries. Guarantees spec §1.3.1 (DIRTY precedes DATA within
+     *      the same batch) uniformly across every entry point.
+     *   5. PAUSE/RESUME lock bookkeeping (C0) — update `_pauseLocks`,
+     *      derive `_paused`, filter unknown-lockId RESUME, replay
+     *      bufferAll buffer on final lock release.
+     *   6. Meta TEARDOWN fan-out — notify meta children before
+     *      `_updateState`'s TEARDOWN branch calls `_deactivate`. Hoisted
+     *      out of the walk to keep `_updateState` re-entrance-free.
+     *   7. `_updateState` — walk the batch in tier order, advancing
+     *      `_cached` / `_status` / `_versioning` and running equals
+     *      substitution on tier-3 DATA (§3.5.1). Returns
+     *      `{finalMessages, equalsError?}`.
+     *   8. `downWithBatch` dispatch (or bufferAll capture if paused with
+     *      `pausable: "resumeAll"`).
+     *   9. Recursive ERROR emission if equals threw mid-walk.
+     *
+     * `node.down` / `node.emit` / `actions.down` / `actions.emit` all
+     * converge here — the unified `_emit` waist (spec §1.3.1).
+     */
+    _emit(messages: Messages): void;
+    /**
+     * @internal Walk an outgoing (already-framed) batch, updating own
+     * cache / status / versioning and running equals substitution on
+     * every tier-3 DATA (§3.5.1). Framing — tier sort and synthetic
+     * DIRTY prefix — has already happened upstream in `_frameBatch`.
+     * This walk trusts the input is in monotone tier order and that the
+     * spec §1.3.1 DIRTY/RESOLVED precedence invariant is already
+     * satisfied by the frame.
+     *
+     * Equals substitution: every DATA payload is compared against the
+     * live `_cached`; when equal, the tuple is rewritten to `[RESOLVED]`
+     * in a per-call copy and cache is not re-advanced. `.cache` remains
+     * coherent with "the last DATA payload this node actually sent
+     * downstream".
+     *
+     * Returns `{ finalMessages, equalsError? }`:
+     * - `finalMessages` — the array to deliver to sinks (may be
+     *   `messages` unchanged, a rewritten copy with DATA→RESOLVED
+     *   substitutions, or a truncated prefix when equals throws mid-walk).
+     * - `equalsError` — present only when the configured `equals` function
+     *   threw on some DATA message. `_emit` delivers the prefix first,
+     *   then emits a fresh ERROR batch via a recursive `_emit` call so
+     *   subscribers observe `[...walked_prefix, ERROR]` in order.
+     */
+    private _updateState;
+    private _deliverToSinks;
+    /**
+     * @internal Dispatch entry point that respects the per-batch emit
+     * accumulator (Bug 2). Inside an explicit `batch()` scope, append to
+     * `_batchPendingMessages` and register a flush hook on first append.
+     * Outside batch — or during a drain (where `flushInProgress` is true
+     * but `batchDepth` is 0) — dispatch synchronously through `downWithBatch`.
+     *
+     * Per-emit state updates (`_frameBatch`, `_updateState`) have already
+     * happened by the time we reach here; only the **downstream delivery**
+     * is coalesced. Cache, version, and status are visible mid-batch on
+     * the emitting node itself.
+     */
+    private _dispatchOrAccumulate;
+    /**
+     * @internal Flushes the accumulated batch through `downWithBatch` and
+     * clears the pending state. Idempotent — safe to call when pending is
+     * already null or empty (e.g. on a `batch()` throw, where the hook
+     * fires for cleanup but the drainPhase queues are wiped after).
+     *
+     * Critical: the accumulated batch is interleaved per-emit framings like
+     * `[DIRTY, DATA(1), DIRTY, DATA(2)]` — non-monotone tier order. We must
+     * re-frame to sort by tier before handing to `downWithBatch`, which
+     * assumes pre-sorted input. `_frameBatch` also handles the synthetic
+     * DIRTY prepend rule (no-op here — `hasDirty` is true since each
+     * accumulated emit already carries its own DIRTY prefix).
+     */
+    private _flushBatchPending;
+}
+/**
+ * Creates a reactive {@link Node} — the single GraphReFly primitive (§2).
+ *
+ * Typical shapes:
+ * - `node([])` / `node({ initial: v })` — a manual source (state node).
+ * - `node(producerFn, opts)` — a producer that runs on first-subscribe.
+ * - `node(deps, computeFn, opts)` — a derived / effect node.
+ *
+ * For value-returning computations, prefer the sugar factories in `sugar.ts`
+ * (`state`, `derived`, `effect`, `producer`, `dynamicNode`), which wrap user
+ * fns with `actions.emit(userFn(data))`. Calling `node()` directly gives you
+ * the raw `NodeFn` contract: explicit emission via `actions`, cleanup return.
+ */
+declare function node<T = unknown>(depsOrFn?: readonly Node[] | NodeFn | NodeOptions<T>, fnOrOpts?: NodeFn | NodeOptions<T>, optsArg?: NodeOptions<T>): Node<T>;
+
+export { START_MSG as $, type Actor as A, type NodeInspectorHook as B, COMPLETE as C, DATA as D, ERROR as E, type FnCtx as F, type GlobalInspectorEvent as G, type HashFn as H, INVALIDATE as I, type NodeInspectorHookEvent as J, type NodeSink as K, type NodeStatus as L, type Message as M, type Node as N, type NodeTransportOptions as O, type NodeVersionInfo as P, type OnMessageHandler as Q, type OnSubscribeHandler as R, PAUSE as S, type PolicyAllow as T, type PolicyDeny as U, type PolicyRuleData as V, RESOLVED as W, RESOLVED_MSG as X, RESOLVED_ONLY_BATCH as Y, RESUME as Z, START as _, type NodeOptions as a, type SubscribeContext as a0, TEARDOWN as a1, TEARDOWN_MSG as a2, TEARDOWN_ONLY_BATCH as a3, type V0 as a4, type V1 as a5, type VersioningLevel as a6, type VersioningOptions as a7, accessHintForGuard as a8, advanceVersion as a9, configure as aa, createVersioning as ab, defaultConfig as ac, defaultHash as ad, isV1 as ae, node as af, normalizeActor as ag, policy as ah, policyFromRules as ai, registerBuiltins as aj, type NodeActions as b, COMPLETE_MSG as c, COMPLETE_ONLY_BATCH as d, DEFAULT_ACTOR as e, DIRTY as f, DIRTY_MSG as g, DIRTY_ONLY_BATCH as h, type DepRecord as i, type GlobalInspectorHook as j, GraphReFlyConfig as k, type GuardAction as l, GuardDenied as m, type GuardDeniedDetails as n, INVALIDATE_MSG as o, INVALIDATE_ONLY_BATCH as p, type MessageContext as q, type MessageTypeRegistration as r, type MessageTypeRegistrationInput as s, type Messages as t, type NodeCtx as u, type NodeDescribeKind as v, type NodeFn as w, type NodeFnCleanup as x, type NodeGuard as y, NodeImpl as z };