@graphrefly/graphrefly 0.21.0 → 0.23.0

package/dist/meta-BnG7XAaE.d.ts

@@ -1,778 +0,0 @@
-/**
- * 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).
- *
- * @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;
-
-/**
- * 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;
-
-/**
- * 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.get()) === 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;
-
-/**
- * `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 (GRAPHREFLY-SPEC §2.2). */
-type NodeStatus = "disconnected" | "pending" | "dirty" | "settled" | "resolved" | "completed" | "errored";
-/** Callback that receives downstream message batches. */
-type NodeSink = (messages: Messages) => void;
-/** Imperative actions available inside a node's compute function. */
-interface NodeActions {
-    /** Emit raw messages downstream. */
-    down(messages: Messages): void;
-    /** Emit a single value (auto-wraps in DIRTY/DATA or DIRTY/RESOLVED). */
-    emit(value: unknown): void;
-    /** Send messages upstream toward sources. */
-    up(messages: Messages): void;
-}
-/**
- * Callback for intercepting messages before the default dispatch (§2.6).
- *
- * 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;
-/**
- * Internal inspector hook (opt-in): emits dependency message and run events
- * for graph-level observability features (`observe(..., { causal|derived })`).
- */
-type NodeInspectorHookEvent = {
-    kind: "dep_message";
-    depIndex: number;
-    message: Message;
-} | {
-    kind: "run";
-    depValues: readonly unknown[];
-};
-type NodeInspectorHook = (event: NodeInspectorHookEvent) => void;
-/** Explicit describe `type` for {@link Graph.describe} (GRAPHREFLY-SPEC Appendix B). */
-type NodeDescribeKind = "state" | "derived" | "producer" | "operator" | "effect";
-/** Options accepted by every node constructor. */
-interface NodeOptions {
-    name?: string;
-    /**
-     * Overrides inferred `type` in describe output. Sugar constructors set this;
-     * omit to infer from deps / fn / manual emit usage.
-     */
-    describeKind?: NodeDescribeKind;
-    /** Equality check for RESOLVED detection. Defaults to `Object.is`. */
-    equals?: (a: unknown, b: unknown) => boolean;
-    initial?: unknown;
-    /**
-     * Each key becomes an independently subscribable companion node.
-     * Meta nodes outlive the parent's subscription lifecycle: when all sinks
-     * unsubscribe the parent deactivates but meta nodes stay alive.
-     * Send `[[TEARDOWN]]` to the parent to release meta node resources.
-     */
-    meta?: Record<string, unknown>;
-    /** Allow fresh subscriptions after COMPLETE/ERROR. */
-    resubscribable?: boolean;
-    /**
-     * Invoked when a new {@link Node.subscribe} clears a terminal state on a
-     * resubscribable node — reset operator-local counters/accumulators here.
-     */
-    onResubscribe?: () => void;
-    /** Clear cached value on TEARDOWN. */
-    resetOnTeardown?: boolean;
-    /**
-     * When `true` (default), auto-emit `[[COMPLETE]]` when all deps complete
-     * (spec §1.3.5). Set `false` for derived/operator nodes that should not
-     * auto-complete.
-     */
-    completeWhenDepsComplete?: boolean;
-    /**
-     * Intercept messages before the default dispatch (spec §2.6).
-     *
-     * Return `true` to consume the message (skip default handling),
-     * or `false` to let the default dispatch run.
-     */
-    onMessage?: OnMessageHandler;
-    /**
-     * ABAC: `(actor, action) => boolean`. `write` applies to both {@link Node.down} and {@link Node.up}.
-     * Companion {@link NodeOptions.meta | meta} nodes inherit this guard from the primary.
-     */
-    guard?: NodeGuard;
-    /** 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;
-}
-/** Actor/delivery context for {@link Node.down} and {@link Node.up}. */
-type NodeTransportOptions = {
-    actor?: Actor;
-    /**
-     * When `true`, skips guard checks (reactive internals, graph lifecycle TEARDOWN, etc.).
-     * Not for untrusted call sites.
-     */
-    internal?: boolean;
-    /**
-     * `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}. */
-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.
-     */
-    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.
-     */
-    actor?: Actor;
-}
-/** A reactive node in the GraphReFly protocol. */
-interface Node<T = unknown> {
-    readonly name?: string;
-    readonly status: NodeStatus;
-    readonly meta: Record<string, Node>;
-    /** Returns the current cached value. */
-    get(): T | undefined;
-    /** Push messages downstream. */
-    down(messages: Messages, options?: NodeTransportOptions): void;
-    /**
-     * Registers a sink to receive downstream messages.
-     *
-     * @param sink - Callback receiving message batches.
-     * @param hints - Optional optimization hints (e.g. `{ singleDep: true }`).
-     * @returns An unsubscribe function (idempotent).
-     */
-    subscribe(sink: NodeSink, hints?: SubscribeHints): () => void;
-    /** Send messages upstream (present on nodes with deps). */
-    up?: (messages: Messages, options?: NodeTransportOptions) => void;
-    /** Disconnect from upstream deps (present on nodes with deps). */
-    unsubscribe?: () => void;
-    /** Last successful guarded `down` / `up` (not set for `internal` deliveries). */
-    readonly lastMutation?: Readonly<{
-        actor: Actor;
-        timestamp_ns: number;
-    }>;
-    /** Whether `actor` may {@link Graph.observe} this node. */
-    allowsObserve(actor: Actor): boolean;
-    /** Whether a {@link NodeOptions.guard | guard} is installed. */
-    hasGuard(): boolean;
-    /** Versioning info (GRAPHREFLY-SPEC §7). `undefined` when versioning is not enabled. */
-    readonly v: Readonly<NodeVersionInfo> | undefined;
-}
-/**
- * Explicit cleanup wrapper. When a node fn returns `{ cleanup, value? }`,
- * `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.
- */
-type CleanupResult<T = unknown> = {
-    readonly [CLEANUP_RESULT]: true;
-    cleanup: () => void;
-    value?: T;
-};
-/** Create a branded {@link CleanupResult}. */
-declare function cleanupResult<T>(cleanup: () => void): CleanupResult<T>;
-declare function cleanupResult<T>(cleanup: () => void, value: T): CleanupResult<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 = {
-    type: "state" | "derived" | "producer" | "operator" | "effect";
-    status?: Node["status"];
-    deps: string[];
-    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;
-        version: number;
-        cid?: string;
-        prev?: string | null;
-    };
-    /** Guard info (full detail). */
-    guard?: string;
-    /** Last mutation attribution (full detail). */
-    lastMutation?: Readonly<{
-        actor: Actor;
-        timestamp_ns: number;
-    }>;
-};
-/**
- * Detail level for `describe()` progressive disclosure (Phase 3.3b).
- * - `"minimal"` — type + deps only (default). LLM-friendly.
- * - `"standard"` — type, status, value, deps, meta, versioning (`v`).
- * - `"full"` — standard + guard, lastMutation.
- */
-type DescribeDetail = "minimal" | "standard" | "full";
-/**
- * Valid field names for `describe({ fields: [...] })` (Phase 3.3b).
- * Dotted paths like `"meta.label"` select specific meta keys.
- */
-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;
-
-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 };