@nanobpm/urban 0.51.0 → 0.53.0

package/src/runtime/core/modules/workers.test.ts

@@ -4,8 +4,20 @@ import assert from "node:assert/strict";
 import type { AppApi, RuntimeContext } from "../context.ts";
 import type { EngineClient, EngineJob, HostContext, JobHandler, WorkerSubscription } from "../host.ts";
 import type { AppManifest } from "../manifest.ts";
-import { DataLayer } from "./datasource.ts";
+import { DataLayer, type ProvisionedSource } from "./datasource.ts";
 import { mountWorkers, sdkDecisionEvaluator, type AppJobHandler } from "./workers.ts";
+import { makeGateway } from "./gateway.ts";
+import { LineageStore } from "./lineage-store.ts";
+import {
+  __resetExecStoreForTests,
+  currentJobContext,
+  installExecStore,
+  type JobExecContext,
+} from "../execContext.ts";
+import { createNodeHost } from "../../adapters/node.ts";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 
 /** A tiny engine that records registrations and can deliver a job to a handler. */
 class MiniEngine implements EngineClient {
@@ -303,3 +315,126 @@ test("AppJobHandler carries optional In/Out variable types", async () => {
   assert.deepEqual(await open(openJob, app), { count: 2 });
   assert.equal(await voidReturn(job, app), undefined);
 });
+
+// --- Lineage threading + projection recording (issue #254) ---------------------
+
+/** A DataLayer with a single default sqlite source, so `tryLineageStore` can record into it. */
+async function dataLayerWithSqlite(): Promise<{ data: DataLayer; db: ProvisionedSource["db"]; cleanup: () => Promise<void> }> {
+  const dir = await mkdtemp(join(tmpdir(), "urban-workers-lineage-"));
+  const host = createNodeHost({ cwd: dir, log: () => {} });
+  const db = host.openSqlite(join(dir, "app.db"));
+  const src: ProvisionedSource = {
+    name: "main",
+    driver: "sqlite",
+    db,
+    source: makeGateway(db),
+    migrationsApplied: [],
+    close: () => db.close(),
+  };
+  const data = new DataLayer(new Map([["main", src]]), "main", {});
+  return { data, db, cleanup: async () => { try { db.close(); } catch { /* already closed */ } await rm(dir, { recursive: true, force: true }); } };
+}
+
+test("mountWorkers threads the lineage rootRequestKey into the ambient job context", async () => {
+  __resetExecStoreForTests();
+  const host = createNodeHost({ cwd: process.cwd(), log: () => {} });
+  installExecStore(() => host.createAsyncStore?.<JobExecContext>());
+  const engine = new MiniEngine();
+  const { ctx } = makeCtx({ workers: [{ taskType: "spawn", handler: "workers/spawn.ts" }] }, engine);
+  const seen: Array<JobExecContext | undefined> = [];
+  const handler: AppJobHandler = () => {
+    seen.push(currentJobContext());
+  };
+  ctx.host.importModule = async () => ({ default: handler });
+  try {
+    await mountWorkers(ctx, makeApp());
+    // An instance carrying an envelope propagates its root.
+    await engine.deliver("spawn", {
+      jobKey: "j1",
+      jobType: "spawn",
+      processInstanceKey: "pi-child",
+      variables: { _urban: { lineage: { rootRequestKey: "ROOT", causedByInstanceKey: "pi-parent" } } },
+    });
+    // An instance with no envelope is treated as its own root.
+    await engine.deliver("spawn", { jobKey: "j2", jobType: "spawn", processInstanceKey: "pi-solo", variables: {} });
+    assert.equal(seen[0]?.rootRequestKey, "ROOT");
+    assert.equal(seen[1]?.rootRequestKey, "pi-solo");
+  } finally {
+    __resetExecStoreForTests();
+  }
+});
+
+test("mountWorkers records each activated job's lineage edge into the projection (idempotently)", async () => {
+  const engine = new MiniEngine();
+  const { ctx } = makeCtx({ workers: [{ taskType: "work", handler: "workers/work.ts" }] }, engine);
+  const handler: AppJobHandler = () => ({ ok: true });
+  ctx.host.importModule = async () => ({ default: handler });
+  const { data, db, cleanup } = await dataLayerWithSqlite();
+  try {
+    await mountWorkers(ctx, makeApp({ data }));
+    const job = {
+      jobKey: "j1",
+      jobType: "work",
+      processInstanceKey: "pi-child",
+      variables: { _urban: { lineage: { rootRequestKey: "ROOT", causedByInstanceKey: "pi-root" } } },
+    };
+    await engine.deliver("work", job);
+    await engine.deliver("work", { ...job, jobKey: "j2" }); // re-activation → idempotent
+
+    const tree = new LineageStore(db).getLineage("ROOT");
+    const child = tree.nodes.find((n) => n.instanceKey === "pi-child");
+    assert.equal(child?.causedByInstanceKey, "pi-root");
+    assert.equal(child?.edgeType, "weak");
+    assert.equal(new LineageStore(db).edges("ROOT").length, 1, "re-activation does not duplicate the edge");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("mountWorkers records nothing when the app has no default data source (absent-safe)", async () => {
+  const engine = new MiniEngine();
+  const { ctx, logs } = makeCtx({ workers: [{ taskType: "work", handler: "workers/work.ts" }] }, engine);
+  const handler: AppJobHandler = () => ({ ok: true });
+  ctx.host.importModule = async () => ({ default: handler });
+  // makeApp's DataLayer has no default source; mounting + delivering must not throw.
+  await mountWorkers(ctx, makeApp());
+  await engine.deliver("work", { jobKey: "j1", jobType: "work", processInstanceKey: "pi", variables: {} });
+  assert.ok(!logs.some((l) => l.level === "error"));
+});
+
+test("mountWorkers surfaces a real provisioning failure as a warn (not the silent absent case)", async () => {
+  const engine = new MiniEngine();
+  const { ctx, logs } = makeCtx({ workers: [{ taskType: "work", handler: "workers/work.ts" }] }, engine);
+  const handler: AppJobHandler = () => ({ ok: true });
+  ctx.host.importModule = async () => ({ default: handler });
+  const { data, db, cleanup } = await dataLayerWithSqlite();
+  try {
+    // A default source IS configured, but provisioning the projection fails (closed db). This is a
+    // genuine fault, not the absent case, so it must be logged at `warn` with the error — never
+    // disguised as an expected "no default data source" debug, and never a failed worker mount.
+    db.close();
+    await mountWorkers(ctx, makeApp({ data }));
+    await engine.deliver("work", { jobKey: "j1", jobType: "work", processInstanceKey: "pi", variables: {} });
+    const warned = logs.find((l) => l.level === "warn" && l.msg.includes("failed to provision"));
+    assert.ok(warned, "a configured-but-broken datasource must warn, not silently degrade");
+    assert.ok(!logs.some((l) => l.msg.includes("no default data source")), "must not claim the datasource is absent");
+  } finally {
+    await cleanup();
+  }
+});
+
+test("mountWorkers surfaces a configured-but-missing default source as a warn (not the silent absent case)", async () => {
+  const engine = new MiniEngine();
+  const { ctx, logs } = makeCtx({ workers: [{ taskType: "work", handler: "workers/work.ts" }] }, engine);
+  const handler: AppJobHandler = () => ({ ok: true });
+  ctx.host.importModule = async () => ({ default: handler });
+  // A default source is NAMED but no such source is provisioned, so `data.source()` throws
+  // `no such data source "main"`. That is a genuine misconfiguration — it must warn, never be
+  // disguised as the expected "no default data source" absent case.
+  const data = new DataLayer(new Map(), "main", {});
+  await mountWorkers(ctx, makeApp({ data }));
+  await engine.deliver("work", { jobKey: "j1", jobType: "work", processInstanceKey: "pi", variables: {} });
+  const warned = logs.find((l) => l.level === "warn" && l.msg.includes("failed to provision"));
+  assert.ok(warned, "a configured-but-missing default source must warn, not silently degrade");
+  assert.ok(!logs.some((l) => l.msg.includes("no default data source")), "must not claim the datasource is absent");
+});

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

@@ -8,6 +8,9 @@ import type { EngineJob, JobHandler, WorkerSubscription } from "../host.ts";
 import { workerJobType, type Worker } from "../manifest.ts";
 import { type DecisionEvaluator, type LlmRuntime, runLlmJob } from "./llm.ts";
 import { runInJobContext } from "../execContext.ts";
+import type { JobExecContext } from "../execContext.ts";
+import { readLineage } from "../lineage.ts";
+import { LineageStore } from "./lineage-store.ts";
 
 /** The subset of the engine SDK the LLM decision-rails need: evaluate a DMN decision,
  *  whose `output` comes back as a JSON string (the orchestration-cluster contract). */
@@ -86,6 +89,60 @@ function withJobLog(app: AppApi, job: EngineJob): AppApi {
   return { ...app, log: app.log.child(bindings) };
 }
 
+/**
+ * Build the ambient {@link JobExecContext} a worker runs its handler within. Beyond the
+ * instance/element/jobType used for write-provenance, it resolves the lineage
+ * `rootRequestKey` (issue #254): the job's own `_urban.lineage` envelope root when present,
+ * else the instance's own key — so an instance with no envelope is treated as a root and any
+ * instance/message its handler spawns inherits that root with `causedByInstanceKey` set.
+ */
+function jobExecContext(job: EngineJob, jobType: string): JobExecContext {
+  return {
+    instanceKey: job.processInstanceKey,
+    elementId: job.elementId,
+    jobType,
+    rootRequestKey: readLineage(job.variables)?.rootRequestKey ?? job.processInstanceKey,
+  };
+}
+
+/**
+ * Build the framework lineage projection store over the app's DEFAULT data source, or `undefined`
+ * when the app configures none. The store records the `_urban.lineage` edge every activated job
+ * reveals (issue #254), so intent→progress lineage materialises for free — but it is a sidecar on
+ * the app's own source (like write-provenance), so an app with no datasource simply records
+ * nothing. Absent- and error-safe: any failure to provision degrades to no lineage recording, never
+ * a failed worker mount.
+ */
+function tryLineageStore(app: AppApi, log: RuntimeContext["host"]["log"]): LineageStore | undefined {
+  if (!app.data.hasDefaultSource()) {
+    // No default data source configured at all — lineage is a sidecar on the app's own source, so
+    // this is the expected absent case (like write-provenance): record nothing, silently.
+    log("debug", "lineage: no default data source; lineage recording disabled");
+    return undefined;
+  }
+  try {
+    const source = app.data.source();
+    const store = new LineageStore(source.db);
+    store.ensureSchema();
+    return store;
+  } catch (err) {
+    // A default IS configured but resolving or provisioning it failed — a missing named source
+    // (`no such data source`) or a schema/DB error. That is a genuine fault, not the absent case,
+    // so surface it at `warn` rather than disguising it as "no source".
+    log("warn", "lineage: failed to provision projection store; lineage recording disabled", { error: String(err) });
+    return undefined;
+  }
+}
+
+/** Record an activated job's lineage edge, never letting a projection write break the job. */
+function recordJobLineage(store: LineageStore, job: EngineJob, log: RuntimeContext["host"]["log"]): void {
+  try {
+    store.recordFromJob(job);
+  } catch (err) {
+    log("warn", "lineage: failed to record job edge", { jobType: job.jobType, error: String(err) });
+  }
+}
+
 /**
  * Resolve a handler for `jobType` from a loaded module, in priority order:
  *   1. `handlers[jobType]`            (a map keyed by job type — the multi-type module case)
@@ -116,6 +173,11 @@ export async function mountWorkers(ctx: RuntimeContext, app: AppApi): Promise<Wo
   const subs: WorkerSubscription[] = [];
   const jobTypes: string[] = [];
 
+  // The framework lineage projection (issue #254): each activated job records the `_urban.lineage`
+  // edge its instance carries, so intent→progress lineage materialises for free. Absent when the
+  // app configures no default data source.
+  const lineageStore = tryLineageStore(app, ctx.host.log);
+
   // Cache module loads so a multi-type handler module is imported once.
   const moduleCache = new Map<string, Record<string, unknown>>();
   const joinRoot = (p: string): string =>
@@ -157,11 +219,13 @@ export async function mountWorkers(ctx: RuntimeContext, app: AppApi): Promise<Wo
         env: (n) => app.env(n),
         evaluateDecision: app.sdk ? sdkDecisionEvaluator(app.sdk) : undefined,
       };
-      const wrapped: JobHandler = (job) =>
-        runInJobContext(
-          { instanceKey: job.processInstanceKey, elementId: job.elementId, jobType },
+      const wrapped: JobHandler = (job) => {
+        if (lineageStore) recordJobLineage(lineageStore, job, ctx.host.log);
+        return runInJobContext(
+          jobExecContext(job, jobType),
           () => runLlmJob(job.variables, binding, rt),
         );
+      };
       const sub = await ctx.engine.registerWorker(jobType, wrapped, {
         workerName: `${ctx.manifest.id}:${jobType}`,
       });
@@ -178,11 +242,13 @@ export async function mountWorkers(ctx: RuntimeContext, app: AppApi): Promise<Wo
           `(expected handlers["${jobType}"], a named export, or a default function)`,
       );
     }
-    const wrapped: JobHandler = (job) =>
-      runInJobContext(
-        { instanceKey: job.processInstanceKey, elementId: job.elementId, jobType },
+    const wrapped: JobHandler = (job) => {
+      if (lineageStore) recordJobLineage(lineageStore, job, ctx.host.log);
+      return runInJobContext(
+        jobExecContext(job, jobType),
         () => handler(job, withJobLog(app, job)),
       );
+    };
     const sub = await ctx.engine.registerWorker(jobType, wrapped, {
       workerName: `${ctx.manifest.id}:${jobType}`,
     });

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

@@ -0,0 +1,350 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  buildScopeIndex,
+  derivePhase,
+  deriveInstancePhases,
+  furthestReached,
+  rollupLineagePhase,
+  SCOPE_CONTAINERS,
+  type InstancePhase,
+  type ProvenanceProgressRow,
+} from "./phase.ts";
+import { buildLineageTree, type LineageEdge } from "./lineage.ts";
+
+// A representative model in the spirit of the issue's motivating `plan-fanout.bpmn`: a process
+// with named subProcesses ("Plan", "Implement task") wrapping tasks, a flat task at process level,
+// a nano:phase override (attribute form), and a zeebe:property override.
+const MODEL = `<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" xmlns:nano="http://nanobpm.io/schema/1.0">
+  <bpmn:process id="plan-fanout" name="Plan Fanout">
+    <bpmn:startEvent id="start" name="Start" />
+    <bpmn:subProcess id="plan" name="Plan">
+      <bpmn:serviceTask id="draft-plan" name="Draft plan" />
+      <bpmn:userTask id="review-plan" name="Review plan" />
+    </bpmn:subProcess>
+    <bpmn:subProcess id="implement" name="Implement task">
+      <bpmn:serviceTask id="write-code" name="Write code">
+        <bpmn:extensionElements>
+          <zeebe:properties>
+            <zeebe:property name="nano:phase" value="Coding (agent)" />
+          </zeebe:properties>
+        </bpmn:extensionElements>
+      </bpmn:serviceTask>
+      <bpmn:subProcess id="trial-merge" name="Trial merge">
+        <bpmn:serviceTask id="merge-attempt" name="Merge attempt" />
+      </bpmn:subProcess>
+    </bpmn:subProcess>
+    <bpmn:serviceTask id="finalize" name="Finalize plan" nano:phase="Wrap up" />
+    <bpmn:endEvent id="dispatched" name="Dispatched" />
+  </bpmn:process>
+</bpmn:definitions>`;
+
+test("SCOPE_CONTAINERS names the process + nestable scope families", () => {
+  assert.deepEqual([...SCOPE_CONTAINERS], ["process", "subProcess", "adHocSubProcess", "transaction"]);
+});
+
+test("buildScopeIndex records the process and every id-bearing element with its scope chain", () => {
+  const idx = buildScopeIndex(MODEL);
+  assert.equal(idx.process?.id, "plan-fanout");
+  assert.equal(idx.process?.name, "Plan Fanout");
+
+  // A flat task at process level: chain is just the process.
+  assert.deepEqual(idx.elements.get("start")?.scopeChain, ["plan-fanout"]);
+  // A task inside a top-level subProcess.
+  assert.deepEqual(idx.elements.get("draft-plan")?.scopeChain, ["plan-fanout", "plan"]);
+  // A task inside a nested subProcess: full outermost→innermost chain.
+  assert.deepEqual(idx.elements.get("merge-attempt")?.scopeChain, [
+    "plan-fanout",
+    "implement",
+    "trial-merge",
+  ]);
+  // Scope containers are flagged and carry their own chain (excluding themselves).
+  assert.equal(idx.elements.get("trial-merge")?.isScope, true);
+  assert.deepEqual(idx.elements.get("trial-merge")?.scopeChain, ["plan-fanout", "implement"]);
+  assert.equal(idx.elements.get("write-code")?.isScope, false);
+});
+
+test("buildScopeIndex captures nano:phase overrides in attribute and zeebe:property forms", () => {
+  const idx = buildScopeIndex(MODEL);
+  // Attribute form on a flat task.
+  assert.equal(idx.elements.get("finalize")?.phaseOverride, "Wrap up");
+  // zeebe:property form nested in extensionElements attaches to the owning service task, not to a
+  // sibling or ancestor.
+  assert.equal(idx.elements.get("write-code")?.phaseOverride, "Coding (agent)");
+  assert.equal(idx.elements.get("implement")?.phaseOverride, undefined);
+  // No override → undefined.
+  assert.equal(idx.elements.get("draft-plan")?.phaseOverride, undefined);
+});
+
+test("buildScopeIndex ignores over-broad matches: bare `phase` attr and non-zeebe/loose `property`", () => {
+  const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:zeebe="http://camunda.org/schema/zeebe/1.0">
+  <bpmn:process id="p" name="P">
+    <!-- A bare, unprefixed phase="…" attribute must NOT be treated as an override. -->
+    <bpmn:serviceTask id="bare-attr" name="Bare attr" phase="not an override" />
+    <!-- A bpmn:property (non-zeebe) carrying name="nano:phase" must NOT override. -->
+    <bpmn:serviceTask id="bpmn-prop" name="Bpmn prop">
+      <bpmn:extensionElements>
+        <bpmn:property name="nano:phase" value="not an override" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <!-- A zeebe:property outside any extensionElements block must NOT override. -->
+    <bpmn:serviceTask id="loose-prop" name="Loose prop">
+      <zeebe:property name="nano:phase" value="not an override" />
+    </bpmn:serviceTask>
+  </bpmn:process>
+</bpmn:definitions>`;
+  const idx = buildScopeIndex(xml);
+  assert.equal(idx.elements.get("bare-attr")?.phaseOverride, undefined);
+  assert.equal(idx.elements.get("bpmn-prop")?.phaseOverride, undefined);
+  assert.equal(idx.elements.get("loose-prop")?.phaseOverride, undefined);
+});
+
+test("derivePhase: a scope element is its own leaf crumb, appended exactly once (no duplicate)", () => {
+  // Querying a subProcess id (an element that IS a scope) must place it as the leaf crumb after its
+  // enclosing scopes — never omitted and never duplicated. Guards the "always append the element as
+  // its own leaf" contract, since `scopeChain` excludes the element itself.
+  const idx = buildScopeIndex(MODEL);
+  const phase = derivePhase(idx, "trial-merge");
+  assert.ok(phase);
+  assert.deepEqual(
+    phase.breadcrumb.map((c) => c.label),
+    ["Plan Fanout", "Implement task", "Trial merge"],
+  );
+  assert.deepEqual(
+    phase.breadcrumb.map((c) => c.kind),
+    ["process", "subProcess", "subProcess"],
+  );
+  assert.equal(phase.fine, "Trial merge");
+});
+
+test("derivePhase builds a breadcrumb of enclosing named scopes down to the element", () => {
+  const idx = buildScopeIndex(MODEL);
+  const phase = derivePhase(idx, "review-plan");
+  assert.ok(phase);
+  assert.deepEqual(
+    phase.breadcrumb.map((c) => c.label),
+    ["Plan Fanout", "Plan", "Review plan"],
+  );
+  assert.deepEqual(
+    phase.breadcrumb.map((c) => c.kind),
+    ["process", "subProcess", "element"],
+  );
+  assert.equal(phase.process, "Plan Fanout");
+  assert.equal(phase.coarse, "Plan");
+  assert.equal(phase.fine, "Review plan");
+});
+
+test("derivePhase: coarse is the top-level subProcess even when nested deeper", () => {
+  const idx = buildScopeIndex(MODEL);
+  const phase = derivePhase(idx, "merge-attempt");
+  assert.ok(phase);
+  assert.deepEqual(
+    phase.breadcrumb.map((c) => c.label),
+    ["Plan Fanout", "Implement task", "Trial merge", "Merge attempt"],
+  );
+  // Outermost meaningful scope = the top-level subProcess directly under the process.
+  assert.equal(phase.coarse, "Implement task");
+  assert.equal(phase.fine, "Merge attempt");
+});
+
+test("derivePhase: a flat (process-level) element yields a task-granular phase for free", () => {
+  const idx = buildScopeIndex(MODEL);
+  const phase = derivePhase(idx, "start");
+  assert.ok(phase);
+  assert.deepEqual(
+    phase.breadcrumb.map((c) => c.label),
+    ["Plan Fanout", "Start"],
+  );
+  // No subProcess → coarse falls back to the process.
+  assert.equal(phase.coarse, "Plan Fanout");
+  assert.equal(phase.fine, "Start");
+});
+
+test("derivePhase granularity: auto is subProcess-then-element", () => {
+  const idx = buildScopeIndex(MODEL);
+  // Inside a subProcess → auto picks the coarse subProcess label.
+  assert.equal(derivePhase(idx, "review-plan")?.label, "Plan");
+  // Flat → auto falls to the element label.
+  assert.equal(derivePhase(idx, "start")?.label, "Start");
+});
+
+test("derivePhase granularity: subProcess and element force a level", () => {
+  const idx = buildScopeIndex(MODEL);
+  assert.equal(derivePhase(idx, "merge-attempt", { granularity: "subProcess" })?.label, "Implement task");
+  assert.equal(derivePhase(idx, "merge-attempt", { granularity: "element" })?.label, "Merge attempt");
+  // A flat element forced to subProcess granularity falls back to the process (no subProcess).
+  assert.equal(derivePhase(idx, "start", { granularity: "subProcess" })?.label, "Plan Fanout");
+});
+
+test("derivePhase: Tier-1 override replaces the structural label and flags its source", () => {
+  const idx = buildScopeIndex(MODEL);
+  const attrForm = derivePhase(idx, "finalize");
+  assert.ok(attrForm);
+  assert.equal(attrForm.fine, "Wrap up");
+  assert.equal(attrForm.breadcrumb.at(-1)?.source, "override");
+
+  const propForm = derivePhase(idx, "write-code");
+  assert.ok(propForm);
+  assert.equal(propForm.fine, "Coding (agent)");
+  assert.equal(propForm.breadcrumb.at(-1)?.source, "override");
+  // Its structural ancestors remain structural.
+  assert.equal(propForm.breadcrumb[0].source, "structural");
+});
+
+test("derivePhase: unnamed element falls back to its id (never blank)", () => {
+  const idx = buildScopeIndex(
+    `<bpmn:process id="p"><bpmn:task id="t42" /></bpmn:process>`,
+  );
+  const phase = derivePhase(idx, "t42");
+  assert.ok(phase);
+  assert.equal(phase.fine, "t42");
+  assert.equal(phase.breadcrumb.at(-1)?.source, "structural");
+});
+
+test("derivePhase returns undefined for an unknown element", () => {
+  const idx = buildScopeIndex(MODEL);
+  assert.equal(derivePhase(idx, "no-such-element"), undefined);
+});
+
+test("derivePhase tolerates namespace prefixes and entity-encoded names", () => {
+  const idx = buildScopeIndex(
+    `<process id="p" name="A &amp; B"><subProcess id="s" name="Wave &lt;1&gt;"><task id="t" name="Go" /></subProcess></process>`,
+  );
+  const phase = derivePhase(idx, "t");
+  assert.ok(phase);
+  assert.deepEqual(
+    phase.breadcrumb.map((c) => c.label),
+    ["A & B", "Wave <1>", "Go"],
+  );
+});
+
+test("buildScopeIndex tolerates a literal `>` inside a quoted attribute value (no tag truncation)", () => {
+  const idx = buildScopeIndex(
+    `<process id="p" name="Root"><subProcess id="s" name="Wave > 1"><task id="t" name="Go" nano:phase="P > Q" /></subProcess></process>`,
+  );
+  // The `>` inside `name="Wave > 1"` must not truncate the subProcess tag: its id/name and the
+  // task's namespaced phase override (which follows the inner `>`) all parse intact.
+  assert.equal(idx.elements.get("s")?.name, "Wave > 1");
+  assert.equal(idx.elements.get("t")?.name, "Go");
+  assert.equal(idx.elements.get("t")?.phaseOverride, "P > Q");
+  assert.deepEqual(idx.elements.get("t")?.scopeChain, ["p", "s"]);
+});
+
+test("buildScopeIndex parses single-quoted attribute values (id/name/nano:phase, valid XML)", () => {
+  // XML permits single-quoted attribute values; `attr()`/`phaseAttr()` must recognize them so
+  // ids, names, and namespaced phase overrides are not silently dropped (which would break scope
+  // chains). A double-quoted value that itself contains an apostrophe must survive intact too.
+  const idx = buildScopeIndex(
+    `<process id='p' name='Root'><subProcess id='s' name="Ada's Wave"><task id='t' name='Go' nano:phase='Do &amp; Review' /></subProcess></process>`,
+  );
+  assert.equal(idx.elements.get("s")?.name, "Ada's Wave");
+  assert.equal(idx.elements.get("t")?.name, "Go");
+  assert.equal(idx.elements.get("t")?.phaseOverride, "Do & Review");
+  assert.deepEqual(idx.elements.get("t")?.scopeChain, ["p", "s"]);
+});
+
+test("furthestReached picks the greatest seq per instance and ignores null joins", () => {
+  const rows: ProvenanceProgressRow[] = [
+    { instance_key: "i1", element_id: "start", seq: 1, at: "2024-01-01T00:00:00Z" },
+    { instance_key: "i1", element_id: "review-plan", seq: 5, at: "2024-01-01T00:05:00Z" },
+    { instance_key: "i1", element_id: "draft-plan", seq: 3, at: "2024-01-01T00:03:00Z" },
+    { instance_key: "i2", element_id: "finalize", seq: 2, at: "2024-01-01T00:02:00Z" },
+    { instance_key: null, element_id: "x", seq: 9 },
+    { instance_key: "i3", element_id: null, seq: 9 },
+  ];
+  const f = furthestReached(rows);
+  assert.equal(f.get("i1")?.elementId, "review-plan");
+  assert.equal(f.get("i1")?.seq, 5);
+  assert.equal(f.get("i2")?.elementId, "finalize");
+  assert.equal(f.has("i3"), false);
+  assert.equal(f.has(""), false);
+});
+
+test("deriveInstancePhases projects furthest element → phase per instance", () => {
+  const idx = buildScopeIndex(MODEL);
+  const rows: ProvenanceProgressRow[] = [
+    { instance_key: "i1", element_id: "draft-plan", seq: 1, at: "2024-01-01T00:01:00Z" },
+    { instance_key: "i1", element_id: "review-plan", seq: 2, at: "2024-01-01T00:02:00Z" },
+    { instance_key: "i2", element_id: "merge-attempt", seq: 3, at: "2024-01-01T00:03:00Z" },
+    // Furthest element belongs to a different deployed model → skipped.
+    { instance_key: "i3", element_id: "foreign-element", seq: 4, at: "2024-01-01T00:04:00Z" },
+  ];
+  const phases = deriveInstancePhases(idx, rows);
+  assert.equal(phases.get("i1")?.phase.label, "Plan");
+  assert.equal(phases.get("i1")?.seq, 2);
+  assert.equal(phases.get("i1")?.at, "2024-01-01T00:02:00Z");
+  assert.equal(phases.get("i2")?.phase.coarse, "Implement task");
+  assert.equal(phases.has("i3"), false);
+});
+
+test("rollupLineagePhase: epic frontier is the most-recently-advanced contributor", () => {
+  // Parent epic i-root fans out to two children; the child that advanced latest defines the frontier.
+  const edges: LineageEdge[] = [
+    { rootRequestKey: "i-root", instanceKey: "i-child-a", causedByInstanceKey: "i-root", edgeType: "weak" },
+    { rootRequestKey: "i-root", instanceKey: "i-child-b", causedByInstanceKey: "i-root", edgeType: "weak" },
+  ];
+  const tree = buildLineageTree("i-root", edges);
+  const idx = buildScopeIndex(MODEL);
+  const rows: ProvenanceProgressRow[] = [
+    { instance_key: "i-root", element_id: "draft-plan", seq: 1, at: "2024-01-01T00:01:00Z" },
+    { instance_key: "i-child-a", element_id: "review-plan", seq: 2, at: "2024-01-01T00:02:00Z" },
+    { instance_key: "i-child-b", element_id: "merge-attempt", seq: 3, at: "2024-01-01T00:09:00Z" },
+  ];
+  const phases = deriveInstancePhases(idx, rows);
+  const rollup = rollupLineagePhase(tree, phases);
+  assert.equal(rollup.rootRequestKey, "i-root");
+  assert.equal(rollup.frontier?.instanceKey, "i-child-b");
+  assert.equal(rollup.frontier?.phase.coarse, "Implement task");
+  assert.equal(rollup.contributions.length, 3);
+});
+
+test("rollupLineagePhase: frontier breaks ties on seq and folds in unattached nodes", () => {
+  const tree = buildLineageTree("i-root", [
+    { rootRequestKey: "i-root", instanceKey: "i-root", edgeType: "weak" },
+  ]);
+  // Two contributors with the SAME `at` — greater seq wins the tie.
+  const phaseByInstance = new Map<string, InstancePhase>([
+    [
+      "i-root",
+      { instanceKey: "i-root", phase: derivePhase(buildScopeIndex(MODEL), "start")!, seq: 1, at: "t" },
+    ],
+    // An orphan node not reachable from root but present via the phase map is still considered.
+    [
+      "i-orphan",
+      { instanceKey: "i-orphan", phase: derivePhase(buildScopeIndex(MODEL), "finalize")!, seq: 9, at: "t" },
+    ],
+  ]);
+  // Attach the orphan to tree.nodes so the rollup can see it.
+  const treeWithOrphan = {
+    ...tree,
+    nodes: [...tree.nodes, { instanceKey: "i-orphan", attachments: [], children: [] }],
+  };
+  const rollup = rollupLineagePhase(treeWithOrphan, phaseByInstance);
+  assert.equal(rollup.frontier?.instanceKey, "i-orphan");
+  assert.equal(rollup.contributions.length, 2);
+});
+
+test("rollupLineagePhase: no phased nodes → no frontier", () => {
+  const tree = buildLineageTree("i-root", [
+    { rootRequestKey: "i-root", instanceKey: "i-root", edgeType: "weak" },
+  ]);
+  const rollup = rollupLineagePhase(tree, new Map());
+  assert.equal(rollup.frontier, undefined);
+  assert.deepEqual(rollup.contributions, []);
+});
+
+test("buildScopeIndex is resilient to comments, CDATA and self-closing scopes", () => {
+  const idx = buildScopeIndex(
+    `<bpmn:process id="p" name="P">
+       <!-- a comment with <fake id="x" /> inside -->
+       <bpmn:subProcess id="s" name="S">
+         <bpmn:serviceTask id="t" name="T"><![CDATA[<not id="y"/>]]></bpmn:serviceTask>
+       </bpmn:subProcess>
+     </bpmn:process>`,
+  );
+  assert.equal(idx.elements.has("x"), false);
+  assert.equal(idx.elements.has("y"), false);
+  assert.deepEqual(idx.elements.get("t")?.scopeChain, ["p", "s"]);
+});