@nanobpm/urban 0.50.0 → 0.52.0

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

@@ -549,6 +549,16 @@ table.pc-grid { width:100%; border-collapse:collapse; font-size:.9rem; table-lay
    neighbours. */
 table.pc-grid th, table.pc-grid td { text-align:left; padding:.4rem .6rem; border-bottom:1px solid var(--nano-edge); overflow-wrap:anywhere; word-wrap:break-word; vertical-align:top; }
 table.pc-grid th { font-weight:600; color:var(--nano-text-muted); }
+/* A cell's optional muted second line (col.subtitleField / subtitleTemplate):
+   the identity key rendered under the title, GitHub/Linear style. Plain DOM
+   text (never a link/href source), smaller and muted so the primary line leads. */
+.pc-cell-sub { font-size:.8rem; color:var(--nano-text-muted); margin-top:.1rem; }
+/* One-line clamp (col.truncate): stop a bounded column wrapping and show an
+   ellipsis, with the full value carried in a title=/aria-label tooltip. Needs a
+   bounded column (per-column width/weight) to clip against; a native <col> width
+   is honoured under table-layout:fixed. Applied to the primary and, when present,
+   the subtitle line so both stay single-line. */
+.pc-truncate { white-space:nowrap; overflow:hidden; text-overflow:ellipsis; }
 .pc-tabs { display:flex; gap:.5rem; margin-bottom:.75rem; }
 .pc-tab { padding:.35rem .8rem; border:1px solid var(--nano-edge); border-radius:.4rem; background:transparent; color:inherit; font:inherit; cursor:pointer; }
 .pc-tab.active { background:var(--nano-accent); color:var(--nano-on-accent); border-color:var(--nano-accent); }
@@ -1039,6 +1049,15 @@ function renderButton(node) {
 // tooltip stay keyed to the raw 'field' value (a badge shows a fixed glyph, not
 // the field text), so a template does not change badge behaviour. Sorting,
 // groupBy and orderBy also key off real fields, never the rendered template.
+//
+// Two-line identity + one-line clamp (additive, opt-in, backward-compatible):
+// a column may also declare 'subtitleField'/'subtitleTemplate' to render a muted
+// second line under the primary text (the identity key beneath a title, GitHub/
+// Linear style) and 'truncate: true' to clamp each line to one row with an
+// ellipsis and a full-text title/aria-label tooltip (pairs with a per-column
+// width/weight — see buildColgroup — to give the clip a bounded column). The
+// subtitle is ALWAYS plain DOM text, never an href source. With none of these
+// set the cell is a single inline node exactly as before (see cellTd).
 function gridCell(col, row) {
   // Raw single-field value: drives the badge presence gate + tooltip and any
   // field-derived defaults. Kept separate from the (possibly templated) display
@@ -1068,17 +1087,28 @@ function gridCell(col, row) {
       el("span", { class: "pc-badge pc-badge-" + tone, title: rawText, "aria-label": rawText }, label),
     );
   }
+  // Optional second line (col.subtitleField / subtitleTemplate): a muted key
+  // under the primary title. subtitleTemplate wins (interpolated from the row);
+  // else the raw subtitleField value. Absent/null → "" → no extra line. It is
+  // ALWAYS plain DOM text (see cellTd), never a link/href source — a subtitle
+  // cannot smuggle a scheme or path, only linkField/keyField drive hrefs.
+  const subRaw =
+    col.subtitleField != null && row[col.subtitleField] != null ? String(row[col.subtitleField]) : "";
+  const subText = typeof col.subtitleTemplate === "string" ? interpTemplate(col.subtitleTemplate, row) : subRaw;
+  const truncate = col.truncate === true;
+  // Primary inline content: an anchor for a valid link mode (checked in the same
+  // badge < linkField < link(page) < link(processExplorer) precedence as before),
+  // else the plain display text. Each link mode only claims the cell while
+  // 'primary' is still the bare text — an invalid href falls through to the next
+  // mode and ultimately to plain text, exactly as the early-return chain did.
+  let primary = text;
   if (col.linkField) {
     const href = row[col.linkField] == null ? "" : String(row[col.linkField]);
     if (text !== "" && /^https?:\/\//i.test(href)) {
-      return el(
-        "td",
-        {},
-        el("a", { class: "pc-link", href, target: "_blank", rel: "noopener noreferrer" }, text),
-      );
+      primary = el("a", { class: "pc-link", href, target: "_blank", rel: "noopener noreferrer" }, text);
     }
   }
-  if (col.link && col.link.kind === "page" && col.link.page && col.link.keyField) {
+  if (primary === text && col.link && col.link.kind === "page" && col.link.page && col.link.keyField) {
     // An in-app link to another page, scoped to this row: #/<page>/<key>. The
     // key (e.g. a plan_key "owner/repo#123") is URL-encoded into the route's
     // param tail, which parseRoute() decodes back verbatim; the page id is
@@ -1089,37 +1119,130 @@ function gridCell(col, row) {
     const keyStr = key == null ? "" : String(key).trim();
     if (text !== "" && safePageId(col.link.page) && keyStr !== "") {
       const href = "#/" + encodeURIComponent(col.link.page) + "/" + encodeURIComponent(keyStr);
-      return el("td", {}, el("a", { class: "pc-link", href }, text));
+      primary = el("a", { class: "pc-link", href }, text);
     }
   }
-  if (col.link && col.link.kind === "processExplorer" && col.link.keyField) {
+  if (primary === text && col.link && col.link.kind === "processExplorer" && col.link.keyField) {
     const key = row[col.link.keyField];
     const keyStr = key == null ? "" : String(key).trim();
     if (text !== "" && keyStr !== "") {
       const href = "/console/explorer?instance=" + encodeURIComponent(keyStr);
-      return el(
-        "td",
-        {},
-        el("a", {
-          class: "pc-link",
-          href,
-          target: "_blank",
-          rel: "noopener noreferrer",
-          // Embedded in the console a plain primary click routes the host's
-          // explorer in place (via the nano-navigate bridge) instead of opening
-          // a new window. A non-primary button (middle/right = new-tab/context
-          // intent), a modified click (⌘/ctrl/shift/alt = new-tab intent) and
-          // any standalone run fall through to the native anchor above.
-          onclick: (ev) => {
-            if (ev.button !== 0) return;
-            if (ev.metaKey || ev.ctrlKey || ev.shiftKey || ev.altKey) return;
-            if (hostNavigate("processExplorer", { instance: keyStr })) ev.preventDefault();
-          },
-        }, text),
-      );
+      primary = el("a", {
+        class: "pc-link",
+        href,
+        target: "_blank",
+        rel: "noopener noreferrer",
+        // Embedded in the console a plain primary click routes the host's
+        // explorer in place (via the nano-navigate bridge) instead of opening
+        // a new window. A non-primary button (middle/right = new-tab/context
+        // intent), a modified click (⌘/ctrl/shift/alt = new-tab intent) and
+        // any standalone run fall through to the native anchor above.
+        onclick: (ev) => {
+          if (ev.button !== 0) return;
+          if (ev.metaKey || ev.ctrlKey || ev.shiftKey || ev.altKey) return;
+          if (hostNavigate("processExplorer", { instance: keyStr })) ev.preventDefault();
+        },
+      }, text);
+    }
+  }
+  return cellTd(primary, text, subText, truncate);
+}
+
+// Compose a grid <td> from its primary inline content (a string or an anchor),
+// an optional muted subtitle line, and optional one-line truncation. With
+// NEITHER a subtitle nor truncation the cell is exactly the single inline node
+// as before, so existing grids render byte-for-byte unchanged (backward
+// compatible). When either is set the content is wrapped in a .pc-cell-main
+// line and, if a subtitle is present, a .pc-cell-sub line beneath it. truncate
+// adds .pc-truncate (nowrap + ellipsis) to each line and mirrors the full text
+// into title=/aria-label so the clipped value is still recoverable on hover and
+// to assistive tech. When the primary is an element (a link cell's <a>), title=/
+// aria-label= are ALSO mirrored onto it: HTML does not inherit those to
+// descendants, so hovering the link text or naming the anchor for assistive tech
+// would otherwise miss the full value the wrapper carries. The subtitle is set as
+// DOM text only — never an href.
+function cellTd(primary, primaryText, subText, truncate) {
+  if (subText === "" && !truncate) return el("td", {}, primary);
+  const mainAttrs = { class: "pc-cell-main" + (truncate ? " pc-truncate" : "") };
+  if (truncate && primaryText !== "") {
+    mainAttrs.title = primaryText; mainAttrs["aria-label"] = primaryText;
+    if (primary && typeof primary.setAttribute === "function") {
+      primary.setAttribute("title", primaryText); primary.setAttribute("aria-label", primaryText);
+    }
+  }
+  const main = el("div", mainAttrs, primary);
+  if (subText === "") return el("td", {}, main);
+  const subAttrs = { class: "pc-cell-sub" + (truncate ? " pc-truncate" : "") };
+  if (truncate) { subAttrs.title = subText; subAttrs["aria-label"] = subText; }
+  return el("td", {}, main, el("div", subAttrs, subText));
+}
+
+// Parse a "<number>%" width into its numeric percentage, or null if the string
+// is not a bare percentage (e.g. "22rem", "120px") — used to decide whether the
+// remainder left for weighted columns can be computed.
+function colWidthPct(width) {
+  const m = /^\s*([0-9]*\.?[0-9]+)%\s*$/.exec(width);
+  return m ? parseFloat(m[1]) : null;
+}
+
+// A column carries an explicit width only when it is a non-empty string. Single
+// source of truth so colWidthStyle/buildColgroup can't drift on what "explicit"
+// means (which columns win verbatim, consume the remainder, or use their weight).
+function hasExplicitWidth(col) {
+  return typeof col.width === "string" && col.width !== "";
+}
+
+// A column's <col> width for the grid's <colgroup>: an explicit col.width string
+// ("40%", "22rem") wins verbatim; else a positive numeric col.weight is
+// normalised across the weighted columns into a percentage share of the width
+// left over by explicit columns (remainderPct); else null (no width — the column
+// shares the remainder equally under table-layout:fixed).
+function colWidthStyle(col, weightTotal, remainderPct) {
+  if (hasExplicitWidth(col)) return col.width;
+  if (typeof col.weight === "number" && col.weight > 0 && weightTotal > 0) {
+    return Math.round((col.weight / weightTotal) * remainderPct * 100) / 100 + "%";
+  }
+  return null;
+}
+
+// Build a <colgroup> that sizes the grid's columns so table-layout:fixed stops
+// splitting width equally. Returns null when no column declares width/weight, so
+// an unsized grid emits no colgroup and lays out exactly as today. 'extraCount'
+// adds trailing unsized <col>s for the row-actions/detail column so the sized
+// data columns stay aligned with their headers.
+function buildColgroup(cols, extraCount) {
+  const hasSizing = cols.some(
+    (c) => hasExplicitWidth(c) || (typeof c.weight === "number" && c.weight > 0),
+  );
+  if (!hasSizing) return null;
+  // Only columns that will actually use their weight (no explicit width — an
+  // explicit width wins verbatim in colWidthStyle and never consumes weight)
+  // contribute to weightTotal; counting a width-bearing column's weight here
+  // would inflate the divisor and shrink the truly-weighted columns' share.
+  let weightTotal = 0;
+  for (const c of cols)
+    if (!hasExplicitWidth(c) && typeof c.weight === "number" && c.weight > 0) weightTotal += c.weight;
+  // Weighted columns share only the width the explicit columns leave behind, so
+  // mixing e.g. width:"40%" with weighted columns can't oversubscribe past 100%.
+  // The remainder is only computable when every explicit width is a percentage;
+  // if any uses an absolute/relative unit (rem/px) we can't subtract it from
+  // 100%, so weighted columns fall back to a share of the full width.
+  let explicitPctTotal = 0;
+  let allExplicitArePct = true;
+  for (const c of cols) {
+    if (hasExplicitWidth(c)) {
+      const pct = colWidthPct(c.width);
+      if (pct === null) allExplicitArePct = false;
+      else explicitPctTotal += pct;
     }
   }
-  return el("td", {}, text);
+  const remainderPct = allExplicitArePct ? Math.max(0, 100 - explicitPctTotal) : 100;
+  const colEls = cols.map((c) => {
+    const w = colWidthStyle(c, weightTotal, remainderPct);
+    return el("col", w ? { style: "width:" + w } : {});
+  });
+  for (let i = 0; i < extraCount; i++) colEls.push(el("col", {}));
+  return el("colgroup", {}, ...colEls);
 }
 
 function renderActionForm(node) {
@@ -1315,7 +1438,13 @@ function renderDataGrid(node) {
   if (hasExtra) headCells.push(el("th", {}, ""));
   const thead = el("thead", {}, el("tr", {}, ...headCells));
   const tbody = el("tbody", {});
-  const table = el("table", { class: "pc-grid" }, thead, tbody);
+  // A <colgroup> (present only when a column declares width/weight) sizes the
+  // columns so table-layout:fixed stops splitting width equally; it must precede
+  // <thead> in the table.
+  const colgroup = buildColgroup(cols, hasExtra ? 1 : 0);
+  const table = colgroup
+    ? el("table", { class: "pc-grid" }, colgroup, thead, tbody)
+    : el("table", { class: "pc-grid" }, thead, tbody);
   card.append(table);
   const span = String((cols.length || 1) + (hasExtra ? 1 : 0));
 
@@ -1407,9 +1536,12 @@ function renderDataGrid(node) {
     if (cg.title) wrap.append(el("div", { class: "pc-child-title" }, cg.title));
     const ccols = cg.columns || [];
     const cbody = el("tbody", {});
-    const ctable = el("table", { class: "pc-grid" },
-      el("thead", {}, el("tr", {}, ...ccols.map((c) => el("th", {}, c.header || c.field)),
-        ...(cg.lazyField ? [el("th", {}, "")] : []))), cbody);
+    const ccolgroup = buildColgroup(ccols, cg.lazyField ? 1 : 0);
+    const cthead = el("thead", {}, el("tr", {}, ...ccols.map((c) => el("th", {}, c.header || c.field)),
+      ...(cg.lazyField ? [el("th", {}, "")] : [])));
+    const ctable = ccolgroup
+      ? el("table", { class: "pc-grid" }, ccolgroup, cthead, cbody)
+      : el("table", { class: "pc-grid" }, cthead, cbody);
     wrap.append(ctable);
     try {
       const { rows } = await getJSON(dataUrl(cg.source || "app", cg.table,

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/engine/nanosdk.test.ts

@@ -11,6 +11,9 @@ import {
   type NanoSdkJobWorkerConfig,
 } from "./nanosdk.ts";
 import { BpmnError } from "../core/host.ts";
+import { __resetExecStoreForTests, installExecStore, runInJobContext } from "../core/execContext.ts";
+import { readLineage } from "../core/lineage.ts";
+import { createNodeHost } from "../adapters/node.ts";
 
 /** A fake nano-sdk client that records calls and lets a test drive its job worker. */
 function fakeSdkClient(overrides: Partial<NanoSdkClient> = {}): NanoSdkClient & {
@@ -133,7 +136,8 @@ test("createInstance routes through the SDK and coerces the key", async () => {
   const engine = new SdkEngineClient(client);
   const res = await engine.createInstance({ processDefinitionId: "p", variables: { a: 1 } });
   assert.equal(res.processInstanceKey, "99");
-  assert.deepEqual(res.variables, { a: 1 });
+  // Caller variables are preserved (the SDK also auto-threads a `_urban.lineage` envelope, tested below).
+  assert.equal(res.variables?.a, 1);
   assert.ok(client.calls.includes("createProcessInstance"));
 });
 
@@ -162,7 +166,7 @@ test("cancelInstance routes through the SDK", async () => {
   assert.ok(client.calls.includes("cancelProcessInstance") || seen !== undefined);
 });
 
-test("publishMessage defaults correlationKey/variables", async () => {
+test("publishMessage defaults correlationKey and auto-threads lineage onto variables", async () => {
   let seen: Record<string, unknown> | undefined;
   const client = fakeSdkClient({
     publishMessage: async (input) => {
@@ -172,7 +176,12 @@ test("publishMessage defaults correlationKey/variables", async () => {
   });
   const engine = new SdkEngineClient(client);
   await engine.publishMessage({ name: "m" });
-  assert.deepEqual(seen, { name: "m", correlationKey: "", variables: {} });
+  assert.equal(seen?.name, "m");
+  assert.equal(seen?.correlationKey, "");
+  // With no ambient job context this is a top-level publish: a fresh root envelope is minted.
+  const env = readLineage(seen?.variables);
+  assert.ok(env, "a lineage envelope is threaded onto the message variables");
+  assert.equal(env?.causedByInstanceKey, undefined);
 });
 
 test("searchUserTasks passes zero-wait consistency and maps items", async () => {
@@ -670,3 +679,88 @@ test("createNanoSdkEngineClient uses an injected client factory with the resolve
   assert.deepEqual(seen, { restAddress: "http://x/v2", token: "t", transport: "falcon" });
   assert.ok(engine);
 });
+
+// --- Lineage auto-threading (issue #254) ---------------------------------------
+
+/** A fake client that captures the variables handed to createProcessInstance/publishMessage. */
+function capturingClient(): NanoSdkClient & { createVars?: Record<string, unknown>; msgVars?: Record<string, unknown> } {
+  const base = fakeSdkClient();
+  const cap: NanoSdkClient & { createVars?: Record<string, unknown>; msgVars?: Record<string, unknown> } = {
+    ...base,
+    async createProcessInstance(input) {
+      cap.createVars = input.variables;
+      return { processInstanceKey: 99, variables: input.variables };
+    },
+    async publishMessage(input) {
+      cap.msgVars = input.variables;
+      return { key: 1 };
+    },
+  };
+  return cap;
+}
+
+test("createInstance mints a fresh root envelope for a top-level request (no ambient)", async () => {
+  __resetExecStoreForTests();
+  const client = capturingClient();
+  const engine = new SdkEngineClient(client);
+  await engine.createInstance({ processDefinitionId: "p", variables: { a: 1 } });
+  const env = readLineage(client.createVars);
+  assert.ok(env, "an envelope was threaded onto the variables");
+  assert.notEqual(env?.rootRequestKey, "");
+  assert.equal(env?.causedByInstanceKey, undefined, "a fresh root has no cause");
+  assert.equal(client.createVars?.a, 1, "caller variables are preserved");
+});
+
+test("createInstance propagates the ambient lineage and stamps causedByInstanceKey", async () => {
+  __resetExecStoreForTests();
+  const host = createNodeHost({ cwd: process.cwd(), log: () => {} });
+  installExecStore(() => host.createAsyncStore?.());
+  const client = capturingClient();
+  const engine = new SdkEngineClient(client);
+  try {
+    await runInJobContext({ instanceKey: "pi-parent", rootRequestKey: "root-1", jobType: "w" }, () =>
+      engine.createInstance({ processDefinitionId: "child" }),
+    );
+  } finally {
+    __resetExecStoreForTests();
+  }
+  assert.deepEqual(readLineage(client.createVars), {
+    rootRequestKey: "root-1",
+    causedByInstanceKey: "pi-parent",
+  });
+});
+
+test("createInstance leaves an explicit caller-supplied envelope untouched (override wins)", async () => {
+  __resetExecStoreForTests();
+  const host = createNodeHost({ cwd: process.cwd(), log: () => {} });
+  installExecStore(() => host.createAsyncStore?.());
+  const client = capturingClient();
+  const engine = new SdkEngineClient(client);
+  try {
+    await runInJobContext({ instanceKey: "pi-parent", rootRequestKey: "root-1", jobType: "w" }, () =>
+      engine.createInstance({
+        processDefinitionId: "child",
+        variables: { _urban: { lineage: { rootRequestKey: "explicit" } } },
+      }),
+    );
+  } finally {
+    __resetExecStoreForTests();
+  }
+  assert.deepEqual(readLineage(client.createVars), { rootRequestKey: "explicit", causedByInstanceKey: undefined });
+});
+
+test("publishMessage threads lineage so message-started instances inherit it", async () => {
+  __resetExecStoreForTests();
+  const host = createNodeHost({ cwd: process.cwd(), log: () => {} });
+  installExecStore(() => host.createAsyncStore?.());
+  const client = capturingClient();
+  const engine = new SdkEngineClient(client);
+  try {
+    await runInJobContext({ instanceKey: "pi-9", rootRequestKey: "root-9", jobType: "w" }, () =>
+      engine.publishMessage({ name: "start" }),
+    );
+  } finally {
+    __resetExecStoreForTests();
+  }
+  assert.deepEqual(readLineage(client.msgVars), { rootRequestKey: "root-9", causedByInstanceKey: "pi-9" });
+});