@graphrefly/graphrefly 0.45.0 → 0.47.0

package/dist/chunk-4S53H2KR.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils/surface/errors.ts","../src/utils/surface/create.ts","../src/utils/surface/reduce.ts","../src/utils/surface/snapshot.ts"],"sourcesContent":["/**\n * Typed errors for the surface layer (§9.3-core).\n *\n * The surface layer is consumed by `@graphrefly/mcp-server` and\n * `@graphrefly/cli`. Both have native error channels (MCP's `isError` flag,\n * CLI's exit codes), so surface functions throw a {@link SurfaceError}\n * carrying a structured code + details payload that wrappers can map to\n * their native shape. No `Result` envelope — keep the callsite idiom\n * `try/catch` and let each wrapper surface the error its own way.\n *\n * @module\n */\n\n/** Structured error codes emitted by the surface layer. JSON-safe. */\nexport type SurfaceErrorCode =\n\t| \"invalid-spec\"\n\t| \"graph-not-found\"\n\t| \"graph-exists\"\n\t| \"snapshot-not-found\"\n\t| \"node-not-found\"\n\t| \"reduce-timeout\"\n\t| \"catalog-error\"\n\t| \"restore-failed\"\n\t| \"snapshot-failed\"\n\t| \"tier-no-list\"\n\t| \"compose-not-configured\"\n\t| \"compose-failed\"\n\t| \"internal-error\";\n\n/** JSON-safe shape surfaces should echo back through the wrapper. */\nexport interface SurfaceErrorPayload {\n\tcode: SurfaceErrorCode;\n\tmessage: string;\n\t/** Optional structured detail; must be JSON-safe. */\n\tdetails?: Readonly<Record<string, unknown>>;\n}\n\n/**\n * Thrown by surface layer functions on failure. `code` is the stable\n * machine-readable identifier; `details` carries structured context\n * (e.g. `validateSpec` errors, missing path name). Both fields round-trip\n * through `toJSON()` for wrappers that serialize errors over the wire.\n */\nexport class SurfaceError extends Error {\n\treadonly code: SurfaceErrorCode;\n\treadonly details?: Readonly<Record<string, unknown>>;\n\n\tconstructor(\n\t\tcode: SurfaceErrorCode,\n\t\tmessage: string,\n\t\tdetails?: Readonly<Record<string, unknown>>,\n\t) {\n\t\tsuper(message);\n\t\tthis.name = \"SurfaceError\";\n\t\tthis.code = code;\n\t\tif (details !== undefined) this.details = details;\n\t}\n\n\t/**\n\t * JSON-safe payload for wire serialization. Defensively validates\n\t * `details` — if it can't be round-tripped through `JSON.stringify`\n\t * (cyclic refs, `BigInt`, `Error` instance not pre-toJSON'd), the\n\t * payload falls back to `{code, message}` only rather than crashing\n\t * the MCP/CLI wrapper when it serializes this error onto the wire.\n\t */\n\ttoJSON(): SurfaceErrorPayload {\n\t\tconst out: SurfaceErrorPayload = { code: this.code, message: this.message };\n\t\tif (this.details !== undefined) {\n\t\t\tconst safe = safeDetails(this.details);\n\t\t\tif (safe !== undefined) out.details = safe;\n\t\t}\n\t\treturn out;\n\t}\n}\n\nfunction safeDetails(\n\tdetails: Readonly<Record<string, unknown>>,\n): Readonly<Record<string, unknown>> | undefined {\n\ttry {\n\t\t// Round-trip through JSON to strip non-serializable values (functions,\n\t\t// undefined) and reject cyclic structures with a thrown TypeError. The\n\t\t// round-trip result is the canonical wire shape.\n\t\treturn JSON.parse(JSON.stringify(details)) as Readonly<Record<string, unknown>>;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\n/** Wrap any thrown value as a SurfaceError. Idempotent on existing SurfaceError. */\nexport function asSurfaceError(\n\terr: unknown,\n\tfallbackCode: SurfaceErrorCode = \"internal-error\",\n): SurfaceError {\n\tif (err instanceof SurfaceError) return err;\n\tconst message = err instanceof Error ? err.message : String(err);\n\treturn new SurfaceError(fallbackCode, message);\n}\n","/**\n * Surface: create a graph from a {@link GraphSpec} (§9.3-core).\n *\n * Thin wrapper over {@link compileSpec} that converts the two failure modes\n * ({@link validateSpec} structural errors, and catalog-aware validation\n * errors) into typed {@link SurfaceError} throws. Consumers are MCP/CLI\n * wrappers, not end-user graph code — those should import `compileSpec`\n * directly.\n *\n * @module\n */\n\nimport type { Graph } from \"@graphrefly/pure-ts/graph\";\nimport type { CompileSpecOptions, GraphSpec } from \"../graphspec/index.js\";\nimport { compileSpec, validateSpec, validateSpecAgainstCatalog } from \"../graphspec/index.js\";\nimport { SurfaceError } from \"./errors.js\";\n\n/** Options for {@link createGraph}. Same shape as {@link CompileSpecOptions}. */\nexport type CreateGraphOptions = CompileSpecOptions;\n\n/**\n * Build a {@link Graph} from a parsed {@link GraphSpec} with surface-layer\n * error typing.\n *\n * @throws {SurfaceError} `invalid-spec` for structural errors;\n *   `catalog-error` when fn/source names or config don't match the catalog.\n */\nexport function createGraph(spec: GraphSpec, opts?: CreateGraphOptions): Graph {\n\tconst structural = validateSpec(spec);\n\tif (!structural.valid) {\n\t\tthrow new SurfaceError(\n\t\t\t\"invalid-spec\",\n\t\t\t`GraphSpec validation failed:\\n${structural.errors.join(\"\\n\")}`,\n\t\t\t{ errors: structural.errors },\n\t\t);\n\t}\n\tconst catalog = opts?.catalog ?? {};\n\tconst catalogValidation = validateSpecAgainstCatalog(spec, catalog);\n\tif (!catalogValidation.valid) {\n\t\tthrow new SurfaceError(\n\t\t\t\"catalog-error\",\n\t\t\t`Catalog validation failed:\\n${catalogValidation.errors.join(\"\\n\")}`,\n\t\t\t{ errors: catalogValidation.errors },\n\t\t);\n\t}\n\ttry {\n\t\treturn compileSpec(spec, opts);\n\t} catch (err) {\n\t\t// compileSpec re-throws validation errors plus may throw on missing\n\t\t// catalog entries for template-inner deferred nodes. Surface as\n\t\t// catalog-error; callers can inspect the wrapped message.\n\t\tconst message = err instanceof Error ? err.message : String(err);\n\t\tthrow new SurfaceError(\"catalog-error\", message);\n\t}\n}\n","/**\n * Surface: one-shot `input → pipeline → output` (§9.3-core).\n *\n * `runReduction` compiles a {@link GraphSpec}, pushes an input value to a\n * named state node, awaits the first post-push DATA emission on a named\n * output, then disposes the graph. Stateless per call — no graphId, no\n * registry.\n *\n * Named `runReduction` (not `reduce`) to avoid collision with the\n * reactive {@link reduce} operator in `extra/operators.ts`. The MCP tool\n * name (`graphrefly_reduce`) and CLI subcommand (`graphrefly reduce`) use\n * the short form; the library export carries the verb.\n *\n * The subscribe-before-push ordering is deliberate. `graph.set` propagates\n * synchronously for sync derived/operator chains; for async sources\n * (`fromPromise`, `fromAsyncIter`, LLM adapters) the first post-push DATA\n * arrives on a later tick. Subscribing before the push catches both, and\n * skipping the priming push-on-subscribe emission avoids resolving with the\n * stale pre-push cache (spec §2.2).\n *\n * @module\n */\n\nimport type { Node } from \"@graphrefly/pure-ts/core\";\nimport { COMPLETE, DATA, ERROR, RESOLVED } from \"@graphrefly/pure-ts/core\";\nimport type { GraphSpec, GraphSpecCatalog } from \"../graphspec/index.js\";\nimport { createGraph } from \"./create.js\";\nimport { SurfaceError } from \"./errors.js\";\n\n/** Options for {@link reduce}. */\nexport interface ReduceOptions {\n\t/** Fn/source catalog for {@link createGraph}. */\n\tcatalog?: GraphSpecCatalog;\n\t/** Path of the state node that receives the input. Default `\"input\"`. */\n\tinputPath?: string;\n\t/** Path of the node whose first post-push DATA is the result. Default `\"output\"`. */\n\toutputPath?: string;\n\t/** Hard deadline in milliseconds. Default `30_000`. */\n\ttimeoutMs?: number;\n}\n\nconst DEFAULT_TIMEOUT_MS = 30_000;\n\n/**\n * Run a spec as a one-shot reduction: `input → graph → output`.\n *\n * Resolves on the first `[DATA, v]` **or** `[RESOLVED]` emitted by\n * `outputPath` after the input push. The RESOLVED path handles spec\n * §1.3.3 equals-substitution (output recomputed to a value equal to its\n * cache, so the graph skips the DATA push) by returning `outputNode.cache`\n * — the caller always gets the settled value, never hangs on idempotent\n * inputs.\n *\n * @throws {SurfaceError} `invalid-spec` / `catalog-error` (propagated from\n *   {@link createGraph}), `node-not-found` when `inputPath`/`outputPath`\n *   can't be resolved, `reduce-timeout` when `timeoutMs` elapses without\n *   a post-push emission, or the ERROR payload from the graph re-thrown\n *   as `internal-error`.\n */\nexport async function runReduction(\n\tspec: GraphSpec,\n\tinput: unknown,\n\topts?: ReduceOptions,\n): Promise<unknown> {\n\tconst inputPath = opts?.inputPath ?? \"input\";\n\tconst outputPath = opts?.outputPath ?? \"output\";\n\tconst timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n\n\tconst graph = createGraph(spec, { catalog: opts?.catalog });\n\tlet outputNode: Node<unknown>;\n\ttry {\n\t\toutputNode = graph.resolve(outputPath);\n\t} catch {\n\t\tgraph.destroy();\n\t\tthrow new SurfaceError(\n\t\t\t\"node-not-found\",\n\t\t\t`reduce: output path \"${outputPath}\" is not registered`,\n\t\t\t{ path: outputPath },\n\t\t);\n\t}\n\t// Verify input path exists before we subscribe and push.\n\ttry {\n\t\tgraph.resolve(inputPath);\n\t} catch {\n\t\tgraph.destroy();\n\t\tthrow new SurfaceError(\n\t\t\t\"node-not-found\",\n\t\t\t`reduce: input path \"${inputPath}\" is not registered`,\n\t\t\t{ path: inputPath },\n\t\t);\n\t}\n\n\ttry {\n\t\treturn await new Promise<unknown>((resolve, reject) => {\n\t\t\tlet primed = false;\n\t\t\tlet settled = false;\n\t\t\tlet timer: ReturnType<typeof setTimeout> | undefined;\n\t\t\tlet unsub: (() => void) | undefined;\n\t\t\t// Sync-settle deferred-unsubscribe invariant (C24-4):\n\t\t\t// `outputNode.subscribe(cb)` may invoke `cb` synchronously during\n\t\t\t// the call (push-on-subscribe per spec §2.2). If `cb` reaches\n\t\t\t// `finish()` BEFORE `subscribe()` returns, `unsub` is still\n\t\t\t// `undefined` and we'd leak the subscription if we tried `unsub?.()`\n\t\t\t// immediately. The contract: `finish()` toggles `shouldUnsub = true`;\n\t\t\t// the post-subscribe block (after `unsub` is assigned) checks that\n\t\t\t// flag and tears down. Two-phase ensures exactly one unsubscribe\n\t\t\t// regardless of whether settlement happened during or after the\n\t\t\t// subscribe call.\n\t\t\tlet shouldUnsub = false;\n\n\t\t\tconst finish = (action: () => void): void => {\n\t\t\t\tif (settled) return;\n\t\t\t\tsettled = true;\n\t\t\t\tif (timer !== undefined) clearTimeout(timer);\n\t\t\t\tif (unsub !== undefined) {\n\t\t\t\t\tunsub();\n\t\t\t\t\tunsub = undefined;\n\t\t\t\t} else {\n\t\t\t\t\tshouldUnsub = true;\n\t\t\t\t}\n\t\t\t\taction();\n\t\t\t};\n\n\t\t\tunsub = outputNode.subscribe((msgs) => {\n\t\t\t\tfor (const m of msgs) {\n\t\t\t\t\tif (settled) return;\n\t\t\t\t\t// Skip push-on-subscribe emissions that land before we\n\t\t\t\t\t// trigger the input push — those carry pre-push state.\n\t\t\t\t\tif (!primed) continue;\n\t\t\t\t\tif (m[0] === DATA) {\n\t\t\t\t\t\tfinish(() => resolve(m[1]));\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\t\t\t\t\tif (m[0] === RESOLVED) {\n\t\t\t\t\t\t// Spec §1.3.3 equals-substitution: the output recomputed to\n\t\t\t\t\t\t// a value equal to its cached value, so the graph emits\n\t\t\t\t\t\t// RESOLVED instead of DATA. For a one-shot reduce the\n\t\t\t\t\t\t// caller wants the output value — read the cache **before**\n\t\t\t\t\t\t// finish() runs unsub (which can trigger lazy deactivation\n\t\t\t\t\t\t// and clear the cache per the RAM-cache rule).\n\t\t\t\t\t\tconst cached = outputNode.cache;\n\t\t\t\t\t\tfinish(() => resolve(cached));\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\t\t\t\t\tif (m[0] === ERROR) {\n\t\t\t\t\t\tconst payload = m[1];\n\t\t\t\t\t\tconst message = payload instanceof Error ? payload.message : String(payload);\n\t\t\t\t\t\tconst cause = payload instanceof Error ? payload : undefined;\n\t\t\t\t\t\tfinish(() =>\n\t\t\t\t\t\t\treject(\n\t\t\t\t\t\t\t\tnew SurfaceError(\n\t\t\t\t\t\t\t\t\t\"internal-error\",\n\t\t\t\t\t\t\t\t\t`reduce: output emitted ERROR: ${message}`,\n\t\t\t\t\t\t\t\t\tcause != null ? { cause } : undefined,\n\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t),\n\t\t\t\t\t\t);\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\t\t\t\t\tif (m[0] === COMPLETE) {\n\t\t\t\t\t\tfinish(() =>\n\t\t\t\t\t\t\treject(\n\t\t\t\t\t\t\t\tnew SurfaceError(\n\t\t\t\t\t\t\t\t\t\"internal-error\",\n\t\t\t\t\t\t\t\t\t`reduce: output COMPLETEd without a post-push DATA`,\n\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t),\n\t\t\t\t\t\t);\n\t\t\t\t\t\treturn;\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t});\n\t\t\tif (shouldUnsub) {\n\t\t\t\tunsub?.();\n\t\t\t\tunsub = undefined;\n\t\t\t}\n\n\t\t\tprimed = true;\n\t\t\ttry {\n\t\t\t\tgraph.set(inputPath, input);\n\t\t\t} catch (err) {\n\t\t\t\tconst message = err instanceof Error ? err.message : String(err);\n\t\t\t\tconst cause = err instanceof Error ? err : undefined;\n\t\t\t\tfinish(() =>\n\t\t\t\t\treject(\n\t\t\t\t\t\tnew SurfaceError(\n\t\t\t\t\t\t\t\"internal-error\",\n\t\t\t\t\t\t\t`reduce: failed to set input on \"${inputPath}\": ${message}`,\n\t\t\t\t\t\t\tcause != null ? { path: inputPath, cause } : { path: inputPath },\n\t\t\t\t\t\t),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\t// Synchronous wave may have already settled the promise via the\n\t\t\t// subscribe callback above; skip the timer in that case so we\n\t\t\t// don't leak an orphan setTimeout into the event loop (A1, E4).\n\t\t\tif (!settled && Number.isFinite(timeoutMs) && timeoutMs > 0) {\n\t\t\t\ttimer = setTimeout(() => {\n\t\t\t\t\tfinish(() =>\n\t\t\t\t\t\treject(\n\t\t\t\t\t\t\tnew SurfaceError(\n\t\t\t\t\t\t\t\t\"reduce-timeout\",\n\t\t\t\t\t\t\t\t`reduce: no output emitted within ${timeoutMs}ms`,\n\t\t\t\t\t\t\t\t{ timeoutMs, outputPath },\n\t\t\t\t\t\t\t),\n\t\t\t\t\t\t),\n\t\t\t\t\t);\n\t\t\t\t}, timeoutMs);\n\t\t\t\t// Belt-and-suspenders: if the caller drops the returned promise\n\t\t\t\t// we shouldn't keep the process alive.\n\t\t\t\ttimer.unref?.();\n\t\t\t}\n\t\t});\n\t} finally {\n\t\tgraph.destroy();\n\t}\n}\n","/**\n * Surface: snapshot save/restore/diff/list over {@link KvStorageTier} (§9.3-core).\n *\n * One-shot snapshot management for stateless callers (MCP tools, CLI\n * commands) layered on the existing multi-tier auto-checkpoint substrate.\n * A saved snapshot is a `mode: \"full\"` {@link GraphCheckpointRecord} with\n * `seq: 0` — byte-identical to the baseline anchor\n * {@link Graph.attachSnapshotStorage} writes on its first flush. An\n * auto-checkpointed graph can therefore be restored through this surface,\n * and a surface-saved snapshot can be picked up by `attachSnapshotStorage({\n * autoRestore: true })`.\n *\n * The wire envelope stays at {@link SNAPSHOT_WIRE_VERSION}; no new format.\n *\n * @module\n */\n\nimport { wallClockNs } from \"@graphrefly/pure-ts/core\";\nimport type { KvStorageTier } from \"@graphrefly/pure-ts/extra\";\nimport type {\n\tGraphCheckpointRecord,\n\tGraphDiffResult,\n\tGraphNodeFactory,\n\tGraphPersistSnapshot,\n} from \"@graphrefly/pure-ts/graph\";\nimport { Graph, SNAPSHOT_VERSION } from \"@graphrefly/pure-ts/graph\";\nimport { SurfaceError } from \"./errors.js\";\n\n/**\n * Current envelope version. Re-exported from `graph.ts` so the one-shot\n * surface path and `Graph.attachSnapshotStorage` write byte-identical\n * `format_version` fields — no silent wire drift.\n */\nexport const SNAPSHOT_WIRE_VERSION = SNAPSHOT_VERSION;\n\n/** Shape returned by {@link saveSnapshot}. */\nexport interface SaveSnapshotResult {\n\tsnapshotId: string;\n\ttimestamp_ns: number;\n}\n\n/** Options for {@link restoreSnapshot}. */\nexport interface RestoreSnapshotOptions {\n\t/** Passthrough to `Graph.fromSnapshot`. First matching pattern wins. */\n\tfactories?: Record<string, GraphNodeFactory>;\n}\n\n/**\n * Key prefix applied to every surface-written snapshot record. Isolates\n * surface-saved snapshots from other keys on the same tier (notably\n * `attachSnapshotStorage` baseline/WAL keys written under `graph.name`).\n */\nexport const SNAPSHOT_KEY_PREFIX = \"snapshot:\";\n\n/**\n * Reject caller-supplied ids that start with {@link SNAPSHOT_KEY_PREFIX}.\n *\n * Surface ids are keyed in the caller's external namespace; the `\"snapshot:\"`\n * prefix is an implementation detail of tier layout. Allowing `\"snapshot:foo\"`\n * through would produce surprising round-trips — `deleteSnapshot(\"foo\")` and\n * `deleteSnapshot(\"snapshot:foo\")` would both target the same tier key, while\n * `listSnapshots()` decodes to `\"foo\"` — so we enforce disjointness at the API\n * boundary (pre-1.0, no back-compat).\n */\nfunction assertExternalId(snapshotId: string): void {\n\tif (snapshotId.startsWith(SNAPSHOT_KEY_PREFIX)) {\n\t\tthrow new SurfaceError(\n\t\t\t\"snapshot-failed\",\n\t\t\t`snapshot id must not start with \"${SNAPSHOT_KEY_PREFIX}\" (reserved); got \"${snapshotId}\"`,\n\t\t\t{ snapshotId },\n\t\t);\n\t}\n}\n\nfunction encodeKey(snapshotId: string): string {\n\treturn `${SNAPSHOT_KEY_PREFIX}${snapshotId}`;\n}\n\nfunction decodeKey(key: string): string | undefined {\n\treturn key.startsWith(SNAPSHOT_KEY_PREFIX) ? key.slice(SNAPSHOT_KEY_PREFIX.length) : undefined;\n}\n\nfunction unwrapCheckpoint(raw: unknown, snapshotId: string): GraphPersistSnapshot {\n\tif (raw == null || typeof raw !== \"object\") {\n\t\tthrow new SurfaceError(\"snapshot-not-found\", `snapshot \"${snapshotId}\" not found in tier`, {\n\t\t\tsnapshotId,\n\t\t});\n\t}\n\t// Accept both wrapped (GraphCheckpointRecord) and bare\n\t// (GraphPersistSnapshot) payloads — attachSnapshotStorage writes wrapped, a user\n\t// may also hand us a bare one via dictKv for tests.\n\tconst record = raw as Record<string, unknown>;\n\tif (\"mode\" in record) {\n\t\tif (record.mode === \"full\" && \"snapshot\" in record) {\n\t\t\treturn record.snapshot as GraphPersistSnapshot;\n\t\t}\n\t\tif (record.mode === \"diff\") {\n\t\t\tthrow new SurfaceError(\n\t\t\t\t\"restore-failed\",\n\t\t\t\t`snapshot \"${snapshotId}\" is a diff record (legacy/non-paired tier write); under the Phase 14.6 paired-tier shape snapshot tiers hold only baselines. For WAL replay use Graph.restoreSnapshot({ mode: \"diff\", source: { tier, walTier } }).`,\n\t\t\t\t{ snapshotId, mode: \"diff\" },\n\t\t\t);\n\t\t}\n\t\tthrow new SurfaceError(\n\t\t\t\"restore-failed\",\n\t\t\t`snapshot \"${snapshotId}\" has unknown mode \"${String(record.mode)}\"`,\n\t\t\t{ snapshotId, mode: String(record.mode) },\n\t\t);\n\t}\n\tif (\"nodes\" in record && \"edges\" in record && \"subgraphs\" in record && \"name\" in record) {\n\t\treturn record as unknown as GraphPersistSnapshot;\n\t}\n\tthrow new SurfaceError(\n\t\t\"restore-failed\",\n\t\t`snapshot \"${snapshotId}\" payload is not a GraphCheckpointRecord or GraphPersistSnapshot`,\n\t\t{ snapshotId },\n\t);\n}\n\n/**\n * Write a graph's current state as a one-shot `mode: \"full\"` record.\n *\n * Uses the same {@link GraphCheckpointRecord} envelope as\n * {@link Graph.attachSnapshotStorage} so the two persistence paths interoperate.\n *\n * @throws {SurfaceError} `snapshot-failed` when the tier's `save` throws.\n */\nexport async function saveSnapshot(\n\tgraph: Graph,\n\tsnapshotId: string,\n\ttier: KvStorageTier,\n): Promise<SaveSnapshotResult> {\n\tassertExternalId(snapshotId);\n\tlet snapshot: GraphPersistSnapshot;\n\ttry {\n\t\tsnapshot = graph.snapshot();\n\t} catch (err) {\n\t\tconst message = err instanceof Error ? err.message : String(err);\n\t\tthrow new SurfaceError(\n\t\t\t\"snapshot-failed\",\n\t\t\t`snapshot \"${snapshotId}\" serialization failed: ${message}`,\n\t\t\t{ snapshotId },\n\t\t);\n\t}\n\tconst record: GraphCheckpointRecord = {\n\t\tname: graph.name,\n\t\tmode: \"full\",\n\t\tseq: 0,\n\t\ttimestamp_ns: wallClockNs(),\n\t\tformat_version: SNAPSHOT_WIRE_VERSION,\n\t\tsnapshot,\n\t};\n\ttry {\n\t\tawait tier.save(encodeKey(snapshotId), record);\n\t} catch (err) {\n\t\tconst message = err instanceof Error ? err.message : String(err);\n\t\tthrow new SurfaceError(\"snapshot-failed\", `snapshot \"${snapshotId}\" save failed: ${message}`, {\n\t\t\tsnapshotId,\n\t\t});\n\t}\n\treturn { snapshotId, timestamp_ns: record.timestamp_ns };\n}\n\n/**\n * Load a snapshot from a tier and materialize it as a new {@link Graph}.\n *\n * Uses {@link Graph.fromSnapshot} to reconstruct topology; pass\n * `factories` when the graph includes non-state nodes that the default\n * hydrator can't rebuild on its own.\n *\n * **Requires a `mode: \"full\"` record.** Surface-written snapshots from\n * {@link saveSnapshot} always qualify. Records written by\n * {@link Graph.attachSnapshotStorage} with `compactEvery > 1` may be\n * `mode: \"diff\"` between compacts — those throw `restore-failed` until\n * the tier's next compact flush (or until Phase 8.7 WAL replay lands).\n * If you need interop during development, either call\n * {@link saveSnapshot} explicitly (always full) or configure\n * `attachSnapshotStorage({compactEvery: 1})`.\n *\n * @throws {SurfaceError} `snapshot-not-found` on miss; `restore-failed`\n *   when the payload shape doesn't match, when the record is\n *   `mode: \"diff\"`, or when `Graph.fromSnapshot` rejects.\n */\nexport async function restoreSnapshot(\n\tsnapshotId: string,\n\ttier: KvStorageTier,\n\topts?: RestoreSnapshotOptions,\n): Promise<Graph> {\n\tassertExternalId(snapshotId);\n\t// Try namespaced key first (surface-written records), fall back to raw key\n\t// so callers restoring snapshots that predate the namespacing change (or\n\t// bare `GraphPersistSnapshot` payloads written by user test fixtures)\n\t// still resolve. Once all writers are on encodeKey, the fallback can go.\n\tconst key = encodeKey(snapshotId);\n\tlet raw = await tier.load(key);\n\tif (raw === undefined) {\n\t\traw = await tier.load(snapshotId);\n\t}\n\tconst snapshot = unwrapCheckpoint(raw, snapshotId);\n\ttry {\n\t\treturn Graph.fromSnapshot(\n\t\t\tsnapshot,\n\t\t\topts?.factories ? { factories: opts.factories } : undefined,\n\t\t);\n\t} catch (err) {\n\t\tconst message = err instanceof Error ? err.message : String(err);\n\t\tthrow new SurfaceError(\n\t\t\t\"restore-failed\",\n\t\t\t`snapshot \"${snapshotId}\" restore failed: ${message}`,\n\t\t\t{\n\t\t\t\tsnapshotId,\n\t\t\t},\n\t\t);\n\t}\n}\n\n/**\n * Load two snapshots and compute a {@link GraphDiffResult} via static\n * {@link Graph.diff}. Returns the audit shape (structural + value diff,\n * no payload); use {@link diffForWAL} directly for WAL-oriented diffs.\n *\n * @throws {SurfaceError} `snapshot-not-found` on either miss.\n */\nexport async function diffSnapshots(\n\tsnapshotIdA: string,\n\tsnapshotIdB: string,\n\ttier: KvStorageTier,\n): Promise<GraphDiffResult> {\n\tassertExternalId(snapshotIdA);\n\tassertExternalId(snapshotIdB);\n\tconst loadWithFallback = async (id: string): Promise<unknown> => {\n\t\tconst key = encodeKey(id);\n\t\tlet raw = await tier.load(key);\n\t\tif (raw === undefined) raw = await tier.load(id);\n\t\treturn raw;\n\t};\n\tconst [rawA, rawB] = await Promise.all([\n\t\tloadWithFallback(snapshotIdA),\n\t\tloadWithFallback(snapshotIdB),\n\t]);\n\tconst snapshotA = unwrapCheckpoint(rawA, snapshotIdA);\n\tconst snapshotB = unwrapCheckpoint(rawB, snapshotIdB);\n\treturn Graph.diff(snapshotA, snapshotB);\n}\n\n/**\n * Enumerate snapshot ids on a tier.\n *\n * Only keys written by {@link saveSnapshot} are returned. Surface-written\n * records are stored under the `\"snapshot:\"` key prefix and decoded back to\n * the caller-visible id before being returned — other keys on the same tier\n * (notably `attachSnapshotStorage` baseline/WAL keys written under `graph.name`) are\n * filtered out automatically. This lets a single tier back both the surface\n * and `attachSnapshotStorage` without leaking graph names through `listSnapshots`.\n *\n * @param tier — the storage tier to enumerate.\n * @param opts.includeUnprefixed — when `true`, also return keys that are\n *   NOT under the namespacing prefix. Off by default; set this when reading\n *   pre-namespacing snapshot sets.\n *\n *   **Caveat:** when a tier is shared with {@link Graph.attachSnapshotStorage}, its\n *   auto-checkpoint baseline + WAL keys (written under `graph.name`) are\n *   unprefixed. Calling with `includeUnprefixed: true` returns those keys\n *   alongside surface snapshots — and subsequent `restoreSnapshot` /\n *   `deleteSnapshot` will operate on them via the fallback-lookup path,\n *   potentially overwriting or deleting live auto-checkpoint state. Use\n *   `includeUnprefixed` only against tiers you know are NOT shared with\n *   `attachSnapshotStorage`, or follow up with a predicate filter to separate\n *   ids you own from ones owned by other subsystems.\n *\n * @throws {SurfaceError} `tier-no-list` when the tier does not implement\n *   the optional `list()` method. Check `typeof tier.list === \"function\"`\n *   before calling if you want to branch on capability.\n */\nexport async function listSnapshots(\n\ttier: KvStorageTier,\n\topts?: { includeUnprefixed?: boolean },\n): Promise<readonly string[]> {\n\tif (typeof tier.list !== \"function\") {\n\t\tthrow new SurfaceError(\n\t\t\t\"tier-no-list\",\n\t\t\t\"KvStorageTier does not implement list(); wrap the tier with an enumerator or use a different backend\",\n\t\t);\n\t}\n\tconst keys = await tier.list();\n\tconst result: string[] = [];\n\tconst includeUnprefixed = opts?.includeUnprefixed === true;\n\tfor (const k of keys) {\n\t\tconst decoded = decodeKey(k);\n\t\tif (decoded !== undefined) result.push(decoded);\n\t\telse if (includeUnprefixed) result.push(k);\n\t}\n\treturn result;\n}\n\n/**\n * Delete a snapshot from a tier.\n *\n * Silent on miss (clear semantics). `tier.clear` is optional — throws\n * `snapshot-failed` when the tier is append-only.\n *\n * @throws {SurfaceError} `snapshot-failed` when `clear` is unsupported\n *   or throws.\n */\nexport async function deleteSnapshot(snapshotId: string, tier: KvStorageTier): Promise<void> {\n\tassertExternalId(snapshotId);\n\tif (typeof tier.delete !== \"function\") {\n\t\tthrow new SurfaceError(\n\t\t\t\"snapshot-failed\",\n\t\t\t`KvStorageTier is append-only (no delete()); cannot delete \"${snapshotId}\"`,\n\t\t\t{ snapshotId },\n\t\t);\n\t}\n\ttry {\n\t\tawait tier.delete(encodeKey(snapshotId));\n\t} catch (err) {\n\t\tconst message = err instanceof Error ? err.message : String(err);\n\t\tthrow new SurfaceError(\n\t\t\t\"snapshot-failed\",\n\t\t\t`snapshot \"${snapshotId}\" delete failed: ${message}`,\n\t\t\t{\n\t\t\t\tsnapshotId,\n\t\t\t},\n\t\t);\n\t}\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-4XCHZRUJ.js

@@ -0,0 +1,128 @@
+import {
+  domainMeta
+} from "./chunk-FMPF42Q4.js";
+
+// src/utils/inspect/lens.ts
+import { node } from "@graphrefly/pure-ts/core";
+import { keepalive } from "@graphrefly/pure-ts/extra";
+import {
+  reachable
+} from "@graphrefly/pure-ts/graph";
+import { watchTopologyTree } from "@graphrefly/pure-ts/graph";
+function computeHealthReport(described) {
+  const problems = [];
+  for (const [path, desc] of Object.entries(described.nodes)) {
+    if (desc.status !== "errored") continue;
+    const entry = { path, status: "errored" };
+    const upstream = reachable(described, path, "upstream", {});
+    for (const p of upstream) {
+      if (p === path) continue;
+      if (described.nodes[p]?.status === "errored") {
+        entry.upstreamCause = p;
+        break;
+      }
+    }
+    problems.push(entry);
+  }
+  problems.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+  return { ok: problems.length === 0, problems };
+}
+function healthReportEqual(a, b) {
+  if (a.ok !== b.ok) return false;
+  if (a.problems.length !== b.problems.length) return false;
+  for (let i = 0; i < a.problems.length; i++) {
+    const x = a.problems[i];
+    const y = b.problems[i];
+    if (x.path !== y.path) return false;
+    if (x.status !== y.status) return false;
+    if (x.upstreamCause !== y.upstreamCause) return false;
+  }
+  return true;
+}
+function graphLens(target) {
+  const topologyHandle = target.describe({
+    reactive: true,
+    detail: "standard",
+    reactiveName: "graphLens.topology"
+  });
+  const topology = topologyHandle.node;
+  const health = node(
+    [topology],
+    (batchData, actions, ctx) => {
+      const data = batchData.map(
+        (batch, i) => batch != null && batch.length > 0 ? batch.at(-1) : ctx.prevData[i]
+      );
+      actions.emit(computeHealthReport(data[0]));
+    },
+    {
+      name: "graphLens.health",
+      describeKind: "derived",
+      equals: healthReportEqual,
+      meta: domainMeta("lens", "health")
+    }
+  );
+  const stopHealthKeep = keepalive(health);
+  const flowMap = /* @__PURE__ */ new Map();
+  let lastAppliedFlush_ns = -1;
+  const dataFlow = target.observe({ reactive: true, tiers: ["data"] });
+  const flow = node(
+    [dataFlow, topology],
+    (batchData, actions, ctx) => {
+      const data = batchData.map(
+        (batch, i) => batch != null && batch.length > 0 ? batch.at(-1) : ctx.prevData[i]
+      );
+      const changeset = data[0];
+      const described = data[1];
+      const c = changeset;
+      const desc = described;
+      if (c != null && c.flushedAt_ns > lastAppliedFlush_ns) {
+        lastAppliedFlush_ns = c.flushedAt_ns;
+        for (const event of c.events) {
+          if (event.type !== "data") continue;
+          const path = event.path;
+          if (path == null || path === "") continue;
+          const prior = flowMap.get(path);
+          flowMap.set(path, {
+            path,
+            count: (prior?.count ?? 0) + 1,
+            lastUpdate_ns: c.flushedAt_ns
+          });
+        }
+      }
+      if (desc != null && flowMap.size > 0) {
+        const valid = new Set(Object.keys(desc.nodes));
+        for (const k of [...flowMap.keys()]) {
+          if (!valid.has(k)) flowMap.delete(k);
+        }
+      }
+      actions.emit(new Map(flowMap));
+    },
+    {
+      name: "graphLens.flow",
+      describeKind: "derived",
+      meta: domainMeta("lens", "flow")
+    }
+  );
+  const stopFlowKeep = keepalive(flow);
+  let disposed = false;
+  return {
+    topology,
+    health,
+    flow,
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      stopFlowKeep();
+      stopHealthKeep();
+      topologyHandle.dispose();
+    }
+  };
+}
+
+export {
+  computeHealthReport,
+  healthReportEqual,
+  graphLens,
+  watchTopologyTree
+};
+//# sourceMappingURL=chunk-4XCHZRUJ.js.map

package/dist/chunk-4XCHZRUJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils/inspect/lens.ts"],"sourcesContent":["/**\n * Reactive graph observability preset (Tier 5.3 reshape — Session A.4 lock).\n *\n * `graphLens(target)` is a thin compositor (~30 LOC of glue) over two\n * already-shipped reactive primitives:\n *\n * - `target.describe({ reactive: true })` — live topology snapshot.\n * - `target.observe({ reactive: true, tiers: [\"data\"] })` — coalesced data\n *   changesets per outermost batch flush.\n *\n * It returns three Nodes plus a dispose function:\n *\n * - `topology: Node<GraphDescribeOutput>` — the live describe snapshot,\n *   re-emitting on every settle of the target tree (structural change,\n *   error/complete/teardown transition).\n * - `health: Node<HealthReport>` — `{ok, problems[]}` aggregated from the\n *   live describe; `ok=false` when any node enters `\"errored\"` status,\n *   with `upstreamCause` walked backward through deps.\n * - `flow: Node<ReadonlyMap<string, FlowEntry>>` — per-path DATA counters\n *   accumulating as `target.observe({reactive: true, tiers: [\"data\"]})`\n *   delivers changesets. The map is reconciled against `topology` on each\n *   topology change so removed nodes drop their entries.\n *\n * Pre-Tier-5.3 shipped a `LensGraph` class with `stats` / `health` / `flow`\n * (as a `ReactiveMapBundle`) / `why(from, to)` / `flowEntryNode(...)`. The\n * surface collapsed because every concern was already a one-liner over\n * `describe({reactive:true})` + `observe({reactive:true, tiers})` once those\n * landed in Tier 1.5.1 / 1.5.2 — the class added no protocol-level concept,\n * just glue. Callers who need topology stats compose a derived over\n * `topology` directly; callers who need a causal chain call\n * `target.describe({ explain: { from, to }, reactive: true })`.\n *\n * The transitive topology-subscription helper {@link watchTopologyTree} is\n * re-exported here for downstream factories that need full-tree dynamic\n * coverage without taking a dep on `graph/`.\n *\n * @module\n */\nimport { type Node, node } from \"@graphrefly/pure-ts/core\";\nimport { keepalive } from \"@graphrefly/pure-ts/extra\";\nimport {\n\ttype Graph,\n\ttype GraphDescribeOutput,\n\ttype ObserveChangeset,\n\ttype ObserveEvent,\n\treachable,\n} from \"@graphrefly/pure-ts/graph\";\nimport { domainMeta } from \"../../base/meta/domain-meta.js\";\n\nexport { watchTopologyTree } from \"@graphrefly/pure-ts/graph\";\n\n// ---------------------------------------------------------------------------\n// Payload types\n// ---------------------------------------------------------------------------\n\n/** A single health problem entry. */\nexport interface HealthProblem {\n\tpath: string;\n\t/** V1 only reports `\"errored\"`. Future versions may add `\"completed\"`, `\"disconnected\"`. */\n\tstatus: \"errored\";\n\t/** First errored upstream ancestor along the dep chain, when one exists and is distinct from `path`. */\n\tupstreamCause?: string;\n}\n\n/** Aggregate health snapshot. `ok=true` iff `problems.length === 0`. */\nexport interface HealthReport {\n\tok: boolean;\n\tproblems: readonly HealthProblem[];\n}\n\n/** Per-path flow entry stored in the {@link GraphLensView.flow} map. */\nexport interface FlowEntry {\n\tpath: string;\n\t/** Cumulative DATA emissions observed since the lens activated. */\n\tcount: number;\n\t/** Monotonic ns at the most recent DATA emission for this path, or `null` if none yet. */\n\tlastUpdate_ns: number | null;\n}\n\n/** Output of {@link graphLens}. */\nexport interface GraphLensView {\n\t/** Live describe snapshot. Re-emits on structural change AND status transitions. */\n\ttopology: Node<GraphDescribeOutput>;\n\t/** Live `{ok, problems[]}`. Aggregated from `topology`; equality-deduped. */\n\thealth: Node<HealthReport>;\n\t/** Per-path DATA counter map. Re-emits per outermost batch flush. */\n\tflow: Node<ReadonlyMap<string, FlowEntry>>;\n\t/**\n\t * Tear down the underlying `describe({reactive:true})` subscription.\n\t * The `flow` node activates lazily; subscribing-then-unsubscribing reclaims\n\t * its observe stream automatically. Call `dispose()` once when finished.\n\t */\n\tdispose(): void;\n}\n\n// ---------------------------------------------------------------------------\n// Pure helpers (exported for testing / composition)\n// ---------------------------------------------------------------------------\n\n/** Build a `HealthReport` from a fresh `GraphDescribeOutput`. */\nexport function computeHealthReport(described: GraphDescribeOutput): HealthReport {\n\tconst problems: HealthProblem[] = [];\n\tfor (const [path, desc] of Object.entries(described.nodes)) {\n\t\tif (desc.status !== \"errored\") continue;\n\t\tconst entry: HealthProblem = { path, status: \"errored\" };\n\t\t// Walk upstream to find the first errored ancestor (if any) distinct from `path`.\n\t\t// Explicit empty options disambiguates the overload (otherwise both match\n\t\t// and TS picks the `withDetail:true` signature first).\n\t\tconst upstream = reachable(described, path, \"upstream\", {});\n\t\tfor (const p of upstream) {\n\t\t\tif (p === path) continue;\n\t\t\tif (described.nodes[p]?.status === \"errored\") {\n\t\t\t\tentry.upstreamCause = p;\n\t\t\t\tbreak;\n\t\t\t}\n\t\t}\n\t\tproblems.push(entry);\n\t}\n\tproblems.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));\n\treturn { ok: problems.length === 0, problems };\n}\n\n/** Structural equality for {@link HealthReport} — used as the `health` derived's `equals`. */\nexport function healthReportEqual(a: HealthReport, b: HealthReport): boolean {\n\tif (a.ok !== b.ok) return false;\n\tif (a.problems.length !== b.problems.length) return false;\n\tfor (let i = 0; i < a.problems.length; i++) {\n\t\tconst x = a.problems[i]!;\n\t\tconst y = b.problems[i]!;\n\t\tif (x.path !== y.path) return false;\n\t\tif (x.status !== y.status) return false;\n\t\tif (x.upstreamCause !== y.upstreamCause) return false;\n\t}\n\treturn true;\n}\n\n// ---------------------------------------------------------------------------\n// graphLens preset\n// ---------------------------------------------------------------------------\n\n/**\n * Reactive observability preset over a target {@link Graph}.\n *\n * @param target - The graph to observe.\n *\n * @example\n * ```ts\n * const g = new Graph(\"app\");\n * g.add(state(0, { name: \"counter\" }), { name: \"counter\" });\n *\n * const lens = graphLens(g);\n * lens.topology.subscribe((msgs) => console.log(\"topology:\", msgs));\n * lens.health.subscribe((msgs) => console.log(\"health:\", msgs));\n * lens.flow.subscribe((msgs) => {\n *   for (const [type, payload] of msgs) {\n *     if (type === DATA) console.log(\"flow map size:\", (payload as ReadonlyMap<string, FlowEntry>).size);\n *   }\n * });\n *\n * // Causal chains: use the underlying primitive directly — `graphLens` no\n * // longer wraps it, since `graph.describe({ explain: {...}, reactive: true })`\n * // already provides everything the old `lens.why()` did.\n * const why = g.describe({\n *   explain: { from: \"counter\", to: \"consumer\" },\n *   reactive: true,\n * });\n *\n * // Tear down when done.\n * lens.dispose();\n * ```\n *\n * @category observability\n */\nexport function graphLens(target: Graph): GraphLensView {\n\tconst topologyHandle = target.describe({\n\t\treactive: true,\n\t\tdetail: \"standard\",\n\t\treactiveName: \"graphLens.topology\",\n\t});\n\tconst topology = topologyHandle.node;\n\n\tconst health = node<HealthReport>(\n\t\t[topology],\n\t\t(batchData, actions, ctx) => {\n\t\t\tconst data = batchData.map((batch, i) =>\n\t\t\t\tbatch != null && batch.length > 0 ? batch.at(-1) : ctx.prevData[i],\n\t\t\t);\n\t\t\tactions.emit(computeHealthReport(data[0] as GraphDescribeOutput));\n\t\t},\n\t\t{\n\t\t\tname: \"graphLens.health\",\n\t\t\tdescribeKind: \"derived\",\n\t\t\tequals: healthReportEqual,\n\t\t\tmeta: domainMeta(\"lens\", \"health\"),\n\t\t},\n\t);\n\t// `topology` is already kept alive by `_describeReactive`'s internal\n\t// keepalive; `health` needs its own so the derived stays warm even if\n\t// the consumer subscribes lazily.\n\tconst stopHealthKeep = keepalive(health);\n\n\t// `flow` accumulates per-path counters across emissions. Closure-mirror\n\t// (COMPOSITION-GUIDE §28) holds the canonical map; the derived returns a\n\t// fresh ReadonlyMap projection per emit so consumers never observe an\n\t// in-place mutation. Topology drives reconciliation: paths that disappear\n\t// from the describe drop their counter entry.\n\t//\n\t// `lastAppliedFlush_ns` guards against double-applying the same changeset\n\t// when topology re-emits without a new dataFlow event (e.g. a node remove\n\t// re-fires `topology` while `dataFlow.cache` still holds the previous\n\t// changeset by reference). Using the monotonic `flushedAt_ns` cursor (qa\n\t// G2A — EC4 fix) is more robust than ref-comparison: an empty changeset\n\t// re-emitted with a fresh object identity but the same `flushedAt_ns`\n\t// won't trigger a stale-events replay, and a genuinely-new changeset\n\t// always advances the cursor.\n\tconst flowMap = new Map<string, FlowEntry>();\n\tlet lastAppliedFlush_ns = -1;\n\tconst dataFlow = target.observe({ reactive: true, tiers: [\"data\"] });\n\tconst flow = node<ReadonlyMap<string, FlowEntry>>(\n\t\t[dataFlow, topology],\n\t\t(batchData, actions, ctx) => {\n\t\t\tconst data = batchData.map((batch, i) =>\n\t\t\t\tbatch != null && batch.length > 0 ? batch.at(-1) : ctx.prevData[i],\n\t\t\t);\n\t\t\tconst changeset = data[0];\n\t\t\tconst described = data[1];\n\t\t\tconst c = changeset as ObserveChangeset | undefined;\n\t\t\tconst desc = described as GraphDescribeOutput | undefined;\n\n\t\t\t// Apply NEW changeset events first so a freshly-emitted node-remove\n\t\t\t// observed below cleanly drops the entry. (If we reconciled first\n\t\t\t// then applied, an event referencing a path the topology had already\n\t\t\t// dropped would re-create the entry only to be wiped on the next\n\t\t\t// topology re-emit — order events-then-topology to avoid that.)\n\t\t\t//\n\t\t\t// Skip when `events.length === 0`: an empty changeset has no work\n\t\t\t// to do. The cursor advances anyway so a future identical-content\n\t\t\t// changeset (different ref, same flushedAt_ns) is also skipped.\n\t\t\tif (c != null && c.flushedAt_ns > lastAppliedFlush_ns) {\n\t\t\t\tlastAppliedFlush_ns = c.flushedAt_ns;\n\t\t\t\tfor (const event of c.events as readonly ObserveEvent[]) {\n\t\t\t\t\tif (event.type !== \"data\") continue;\n\t\t\t\t\tconst path = event.path;\n\t\t\t\t\tif (path == null || path === \"\") continue;\n\t\t\t\t\tconst prior = flowMap.get(path);\n\t\t\t\t\tflowMap.set(path, {\n\t\t\t\t\t\tpath,\n\t\t\t\t\t\tcount: (prior?.count ?? 0) + 1,\n\t\t\t\t\t\tlastUpdate_ns: c.flushedAt_ns,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// Reconcile against current topology — drop entries whose paths\n\t\t\t// no longer exist in the describe.\n\t\t\tif (desc != null && flowMap.size > 0) {\n\t\t\t\tconst valid = new Set(Object.keys(desc.nodes));\n\t\t\t\tfor (const k of [...flowMap.keys()]) {\n\t\t\t\t\tif (!valid.has(k)) flowMap.delete(k);\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// Snapshot — consumers receive a frozen view.\n\t\t\tactions.emit(new Map(flowMap) as ReadonlyMap<string, FlowEntry>);\n\t\t},\n\t\t{\n\t\t\tname: \"graphLens.flow\",\n\t\t\tdescribeKind: \"derived\",\n\t\t\tmeta: domainMeta(\"lens\", \"flow\"),\n\t\t},\n\t);\n\tconst stopFlowKeep = keepalive(flow);\n\n\tlet disposed = false;\n\treturn {\n\t\ttopology,\n\t\thealth,\n\t\tflow,\n\t\tdispose() {\n\t\t\tif (disposed) return;\n\t\t\tdisposed = true;\n\t\t\tstopFlowKeep();\n\t\t\tstopHealthKeep();\n\t\t\ttopologyHandle.dispose();\n\t\t},\n\t};\n}\n"],"mappings":"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","names":[]}