@graphrefly/ts 0.0.0

package/dist/chunk-2ILL7HQI.js

@@ -0,0 +1,1189 @@
+import {
+  GRAPH_CHECKPOINT_VERSION,
+  checkpointBackendStateOfNode,
+  checkpointTerminal,
+  checkpointValue,
+  initNodeWithCore,
+  toCheckpointJson
+} from "./chunk-PKVBHGBM.js";
+import {
+  EnvironmentDrivers,
+  Node,
+  NodeCore,
+  batch,
+  checkpointStateOfNode,
+  defaultDispatcher,
+  getNodeOwner,
+  isNodeActiveForRelease,
+  isNodeRuntimeQuiescentForRelease,
+  isNodeRuntimeReleased,
+  releaseRuntimeOfNode,
+  setNodeOwner,
+  setNodeTopologyDepsChangedObserver,
+  subscriberCountOfNode,
+  withEnvironmentDrivers,
+  withNodeCore
+} from "./chunk-I3IHOHCJ.js";
+import {
+  assertStrictJsonObject,
+  stableJsonString,
+  strictCanonicalJsonBytes
+} from "./chunk-4VLAQHZI.js";
+import {
+  depCount,
+  depLatest
+} from "./chunk-SWTLEQL6.js";
+import {
+  SENTINEL,
+  errorPayload,
+  messageTier
+} from "./chunk-DK554R7P.js";
+
+// src/graph/blueprint.ts
+var GRAPH_BLUEPRINT_VERSION = "graphrefly.blueprint.v1";
+function normalizeTopologyMeta(meta, label = "meta", kind = "graph meta") {
+  try {
+    return assertStrictJsonObject(meta, label);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new TypeError(`${label}: ${kind} must be strict JSON-compatible data (D177): ${message}`);
+  }
+}
+function normalizeTopology(snapshot) {
+  return normalizeTopologySnapshot(snapshot, /* @__PURE__ */ new WeakSet(), "$");
+}
+function normalizeTopologySnapshot(snapshot, seen, path) {
+  if (snapshot === null || typeof snapshot !== "object") {
+    throw new TypeError(`normalizeTopology: snapshot at ${path} must be an object`);
+  }
+  if (seen.has(snapshot)) {
+    throw new TypeError(`normalizeTopology: circular subgraph reference at ${path}`);
+  }
+  seen.add(snapshot);
+  try {
+    const nodes = mapDense(snapshot.nodes, `${path}.nodes`, (node, index) => {
+      const nodePath = `${path}.nodes[${index}]`;
+      assertTopologyObject(node, nodePath);
+      const id = topologyString(node.id, `${nodePath}.id`);
+      const factory = topologyString(node.factory, `${nodePath}.factory`);
+      const out2 = {
+        id,
+        factory,
+        deps: mapDense(
+          node.deps,
+          `${labelForNode(id)}.deps`,
+          (dep, depIndex) => topologyString(dep, `${labelForNode(id)}.deps[${depIndex}]`)
+        )
+      };
+      if (node.name !== void 0) {
+        out2.name = topologyString(node.name, `${nodePath}.name`);
+      }
+      if (node.meta !== void 0) {
+        out2.meta = normalizeTopologyMeta(node.meta, `${labelForNode(id)}.meta`);
+      }
+      return out2;
+    }).sort(compareNodes);
+    const out = {
+      nodes,
+      edges: deriveEdges(nodes)
+    };
+    if (snapshot.name !== void 0) {
+      out.name = topologyString(snapshot.name, `${path}.name`);
+    }
+    if (snapshot.subgraphs !== void 0) {
+      out.subgraphs = mapDense(
+        snapshot.subgraphs,
+        `${path}.subgraphs`,
+        (subgraph, index) => normalizeTopologySnapshot(subgraph, seen, `${path}.subgraphs[${index}]`)
+      ).sort(compareTopologies);
+    }
+    return out;
+  } finally {
+    seen.delete(snapshot);
+  }
+}
+function mapDense(values, path, mapper) {
+  if (!Array.isArray(values)) {
+    throw new TypeError(`normalizeTopology: ${path} must be an array`);
+  }
+  const out = [];
+  for (let i = 0; i < values.length; i += 1) {
+    if (!(i in values)) {
+      throw new TypeError(`normalizeTopology: sparse array hole at ${path}[${i}]`);
+    }
+    out.push(mapper(values[i], i));
+  }
+  return out;
+}
+function assertTopologyObject(value, path) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`normalizeTopology: ${path} must be an object`);
+  }
+}
+function topologyString(value, path) {
+  if (typeof value !== "string") {
+    throw new TypeError(`normalizeTopology: ${path} must be a string`);
+  }
+  return value;
+}
+function canonicalTopologyJson(snapshot) {
+  return stableJsonString(normalizeTopology(snapshot));
+}
+function canonicalTopologyBytes(snapshot) {
+  return strictCanonicalJsonBytes(normalizeTopology(snapshot));
+}
+function withBlueprintHash(blueprint, options) {
+  if (typeof options.algorithm !== "string" || options.algorithm.length === 0) {
+    throw new TypeError("withBlueprintHash: algorithm must be a non-empty string");
+  }
+  const topology = normalizeTopology(blueprint.topology);
+  const withHash = (value2) => {
+    if (typeof value2 !== "string" || value2.length === 0) {
+      throw new TypeError("withBlueprintHash: hash value must be a non-empty string");
+    }
+    return {
+      ...blueprint,
+      topology,
+      hash: {
+        kind: "topology",
+        algorithm: options.algorithm,
+        input: "strictCanonicalTopologyBytes",
+        value: value2
+      }
+    };
+  };
+  const value = options.hash(canonicalTopologyBytes(topology));
+  if (typeof value !== "string" || value.length === 0) {
+    const maybeThenable = value;
+    if (maybeThenable === null || maybeThenable === void 0 || typeof maybeThenable.then !== "function") {
+      throw new TypeError("withBlueprintHash: hash value must be a non-empty string");
+    }
+    return value.then(withHash);
+  }
+  return withHash(value);
+}
+function withBlueprintProvenance(blueprint, provenance) {
+  return {
+    ...blueprint,
+    provenance: normalizeTopologyMeta(provenance, "graph blueprint provenance", "provenance")
+  };
+}
+function graphBlueprintDiagnostics(topology) {
+  const issues = [];
+  collectDiagnostics(topology, issues);
+  issues.sort(compareIssues);
+  return { ok: !issues.some((issue) => issue.severity === "error"), issues };
+}
+function collectDiagnostics(topology, issues) {
+  const seen = /* @__PURE__ */ new Set();
+  const duplicateIds = /* @__PURE__ */ new Set();
+  for (const node of topology.nodes) {
+    if (seen.has(node.id)) duplicateIds.add(node.id);
+    seen.add(node.id);
+  }
+  for (const id of duplicateIds) {
+    issues.push({
+      severity: "error",
+      code: "duplicate-node-id",
+      nodeId: id,
+      message: `duplicate topology node id '${id}'`
+    });
+  }
+  const dependents = /* @__PURE__ */ new Map();
+  for (const node of topology.nodes) dependents.set(node.id, 0);
+  for (const node of topology.nodes) {
+    for (const dep of node.deps) {
+      if (!seen.has(dep)) {
+        issues.push({
+          severity: "error",
+          code: "dangling-dep",
+          nodeId: node.id,
+          from: dep,
+          to: node.id,
+          message: `node '${node.id}' depends on missing node '${dep}'`
+        });
+        continue;
+      }
+      dependents.set(dep, (dependents.get(dep) ?? 0) + 1);
+    }
+  }
+  for (const node of topology.nodes) {
+    if (node.deps.length === 0 && (dependents.get(node.id) ?? 0) === 0) {
+      issues.push({
+        severity: "warning",
+        code: "island-node",
+        nodeId: node.id,
+        message: `node '${node.id}' has no deps and no dependents`
+      });
+    }
+  }
+  for (const subgraph of topology.subgraphs ?? []) collectDiagnostics(subgraph, issues);
+}
+function deriveEdges(nodes) {
+  const seen = /* @__PURE__ */ new Set();
+  const edges = [];
+  for (const node of nodes) {
+    for (const from of node.deps) {
+      const key = `${from}\0${node.id}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      edges.push({ from, to: node.id });
+    }
+  }
+  return edges.sort(compareEdges);
+}
+function labelForNode(id) {
+  return id === "" ? "node" : `node '${id}'`;
+}
+function compareText(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+function compareNodes(a, b) {
+  return compareText(a.id, b.id);
+}
+function compareEdges(a, b) {
+  return compareText(a.from, b.from) || compareText(a.to, b.to);
+}
+function compareTopologies(a, b) {
+  return compareText(stableJsonString(a), stableJsonString(b));
+}
+function compareIssues(a, b) {
+  return compareText(a.code, b.code) || compareText(a.nodeId ?? "", b.nodeId ?? "") || compareText(a.from ?? "", b.from ?? "") || compareText(a.to ?? "", b.to ?? "");
+}
+
+// src/graph/describe.ts
+function topologyFromDescribe(snapshot) {
+  const nodes = snapshot.nodes.map((node) => {
+    const topologyNode = {
+      id: node.id,
+      factory: node.factory,
+      deps: [...node.deps]
+    };
+    if (node.name !== void 0) topologyNode.name = node.name;
+    if (node.meta !== void 0) topologyNode.meta = cloneTopologyMeta(node.meta);
+    return topologyNode;
+  });
+  const out = {
+    nodes,
+    edges: snapshot.edges.map((edge) => ({ from: edge.from, to: edge.to }))
+  };
+  if (snapshot.name !== void 0) out.name = snapshot.name;
+  if (snapshot.subgraphs !== void 0)
+    out.subgraphs = snapshot.subgraphs.map(topologyFromDescribe);
+  return out;
+}
+function cloneTopologyMeta(meta) {
+  return cloneTopologyValue(meta, /* @__PURE__ */ new WeakMap());
+}
+function cloneTopologyValue(value, seen) {
+  if (value === null) return null;
+  const kind = typeof value;
+  if (kind === "string" || kind === "boolean") return value;
+  if (kind === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error("topology(): meta must be finite JSON-compatible data (D39/D173)");
+    }
+    return value;
+  }
+  if (kind !== "object") {
+    throw new Error("topology(): meta must be JSON-compatible data (D39/D173)");
+  }
+  const objectValue = value;
+  const cached = seen.get(objectValue);
+  if (cached !== void 0) return cached;
+  if (Array.isArray(value)) {
+    const out2 = new Array(value.length);
+    seen.set(objectValue, out2);
+    for (let i = 0; i < value.length; i += 1) {
+      if (!(i in value)) {
+        throw new Error("topology(): meta arrays must be dense JSON-compatible data (D39/D173)");
+      }
+      out2[i] = cloneTopologyValue(value[i], seen);
+    }
+    return out2;
+  }
+  const proto = Object.getPrototypeOf(objectValue);
+  if (proto !== Object.prototype && proto !== null) {
+    throw new Error("topology(): meta must be plain JSON-compatible data (D39/D173)");
+  }
+  const out = {};
+  seen.set(objectValue, out);
+  for (const [key, item] of Object.entries(value))
+    out[key] = cloneTopologyValue(item, seen);
+  return out;
+}
+
+// src/graph/graph.ts
+var restoreRegistrars = /* @__PURE__ */ new WeakMap();
+var lifecycleRegistrars = /* @__PURE__ */ new WeakMap();
+function nodeOwner(n) {
+  return getNodeOwner(n);
+}
+function assertGraphLocalNode(owner, n, label) {
+  if (isNodeRuntimeReleased(n)) {
+    throw new Error(`${label} has been released from its graph lifecycle (D122)`);
+  }
+  const existing = nodeOwner(n);
+  if (existing !== void 0 && existing !== owner) {
+    throw new Error(
+      `${label} belongs to a different graph; cross-graph deps require a wire bridge`
+    );
+  }
+}
+var StateNode = class extends Node {
+  set(v) {
+    this.down([["DATA", v]]);
+  }
+};
+var GraphTopologyGroup = class {
+  name;
+  _graph;
+  _members = [];
+  _released = false;
+  constructor(graph2, opts = {}) {
+    this._graph = graph2;
+    this.name = opts.name;
+  }
+  get released() {
+    return this._released;
+  }
+  add(node) {
+    this._assertLive();
+    const lifecycle = lifecycleRegistrars.get(this._graph);
+    if (lifecycle === void 0) throw new Error("topologyGroup: graph lifecycle unavailable");
+    lifecycle.assertRegisteredNode(node, `topology group '${this.name ?? "group"}' member`);
+    if (!this._members.includes(node)) this._members.push(node);
+    return node;
+  }
+  node(deps = [], fn = null, opts = {}) {
+    this._assertLive();
+    return this.add(this._graph.node(deps, fn, opts));
+  }
+  state(initial, opts = {}) {
+    this._assertLive();
+    return this.add(this._graph.state(initial, opts));
+  }
+  producer(fn, opts = {}) {
+    this._assertLive();
+    return this.add(this._graph.producer(fn, opts));
+  }
+  derived(deps, fn, opts = {}) {
+    this._assertLive();
+    return this.add(this._graph.derived(deps, fn, opts));
+  }
+  effect(deps, fn, opts = {}) {
+    this._assertLive();
+    return this.add(this._graph.effect(deps, fn, opts));
+  }
+  initNode(op, deps, opts = {}) {
+    this._assertLive();
+    return this.add(this._graph.initNode(op, deps, opts));
+  }
+  release(opts = {}) {
+    if (this._released) return;
+    const lifecycle = lifecycleRegistrars.get(this._graph);
+    if (lifecycle === void 0) throw new Error("topologyGroup: graph lifecycle unavailable");
+    lifecycle.releaseNodes([...this._members], {
+      reason: opts.reason ?? this.name
+    });
+    this._members.length = 0;
+    this._released = true;
+  }
+  _assertLive() {
+    if (this._released) {
+      throw new Error(`topology group '${this.name ?? "group"}' has been released (D152)`);
+    }
+  }
+};
+var Graph = class {
+  name;
+  _dispatcher;
+  _versioning;
+  _environment;
+  _core = new NodeCore();
+  _entries = /* @__PURE__ */ new Map();
+  _byId = /* @__PURE__ */ new Map();
+  _retiredIds = /* @__PURE__ */ new Set();
+  _mounts = [];
+  _seq = 0;
+  _clock = 0;
+  // graph-local monotonic clock for observe seq (D26)
+  _topologyObserverSeq = 0;
+  _topologyObservers = /* @__PURE__ */ new Map();
+  _topologyDelivering = false;
+  _topologyQueue = [];
+  // D51: stable synthetic ids for unregistered live deps (runtime *Map inners) auto-discovered by
+  // describe(). WeakMap-cached so successive describes agree + the inner's id is freed when it is.
+  // A dedicated counter (NOT _seq) so a describe() call never perturbs registered-node id numbering.
+  _synthSeq = 0;
+  _synthIds = /* @__PURE__ */ new WeakMap();
+  constructor(opts = {}) {
+    this.name = opts.name;
+    this._dispatcher = opts.dispatcher ?? defaultDispatcher;
+    this._versioning = opts.versioning;
+    this._environment = opts.environment ?? EnvironmentDrivers.empty();
+    if (opts.profile) this._dispatcher.setRecording(true);
+    restoreRegistrars.set(this, {
+      stateNode: (id, stateOpts = {}) => {
+        const n = this._construct(() => new StateNode([], null, this._nodeOpts(stateOpts)));
+        this._addWithId(n, "state", [], stateOpts, id);
+        return n;
+      },
+      node: (id, factory, deps, fn, nodeOpts = {}) => {
+        this._assertDepsLocal(deps, `dep of restored '${id}'`);
+        const n = this._construct(() => new Node([...deps], fn, this._nodeOpts(nodeOpts)));
+        this._addWithId(n, factory, deps, nodeOpts, id);
+        return n;
+      }
+    });
+    lifecycleRegistrars.set(this, {
+      assertRegisteredNode: (node, label) => this._assertRegisteredNode(node, label),
+      releaseNodes: (nodes, releaseOpts) => this._releaseNodes(nodes, releaseOpts)
+    });
+  }
+  // ── registration / inspection index ──
+  _add(n, factory, deps, opts) {
+    const id = opts.name ?? `${factory}#${this._seq++}`;
+    return this._addWithId(n, factory, deps, opts, id);
+  }
+  _addWithId(n, factory, deps, opts, id) {
+    assertGraphLocalNode(this, n, `graph node '${opts.name ?? factory}'`);
+    for (const dep of deps) assertGraphLocalNode(this, dep, `dep of '${opts.name ?? factory}'`);
+    if (this._byId.has(id)) {
+      throw new Error(`graph: duplicate node id '${id}' (checkpoint/describe ids must be unique)`);
+    }
+    if (this._retiredIds.has(id)) {
+      throw new Error(`graph: node id '${id}' was released and cannot be reused (D152/D153)`);
+    }
+    const meta = opts.meta === void 0 ? void 0 : normalizeTopologyMeta(opts.meta, `graph node '${id}' meta`);
+    this._entries.set(n, {
+      node: n,
+      id,
+      name: opts.name,
+      factory,
+      deps,
+      meta,
+      restore: opts.restore
+    });
+    setNodeOwner(n, this);
+    this._byId.set(id, n);
+    setNodeTopologyDepsChangedObserver(n, (_node, prevDeps, nextDeps) => {
+      this._emitTopologyDepsChanged(n, prevDeps, nextDeps);
+    });
+    const seqMatch = /#(\d+)$/.exec(id);
+    if (seqMatch) this._seq = Math.max(this._seq, Number(seqMatch[1]) + 1);
+    this._emitTopologyNodeRegistered(n);
+    return n;
+  }
+  _assertDepsLocal(deps, label) {
+    for (const dep of deps) assertGraphLocalNode(this, dep, label);
+  }
+  _assertRegisteredNode(node, label) {
+    assertGraphLocalNode(this, node, label);
+    if (!this._entries.has(node)) {
+      throw new Error(`${label} is not a registered graph node (D152)`);
+    }
+  }
+  _nodeOpts(opts) {
+    if (opts.meta !== void 0) {
+      normalizeTopologyMeta(opts.meta, `graph node '${opts.name ?? opts.factory ?? "node"}' meta`);
+    }
+    const { name: _n, meta: _m, restore: _r, ...rest } = opts;
+    return {
+      ...rest,
+      versioning: rest.versioning ?? this._versioning,
+      dispatcher: this._dispatcher
+    };
+  }
+  _construct(create) {
+    return withEnvironmentDrivers(this._environment, () => withNodeCore(this._core, create));
+  }
+  /** Look up a registered node by its id. */
+  find(id) {
+    return this._byId.get(id);
+  }
+  _releaseNodes(nodes, _opts = {}) {
+    const seen = /* @__PURE__ */ new Set();
+    const entries = [];
+    for (const node of nodes) {
+      if (seen.has(node)) continue;
+      seen.add(node);
+      const entry = this._entries.get(node);
+      if (entry === void 0) continue;
+      entries.push({ node, entry });
+    }
+    const releaseSet = new Set(entries.map(({ node }) => node));
+    const releaseIds = new Map(entries.map(({ node, entry }) => [node, entry.id]));
+    for (const entry of this._entries.values()) {
+      if (releaseSet.has(entry.node)) continue;
+      for (const dep of entry.node.deps) {
+        if (!releaseSet.has(dep)) continue;
+        const depId = releaseIds.get(dep) ?? dep.name ?? dep.factory ?? "released node";
+        throw new Error(
+          `graph: cannot release node group; '${entry.id}' still depends on '${depId}' (D122)`
+        );
+      }
+    }
+    for (const { node, entry } of entries) {
+      if (!isNodeRuntimeQuiescentForRelease(node)) {
+        throw new Error(
+          `graph: cannot release node group; '${entry.id}' is not runtime-quiescent (D124)`
+        );
+      }
+      let internalSubscribers = 0;
+      for (const { node: dependent } of entries) {
+        if (dependent === node || !isNodeActiveForRelease(dependent)) continue;
+        for (const dep of dependent.deps) {
+          if (dep === node) internalSubscribers += 1;
+        }
+      }
+      if (subscriberCountOfNode(node) > internalSubscribers) {
+        throw new Error(
+          `graph: cannot release node group; '${entry.id}' still has live subscribers (D124)`
+        );
+      }
+    }
+    const releasedEvents = this._topologyObservers.size === 0 ? [] : entries.map(({ node, entry }) => ({
+      path: entry.id,
+      factory: entry.factory,
+      deps: this._topologyDeps(node.deps)
+    }));
+    for (const { node, entry } of entries) {
+      this._entries.delete(node);
+      this._byId.delete(entry.id);
+      this._retiredIds.add(entry.id);
+    }
+    let releaseError;
+    for (const { node } of entries) {
+      try {
+        releaseRuntimeOfNode(node);
+      } catch (error) {
+        if (releaseError === void 0) releaseError = error;
+      }
+    }
+    for (const event of releasedEvents) this._emitTopologyNodeReleased(event);
+    if (releaseError !== void 0) throw releaseError;
+  }
+  // ── 8 verbs (core: node/state/batch + sugar: producer/derived/effect/mount) ──
+  /** ctx-level power surface: a raw `(ctx)=>void` fn (or a passthrough/state when null). */
+  node(deps = [], fn = null, opts = {}) {
+    this._assertDepsLocal(deps, `dep of '${opts.name ?? "node"}'`);
+    const n = this._construct(() => new Node(deps, fn, this._nodeOpts(opts)));
+    return this._add(n, opts.factory ?? "node", deps, opts);
+  }
+  /** A manual source with `.set(v)` (L4-Q1). */
+  state(initial, opts = {}) {
+    const n = this._construct(
+      () => new StateNode([], null, { ...this._nodeOpts(opts), initial })
+    );
+    this._add(n, "state", [], opts);
+    return n;
+  }
+  /** ctx-level depless source; its fn runs on activation (R-rom-ram). */
+  producer(fn, opts = {}) {
+    const n = this._construct(() => new Node([], fn, this._nodeOpts(opts)));
+    return this._add(n, "producer", [], opts);
+  }
+  /** value-level pure transform: deps → value (D27 wrapped; D30 throw→ERROR). */
+  derived(deps, fn, opts = {}) {
+    this._assertDepsLocal(deps, `dep of '${opts.name ?? "derived"}'`);
+    const ctxFn = (ctx) => {
+      try {
+        const args = Array.from(
+          { length: depCount(ctx) },
+          (_, i) => depLatest(ctx, i)
+        );
+        const result = fn(...args);
+        if (result !== void 0) ctx.down([["DATA", result]]);
+      } catch (e) {
+        ctx.down([["ERROR", errorPayload(e, "derived threw without a valid error payload")]]);
+      }
+    };
+    const n = this._construct(() => new Node([...deps], ctxFn, this._nodeOpts(opts)));
+    return this._add(n, "derived", deps, opts);
+  }
+  /** value-level sink: deps → effect; return value (a fn) becomes onDeactivation (D28). */
+  effect(deps, fn, opts = {}) {
+    this._assertDepsLocal(deps, `dep of '${opts.name ?? "effect"}'`);
+    const ctxFn = (ctx) => {
+      try {
+        const args = Array.from(
+          { length: depCount(ctx) },
+          (_, i) => depLatest(ctx, i)
+        );
+        const cleanup = fn(...args);
+        if (typeof cleanup === "function") ctx.onDeactivation(cleanup);
+      } catch (e) {
+        ctx.down([["ERROR", errorPayload(e, "effect threw without a valid error payload")]]);
+      }
+    };
+    const n = this._construct(() => new Node([...deps], ctxFn, this._nodeOpts(opts)));
+    return this._add(n, "effect", deps, opts);
+  }
+  /** Declarative batch (D12): one wave, success→commit / throw→rollback. */
+  batch(fn) {
+    return batch(fn);
+  }
+  /** Embed a child graph addressable under `at` (R-mount; mount has no deps). */
+  mount(child, opts) {
+    const mount = { at: opts.at, graph: child };
+    this._mounts.push(mount);
+    if (this._topologyObservers.size > 0) this._ensureMountedTopologyForwarders();
+    this._emitTopologyMountChanged(opts.at);
+  }
+  // ── operator funnel (D43): instantiate any free-standing Operator (node sugar, D6/L1.5) ──
+  // g.initNode is the single graph-bound entry for the whole operator/source catalog (D40):
+  // it delegates to the FREE initNode (graph/operators.ts — the D30 throw→ERROR boundary +
+  // dispatcher binding live there) and records the operator's REAL factory name in the
+  // inspection index (_add) so describe shows it (D6/R-describe) while the node stays thin
+  // (R-node-thin). Operators are free-standing factory definitions (graph/operators.ts,
+  // graph/sources.ts) usable bare via the free initNode(); this funnel is the inspectable
+  // path. Replaces the per-operator methods.
+  /**
+   * Instantiate an operator (or source) factory as a registered graph node. `deps` are
+   * type-checked against the operator's input element type; the output type flows from the
+   * operator. A source is a depless operator — pass `[]`. Caller `opts` (name/meta/behavioral
+   * overrides) win over the operator's baked-in `opts`.
+   */
+  initNode(op, deps, opts = {}) {
+    const entryOpts = op.restore !== void 0 && !("restore" in opts) ? { ...opts, restore: op.restore } : opts;
+    for (const dep of deps)
+      assertGraphLocalNode(this, dep, `dep of '${entryOpts.name ?? op.factory}'`);
+    const erased = deps;
+    const n = withEnvironmentDrivers(
+      this._environment,
+      () => initNodeWithCore(this._core, op, erased, this._nodeOpts(entryOpts))
+    );
+    return this._add(n, op.factory, erased, entryOpts);
+  }
+  /**
+   * Graph-owned activation root for internal helper nodes. This is the sanctioned keepalive shape:
+   * a graph, not a helper closure, owns the subscription and returns the release handle.
+   */
+  retain(node, opts = {}) {
+    assertGraphLocalNode(this, node, opts.reason ?? "retained node");
+    return node.subscribe(() => {
+    });
+  }
+  /**
+   * D152 graph-owned topology/release group. Members are ordinary registered graph nodes;
+   * release is quiescent-only and removes ids atomically without synthesizing protocol messages.
+   */
+  topologyGroup(opts = {}) {
+    return new GraphTopologyGroup(this, opts);
+  }
+  // ── inspection: describe / observe / profile (D39) ──
+  /** Live point-in-time structure snapshot (R-describe / D39 / D51). `_prefix` carries the mount path. */
+  describe(opts = {}, _prefix = "") {
+    const discovered = /* @__PURE__ */ new Map();
+    const localId = (n) => {
+      const e = this._entries.get(n);
+      if (e) return `${_prefix}${e.id}`;
+      let sid = this._synthIds.get(n);
+      if (sid === void 0) {
+        do {
+          sid = `~${n.factory ?? "?"}#${this._synthSeq++}`;
+        } while (this._byId.has(sid));
+        this._synthIds.set(n, sid);
+      }
+      discovered.set(n, sid);
+      return `${_prefix}${sid}`;
+    };
+    const nodes = [];
+    const edges = [];
+    for (const entry of this._entries.values()) {
+      const id = `${_prefix}${entry.id}`;
+      const liveIds = entry.node.deps.map(localId);
+      const dnode = {
+        id,
+        factory: entry.factory,
+        status: entry.node.status,
+        deps: liveIds
+      };
+      if (entry.name !== void 0) dnode.name = entry.name;
+      if (entry.node.cache !== void 0) dnode.value = entry.node.cache;
+      if (entry.node.version !== void 0) dnode.version = entry.node.version;
+      if (entry.meta !== void 0) dnode.meta = entry.meta;
+      nodes.push(dnode);
+      for (const from of liveIds) edges.push({ from, to: id });
+    }
+    const visited = /* @__PURE__ */ new Set();
+    const queue = [...discovered.keys()];
+    for (let i = 0; i < queue.length; i += 1) {
+      const inner = queue[i];
+      if (visited.has(inner)) continue;
+      visited.add(inner);
+      const sid = discovered.get(inner);
+      if (sid === void 0) continue;
+      const liveIds = inner.deps.map(localId);
+      for (const dep of inner.deps) {
+        if (!this._entries.has(dep) && !visited.has(dep)) queue.push(dep);
+      }
+      const dnode = {
+        id: `${_prefix}${sid}`,
+        factory: inner.factory ?? "?",
+        status: inner.status,
+        deps: liveIds
+      };
+      if (inner.cache !== void 0) dnode.value = inner.cache;
+      if (inner.version !== void 0) dnode.version = inner.version;
+      nodes.push(dnode);
+      for (const from of liveIds) edges.push({ from, to: dnode.id });
+    }
+    const snap = { nodes, edges };
+    if (this.name !== void 0) snap.name = this.name;
+    if (this._mounts.length > 0) {
+      snap.subgraphs = this._mounts.map((m) => m.graph.describe({}, `${_prefix}${m.at}::`));
+    }
+    return opts.explain ? explainSubset(snap, opts.explain) : snap;
+  }
+  /**
+   * D173 pure-structure topology snapshot over the same live truth source as describe().
+   * Runtime status/value/version remain on describe(); blueprint metadata is a later envelope.
+   */
+  topology() {
+    return topologyFromDescribe(this.describe());
+  }
+  /**
+   * D177 synchronous audit/collaboration envelope over the pure topology snapshot.
+   * Hashing and environment provenance enrichment stay in pure helpers outside Graph core.
+   */
+  blueprint(opts = {}) {
+    const topology = normalizeTopology(this.topology());
+    const out = {
+      version: GRAPH_BLUEPRINT_VERSION,
+      topology
+    };
+    if (opts.diagnostics) {
+      out.diagnostics = graphBlueprintDiagnostics(topology);
+    }
+    if (opts.provenance !== void 0) {
+      out.provenance = normalizeTopologyMeta(
+        opts.provenance,
+        "graph blueprint provenance",
+        "provenance"
+      );
+    }
+    return out;
+  }
+  _observeTargets(path) {
+    const all = [...this._entries.values()].map((e) => [
+      e.id,
+      e.node
+    ]);
+    if (path === void 0) return all;
+    const exact = this._byId.get(path);
+    if (exact) return [[path, exact]];
+    return all.filter(([id]) => id.startsWith(`${path}::`));
+  }
+  /**
+   * observe(path?) = read-only enveloped EGRESS (R-observe / D39). NOT a graph node — it
+   * taps the target node(s) via subscribe and forwards each Message as an ObserveEvent.
+   * No path = whole graph; an exact id = a single node; otherwise a `::`-prefix subtree.
+   */
+  // NOTE (R-observe/D19): observe is a real, lazily-ACTIVATING subscriber — observing a
+  // cold node runs its fn (and activates upstream); whole-graph observe() activates the
+  // graph. "Read-only" means it never emits/mutates node state, NOT that it avoids
+  // activation. Use it knowing inspection of a cold graph wakes it.
+  observe(path) {
+    const targets = this._observeTargets(path);
+    return {
+      subscribe: (sink) => {
+        const unsubs = targets.map(
+          ([id, n]) => n.subscribe((msg) => {
+            sink({ path: id, msg, tier: messageTier(msg[0]), seq: this._clock++ });
+          })
+        );
+        return () => {
+          for (const u of unsubs) u();
+        };
+      }
+    };
+  }
+  /**
+   * D145 observeTopology(path?) = read-only graph lifecycle egress over the existing
+   * graph registry. It is not a graph node, does not subscribe to nodes, and emits no DATA.
+   */
+  observeTopology(path) {
+    return {
+      subscribe: (sink) => {
+        const id = this._topologyObserverSeq++;
+        this._topologyObservers.set(id, { path, sink });
+        this._ensureMountedTopologyForwarders();
+        return () => {
+          this._topologyObservers.delete(id);
+          if (this._topologyObservers.size === 0) this._releaseMountedTopologyForwarders();
+        };
+      }
+    };
+  }
+  _idForTopologyNode(n) {
+    const e = this._entries.get(n);
+    if (e) return e.id;
+    let sid = this._synthIds.get(n);
+    if (sid === void 0) {
+      do {
+        sid = `~${n.factory ?? "?"}#${this._synthSeq++}`;
+      } while (this._byId.has(sid));
+      this._synthIds.set(n, sid);
+    }
+    return sid;
+  }
+  _topologyDeps(deps) {
+    return deps.map((dep) => this._idForTopologyNode(dep));
+  }
+  _emitTopologyNodeRegistered(node) {
+    if (this._topologyObservers.size === 0) return;
+    const entry = this._entries.get(node);
+    if (entry === void 0) return;
+    this._emitTopologyEvent({
+      kind: "node-registered",
+      path: entry.id,
+      factory: entry.factory,
+      deps: this._topologyDeps(node.deps),
+      seq: this._clock++
+    });
+  }
+  _emitTopologyDepsChanged(node, prevDeps, nextDeps) {
+    if (this._topologyObservers.size === 0) return;
+    const entry = this._entries.get(node);
+    if (entry === void 0) return;
+    this._emitTopologyEvent({
+      kind: "deps-changed",
+      path: entry.id,
+      prevDeps: this._topologyDeps(prevDeps),
+      deps: this._topologyDeps(nextDeps),
+      seq: this._clock++
+    });
+  }
+  _emitTopologyNodeReleased(event) {
+    if (this._topologyObservers.size === 0) return;
+    this._emitTopologyEvent({
+      kind: "node-released",
+      path: event.path,
+      factory: event.factory,
+      deps: [...event.deps],
+      seq: this._clock++
+    });
+  }
+  _emitTopologyMountChanged(path) {
+    if (this._topologyObservers.size === 0) return;
+    this._emitTopologyEvent({
+      kind: "mount-changed",
+      path,
+      factory: "mount",
+      deps: [],
+      seq: this._clock++
+    });
+  }
+  _ensureMountedTopologyForwarders() {
+    if (this._topologyObservers.size === 0) return;
+    for (const mount of this._mounts) {
+      if (mount.topologyUnsub !== void 0) continue;
+      const mountPath = mount.at;
+      mount.topologyUnsub = mount.graph.observeTopology().subscribe((event) => {
+        this._emitMountedTopologyEvent(mountPath, event);
+      });
+    }
+  }
+  _releaseMountedTopologyForwarders() {
+    for (const mount of this._mounts) {
+      mount.topologyUnsub?.();
+      mount.topologyUnsub = void 0;
+    }
+  }
+  _emitMountedTopologyEvent(mountPath, event) {
+    if (this._topologyObservers.size === 0) return;
+    this._emitTopologyEvent({
+      kind: event.kind,
+      path: prefixTopologyPath(mountPath, event.path),
+      deps: event.deps.map((dep) => prefixTopologyPath(mountPath, dep)),
+      ...event.prevDeps !== void 0 ? { prevDeps: event.prevDeps.map((dep) => prefixTopologyPath(mountPath, dep)) } : {},
+      ...event.factory !== void 0 ? { factory: event.factory } : {},
+      seq: this._clock++
+    });
+  }
+  _emitTopologyEvent(event) {
+    if (this._topologyDelivering) {
+      this._topologyQueue.push(event);
+      return;
+    }
+    this._topologyDelivering = true;
+    try {
+      let current = event;
+      while (current !== void 0) {
+        const observers = [...this._topologyObservers.entries()];
+        for (const [id, observer] of observers) {
+          if (this._topologyObservers.get(id) !== observer) continue;
+          if (observer.path !== void 0 && !topologyPathMatches(current.path, observer.path))
+            continue;
+          try {
+            observer.sink(cloneTopologyEvent(current));
+          } catch {
+          }
+        }
+        current = this._topologyQueue.shift();
+      }
+    } finally {
+      this._topologyDelivering = false;
+    }
+  }
+  /**
+   * profile() = accumulated-counter snapshot (R-profile / D39). invokes + duration are
+   * dispatcher-backed (the invoke funnel, F-DISPATCH-ALL) — counters never live on the
+   * thin node (R-node-thin). Requires `graph({ profile: true })` (opt-in, F-PERF).
+   */
+  profile() {
+    const nodes = {};
+    let totalInvokes = 0;
+    for (const e of this._entries.values()) {
+      const h = e.node.handle;
+      const stat = h ? this._dispatcher.statFor(h) : void 0;
+      const invokes = stat?.invokes ?? 0;
+      nodes[e.id] = {
+        invokes,
+        totalDurationNs: stat?.totalDurationNs ?? 0,
+        lastDurationNs: stat?.lastDurationNs ?? 0,
+        status: e.node.status
+      };
+      totalInvokes += invokes;
+    }
+    return { totalInvokes, nodes };
+  }
+  /** Versioned graph lifecycle checkpoint (R-snapshot / D83 / D90). Pure capture, no storage I/O. */
+  checkpoint() {
+    return this._checkpoint("", /* @__PURE__ */ new WeakSet());
+  }
+  _checkpoint(_prefix, stack) {
+    if (stack.has(this)) {
+      throw new Error("checkpoint: cyclic graph mount detected");
+    }
+    stack.add(this);
+    const discovered = /* @__PURE__ */ new Map();
+    const localId = (n) => {
+      const e = this._entries.get(n);
+      if (e) return `${_prefix}${e.id}`;
+      let sid = this._synthIds.get(n);
+      if (sid === void 0) {
+        do {
+          sid = `~${n.factory ?? "?"}#${this._synthSeq++}`;
+        } while (this._byId.has(sid));
+        this._synthIds.set(n, sid);
+      }
+      discovered.set(n, sid);
+      return `${_prefix}${sid}`;
+    };
+    const nodes = [];
+    const edges = [];
+    for (const entry of this._entries.values()) {
+      const id = `${_prefix}${entry.id}`;
+      const liveIds = entry.node.deps.map(localId);
+      nodes.push(
+        this._checkpointNode(entry.node, id, {
+          name: entry.name,
+          factory: checkpointFactory(entry.factory, entry.node, false, entry.restore, entry.meta),
+          deps: liveIds,
+          meta: entry.meta
+        })
+      );
+      for (const from of liveIds) edges.push({ from, to: id });
+    }
+    const visited = /* @__PURE__ */ new Set();
+    const queue = [...discovered.keys()];
+    for (let i = 0; i < queue.length; i += 1) {
+      const inner = queue[i];
+      if (visited.has(inner)) continue;
+      visited.add(inner);
+      const sid = discovered.get(inner);
+      if (sid === void 0) continue;
+      const liveIds = inner.deps.map(localId);
+      for (const dep of inner.deps) {
+        if (!this._entries.has(dep) && !visited.has(dep)) queue.push(dep);
+      }
+      const id = `${_prefix}${sid}`;
+      nodes.push(
+        this._checkpointNode(inner, id, {
+          factory: checkpointFactory(inner.factory ?? "?", inner, true),
+          deps: liveIds
+        })
+      );
+      for (const from of liveIds) edges.push({ from, to: id });
+    }
+    const checkpoint = {
+      version: GRAPH_CHECKPOINT_VERSION,
+      nodes,
+      edges
+    };
+    if (this.name !== void 0) checkpoint.name = this.name;
+    if (this._mounts.length > 0) {
+      checkpoint.mounts = this._mounts.map((m) => ({
+        at: m.at,
+        checkpoint: m.graph._checkpoint("", stack)
+      }));
+    }
+    stack.delete(this);
+    return toCheckpointJson(checkpoint, "checkpoint");
+  }
+  _checkpointNode(node, id, opts) {
+    const state = checkpointStateOfNode(node);
+    assertCheckpointQuiescentStatus(node.status, id, "checkpoint");
+    const nonAuthoritativeCollectionHelper = isNonAuthoritativeCollectionHelperMeta(opts.meta);
+    const out = {
+      id,
+      factory: opts.factory,
+      status: node.status,
+      deps: opts.deps,
+      value: nonAuthoritativeCollectionHelper ? { kind: "SENTINEL" } : checkpointValue(state.cache, state.hasData, `${id}.value`),
+      terminal: checkpointTerminal(state.terminal, `${id}.terminal`),
+      lifecycle: { activated: state.activated, hasCalledFnOnce: state.hasCalledFnOnce },
+      ctxState: {
+        persist: state.ctxState.persist,
+        value: nonAuthoritativeCollectionHelper ? { kind: "SENTINEL" } : checkpointValue(
+          state.ctxState.value,
+          state.ctxState.value !== SENTINEL,
+          `${id}.ctxState`
+        )
+      }
+    };
+    if (opts.name !== void 0) out.name = opts.name;
+    const backendState = checkpointBackendStateOfNode(node, `${id}.backendState`);
+    if (backendState !== void 0) out.backendState = backendState;
+    if (state.version !== void 0) out.version = state.version;
+    if (opts.meta !== void 0)
+      out.meta = toCheckpointJson(opts.meta, `${id}.meta`);
+    return out;
+  }
+};
+function isNonAuthoritativeCollectionHelperMeta(meta) {
+  return meta?.kind === "collection_delta" || meta?.kind === "collection_intent" || meta?.kind === "collection_policy_apply" || meta?.kind === "collection_snapshot" || meta?.kind === "collection_snapshot_prep";
+}
+function assertCheckpointQuiescentStatus(status, id, op) {
+  if (status === "pending" || status === "dirty") {
+    throw new Error(
+      `${op}: node '${id}' has non-quiescent status '${status}' that cannot be checkpoint-restored yet`
+    );
+  }
+}
+function topologyPathMatches(eventPath, path) {
+  return eventPath === path || eventPath.startsWith(`${path}::`);
+}
+function prefixTopologyPath(prefix, path) {
+  return `${prefix}::${path}`;
+}
+function cloneTopologyEvent(event) {
+  const deps = Object.freeze([...event.deps]);
+  const prevDeps = event.prevDeps === void 0 ? void 0 : Object.freeze([...event.prevDeps]);
+  return Object.freeze({
+    kind: event.kind,
+    path: event.path,
+    deps,
+    ...prevDeps !== void 0 ? { prevDeps } : {},
+    ...event.factory !== void 0 ? { factory: event.factory } : {},
+    seq: event.seq
+  });
+}
+function checkpointFactory(name, node, unregistered, restore, meta) {
+  const state = checkpointStateOfNode(node);
+  if (unregistered) {
+    return {
+      kind: "local-only",
+      name,
+      reason: "node is an unregistered live dependency auto-discovered from topology"
+    };
+  }
+  if (restore === void 0 && typeof meta?.kind === "string" && meta.kind.startsWith("collection_")) {
+    return {
+      kind: "local-only",
+      name,
+      reason: "collection helper node has no backend checkpoint restore metadata"
+    };
+  }
+  if (restore !== void 0) {
+    const out = {
+      kind: "registry-ref",
+      ref: toCheckpointJson(restore.ref, `${name}.factory.ref`)
+    };
+    if (restore.config !== void 0)
+      out.config = toCheckpointJson(restore.config, `${name}.factory.config`);
+    if (restore.configVersion !== void 0)
+      out.configVersion = toCheckpointJson(restore.configVersion, `${name}.factory.configVersion`);
+    return out;
+  }
+  if (state.handle !== null) {
+    return {
+      kind: "local-only",
+      name,
+      reason: "node uses a function body; first-cut checkpoints do not serialize local functions"
+    };
+  }
+  return { kind: "registry-ref", ref: name };
+}
+function explainSubset(snap, chain) {
+  const fwd = /* @__PURE__ */ new Map();
+  const rev = /* @__PURE__ */ new Map();
+  const push = (map, k, v) => {
+    const a = map.get(k);
+    if (a) a.push(v);
+    else map.set(k, [v]);
+  };
+  for (const e of snap.edges) {
+    push(fwd, e.from, e.to);
+    push(rev, e.to, e.from);
+  }
+  const reach = (start, adj) => {
+    const seen = /* @__PURE__ */ new Set([start]);
+    const stack = [start];
+    while (stack.length > 0) {
+      const cur = stack.pop();
+      for (const nxt of adj.get(cur) ?? []) {
+        if (!seen.has(nxt)) {
+          seen.add(nxt);
+          stack.push(nxt);
+        }
+      }
+    }
+    return seen;
+  };
+  const onPath = new Set([...reach(chain.from, fwd)].filter((id) => reach(chain.to, rev).has(id)));
+  return {
+    ...snap.name !== void 0 ? { name: snap.name } : {},
+    nodes: snap.nodes.filter((n) => onPath.has(n.id)),
+    edges: snap.edges.filter((e) => onPath.has(e.from) && onPath.has(e.to))
+  };
+}
+function graph(opts = {}) {
+  return new Graph(opts);
+}
+function releaseGraphNodes(graph2, nodes, opts = {}) {
+  const registrar = lifecycleRegistrars.get(graph2);
+  if (registrar === void 0) throw new Error("graph: unknown lifecycle registrar");
+  registrar.releaseNodes(nodes, opts);
+}
+function restoreStateNodeInGraph(graph2, id, opts = {}) {
+  const registrar = restoreRegistrars.get(graph2);
+  if (registrar === void 0) throw new Error("restoreGraph: unknown graph restore registrar");
+  return registrar.stateNode(id, opts);
+}
+function restoreNodeInGraph(graph2, id, factory, deps, fn, opts = {}) {
+  const registrar = restoreRegistrars.get(graph2);
+  if (registrar === void 0) throw new Error("restoreGraph: unknown graph restore registrar");
+  return registrar.node(id, factory, deps, fn, opts);
+}
+
+export {
+  GRAPH_BLUEPRINT_VERSION,
+  normalizeTopology,
+  canonicalTopologyJson,
+  canonicalTopologyBytes,
+  withBlueprintHash,
+  withBlueprintProvenance,
+  graphBlueprintDiagnostics,
+  assertGraphLocalNode,
+  StateNode,
+  Graph,
+  graph,
+  releaseGraphNodes,
+  restoreStateNodeInGraph,
+  restoreNodeInGraph
+};
+//# sourceMappingURL=chunk-2ILL7HQI.js.map