@smthrs/flow 0.0.0-stage → 1.0.0-rc.12

package/dist/cjs/Graph.js

@@ -0,0 +1,1020 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Graph_exports = {};
+__export(Graph_exports, {
+  build: () => build,
+  diagnostics: () => diagnostics,
+  drafts: () => drafts,
+  edges: () => edges,
+  evaluatedFrom: () => evaluatedFrom,
+  inspect: () => inspect,
+  maximumGraphDepth: () => maximumGraphDepth,
+  nodes: () => nodes
+});
+module.exports = __toCommonJS(Graph_exports);
+var Capability = __toESM(require("@smthrs/capability/Capability"), 1);
+var Effects = __toESM(require("@smthrs/plan/Effects"), 1);
+var import_GraphBuildError = require("@smthrs/plan/GraphBuildError");
+var KeyMaterial = __toESM(require("@smthrs/plan/KeyMaterial"), 1);
+var Node = __toESM(require("@smthrs/plan/Node"), 1);
+var Planned = __toESM(require("@smthrs/plan/Planned"), 1);
+var Context = __toESM(require("effect/Context"), 1);
+var Option = __toESM(require("effect/Option"), 1);
+var Predicate = __toESM(require("effect/Predicate"), 1);
+var import_TypeId = require("./Action/TypeId.js");
+var Annotations = __toESM(require("./Flow/Annotations.js"), 1);
+var import_CapabilityCeiling = require("./Flow/CapabilityCeiling.js");
+var import_TypeId2 = require("./Flow/TypeId.js");
+var DeclarationSite = __toESM(require("./internal/DeclarationSite.js"), 1);
+var import_OutcomeMarker = require("./internal/OutcomeMarker.js");
+const emptyEffects = { reads: [], writes: [], boundaryMode: "expected" };
+const sorted = (values) => [...new Set(values)].sort();
+const flowDeclaration = (value) => Predicate.hasProperty(value, import_TypeId2.TypeId) ? value : void 0;
+const actionDeclaration = (value) => Predicate.hasProperty(value, import_TypeId.TypeId) ? value : void 0;
+const declaredEffects = (annotations) => Option.getOrUndefined(Context.getOption(annotations, Annotations.EffectsDeclaration));
+const declaredPlacement = (annotations) => Option.getOrUndefined(Context.getOption(annotations, Annotations.Placement));
+const declaredEnvelope = (annotations) => Option.getOrUndefined(Context.getOption(annotations, Annotations.EffectEnvelope));
+const refusalMessage = (narrowed, site) => {
+  const at = `"${site.flow}" at "${site.id}"`;
+  switch (narrowed.code) {
+    case "effect_outside_envelope":
+      return `Flow ${at} declares ${narrowed.paths.length === 1 ? "a path" : "paths"} its caller's effect envelope does not cover: ${narrowed.paths.join(", ")}. Widen the caller's declared effects to cover them, or narrow this declaration to what the envelope already allows.`;
+    case "effect_mode_widening":
+      return `Flow ${at} declares an expected effect mode inside a hermetic envelope. A hermetic envelope is the claim that every effect beneath it is declared, so the callee has to declare a hermetic mode too.`;
+    case "effect_tier_widening":
+      return `Flow ${at} declares an effect tier its caller's envelope does not permit. A tier may only narrow from irreversible to compensable to sealed, so raise the caller's tier or lower this one.`;
+  }
+};
+const schemaIdentity = (schema) => {
+  const cached = schemaDocuments.get(schema);
+  if (cached !== void 0) return cached;
+  const document = Node.schemaIdentity(schema, { onExcessProperty: "error" });
+  schemaDocuments.set(schema, document);
+  return document;
+};
+const schemaDocuments = /* @__PURE__ */ new WeakMap();
+const isPlainObject = (value) => typeof value === "object" && value !== null && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+const referenceOf = (value) => {
+  const live = Planned.reference(value);
+  if (live !== void 0) return live;
+  return Node.plannedReference(value);
+};
+const outcomeTagOf = (ast) => {
+  const descriptor = Object.getOwnPropertyDescriptor(ast, import_OutcomeMarker.OutcomeNodeTypeId);
+  if (descriptor === void 0 || !("value" in descriptor)) return void 0;
+  const value = descriptor.value;
+  return value === "Done" || value === "To" || value === "Park" ? value : void 0;
+};
+const placeholder = (reference, node) => reference.path.reduce(
+  (value, key) => value[key],
+  Planned.make(node)
+);
+const maximumGraphDepth = 1e3;
+const maximumPayloadDepth = 1e3;
+const container = (value, at) => {
+  if (Array.isArray(value)) return value;
+  if (typeof value !== "object" || value === null) return void 0;
+  try {
+    return isPlainObject(value) ? value : void 0;
+  } catch {
+    throw new import_GraphBuildError.GraphBuildError({
+      code: "invalid_payload",
+      node: at,
+      path: [],
+      message: `Payload at "${at}" does not expose an inert object prototype.`
+    });
+  }
+};
+const walkPayload = (root, walk) => {
+  const resolvedRoot = walk.resolve(root);
+  if (resolvedRoot !== void 0) return resolvedRoot.value;
+  const rootContainer = container(root, walk.at);
+  if (rootContainer === void 0) return root;
+  const open = (source) => {
+    const descriptors = (() => {
+      try {
+        return Object.getOwnPropertyDescriptors(source);
+      } catch {
+        throw new import_GraphBuildError.GraphBuildError({
+          code: "invalid_payload",
+          node: walk.at,
+          path: [],
+          message: `Payload at "${walk.at}" does not expose inert own properties.`
+        });
+      }
+    })();
+    if (Array.isArray(source)) {
+      const members2 = Array.from({ length: source.length }, (_, index) => {
+        const descriptor = descriptors[String(index)];
+        if (descriptor === void 0) return void 0;
+        if (!("value" in descriptor)) {
+          throw new import_GraphBuildError.GraphBuildError({
+            code: "invalid_payload",
+            node: walk.at,
+            path: [String(index)],
+            message: `Payload at "${walk.at}" contains an accessor at index ${index}. Pass inert data.`
+          });
+        }
+        return descriptor.value;
+      });
+      return { source, keys: void 0, members: members2, output: [], index: 0 };
+    }
+    const keys = walk.keysOf(
+      Object.keys(descriptors).filter((key) => descriptors[key]?.enumerable === true)
+    );
+    const members = keys.map((key) => {
+      const descriptor = descriptors[key];
+      if (!("value" in descriptor)) {
+        throw new import_GraphBuildError.GraphBuildError({
+          code: "invalid_payload",
+          node: walk.at,
+          path: [key],
+          message: `Payload at "${walk.at}" contains accessor property "${key}". Pass inert data.`
+        });
+      }
+      return descriptor.value;
+    });
+    return {
+      source,
+      keys,
+      members,
+      output: /* @__PURE__ */ Object.create(null),
+      index: 0
+    };
+  };
+  const rootFrame = open(rootContainer);
+  const frames = [rootFrame];
+  const ancestors = /* @__PURE__ */ new Set([rootContainer]);
+  while (frames.length > 0) {
+    const frame = frames[frames.length - 1];
+    if (frame.index >= frame.members.length) {
+      frames.pop();
+      ancestors.delete(frame.source);
+      continue;
+    }
+    const position = frame.index;
+    frame.index = position + 1;
+    const key = frame.keys?.[position];
+    const member = frame.members[position];
+    const place = (produced) => {
+      if (key === void 0) {
+        const members = frame.output;
+        members.push(produced);
+        return;
+      }
+      Object.defineProperty(frame.output, key, {
+        configurable: true,
+        enumerable: true,
+        value: produced,
+        writable: true
+      });
+    };
+    const resolved = walk.resolve(member);
+    if (resolved !== void 0) {
+      place(resolved.value);
+      continue;
+    }
+    const nested = container(member, walk.at);
+    if (nested === void 0) {
+      place(member);
+      continue;
+    }
+    if (ancestors.has(nested)) {
+      throw new import_GraphBuildError.GraphBuildError({
+        code: "cyclic_payload",
+        node: walk.at,
+        path: [],
+        message: `Payload at "${walk.at}" contains itself, so no plan can hash or serialize it. Pass acyclic data.`
+      });
+    }
+    if (frames.length >= maximumPayloadDepth) {
+      throw new import_GraphBuildError.GraphBuildError({
+        code: "payload_too_deep",
+        node: walk.at,
+        path: [],
+        message: `Payload at "${walk.at}" nests more than ${maximumPayloadDepth} levels deep. Flatten the payload: a plan hashes and stores every level of it.`
+      });
+    }
+    const opened = open(nested);
+    place(opened.output);
+    ancestors.add(nested);
+    frames.push(opened);
+  }
+  return rootFrame.output;
+};
+const hydrate = (value, substitutions, at) => walkPayload(value, {
+  at,
+  keysOf: (keys) => keys,
+  resolve: (member) => {
+    const reference = referenceOf(member);
+    return reference === void 0 ? void 0 : { value: placeholder(reference, substitutions.get(reference.node) ?? reference.node) };
+  }
+});
+const literal = (value, found, at) => walkPayload(value, {
+  at,
+  keysOf: (keys) => [...keys].sort(),
+  resolve: (member) => {
+    const reference = Planned.reference(member);
+    if (reference === void 0) return void 0;
+    found.push(reference);
+    return { value: { _tag: "PlannedInput", path: [...reference.path] } };
+  }
+});
+const structuralIdentity = (left, right) => {
+  const pending = [[left, right]];
+  const visited = /* @__PURE__ */ new WeakMap();
+  let examined = 0;
+  try {
+    while (pending.length > 0) {
+      const [left2, right2] = pending.pop();
+      if (++examined > maxComparisonPairs) return false;
+      if (Object.is(left2, right2)) continue;
+      if (left2 !== Object(left2)) return false;
+      if (right2 !== Object(right2)) return false;
+      const leftObject = left2;
+      const rightObject = right2;
+      const leftIsArray = Array.isArray(leftObject);
+      if (leftIsArray !== Array.isArray(rightObject)) return false;
+      if (leftIsArray && leftObject.length !== rightObject.length) {
+        return false;
+      }
+      const seen = visited.get(leftObject) ?? /* @__PURE__ */ new WeakSet();
+      if (seen.has(rightObject)) continue;
+      seen.add(rightObject);
+      visited.set(leftObject, seen);
+      if (!leftIsArray && !(isPlainObject(leftObject) && isPlainObject(rightObject))) return false;
+      const leftKeys = Reflect.ownKeys(leftObject).filter(
+        (key) => Object.prototype.propertyIsEnumerable.call(leftObject, key)
+      );
+      const rightKeys = Reflect.ownKeys(rightObject).filter(
+        (key) => Object.prototype.propertyIsEnumerable.call(rightObject, key)
+      );
+      if (leftKeys.length !== rightKeys.length) return false;
+      for (const key of leftKeys) {
+        if (!Object.prototype.propertyIsEnumerable.call(rightObject, key)) return false;
+        const leftMember = Object.getOwnPropertyDescriptor(leftObject, key);
+        const rightMember = Object.getOwnPropertyDescriptor(rightObject, key);
+        if (!("value" in leftMember) || !("value" in rightMember)) return false;
+        pending.push([leftMember.value, rightMember.value]);
+      }
+    }
+  } catch {
+    return false;
+  }
+  return true;
+};
+const maxComparisonPairs = 1e5;
+const placementConflicts = (enclosing, callee) => enclosing !== void 0 && callee !== void 0 && !structuralIdentity(enclosing, callee);
+const maxPlacementChars = 240;
+const maxPlacementDepth = 4;
+const maxPlacementMembers = 32;
+const renderPlacement = (value) => {
+  const render = (value2, depth, seen) => {
+    if (typeof value2 === "string") return JSON.stringify(value2);
+    if (typeof value2 === "bigint") return `${value2}n`;
+    if (Object(value2) !== value2) return String(value2);
+    const object = value2;
+    if (seen.includes(object)) return "<cycle>";
+    if (depth === maxPlacementDepth) return "<elided>";
+    const nested = [...seen, object];
+    if (Array.isArray(object)) {
+      const length = object.length;
+      const shown2 = Math.min(length, maxPlacementMembers);
+      const members2 = [];
+      for (let index = 0; index < shown2; index++) {
+        const member = Object.getOwnPropertyDescriptor(object, String(index));
+        members2.push(
+          member === void 0 ? "<hole>" : "value" in member ? render(member.value, depth + 1, nested) : "<accessor>"
+        );
+      }
+      if (length > shown2) members2.push("<more>");
+      return `[${members2.join(",")}]`;
+    }
+    if (!isPlainObject(object)) return Object.prototype.toString.call(object);
+    const keys = Reflect.ownKeys(object).filter((key) => Object.prototype.propertyIsEnumerable.call(object, key)).sort((left, right) => String(left).localeCompare(String(right)));
+    const members = keys.slice(0, maxPlacementMembers).map((key) => {
+      const member = Object.getOwnPropertyDescriptor(object, key);
+      const rendered = "value" in member ? render(member.value, depth + 1, nested) : "<accessor>";
+      return `${String(key)}:${rendered}`;
+    }).sort();
+    const shown = keys.length > maxPlacementMembers ? [...members, "<more>"] : members;
+    return `{${shown.join(",")}}`;
+  };
+  try {
+    const rendered = render(value, 0, []);
+    return rendered.length <= maxPlacementChars ? rendered : `${rendered.slice(0, maxPlacementChars)} [${rendered.length - maxPlacementChars} characters dropped]`;
+  } catch {
+    return "<unrenderable>";
+  }
+};
+const payloadInputs = (payload, at) => {
+  const found = [];
+  const inputs = [{ _tag: "Literal", value: literal(payload, found, at) }];
+  const seen = /* @__PURE__ */ new Set();
+  for (const reference of found) {
+    const identity = JSON.stringify([reference.node, ...reference.path]);
+    if (seen.has(identity)) continue;
+    seen.add(identity);
+    inputs.push({ _tag: "Ref", from: reference.node, path: [...reference.path] });
+  }
+  return inputs;
+};
+const build = (flowOrNode, payload, options = {}) => {
+  const observed = [];
+  const observedIds = /* @__PURE__ */ new Set();
+  const observedEdges = [];
+  const observedDiagnostics = [];
+  const observeIdentity = (node, field, identity) => {
+    if (options.callbackIdentity !== "stable" || identity !== void 0 && identity.algorithm !== "sha256-source-ephemeral/v4") return;
+    observedDiagnostics.push(
+      new import_GraphBuildError.GraphBuildError({
+        code: "unstable_callback",
+        node,
+        path: [field],
+        message: `Callback ${field} at "${node}" has ${identity === void 0 ? "unavailable" : "process-local"} identity and cannot enter a stable graph. Use Node.capture with every semantic capture, including the version of imported implementation behavior.`
+      })
+    );
+  };
+  const operations = [];
+  const sequence = (steps) => {
+    for (let index = steps.length - 1; index >= 0; index--) operations.push(steps[index]);
+  };
+  const record = (entry) => {
+    if (observedIds.has(entry.id)) {
+      throw new import_GraphBuildError.GraphBuildError({
+        code: "duplicate_node",
+        node: entry.id,
+        path: [],
+        message: `Node id "${entry.id}" is durable dispatch identity, so two nodes may not share one. Two structural addresses in this graph collided, most often because a Node.all member name contains the separator a nested address also produces. Rename one of them.`
+      });
+    }
+    observedIds.add(entry.id);
+    const material = {
+      version: KeyMaterial.version,
+      kind: entry.tier,
+      body: entry.capabilityCeilings?.length ? { ...entry.body, capabilityCeilings: entry.capabilityCeilings } : entry.body,
+      inputs: entry.inputs,
+      layers: sorted(
+        options.resolveLayers?.({
+          nodeId: entry.id,
+          kind: entry.kind,
+          capabilities: entry.capabilities,
+          effects: entry.effects,
+          placement: entry.placement
+        }) ?? []
+      ),
+      capabilities: entry.capabilities,
+      ...entry.nondeterministic === void 0 ? {} : { nondeterministic: entry.nondeterministic },
+      ...entry.effects === void 0 ? {} : { effects: entry.effects },
+      ...entry.placement === void 0 ? {} : { placement: entry.placement }
+    };
+    observed.push({
+      id: entry.id,
+      kind: entry.kind,
+      dependencies: entry.dependencies,
+      capabilities: entry.capabilities,
+      capabilityCeilings: entry.capabilityCeilings ?? [],
+      placement: entry.placement,
+      // Priority reaches the compiled plan through the draft and stays OUT of
+      // `material`: it orders ready work without changing what the work
+      // produces, so raising it must not re-key a step.
+      draft: {
+        id: entry.id,
+        material,
+        effects: entry.effects ?? emptyEffects,
+        ...entry.priority === void 0 ? {} : { priority: entry.priority }
+      },
+      ast: entry.ast,
+      payload: entry.payload,
+      ...entry.declaredAt === void 0 ? {} : { declaredAt: entry.declaredAt }
+    });
+  };
+  const preparedEnvelopes = /* @__PURE__ */ new Map();
+  const admitEnvelope = (enclosing, declared, site) => {
+    if (declared === void 0) return enclosing;
+    if (enclosing === void 0) return declared;
+    let prepared = preparedEnvelopes.get(enclosing);
+    if (prepared === void 0) {
+      prepared = Effects.prepareEnvelope(enclosing);
+      preparedEnvelopes.set(enclosing, prepared);
+    }
+    const narrowed = Effects.narrowPrepared(prepared, declared);
+    if (narrowed.ok) return declared;
+    observedDiagnostics.push(
+      new import_GraphBuildError.GraphBuildError({
+        code: narrowed.code,
+        node: site.id,
+        path: [...narrowed.paths],
+        message: refusalMessage(narrowed, site)
+      })
+    );
+    return enclosing;
+  };
+  const coveredCapability = (stack, text) => {
+    const groups = stack.flatMap((flow) => (0, import_CapabilityCeiling.capabilityCeilings)(flow.annotations));
+    if (groups.length === 0) return true;
+    const candidate = Capability.parsePattern(text);
+    if (Option.isNone(candidate)) return false;
+    return groups.every(
+      (group) => group.some((text2) => {
+        const grant = Capability.parsePattern(text2);
+        return Option.isSome(grant) && Capability.subsumes(grant.value, candidate.value);
+      })
+    );
+  };
+  const expandFlowCall = (call) => {
+    const annotations = call.declaration?.annotations ?? Context.empty();
+    const dependencies = call.dependencies;
+    const inputs = [...payloadInputs(call.payload, call.id), ...call.inputs];
+    const target = call.mode === "inline" ? call.declaration : void 0;
+    const ceiling = sorted((0, import_CapabilityCeiling.capabilityCeilings)(annotations)[0] ?? call.capabilities);
+    const placement = declaredPlacement(annotations);
+    const envelope = declaredEnvelope(annotations);
+    const calleeEnvelope = admitEnvelope(call.envelope, envelope, { id: call.id, flow: call.flow });
+    const dropped = ceiling.filter((capability) => !coveredCapability(call.stack, capability));
+    if (dropped.length > 0) {
+      observedDiagnostics.push(
+        new import_GraphBuildError.GraphBuildError({
+          code: "capability_outside_grant",
+          node: call.id,
+          path: dropped,
+          message: `Flow "${call.flow}" at "${call.id}" requires ${dropped.join(", ")}, which the calling flow does not provably grant. Execution intersects this declaration with every caller ceiling.`
+        })
+      );
+    }
+    if (call.mode === "inline" && placementConflicts(call.placement, placement)) {
+      throw new import_GraphBuildError.GraphBuildError({
+        code: "placement_requires_boundary",
+        node: call.id,
+        path: [],
+        message: `Flow "${call.flow}" is called inline at "${call.id}", but its declared placement ${renderPlacement(placement)} is not structurally identical to the enclosing flow's ${renderPlacement(call.placement)}. An inline .call() runs in the caller's execution, so use ${call.flow}.child(payload) to give it its own.`
+      });
+    }
+    const recordCall = () => {
+      const bodyIdentity = call.declaration === void 0 ? void 0 : Node.functionIdentity(call.declaration.body);
+      observeIdentity(call.id, "body", bodyIdentity);
+      record({
+        id: call.id,
+        kind: "FlowCall",
+        dependencies,
+        capabilities: call.capabilities,
+        capabilityCeilings: [
+          ...call.stack.flatMap((flow) => (0, import_CapabilityCeiling.capabilityCeilings)(flow.annotations)),
+          ...(0, import_CapabilityCeiling.capabilityCeilings)(annotations)
+        ],
+        effects: declaredEffects(annotations),
+        placement,
+        priority: call.priority,
+        // A declared envelope states how reversible the flow beneath it is, so
+        // it is the call's tier. A flow that declared none keeps the sealed
+        // default every call has always carried, which is what keeps every
+        // existing flow's key exactly where it was.
+        tier: envelope?.tier ?? "sealed",
+        body: {
+          _tag: "FlowCall",
+          flow: call.flow,
+          mode: call.mode,
+          declaration: call.declaration === void 0 ? void 0 : {
+            payload: schemaIdentity(call.declaration.payloadSchema),
+            success: schemaIdentity(call.declaration.successSchema),
+            error: schemaIdentity(call.declaration.errorSchema),
+            capabilities: ceiling,
+            // A spliced body re-keys this call through the `Ref` on the node it
+            // produced. A call the graph keeps as a LEAF — an explicit boundary,
+            // a handoff — has no such node, and its own digest is the only thing
+            // an edited body can move.
+            body: bodyIdentity
+          }
+        },
+        inputs,
+        ast: call.ast,
+        payload: call.payload,
+        declaredAt: DeclarationSite.declaredAt(call.declaration)
+      });
+    };
+    if (target === void 0) {
+      recordCall();
+      return;
+    }
+    if (call.stack.includes(target)) {
+      throw new import_GraphBuildError.GraphBuildError({
+        code: "recursion_requires_boundary",
+        node: call.id,
+        path: [],
+        message: `Flow "${call.flow}" cannot call itself inline at "${call.id}". Use ${call.flow}.to(payload) to hand off to the next round, or .child(payload) for an explicit boundary.`
+      });
+    }
+    const built = target.body(call.payload);
+    const spliced = `${call.id}.flow`;
+    sequence([
+      () => expand({
+        ast: built.ast,
+        id: spliced,
+        depth: call.depth + 1,
+        capabilities: ceiling.filter((capability) => coveredCapability(call.stack, capability)),
+        // Inside the spliced body the callee's own placement is the one to
+        // satisfy; a callee that declared none keeps running under the
+        // caller's.
+        placement: placement ?? call.placement,
+        envelope: calleeEnvelope,
+        priority: call.priority,
+        substitutions: call.substitutions,
+        stack: [...call.stack, target],
+        prerequisite: void 0,
+        barriers: call.barriers
+      }),
+      () => {
+        dependencies.push(spliced);
+        observedEdges.push({ from: spliced, to: call.id, reason: "value" });
+        inputs.push({ _tag: "Ref", from: spliced, path: [] });
+      },
+      recordCall
+    ]);
+  };
+  const continuation = (ast, id, subject) => {
+    const builder = Node.continuation(ast);
+    if (builder === void 0) {
+      observedDiagnostics.push(
+        new import_GraphBuildError.GraphBuildError({
+          code: "invalid_continuation",
+          node: id,
+          path: [],
+          message: `Node.bindPlanned at "${id}" no longer holds its continuation builder, so its continuation is missing from the graph. An AST that crossed a serialization boundary left that side table behind.`
+        })
+      );
+      return void 0;
+    }
+    const built = builder(Planned.make(subject));
+    if (Node.isNode(built)) return built.ast;
+    observedDiagnostics.push(
+      new import_GraphBuildError.GraphBuildError({
+        code: "invalid_continuation",
+        node: id,
+        path: [],
+        message: `Node.bindPlanned at "${id}" did not produce a Node, so its continuation is missing from the graph.`
+      })
+    );
+    return void 0;
+  };
+  const expand = (request) => {
+    if (request.depth > maximumGraphDepth) {
+      throw new import_GraphBuildError.GraphBuildError({
+        code: "graph_too_deep",
+        node: request.id,
+        path: [],
+        message: `The graph nests more than ${maximumGraphDepth} levels deep. Split the flow with .child() boundaries or trampoline handoffs so one execution plans a bounded graph.`
+      });
+    }
+    const { ast, capabilities, depth, envelope, id, placement, stack, substitutions } = request;
+    const priority = ast.priority ?? request.priority;
+    const dependencies = [];
+    const inputs = [];
+    const depend = (from, reason) => {
+      dependencies.push(from);
+      observedEdges.push({ from, to: id, reason });
+      inputs.push(reason === "continuation" ? { _tag: "Pending", from } : { _tag: "Ref", from, path: [] });
+    };
+    const child = (childAst, childId, options2 = {}) => ({
+      ast: childAst,
+      id: childId,
+      depth: depth + 1,
+      capabilities,
+      placement,
+      envelope,
+      priority,
+      substitutions: options2.substitutions ?? substitutions,
+      stack,
+      prerequisite: options2.prerequisite,
+      barriers: options2.barriers ?? request.barriers
+    });
+    if (request.prerequisite !== void 0) depend(request.prerequisite, "continuation");
+    for (const barrier of request.barriers) {
+      if (barrier !== request.prerequisite) depend(barrier, "continuation");
+    }
+    switch (ast._tag) {
+      case "FlowCall": {
+        expandFlowCall({
+          id,
+          depth,
+          ast,
+          flow: ast.flow,
+          mode: ast.mode,
+          declaration: flowDeclaration(Node.declaration(ast)),
+          payload: hydrate(ast.payload, substitutions, id),
+          capabilities,
+          placement,
+          envelope,
+          priority,
+          substitutions,
+          stack,
+          barriers: request.barriers,
+          dependencies,
+          inputs
+        });
+        return;
+      }
+      case "ActionCall": {
+        const declared = actionDeclaration(Node.declaration(ast));
+        const annotations = declared?.annotations ?? Context.empty();
+        const payload2 = hydrate(ast.payload, substitutions, id);
+        admitEnvelope(envelope, declaredEnvelope(annotations), { id, flow: ast.action });
+        const ceiling = sorted(Context.get(annotations, Annotations.Capabilities));
+        const dropped = ceiling.filter((capability) => !coveredCapability(stack, capability));
+        if (dropped.length > 0) {
+          observedDiagnostics.push(
+            new import_GraphBuildError.GraphBuildError({
+              code: "capability_outside_grant",
+              node: id,
+              path: dropped,
+              message: `Action "${ast.action}" at "${id}" requires ${dropped.join(", ")}, which the calling flow does not provably grant. Execution intersects this declaration with every caller ceiling.`
+            })
+          );
+        }
+        record({
+          id,
+          kind: ast._tag,
+          dependencies,
+          capabilities,
+          capabilityCeilings: [
+            ...stack.flatMap((flow) => (0, import_CapabilityCeiling.capabilityCeilings)(flow.annotations)),
+            ...(0, import_CapabilityCeiling.capabilityCeilings)(annotations)
+          ],
+          effects: declaredEffects(annotations),
+          placement: declaredPlacement(annotations),
+          priority,
+          tier: declared?.tier ?? "sealed",
+          nondeterministic: declared?.nondeterministic,
+          body: {
+            _tag: "ActionCall",
+            action: ast.action,
+            tier: declared?.tier ?? "sealed",
+            declaration: declared === void 0 ? void 0 : {
+              payload: schemaIdentity(declared.payloadSchema),
+              success: schemaIdentity(declared.successSchema),
+              error: schemaIdentity(declared.errorSchema),
+              ...ceiling.length === 0 ? {} : { capabilities: ceiling },
+              ...declared.implementationVersion === void 0 ? {} : { implementationVersion: declared.implementationVersion }
+            }
+          },
+          inputs: [...payloadInputs(payload2, id), ...inputs],
+          ast,
+          payload: payload2,
+          declaredAt: DeclarationSite.declaredAt(declared)
+        });
+        return;
+      }
+      case "Succeed": {
+        const value = hydrate(ast.value, substitutions, id);
+        const outcome = outcomeTagOf(ast);
+        if (outcome !== void 0) {
+          const tag = typeof value === "object" && value !== null ? Object.getOwnPropertyDescriptor(value, "_tag") : void 0;
+          if (tag === void 0 || !("value" in tag) || tag.value !== outcome) {
+            throw new import_GraphBuildError.GraphBuildError({
+              code: "invalid_payload",
+              node: id,
+              path: [],
+              message: `Flow outcome node at "${id}" lost its ${outcome} payload.`
+            });
+          }
+          Object.defineProperty(value, import_OutcomeMarker.OutcomeValueTypeId, {
+            configurable: false,
+            enumerable: false,
+            value: outcome,
+            writable: false
+          });
+        }
+        record({
+          id,
+          kind: ast._tag,
+          dependencies,
+          capabilities,
+          effects: void 0,
+          placement: void 0,
+          priority,
+          tier: "sealed",
+          body: outcome === void 0 ? { _tag: ast._tag } : { _tag: ast._tag, outcome },
+          inputs: [...payloadInputs(value, id), ...inputs],
+          ast,
+          payload: value
+        });
+        return;
+      }
+      case "Fail": {
+        const error = hydrate(ast.error, substitutions, id);
+        record({
+          id,
+          kind: ast._tag,
+          dependencies,
+          capabilities,
+          effects: void 0,
+          placement: void 0,
+          priority,
+          tier: "sealed",
+          body: { _tag: ast._tag },
+          inputs: [...payloadInputs(error, id), ...inputs],
+          ast,
+          payload: error
+        });
+        return;
+      }
+      case "All": {
+        const members = Object.keys(ast.nodes);
+        const steps = [];
+        for (const member of members) {
+          const memberId = `${id}.all.${member}`;
+          steps.push(() => expand(child(ast.nodes[member], memberId)));
+          steps.push(() => depend(memberId, "value"));
+        }
+        steps.push(
+          () => record({
+            id,
+            kind: ast._tag,
+            dependencies,
+            capabilities,
+            effects: void 0,
+            placement: void 0,
+            priority,
+            tier: "sealed",
+            body: { _tag: ast._tag, members },
+            inputs,
+            ast,
+            payload: void 0
+          })
+        );
+        sequence(steps);
+        return;
+      }
+      case "Race": {
+        const members = Object.keys(ast.nodes);
+        const steps = [];
+        for (const member of members) {
+          const memberId = `${id}.race.${member}`;
+          steps.push(() => expand(child(ast.nodes[member], memberId)));
+          steps.push(() => depend(memberId, "value"));
+        }
+        steps.push(
+          () => record({
+            id,
+            kind: ast._tag,
+            dependencies,
+            capabilities,
+            effects: void 0,
+            placement: void 0,
+            priority,
+            tier: "sealed",
+            body: { _tag: ast._tag, mode: ast.mode, count: ast.count, members },
+            inputs,
+            ast,
+            payload: void 0
+          })
+        );
+        sequence(steps);
+        return;
+      }
+      case "Map": {
+        observeIdentity(id, "mapper", ast.mapper);
+        const first = `${id}.map`;
+        sequence([
+          () => expand(child(ast.first, first)),
+          () => depend(first, "value"),
+          () => record({
+            id,
+            kind: ast._tag,
+            dependencies,
+            capabilities,
+            effects: void 0,
+            placement: void 0,
+            priority,
+            tier: "sealed",
+            body: { _tag: ast._tag, mapper: ast.mapper },
+            inputs,
+            ast,
+            payload: void 0
+          })
+        ]);
+        return;
+      }
+      case "AndThen": {
+        observeIdentity(id, "continuation", ast.continuation);
+        const first = `${id}.andThen`;
+        sequence([
+          () => expand(child(ast.first, first)),
+          () => depend(first, "value"),
+          () => {
+            const next = ast.next ?? continuation(ast, id, first);
+            if (next === void 0) return;
+            const thenId = `${id}.then`;
+            sequence([
+              () => expand(child(next, thenId, {
+                prerequisite: first,
+                // Explicit andThen sequences every descendant, not only the
+                // result/join node. bindPlanned remains a dependency builder:
+                // independent members can run while a referenced producer runs.
+                // The first subtree already carries the outer barriers, so
+                // its success transitively gates every nested descendant.
+                barriers: ast.next === void 0 ? request.barriers : [first]
+              })),
+              () => depend(thenId, "value")
+            ]);
+          },
+          () => record({
+            id,
+            kind: ast._tag,
+            dependencies,
+            capabilities,
+            effects: void 0,
+            placement: void 0,
+            priority,
+            tier: "sealed",
+            body: { _tag: ast._tag, continuation: ast.continuation, static: ast.next !== void 0 },
+            inputs,
+            ast,
+            payload: void 0
+          })
+        ]);
+        return;
+      }
+      case "Branch": {
+        observeIdentity(id, "predicate", ast.predicate);
+        const first = `${id}.branch`;
+        const arms = new Map([...substitutions, [ast.subject, first]]);
+        sequence([
+          () => expand(child(ast.first, first)),
+          () => depend(first, "value"),
+          () => expand(child(ast.then, `${id}.then`, { substitutions: arms, prerequisite: first })),
+          () => depend(`${id}.then`, "value"),
+          () => expand(child(ast.else, `${id}.else`, { substitutions: arms, prerequisite: first })),
+          () => depend(`${id}.else`, "value"),
+          () => record({
+            id,
+            kind: ast._tag,
+            dependencies,
+            capabilities,
+            effects: void 0,
+            placement: void 0,
+            priority,
+            tier: "sealed",
+            body: { _tag: ast._tag, predicate: ast.predicate },
+            inputs,
+            ast,
+            payload: void 0
+          })
+        ]);
+        return;
+      }
+      case "Catch": {
+        if (ast.filter !== void 0) observeIdentity(id, "filter", ast.filterIdentity);
+        const protectedId = `${id}.protected`;
+        const failureId = `${id}.failure`;
+        const recovery = new Map([...substitutions, [ast.subject, protectedId]]);
+        sequence([
+          () => expand(child(ast.protected, protectedId)),
+          () => depend(protectedId, "value"),
+          () => expand(child(ast.failure, failureId, { substitutions: recovery, prerequisite: protectedId })),
+          () => {
+            dependencies.push(failureId);
+            observedEdges.push({ from: protectedId, to: failureId, reason: "failure" });
+            observedEdges.push({ from: failureId, to: id, reason: "value" });
+            inputs.push({ _tag: "Ref", from: failureId, path: [] });
+          },
+          () => record({
+            id,
+            kind: ast._tag,
+            dependencies,
+            capabilities,
+            effects: void 0,
+            placement: void 0,
+            priority,
+            tier: "sealed",
+            body: { _tag: ast._tag, filter: ast.filter, filterIdentity: ast.filterIdentity },
+            inputs,
+            ast,
+            payload: void 0
+          })
+        ]);
+        return;
+      }
+    }
+  };
+  const declaration = flowDeclaration(flowOrNode);
+  const root = options.root ?? "root";
+  if (declaration === void 0) {
+    expand({
+      ast: flowOrNode.ast,
+      id: root,
+      depth: 0,
+      capabilities: [],
+      placement: void 0,
+      envelope: void 0,
+      priority: void 0,
+      substitutions: /* @__PURE__ */ new Map(),
+      stack: [],
+      prerequisite: void 0,
+      barriers: []
+    });
+  } else {
+    const entry = hydrate(payload, /* @__PURE__ */ new Map(), root);
+    expandFlowCall({
+      id: root,
+      depth: 0,
+      // The entry is a call to the flow itself that no author wrote, so its
+      // AST is synthesized here rather than recorded by `Node.flowCall`, which
+      // would replace a payload's non-JSON values with their plain-object
+      // copies. What a body was planned with stays what the entry node shows.
+      ast: { _tag: "FlowCall", flow: declaration._tag, mode: "inline", payload: entry },
+      flow: declaration._tag,
+      mode: "inline",
+      declaration,
+      payload: entry,
+      capabilities: sorted(Context.get(declaration.annotations, Annotations.Capabilities)),
+      // Nothing encloses the entry, so its own declared placement is what the
+      // body it splices has to be satisfiable under, not a constraint on it.
+      // Its declared envelope reads the same way: the entry is the top of the
+      // authority chain, so it grants rather than narrows.
+      placement: void 0,
+      envelope: void 0,
+      priority: void 0,
+      substitutions: /* @__PURE__ */ new Map(),
+      stack: [],
+      barriers: [],
+      dependencies: [],
+      inputs: []
+    });
+  }
+  while (operations.length > 0) operations.pop()();
+  return {
+    nodes: observed,
+    edges: observedEdges,
+    diagnostics: observedDiagnostics
+  };
+};
+const nodes = (graph) => graph.nodes;
+const edges = (graph) => graph.edges;
+const evaluatedFrom = (evaluated, entry) => DeclarationSite.evaluatedFrom(evaluated, entry);
+const drafts = (graph) => {
+  const refusal = graph.diagnostics.find(import_GraphBuildError.isFatalDiagnostic);
+  if (refusal !== void 0) throw refusal;
+  return graph.nodes.map((node) => node.draft);
+};
+const diagnostics = (graph) => graph.diagnostics;
+const inspect = (flow) => {
+  const prompt = "prompt" in flow && typeof flow.prompt === "function" ? Function.prototype.toString.call(flow.prompt) : void 0;
+  const withPrompt = (inspection) => prompt === void 0 ? inspection : { ...inspection, prompt };
+  try {
+    const graph = build(flow, Planned.make("input"));
+    const nodes2 = graph.nodes.map((node) => ({
+      id: node.id,
+      kind: node.kind,
+      ...node.ast._tag === "FlowCall" ? { label: node.ast.flow } : node.ast._tag === "ActionCall" ? { label: node.ast.action } : {},
+      dependencies: node.dependencies
+    }));
+    const steps = graph.nodes.flatMap(
+      (node) => node.ast._tag === "ActionCall" ? [{ id: node.id, label: node.ast.action }] : node.ast._tag === "FlowCall" && node.ast.mode !== "inline" ? [{ id: node.id, label: node.ast.flow }] : []
+    );
+    return withPrompt({
+      nodes: nodes2,
+      edges: graph.edges,
+      steps,
+      diagnostics: graph.diagnostics.map(({ code, message }) => ({ code, message }))
+    });
+  } catch (error) {
+    return withPrompt({
+      // The declaration itself is a known boundary even when its internals
+      // require real input. Do not publish a fictitious empty execution.
+      nodes: [{ id: "root", kind: "FlowCall", label: flow._tag, dependencies: [] }],
+      edges: [],
+      steps: [{ id: "root", label: flow._tag }],
+      diagnostics: [{
+        code: error instanceof import_GraphBuildError.GraphBuildError ? error.code === "planned_value_computed" ? "declaration_requires_input" : error.code : "declaration_inspection_failed",
+        message: error instanceof Error ? error.message : String(error)
+      }]
+    });
+  }
+};
+//# sourceMappingURL=Graph.js.map