@nanobpm/urban 0.51.0 → 0.52.0

package/src/runtime/core/modules/lineage-store.ts

@@ -0,0 +1,239 @@
+// lineage-store — the durable read-model projection behind the lineage primitive (issue #254).
+//
+// A framework-level, per-source sidecar (like the write-provenance table) that materialises the
+// lineage edges the SDK auto-threads (`_urban.lineage`) and — where the engine emits it — the
+// native execution edge (`parentProcessInstanceKey`, Magikcraft/nano-bpm#808). `getLineage(root)`
+// unions both and returns the stitched descendant tree for one root request. Apps attach their own
+// domain rows (PRs, tasks) to a node via {@link LineageStore.attach} WITHOUT the framework knowing
+// their schema — the extension point that lets intent→progress visualisation be app-agnostic.
+//
+// The tree assembly itself is the pure {@link buildLineageTree}; this store is only its thin,
+// idempotent persistence + query layer, so recording the same instance twice (an engine job
+// re-activation) collapses to a no-op.
+
+import type { SqliteDb } from "../host.ts";
+import {
+  buildLineageTree,
+  type LineageAttachment,
+  type LineageEdge,
+  type LineageEdgeType,
+  type LineageTree,
+  readLineage,
+} from "../lineage.ts";
+
+/** The lineage edge table name. Framework bookkeeping, so `_urban_`-prefixed to stay hidden from
+ * the domain model / DB Manager (see `SqliteGateway.schema()`), like the migrations ledger. */
+export const LINEAGE_EDGES_TABLE = "_urban_lineage_edges";
+/** The lineage attachment table name (app-registered domain rows on a node). `_urban_`-prefixed for
+ * the same reason as {@link LINEAGE_EDGES_TABLE}. */
+export const LINEAGE_ATTACHMENTS_TABLE = "_urban_lineage_attachments";
+
+/**
+ * The canonical lineage DDL — the single source of truth applied by
+ * {@link LineageStore.ensureSchema}, mirrored verbatim by the boot migration
+ * `db/migrations/004_urban_lineage.sql` (a drift-guard test asserts they match).
+ *
+ * Forward-only and additive. `_urban_lineage_edges` is keyed by `(instance_key, edge_type)` so a
+ * node can hold both its weak (envelope) and strong (execution) edge at once and a re-record is a
+ * no-op; `_urban_lineage_attachments` is keyed by `(node_key, kind, ref)` so re-attaching the same
+ * domain row is idempotent. Both carry `root_request_key` with an index so a `getLineage(root)`
+ * reads only that thread.
+ */
+export const LINEAGE_SCHEMA_SQL = `CREATE TABLE IF NOT EXISTS ${LINEAGE_EDGES_TABLE} (
+  root_request_key       TEXT NOT NULL,
+  instance_key           TEXT NOT NULL,
+  caused_by_instance_key TEXT,
+  edge_type              TEXT NOT NULL DEFAULT 'weak',
+  created_at             TEXT NOT NULL,
+  PRIMARY KEY (instance_key, edge_type)
+);
+CREATE INDEX IF NOT EXISTS idx_${LINEAGE_EDGES_TABLE}_root ON ${LINEAGE_EDGES_TABLE} (root_request_key);
+CREATE TABLE IF NOT EXISTS ${LINEAGE_ATTACHMENTS_TABLE} (
+  root_request_key TEXT NOT NULL,
+  node_key         TEXT NOT NULL,
+  kind             TEXT NOT NULL,
+  ref              TEXT NOT NULL,
+  label            TEXT,
+  created_at       TEXT NOT NULL,
+  PRIMARY KEY (node_key, kind, ref)
+);
+CREATE INDEX IF NOT EXISTS idx_${LINEAGE_ATTACHMENTS_TABLE}_root ON ${LINEAGE_ATTACHMENTS_TABLE} (root_request_key);`;
+
+/** A monotonic wall clock, injectable for deterministic `created_at` in tests. */
+export interface Clock {
+  now(): number;
+}
+
+/** The default clock: `Date.now()`. */
+export const systemClock: Clock = { now: () => Date.now() };
+
+/** A minimal job shape {@link LineageStore.recordFromJob} reads — a structural subset of the
+ *  runtime's `EngineJob` plus the future engine execution edge (`parentProcessInstanceKey`,
+ *  Magikcraft/nano-bpm#808), consumed as a strong edge where present. */
+export interface LineageJobLike {
+  readonly processInstanceKey?: string;
+  readonly variables?: Record<string, unknown>;
+  /** The engine-native execution parent, when the engine emits it (#808). */
+  readonly parentProcessInstanceKey?: string;
+}
+
+export interface LineageStoreOptions {
+  readonly clock?: Clock;
+}
+
+interface EdgeRow {
+  root_request_key: string;
+  instance_key: string;
+  caused_by_instance_key: string | null;
+  edge_type: string;
+}
+
+interface AttachmentRow {
+  root_request_key: string;
+  node_key: string;
+  kind: string;
+  ref: string;
+  label: string | null;
+}
+
+function normalizeEdgeType(raw: string): LineageEdgeType {
+  return raw === "strong" ? "strong" : "weak";
+}
+
+export class LineageStore {
+  readonly #db: SqliteDb;
+  readonly #clock: Clock;
+
+  constructor(db: SqliteDb, options: LineageStoreOptions = {}) {
+    this.#db = db;
+    this.#clock = options.clock ?? systemClock;
+  }
+
+  /** Apply the canonical lineage DDL (idempotent). Callers whose app DataLayer applies the boot
+   *  migration `db/migrations/004_urban_lineage.sql` do not need this; the runtime calls it so the
+   *  store is usable against a bare source too. The DDL is identical to the migration (drift-guarded). */
+  ensureSchema(): void {
+    this.#db.exec(LINEAGE_SCHEMA_SQL);
+  }
+
+  /**
+   * Record one lineage edge, idempotently. A re-record of the same `(instance_key, edge_type)` is a
+   * no-op (an engine may re-activate a job on retry), so recording is safe to drive from any
+   * at-least-once observation point. A blank `rootRequestKey` or `instanceKey` is ignored.
+   */
+  recordEdge(edge: LineageEdge): boolean {
+    if (!edge.rootRequestKey || !edge.instanceKey) return false;
+    const { changes } = this.#db.run(
+      `INSERT OR IGNORE INTO ${LINEAGE_EDGES_TABLE}
+         (root_request_key, instance_key, caused_by_instance_key, edge_type, created_at)
+       VALUES (?, ?, ?, ?, ?)`,
+      [
+        edge.rootRequestKey,
+        edge.instanceKey,
+        edge.causedByInstanceKey ?? null,
+        edge.edgeType,
+        new Date(this.#clock.now()).toISOString(),
+      ],
+    );
+    return changes > 0;
+  }
+
+  /**
+   * Record the WEAK edge carried by an instance's `_urban.lineage` envelope. `instanceKey` is the
+   * effect/descendant node (a created instance's returned key, or a running job's own instance).
+   * A no-op when the variables carry no valid envelope.
+   */
+  recordEnvelope(instanceKey: string | undefined, variables: unknown): boolean {
+    if (!instanceKey) return false;
+    const env = readLineage(variables);
+    if (!env) return false;
+    return this.recordEdge({
+      rootRequestKey: env.rootRequestKey,
+      instanceKey,
+      causedByInstanceKey: env.causedByInstanceKey,
+      edgeType: "weak",
+    });
+  }
+
+  /**
+   * Record every edge an activated job reveals about its own instance: the weak envelope edge, and
+   * — where the engine supplies `parentProcessInstanceKey` (#808) — the strong execution edge under
+   * the same root. The natural single observation point for the worker runtime, since every instance
+   * that does work activates a job carrying its envelope. Never throws for a malformed job.
+   */
+  recordFromJob(job: LineageJobLike): void {
+    const env = readLineage(job.variables);
+    if (!env || !job.processInstanceKey) return;
+    this.recordEnvelope(job.processInstanceKey, job.variables);
+    if (job.parentProcessInstanceKey) {
+      this.recordEdge({
+        rootRequestKey: env.rootRequestKey,
+        instanceKey: job.processInstanceKey,
+        causedByInstanceKey: job.parentProcessInstanceKey,
+        edgeType: "strong",
+      });
+    }
+  }
+
+  /**
+   * Attach an app-defined domain row to a lineage node, idempotently. The framework stores it
+   * opaquely by `(node_key, kind, ref)` — it never interprets the app's schema. This is the
+   * extension point that lets an app hang its PRs/tasks off the lineage tree.
+   */
+  attach(rootRequestKey: string, attachment: LineageAttachment): boolean {
+    if (!rootRequestKey || !attachment.nodeKey || !attachment.kind || !attachment.ref) return false;
+    const { changes } = this.#db.run(
+      `INSERT OR IGNORE INTO ${LINEAGE_ATTACHMENTS_TABLE}
+         (root_request_key, node_key, kind, ref, label, created_at)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+      [
+        rootRequestKey,
+        attachment.nodeKey,
+        attachment.kind,
+        attachment.ref,
+        attachment.label ?? null,
+        new Date(this.#clock.now()).toISOString(),
+      ],
+    );
+    return changes > 0;
+  }
+
+  /** The persisted edges for one root, in insertion order. */
+  edges(rootRequestKey: string): LineageEdge[] {
+    const rows = this.#db.all<EdgeRow>(
+      `SELECT root_request_key, instance_key, caused_by_instance_key, edge_type
+         FROM ${LINEAGE_EDGES_TABLE} WHERE root_request_key = ? ORDER BY rowid`,
+      [rootRequestKey],
+    );
+    return rows.map((r) => ({
+      rootRequestKey: r.root_request_key,
+      instanceKey: r.instance_key,
+      causedByInstanceKey: r.caused_by_instance_key ?? undefined,
+      edgeType: normalizeEdgeType(r.edge_type),
+    }));
+  }
+
+  /** The persisted attachments for one root, in insertion order. */
+  attachments(rootRequestKey: string): LineageAttachment[] {
+    const rows = this.#db.all<AttachmentRow>(
+      `SELECT root_request_key, node_key, kind, ref, label
+         FROM ${LINEAGE_ATTACHMENTS_TABLE} WHERE root_request_key = ? ORDER BY rowid`,
+      [rootRequestKey],
+    );
+    return rows.map((r) => ({
+      nodeKey: r.node_key,
+      kind: r.kind,
+      ref: r.ref,
+      ...(r.label ? { label: r.label } : {}),
+    }));
+  }
+
+  /**
+   * The stitched descendant tree for `rootRequestKey`, unioning the weak (envelope) and strong
+   * (engine execution) edges and hanging each app attachment off its node. The generic read
+   * surface any Urban app queries for intent→progress.
+   */
+  getLineage(rootRequestKey: string): LineageTree {
+    return buildLineageTree(rootRequestKey, this.edges(rootRequestKey), this.attachments(rootRequestKey));
+  }
+}

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" });
+});

package/src/runtime/engine/nanosdk.ts

@@ -31,6 +31,7 @@ import {
 } from "../core/form-contract.ts";
 import type { EngineSdkClient } from "./sdk.ts";
 import { isRecord } from "../core/guards.ts";
+import { applyAmbientLineage } from "../core/lineage.ts";
 
 /** Coerce an engine response's process-instance key to a non-empty string, or
  * throw — a missing key means a malformed/partial response, not a real instance. */
@@ -193,9 +194,12 @@ export class SdkEngineClient implements EngineClient {
     variables?: Record<string, unknown>;
     awaitCompletion?: boolean;
   }): Promise<{ processInstanceKey: string; variables?: Record<string, unknown> }> {
+    // Auto-thread the `_urban.lineage` envelope (issue #254): a handler that spawns an
+    // instance propagates its `rootRequestKey` and stamps `causedByInstanceKey`; a genuine
+    // top-level request mints a fresh root. An explicit caller-supplied envelope wins.
     const body = await this.client.createProcessInstance({
       processDefinitionId: input.processDefinitionId,
-      variables: input.variables ?? {},
+      variables: applyAmbientLineage(input.variables),
       awaitCompletion: input.awaitCompletion ?? false,
     });
     const rawKey = body.processInstanceKey ?? body.key;
@@ -217,10 +221,12 @@ export class SdkEngineClient implements EngineClient {
     correlationKey?: string;
     variables?: Record<string, unknown>;
   }): Promise<void> {
+    // Message-started instances inherit lineage too (issue #254): thread the envelope onto the
+    // message variables so the instance the message starts carries `_urban.lineage`.
     await this.client.publishMessage({
       name: input.name,
       correlationKey: input.correlationKey ?? "",
-      variables: input.variables ?? {},
+      variables: applyAmbientLineage(input.variables),
     });
   }