@graphrefly/graphrefly 0.6.0 → 0.8.0

package/README.md

@@ -1,8 +1,8 @@
 # GraphReFly
 
-**Reactive graph protocol for human + LLM co-operation.**
+**Describe what matters. It watches, filters, and explains — persistently.**
 
-One primitive. Zero dependencies. Composable nodes with glitch-free diamond resolution, two-phase push propagation, durable streaming, and framework adapters for React, Vue, Svelte, Solid, and NestJS.
+You're buried under emails, alerts, feeds, and messages. You can't process it all. GraphReFly lets you describe automations in plain language, review them visually, run them persistently, and trace every decision back to its source.
 
 [![npm](https://img.shields.io/npm/v/@graphrefly/graphrefly?color=blue)](https://www.npmjs.com/package/@graphrefly/graphrefly)
 [![license](https://img.shields.io/github/license/graphrefly/graphrefly-ts)](./LICENSE)
@@ -11,6 +11,18 @@ One primitive. Zero dependencies. Composable nodes with glitch-free diamond reso
 
 ---
 
+<!-- TODO: Demo 0 GIF/video — NL → flow view → running → "why was this flagged?" -->
+
+## What can you do with it?
+
+**Email triage** — "Watch my inbox. Urgent emails from my team go to a priority list. Newsletters get summarized weekly. Everything else, count by sender." It watches, classifies, and alerts — and when you ask "why was this flagged?", it walks you through the reasoning.
+
+**Spending alerts** — Connect bank transactions to budget categories. Get a push notification when monthly dining exceeds your target. No polling, no manual checks — changes propagate the moment data arrives.
+
+**Knowledge management** — Notes, bookmarks, highlights flow in. Contradictions surface automatically. Related ideas link themselves. Your second brain stays current without you maintaining it.
+
+---
+
 ## Quick start
 
 ```bash
@@ -30,20 +42,24 @@ count.set(3);
 // → doubled: 6
 ```
 
+## How it works
+
+You describe what you need — an LLM composes a reactive graph (like SQL for data flows). The graph runs persistently, checkpoints its state, and traces every decision through a causal chain. Ask "why?" at any point and get a human-readable explanation from source to conclusion.
+
 ## Why GraphReFly?
 
-Most state libraries solve **one** problem well. GraphReFly solves the space between them:
-
-|  | Zustand / Jotai | RxJS | XState | TC39 Signals | **GraphReFly** |
-|--|-----------------|------|--------|-------------|---------------|
-| Simple store API | yes | no | no | yes | **yes** |
-| Streaming operators | no | yes | no | no | **yes** |
-| Diamond resolution | no | n/a | n/a | partial | **glitch-free** |
-| Graph introspection | no | no | visual | no | **describe / observe / diagram** |
-| Durable checkpoints | no | no | persistence | no | **file / SQLite / IndexedDB** |
-| LLM orchestration | no | no | no | no | **agentLoop / chatStream / toolRegistry** |
-| Framework adapters | React | Angular | React / Vue | varies | **React / Vue / Svelte / Solid / NestJS** |
-| Dependencies | 0 | 0 | 0 | n/a | **0** |
+|  | Zustand / Jotai | RxJS | XState | LangGraph | TC39 Signals | **GraphReFly** |
+|--|-----------------|------|--------|-----------|-------------|---------------|
+| Simple store API | yes | no | no | no | yes | **yes** |
+| Streaming operators | no | yes | no | no | no | **yes** |
+| Diamond resolution | no | n/a | n/a | n/a | partial | **glitch-free** |
+| Graph introspection | no | no | visual | checkpoints | no | **describe / observe / diagram** |
+| Causal tracing | no | no | no | no | no | **explain every decision** |
+| Durable checkpoints | no | no | persistence | yes | no | **file / SQLite / IndexedDB** |
+| LLM orchestration | no | no | no | yes | no | **agentLoop / chatStream / toolRegistry** |
+| NL → graph composition | no | no | no | no | no | **graphFromSpec / llmCompose** |
+| Framework adapters | React | Angular | React / Vue | n/a | varies | **React / Vue / Svelte / Solid / NestJS** |
+| Dependencies | 0 | 0 | 0 | many | n/a | **0** |
 
 ## One primitive
 

package/dist/{chunk-HP7OKEOE.js → chunk-A2AJJOSJ.js}

@@ -2,10 +2,10 @@ import {
   GRAPH_META_SEGMENT,
   Graph,
   reachable
-} from "./chunk-6W5SGIGB.js";
+} from "./chunk-WYI7YW54.js";
 import {
   __export
-} from "./chunk-5X3LAO3B.js";
+} from "./chunk-QTZSBQGJ.js";
 
 // src/graph/index.ts
 var graph_exports = {};
@@ -104,4 +104,4 @@ export {
   replayWAL,
   graph_exports
 };
-//# sourceMappingURL=chunk-HP7OKEOE.js.map
+//# sourceMappingURL=chunk-A2AJJOSJ.js.map

package/dist/chunk-A2AJJOSJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/graph/index.ts","../src/graph/codec.ts"],"sourcesContent":["/**\n * Graph container: registry, wiring, introspection (Phase 1).\n */\n\nexport {\n\tcreateDagCborCodec,\n\tcreateDagCborZstdCodec,\n\ttype DeltaCheckpoint,\n\ttype EvictedSubgraphInfo,\n\ttype EvictionPolicy,\n\ttype GraphCodec,\n\tJsonCodec,\n\ttype LazyGraphCodec,\n\tnegotiateCodec,\n\treplayWAL,\n\ttype WALEntry,\n} from \"./codec.js\";\nexport {\n\ttype AutoCheckpointAdapter,\n\ttype DescribeFilter,\n\tGRAPH_META_SEGMENT,\n\tGraph,\n\ttype GraphActorOptions,\n\ttype GraphAutoCheckpointHandle,\n\ttype GraphAutoCheckpointOptions,\n\ttype GraphCheckpointRecord,\n\ttype GraphDescribeOptions,\n\ttype GraphDescribeOutput,\n\ttype GraphDiagramDirection,\n\ttype GraphDiagramOptions,\n\ttype GraphDiffChange,\n\ttype GraphDiffResult,\n\ttype GraphDumpOptions,\n\ttype GraphFactoryContext,\n\ttype GraphNodeFactory,\n\ttype GraphObserveAll,\n\ttype GraphObserveOne,\n\ttype GraphOptions,\n\ttype GraphPersistSnapshot,\n\ttype GraphSpyHandle,\n\ttype GraphSpyOptions,\n\ttype GraphSpyTheme,\n\ttype GraphSpyThemeName,\n\ttype ObserveDetail,\n\ttype ObserveEvent,\n\ttype ObserveOptions,\n\ttype ObserveResult,\n\ttype ReachableDirection,\n\ttype ReachableOptions,\n\treachable,\n\ttype TraceEntry,\n} from \"./graph.js\";\n","/**\n * GraphCodec — pluggable serialization for graph snapshots (Phase 8.6).\n *\n * Design reference: `archive/docs/SESSION-serialization-memory-footprint.md`\n *\n * The codec interface decouples snapshot format from graph internals.\n * Default is JSON (current behavior). DAG-CBOR and compressed variants\n * ship as optional codecs. FlatBuffers/Arrow for advanced tiers.\n *\n * Tiered representation:\n *   HOT  — JS objects (live propagation, no codec involved)\n *   WARM — DAG-CBOR in-memory buffer (lazy hydration, delta checkpoints)\n *   COLD — Arrow/Parquet (bulk storage, ML pipelines, archival)\n *   PEEK — FlatBuffers (zero-copy read from dormant graph)\n */\n\nimport type { GraphPersistSnapshot } from \"./graph.js\";\n\n// ---------------------------------------------------------------------------\n// Core codec interface\n// ---------------------------------------------------------------------------\n\n/**\n * Encode/decode graph snapshots to/from binary.\n *\n * Implementations must be deterministic: `encode(x)` always produces the\n * same bytes for the same input. This is critical for CID computation (V1)\n * and snapshot hash-comparison.\n */\nexport interface GraphCodec {\n\t/** MIME-like content type identifier (e.g. \"application/dag-cbor+zstd\"). */\n\treadonly contentType: string;\n\n\t/** Human-readable name for diagnostics. */\n\treadonly name: string;\n\n\t/** Encode a snapshot to binary. */\n\tencode(snapshot: GraphPersistSnapshot): Uint8Array;\n\n\t/**\n\t * Decode binary back to a snapshot.\n\t *\n\t * For lazy codecs, this may return a proxy that decodes nodes on access\n\t * (see {@link LazyGraphCodec}).\n\t */\n\tdecode(buffer: Uint8Array): GraphPersistSnapshot;\n}\n\n/**\n * Extended codec that supports lazy (on-demand) node decoding.\n *\n * `decodeLazy` returns a snapshot where `nodes` is a Proxy — individual\n * nodes are decoded only when accessed. This enables near-zero cold-start\n * for large graphs (decode envelope + topology, skip node values until read).\n */\nexport interface LazyGraphCodec extends GraphCodec {\n\t/** Decode envelope and topology; defer node value decoding to access time. */\n\tdecodeLazy(buffer: Uint8Array): GraphPersistSnapshot;\n}\n\n// ---------------------------------------------------------------------------\n// Delta checkpoint types (requires V0 — Phase 6.0)\n// ---------------------------------------------------------------------------\n\n/**\n * A delta checkpoint: only the nodes that changed since last checkpoint.\n *\n * Append-only: each delta is identified by `seq` (monotonic). A full\n * snapshot is taken every `compactEvery` deltas for WAL compaction.\n */\nexport interface DeltaCheckpoint {\n\t/** Monotonic sequence number. */\n\tseq: number;\n\t/** Graph name. */\n\tname: string;\n\t/** Base snapshot seq this delta applies to (0 = initial full snapshot). */\n\tbaseSec: number;\n\t/** Only nodes with version > lastCheckpoint. Keyed by node name. */\n\tnodes: Record<\n\t\tstring,\n\t\t{\n\t\t\t/** V0 version at time of checkpoint. */\n\t\t\tversion: number;\n\t\t\t/** Serialized node value (codec-dependent). */\n\t\t\tvalue: unknown;\n\t\t\t/** Meta snapshot (only if materialized). */\n\t\t\tmeta?: Record<string, unknown>;\n\t\t}\n\t>;\n\t/** Nodes removed since last checkpoint. */\n\tremoved: string[];\n\t/** Edges added since last checkpoint. */\n\tedgesAdded: ReadonlyArray<{ from: string; to: string }>;\n\t/** Edges removed since last checkpoint. */\n\tedgesRemoved: ReadonlyArray<{ from: string; to: string }>;\n\t/** Timestamp (wall-clock ns) of this checkpoint. */\n\ttimestampNs: bigint;\n}\n\n/**\n * WAL entry: either a full snapshot or a delta.\n */\nexport type WALEntry =\n\t| { type: \"full\"; snapshot: GraphPersistSnapshot; seq: number }\n\t| { type: \"delta\"; delta: DeltaCheckpoint };\n\n// ---------------------------------------------------------------------------\n// Eviction policy (dormant subgraph management)\n// ---------------------------------------------------------------------------\n\n/**\n * Policy for evicting dormant subgraphs to reduce memory.\n *\n * When a subgraph hasn't propagated for `idleTimeoutMs`, it is serialized\n * using the graph's codec and JS objects are released. Re-hydrated on next\n * access (read, propagation, describe).\n */\nexport interface EvictionPolicy {\n\t/** Milliseconds of inactivity before eviction. */\n\tidleTimeoutMs: number;\n\t/** Codec to use for serializing evicted subgraphs (default: graph's codec). */\n\tcodec?: GraphCodec;\n}\n\n/** Metadata about an evicted subgraph, exposed via describe(). */\nexport interface EvictedSubgraphInfo {\n\t/** True if currently evicted (serialized, JS objects released). */\n\tevicted: true;\n\t/** Wall-clock ns of last propagation before eviction. */\n\tlastActiveNs: bigint;\n\t/** Size of serialized buffer in bytes. */\n\tserializedBytes: number;\n\t/** Codec used for serialization. */\n\tcodecName: string;\n}\n\n// ---------------------------------------------------------------------------\n// JSON codec (default — wraps current behavior)\n// ---------------------------------------------------------------------------\n\n/**\n * Default JSON codec. Wraps `JSON.stringify`/`JSON.parse` with deterministic\n * key ordering (matching current `snapshot()` behavior).\n */\nexport const JsonCodec: GraphCodec = {\n\tcontentType: \"application/json\",\n\tname: \"json\",\n\n\tencode(snapshot: GraphPersistSnapshot): Uint8Array {\n\t\t// Deterministic: snapshot() already sorts keys.\n\t\tconst json = JSON.stringify(snapshot);\n\t\treturn new TextEncoder().encode(json);\n\t},\n\n\tdecode(buffer: Uint8Array): GraphPersistSnapshot {\n\t\tconst json = new TextDecoder().decode(buffer);\n\t\treturn JSON.parse(json) as GraphPersistSnapshot;\n\t},\n};\n\n// ---------------------------------------------------------------------------\n// DAG-CBOR codec (stub — requires @ipld/dag-cbor)\n// ---------------------------------------------------------------------------\n\n/**\n * Create a DAG-CBOR codec.\n *\n * Requires `@ipld/dag-cbor` as a peer dependency. ~40-50% smaller than JSON,\n * deterministic encoding (required for V1 CID), CID links as native type.\n *\n * @example\n * ```ts\n * import * as dagCbor from \"@ipld/dag-cbor\";\n * const codec = createDagCborCodec(dagCbor);\n * const bytes = codec.encode(graph.snapshot());\n * ```\n */\nexport function createDagCborCodec(dagCbor: {\n\tencode: (value: unknown) => Uint8Array;\n\tdecode: (bytes: Uint8Array) => unknown;\n}): GraphCodec {\n\treturn {\n\t\tcontentType: \"application/dag-cbor\",\n\t\tname: \"dag-cbor\",\n\t\tencode: (snapshot) => dagCbor.encode(snapshot),\n\t\tdecode: (buffer) => dagCbor.decode(buffer) as GraphPersistSnapshot,\n\t};\n}\n\n/**\n * Create a DAG-CBOR + zstd codec. ~80-90% smaller than JSON.\n *\n * Requires `@ipld/dag-cbor` and a zstd implementation (e.g. `fzstd` for\n * browser, `node:zlib` for Node.js).\n *\n * @example\n * ```ts\n * import * as dagCbor from \"@ipld/dag-cbor\";\n * import { compressSync, decompressSync } from \"fzstd\";\n * const codec = createDagCborZstdCodec(dagCbor, { compressSync, decompressSync });\n * ```\n */\nexport function createDagCborZstdCodec(\n\tdagCbor: {\n\t\tencode: (value: unknown) => Uint8Array;\n\t\tdecode: (bytes: Uint8Array) => unknown;\n\t},\n\tzstd: {\n\t\tcompressSync: (data: Uint8Array) => Uint8Array;\n\t\tdecompressSync: (data: Uint8Array) => Uint8Array;\n\t},\n): GraphCodec {\n\treturn {\n\t\tcontentType: \"application/dag-cbor+zstd\",\n\t\tname: \"dag-cbor-zstd\",\n\t\tencode: (snapshot) => zstd.compressSync(dagCbor.encode(snapshot)),\n\t\tdecode: (buffer) => dagCbor.decode(zstd.decompressSync(buffer)) as GraphPersistSnapshot,\n\t};\n}\n\n// ---------------------------------------------------------------------------\n// Codec negotiation (for peerGraph)\n// ---------------------------------------------------------------------------\n\n/**\n * Negotiate a common codec between two peers.\n *\n * Each peer advertises its supported codecs (ordered by preference).\n * Returns the first codec supported by both, or null if none.\n */\nexport function negotiateCodec(\n\tlocalPreference: readonly GraphCodec[],\n\tremoteContentTypes: readonly string[],\n): GraphCodec | null {\n\tconst remoteSet = new Set(remoteContentTypes);\n\tfor (const codec of localPreference) {\n\t\tif (remoteSet.has(codec.contentType)) return codec;\n\t}\n\treturn null;\n}\n\n// ---------------------------------------------------------------------------\n// WAL helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Reconstruct a snapshot from a WAL (full snapshot + sequence of deltas).\n *\n * Applies deltas in order on top of the base snapshot. Validates that\n * delta `baseSec` chains correctly.\n */\nexport function replayWAL(entries: readonly WALEntry[]): GraphPersistSnapshot {\n\tif (entries.length === 0) {\n\t\tthrow new Error(\"WAL is empty — need at least one full snapshot\");\n\t}\n\n\tconst first = entries[0]!;\n\tif (first.type !== \"full\") {\n\t\tthrow new Error(\"WAL must start with a full snapshot\");\n\t}\n\n\t// Deep clone the base snapshot so we can mutate it.\n\tconst result: GraphPersistSnapshot = JSON.parse(JSON.stringify(first.snapshot));\n\n\tfor (let i = 1; i < entries.length; i++) {\n\t\tconst entry = entries[i]!;\n\t\tif (entry.type === \"full\") {\n\t\t\t// A compaction point — replace the entire result.\n\t\t\tObject.assign(result, JSON.parse(JSON.stringify(entry.snapshot)));\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst delta = entry.delta;\n\n\t\t// Apply node changes.\n\t\tfor (const [name, patch] of Object.entries(delta.nodes)) {\n\t\t\tif (result.nodes[name]) {\n\t\t\t\tresult.nodes[name]!.value = patch.value;\n\t\t\t\tif (patch.meta) {\n\t\t\t\t\tresult.nodes[name]!.meta = patch.meta;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\t// Apply removals.\n\t\tfor (const name of delta.removed) {\n\t\t\tdelete result.nodes[name];\n\t\t}\n\n\t\t// Apply edge changes.\n\t\tconst edges = [...result.edges];\n\t\tfor (const edge of delta.edgesRemoved) {\n\t\t\tconst idx = edges.findIndex((e) => e.from === edge.from && e.to === edge.to);\n\t\t\tif (idx !== -1) edges.splice(idx, 1);\n\t\t}\n\t\tfor (const edge of delta.edgesAdded) {\n\t\t\tedges.push(edge);\n\t\t}\n\t\t(result as unknown as { edges: typeof edges }).edges = edges;\n\t}\n\n\treturn result;\n}\n"],"mappings":";;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACgJO,IAAM,YAAwB;AAAA,EACpC,aAAa;AAAA,EACb,MAAM;AAAA,EAEN,OAAO,UAA4C;AAElD,UAAM,OAAO,KAAK,UAAU,QAAQ;AACpC,WAAO,IAAI,YAAY,EAAE,OAAO,IAAI;AAAA,EACrC;AAAA,EAEA,OAAO,QAA0C;AAChD,UAAM,OAAO,IAAI,YAAY,EAAE,OAAO,MAAM;AAC5C,WAAO,KAAK,MAAM,IAAI;AAAA,EACvB;AACD;AAmBO,SAAS,mBAAmB,SAGpB;AACd,SAAO;AAAA,IACN,aAAa;AAAA,IACb,MAAM;AAAA,IACN,QAAQ,CAAC,aAAa,QAAQ,OAAO,QAAQ;AAAA,IAC7C,QAAQ,CAAC,WAAW,QAAQ,OAAO,MAAM;AAAA,EAC1C;AACD;AAeO,SAAS,uBACf,SAIA,MAIa;AACb,SAAO;AAAA,IACN,aAAa;AAAA,IACb,MAAM;AAAA,IACN,QAAQ,CAAC,aAAa,KAAK,aAAa,QAAQ,OAAO,QAAQ,CAAC;AAAA,IAChE,QAAQ,CAAC,WAAW,QAAQ,OAAO,KAAK,eAAe,MAAM,CAAC;AAAA,EAC/D;AACD;AAYO,SAAS,eACf,iBACA,oBACoB;AACpB,QAAM,YAAY,IAAI,IAAI,kBAAkB;AAC5C,aAAW,SAAS,iBAAiB;AACpC,QAAI,UAAU,IAAI,MAAM,WAAW,EAAG,QAAO;AAAA,EAC9C;AACA,SAAO;AACR;AAYO,SAAS,UAAU,SAAoD;AAC7E,MAAI,QAAQ,WAAW,GAAG;AACzB,UAAM,IAAI,MAAM,qDAAgD;AAAA,EACjE;AAEA,QAAM,QAAQ,QAAQ,CAAC;AACvB,MAAI,MAAM,SAAS,QAAQ;AAC1B,UAAM,IAAI,MAAM,qCAAqC;AAAA,EACtD;AAGA,QAAM,SAA+B,KAAK,MAAM,KAAK,UAAU,MAAM,QAAQ,CAAC;AAE9E,WAAS,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAAK;AACxC,UAAM,QAAQ,QAAQ,CAAC;AACvB,QAAI,MAAM,SAAS,QAAQ;AAE1B,aAAO,OAAO,QAAQ,KAAK,MAAM,KAAK,UAAU,MAAM,QAAQ,CAAC,CAAC;AAChE;AAAA,IACD;AAEA,UAAM,QAAQ,MAAM;AAGpB,eAAW,CAAC,MAAM,KAAK,KAAK,OAAO,QAAQ,MAAM,KAAK,GAAG;AACxD,UAAI,OAAO,MAAM,IAAI,GAAG;AACvB,eAAO,MAAM,IAAI,EAAG,QAAQ,MAAM;AAClC,YAAI,MAAM,MAAM;AACf,iBAAO,MAAM,IAAI,EAAG,OAAO,MAAM;AAAA,QAClC;AAAA,MACD;AAAA,IACD;AAGA,eAAW,QAAQ,MAAM,SAAS;AACjC,aAAO,OAAO,MAAM,IAAI;AAAA,IACzB;AAGA,UAAM,QAAQ,CAAC,GAAG,OAAO,KAAK;AAC9B,eAAW,QAAQ,MAAM,cAAc;AACtC,YAAM,MAAM,MAAM,UAAU,CAAC,MAAM,EAAE,SAAS,KAAK,QAAQ,EAAE,OAAO,KAAK,EAAE;AAC3E,UAAI,QAAQ,GAAI,OAAM,OAAO,KAAK,CAAC;AAAA,IACpC;AACA,eAAW,QAAQ,MAAM,YAAY;AACpC,YAAM,KAAK,IAAI;AAAA,IAChB;AACA,IAAC,OAA8C,QAAQ;AAAA,EACxD;AAEA,SAAO;AACR;","names":[]}

package/dist/{chunk-CP6MNKAA.js → chunk-E7OH6ZAZ.js}

@@ -1,7 +1,11 @@
+import {
+  ResettableTimer
+} from "./chunk-WZ2Z2CRV.js";
 import {
   describeNode,
-  metaSnapshot
-} from "./chunk-O3PI7W45.js";
+  metaSnapshot,
+  resolveDescribeFields
+} from "./chunk-LR2CLSEF.js";
 import {
   COMPLETE,
   DATA,
@@ -43,7 +47,7 @@ import {
   propagatesToMeta,
   state,
   wallClockNs
-} from "./chunk-5X3LAO3B.js";
+} from "./chunk-QTZSBQGJ.js";
 
 // src/core/index.ts
 var core_exports = {};
@@ -59,6 +63,7 @@ __export(core_exports, {
   PAUSE: () => PAUSE,
   RESOLVED: () => RESOLVED,
   RESUME: () => RESUME,
+  ResettableTimer: () => ResettableTimer,
   TEARDOWN: () => TEARDOWN,
   accessHintForGuard: () => accessHintForGuard,
   advanceVersion: () => advanceVersion,
@@ -87,6 +92,7 @@ __export(core_exports, {
   policyFromRules: () => policyFromRules,
   producer: () => producer,
   propagatesToMeta: () => propagatesToMeta,
+  resolveDescribeFields: () => resolveDescribeFields,
   state: () => state,
   wallClockNs: () => wallClockNs
 });
@@ -94,4 +100,4 @@ __export(core_exports, {
 export {
   core_exports
 };
-//# sourceMappingURL=chunk-CP6MNKAA.js.map
+//# sourceMappingURL=chunk-E7OH6ZAZ.js.map

package/dist/{chunk-CP6MNKAA.js.map → chunk-E7OH6ZAZ.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/core/index.ts"],"sourcesContent":["/**\n * Core layer: message protocol, node primitive, lifecycle (Phase 0).\n */\nexport * from \"./actor.js\";\nexport * from \"./batch.js\";\nexport { monotonicNs, wallClockNs } from \"./clock.js\";\nexport * from \"./dynamic-node.js\";\nexport * from \"./guard.js\";\nexport * from \"./messages.js\";\nexport * from \"./meta.js\";\nexport {\n\ttype Node,\n\ttype NodeActions,\n\ttype NodeDescribeKind,\n\ttype NodeFn,\n\ttype NodeOptions,\n\ttype NodeSink,\n\ttype NodeStatus,\n\ttype NodeTransportOptions,\n\tnode,\n\ttype OnMessageHandler,\n\ttype SubscribeHints,\n} from \"./node.js\";\nexport * from \"./sugar.js\";\nexport {\n\tadvanceVersion,\n\tcreateVersioning,\n\tdefaultHash,\n\ttype HashFn,\n\tisV1,\n\ttype NodeVersionInfo,\n\ttype V0,\n\ttype V1,\n\ttype VersioningLevel,\n\ttype VersioningOptions,\n} from \"./versioning.js\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../src/core/index.ts"],"sourcesContent":["/**\n * Core layer: message protocol, node primitive, lifecycle (Phase 0).\n */\nexport * from \"./actor.js\";\nexport * from \"./batch.js\";\nexport { monotonicNs, wallClockNs } from \"./clock.js\";\nexport * from \"./dynamic-node.js\";\nexport * from \"./guard.js\";\nexport * from \"./messages.js\";\nexport * from \"./meta.js\";\nexport {\n\ttype Node,\n\ttype NodeActions,\n\ttype NodeDescribeKind,\n\ttype NodeFn,\n\ttype NodeOptions,\n\ttype NodeSink,\n\ttype NodeStatus,\n\ttype NodeTransportOptions,\n\tnode,\n\ttype OnMessageHandler,\n\ttype SubscribeHints,\n} from \"./node.js\";\nexport * from \"./sugar.js\";\nexport { ResettableTimer } from \"./timer.js\";\nexport {\n\tadvanceVersion,\n\tcreateVersioning,\n\tdefaultHash,\n\ttype HashFn,\n\tisV1,\n\ttype NodeVersionInfo,\n\ttype V0,\n\ttype V1,\n\ttype VersioningLevel,\n\ttype VersioningOptions,\n} from \"./versioning.js\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;","names":[]}

package/dist/chunk-LR2CLSEF.js

@@ -0,0 +1,106 @@
+import {
+  DynamicNodeImpl,
+  NodeImpl,
+  accessHintForGuard
+} from "./chunk-QTZSBQGJ.js";
+
+// src/core/meta.ts
+function resolveDescribeFields(detail, fields) {
+  if (fields != null && fields.length > 0) return new Set(fields);
+  switch (detail) {
+    case "standard":
+      return /* @__PURE__ */ new Set(["type", "status", "value", "deps", "meta", "v"]);
+    case "full":
+      return null;
+    // null = include everything
+    case "minimal":
+    default:
+      return /* @__PURE__ */ new Set(["type", "deps"]);
+  }
+}
+function inferDescribeType(n) {
+  if (n._describeKind != null) return n._describeKind;
+  if (!n._hasDeps) return n._fn != null ? "producer" : "state";
+  if (n._fn == null) return "derived";
+  if (n._manualEmitUsed) return "operator";
+  return "derived";
+}
+function metaSnapshot(node) {
+  const out = {};
+  for (const [key, child] of Object.entries(node.meta)) {
+    try {
+      out[key] = child.get();
+    } catch {
+    }
+  }
+  return out;
+}
+function describeNode(node, includeFields) {
+  const all = includeFields == null;
+  const metaKeys = !all && includeFields != null ? [...includeFields].filter((f) => f.startsWith("meta.")).map((f) => f.slice(5)) : null;
+  const wantsMeta = all || includeFields.has("meta") || metaKeys != null && metaKeys.length > 0;
+  let type = "state";
+  let deps = [];
+  if (node instanceof NodeImpl) {
+    type = inferDescribeType(node);
+    deps = node._deps.map((d) => d.name ?? "");
+  } else if (node instanceof DynamicNodeImpl) {
+    type = node._describeKind ?? "derived";
+    deps = [];
+  }
+  const out = { type, deps };
+  if (all || includeFields.has("status")) {
+    out.status = node.status;
+  }
+  const guard = node instanceof NodeImpl && node._guard || node instanceof DynamicNodeImpl && node._guard || void 0;
+  if (wantsMeta) {
+    const rawMeta = { ...metaSnapshot(node) };
+    if (guard != null && rawMeta.access === void 0) {
+      rawMeta.access = accessHintForGuard(guard);
+    }
+    if (metaKeys != null && metaKeys.length > 0 && !includeFields.has("meta")) {
+      const filtered = {};
+      for (const k of metaKeys) {
+        if (k in rawMeta) filtered[k] = rawMeta[k];
+      }
+      out.meta = filtered;
+    } else {
+      out.meta = rawMeta;
+    }
+  }
+  if (node.name != null) {
+    out.name = node.name;
+  }
+  if (all || includeFields.has("value")) {
+    try {
+      out.value = node.get();
+    } catch {
+    }
+  }
+  if ((all || includeFields.has("v")) && node.v != null) {
+    const vInfo = { id: node.v.id, version: node.v.version };
+    if ("cid" in node.v) {
+      vInfo.cid = node.v.cid;
+      vInfo.prev = node.v.prev;
+    }
+    out.v = vInfo;
+  }
+  if (all || includeFields.has("guard")) {
+    if (guard != null) {
+      out.guard = accessHintForGuard(guard);
+    }
+  }
+  if (all || includeFields.has("lastMutation")) {
+    if (node.lastMutation != null) {
+      out.lastMutation = node.lastMutation;
+    }
+  }
+  return out;
+}
+
+export {
+  resolveDescribeFields,
+  metaSnapshot,
+  describeNode
+};
+//# sourceMappingURL=chunk-LR2CLSEF.js.map

package/dist/chunk-LR2CLSEF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/meta.ts"],"sourcesContent":["import type { Actor } from \"./actor.js\";\nimport { DynamicNodeImpl } from \"./dynamic-node.js\";\nimport { accessHintForGuard } from \"./guard.js\";\nimport { type Node, NodeImpl } from \"./node.js\";\n\n/** JSON-shaped slice of a node for Phase 1 `Graph.describe()` (GRAPHREFLY-SPEC §3.6, Appendix B). */\nexport type DescribeNodeOutput = {\n\ttype: \"state\" | \"derived\" | \"producer\" | \"operator\" | \"effect\";\n\tstatus?: Node[\"status\"];\n\tdeps: string[];\n\tmeta?: Record<string, unknown>;\n\tname?: string;\n\tvalue?: unknown;\n\t/** Node versioning info (GRAPHREFLY-SPEC §7). Present only when versioning is enabled. */\n\tv?: { id: string; version: number; cid?: string; prev?: string | null };\n\t/** Guard info (full detail). */\n\tguard?: string;\n\t/** Last mutation attribution (full detail). */\n\tlastMutation?: Readonly<{ actor: Actor; timestamp_ns: number }>;\n};\n\n/**\n * Detail level for `describe()` progressive disclosure (Phase 3.3b).\n * - `\"minimal\"` — type + deps only (default). LLM-friendly.\n * - `\"standard\"` — type, status, value, deps, meta, versioning (`v`).\n * - `\"full\"` — standard + guard, lastMutation.\n */\nexport type DescribeDetail = \"minimal\" | \"standard\" | \"full\";\n\n/**\n * Valid field names for `describe({ fields: [...] })` (Phase 3.3b).\n * Dotted paths like `\"meta.label\"` select specific meta keys.\n */\nexport type DescribeField =\n\t| \"type\"\n\t| \"status\"\n\t| \"value\"\n\t| \"deps\"\n\t| \"meta\"\n\t| \"v\"\n\t| \"guard\"\n\t| \"lastMutation\"\n\t| `meta.${string}`;\n\n/** Resolve which fields to include based on detail level or explicit field list. */\nexport function resolveDescribeFields(\n\tdetail?: DescribeDetail,\n\tfields?: readonly DescribeField[],\n): Set<string> | null {\n\t// Explicit fields override detail level\n\tif (fields != null && fields.length > 0) return new Set(fields);\n\tswitch (detail) {\n\t\tcase \"standard\":\n\t\t\treturn new Set([\"type\", \"status\", \"value\", \"deps\", \"meta\", \"v\"]);\n\t\tcase \"full\":\n\t\t\treturn null; // null = include everything\n\t\tcase \"minimal\":\n\t\tdefault:\n\t\t\treturn new Set([\"type\", \"deps\"]);\n\t}\n}\n\nfunction inferDescribeType(n: NodeImpl): DescribeNodeOutput[\"type\"] {\n\tif (n._describeKind != null) return n._describeKind;\n\tif (!n._hasDeps) return n._fn != null ? \"producer\" : \"state\";\n\tif (n._fn == null) return \"derived\";\n\tif (n._manualEmitUsed) return \"operator\";\n\treturn \"derived\";\n}\n\n/**\n * Reads the current cached value of every companion meta field on a node,\n * suitable for merging into `describe()`-style JSON (GRAPHREFLY-SPEC §2.3, §3.6).\n *\n * @remarks\n * Values come from {@link Node.get}, which returns the **last settled** cache.\n * If a meta field is in `\"dirty\"` status (DIRTY received, DATA pending), the\n * snapshot contains the *previous* value — check `node.meta[key].status` when\n * freshness matters. Avoid calling mid-batch for the same reason.\n *\n * Meta nodes are **not** terminated when their parent receives COMPLETE or\n * ERROR — they remain writable so callers can record post-mortem metadata\n * (e.g. `meta.error`). They *are* torn down when the parent receives TEARDOWN.\n *\n * @param node - The node whose meta fields to snapshot.\n * @returns Plain object of `{ key: value }` pairs (empty if no meta defined).\n * Keys whose companion node's {@link Node.get} throws are omitted.\n *\n * @example\n * ```ts\n * import { core } from \"@graphrefly/graphrefly-ts\";\n *\n * const n = core.node({ initial: 0, meta: { tag: \"a\" } });\n * core.metaSnapshot(n); // { tag: \"a\" }\n * ```\n */\nexport function metaSnapshot(node: Node): Record<string, unknown> {\n\tconst out: Record<string, unknown> = {};\n\tfor (const [key, child] of Object.entries(node.meta)) {\n\t\ttry {\n\t\t\tout[key] = child.get();\n\t\t} catch {\n\t\t\t/* omit key — describe tooling still gets other fields */\n\t\t}\n\t}\n\treturn out;\n}\n\n/**\n * Builds a single-node slice of `Graph.describe()` JSON (structure + `meta` snapshot).\n * Parity with graphrefly-py `describe_node`.\n *\n * `type` is inferred from factory configuration, optional `describeKind` in node options,\n * and the last `manualEmitUsed` hint (operator vs derived). {@link effect} sets\n * `describeKind: \"effect\"`. Nodes not created by {@link node} fall back to `type: \"state\"` and empty `deps`.\n *\n * @param node - Any `Node` to introspect.\n * @returns `DescribeNodeOutput` suitable for merging into graph describe maps.\n *\n * @example\n * ```ts\n * import { describeNode, state } from \"@graphrefly/graphrefly-ts\";\n *\n * describeNode(state(0));\n * ```\n */\n/**\n * Builds a single-node slice for `Graph.describe()`.\n *\n * @param node - Node to introspect.\n * @param includeFields - Set of fields to include, or `null` for all. When omitted, all fields are included (legacy behavior).\n */\nexport function describeNode(node: Node, includeFields?: Set<string> | null): DescribeNodeOutput {\n\tconst all = includeFields == null; // null or undefined → include everything\n\n\t// Specific meta keys requested via dotted paths (e.g. \"meta.label\")\n\tconst metaKeys: string[] | null =\n\t\t!all && includeFields != null\n\t\t\t? [...includeFields].filter((f) => f.startsWith(\"meta.\")).map((f) => f.slice(5))\n\t\t\t: null;\n\tconst wantsMeta = all || includeFields!.has(\"meta\") || (metaKeys != null && metaKeys.length > 0);\n\n\tlet type: DescribeNodeOutput[\"type\"] = \"state\";\n\tlet deps: string[] = [];\n\n\tif (node instanceof NodeImpl) {\n\t\ttype = inferDescribeType(node);\n\t\tdeps = node._deps.map((d) => d.name ?? \"\");\n\t} else if (node instanceof DynamicNodeImpl) {\n\t\ttype = node._describeKind ?? \"derived\";\n\t\tdeps = [];\n\t}\n\n\tconst out: DescribeNodeOutput = { type, deps };\n\n\t// status\n\tif (all || includeFields!.has(\"status\")) {\n\t\tout.status = node.status;\n\t}\n\n\t// Resolve guard once — used by both meta.access hint and standalone guard field\n\tconst guard =\n\t\t(node instanceof NodeImpl && node._guard) ||\n\t\t(node instanceof DynamicNodeImpl && node._guard) ||\n\t\tundefined;\n\n\t// meta\n\tif (wantsMeta) {\n\t\tconst rawMeta: Record<string, unknown> = { ...metaSnapshot(node) };\n\t\tif (guard != null && rawMeta.access === undefined) {\n\t\t\trawMeta.access = accessHintForGuard(guard);\n\t\t}\n\n\t\tif (metaKeys != null && metaKeys.length > 0 && !includeFields!.has(\"meta\")) {\n\t\t\t// Only specific meta keys\n\t\t\tconst filtered: Record<string, unknown> = {};\n\t\t\tfor (const k of metaKeys) {\n\t\t\t\tif (k in rawMeta) filtered[k] = rawMeta[k];\n\t\t\t}\n\t\t\tout.meta = filtered;\n\t\t} else {\n\t\t\tout.meta = rawMeta;\n\t\t}\n\t}\n\n\t// name (always include when present — it's identity, not detail)\n\tif (node.name != null) {\n\t\tout.name = node.name;\n\t}\n\n\t// value\n\tif (all || includeFields!.has(\"value\")) {\n\t\ttry {\n\t\t\tout.value = node.get();\n\t\t} catch {\n\t\t\t/* omit value */\n\t\t}\n\t}\n\n\t// Versioning (GRAPHREFLY-SPEC §7)\n\tif ((all || includeFields!.has(\"v\")) && node.v != null) {\n\t\tconst vInfo: DescribeNodeOutput[\"v\"] = { id: node.v.id, version: node.v.version };\n\t\tif (\"cid\" in node.v) {\n\t\t\tvInfo!.cid = (node.v as { cid: string }).cid;\n\t\t\tvInfo!.prev = (node.v as { prev: string | null }).prev;\n\t\t}\n\t\tout.v = vInfo;\n\t}\n\n\t// Guard info (full detail)\n\tif (all || includeFields!.has(\"guard\")) {\n\t\tif (guard != null) {\n\t\t\tout.guard = accessHintForGuard(guard);\n\t\t}\n\t}\n\n\t// Last mutation attribution (full detail)\n\tif (all || includeFields!.has(\"lastMutation\")) {\n\t\tif (node.lastMutation != null) {\n\t\t\tout.lastMutation = node.lastMutation;\n\t\t}\n\t}\n\n\treturn out;\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-5X3LAO3B.js → chunk-QTZSBQGJ.js}

@@ -219,10 +219,14 @@ function partitionForBatch(messages) {
   }
   return { immediate, deferred, terminal };
 }
-function emitWithBatch(emit, messages, phase = 2) {
+function emitWithBatch(emit, messages, phase = 2, options) {
   if (messages.length === 0) {
     return;
   }
+  if (options?.strategy === "sequential") {
+    _emitSequential(emit, messages, phase);
+    return;
+  }
   const queue = phase === 3 ? pendingPhase3 : pendingPhase2;
   if (messages.length === 1) {
     const t = messages[0][0];
@@ -263,6 +267,29 @@ function emitWithBatch(emit, messages, phase = 2) {
     }
   }
 }
+function _emitSequential(emit, messages, phase = 2) {
+  const dataQueue = phase === 3 ? pendingPhase3 : pendingPhase2;
+  for (const msg of messages) {
+    const tier = messageTier(msg[0]);
+    if (tier === 2) {
+      if (isBatching()) {
+        const m = msg;
+        dataQueue.push(() => emit([m]));
+      } else {
+        emit([msg]);
+      }
+    } else if (tier >= 3) {
+      if (isBatching()) {
+        const m = msg;
+        pendingPhase3.push(() => emit([m]));
+      } else {
+        emit([msg]);
+      }
+    } else {
+      emit([msg]);
+    }
+  }
+}
 
 // src/core/clock.ts
 function monotonicNs() {
@@ -426,6 +453,7 @@ function isV1(info) {
 }
 
 // src/core/node.ts
+var NO_VALUE = /* @__PURE__ */ Symbol.for("graphrefly/NO_VALUE");
 function createIntBitSet() {
   let bits = 0;
   return {
@@ -555,10 +583,10 @@ var NodeImpl = class {
     this._hasDeps = deps.length > 0;
     this._autoComplete = opts.completeWhenDepsComplete ?? true;
     this._isSingleDep = deps.length === 1 && fn != null;
-    this._cached = opts.initial;
+    this._cached = "initial" in opts ? opts.initial : NO_VALUE;
     this._status = this._hasDeps ? "disconnected" : "settled";
     this._hashFn = opts.versioningHash ?? defaultHash;
-    this._versioning = opts.versioning != null ? createVersioning(opts.versioning, this._cached, {
+    this._versioning = opts.versioning != null ? createVersioning(opts.versioning, this._cached === NO_VALUE ? void 0 : this._cached, {
       id: opts.versioningId,
       hash: this._hashFn
     }) : void 0;
@@ -642,10 +670,14 @@ var NodeImpl = class {
   _applyVersioning(level, opts) {
     if (this._versioning != null) return;
     this._hashFn = opts?.hash ?? this._hashFn;
-    this._versioning = createVersioning(level, this._cached, {
-      id: opts?.id,
-      hash: this._hashFn
-    });
+    this._versioning = createVersioning(
+      level,
+      this._cached === NO_VALUE ? void 0 : this._cached,
+      {
+        id: opts?.id,
+        hash: this._hashFn
+      }
+    );
   }
   hasGuard() {
     return this._guard != null;
@@ -655,7 +687,7 @@ var NodeImpl = class {
     return this._guard(normalizeActor(actor), "observe");
   }
   get() {
-    return this._cached;
+    return this._cached === NO_VALUE ? void 0 : this._cached;
   }
   down(messages, options) {
     if (messages.length === 0) return;
@@ -712,6 +744,7 @@ var NodeImpl = class {
     }
     if (this._terminal && this._opts.resubscribable) {
       this._terminal = false;
+      this._cached = NO_VALUE;
       this._status = this._hasDeps ? "disconnected" : "settled";
       this._opts.onResubscribe?.();
     }
@@ -811,7 +844,7 @@ var NodeImpl = class {
         const cleanupFn = this._cleanup;
         this._cleanup = void 0;
         cleanupFn?.();
-        this._cached = void 0;
+        this._cached = NO_VALUE;
         this._lastDepValues = void 0;
       }
       this._status = statusAfterMessage(this._status, m);
@@ -820,7 +853,7 @@ var NodeImpl = class {
       }
       if (t === TEARDOWN) {
         if (this._opts.resetOnTeardown) {
-          this._cached = void 0;
+          this._cached = NO_VALUE;
         }
         const teardownCleanup = this._cleanup;
         this._cleanup = void 0;
@@ -851,7 +884,15 @@ var NodeImpl = class {
   }
   _emitAutoValue(value) {
     const wasDirty = this._status === "dirty";
-    const unchanged = this._equals(this._cached, value);
+    let unchanged;
+    try {
+      unchanged = this._cached !== NO_VALUE && this._equals(this._cached, value);
+    } catch (eqErr) {
+      const eqMsg = eqErr instanceof Error ? eqErr.message : String(eqErr);
+      const wrapped = new Error(`Node "${this.name}": equals threw: ${eqMsg}`, { cause: eqErr });
+      this._downInternal([[ERROR, wrapped]]);
+      return;
+    }
     if (unchanged) {
       this._downInternal(wasDirty ? [[RESOLVED]] : [[DIRTY], [RESOLVED]]);
       return;
@@ -898,7 +939,9 @@ var NodeImpl = class {
       if (out === void 0) return;
       this._emitAutoValue(out);
     } catch (err) {
-      this._downInternal([[ERROR, err]]);
+      const errMsg = err instanceof Error ? err.message : String(err);
+      const wrapped = new Error(`Node "${this.name}": fn threw: ${errMsg}`, { cause: err });
+      this._downInternal([[ERROR, wrapped]]);
     }
   }
   _onDepDirty(index) {
@@ -933,7 +976,11 @@ var NodeImpl = class {
         try {
           if (this._onMessage(msg, index, this._actions)) continue;
         } catch (err) {
-          this._downInternal([[ERROR, err]]);
+          const errMsg = err instanceof Error ? err.message : String(err);
+          const wrapped = new Error(`Node "${this.name}": onMessage threw: ${errMsg}`, {
+            cause: err
+          });
+          this._downInternal([[ERROR, wrapped]]);
           return;
         }
       }
@@ -1069,7 +1116,7 @@ var DynamicNodeImpl = class {
   _actions;
   _boundEmitToSinks;
   // Mutable state
-  _cached;
+  _cached = NO_VALUE;
   _status = "disconnected";
   _terminal = false;
   _connected = false;
@@ -1163,7 +1210,7 @@ var DynamicNodeImpl = class {
     return this._guard(normalizeActor(actor), "observe");
   }
   get() {
-    return this._cached;
+    return this._cached === NO_VALUE ? void 0 : this._cached;
   }
   down(messages, options) {
     if (messages.length === 0) return;
@@ -1221,6 +1268,7 @@ var DynamicNodeImpl = class {
     }
     if (this._terminal && this._resubscribable) {
       this._terminal = false;
+      this._cached = NO_VALUE;
       this._status = "disconnected";
       this._onResubscribe?.();
     }
@@ -1298,10 +1346,13 @@ var DynamicNodeImpl = class {
       const t = m[0];
       if (t === DATA) this._cached = m[1];
       if (t === INVALIDATE) {
-        this._cached = void 0;
+        this._cached = NO_VALUE;
+        this._status = "dirty";
       }
-      if (t === DATA || t === RESOLVED) {
+      if (t === DATA) {
         this._status = "settled";
+      } else if (t === RESOLVED) {
+        this._status = "resolved";
       } else if (t === DIRTY) {
         this._status = "dirty";
       } else if (t === COMPLETE) {
@@ -1312,7 +1363,7 @@ var DynamicNodeImpl = class {
         this._terminal = true;
       }
       if (t === TEARDOWN) {
-        if (this._resetOnTeardown) this._cached = void 0;
+        if (this._resetOnTeardown) this._cached = NO_VALUE;
         try {
           this._propagateToMeta(t);
         } finally {
@@ -1335,7 +1386,15 @@ var DynamicNodeImpl = class {
   }
   _emitAutoValue(value) {
     const wasDirty = this._status === "dirty";
-    const unchanged = this._equals(this._cached, value);
+    let unchanged;
+    try {
+      unchanged = this._cached !== NO_VALUE && this._equals(this._cached, value);
+    } catch (eqErr) {
+      const eqMsg = eqErr instanceof Error ? eqErr.message : String(eqErr);
+      const wrapped = new Error(`Node "${this.name}": equals threw: ${eqMsg}`, { cause: eqErr });
+      this._downInternal([[ERROR, wrapped]]);
+      return;
+    }
     if (unchanged) {
       this._downInternal(wasDirty ? [[RESOLVED]] : [[DIRTY], [RESOLVED]]);
       return;
@@ -1568,4 +1627,4 @@ export {
   effect,
   pipe
 };
-//# sourceMappingURL=chunk-5X3LAO3B.js.map
+//# sourceMappingURL=chunk-QTZSBQGJ.js.map