@graphrefly/graphrefly 0.44.0 → 0.46.0

package/dist/chunk-WKSWLSCX.js

@@ -0,0 +1,207 @@
+import {
+  llmConsolidator,
+  llmExtractor,
+  memoryRetrieval,
+  memoryWithKG,
+  memoryWithTiers,
+  memoryWithVectors
+} from "./chunk-OO5BM6CJ.js";
+import {
+  distill
+} from "./chunk-A7KV5UK4.js";
+
+// src/presets/ai/agent-memory.ts
+import { DATA, node, placeholderArgs, RESOLVED } from "@graphrefly/pure-ts/core";
+import { fromAny, fromTimer, switchMap } from "@graphrefly/pure-ts/extra";
+import { Graph } from "@graphrefly/pure-ts/graph";
+var AgentMemoryGraph = class extends Graph {
+  distillBundle;
+  compact;
+  size;
+  /** Vector index bundle (null if not enabled). */
+  vectors;
+  /** Knowledge graph (null if not enabled). */
+  kg;
+  /** Memory tiers bundle (null if not configured). */
+  memoryTiers;
+  /**
+   * The mounted `MemoryWithTiersGraph` subgraph (null when `opts.tiers` was
+   * omitted). Surfaces the inner graph for `describe()` / `explain()` walks
+   * and for callers that need direct access to the tiers subgraph (e.g.
+   * to register additional disposers or attach storage). Companion to
+   * `memoryTiers`, which carries only the bundle's reactive surface (B5e).
+   */
+  tiers;
+  /**
+   * Reactive consumer API. Given a reactive `RetrievalQuery | null` source,
+   * returns a `Node` emitting the packed retrieval results. Composable with
+   * graph topology — subscribe it, chain it into `promptNode`, or switchMap
+   * over a user-input node.
+   *
+   * Each call mounts its own per-input subgraph at
+   * `retrieval::retrieve_${id}` (via `MemoryRetrievalGraph`); concurrent
+   * calls don't share state mirrors. One-shot consumers wrap with
+   * `awaitSettled(retrieveReactive(query))`.
+   *
+   * Null when no retrieval pipeline is configured.
+   *
+   * **QA F-9 (2026-04-30):** the prior `retrieval` / `retrievalTrace`
+   * shared state-node mirrors have been dropped. Use `retrieveReactive`
+   * for per-call reactive results; one-shot trace consumers should
+   * subscribe to the projection's upstream `result` derived directly
+   * via `view.target.resolve("retrieval::retrieve_${id}::result")`.
+   */
+  retrieveReactive;
+  constructor(name, source, opts) {
+    super(name, opts.graph);
+    let rawExtractFn;
+    if (opts.extractFn) {
+      rawExtractFn = opts.extractFn;
+    } else if (opts.adapter && opts.extractPrompt) {
+      rawExtractFn = llmExtractor(opts.extractPrompt, { adapter: opts.adapter });
+    } else {
+      throw new Error("agentMemory: provide either extractFn or adapter + extractPrompt");
+    }
+    this.tagFactory("agentMemory", placeholderArgs(opts));
+    const extractFn = (rawNode, existingNode) => {
+      let latestExisting = existingNode.cache ?? /* @__PURE__ */ new Map();
+      const unsubExisting = existingNode.subscribe((msgs) => {
+        for (const m of msgs) {
+          if (m[0] === DATA) latestExisting = m[1];
+        }
+      });
+      this.addDisposer(unsubExisting);
+      return switchMap(rawNode, (raw) => {
+        if (raw == null) return { upsert: [] };
+        return rawExtractFn(raw, latestExisting);
+      });
+    };
+    let filteredSource = source;
+    if (opts.admissionFilter) {
+      const srcNode = fromAny(source);
+      const filter = opts.admissionFilter;
+      filteredSource = node(
+        [srcNode],
+        (batchData, actions, ctx) => {
+          const data = batchData.map(
+            (batch, i) => batch != null && batch.length > 0 ? batch.at(-1) : ctx.prevData[i]
+          );
+          const raw = data[0];
+          if (filter(raw)) {
+            actions.emit(raw);
+          } else {
+            actions.down([[RESOLVED]]);
+          }
+        },
+        { name: "admissionFilter", describeKind: "derived" }
+      );
+    }
+    let consolidateFn;
+    if (opts.consolidateFn) {
+      consolidateFn = opts.consolidateFn;
+    } else if (opts.adapter && opts.consolidatePrompt) {
+      consolidateFn = llmConsolidator(opts.consolidatePrompt, { adapter: opts.adapter });
+    }
+    let consolidateTrigger = opts.consolidateTrigger;
+    if (!consolidateTrigger && consolidateFn && opts.reflection?.enabled !== false) {
+      const interval = opts.reflection?.interval ?? 3e5;
+      consolidateTrigger = fromTimer(interval, { period: interval });
+    }
+    const distillOpts = {
+      score: opts.score,
+      cost: opts.cost,
+      budget: opts.budget ?? 2e3,
+      context: opts.context,
+      consolidate: consolidateFn,
+      consolidateTrigger
+    };
+    let distillBundle;
+    let memoryTiersBundle = null;
+    let tiersSubgraph = null;
+    if (opts.tiers) {
+      const tiersGraph = memoryWithTiers({
+        // User customization first; canonical agent-memory-level overrides
+        // last so they always win even if `MemoryTiersOptions` later adds
+        // any of the same keys.
+        ...opts.tiers,
+        name: "tiers",
+        source: filteredSource,
+        extractFn,
+        score: opts.score,
+        cost: opts.cost,
+        ...opts.budget !== void 0 ? { budget: opts.budget } : { budget: 2e3 },
+        ...opts.context !== void 0 ? { context: opts.context } : {},
+        ...consolidateFn !== void 0 ? { consolidate: consolidateFn } : {},
+        ...consolidateTrigger !== void 0 ? { consolidateTrigger } : {}
+      });
+      this.mount("tiers", tiersGraph);
+      distillBundle = tiersGraph.store;
+      memoryTiersBundle = tiersGraph.tiers;
+      tiersSubgraph = tiersGraph;
+    } else {
+      distillBundle = distill(filteredSource, extractFn, distillOpts);
+      this.add(distillBundle.store.entries, { name: "store" });
+      this.add(distillBundle.compact, { name: "compact" });
+      this.add(distillBundle.size, { name: "size" });
+    }
+    let vectors = null;
+    if (opts.vectorDimensions && opts.vectorDimensions > 0 && opts.embedFn) {
+      const vectorsGraph = memoryWithVectors({
+        name: "vectors",
+        store: distillBundle,
+        dimension: opts.vectorDimensions,
+        embedFn: opts.embedFn
+      });
+      this.mount("vectors", vectorsGraph);
+      vectors = vectorsGraph.vectors;
+    }
+    let kg = null;
+    if (opts.enableKnowledgeGraph) {
+      const kgGraph = memoryWithKG({
+        name: "knowledge",
+        store: distillBundle,
+        kgName: `${name}-kg`,
+        mountPath: "knowledge-kg",
+        ...opts.entityFn !== void 0 ? { entityFn: opts.entityFn } : {}
+      });
+      this.mount("knowledge", kgGraph);
+      kg = kgGraph.kg;
+    }
+    let retrieveReactive = null;
+    if (vectors || kg) {
+      const retrievalGraph = memoryRetrieval({
+        name: "retrieval",
+        store: distillBundle,
+        vectors,
+        kg,
+        score: opts.score,
+        cost: opts.cost,
+        ...opts.budget !== void 0 ? { budget: opts.budget } : {},
+        ...opts.retrieval?.topK !== void 0 ? { topK: opts.retrieval.topK } : {},
+        ...opts.retrieval?.graphDepth !== void 0 ? { graphDepth: opts.retrieval.graphDepth } : {},
+        ...opts.contextOf !== void 0 ? { contextOf: opts.contextOf } : {},
+        ...opts.contextWeight !== void 0 ? { contextWeight: opts.contextWeight } : {},
+        ...opts.context !== void 0 ? { context: opts.context } : {}
+      });
+      this.mount("retrieval", retrievalGraph);
+      retrieveReactive = retrievalGraph.retrieveReactive.bind(retrievalGraph);
+    }
+    this.distillBundle = distillBundle;
+    this.compact = distillBundle.compact;
+    this.size = distillBundle.size;
+    this.vectors = vectors;
+    this.kg = kg;
+    this.memoryTiers = memoryTiersBundle;
+    this.tiers = tiersSubgraph;
+    this.retrieveReactive = retrieveReactive;
+  }
+};
+function agentMemory(name, source, opts) {
+  return new AgentMemoryGraph(name, source, opts);
+}
+
+export {
+  AgentMemoryGraph,
+  agentMemory
+};
+//# sourceMappingURL=chunk-WKSWLSCX.js.map

package/dist/chunk-WKSWLSCX.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/presets/ai/agent-memory.ts"],"sourcesContent":["// ---------------------------------------------------------------------------\n// agentMemory — sugar over the memoryWith* composers (Unit 7 B).\n//\n// Thin wiring: distill() builds the core store (when no tiers configured);\n// optional capabilities delegate to the composer Graph subclasses in\n// `memory-composers.ts`. Each composer is a self-contained\n// `MemoryWithXxxGraph` that AgentMemoryGraph mounts on itself (Class B\n// audit, 2026-04-30) — teardown cascades via `Graph.destroy()`.\n//\n// **Phase 12.D (2026-04-30):** Migrated from the `Object.assign(graph, ...)`\n// factory pattern to `class extends Graph` (mirrors the\n// `MemoryWith*Graph` precedent). Required by Phase 13.G `agent(spec)` —\n// `AgentBundle.graph: AgentGraph<TIn, TOut>` consumers want `instanceof`\n// narrowing on agent-memory subgraphs.\n// ---------------------------------------------------------------------------\n\nimport { DATA, type Node, node, placeholderArgs, RESOLVED } from \"@graphrefly/pure-ts/core\";\nimport { fromAny, fromTimer, type NodeInput, switchMap } from \"@graphrefly/pure-ts/extra\";\nimport { Graph, type GraphOptions } from \"@graphrefly/pure-ts/graph\";\nimport {\n\ttype DistillBundle,\n\ttype DistillOptions,\n\tdistill,\n\ttype Extraction,\n} from \"../../base/composition/distill.js\";\nimport type { LLMAdapter } from \"../../utils/ai/adapters/core/types.js\";\nimport {\n\ttype MemoryWithTiersGraph,\n\tmemoryRetrieval,\n\tmemoryWithKG,\n\tmemoryWithTiers,\n\tmemoryWithVectors,\n} from \"../../utils/ai/memory/memory-composers.js\";\nimport type { RetrievalEntry, RetrievalQuery } from \"../../utils/ai/memory/retrieval.js\";\nimport type { MemoryTiersBundle, MemoryTiersOptions } from \"../../utils/ai/memory/tiers.js\";\nimport { llmConsolidator, llmExtractor } from \"../../utils/ai/prompts/prompt-call.js\";\nimport type { KnowledgeGraph, VectorIndexGraph } from \"../../utils/memory/index.js\";\n\nexport type AgentMemoryOptions<TMem = unknown> = {\n\tgraph?: GraphOptions;\n\t/** LLM adapter for extraction and consolidation. */\n\tadapter?: LLMAdapter;\n\t/** System prompt for the extractor LLM. */\n\textractPrompt?: string;\n\t/** Custom extractFn (overrides adapter + extractPrompt). */\n\textractFn?: (raw: unknown, existing: ReadonlyMap<string, TMem>) => NodeInput<Extraction<TMem>>;\n\t/** System prompt for the consolidation LLM. */\n\tconsolidatePrompt?: string;\n\t/** Custom consolidateFn (overrides adapter + consolidatePrompt). */\n\tconsolidateFn?: (entries: ReadonlyMap<string, TMem>) => NodeInput<Extraction<TMem>>;\n\t/** Reactive trigger for consolidation (caller supplies e.g. `fromTimer`). */\n\tconsolidateTrigger?: NodeInput<unknown>;\n\t/** Score function for budget packing (required). */\n\tscore: (mem: TMem, context: unknown) => number;\n\t/** Cost function for budget packing (required). */\n\tcost: (mem: TMem) => number;\n\t/** Token budget for compact view (default 2000). */\n\tbudget?: number;\n\t/** Context node for scoring. */\n\tcontext?: NodeInput<unknown>;\n\t/** Admission filter (default: admit all). */\n\tadmissionFilter?: (candidate: unknown) => boolean;\n\t/** Vector index dimensions (> 0 enables vector index for retrieval). */\n\tvectorDimensions?: number;\n\t/**\n\t * B12: optional accessor for an entry's hierarchical context breadcrumb\n\t * (e.g. `[\"projects\", \"auth\", \"tokens\"]`). When supplied alongside\n\t * `contextWeight > 0`, retrieval applies a score boost for entries whose\n\t * context shares a prefix with the query's `context`. Entries without\n\t * a breadcrumb are scored flatly.\n\t */\n\tcontextOf?: (mem: TMem) => readonly string[] | undefined;\n\t/**\n\t * B12: hierarchical context boost multiplier. Score is scaled by\n\t * `(1 + contextWeight * sharedDepth / queryDepth)` when both the query\n\t * and entry supply a `context`. Default: 0.\n\t */\n\tcontextWeight?: number;\n\n\t// --- In-factory composition (new) ---\n\n\t/** Extract embedding vector from a memory entry (enables vector index). */\n\tembedFn?: (mem: TMem) => readonly number[] | undefined;\n\t/** Enable knowledge graph for entity/relation tracking. */\n\tenableKnowledgeGraph?: boolean;\n\t/** Extract entities and relations from a memory entry. */\n\tentityFn?: (\n\t\tkey: string,\n\t\tmem: TMem,\n\t) =>\n\t\t| {\n\t\t\t\tentities?: Array<{ id: string; value: unknown }>;\n\t\t\t\trelations?: Array<{ from: string; to: string; relation: string; weight?: number }>;\n\t\t  }\n\t\t| undefined;\n\n\t/** 3-tier storage configuration. Omit to use single-tier (existing behavior). */\n\ttiers?: MemoryTiersOptions<TMem>;\n\n\t/** Retrieval pipeline configuration. Requires vector index or knowledge graph. */\n\tretrieval?: {\n\t\t/** Max candidates from vector search (default 20). */\n\t\ttopK?: number;\n\t\t/** KG expansion depth in hops (default 1). */\n\t\tgraphDepth?: number;\n\t};\n\n\t/** Periodic reflection/consolidation configuration. */\n\treflection?: {\n\t\t/** Interval in ms between consolidation runs (default 300_000 = 5 min). */\n\t\tinterval?: number;\n\t\t/** Enable/disable periodic reflection (default true when consolidateFn is available). */\n\t\tenabled?: boolean;\n\t};\n};\n\n/**\n * Pre-wired agentic memory graph. Sugar over `distill` plus the\n * `memoryWithVectors` / `memoryWithKG` / `memoryWithTiers` / `memoryRetrieval`\n * composers. Power users who want a subset of capabilities can call those\n * composers directly; this class bundles them into one ergonomic Graph subclass.\n *\n * Mounts:\n * - `tiers/*`     — present when `opts.tiers` configured (replaces the\n *                   default distill bundle).\n * - `vectors/*`   — present when `opts.vectorDimensions > 0 && opts.embedFn`.\n * - `knowledge/*` — present when `opts.enableKnowledgeGraph`.\n * - `retrieval/*` — present when vectors or kg configured.\n *\n * When `opts.tiers` is omitted, `store` / `compact` / `size` are added as\n * top-level nodes on this graph (visible in `describe()` / `explain()`).\n */\nexport class AgentMemoryGraph<TMem = unknown> extends Graph {\n\treadonly distillBundle: DistillBundle<TMem>;\n\treadonly compact: Node<Array<{ key: string; value: TMem; score: number }>>;\n\treadonly size: Node<number>;\n\t/** Vector index bundle (null if not enabled). */\n\treadonly vectors: VectorIndexGraph<TMem> | null;\n\t/** Knowledge graph (null if not enabled). */\n\treadonly kg: KnowledgeGraph<unknown, string> | null;\n\t/** Memory tiers bundle (null if not configured). */\n\treadonly memoryTiers: MemoryTiersBundle<TMem> | null;\n\t/**\n\t * The mounted `MemoryWithTiersGraph` subgraph (null when `opts.tiers` was\n\t * omitted). Surfaces the inner graph for `describe()` / `explain()` walks\n\t * and for callers that need direct access to the tiers subgraph (e.g.\n\t * to register additional disposers or attach storage). Companion to\n\t * `memoryTiers`, which carries only the bundle's reactive surface (B5e).\n\t */\n\treadonly tiers: MemoryWithTiersGraph<unknown, TMem> | null;\n\t/**\n\t * Reactive consumer API. Given a reactive `RetrievalQuery | null` source,\n\t * returns a `Node` emitting the packed retrieval results. Composable with\n\t * graph topology — subscribe it, chain it into `promptNode`, or switchMap\n\t * over a user-input node.\n\t *\n\t * Each call mounts its own per-input subgraph at\n\t * `retrieval::retrieve_${id}` (via `MemoryRetrievalGraph`); concurrent\n\t * calls don't share state mirrors. One-shot consumers wrap with\n\t * `awaitSettled(retrieveReactive(query))`.\n\t *\n\t * Null when no retrieval pipeline is configured.\n\t *\n\t * **QA F-9 (2026-04-30):** the prior `retrieval` / `retrievalTrace`\n\t * shared state-node mirrors have been dropped. Use `retrieveReactive`\n\t * for per-call reactive results; one-shot trace consumers should\n\t * subscribe to the projection's upstream `result` derived directly\n\t * via `view.target.resolve(\"retrieval::retrieve_${id}::result\")`.\n\t */\n\treadonly retrieveReactive:\n\t\t| ((queryInput: NodeInput<RetrievalQuery | null>) => Node<ReadonlyArray<RetrievalEntry<TMem>>>)\n\t\t| null;\n\n\tconstructor(name: string, source: NodeInput<unknown>, opts: AgentMemoryOptions<TMem>) {\n\t\tsuper(name, opts.graph);\n\n\t\t// --- Extract function resolution ---\n\t\t// /qa A3 (2026-04-30): validate BEFORE tagFactory so an invalid-opts\n\t\t// throw doesn't leave a tagged-but-empty Graph instance behind.\n\t\tlet rawExtractFn: (\n\t\t\traw: unknown,\n\t\t\texisting: ReadonlyMap<string, TMem>,\n\t\t) => NodeInput<Extraction<TMem>>;\n\t\tif (opts.extractFn) {\n\t\t\trawExtractFn = opts.extractFn;\n\t\t} else if (opts.adapter && opts.extractPrompt) {\n\t\t\trawExtractFn = llmExtractor<unknown, TMem>(opts.extractPrompt, { adapter: opts.adapter });\n\t\t} else {\n\t\t\tthrow new Error(\"agentMemory: provide either extractFn or adapter + extractPrompt\");\n\t\t}\n\n\t\t// Tier 1.5.3 Phase 2.5 (DG1=B): tag the Graph with its constructing\n\t\t// factory so `describe()` exposes provenance. Opts contain non-JSON\n\t\t// fields (`adapter`, `extractFn`, `embedFn`, `score`, `cost`, `evict`,\n\t\t// callbacks, etc.) so route through `placeholderArgs` (DG2=ii).\n\t\tthis.tagFactory(\"agentMemory\", placeholderArgs(opts as unknown as Record<string, unknown>));\n\t\t// Tier 1.5.4 — distill's `extractFn` is now reactive (called once with\n\t\t// nodes). Adapt the AgentMemoryOptions callback shape via switchMap +\n\t\t// closure-mirror for `existing` (COMPOSITION-GUIDE §40 recipe).\n\t\t// QA F9: register the closure-mirror's unsub with the host graph so\n\t\t// `graph.destroy()` reclaims it — was previously leaked.\n\t\t//\n\t\t// **Phase 16 attempt (2026-04-29) reverted.** Tried `withLatestFrom(\n\t\t// rawNode, existingNode) + switchMap`; this is the WRONG migration per\n\t\t// COMPOSITION-GUIDE §28. **Phase 10.5 (same-day partial-flag flip on\n\t\t// `withLatestFrom`)** removes the initial-pair drop, but this site stays\n\t\t// on closure-mirror form pending Phase 11 restricted signatures. See\n\t\t// `archive/docs/SESSION-graph-narrow-waist.md` § \"Status of existing\n\t\t// modifications\" + § \"Phase 10.5\".\n\t\tconst extractFn = (\n\t\t\trawNode: Node<unknown>,\n\t\t\texistingNode: Node<ReadonlyMap<string, TMem>>,\n\t\t): NodeInput<Extraction<TMem>> => {\n\t\t\tlet latestExisting: ReadonlyMap<string, TMem> =\n\t\t\t\t(existingNode.cache as ReadonlyMap<string, TMem> | undefined) ?? new Map();\n\t\t\tconst unsubExisting = existingNode.subscribe((msgs) => {\n\t\t\t\tfor (const m of msgs) {\n\t\t\t\t\tif (m[0] === DATA) latestExisting = m[1] as ReadonlyMap<string, TMem>;\n\t\t\t\t}\n\t\t\t});\n\t\t\tthis.addDisposer(unsubExisting);\n\t\t\treturn switchMap(rawNode, (raw) => {\n\t\t\t\tif (raw == null) return { upsert: [] };\n\t\t\t\treturn rawExtractFn(raw, latestExisting);\n\t\t\t});\n\t\t};\n\n\t\t// --- Admission filter ---\n\t\tlet filteredSource = source;\n\t\tif (opts.admissionFilter) {\n\t\t\tconst srcNode = fromAny(source);\n\t\t\tconst filter = opts.admissionFilter;\n\t\t\tfilteredSource = node(\n\t\t\t\t[srcNode],\n\t\t\t\t(batchData, actions, ctx) => {\n\t\t\t\t\tconst data = batchData.map((batch, i) =>\n\t\t\t\t\t\tbatch != null && batch.length > 0 ? batch.at(-1) : ctx.prevData[i],\n\t\t\t\t\t);\n\t\t\t\t\tconst raw = data[0];\n\t\t\t\t\tif (filter(raw)) {\n\t\t\t\t\t\tactions.emit(raw);\n\t\t\t\t\t} else {\n\t\t\t\t\t\t// EC1 (qa 2026-04-30): emitting `undefined` would violate spec §5.12\n\t\t\t\t\t\t// (undefined is the protocol SENTINEL — TopicGraph.publish even\n\t\t\t\t\t\t// throws on it). Downstream `batch.at(-1) : ctx.prevData[i]`\n\t\t\t\t\t\t// would also resolve `undefined` back to the prior accepted\n\t\t\t\t\t\t// value, leaking past-the-filter. Emit a tier-3 RESOLVED so the\n\t\t\t\t\t\t// wave settles cleanly without surfacing a stale DATA.\n\t\t\t\t\t\tactions.down([[RESOLVED]]);\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t\t{ name: \"admissionFilter\", describeKind: \"derived\" },\n\t\t\t);\n\t\t}\n\n\t\t// --- Consolidation ---\n\t\tlet consolidateFn:\n\t\t\t| ((entries: ReadonlyMap<string, TMem>) => NodeInput<Extraction<TMem>>)\n\t\t\t| undefined;\n\t\tif (opts.consolidateFn) {\n\t\t\tconsolidateFn = opts.consolidateFn;\n\t\t} else if (opts.adapter && opts.consolidatePrompt) {\n\t\t\tconsolidateFn = llmConsolidator<TMem>(opts.consolidatePrompt, { adapter: opts.adapter });\n\t\t}\n\n\t\t// --- Reflection: default consolidateTrigger from fromTimer ---\n\t\tlet consolidateTrigger = opts.consolidateTrigger;\n\t\tif (!consolidateTrigger && consolidateFn && opts.reflection?.enabled !== false) {\n\t\t\tconst interval = opts.reflection?.interval ?? 300_000;\n\t\t\tconsolidateTrigger = fromTimer(interval, { period: interval });\n\t\t}\n\n\t\t// --- Build distill bundle (the core) ---\n\t\t// Tier 4.1 B (2026-04-29): when tiers are configured, `memoryWithTiers`\n\t\t// is the construction site for the distill bundle so it can wire\n\t\t// `reactiveMap.retention` into the store at construction (no §7 cycle).\n\t\t// When tiers are NOT configured, agentMemory calls `distill` directly.\n\t\tconst distillOpts: DistillOptions<TMem> = {\n\t\t\tscore: opts.score,\n\t\t\tcost: opts.cost,\n\t\t\tbudget: opts.budget ?? 2000,\n\t\t\tcontext: opts.context,\n\t\t\tconsolidate: consolidateFn,\n\t\t\tconsolidateTrigger,\n\t\t};\n\n\t\tlet distillBundle: DistillBundle<TMem>;\n\t\tlet memoryTiersBundle: MemoryTiersBundle<TMem> | null = null;\n\t\tlet tiersSubgraph: MemoryWithTiersGraph<unknown, TMem> | null = null;\n\t\tif (opts.tiers) {\n\t\t\tconst tiersGraph = memoryWithTiers<unknown, TMem>({\n\t\t\t\t// User customization first; canonical agent-memory-level overrides\n\t\t\t\t// last so they always win even if `MemoryTiersOptions` later adds\n\t\t\t\t// any of the same keys.\n\t\t\t\t...opts.tiers,\n\t\t\t\tname: \"tiers\",\n\t\t\t\tsource: filteredSource,\n\t\t\t\textractFn,\n\t\t\t\tscore: opts.score,\n\t\t\t\tcost: opts.cost,\n\t\t\t\t...(opts.budget !== undefined ? { budget: opts.budget } : { budget: 2000 }),\n\t\t\t\t...(opts.context !== undefined ? { context: opts.context } : {}),\n\t\t\t\t...(consolidateFn !== undefined ? { consolidate: consolidateFn } : {}),\n\t\t\t\t...(consolidateTrigger !== undefined ? { consolidateTrigger } : {}),\n\t\t\t});\n\t\t\tthis.mount(\"tiers\", tiersGraph);\n\t\t\tdistillBundle = tiersGraph.store;\n\t\t\tmemoryTiersBundle = tiersGraph.tiers;\n\t\t\ttiersSubgraph = tiersGraph;\n\t\t} else {\n\t\t\tdistillBundle = distill<unknown, TMem>(filteredSource, extractFn, distillOpts);\n\t\t\tthis.add(distillBundle.store.entries, { name: \"store\" });\n\t\t\tthis.add(distillBundle.compact, { name: \"compact\" });\n\t\t\tthis.add(distillBundle.size, { name: \"size\" });\n\t\t}\n\n\t\t// --- Vector index (composer) ---\n\t\tlet vectors: VectorIndexGraph<TMem> | null = null;\n\t\tif (opts.vectorDimensions && opts.vectorDimensions > 0 && opts.embedFn) {\n\t\t\tconst vectorsGraph = memoryWithVectors<TMem>({\n\t\t\t\tname: \"vectors\",\n\t\t\t\tstore: distillBundle,\n\t\t\t\tdimension: opts.vectorDimensions,\n\t\t\t\tembedFn: opts.embedFn,\n\t\t\t});\n\t\t\tthis.mount(\"vectors\", vectorsGraph);\n\t\t\tvectors = vectorsGraph.vectors;\n\t\t}\n\n\t\t// --- Knowledge graph (composer) ---\n\t\tlet kg: KnowledgeGraph<unknown, string> | null = null;\n\t\tif (opts.enableKnowledgeGraph) {\n\t\t\tconst kgGraph = memoryWithKG<TMem>({\n\t\t\t\tname: \"knowledge\",\n\t\t\t\tstore: distillBundle,\n\t\t\t\tkgName: `${name}-kg`,\n\t\t\t\tmountPath: \"knowledge-kg\",\n\t\t\t\t...(opts.entityFn !== undefined ? { entityFn: opts.entityFn } : {}),\n\t\t\t});\n\t\t\tthis.mount(\"knowledge\", kgGraph);\n\t\t\tkg = kgGraph.kg;\n\t\t}\n\n\t\t// --- Retrieval pipeline (composer) ---\n\t\tlet retrieveReactive:\n\t\t\t| ((\n\t\t\t\t\tqueryInput: NodeInput<RetrievalQuery | null>,\n\t\t\t  ) => Node<ReadonlyArray<RetrievalEntry<TMem>>>)\n\t\t\t| null = null;\n\n\t\tif (vectors || kg) {\n\t\t\tconst retrievalGraph = memoryRetrieval<TMem>({\n\t\t\t\tname: \"retrieval\",\n\t\t\t\tstore: distillBundle,\n\t\t\t\tvectors,\n\t\t\t\tkg,\n\t\t\t\tscore: opts.score,\n\t\t\t\tcost: opts.cost,\n\t\t\t\t...(opts.budget !== undefined ? { budget: opts.budget } : {}),\n\t\t\t\t...(opts.retrieval?.topK !== undefined ? { topK: opts.retrieval.topK } : {}),\n\t\t\t\t...(opts.retrieval?.graphDepth !== undefined\n\t\t\t\t\t? { graphDepth: opts.retrieval.graphDepth }\n\t\t\t\t\t: {}),\n\t\t\t\t...(opts.contextOf !== undefined ? { contextOf: opts.contextOf } : {}),\n\t\t\t\t...(opts.contextWeight !== undefined ? { contextWeight: opts.contextWeight } : {}),\n\t\t\t\t...(opts.context !== undefined ? { context: opts.context } : {}),\n\t\t\t});\n\t\t\tthis.mount(\"retrieval\", retrievalGraph);\n\t\t\tretrieveReactive = retrievalGraph.retrieveReactive.bind(retrievalGraph);\n\t\t}\n\n\t\tthis.distillBundle = distillBundle;\n\t\tthis.compact = distillBundle.compact;\n\t\tthis.size = distillBundle.size;\n\t\tthis.vectors = vectors;\n\t\tthis.kg = kg;\n\t\tthis.memoryTiers = memoryTiersBundle;\n\t\tthis.tiers = tiersSubgraph;\n\t\tthis.retrieveReactive = retrieveReactive;\n\t}\n}\n\n/**\n * Pre-wired agentic memory graph. Sugar over `distill` plus the\n * `memoryWithVectors` / `memoryWithKG` / `memoryWithTiers` / `memoryRetrieval`\n * composers. Power users who want a subset of capabilities can call those\n * composers directly; this factory bundles them into one ergonomic call.\n *\n * Returns an {@link AgentMemoryGraph} subclass instance — `instanceof\n * AgentMemoryGraph` narrows in callers (e.g. Phase 13.G `agent(spec)`).\n */\nexport function agentMemory<TMem = unknown>(\n\tname: string,\n\tsource: NodeInput<unknown>,\n\topts: AgentMemoryOptions<TMem>,\n): AgentMemoryGraph<TMem> {\n\treturn new AgentMemoryGraph<TMem>(name, source, opts);\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-Y52CS6YA.js

@@ -0,0 +1,88 @@
+import {
+  msgVal,
+  operatorOpts
+} from "./chunk-TSBFTJKM.js";
+
+// src/base/resilience/status.ts
+import {
+  batch,
+  COMPLETE,
+  DATA,
+  DIRTY,
+  ERROR,
+  factoryTag,
+  node,
+  RESOLVED
+} from "@graphrefly/pure-ts/core";
+function withStatus(src, options) {
+  const initialStatus = options?.initialStatus ?? "pending";
+  const callerMeta = options?.meta;
+  const out = node(
+    [],
+    (_deps, a) => {
+      let currentStatus = initialStatus;
+      out.meta.status.down([[DATA, initialStatus]]);
+      out.meta.error.down([[DATA, null]]);
+      const unsub = src.subscribe((msgs) => {
+        for (const m of msgs) {
+          const t = m[0];
+          if (t === DIRTY) a.down([[DIRTY]]);
+          else if (t === DATA) {
+            if (currentStatus === "errored") {
+              batch(() => {
+                out.meta.error.down([[DATA, null]]);
+                out.meta.status.down([[DATA, "running"]]);
+                a.emit(m[1]);
+              });
+              currentStatus = "running";
+            } else if (currentStatus !== "running") {
+              batch(() => {
+                out.meta.status.down([[DATA, "running"]]);
+                a.emit(m[1]);
+              });
+              currentStatus = "running";
+            } else {
+              a.emit(m[1]);
+            }
+          } else if (t === RESOLVED) a.down([[RESOLVED]]);
+          else if (t === COMPLETE) {
+            out.meta.status.down([[DATA, "completed"]]);
+            currentStatus = "completed";
+            a.down([[COMPLETE]]);
+          } else if (t === ERROR) {
+            const err = msgVal(m);
+            batch(() => {
+              out.meta.error.down([[DATA, err]]);
+              out.meta.status.down([[DATA, "errored"]]);
+            });
+            currentStatus = "errored";
+            a.down([m]);
+          } else a.down([m]);
+        }
+      });
+      return unsub;
+    },
+    {
+      ...operatorOpts(),
+      meta: {
+        ...callerMeta ?? {},
+        status: initialStatus,
+        error: null,
+        ...factoryTag("withStatus", { initialStatus })
+      },
+      completeWhenDepsComplete: false,
+      resubscribable: true,
+      initial: src.cache
+    }
+  );
+  return {
+    node: out,
+    status: out.meta.status,
+    error: out.meta.error
+  };
+}
+
+export {
+  withStatus
+};
+//# sourceMappingURL=chunk-Y52CS6YA.js.map

package/dist/chunk-Y52CS6YA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/base/resilience/status.ts"],"sourcesContent":["/**\n * Status wrapper — surface lifecycle state alongside output.\n *\n * `withStatus` mirrors a source `Node<T>` and produces companion `status` /\n * `error` reactive nodes for UI and meta-snapshot consumers.\n */\n\nimport {\n\tbatch,\n\tCOMPLETE,\n\tDATA,\n\tDIRTY,\n\tERROR,\n\tfactoryTag,\n\ttype Node,\n\tnode,\n\tRESOLVED,\n} from \"@graphrefly/pure-ts/core\";\nimport { msgVal, operatorOpts } from \"./_internal.js\";\n\n/**\n * Central lifecycle vocabulary for resilience primitives + `processManager`.\n *\n * **DS-13.5.B follow-on (2026-05-01).** Widened from\n * `\"pending\" | \"running\" | \"completed\" | \"errored\"` to add `\"cancelled\"`\n * (replaces `processManager`'s prior `\"compensated\"` semantics) and\n * `\"paused\"` (carried by `<Primitive>State` lifecycle-shaped companions\n * on `retry` / `circuitBreaker` / `rateLimiter`).\n *\n * Resilience primitives use this enum as the literal vocabulary inside\n * lifecycle-shaped state nodes; `withStatus` (legacy) only emits the\n * original four (pre-widening) — the cancelled / paused values are added\n * for downstream consumers that need richer lifecycle reporting.\n */\nexport type StatusValue = \"pending\" | \"running\" | \"completed\" | \"errored\" | \"cancelled\" | \"paused\";\n\nexport type WithStatusBundle<T> = {\n\tnode: Node<T>;\n\tstatus: Node<StatusValue>;\n\terror: Node<unknown | null>;\n};\n\n/**\n * Wraps `src` with `status` and `error` {@link state} companions for UI or meta snapshots.\n *\n * @param src - Upstream node to mirror.\n * @param options - `initialStatus` defaults to `\"pending\"`.\n * @returns `{ node, status, error }` where `out` is the mirrored stream, `status` is a\n *   reactive `Node<StatusValue>` (`\"pending\" | \"running\" | \"completed\" | \"errored\"`),\n *   and `error` holds the last `ERROR` payload (cleared to `null` on the next `DATA`\n *   after `errored`).\n *\n * @remarks\n * **Lifecycle:** `pending` (no DATA yet) → `running` (on first DATA) → `completed`\n * (on COMPLETE) or `errored` (on ERROR). After `errored`, the next `DATA` clears\n * `error` and re-enters `running` inside a {@link batch} so subscribers see one\n * consistent transition (matches graphrefly-py).\n *\n * **Producer-pattern visibility:** `out` is built via `node([], fn, …)`, so `src`\n * appears as the source dependency in `describe()` traversal but the `status` /\n * `error` companions are mirrored via subscribe-callback effects — they appear\n * under `out.meta.status` / `out.meta.error` (and as `<name>::__meta__::status`\n * paths in `describe()`) rather than as separate top-level edges. Subscribers\n * to `out` see the throttled DATA stream; `status` / `error` companions may not\n * appear as edges in `describe()` if no consumer subscribes to them (per\n * COMPOSITION-GUIDE §1, push-on-subscribe semantics).\n *\n * **Per-subscribe lifecycle (DF8, 2026-04-29 doc lock).** When the wrapped\n * source is `resubscribable: true` and multiple consumers attach in\n * sequence, each new subscription cycle re-runs the producer fn AND\n * re-emits the initial `pending` + `null` companion DATAs. Downstream\n * subscribers to the `status` / `error` companions see thrash:\n * `pending → running → completed → pending → running …`. This is the\n * intended fresh-cycle semantic (each subscription cycle reports its own\n * lifecycle); consumers that need a \"stable\" status across cycles should\n * derive a snapshot via a separate `state()` mirror rather than depending\n * on the per-cycle reset.\n *\n * @example\n * ```ts\n * import { withStatus, state } from \"@graphrefly/graphrefly-ts\";\n *\n * const src = state<number>(0);\n * const { node, status, error } = withStatus(src);\n *\n * status.subscribe((msgs) => console.log(\"status:\", msgs));\n * src.down([[DATA, 42]]); // status → \"running\"\n * ```\n *\n * @category extra\n */\nexport function withStatus<T>(\n\tsrc: Node<T>,\n\toptions?: { initialStatus?: StatusValue; meta?: Record<string, unknown> },\n): WithStatusBundle<T> {\n\tconst initialStatus = options?.initialStatus ?? \"pending\";\n\tconst callerMeta = options?.meta;\n\n\tconst out = node<T>(\n\t\t[],\n\t\t(_deps, a) => {\n\t\t\tlet currentStatus: StatusValue = initialStatus;\n\t\t\tout.meta.status.down([[DATA, initialStatus]]);\n\t\t\tout.meta.error.down([[DATA, null]]);\n\n\t\t\tconst unsub = src.subscribe((msgs) => {\n\t\t\t\tfor (const m of msgs) {\n\t\t\t\t\tconst t = m[0];\n\t\t\t\t\tif (t === DIRTY) a.down([[DIRTY]]);\n\t\t\t\t\telse if (t === DATA) {\n\t\t\t\t\t\tif (currentStatus === \"errored\") {\n\t\t\t\t\t\t\tbatch(() => {\n\t\t\t\t\t\t\t\tout.meta.error.down([[DATA, null]]);\n\t\t\t\t\t\t\t\tout.meta.status.down([[DATA, \"running\"]]);\n\t\t\t\t\t\t\t\ta.emit(m[1] as T);\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\tcurrentStatus = \"running\";\n\t\t\t\t\t\t} else if (currentStatus !== \"running\") {\n\t\t\t\t\t\t\t// First DATA after `pending` (or another non-running state):\n\t\t\t\t\t\t\t// flip status to \"running\" alongside the DATA emit so external\n\t\t\t\t\t\t\t// observers see one coherent wave (no torn reads between the\n\t\t\t\t\t\t\t// status companion and the mirrored stream).\n\t\t\t\t\t\t\tbatch(() => {\n\t\t\t\t\t\t\t\tout.meta.status.down([[DATA, \"running\"]]);\n\t\t\t\t\t\t\t\ta.emit(m[1] as T);\n\t\t\t\t\t\t\t});\n\t\t\t\t\t\t\tcurrentStatus = \"running\";\n\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\t// A9 (QA fix 2026-05-01): already in \"running\" — skip the\n\t\t\t\t\t\t\t// redundant status emit that the previous code did on every\n\t\t\t\t\t\t\t// DATA. Saves a wave walk per DATA on hot streams (e.g. SSE\n\t\t\t\t\t\t\t// token streams through withStatus).\n\t\t\t\t\t\t\ta.emit(m[1] as T);\n\t\t\t\t\t\t}\n\t\t\t\t\t} else if (t === RESOLVED) a.down([[RESOLVED]]);\n\t\t\t\t\telse if (t === COMPLETE) {\n\t\t\t\t\t\tout.meta.status.down([[DATA, \"completed\"]]);\n\t\t\t\t\t\tcurrentStatus = \"completed\";\n\t\t\t\t\t\ta.down([[COMPLETE]]);\n\t\t\t\t\t} else if (t === ERROR) {\n\t\t\t\t\t\tconst err = msgVal(m);\n\t\t\t\t\t\tbatch(() => {\n\t\t\t\t\t\t\tout.meta.error.down([[DATA, err]]);\n\t\t\t\t\t\t\tout.meta.status.down([[DATA, \"errored\"]]);\n\t\t\t\t\t\t});\n\t\t\t\t\t\tcurrentStatus = \"errored\";\n\t\t\t\t\t\ta.down([m]);\n\t\t\t\t\t} else a.down([m]);\n\t\t\t\t}\n\t\t\t});\n\n\t\t\treturn unsub;\n\t\t},\n\t\t{\n\t\t\t...operatorOpts(),\n\t\t\tmeta: {\n\t\t\t\t...(callerMeta ?? {}),\n\t\t\t\tstatus: initialStatus,\n\t\t\t\terror: null,\n\t\t\t\t...factoryTag(\"withStatus\", { initialStatus }),\n\t\t\t},\n\t\t\tcompleteWhenDepsComplete: false,\n\t\t\tresubscribable: true,\n\t\t\tinitial: src.cache,\n\t\t},\n\t);\n\n\treturn {\n\t\tnode: out,\n\t\tstatus: out.meta.status as Node<StatusValue>,\n\t\terror: out.meta.error as Node<unknown | null>,\n\t};\n}\n"],"mappings":";;;;;;AAOA;AAAA,EACC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAEA;AAAA,EACA;AAAA,OACM;AA0EA,SAAS,WACf,KACA,SACsB;AACtB,QAAM,gBAAgB,SAAS,iBAAiB;AAChD,QAAM,aAAa,SAAS;AAE5B,QAAM,MAAM;AAAA,IACX,CAAC;AAAA,IACD,CAAC,OAAO,MAAM;AACb,UAAI,gBAA6B;AACjC,UAAI,KAAK,OAAO,KAAK,CAAC,CAAC,MAAM,aAAa,CAAC,CAAC;AAC5C,UAAI,KAAK,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC;AAElC,YAAM,QAAQ,IAAI,UAAU,CAAC,SAAS;AACrC,mBAAW,KAAK,MAAM;AACrB,gBAAM,IAAI,EAAE,CAAC;AACb,cAAI,MAAM,MAAO,GAAE,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC;AAAA,mBACxB,MAAM,MAAM;AACpB,gBAAI,kBAAkB,WAAW;AAChC,oBAAM,MAAM;AACX,oBAAI,KAAK,MAAM,KAAK,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC;AAClC,oBAAI,KAAK,OAAO,KAAK,CAAC,CAAC,MAAM,SAAS,CAAC,CAAC;AACxC,kBAAE,KAAK,EAAE,CAAC,CAAM;AAAA,cACjB,CAAC;AACD,8BAAgB;AAAA,YACjB,WAAW,kBAAkB,WAAW;AAKvC,oBAAM,MAAM;AACX,oBAAI,KAAK,OAAO,KAAK,CAAC,CAAC,MAAM,SAAS,CAAC,CAAC;AACxC,kBAAE,KAAK,EAAE,CAAC,CAAM;AAAA,cACjB,CAAC;AACD,8BAAgB;AAAA,YACjB,OAAO;AAKN,gBAAE,KAAK,EAAE,CAAC,CAAM;AAAA,YACjB;AAAA,UACD,WAAW,MAAM,SAAU,GAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC;AAAA,mBACrC,MAAM,UAAU;AACxB,gBAAI,KAAK,OAAO,KAAK,CAAC,CAAC,MAAM,WAAW,CAAC,CAAC;AAC1C,4BAAgB;AAChB,cAAE,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC;AAAA,UACpB,WAAW,MAAM,OAAO;AACvB,kBAAM,MAAM,OAAO,CAAC;AACpB,kBAAM,MAAM;AACX,kBAAI,KAAK,MAAM,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AACjC,kBAAI,KAAK,OAAO,KAAK,CAAC,CAAC,MAAM,SAAS,CAAC,CAAC;AAAA,YACzC,CAAC;AACD,4BAAgB;AAChB,cAAE,KAAK,CAAC,CAAC,CAAC;AAAA,UACX,MAAO,GAAE,KAAK,CAAC,CAAC,CAAC;AAAA,QAClB;AAAA,MACD,CAAC;AAED,aAAO;AAAA,IACR;AAAA,IACA;AAAA,MACC,GAAG,aAAa;AAAA,MAChB,MAAM;AAAA,QACL,GAAI,cAAc,CAAC;AAAA,QACnB,QAAQ;AAAA,QACR,OAAO;AAAA,QACP,GAAG,WAAW,cAAc,EAAE,cAAc,CAAC;AAAA,MAC9C;AAAA,MACA,0BAA0B;AAAA,MAC1B,gBAAgB;AAAA,MAChB,SAAS,IAAI;AAAA,IACd;AAAA,EACD;AAEA,SAAO;AAAA,IACN,MAAM;AAAA,IACN,QAAQ,IAAI,KAAK;AAAA,IACjB,OAAO,IAAI,KAAK;AAAA,EACjB;AACD;","names":[]}

package/dist/chunk-YCBUWK77.js

@@ -0,0 +1,92 @@
+import {
+  __export
+} from "./chunk-AZDQPQ3V.js";
+
+// src/compat/solid/index.ts
+var solid_exports = {};
+__export(solid_exports, {
+  useStore: () => useStore,
+  useSubscribe: () => useSubscribe,
+  useSubscribeRecord: () => useSubscribeRecord
+});
+import { DATA, DIRTY, RESOLVED } from "@graphrefly/pure-ts/core";
+import { createSignal, getOwner, onCleanup } from "solid-js";
+function useSubscribe(node) {
+  const [value, setValue] = createSignal(node.cache, { equals: false });
+  const unsub = node.subscribe(() => {
+    setValue(() => node.cache);
+  });
+  if (getOwner()) {
+    onCleanup(() => unsub());
+  } else if (typeof console !== "undefined") {
+    console.warn(
+      "[graphrefly-ts] useSubscribe called outside a Solid reactive owner \u2014 subscription will not be auto-disposed."
+    );
+  }
+  return value;
+}
+function useStore(node) {
+  const value = useSubscribe(node);
+  const setter = (v) => {
+    node.down([[DIRTY], [DATA, v]]);
+  };
+  return [value, setter];
+}
+function useSubscribeRecord(keysNode, factory) {
+  const [value, setValue] = createSignal({}, { equals: false });
+  let entrySubs = [];
+  const cleanupEntries = () => {
+    for (const unsub of entrySubs) unsub();
+    entrySubs = [];
+  };
+  const buildSnapshot = () => {
+    const snap = {};
+    for (const key of keysNode.cache ?? []) {
+      const nodes = factory(key);
+      const values = {};
+      for (const field of Object.keys(nodes)) {
+        values[field] = nodes[field].cache;
+      }
+      snap[key] = values;
+    }
+    return snap;
+  };
+  const sync = (nextKeys) => {
+    cleanupEntries();
+    for (const key of nextKeys) {
+      const nodes = factory(key);
+      for (const field of Object.keys(nodes)) {
+        const unsub = nodes[field].subscribe(() => {
+          setValue(() => buildSnapshot());
+        });
+        entrySubs.push(unsub);
+      }
+    }
+    setValue(() => buildSnapshot());
+  };
+  const keysUnsub = keysNode.subscribe((msgs) => {
+    if (msgs.some((m) => m[0] === DATA || m[0] === RESOLVED)) {
+      sync(keysNode.cache ?? []);
+    }
+  });
+  sync(keysNode.cache ?? []);
+  if (getOwner()) {
+    onCleanup(() => {
+      keysUnsub();
+      cleanupEntries();
+    });
+  } else if (typeof console !== "undefined") {
+    console.warn(
+      "[graphrefly-ts] useSubscribeRecord called outside a Solid reactive owner \u2014 subscription will not be auto-disposed."
+    );
+  }
+  return value;
+}
+
+export {
+  useSubscribe,
+  useStore,
+  useSubscribeRecord,
+  solid_exports
+};
+//# sourceMappingURL=chunk-YCBUWK77.js.map

package/dist/chunk-YCBUWK77.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/compat/solid/index.ts"],"sourcesContent":["// ---------------------------------------------------------------------------\n// Solid bindings — useSubscribe / useStore\n// ---------------------------------------------------------------------------\n// Bridges GraphReFly nodes into Solid reactivity via createSignal.\n// Works with any Node<T>, including companion nodes (node.meta.status).\n//\n// Usage:\n//   import { useSubscribe, useStore } from '@graphrefly/graphrefly-ts/compat/solid';\n//   // Optional peer install (only for this adapter): pnpm add solid-js\n//   const status = useSubscribe(wsStatusNode);     // Accessor<string | undefined>\n//   const [count, setCount] = useStore(countNode); // [Accessor<number | undefined>, Setter]\n// ---------------------------------------------------------------------------\n\nimport { DATA, DIRTY, type Messages, type Node, RESOLVED } from \"@graphrefly/pure-ts/core\";\nimport { createSignal, getOwner, onCleanup } from \"solid-js\";\n\n/** Solid accessor function — returns current value when called. */\nexport type Accessor<T> = () => T;\n\n/**\n * Subscribe to a `Node<T>` as a Solid signal. Auto-cleans up with the owning scope.\n * Subscription lifecycle is tied to Solid scope cleanup (not node terminal messages).\n */\nexport function useSubscribe<T>(node: Node<T>): Accessor<T | undefined | null> {\n\tconst [value, setValue] = createSignal(node.cache, { equals: false });\n\n\tconst unsub = node.subscribe(() => {\n\t\tsetValue(() => node.cache);\n\t});\n\n\tif (getOwner()) {\n\t\tonCleanup(() => unsub());\n\t} else if (typeof console !== \"undefined\") {\n\t\tconsole.warn(\n\t\t\t\"[graphrefly-ts] useSubscribe called outside a Solid reactive owner — subscription will not be auto-disposed.\",\n\t\t);\n\t}\n\n\treturn value;\n}\n\n/**\n * Bind a writable `Node<T>` as a Solid resource tuple `[accessor, setter]`.\n * Setter always forwards `[[DIRTY], [DATA, value]]`, including `value === undefined`.\n * Subscription lifecycle is tied to Solid scope cleanup (not node terminal messages).\n */\nexport function useStore<T>(node: Node<T>): [Accessor<T | undefined | null>, (v: T) => void] {\n\tconst value = useSubscribe(node);\n\tconst setter = (v: T) => {\n\t\tnode.down([[DIRTY], [DATA, v]]);\n\t};\n\treturn [value, setter];\n}\n\n/** Maps a key to an object of nodes. Used by `useSubscribeRecord`. */\nexport type NodeFactory<K, R extends Record<string, any>> = (key: K) => {\n\t[P in keyof R]: Node<R[P]>;\n};\n\n/**\n * Subscribe to a dynamic set of keyed node records as a Solid accessor.\n * Re-subscribes all per-key fields whenever `keys` changes.\n * Key re-sync is gated to settled batches (`messageTier >= 3`) to avoid DIRTY-phase churn.\n */\nexport function useSubscribeRecord<K extends string, R extends Record<string, any>>(\n\tkeysNode: Node<K[]>,\n\tfactory: NodeFactory<K, R>,\n): Accessor<Record<K, R>> {\n\tconst [value, setValue] = createSignal({} as Record<K, R>, { equals: false });\n\tlet entrySubs: Array<() => void> = [];\n\n\tconst cleanupEntries = () => {\n\t\tfor (const unsub of entrySubs) unsub();\n\t\tentrySubs = [];\n\t};\n\n\tconst buildSnapshot = (): Record<K, R> => {\n\t\tconst snap = {} as Record<K, R>;\n\t\tfor (const key of keysNode.cache ?? []) {\n\t\t\tconst nodes = factory(key);\n\t\t\tconst values = {} as R;\n\t\t\tfor (const field of Object.keys(nodes) as (keyof R)[]) {\n\t\t\t\tvalues[field] = nodes[field].cache as R[keyof R];\n\t\t\t}\n\t\t\tsnap[key] = values;\n\t\t}\n\t\treturn snap;\n\t};\n\n\tconst sync = (nextKeys: K[]) => {\n\t\tcleanupEntries();\n\t\tfor (const key of nextKeys) {\n\t\t\tconst nodes = factory(key);\n\t\t\tfor (const field of Object.keys(nodes) as (keyof R)[]) {\n\t\t\t\tconst unsub = nodes[field].subscribe(() => {\n\t\t\t\t\tsetValue(() => buildSnapshot());\n\t\t\t\t});\n\t\t\t\tentrySubs.push(unsub);\n\t\t\t}\n\t\t}\n\t\tsetValue(() => buildSnapshot());\n\t};\n\n\tconst keysUnsub = keysNode.subscribe((msgs: Messages) => {\n\t\tif (msgs.some((m) => m[0] === DATA || m[0] === RESOLVED)) {\n\t\t\tsync(keysNode.cache ?? []);\n\t\t}\n\t});\n\tsync(keysNode.cache ?? []);\n\n\tif (getOwner()) {\n\t\tonCleanup(() => {\n\t\t\tkeysUnsub();\n\t\t\tcleanupEntries();\n\t\t});\n\t} else if (typeof console !== \"undefined\") {\n\t\tconsole.warn(\n\t\t\t\"[graphrefly-ts] useSubscribeRecord called outside a Solid reactive owner — subscription will not be auto-disposed.\",\n\t\t);\n\t}\n\n\treturn value;\n}\n"],"mappings":";;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAaA,SAAS,MAAM,OAAiC,gBAAgB;AAChE,SAAS,cAAc,UAAU,iBAAiB;AAS3C,SAAS,aAAgB,MAA+C;AAC9E,QAAM,CAAC,OAAO,QAAQ,IAAI,aAAa,KAAK,OAAO,EAAE,QAAQ,MAAM,CAAC;AAEpE,QAAM,QAAQ,KAAK,UAAU,MAAM;AAClC,aAAS,MAAM,KAAK,KAAK;AAAA,EAC1B,CAAC;AAED,MAAI,SAAS,GAAG;AACf,cAAU,MAAM,MAAM,CAAC;AAAA,EACxB,WAAW,OAAO,YAAY,aAAa;AAC1C,YAAQ;AAAA,MACP;AAAA,IACD;AAAA,EACD;AAEA,SAAO;AACR;AAOO,SAAS,SAAY,MAAiE;AAC5F,QAAM,QAAQ,aAAa,IAAI;AAC/B,QAAM,SAAS,CAAC,MAAS;AACxB,SAAK,KAAK,CAAC,CAAC,KAAK,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;AAAA,EAC/B;AACA,SAAO,CAAC,OAAO,MAAM;AACtB;AAYO,SAAS,mBACf,UACA,SACyB;AACzB,QAAM,CAAC,OAAO,QAAQ,IAAI,aAAa,CAAC,GAAmB,EAAE,QAAQ,MAAM,CAAC;AAC5E,MAAI,YAA+B,CAAC;AAEpC,QAAM,iBAAiB,MAAM;AAC5B,eAAW,SAAS,UAAW,OAAM;AACrC,gBAAY,CAAC;AAAA,EACd;AAEA,QAAM,gBAAgB,MAAoB;AACzC,UAAM,OAAO,CAAC;AACd,eAAW,OAAO,SAAS,SAAS,CAAC,GAAG;AACvC,YAAM,QAAQ,QAAQ,GAAG;AACzB,YAAM,SAAS,CAAC;AAChB,iBAAW,SAAS,OAAO,KAAK,KAAK,GAAkB;AACtD,eAAO,KAAK,IAAI,MAAM,KAAK,EAAE;AAAA,MAC9B;AACA,WAAK,GAAG,IAAI;AAAA,IACb;AACA,WAAO;AAAA,EACR;AAEA,QAAM,OAAO,CAAC,aAAkB;AAC/B,mBAAe;AACf,eAAW,OAAO,UAAU;AAC3B,YAAM,QAAQ,QAAQ,GAAG;AACzB,iBAAW,SAAS,OAAO,KAAK,KAAK,GAAkB;AACtD,cAAM,QAAQ,MAAM,KAAK,EAAE,UAAU,MAAM;AAC1C,mBAAS,MAAM,cAAc,CAAC;AAAA,QAC/B,CAAC;AACD,kBAAU,KAAK,KAAK;AAAA,MACrB;AAAA,IACD;AACA,aAAS,MAAM,cAAc,CAAC;AAAA,EAC/B;AAEA,QAAM,YAAY,SAAS,UAAU,CAAC,SAAmB;AACxD,QAAI,KAAK,KAAK,CAAC,MAAM,EAAE,CAAC,MAAM,QAAQ,EAAE,CAAC,MAAM,QAAQ,GAAG;AACzD,WAAK,SAAS,SAAS,CAAC,CAAC;AAAA,IAC1B;AAAA,EACD,CAAC;AACD,OAAK,SAAS,SAAS,CAAC,CAAC;AAEzB,MAAI,SAAS,GAAG;AACf,cAAU,MAAM;AACf,gBAAU;AACV,qBAAe;AAAA,IAChB,CAAC;AAAA,EACF,WAAW,OAAO,YAAY,aAAa;AAC1C,YAAQ;AAAA,MACP;AAAA,IACD;AAAA,EACD;AAEA,SAAO;AACR;","names":[]}