@nanobpm/urban 0.50.0 → 0.52.0

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),
     });
   }
 

package/src/runtime/index.ts

@@ -143,6 +143,41 @@ export type {
 } from "./core/modules/llm.ts";
 export { evalCorrelation } from "./core/modules/triggers.ts";
 
+// Lineage — the framework-level lineage primitive (issue #254): the `_urban.lineage`
+// envelope + auto-threading, and the generic read projection that stitches user intent →
+// progress (a root request → the instances/PRs/tasks it causes).
+export {
+  applyAmbientLineage,
+  buildLineageTree,
+  deriveLineage,
+  LINEAGE_KEY,
+  LINEAGE_NAMESPACE,
+  mintRootRequestKey,
+  readLineage,
+  writeLineage,
+} from "./core/lineage.ts";
+export type {
+  ApplyLineageOptions,
+  LineageAttachment,
+  LineageEdge,
+  LineageEdgeType,
+  LineageEnvelope,
+  LineageNode,
+  LineageTree,
+} from "./core/lineage.ts";
+export {
+  LINEAGE_ATTACHMENTS_TABLE,
+  LINEAGE_EDGES_TABLE,
+  LINEAGE_SCHEMA_SQL,
+  LineageStore,
+  systemClock as lineageSystemClock,
+} from "./core/modules/lineage-store.ts";
+export type {
+  Clock as LineageClock,
+  LineageJobLike,
+  LineageStoreOptions,
+} from "./core/modules/lineage-store.ts";
+
 // Model deploy (deploy-by-convention under `resources/`, ADR 0062)
 export { deployModels, RESOURCES_DIR } from "./core/modules/deploy.ts";
 export { defaultScheduler, MAX_TIMER_DELAY_MS } from "./core/modules/scheduler.ts";