@graphrefly/graphrefly 0.15.0 → 0.17.0

package/dist/chunk-EBNKJULL.js

@@ -0,0 +1,231 @@
+import {
+  GRAPH_META_SEGMENT,
+  Graph,
+  reachable
+} from "./chunk-IHJHBADD.js";
+import {
+  NodeImpl,
+  __export
+} from "./chunk-BV3TPSBK.js";
+
+// src/graph/index.ts
+var graph_exports = {};
+__export(graph_exports, {
+  GRAPH_META_SEGMENT: () => GRAPH_META_SEGMENT,
+  Graph: () => Graph,
+  JsonCodec: () => JsonCodec,
+  createDagCborCodec: () => createDagCborCodec,
+  createDagCborZstdCodec: () => createDagCborZstdCodec,
+  graphProfile: () => graphProfile,
+  negotiateCodec: () => negotiateCodec,
+  reachable: () => reachable,
+  replayWAL: () => replayWAL,
+  sizeof: () => sizeof
+});
+
+// src/graph/codec.ts
+var JsonCodec = {
+  contentType: "application/json",
+  name: "json",
+  encode(snapshot) {
+    const json = JSON.stringify(snapshot);
+    return new TextEncoder().encode(json);
+  },
+  decode(buffer) {
+    const json = new TextDecoder().decode(buffer);
+    return JSON.parse(json);
+  }
+};
+function createDagCborCodec(dagCbor) {
+  return {
+    contentType: "application/dag-cbor",
+    name: "dag-cbor",
+    encode: (snapshot) => dagCbor.encode(snapshot),
+    decode: (buffer) => dagCbor.decode(buffer)
+  };
+}
+function createDagCborZstdCodec(dagCbor, zstd) {
+  return {
+    contentType: "application/dag-cbor+zstd",
+    name: "dag-cbor-zstd",
+    encode: (snapshot) => zstd.compressSync(dagCbor.encode(snapshot)),
+    decode: (buffer) => dagCbor.decode(zstd.decompressSync(buffer))
+  };
+}
+function negotiateCodec(localPreference, remoteContentTypes) {
+  const remoteSet = new Set(remoteContentTypes);
+  for (const codec of localPreference) {
+    if (remoteSet.has(codec.contentType)) return codec;
+  }
+  return null;
+}
+function replayWAL(entries) {
+  if (entries.length === 0) {
+    throw new Error("WAL is empty \u2014 need at least one full snapshot");
+  }
+  const first = entries[0];
+  if (first.type !== "full") {
+    throw new Error("WAL must start with a full snapshot");
+  }
+  const result = JSON.parse(JSON.stringify(first.snapshot));
+  for (let i = 1; i < entries.length; i++) {
+    const entry = entries[i];
+    if (entry.type === "full") {
+      Object.assign(result, JSON.parse(JSON.stringify(entry.snapshot)));
+      continue;
+    }
+    const delta = entry.delta;
+    for (const [name, patch] of Object.entries(delta.nodes)) {
+      if (result.nodes[name]) {
+        result.nodes[name].value = patch.value;
+        if (patch.meta) {
+          result.nodes[name].meta = patch.meta;
+        }
+      }
+    }
+    for (const name of delta.removed) {
+      delete result.nodes[name];
+    }
+    const edges = [...result.edges];
+    for (const edge of delta.edgesRemoved) {
+      const idx = edges.findIndex((e) => e.from === edge.from && e.to === edge.to);
+      if (idx !== -1) edges.splice(idx, 1);
+    }
+    for (const edge of delta.edgesAdded) {
+      edges.push(edge);
+    }
+    result.edges = edges;
+  }
+  return result;
+}
+
+// src/graph/sizeof.ts
+var OVERHEAD = {
+  object: 56,
+  array: 64,
+  string: 40,
+  // header; content added separately
+  number: 8,
+  boolean: 4,
+  null: 0,
+  undefined: 0,
+  symbol: 40,
+  bigint: 16,
+  function: 120,
+  map: 72,
+  set: 72,
+  mapEntry: 40,
+  setEntry: 24
+};
+function sizeof(value) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  return _sizeof(value, seen);
+}
+function _sizeof(value, seen) {
+  if (value == null) return 0;
+  const t = typeof value;
+  switch (t) {
+    case "number":
+      return OVERHEAD.number;
+    case "boolean":
+      return OVERHEAD.boolean;
+    case "string":
+      return OVERHEAD.string + value.length * 2;
+    // UTF-16
+    case "bigint":
+      return OVERHEAD.bigint;
+    case "symbol":
+      return OVERHEAD.symbol;
+    case "function":
+      if (seen.has(value)) return 0;
+      seen.add(value);
+      return OVERHEAD.function;
+    case "undefined":
+      return 0;
+  }
+  const obj = value;
+  if (seen.has(obj)) return 0;
+  seen.add(obj);
+  if (obj instanceof Map) {
+    let size2 = OVERHEAD.map;
+    for (const [k, v] of obj) {
+      size2 += OVERHEAD.mapEntry + _sizeof(k, seen) + _sizeof(v, seen);
+    }
+    return size2;
+  }
+  if (obj instanceof Set) {
+    let size2 = OVERHEAD.set;
+    for (const v of obj) {
+      size2 += OVERHEAD.setEntry + _sizeof(v, seen);
+    }
+    return size2;
+  }
+  if (Array.isArray(obj)) {
+    let size2 = OVERHEAD.array + obj.length * 8;
+    for (const item of obj) {
+      size2 += _sizeof(item, seen);
+    }
+    return size2;
+  }
+  if (obj instanceof ArrayBuffer) return obj.byteLength;
+  if (ArrayBuffer.isView(obj)) return obj.byteLength;
+  let size = OVERHEAD.object;
+  const keys = Object.keys(obj);
+  for (const key of keys) {
+    size += OVERHEAD.string + key.length * 2;
+    size += _sizeof(obj[key], seen);
+  }
+  return size;
+}
+
+// src/graph/profile.ts
+function graphProfile(graph, opts) {
+  const topN = opts?.topN ?? 10;
+  const desc = graph.describe({ detail: "standard" });
+  const targets = [];
+  if (typeof graph._collectObserveTargets === "function") {
+    graph._collectObserveTargets("", targets);
+  }
+  const pathToNode = /* @__PURE__ */ new Map();
+  for (const [p, n] of targets) {
+    pathToNode.set(p, n);
+  }
+  const profiles = [];
+  for (const [path, nodeDesc] of Object.entries(desc.nodes)) {
+    const nd = pathToNode.get(path);
+    const impl = nd instanceof NodeImpl ? nd : null;
+    const valueSizeBytes = impl ? sizeof(impl.get()) : 0;
+    const subscriberCount = impl ? impl._sinkCount : 0;
+    const depCount = nodeDesc.deps?.length ?? 0;
+    profiles.push({
+      path,
+      type: nodeDesc.type,
+      status: nodeDesc.status ?? "unknown",
+      valueSizeBytes,
+      subscriberCount,
+      depCount
+    });
+  }
+  const totalValueSizeBytes = profiles.reduce((sum, p) => sum + p.valueSizeBytes, 0);
+  const hotspots = [...profiles].sort((a, b) => b.valueSizeBytes - a.valueSizeBytes).slice(0, topN);
+  return {
+    nodeCount: profiles.length,
+    edgeCount: desc.edges.length,
+    subgraphCount: desc.subgraphs.length,
+    nodes: profiles,
+    totalValueSizeBytes,
+    hotspots
+  };
+}
+
+export {
+  JsonCodec,
+  createDagCborCodec,
+  createDagCborZstdCodec,
+  negotiateCodec,
+  replayWAL,
+  sizeof,
+  graphProfile,
+  graph_exports
+};
+//# sourceMappingURL=chunk-EBNKJULL.js.map

package/dist/chunk-EBNKJULL.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/graph/index.ts","../src/graph/codec.ts","../src/graph/sizeof.ts","../src/graph/profile.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\";\nexport {\n\ttype GraphProfileOptions,\n\ttype GraphProfileResult,\n\tgraphProfile,\n\ttype NodeProfile,\n} from \"./profile.js\";\nexport { sizeof } from \"./sizeof.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","/**\n * Approximate in-memory size estimation for arbitrary JS values.\n *\n * Uses a recursive walk with cycle detection. Not exact — provides a\n * reasonable approximation for profiling and hotspot detection.\n *\n * @module\n * @internal\n */\n\n/** Approximate per-type overhead in bytes (V8 heuristics). */\nconst OVERHEAD = {\n\tobject: 56,\n\tarray: 64,\n\tstring: 40, // header; content added separately\n\tnumber: 8,\n\tboolean: 4,\n\tnull: 0,\n\tundefined: 0,\n\tsymbol: 40,\n\tbigint: 16,\n\tfunction: 120,\n\tmap: 72,\n\tset: 72,\n\tmapEntry: 40,\n\tsetEntry: 24,\n} as const;\n\n/**\n * Estimate the approximate retained memory (in bytes) of a JS value.\n *\n * Handles primitives, plain objects, arrays, Maps, Sets, and nested\n * combinations. Uses a `WeakSet` for cycle detection — cyclic refs\n * are counted once.\n *\n * @param value - The value to measure.\n * @returns Approximate size in bytes.\n */\nexport function sizeof(value: unknown): number {\n\tconst seen = new WeakSet();\n\treturn _sizeof(value, seen);\n}\n\nfunction _sizeof(value: unknown, seen: WeakSet<WeakKey>): number {\n\tif (value == null) return 0;\n\n\tconst t = typeof value;\n\n\tswitch (t) {\n\t\tcase \"number\":\n\t\t\treturn OVERHEAD.number;\n\t\tcase \"boolean\":\n\t\t\treturn OVERHEAD.boolean;\n\t\tcase \"string\":\n\t\t\treturn OVERHEAD.string + (value as string).length * 2; // UTF-16\n\t\tcase \"bigint\":\n\t\t\treturn OVERHEAD.bigint;\n\t\tcase \"symbol\":\n\t\t\treturn OVERHEAD.symbol;\n\t\tcase \"function\":\n\t\t\tif (seen.has(value as object)) return 0;\n\t\t\tseen.add(value as object);\n\t\t\treturn OVERHEAD.function;\n\t\tcase \"undefined\":\n\t\t\treturn 0;\n\t}\n\n\t// Object types — cycle detection\n\tconst obj = value as object;\n\tif (seen.has(obj)) return 0;\n\tseen.add(obj);\n\n\tif (obj instanceof Map) {\n\t\tlet size = OVERHEAD.map;\n\t\tfor (const [k, v] of obj) {\n\t\t\tsize += OVERHEAD.mapEntry + _sizeof(k, seen) + _sizeof(v, seen);\n\t\t}\n\t\treturn size;\n\t}\n\n\tif (obj instanceof Set) {\n\t\tlet size = OVERHEAD.set;\n\t\tfor (const v of obj) {\n\t\t\tsize += OVERHEAD.setEntry + _sizeof(v, seen);\n\t\t}\n\t\treturn size;\n\t}\n\n\tif (Array.isArray(obj)) {\n\t\tlet size = OVERHEAD.array + obj.length * 8; // pointer slots\n\t\tfor (const item of obj) {\n\t\t\tsize += _sizeof(item, seen);\n\t\t}\n\t\treturn size;\n\t}\n\n\t// ArrayBuffer / TypedArray\n\tif (obj instanceof ArrayBuffer) return obj.byteLength;\n\tif (ArrayBuffer.isView(obj)) return (obj as { byteLength: number }).byteLength;\n\n\t// Plain object\n\tlet size = OVERHEAD.object;\n\tconst keys = Object.keys(obj);\n\tfor (const key of keys) {\n\t\tsize += OVERHEAD.string + key.length * 2; // key\n\t\tsize += _sizeof((obj as Record<string, unknown>)[key], seen);\n\t}\n\treturn size;\n}\n","/**\n * Graph profiling and inspection utilities.\n *\n * Provides per-node memory estimation, connectivity stats, and hotspot\n * detection. Non-invasive — reads from `describe()` and node internals\n * without modifying state.\n *\n * @module\n */\n\nimport { NodeImpl } from \"../core/node.js\";\nimport type { Graph, GraphDescribeOutput } from \"./graph.js\";\nimport { sizeof } from \"./sizeof.js\";\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** Per-node profile entry. */\nexport interface NodeProfile {\n\t/** Qualified path within the graph. */\n\tpath: string;\n\t/** Node type (state, derived, producer, effect). */\n\ttype: string;\n\t/** Node status (disconnected, dirty, settled, errored, completed). */\n\tstatus: string;\n\t/** Approximate retained bytes for the node's cached value. */\n\tvalueSizeBytes: number;\n\t/** Number of downstream subscribers (sinks). */\n\tsubscriberCount: number;\n\t/** Number of upstream dependencies. */\n\tdepCount: number;\n}\n\n/** Aggregate graph profile. */\nexport interface GraphProfileResult {\n\t/** Total node count. */\n\tnodeCount: number;\n\t/** Total edge count. */\n\tedgeCount: number;\n\t/** Subgraph count. */\n\tsubgraphCount: number;\n\t/** All node profiles. */\n\tnodes: NodeProfile[];\n\t/** Total approximate value memory across all nodes. */\n\ttotalValueSizeBytes: number;\n\t/** Nodes sorted by valueSizeBytes descending (top N). */\n\thotspots: NodeProfile[];\n}\n\n/** Options for {@link graphProfile}. */\nexport interface GraphProfileOptions {\n\t/** Limit hotspot list (default 10). */\n\ttopN?: number;\n\t/** Include subgraph nodes recursively (default true). */\n\trecursive?: boolean;\n}\n\n// ---------------------------------------------------------------------------\n// Implementation\n// ---------------------------------------------------------------------------\n\n/**\n * Profile a graph's memory and connectivity characteristics.\n *\n * Uses `describe({ detail: \"standard\" })` for node metadata and direct\n * `NodeImpl` access for subscriber counts and cached values.\n *\n * @param graph - The graph to profile.\n * @param opts - Optional configuration.\n * @returns Aggregate profile with per-node details and hotspots.\n */\nexport function graphProfile(graph: Graph, opts?: GraphProfileOptions): GraphProfileResult {\n\tconst topN = opts?.topN ?? 10;\n\n\tconst desc: GraphDescribeOutput = graph.describe({ detail: \"standard\" });\n\n\t// Build path→Node lookup via _collectObserveTargets (same as describe uses).\n\t// Runtime guard: if the internal method is missing (refactored), degrade\n\t// gracefully — profiles will show 0 for valueSizeBytes and subscriberCount.\n\tconst targets: [string, import(\"../core/node.js\").Node][] = [];\n\tif (typeof (graph as any)._collectObserveTargets === \"function\") {\n\t\t(graph as any)._collectObserveTargets(\"\", targets);\n\t}\n\tconst pathToNode = new Map<string, import(\"../core/node.js\").Node>();\n\tfor (const [p, n] of targets) {\n\t\tpathToNode.set(p, n);\n\t}\n\n\tconst profiles: NodeProfile[] = [];\n\n\tfor (const [path, nodeDesc] of Object.entries(desc.nodes)) {\n\t\tconst nd = pathToNode.get(path);\n\t\tconst impl = nd instanceof NodeImpl ? nd : null;\n\n\t\tconst valueSizeBytes = impl ? sizeof(impl.get()) : 0;\n\t\tconst subscriberCount = impl ? impl._sinkCount : 0;\n\t\tconst depCount = nodeDesc.deps?.length ?? 0;\n\n\t\tprofiles.push({\n\t\t\tpath,\n\t\t\ttype: nodeDesc.type,\n\t\t\tstatus: nodeDesc.status ?? \"unknown\",\n\t\t\tvalueSizeBytes,\n\t\t\tsubscriberCount,\n\t\t\tdepCount,\n\t\t});\n\t}\n\n\tconst totalValueSizeBytes = profiles.reduce((sum, p) => sum + p.valueSizeBytes, 0);\n\n\tconst hotspots = [...profiles].sort((a, b) => b.valueSizeBytes - a.valueSizeBytes).slice(0, topN);\n\n\treturn {\n\t\tnodeCount: profiles.length,\n\t\tedgeCount: desc.edges.length,\n\t\tsubgraphCount: desc.subgraphs.length,\n\t\tnodes: profiles,\n\t\ttotalValueSizeBytes,\n\t\thotspots,\n\t};\n}\n"],"mappings":";;;;;;;;;;;AAAA;AAAA;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;;;ACnSA,IAAM,WAAW;AAAA,EAChB,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,QAAQ;AAAA;AAAA,EACR,QAAQ;AAAA,EACR,SAAS;AAAA,EACT,MAAM;AAAA,EACN,WAAW;AAAA,EACX,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,UAAU;AAAA,EACV,KAAK;AAAA,EACL,KAAK;AAAA,EACL,UAAU;AAAA,EACV,UAAU;AACX;AAYO,SAAS,OAAO,OAAwB;AAC9C,QAAM,OAAO,oBAAI,QAAQ;AACzB,SAAO,QAAQ,OAAO,IAAI;AAC3B;AAEA,SAAS,QAAQ,OAAgB,MAAgC;AAChE,MAAI,SAAS,KAAM,QAAO;AAE1B,QAAM,IAAI,OAAO;AAEjB,UAAQ,GAAG;AAAA,IACV,KAAK;AACJ,aAAO,SAAS;AAAA,IACjB,KAAK;AACJ,aAAO,SAAS;AAAA,IACjB,KAAK;AACJ,aAAO,SAAS,SAAU,MAAiB,SAAS;AAAA;AAAA,IACrD,KAAK;AACJ,aAAO,SAAS;AAAA,IACjB,KAAK;AACJ,aAAO,SAAS;AAAA,IACjB,KAAK;AACJ,UAAI,KAAK,IAAI,KAAe,EAAG,QAAO;AACtC,WAAK,IAAI,KAAe;AACxB,aAAO,SAAS;AAAA,IACjB,KAAK;AACJ,aAAO;AAAA,EACT;AAGA,QAAM,MAAM;AACZ,MAAI,KAAK,IAAI,GAAG,EAAG,QAAO;AAC1B,OAAK,IAAI,GAAG;AAEZ,MAAI,eAAe,KAAK;AACvB,QAAIA,QAAO,SAAS;AACpB,eAAW,CAAC,GAAG,CAAC,KAAK,KAAK;AACzB,MAAAA,SAAQ,SAAS,WAAW,QAAQ,GAAG,IAAI,IAAI,QAAQ,GAAG,IAAI;AAAA,IAC/D;AACA,WAAOA;AAAA,EACR;AAEA,MAAI,eAAe,KAAK;AACvB,QAAIA,QAAO,SAAS;AACpB,eAAW,KAAK,KAAK;AACpB,MAAAA,SAAQ,SAAS,WAAW,QAAQ,GAAG,IAAI;AAAA,IAC5C;AACA,WAAOA;AAAA,EACR;AAEA,MAAI,MAAM,QAAQ,GAAG,GAAG;AACvB,QAAIA,QAAO,SAAS,QAAQ,IAAI,SAAS;AACzC,eAAW,QAAQ,KAAK;AACvB,MAAAA,SAAQ,QAAQ,MAAM,IAAI;AAAA,IAC3B;AACA,WAAOA;AAAA,EACR;AAGA,MAAI,eAAe,YAAa,QAAO,IAAI;AAC3C,MAAI,YAAY,OAAO,GAAG,EAAG,QAAQ,IAA+B;AAGpE,MAAI,OAAO,SAAS;AACpB,QAAM,OAAO,OAAO,KAAK,GAAG;AAC5B,aAAW,OAAO,MAAM;AACvB,YAAQ,SAAS,SAAS,IAAI,SAAS;AACvC,YAAQ,QAAS,IAAgC,GAAG,GAAG,IAAI;AAAA,EAC5D;AACA,SAAO;AACR;;;ACpCO,SAAS,aAAa,OAAc,MAAgD;AAC1F,QAAM,OAAO,MAAM,QAAQ;AAE3B,QAAM,OAA4B,MAAM,SAAS,EAAE,QAAQ,WAAW,CAAC;AAKvE,QAAM,UAAsD,CAAC;AAC7D,MAAI,OAAQ,MAAc,2BAA2B,YAAY;AAChE,IAAC,MAAc,uBAAuB,IAAI,OAAO;AAAA,EAClD;AACA,QAAM,aAAa,oBAAI,IAA4C;AACnE,aAAW,CAAC,GAAG,CAAC,KAAK,SAAS;AAC7B,eAAW,IAAI,GAAG,CAAC;AAAA,EACpB;AAEA,QAAM,WAA0B,CAAC;AAEjC,aAAW,CAAC,MAAM,QAAQ,KAAK,OAAO,QAAQ,KAAK,KAAK,GAAG;AAC1D,UAAM,KAAK,WAAW,IAAI,IAAI;AAC9B,UAAM,OAAO,cAAc,WAAW,KAAK;AAE3C,UAAM,iBAAiB,OAAO,OAAO,KAAK,IAAI,CAAC,IAAI;AACnD,UAAM,kBAAkB,OAAO,KAAK,aAAa;AACjD,UAAM,WAAW,SAAS,MAAM,UAAU;AAE1C,aAAS,KAAK;AAAA,MACb;AAAA,MACA,MAAM,SAAS;AAAA,MACf,QAAQ,SAAS,UAAU;AAAA,MAC3B;AAAA,MACA;AAAA,MACA;AAAA,IACD,CAAC;AAAA,EACF;AAEA,QAAM,sBAAsB,SAAS,OAAO,CAAC,KAAK,MAAM,MAAM,EAAE,gBAAgB,CAAC;AAEjF,QAAM,WAAW,CAAC,GAAG,QAAQ,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI;AAEhG,SAAO;AAAA,IACN,WAAW,SAAS;AAAA,IACpB,WAAW,KAAK,MAAM;AAAA,IACtB,eAAe,KAAK,UAAU;AAAA,IAC9B,OAAO;AAAA,IACP;AAAA,IACA;AAAA,EACD;AACD;","names":["size"]}

package/dist/{chunk-XQ4UMAU7.js → chunk-F2ULI3Q3.js}

@@ -2,7 +2,7 @@ import {
   DynamicNodeImpl,
   NodeImpl,
   accessHintForGuard
-} from "./chunk-H243FWYP.js";
+} from "./chunk-BV3TPSBK.js";
 
 // src/core/meta.ts
 function resolveDescribeFields(detail, fields) {
@@ -102,4 +102,4 @@ export {
   metaSnapshot,
   describeNode
 };
-//# sourceMappingURL=chunk-XQ4UMAU7.js.map
+//# sourceMappingURL=chunk-F2ULI3Q3.js.map

package/dist/{chunk-CRACCCJY.js → chunk-IHJHBADD.js}

@@ -1,7 +1,7 @@
 import {
   describeNode,
   resolveDescribeFields
-} from "./chunk-XQ4UMAU7.js";
+} from "./chunk-F2ULI3Q3.js";
 import {
   COMPLETE,
   DATA,
@@ -16,7 +16,7 @@ import {
   messageTier,
   monotonicNs,
   state
-} from "./chunk-H243FWYP.js";
+} from "./chunk-BV3TPSBK.js";
 
 // src/graph/graph.ts
 var PATH_SEP = "::";
@@ -289,6 +289,7 @@ var Graph = class _Graph {
   /** @internal — exposed for {@link teardownMountedGraph}. */
   _mounts = /* @__PURE__ */ new Map();
   _autoCheckpointDisposers = /* @__PURE__ */ new Set();
+  _disposers = /* @__PURE__ */ new Set();
   _defaultVersioningLevel;
   static registerFactory(pattern, factory) {
     if (!pattern) {
@@ -1424,10 +1425,33 @@ var Graph = class _Graph {
   //  Lifecycle & persistence (§3.7–§3.8)
   // ——————————————————————————————————————————————————————————————
   /**
-   * Sends `[[TEARDOWN]]` to all nodes, then clears registries on this graph and every
-   * mounted subgraph (§3.7). The instance is left empty and may be reused with {@link Graph.add}.
+   * Register a cleanup function to be called on {@link Graph.destroy}.
+   *
+   * Factories use this to attach teardown logic for internal nodes, keepalive
+   * subscriptions, or other resources that are not registered on the graph and
+   * would otherwise leak on repeated create/destroy cycles.
+   *
+   * Returns a removal function — call it to unregister the disposer early.
+   */
+  addDisposer(fn) {
+    this._disposers.add(fn);
+    return () => {
+      this._disposers.delete(fn);
+    };
+  }
+  /**
+   * Drains disposers (registered via {@link addDisposer}), then sends `[[TEARDOWN]]` to all
+   * nodes and clears registries on this graph and every mounted subgraph (§3.7).
+   * The instance is left empty and may be reused with {@link Graph.add}.
    */
   destroy() {
+    for (const dispose of [...this._disposers]) {
+      try {
+        dispose();
+      } catch {
+      }
+    }
+    this._disposers.clear();
     this.signal([[TEARDOWN]], { internal: true });
     for (const dispose of [...this._autoCheckpointDisposers]) {
       try {
@@ -1902,4 +1926,4 @@ export {
   Graph,
   reachable
 };
-//# sourceMappingURL=chunk-CRACCCJY.js.map
+//# sourceMappingURL=chunk-IHJHBADD.js.map