@graphrefly/graphrefly 0.1.0

package/dist/meta-BsF6Sag9.d.cts

@@ -0,0 +1,607 @@
+/**
+ * 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;
+
+/**
+ * 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 `emitWithBatch`, 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.
+ *
+ * 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;
+
+/** Lifecycle status of a node. */
+type NodeStatus = "disconnected" | "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}. */
+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.
+ *
+ * Called for every message from every dep. Return `true` to consume the
+ * message (skip default handling), or `false` to let default dispatch run.
+ *
+ * @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.
+ */
+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} / {@link describeNode} (GRAPHREFLY-SPEC Appendix B). */
+type NodeDescribeKind = "state" | "derived" | "producer" | "operator" | "effect";
+/** Options for {@link node}. */
+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 disconnects upstream 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).
+     * - `0` (V0): `id` + `version` — identity & change detection.
+     * - `1` (V1): + `cid` + `prev` — content addressing & linked history.
+     */
+    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).
+ */
+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} to enable per-sink
+ * optimizations.
+ */
+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`.
+     */
+    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?: 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 {@link NodeTransportOptions.actor | actor} may {@link Graph.observe | 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;
+}
+/**
+ * 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`.
+ *
+ * @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>;
+
+/** 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;
+    /** Node versioning info (GRAPHREFLY-SPEC §7). Present only when versioning is enabled. */
+    v?: {
+        id: string;
+        version: number;
+        cid?: string;
+        prev?: 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));
+ * ```
+ */
+declare function describeNode(node: Node): DescribeNodeOutput;
+
+export { propagatesToMeta as $, type Actor as A, describeNode as B, COMPLETE as C, DATA as D, ERROR as E, isKnownMessageType as F, type GuardAction as G, type HashFn as H, INVALIDATE as I, isPhase2Message as J, isTerminalMessage as K, isV1 as L, type Message as M, type Node as N, type OnMessageHandler as O, PAUSE as P, knownMessageTypes as Q, RESOLVED as R, type SubscribeHints as S, TEARDOWN as T, messageTier as U, type V0 as V, metaSnapshot as W, node as X, normalizeActor as Y, policy as Z, policyFromRules as _, type NodeOptions as a, type NodeInspectorHook as a0, type NodeActions as b, type NodeFn as c, DEFAULT_ACTOR as d, DIRTY as e, type DescribeNodeOutput as f, GuardDenied as g, type GuardDeniedDetails as h, type Messages as i, type NodeDescribeKind as j, type NodeGuard as k, type NodeSink as l, type NodeStatus as m, type NodeTransportOptions as n, type NodeVersionInfo as o, type PolicyAllow as p, type PolicyDeny as q, type PolicyRuleData as r, RESUME as s, type V1 as t, type VersioningLevel as u, type VersioningOptions as v, accessHintForGuard as w, advanceVersion as x, createVersioning as y, defaultHash as z };