@graphrefly/graphrefly 0.20.0 → 0.22.0

package/dist/patterns/reactive-layout/index.d.cts

@@ -1,3 +1,5 @@
-export { B as BlockAdapters, C as CanvasMeasureAdapter, a as CanvasMeasureAdapterOptions, b as CanvasModule, c as CharPosition, d as CliMeasureAdapter, e as CliMeasureAdapterOptions, f as ContentBlock, I as ImageMeasurer, g as ImageSizeAdapter, L as LayoutLine, h as LineBreaksResult, j as MeasuredBlock, M as MeasurementAdapter, N as NodeCanvasMeasureAdapter, P as PositionedBlock, k as PrecomputedAdapter, l as PrecomputedAdapterOptions, m as PreparedSegment, R as ReactiveBlockLayoutBundle, n as ReactiveBlockLayoutOptions, o as ReactiveLayoutBundle, p as ReactiveLayoutOptions, S as SegmentBreakKind, q as SegmentMeasureStats, r as SvgBoundsAdapter, s as SvgMeasurer, t as analyzeAndMeasure, u as computeBlockFlow, v as computeCharPositions, w as computeLineBreaks, x as computeTotalHeight, y as measureBlock, z as measureBlocks, A as reactiveBlockLayout, D as reactiveLayout } from '../../index-VHA43cGP.cjs';
-import '../../meta-BnG7XAaE.cjs';
-import '../../graph-KsTe57nI.cjs';
+export { B as BlockAdapters, C as CanvasMeasureAdapter, a as CanvasMeasureAdapterOptions, b as CanvasModule, c as CharPosition, d as CliMeasureAdapter, e as CliMeasureAdapterOptions, f as ContentBlock, I as ImageMeasurer, g as ImageSizeAdapter, L as LayoutLine, h as LineBreaksResult, j as MeasuredBlock, M as MeasurementAdapter, N as NodeCanvasMeasureAdapter, P as PositionedBlock, k as PrecomputedAdapter, l as PrecomputedAdapterOptions, m as PreparedSegment, R as ReactiveBlockLayoutBundle, n as ReactiveBlockLayoutOptions, o as ReactiveLayoutBundle, p as ReactiveLayoutOptions, S as SegmentBreakKind, q as SegmentMeasureStats, r as SvgBoundsAdapter, s as SvgMeasurer, t as analyzeAndMeasure, u as computeBlockFlow, v as computeCharPositions, w as computeLineBreaks, x as computeTotalHeight, y as measureBlock, z as measureBlocks, A as reactiveBlockLayout, D as reactiveLayout } from '../../index-DLE1Sp-L.cjs';
+import '../../node-C5UD5MGq.cjs';
+import '../../graph-ab1yPwIB.cjs';
+import '../../meta--fr9sxRM.cjs';
+import '../../storage-Bew05Xy6.cjs';

package/dist/patterns/reactive-layout/index.d.ts

@@ -1,3 +1,5 @@
-export { B as BlockAdapters, C as CanvasMeasureAdapter, a as CanvasMeasureAdapterOptions, b as CanvasModule, c as CharPosition, d as CliMeasureAdapter, e as CliMeasureAdapterOptions, f as ContentBlock, I as ImageMeasurer, g as ImageSizeAdapter, L as LayoutLine, h as LineBreaksResult, j as MeasuredBlock, M as MeasurementAdapter, N as NodeCanvasMeasureAdapter, P as PositionedBlock, k as PrecomputedAdapter, l as PrecomputedAdapterOptions, m as PreparedSegment, R as ReactiveBlockLayoutBundle, n as ReactiveBlockLayoutOptions, o as ReactiveLayoutBundle, p as ReactiveLayoutOptions, S as SegmentBreakKind, q as SegmentMeasureStats, r as SvgBoundsAdapter, s as SvgMeasurer, t as analyzeAndMeasure, u as computeBlockFlow, v as computeCharPositions, w as computeLineBreaks, x as computeTotalHeight, y as measureBlock, z as measureBlocks, A as reactiveBlockLayout, D as reactiveLayout } from '../../index-8a605sg9.js';
-import '../../meta-BnG7XAaE.js';
-import '../../graph-mILUUqW8.js';
+export { B as BlockAdapters, C as CanvasMeasureAdapter, a as CanvasMeasureAdapterOptions, b as CanvasModule, c as CharPosition, d as CliMeasureAdapter, e as CliMeasureAdapterOptions, f as ContentBlock, I as ImageMeasurer, g as ImageSizeAdapter, L as LayoutLine, h as LineBreaksResult, j as MeasuredBlock, M as MeasurementAdapter, N as NodeCanvasMeasureAdapter, P as PositionedBlock, k as PrecomputedAdapter, l as PrecomputedAdapterOptions, m as PreparedSegment, R as ReactiveBlockLayoutBundle, n as ReactiveBlockLayoutOptions, o as ReactiveLayoutBundle, p as ReactiveLayoutOptions, S as SegmentBreakKind, q as SegmentMeasureStats, r as SvgBoundsAdapter, s as SvgMeasurer, t as analyzeAndMeasure, u as computeBlockFlow, v as computeCharPositions, w as computeLineBreaks, x as computeTotalHeight, y as measureBlock, z as measureBlocks, A as reactiveBlockLayout, D as reactiveLayout } from '../../index-BHm3Ba5q.js';
+import '../../node-C5UD5MGq.js';
+import '../../graph-DFr0diXB.js';
+import '../../meta-n3FoVWML.js';
+import '../../storage-C9fZfMfM.js';

package/dist/patterns/reactive-layout/index.js

@@ -14,10 +14,11 @@ import {
   measureBlocks,
   reactiveBlockLayout,
   reactiveLayout
-} from "../../chunk-IAPLC4NR.js";
-import "../../chunk-3N2Y6PCR.js";
-import "../../chunk-2L5J6RPM.js";
-import "../../chunk-XYL3GLB3.js";
+} from "../../chunk-EQUZ5NLD.js";
+import "../../chunk-NXC35KC5.js";
+import "../../chunk-TH6COGOP.js";
+import "../../chunk-7TAQJHQV.js";
+import "../../chunk-QA3RP5NH.js";
 export {
   CanvasMeasureAdapter,
   CliMeasureAdapter,

package/dist/storage-Bew05Xy6.d.cts

@@ -0,0 +1,182 @@
+import { N as Node } from './node-C5UD5MGq.cjs';
+
+/**
+ * Storage tier primitive — unified persistence surface (roadmap §3.1).
+ *
+ * A {@link StorageTier} is the single abstraction used by:
+ * - {@link Graph.attachStorage} — snapshot cascade with per-tier cadence
+ * - {@link Graph.fromStorage} — hot-boot from the first tier that hits
+ * - {@link cascadingCache} — keyed lookup cache with auto-promotion
+ *
+ * Factory functions cover the common backends: {@link memoryStorage},
+ * {@link dictStorage}, {@link fileStorage}, {@link sqliteStorage} (sync), and
+ * {@link indexedDbStorage} (async). {@link fromIDBRequest} /
+ * {@link fromIDBTransaction} wrap raw IndexedDB primitives as reactive sources
+ * — they belong here as the browser-runtime neighbors of `indexedDbStorage`.
+ */
+
+/**
+ * Single persistence primitive — supports sync and async backends alike via
+ * `void | Promise<void>` returns. `debounceMs` / `compactEvery` / `filter`
+ * are per-tier cadence controls honored by {@link Graph.attachStorage};
+ * {@link cascadingCache} ignores them (it has its own eviction policy).
+ */
+interface StorageTier {
+    /** Read a value. Returns `null` (or resolves to `null`) on miss. */
+    load(key: string): unknown | Promise<unknown>;
+    /** Write a record. Sync tiers return `void`; async tiers return `Promise<void>`. */
+    save(key: string, data: unknown): void | Promise<void>;
+    /** Delete a value. Optional — tiers without `clear` are append/overwrite-only. */
+    clear?(key: string): void | Promise<void>;
+    /**
+     * Debounce saves on this tier (ms). Hot tier: `0` (sync-through).
+     * Warm: `1000`. Cold: `60000`. Each tier holds its own last-save baseline,
+     * so cold flushes aren't penalized by hot flushes.
+     */
+    debounceMs?: number;
+    /**
+     * Every Nth record is a full snapshot; others are diffs against this
+     * tier's own baseline. Default `10`. Set `1` for always-full;
+     * `Number.POSITIVE_INFINITY` is unsafe — WAL replay needs periodic anchors.
+     */
+    compactEvery?: number;
+    /** Pre-save filter — return `false` to skip this record on this tier. */
+    filter?: (key: string, record: unknown) => boolean;
+}
+/** Handle returned by {@link Graph.attachStorage} — dispose to stop observing. */
+interface StorageHandle {
+    dispose(): void;
+}
+/**
+ * In-memory storage tier (process-local; useful for tests and hot tier).
+ *
+ * @returns Sync {@link StorageTier} with JSON-cloned isolation.
+ *
+ * @example
+ * ```ts
+ * import { memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * const hot = memoryStorage();
+ * graph.attachStorage([hot]);
+ * ```
+ *
+ * @category extra
+ */
+declare function memoryStorage(): StorageTier;
+/**
+ * Dict-backed storage tier — stores JSON-cloned values under caller keys in
+ * a caller-owned plain object. Useful for embedding in a parent state shape.
+ *
+ * @param storage - Caller-owned object used as the backing store.
+ * @returns Sync {@link StorageTier}.
+ *
+ * @example
+ * ```ts
+ * import { dictStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * const state: Record<string, unknown> = {};
+ * graph.attachStorage([dictStorage(state)]);
+ * ```
+ *
+ * @category extra
+ */
+declare function dictStorage(storage: Record<string, unknown>): StorageTier;
+/**
+ * Atomic JSON file storage tier (one file per key in a directory, temp + rename).
+ *
+ * Keys are sanitized to filesystem-safe names (`[^a-zA-Z0-9_-]` → `%<hex>`).
+ * `load` returns `null` for missing files, empty files, or invalid JSON.
+ *
+ * @param dir - Directory where per-key JSON files are written.
+ * @returns Sync {@link StorageTier}.
+ *
+ * @example
+ * ```ts
+ * import { fileStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * graph.attachStorage([memoryStorage(), fileStorage("./checkpoints")]);
+ * ```
+ *
+ * @category extra
+ */
+declare function fileStorage(dir: string): StorageTier;
+/**
+ * SQLite storage tier using Node.js `node:sqlite` ({@link DatabaseSync}).
+ *
+ * Returns a {@link StorageTier} extended with `close()` — the caller owns the
+ * connection and should close it when discarding the tier.
+ *
+ * **Runtime:** Requires Node 22.5+ with `node:sqlite` enabled.
+ *
+ * @param path - SQLite database file path.
+ * @returns Sync {@link StorageTier} with an idempotent `close()` method.
+ *
+ * @example
+ * ```ts
+ * import { sqliteStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * const cold = sqliteStorage("./graphs.sqlite");
+ * graph.attachStorage([memoryStorage(), cold]);
+ * // ... later, on shutdown:
+ * cold.close();
+ * ```
+ *
+ * @category extra
+ */
+declare function sqliteStorage(path: string): StorageTier & {
+    close(): void;
+};
+type IndexedDbStorageSpec = {
+    dbName: string;
+    storeName: string;
+    /** Object-store key under which snapshots are written. @default `"graphrefly_checkpoint"`. */
+    key?: string;
+    version?: number;
+};
+/**
+ * Wraps an `IDBRequest` as a one-shot reactive source.
+ *
+ * @param req - Request whose callbacks are converted to protocol messages.
+ * @returns `Node<T>` that emits `DATA` once on success then `COMPLETE`;
+ *   emits `ERROR` on failure.
+ *
+ * @category extra
+ */
+declare function fromIDBRequest<T>(req: IDBRequest<T>): Node<T>;
+/**
+ * Wraps an `IDBTransaction` terminal lifecycle as a one-shot reactive source.
+ *
+ * @param tx - Transaction to observe.
+ * @returns `Node<void>` that emits `DATA` (`undefined`) then `COMPLETE` on
+ *   success; emits `ERROR` on `error`/`abort`.
+ *
+ * @category extra
+ */
+declare function fromIDBTransaction(tx: IDBTransaction): Node<void>;
+/**
+ * IndexedDB-backed async storage tier (browser runtime).
+ *
+ * All three methods return `Promise`s — pairs naturally with a warm/cold
+ * cadence where async writes are debounced per tier via
+ * {@link Graph.attachStorage}. Writes use `readwrite` transactions; reads use
+ * `readonly`. Missing records resolve to `null`.
+ *
+ * @param spec - Database name, store name, optional `key` (default
+ *   `"graphrefly_checkpoint"`) and schema `version` (default `1`).
+ * @returns Async {@link StorageTier}.
+ *
+ * @example
+ * ```ts
+ * import { indexedDbStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * graph.attachStorage([
+ *   memoryStorage(),
+ *   indexedDbStorage({ dbName: "myApp", storeName: "checkpoints" }),
+ * ]);
+ * ```
+ *
+ * @category extra
+ */
+declare function indexedDbStorage(spec: IndexedDbStorageSpec): StorageTier;
+
+export { type IndexedDbStorageSpec as I, type StorageHandle as S, type StorageTier as a, fromIDBRequest as b, fromIDBTransaction as c, dictStorage as d, fileStorage as f, indexedDbStorage as i, memoryStorage as m, sqliteStorage as s };

package/dist/storage-C9fZfMfM.d.ts

@@ -0,0 +1,182 @@
+import { N as Node } from './node-C5UD5MGq.js';
+
+/**
+ * Storage tier primitive — unified persistence surface (roadmap §3.1).
+ *
+ * A {@link StorageTier} is the single abstraction used by:
+ * - {@link Graph.attachStorage} — snapshot cascade with per-tier cadence
+ * - {@link Graph.fromStorage} — hot-boot from the first tier that hits
+ * - {@link cascadingCache} — keyed lookup cache with auto-promotion
+ *
+ * Factory functions cover the common backends: {@link memoryStorage},
+ * {@link dictStorage}, {@link fileStorage}, {@link sqliteStorage} (sync), and
+ * {@link indexedDbStorage} (async). {@link fromIDBRequest} /
+ * {@link fromIDBTransaction} wrap raw IndexedDB primitives as reactive sources
+ * — they belong here as the browser-runtime neighbors of `indexedDbStorage`.
+ */
+
+/**
+ * Single persistence primitive — supports sync and async backends alike via
+ * `void | Promise<void>` returns. `debounceMs` / `compactEvery` / `filter`
+ * are per-tier cadence controls honored by {@link Graph.attachStorage};
+ * {@link cascadingCache} ignores them (it has its own eviction policy).
+ */
+interface StorageTier {
+    /** Read a value. Returns `null` (or resolves to `null`) on miss. */
+    load(key: string): unknown | Promise<unknown>;
+    /** Write a record. Sync tiers return `void`; async tiers return `Promise<void>`. */
+    save(key: string, data: unknown): void | Promise<void>;
+    /** Delete a value. Optional — tiers without `clear` are append/overwrite-only. */
+    clear?(key: string): void | Promise<void>;
+    /**
+     * Debounce saves on this tier (ms). Hot tier: `0` (sync-through).
+     * Warm: `1000`. Cold: `60000`. Each tier holds its own last-save baseline,
+     * so cold flushes aren't penalized by hot flushes.
+     */
+    debounceMs?: number;
+    /**
+     * Every Nth record is a full snapshot; others are diffs against this
+     * tier's own baseline. Default `10`. Set `1` for always-full;
+     * `Number.POSITIVE_INFINITY` is unsafe — WAL replay needs periodic anchors.
+     */
+    compactEvery?: number;
+    /** Pre-save filter — return `false` to skip this record on this tier. */
+    filter?: (key: string, record: unknown) => boolean;
+}
+/** Handle returned by {@link Graph.attachStorage} — dispose to stop observing. */
+interface StorageHandle {
+    dispose(): void;
+}
+/**
+ * In-memory storage tier (process-local; useful for tests and hot tier).
+ *
+ * @returns Sync {@link StorageTier} with JSON-cloned isolation.
+ *
+ * @example
+ * ```ts
+ * import { memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * const hot = memoryStorage();
+ * graph.attachStorage([hot]);
+ * ```
+ *
+ * @category extra
+ */
+declare function memoryStorage(): StorageTier;
+/**
+ * Dict-backed storage tier — stores JSON-cloned values under caller keys in
+ * a caller-owned plain object. Useful for embedding in a parent state shape.
+ *
+ * @param storage - Caller-owned object used as the backing store.
+ * @returns Sync {@link StorageTier}.
+ *
+ * @example
+ * ```ts
+ * import { dictStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * const state: Record<string, unknown> = {};
+ * graph.attachStorage([dictStorage(state)]);
+ * ```
+ *
+ * @category extra
+ */
+declare function dictStorage(storage: Record<string, unknown>): StorageTier;
+/**
+ * Atomic JSON file storage tier (one file per key in a directory, temp + rename).
+ *
+ * Keys are sanitized to filesystem-safe names (`[^a-zA-Z0-9_-]` → `%<hex>`).
+ * `load` returns `null` for missing files, empty files, or invalid JSON.
+ *
+ * @param dir - Directory where per-key JSON files are written.
+ * @returns Sync {@link StorageTier}.
+ *
+ * @example
+ * ```ts
+ * import { fileStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * graph.attachStorage([memoryStorage(), fileStorage("./checkpoints")]);
+ * ```
+ *
+ * @category extra
+ */
+declare function fileStorage(dir: string): StorageTier;
+/**
+ * SQLite storage tier using Node.js `node:sqlite` ({@link DatabaseSync}).
+ *
+ * Returns a {@link StorageTier} extended with `close()` — the caller owns the
+ * connection and should close it when discarding the tier.
+ *
+ * **Runtime:** Requires Node 22.5+ with `node:sqlite` enabled.
+ *
+ * @param path - SQLite database file path.
+ * @returns Sync {@link StorageTier} with an idempotent `close()` method.
+ *
+ * @example
+ * ```ts
+ * import { sqliteStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * const cold = sqliteStorage("./graphs.sqlite");
+ * graph.attachStorage([memoryStorage(), cold]);
+ * // ... later, on shutdown:
+ * cold.close();
+ * ```
+ *
+ * @category extra
+ */
+declare function sqliteStorage(path: string): StorageTier & {
+    close(): void;
+};
+type IndexedDbStorageSpec = {
+    dbName: string;
+    storeName: string;
+    /** Object-store key under which snapshots are written. @default `"graphrefly_checkpoint"`. */
+    key?: string;
+    version?: number;
+};
+/**
+ * Wraps an `IDBRequest` as a one-shot reactive source.
+ *
+ * @param req - Request whose callbacks are converted to protocol messages.
+ * @returns `Node<T>` that emits `DATA` once on success then `COMPLETE`;
+ *   emits `ERROR` on failure.
+ *
+ * @category extra
+ */
+declare function fromIDBRequest<T>(req: IDBRequest<T>): Node<T>;
+/**
+ * Wraps an `IDBTransaction` terminal lifecycle as a one-shot reactive source.
+ *
+ * @param tx - Transaction to observe.
+ * @returns `Node<void>` that emits `DATA` (`undefined`) then `COMPLETE` on
+ *   success; emits `ERROR` on `error`/`abort`.
+ *
+ * @category extra
+ */
+declare function fromIDBTransaction(tx: IDBTransaction): Node<void>;
+/**
+ * IndexedDB-backed async storage tier (browser runtime).
+ *
+ * All three methods return `Promise`s — pairs naturally with a warm/cold
+ * cadence where async writes are debounced per tier via
+ * {@link Graph.attachStorage}. Writes use `readwrite` transactions; reads use
+ * `readonly`. Missing records resolve to `null`.
+ *
+ * @param spec - Database name, store name, optional `key` (default
+ *   `"graphrefly_checkpoint"`) and schema `version` (default `1`).
+ * @returns Async {@link StorageTier}.
+ *
+ * @example
+ * ```ts
+ * import { indexedDbStorage, memoryStorage } from "@graphrefly/graphrefly-ts";
+ *
+ * graph.attachStorage([
+ *   memoryStorage(),
+ *   indexedDbStorage({ dbName: "myApp", storeName: "checkpoints" }),
+ * ]);
+ * ```
+ *
+ * @category extra
+ */
+declare function indexedDbStorage(spec: IndexedDbStorageSpec): StorageTier;
+
+export { type IndexedDbStorageSpec as I, type StorageHandle as S, type StorageTier as a, fromIDBRequest as b, fromIDBTransaction as c, dictStorage as d, fileStorage as f, indexedDbStorage as i, memoryStorage as m, sqliteStorage as s };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@graphrefly/graphrefly",
-	"version": "0.20.0",
+	"version": "0.22.0",
 	"packageManager": "pnpm@10.33.0+sha512.10568bb4a6afb58c9eb3630da90cc9516417abebd3fabbe6739f0ae795728da1491e9db5a544c76ad8eb7570f5c4bb3d6c637b2cb41bfdcdb47fa823c8649319",
 	"description": "Reactive harness layer for agent workflows. Describe automations in plain language, trace every decision, enforce policies, persist checkpoints. Zero dependencies.",
 	"repository": {
@@ -258,6 +258,7 @@
 		"@types/react": "^19.2.14",
 		"@types/react-dom": "^19.2.3",
 		"jsdom": "^29.0.1",
+		"openai": "^6.34.0",
 		"react": "^19.2.4",
 		"react-dom": "^19.2.4",
 		"reflect-metadata": "^0.2.2",

package/dist/chunk-2L5J6RPM.js.map

@@ -1 +0,0 @@
-{"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 { NO_VALUE, 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/** True when the node has never received or been initialized with a value (cache holds SENTINEL). */\n\tsentinel?: boolean;\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\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 */\n/** @internal Used by {@link describeNode} — not part of the public API. */\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 */\n/** @internal Used by {@link Graph.describe} — not part of the public API. */\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 + sentinel indicator\n\tif (all || includeFields!.has(\"value\")) {\n\t\tconst isSentinel =\n\t\t\t(node instanceof NodeImpl && node._cached === NO_VALUE) ||\n\t\t\t(node instanceof DynamicNodeImpl && node._cached === NO_VALUE);\n\t\tif (isSentinel) {\n\t\t\tout.sentinel = true;\n\t\t}\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":[]}