@nanobpm/urban 0.50.0 → 0.52.0

package/src/runtime/core/lineage.test.ts

@@ -0,0 +1,215 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  applyAmbientLineage,
+  buildLineageTree,
+  deriveLineage,
+  type LineageEdge,
+  LINEAGE_KEY,
+  LINEAGE_NAMESPACE,
+  mintRootRequestKey,
+  readLineage,
+  writeLineage,
+} from "./lineage.ts";
+import { __resetExecStoreForTests, installExecStore, runInJobContext } from "./execContext.ts";
+import { createNodeHost } from "../adapters/node.ts";
+import { isRecord } from "./guards.ts";
+
+function lineageOf(variables: Record<string, unknown>): unknown {
+  const ns = variables[LINEAGE_NAMESPACE];
+  return isRecord(ns) ? ns[LINEAGE_KEY] : undefined;
+}
+
+test("readLineage extracts a well-formed envelope and rejects malformed ones", () => {
+  assert.deepEqual(
+    readLineage({ _urban: { lineage: { rootRequestKey: "r1", causedByInstanceKey: "c1" } } }),
+    { rootRequestKey: "r1", causedByInstanceKey: "c1" },
+  );
+  // A bare root (no cause) is a valid fresh root.
+  assert.deepEqual(readLineage({ _urban: { lineage: { rootRequestKey: "r1" } } }), {
+    rootRequestKey: "r1",
+    causedByInstanceKey: undefined,
+  });
+  // Blank/absent rootRequestKey → not a valid envelope.
+  assert.equal(readLineage({ _urban: { lineage: { rootRequestKey: "" } } }), undefined);
+  assert.equal(readLineage({ _urban: { lineage: {} } }), undefined);
+  assert.equal(readLineage({ _urban: {} }), undefined);
+  assert.equal(readLineage({}), undefined);
+  assert.equal(readLineage(undefined), undefined);
+});
+
+test("writeLineage never mutates input and preserves other _urban.* keys", () => {
+  const input = { keep: 1, _urban: { other: "x" } };
+  const out = writeLineage(input, { rootRequestKey: "r1", causedByInstanceKey: "c1" });
+  assert.deepEqual(input, { keep: 1, _urban: { other: "x" } }, "input is not mutated");
+  assert.equal(out.keep, 1);
+  assert.deepEqual(out._urban, { other: "x", lineage: { rootRequestKey: "r1", causedByInstanceKey: "c1" } });
+});
+
+test("writeLineage drops an absent causedByInstanceKey (a fresh root is { rootRequestKey })", () => {
+  const out = writeLineage({}, { rootRequestKey: "r1" });
+  assert.deepEqual(lineageOf(out), { rootRequestKey: "r1" });
+});
+
+test("deriveLineage propagates an ambient root and sets causedByInstanceKey", () => {
+  assert.deepEqual(deriveLineage({ rootRequestKey: "root-1", instanceKey: "inst-5" }), {
+    rootRequestKey: "root-1",
+    causedByInstanceKey: "inst-5",
+  });
+});
+
+test("deriveLineage treats an ambient instance with no envelope as its own root", () => {
+  assert.deepEqual(deriveLineage({ instanceKey: "inst-9" }), {
+    rootRequestKey: "inst-9",
+    causedByInstanceKey: "inst-9",
+  });
+});
+
+test("deriveLineage mints a fresh root when there is no ambient job at all", () => {
+  assert.deepEqual(deriveLineage(undefined, () => "minted-1"), { rootRequestKey: "minted-1" });
+});
+
+test("mintRootRequestKey returns a non-empty, unique-ish value", () => {
+  const a = mintRootRequestKey();
+  const b = mintRootRequestKey();
+  assert.equal(typeof a, "string");
+  assert.notEqual(a, "");
+  assert.notEqual(a, b);
+});
+
+test("applyAmbientLineage: an explicit caller envelope always wins (untouched)", () => {
+  const explicit = { _urban: { lineage: { rootRequestKey: "explicit", causedByInstanceKey: "x" } } };
+  const out = applyAmbientLineage(explicit, {
+    ambient: { rootRequestKey: "ambient-root", instanceKey: "ambient-inst" },
+  });
+  assert.deepEqual(lineageOf(out), { rootRequestKey: "explicit", causedByInstanceKey: "x" });
+});
+
+test("applyAmbientLineage: propagates the ambient root and stamps the cause", () => {
+  const out = applyAmbientLineage(
+    { payload: 1 },
+    { ambient: { rootRequestKey: "root-A", instanceKey: "inst-B" } },
+  );
+  assert.equal(out.payload, 1);
+  assert.deepEqual(lineageOf(out), { rootRequestKey: "root-A", causedByInstanceKey: "inst-B" });
+});
+
+test("applyAmbientLineage: mints a fresh root for a genuine top-level request", () => {
+  const out = applyAmbientLineage({}, { ambient: undefined, mintRootRequestKey: () => "fresh-1" });
+  assert.deepEqual(lineageOf(out), { rootRequestKey: "fresh-1" });
+});
+
+test("applyAmbientLineage reads the real ambient job context (runInJobContext)", () => {
+  __resetExecStoreForTests();
+  const host = createNodeHost({ cwd: process.cwd(), log: () => {} });
+  installExecStore(() => host.createAsyncStore?.());
+  try {
+    const out = runInJobContext({ instanceKey: "pi-1", rootRequestKey: "root-1", jobType: "w" }, () =>
+      applyAmbientLineage({ a: 1 }),
+    );
+    assert.deepEqual(lineageOf(out), { rootRequestKey: "root-1", causedByInstanceKey: "pi-1" });
+  } finally {
+    __resetExecStoreForTests();
+  }
+});
+
+test("buildLineageTree stitches a fan-out tree from weak edges", () => {
+  const edges: LineageEdge[] = [
+    { rootRequestKey: "root", instanceKey: "root", edgeType: "weak" },
+    { rootRequestKey: "root", instanceKey: "child-1", causedByInstanceKey: "root", edgeType: "weak" },
+    { rootRequestKey: "root", instanceKey: "child-2", causedByInstanceKey: "root", edgeType: "weak" },
+    { rootRequestKey: "root", instanceKey: "grand-1", causedByInstanceKey: "child-1", edgeType: "weak" },
+  ];
+  const tree = buildLineageTree("root", edges);
+  assert.equal(tree.root.instanceKey, "root");
+  assert.deepEqual(tree.root.children.map((c) => c.instanceKey).sort(), ["child-1", "child-2"]);
+  const child1 = tree.root.children.find((c) => c.instanceKey === "child-1");
+  assert.deepEqual(child1?.children.map((c) => c.instanceKey), ["grand-1"]);
+  assert.equal(tree.nodes.length, 4);
+});
+
+test("buildLineageTree: a strong (engine) edge supersedes a weak edge on the same node", () => {
+  const edges: LineageEdge[] = [
+    { rootRequestKey: "root", instanceKey: "child", causedByInstanceKey: "root", edgeType: "weak" },
+    { rootRequestKey: "root", instanceKey: "child", causedByInstanceKey: "root", edgeType: "strong" },
+  ];
+  const tree = buildLineageTree("root", edges);
+  const child = tree.nodes.find((n) => n.instanceKey === "child");
+  assert.equal(child?.edgeType, "strong");
+});
+
+test("buildLineageTree ignores edges from other roots and hangs attachments on their node", () => {
+  const edges: LineageEdge[] = [
+    { rootRequestKey: "root", instanceKey: "child", causedByInstanceKey: "root", edgeType: "weak" },
+    { rootRequestKey: "other", instanceKey: "stranger", causedByInstanceKey: "other", edgeType: "weak" },
+  ];
+  const tree = buildLineageTree("root", edges, [
+    { nodeKey: "child", kind: "pull_request", ref: "owner/repo#1", label: "PR 1" },
+    { nodeKey: "missing", kind: "task", ref: "t-1" },
+  ]);
+  assert.equal(tree.nodes.some((n) => n.instanceKey === "stranger"), false);
+  const child = tree.root.children[0];
+  assert.equal(child.instanceKey, "child");
+  assert.deepEqual(child.attachments, [{ nodeKey: "child", kind: "pull_request", ref: "owner/repo#1", label: "PR 1" }]);
+  // An attachment for an instance with no recorded edge yet is PRESERVED as an unattached node,
+  // never silently dropped — attachments are an extension point and must survive the projection.
+  const orphan = tree.nodes.find((n) => n.instanceKey === "missing");
+  assert.ok(orphan, "attachment for an un-stitched instance must materialise its node");
+  assert.deepEqual(orphan.attachments, [{ nodeKey: "missing", kind: "task", ref: "t-1" }]);
+  assert.equal(orphan.edgeType, undefined);
+  assert.equal(orphan.children.length, 0);
+});
+
+test("buildLineageTree: a stray orphan attachment does not shadow a MINTED root's real parentless instance", () => {
+  // Defect-class guard: materialising attachment-only nodes must not reintroduce the phantom-root
+  // bug. A minted (synthetic) rootRequestKey with an orphan attachment adds a second parentless
+  // node; the tree must still root at the real recorded instance, not the empty synthetic phantom.
+  const edges: LineageEdge[] = [
+    { rootRequestKey: "req-UUID", instanceKey: "inst-root", edgeType: "weak" },
+    { rootRequestKey: "req-UUID", instanceKey: "inst-child", causedByInstanceKey: "inst-root", edgeType: "strong" },
+  ];
+  const tree = buildLineageTree("req-UUID", edges, [{ nodeKey: "inst-orphan", kind: "note", ref: "n-1" }]);
+  assert.equal(tree.root.instanceKey, "inst-root");
+  assert.deepEqual(tree.root.children.map((c) => c.instanceKey), ["inst-child"]);
+  assert.equal(tree.nodes.some((n) => n.instanceKey === "req-UUID"), false);
+  // The orphan attachment is preserved (unattached), and the synthetic key never leaks as a node.
+  const orphan = tree.nodes.find((n) => n.instanceKey === "inst-orphan");
+  assert.ok(orphan, "orphan attachment node must be preserved");
+  assert.deepEqual(orphan.attachments, [{ nodeKey: "inst-orphan", kind: "note", ref: "n-1" }]);
+});
+
+test("buildLineageTree roots a MINTED (synthetic) rootRequestKey at the parentless instance, not a phantom", () => {
+  // A genuine top-level request MINTS a UUID `rootRequestKey` that is NOT any instance key
+  // (`deriveLineage` with no ambient job). The real root instance carries that key with no
+  // cause, and its descendants hang off the instance. The tree must be rooted at the real
+  // parentless instance — never at an empty synthetic node while the real root floats detached.
+  const edges: LineageEdge[] = [
+    { rootRequestKey: "req-UUID", instanceKey: "inst-root", edgeType: "weak" },
+    { rootRequestKey: "req-UUID", instanceKey: "inst-child", causedByInstanceKey: "inst-root", edgeType: "weak" },
+    { rootRequestKey: "req-UUID", instanceKey: "inst-grand", causedByInstanceKey: "inst-child", edgeType: "strong" },
+  ];
+  const tree = buildLineageTree("req-UUID", edges);
+  assert.equal(tree.root.instanceKey, "inst-root");
+  assert.deepEqual(tree.root.children.map((c) => c.instanceKey), ["inst-child"]);
+  assert.deepEqual(tree.root.children[0].children.map((c) => c.instanceKey), ["inst-grand"]);
+  // The synthetic correlation key must not leak into the flat view as a phantom node.
+  assert.equal(tree.nodes.some((n) => n.instanceKey === "req-UUID"), false);
+  assert.equal(tree.nodes.length, 3);
+});
+
+test("buildLineageTree keeps a lone real root (parentless, no descendants) as the tree root", () => {
+  // Guard the fallback boundary: a real root instance whose key IS the rootRequestKey and which
+  // has no descendants must stay the root — it must not be mistaken for a replaceable phantom.
+  const edges: LineageEdge[] = [{ rootRequestKey: "root", instanceKey: "root", edgeType: "weak" }];
+  const tree = buildLineageTree("root", edges);
+  assert.equal(tree.root.instanceKey, "root");
+  assert.equal(tree.root.children.length, 0);
+  assert.equal(tree.nodes.length, 1);
+});
+
+test("buildLineageTree keeps the synthetic root when no edges exist at all", () => {
+  const tree = buildLineageTree("req-UUID", []);
+  assert.equal(tree.root.instanceKey, "req-UUID");
+  assert.equal(tree.root.children.length, 0);
+  assert.deepEqual(tree.nodes.map((n) => n.instanceKey), ["req-UUID"]);
+});

package/src/runtime/core/lineage.ts

@@ -0,0 +1,297 @@
+// lineage — the framework-level lineage primitive (issue #254).
+//
+// Any Urban app wants to stitch *user intent → progress*: a single root request (a
+// button press, an inbound webhook, an API call) fans out into the process instances,
+// PRs, tasks and sub-loops it *causes*, and an operator wants to see that whole thread.
+// Today every app hand-rolls that correlation. This module makes it a framework
+// primitive so the next app gets intent→progress threading for free.
+//
+// Two DISTINCT relationships stitch the thread, and they must stay separate:
+//
+//   - the LINEAGE / CAUSATION edge (this module): asynchronous causation — the cause does
+//     NOT block the effect, edges fan out (1→N), descendants settle independently and
+//     survive their ancestor's termination, and they are created by message-start / API
+//     `createInstance` / webhooks as much as by call activities. Carried as a reserved
+//     `_urban.lineage` envelope on every instance/message the SDK starts, AUTO-THREADED
+//     from the ambient job context (see {@link applyAmbientLineage}).
+//   - the EXECUTION edge (`parentProcessInstanceKey`, engine-native — Magikcraft/nano-bpm#808):
+//     synchronous delegation where the parent token blocks on the child. This module does
+//     NOT duplicate it; the read projection ({@link buildLineageTree}) CONSUMES it as a
+//     strong edge, unioned with the weak/causal edges of the envelope.
+//
+// This file is intentionally `node:*`-free (the host contract): the only ambient
+// capability it reaches for is `crypto.randomUUID` (a Web/global, not `node:crypto`),
+// with a portable fallback.
+
+import { currentJobContext, type JobExecContext } from "./execContext.ts";
+import { isRecord } from "./guards.ts";
+
+/** The reserved variable namespace the lineage envelope lives under on every
+ *  instance/message (`_urban.lineage`). Kept as one object so future framework
+ *  conventions can share the `_urban.*` namespace without colliding. */
+export const LINEAGE_NAMESPACE = "_urban";
+/** The key of the lineage envelope within {@link LINEAGE_NAMESPACE}. */
+export const LINEAGE_KEY = "lineage";
+
+/**
+ * The lineage envelope, a reserved convention on every instance/message:
+ * `_urban.lineage = { rootRequestKey, causedByInstanceKey? }`.
+ *  - `rootRequestKey` threads every descendant of a single top-level request back to
+ *    it; it is PRESERVED verbatim across the whole causal tree.
+ *  - `causedByInstanceKey` is the instance that directly caused this one (the weak
+ *    parent edge). Absent on a genuine top-level request (a fresh root).
+ */
+export interface LineageEnvelope {
+  readonly rootRequestKey: string;
+  readonly causedByInstanceKey?: string;
+}
+
+/** Options for {@link applyAmbientLineage}, injectable for deterministic tests. */
+export interface ApplyLineageOptions {
+  /** Override the ambient job context (defaults to {@link currentJobContext}). */
+  readonly ambient?: JobExecContext | undefined;
+  /** Override the fresh-root minter (defaults to {@link mintRootRequestKey}). */
+  readonly mintRootRequestKey?: () => string;
+}
+
+/** Mint a fresh `rootRequestKey` for a genuine top-level request (no ambient lineage).
+ *  Uses `crypto.randomUUID` where available (Node ≥ 16.7 / Deno expose it as a global),
+ *  with a time+random fallback so this stays host-agnostic and never throws. */
+export function mintRootRequestKey(): string {
+  const uuid = globalThis.crypto?.randomUUID?.();
+  if (uuid) return uuid;
+  return `root-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/** Coerce a value to a non-empty string, or `undefined`. */
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value !== "" ? value : undefined;
+}
+
+/**
+ * Read the `_urban.lineage` envelope from a variables map, or `undefined` when absent or
+ * malformed (no/blank `rootRequestKey`). Tolerant by design: a bad envelope degrades to
+ * "no ambient lineage" rather than throwing on the hot instance-creation path.
+ */
+export function readLineage(variables: unknown): LineageEnvelope | undefined {
+  if (!isRecord(variables)) return undefined;
+  const ns = variables[LINEAGE_NAMESPACE];
+  if (!isRecord(ns)) return undefined;
+  const env = ns[LINEAGE_KEY];
+  if (!isRecord(env)) return undefined;
+  const rootRequestKey = nonEmptyString(env.rootRequestKey);
+  if (!rootRequestKey) return undefined;
+  return { rootRequestKey, causedByInstanceKey: nonEmptyString(env.causedByInstanceKey) };
+}
+
+/** Normalise an envelope for storage in variables — drop an absent `causedByInstanceKey`
+ *  rather than serialising `undefined`, so a fresh root's envelope is `{ rootRequestKey }`. */
+function toEnvelopeRecord(envelope: LineageEnvelope): Record<string, unknown> {
+  return envelope.causedByInstanceKey
+    ? { rootRequestKey: envelope.rootRequestKey, causedByInstanceKey: envelope.causedByInstanceKey }
+    : { rootRequestKey: envelope.rootRequestKey };
+}
+
+/**
+ * Return a COPY of `variables` with `envelope` written under `_urban.lineage`, preserving
+ * any other `_urban.*` keys. Never mutates the input.
+ */
+export function writeLineage(
+  variables: Record<string, unknown> | undefined,
+  envelope: LineageEnvelope,
+): Record<string, unknown> {
+  const base = isRecord(variables) ? variables : {};
+  const ns = isRecord(base[LINEAGE_NAMESPACE]) ? base[LINEAGE_NAMESPACE] : {};
+  return { ...base, [LINEAGE_NAMESPACE]: { ...ns, [LINEAGE_KEY]: toEnvelopeRecord(envelope) } };
+}
+
+/**
+ * Derive the envelope to attach to a NEW instance/message given the ambient job context.
+ *  - Ambient lineage present → PROPAGATE it: preserve `rootRequestKey`, set
+ *    `causedByInstanceKey` to the current instance (the cause).
+ *  - Ambient job with an instance but no envelope → that instance is itself a root; the
+ *    child inherits `rootRequestKey = <ambient instance>` and is caused by it.
+ *  - No ambient job at all (a genuine top-level request) → MINT a fresh `rootRequestKey`.
+ */
+export function deriveLineage(
+  ambient: JobExecContext | undefined,
+  mint: () => string = mintRootRequestKey,
+): LineageEnvelope {
+  const rootRequestKey = ambient?.rootRequestKey ?? ambient?.instanceKey;
+  if (rootRequestKey) {
+    return { rootRequestKey, causedByInstanceKey: ambient?.instanceKey };
+  }
+  return { rootRequestKey: mint() };
+}
+
+/**
+ * The single, adapter-agnostic step that auto-threads lineage onto a `createInstance` /
+ * `publishMessage` call's variables. Both the live `SdkEngineClient` and the testkit's
+ * `WasmEngineClient` route through this (No Drift Surfaces), so lineage threads identically
+ * in production and in-harness.
+ *
+ * An EXPLICIT caller-supplied `_urban.lineage` always wins (start a new root or re-parent
+ * deliberately) — it is returned untouched. Otherwise the envelope is derived from the
+ * ambient job context ({@link deriveLineage}) and merged in.
+ */
+export function applyAmbientLineage(
+  variables: Record<string, unknown> | undefined,
+  opts: ApplyLineageOptions = {},
+): Record<string, unknown> {
+  const base = isRecord(variables) ? variables : {};
+  if (readLineage(base)) return { ...base };
+  const ambient = opts.ambient !== undefined ? opts.ambient : currentJobContext();
+  return writeLineage(base, deriveLineage(ambient, opts.mintRootRequestKey));
+}
+
+// ---------------------------------------------------------------------------
+// Read projection — union the weak (envelope) and strong (parentProcessInstanceKey)
+// edges into a stitched descendant tree keyed by rootRequestKey.
+// ---------------------------------------------------------------------------
+
+/** How a node connects to its cause. `weak` = the causal envelope edge; `strong` = the
+ *  engine-native execution edge (`parentProcessInstanceKey`, Magikcraft/nano-bpm#808). */
+export type LineageEdgeType = "weak" | "strong";
+
+/** One directed edge cause → effect in a lineage tree. `causedByInstanceKey` is absent on a
+ *  root's own edge. */
+export interface LineageEdge {
+  readonly rootRequestKey: string;
+  /** The effect / descendant instance this edge lands on. */
+  readonly instanceKey: string;
+  /** The cause / parent instance, or `undefined` for a root. */
+  readonly causedByInstanceKey?: string;
+  readonly edgeType: LineageEdgeType;
+}
+
+/** An app-registered domain row attached to a lineage node (a PR, a task, …). The framework
+ *  stores it opaquely by `(nodeKey, kind, ref)` without knowing the app's schema. */
+export interface LineageAttachment {
+  /** The instance key this row hangs off. */
+  readonly nodeKey: string;
+  /** App-defined category, e.g. `"pull_request"`, `"task"`. */
+  readonly kind: string;
+  /** App-defined reference into its own store, e.g. a PR key. */
+  readonly ref: string;
+  /** Optional human-readable label. */
+  readonly label?: string;
+}
+
+/** A node in the stitched lineage tree. */
+export interface LineageNode {
+  readonly instanceKey: string;
+  /** How this node connects to its parent; `undefined` for the root. */
+  readonly edgeType?: LineageEdgeType;
+  readonly causedByInstanceKey?: string;
+  readonly attachments: LineageAttachment[];
+  readonly children: LineageNode[];
+}
+
+/** The stitched descendant tree for one `rootRequestKey`. */
+export interface LineageTree {
+  readonly rootRequestKey: string;
+  /** The root node of the stitched tree, always present. Normally the top-level request's own
+   *  instance; when `rootRequestKey` is a minted synthetic key, the parentless root instance it
+   *  threads. Falls back to a synthetic node keyed by `rootRequestKey` when no edges exist. */
+  readonly root: LineageNode;
+  /** Every node keyed by instance, in insertion order — a convenience flat view. */
+  readonly nodes: LineageNode[];
+}
+
+/**
+ * Build the stitched descendant tree for `rootRequestKey` by unioning weak and strong edges.
+ * When both edge sources connect the SAME node, the STRONG (engine execution) edge wins — it
+ * is the authoritative parent — so #808's native edge supersedes the envelope's weak guess
+ * without duplicating it. Nodes whose parent chain does not reach the root stay unattached
+ * (they still appear in `nodes`). The root is the instance keyed by `rootRequestKey` when that
+ * is itself an instance, else the single parentless recorded instance (a minted `rootRequestKey`
+ * is a synthetic correlation key, not an instance), else a synthetic node. Pure and
+ * deterministic — the store is a thin persistence layer over this.
+ */
+export function buildLineageTree(
+  rootRequestKey: string,
+  edges: readonly LineageEdge[],
+  attachments: readonly LineageAttachment[] = [],
+): LineageTree {
+  // Collapse to one edge per effect instance: strong supersedes weak.
+  const byInstance = new Map<string, LineageEdge>();
+  for (const e of edges) {
+    if (e.rootRequestKey !== rootRequestKey) continue;
+    const prev = byInstance.get(e.instanceKey);
+    if (!prev || (prev.edgeType === "weak" && e.edgeType === "strong")) {
+      byInstance.set(e.instanceKey, e);
+    }
+  }
+
+  const nodes = new Map<string, MutableNode>();
+  const ensure = (instanceKey: string): MutableNode => {
+    let n = nodes.get(instanceKey);
+    if (!n) {
+      n = { instanceKey, attachments: [], children: [] };
+      nodes.set(instanceKey, n);
+    }
+    return n;
+  };
+
+  // Speculatively materialise the `rootRequestKey` node so descendants whose cause IS the root
+  // (a child inherits the root's own instance key as `rootRequestKey`) can attach to it below.
+  const rootByKey = ensure(rootRequestKey);
+
+  for (const e of byInstance.values()) {
+    const node = ensure(e.instanceKey);
+    node.edgeType = e.edgeType;
+    node.causedByInstanceKey = e.causedByInstanceKey;
+  }
+
+  // Attachments are an app extension point keyed by instance. MATERIALISE the target node even
+  // when no edge has been recorded for it yet, so an attachment for an as-yet-unstitched instance
+  // is preserved in `tree.nodes` (unattached until its edge lands) rather than silently dropped.
+  for (const a of attachments) {
+    const node = ensure(a.nodeKey);
+    node.attachments.push({ nodeKey: a.nodeKey, kind: a.kind, ref: a.ref, ...(a.label ? { label: a.label } : {}) });
+  }
+
+  for (const node of nodes.values()) {
+    const parentKey = node.causedByInstanceKey;
+    if (parentKey && parentKey !== node.instanceKey && nodes.has(parentKey)) {
+      ensure(parentKey).children.push(node);
+    }
+  }
+
+  // Resolve the root node. Usually `rootRequestKey` IS the root instance's own key, so `rootByKey`
+  // carries that instance's edge and descendants. But a genuine top-level request (no ambient job)
+  // MINTS a synthetic `rootRequestKey` — a UUID that is not any instance — so `rootByKey` is an
+  // empty phantom while the real root is the single recorded instance with no cause. Prefer that
+  // parentless instance and drop the phantom, so the tree is never rooted at a childless synthetic
+  // node with the real root left floating detached (the bug this guards against).
+  let root = rootByKey;
+  const rootIsPhantom =
+    rootByKey.edgeType === undefined && rootByKey.children.length === 0 && rootByKey.attachments.length === 0;
+  if (rootIsPhantom) {
+    // A candidate real root is a parentless node that is genuinely part of the causal structure —
+    // it has its own recorded edge or descendants. Attachment-only orphan nodes (materialised above
+    // with no edge and no children) are NOT candidates, so a stray attachment can never shadow the
+    // real parentless root and re-introduce the phantom-root bug guarded by the minted-root case.
+    const parentlessInstances = [...nodes.values()].filter(
+      (n) =>
+        n !== rootByKey &&
+        n.causedByInstanceKey === undefined &&
+        (n.edgeType !== undefined || n.children.length > 0),
+    );
+    if (parentlessInstances.length === 1) {
+      root = parentlessInstances[0];
+      nodes.delete(rootRequestKey);
+    }
+  }
+
+  return { rootRequestKey, root, nodes: [...nodes.values()] };
+}
+
+/** The internal, mutable view of {@link LineageNode} used while building the tree. */
+interface MutableNode {
+  instanceKey: string;
+  edgeType?: LineageEdgeType;
+  causedByInstanceKey?: string;
+  attachments: LineageAttachment[];
+  children: MutableNode[];
+}

package/src/runtime/core/modules/datasource.ts

@@ -281,6 +281,15 @@ export class DataLayer {
     return s;
   }
 
+  /**
+   * Whether a default data source is *configured* — not whether it provisions. Lets a caller
+   * distinguish the expected "no source at all" case from a genuine misconfiguration (a default is
+   * named but its source is missing, so {@link source} throws `no such data source`).
+   */
+  hasDefaultSource(): boolean {
+    return this.defaultSource !== undefined;
+  }
+
   /** A typed accessor for a declared domain type (uses the default source). */
   repo(typeName: string, sourceName?: string): TypeRepo {
     const def = this.types[typeName];