@nanobpm/urban 0.51.0 → 0.53.0

package/dist/runtime/core/extensions.d.ts

@@ -0,0 +1,131 @@
+import type { AppApi, Mounted } from "./context.ts";
+import type { Logger } from "./logger.ts";
+import { EventBus, type Disposer, type DispatchMode, type EmitChannel, type ParallelChannel, type SerialChannel, type WaterfallChannel } from "./events.ts";
+export declare const URBAN_EVENT_MODES: {
+    /** Boot / start / stop notifications — observers never change the outcome. */
+    readonly lifecycle: "emit";
+    /** The ordered extension-registration checkpoint (this module's first consumer). */
+    readonly "extension/register": "serial";
+    /** Request / action dispatch — around-middleware for transform / short-circuit. */
+    readonly "request/dispatch": "waterfall";
+    /** Security / permission gate — a listener may short-circuit with a deny. */
+    readonly "security/gate": "waterfall";
+    /** Instance-tracking reconcile — fan-out where every listener gets its chance. */
+    readonly reconcile: "parallel";
+};
+export type UrbanEventName = keyof typeof URBAN_EVENT_MODES;
+/** A boot/start/stop lifecycle notification (the `lifecycle` emit seam). */
+export interface LifecycleEvent {
+    readonly app: string;
+    readonly phase: "starting" | "started" | "stopping" | "stopped";
+}
+/** The payload handed to each extension as it registers (the `extension/register`
+ *  serial seam): the just-registered extension plus its setup context. */
+export interface ExtensionRegistered {
+    readonly extension: string;
+    readonly context: ExtensionSetupContext;
+}
+/** A request/action flowing through the `request/dispatch` waterfall seam. An
+ *  extension middleware may transform it, short-circuit with a response, or
+ *  recover a downstream throw. Kept transport-agnostic on purpose. */
+export interface DispatchRequest {
+    readonly kind: string;
+    readonly payload: unknown;
+}
+export interface DispatchResponse {
+    readonly handled: boolean;
+    readonly payload: unknown;
+}
+/** A permission check flowing through the `security/gate` waterfall seam. A
+ *  listener that denies short-circuits (never calls `next`). */
+export interface GateRequest {
+    readonly subject: string;
+    readonly action: string;
+    readonly resource: string;
+}
+export interface GateDecision {
+    readonly allow: boolean;
+    readonly reason?: string;
+}
+/** A reconcile tick fanned out on the `reconcile` parallel seam. */
+export interface ReconcileEvent {
+    readonly source: string;
+    readonly at: number;
+}
+/** The typed Urban extension-event taxonomy: one channel per seam, each already
+ *  bound to its declared dispatch mode. Modules and extensions adopt seams by
+ *  registering on these channels; the dispatch semantics come from the channel,
+ *  not the call site. */
+export interface UrbanEvents {
+    /** **emit** — lifecycle notifications. */
+    readonly lifecycle: EmitChannel<LifecycleEvent>;
+    /** **serial** — the ordered extension-registration checkpoint. */
+    readonly extensionRegister: SerialChannel<ExtensionRegistered>;
+    /** **waterfall** — request/action dispatch middleware. */
+    readonly requestDispatch: WaterfallChannel<DispatchRequest, DispatchResponse>;
+    /** **waterfall** — security/permission gate (short-circuit deny). */
+    readonly securityGate: WaterfallChannel<GateRequest, GateDecision>;
+    /** **parallel** — instance-tracking reconcile fan-out. */
+    readonly reconcile: ParallelChannel<ReconcileEvent>;
+}
+/** Declare the whole Urban taxonomy on a bus — each seam exactly once, with the
+ *  mode `URBAN_EVENT_MODES` records for it. */
+export declare function createUrbanEvents(bus: EventBus): UrbanEvents;
+/** Assert (at construction) that the typed taxonomy and the documented mode table
+ *  agree — a guard against the two drifting apart. */
+export declare function urbanEventMode(name: UrbanEventName): DispatchMode;
+/** What an extension's `setup()` gets: the app API, the typed taxonomy to hook
+ *  onto, a structured logger, and `effect()` to hang any other disposable resource
+ *  (a timer, a subscription) on the dispose ladder. */
+export interface ExtensionSetupContext {
+    readonly app: AppApi;
+    readonly events: UrbanEvents;
+    readonly log: Logger;
+    /** Register a disposable effect (a timer, listener, subscription). It joins the
+     *  dispose ladder, so `stop()` / HMR tears it down with everything else. Returns
+     *  the idempotent disposer so an extension can clean up early — which also detaches
+     *  the effect from the ladder, so `stop()` won't run it a second time. */
+    effect(dispose: Disposer): Disposer;
+}
+/** A pluggable Urban extension — the uniform shape an agentic family or a
+ *  connector pack presents to the runtime. `setup()` wires the extension onto the
+ *  taxonomy; anything it registers is an effect on the dispose ladder. */
+export interface UrbanExtension {
+    readonly name: string;
+    /** Explicit ordering for the `extension/register` serial checkpoint; lower runs
+     *  first. Extensions with equal (or absent) order keep registration order. */
+    readonly order?: number;
+    setup(context: ExtensionSetupContext): void | Promise<void>;
+}
+export interface ExtensionHost extends Mounted {
+    /** The typed taxonomy this host mounted the extensions onto. */
+    readonly events: UrbanEvents;
+    /** Live registration count on the bus — proxies `EventBus.listenerCount`, so it
+     *  counts every channel listener AND every `effect()` on the dispose ladder, not
+     *  only channel listeners. 0 after a `stop()` that owns its bus. Use it for leak
+     *  assertions. */
+    readonly listenerCount: number;
+}
+export interface MountExtensionsOptions {
+    /** Reports a contained extension throw (defaults to the app logger's `warn`).
+     *  Only honoured when `mountExtensions` creates its *own* private bus (i.e. `bus`
+     *  and `events` are omitted). When a shared `bus` is passed, that bus already owns
+     *  its error sink and this option is ignored — set the sink on the shared bus. */
+    onError?: (err: unknown, info: {
+        event: string;
+        mode: DispatchMode;
+    }) => void;
+    /** A pre-built taxonomy/bus to mount onto (the runtime shares one app-wide). When
+     *  omitted a private bus is created — handy for isolated tests. */
+    bus?: EventBus;
+    events?: UrbanEvents;
+}
+/** Run `extensions` through the taxonomy: deterministically order them, `setup()`
+ *  each directly (a throwing extension is contained and never strands the others
+ *  or app boot), then notify the `extension/register` serial checkpoint so
+ *  observers react in a deterministic order, and return a `Mounted` whose `stop()`
+ *  disposes the bus — unwinding the whole dispose ladder LIFO — only when
+ *  `mountExtensions` created that bus; onto a shared app-wide bus, disposal is the
+ *  caller's responsibility. So a start→stop→start cycle (or HMR reload) over an
+ *  owned bus leaks no listeners. */
+export declare function mountExtensions(api: AppApi, extensions: readonly UrbanExtension[], options?: MountExtensionsOptions): Promise<ExtensionHost>;

package/dist/runtime/core/extensions.js

@@ -0,0 +1,137 @@
+// extensions — the typed Urban **extension-event taxonomy** and the extension host
+// that runs the agentic-family / connector-pack surface through it (issue #262).
+//
+// `runtime.ts` used to wire every module directly and let extensions reach for
+// whatever they needed; ordering and failure-isolation were implicit. This module
+// formalizes the extension seams as a small set of **typed channels**, each with a
+// declared dispatch mode (see `events.ts`), and gives extensions a single, uniform
+// way to plug in: a `UrbanExtension` whose `setup()` registers listeners and
+// disposable effects onto the app's dispose ladder.
+//
+// The first concrete consumer is exactly the informal plugin surface Urban already
+// stresses today: nwf's agentic families ("drop a family module under
+// `app/agentic/families/`, never edit `main.ts`") and connector packs. Each becomes
+// a `UrbanExtension`; the runtime runs them through the `extension/register` serial
+// checkpoint in a deterministic order, and everything they register tears down on
+// `stop()` / dev-server HMR because it rode the dispose ladder.
+import { EventBus, } from "./events.js";
+// ---------------------------------------------------------------------------
+// The taxonomy — the documented set of typed Urban extension events.
+//
+// Each seam is a canonical event *name* paired with its deliberate *dispatch
+// mode*. This object is the single source of truth for the modes; the ADR's
+// "feature → mechanism map" and the typed `UrbanEvents` channels below are both
+// checked against it — `createUrbanEvents` enumerates the seams by hand, but a
+// drift-guard test asserts every channel's `.mode` equals `URBAN_EVENT_MODES`
+// for its seam (and that coverage is exact), so the docs and the code cannot
+// silently drift.
+// ---------------------------------------------------------------------------
+export const URBAN_EVENT_MODES = {
+    /** Boot / start / stop notifications — observers never change the outcome. */
+    "lifecycle": "emit",
+    /** The ordered extension-registration checkpoint (this module's first consumer). */
+    "extension/register": "serial",
+    /** Request / action dispatch — around-middleware for transform / short-circuit. */
+    "request/dispatch": "waterfall",
+    /** Security / permission gate — a listener may short-circuit with a deny. */
+    "security/gate": "waterfall",
+    /** Instance-tracking reconcile — fan-out where every listener gets its chance. */
+    "reconcile": "parallel",
+};
+/** Declare the whole Urban taxonomy on a bus — each seam exactly once, with the
+ *  mode `URBAN_EVENT_MODES` records for it. */
+export function createUrbanEvents(bus) {
+    return {
+        lifecycle: bus.emit("lifecycle"),
+        extensionRegister: bus.serial("extension/register"),
+        requestDispatch: bus.waterfall("request/dispatch"),
+        securityGate: bus.waterfall("security/gate"),
+        reconcile: bus.parallel("reconcile"),
+    };
+}
+/** Assert (at construction) that the typed taxonomy and the documented mode table
+ *  agree — a guard against the two drifting apart. */
+export function urbanEventMode(name) {
+    return URBAN_EVENT_MODES[name];
+}
+/** Run `extensions` through the taxonomy: deterministically order them, `setup()`
+ *  each directly (a throwing extension is contained and never strands the others
+ *  or app boot), then notify the `extension/register` serial checkpoint so
+ *  observers react in a deterministic order, and return a `Mounted` whose `stop()`
+ *  disposes the bus — unwinding the whole dispose ladder LIFO — only when
+ *  `mountExtensions` created that bus; onto a shared app-wide bus, disposal is the
+ *  caller's responsibility. So a start→stop→start cycle (or HMR reload) over an
+ *  owned bus leaks no listeners. */
+export async function mountExtensions(api, extensions, options = {}) {
+    const log = api.log.child({ module: "extensions" });
+    // Share a caller-owned bus+taxonomy or build a private pair — never a mismatched
+    // one. With only `events`, listeners would register on its bus while `effect()`
+    // and disposal target a *different* private bus (leaked registrations, and a
+    // reused bus could redeclare channels); with only `bus`, callers lose the typed
+    // taxonomy they meant to share. Require both-or-neither.
+    if ((options.bus === undefined) !== (options.events === undefined)) {
+        throw new Error("mountExtensions: `bus` and `events` must be provided together or both omitted");
+    }
+    // Ownership: a bus we created is ours to dispose; a shared app-wide bus belongs
+    // to the caller (the runtime disposes it in teardown). `stop()` honours this so
+    // it never unwinds registrations it did not make.
+    const ownsBus = options.bus === undefined;
+    const bus = options.bus ??
+        new EventBus({
+            onError: options.onError ??
+                ((err, info) => log.warn("extension listener threw and was contained", { event: info.event, mode: info.mode, error: String(err) })),
+        });
+    const events = options.events ?? createUrbanEvents(bus);
+    // Deterministic order: primary by `order` (default 0), stable within ties by the
+    // order the host handed them to us. A sibling dropping a family module gets a
+    // predictable slot without editing anyone else's registration.
+    const ordered = extensions
+        .map((extension, index) => ({ extension, index }))
+        .sort((a, b) => (a.extension.order ?? 0) - (b.extension.order ?? 0) || a.index - b.index)
+        .map((entry) => entry.extension);
+    const context = {
+        app: api,
+        events,
+        log,
+        effect(dispose) {
+            return bus.effect(dispose);
+        },
+    };
+    for (const extension of ordered) {
+        // `setup()` is the checkpoint's unit of work, made atomic by a per-extension
+        // rollback scope: a throw is contained here so one bad extension never strands
+        // app boot or its siblings, AND its partial registrations are rolled back so a
+        // "failed" extension can't leave live listeners/effects that influence later
+        // dispatches or leak on teardown.
+        const rollback = bus.scope();
+        try {
+            await extension.setup(context);
+        }
+        catch (err) {
+            rollback();
+            log.warn("extension setup threw and was contained", { extension: extension.name, error: String(err) });
+            continue;
+        }
+        // Notify the ordered `extension/register` serial checkpoint so observers react
+        // in a deterministic order (also contained, per `SerialChannel.run`).
+        await events.extensionRegister.run({ extension: extension.name, context });
+        log.info("extension mounted", { extension: extension.name });
+    }
+    return {
+        name: "extensions",
+        events,
+        get listenerCount() {
+            return bus.listenerCount;
+        },
+        async stop() {
+            // Only dispose a bus we own. When the runtime shares its app-wide bus, tearing
+            // it down here would unwind unrelated core registrations — disposal is then the
+            // owner's job (runtime teardown calls `bus.dispose()`).
+            if (ownsBus)
+                bus.dispose();
+        },
+        describe() {
+            return { extensions: ordered.map((e) => e.name), listeners: bus.listenerCount };
+        },
+    };
+}

package/dist/runtime/core/glob.d.ts

@@ -4,11 +4,12 @@ export declare function expandPattern(host: HostContext, root: string, pattern:
 /** Expand many patterns, de-duplicating while preserving first-seen order. */
 export declare function expandPatterns(host: HostContext, root: string, patterns: string[] | undefined): Promise<string[]>;
 /**
- * Discover deployables under a convention directory (`resources/`), **shallow, one level deep**:
- * the files directly under `dir` plus the files one sub-directory down (`dir/<subdir>/*`), but
- * never deeper. The shallow bound is deliberate — deploy dedupes by basename (filename only), so a
- * deep recursive walk would reintroduce cross-directory basename-collision risk. Sub-directory
- * descent needs `host.listSubdirs`; a host that can't enumerate directories yields only the
- * top-level files. Returns root-prefixed paths, sorted for determinism.
+ * Discover deployables under a convention directory (`resources/`), **recursively** — every file
+ * directly under `dir` and under every sub-directory at any depth (issue #231). Recursive descent
+ * is safe because deploy now keys a convention resource by its path *relative to* `resources/`
+ * (POSIX), not its bare basename, so two files sharing a filename in different sub-dirs
+ * (`a/x.md`, `b/x.md`) resolve to distinct `resourceId`s and can never collide. Descent needs
+ * `host.listSubdirs`; a host that can't enumerate directories yields only the top-level files.
+ * Returns root-prefixed paths, sorted for determinism.
  */
 export declare function discoverResources(host: HostContext, root: string, dir: string): Promise<string[]>;

package/dist/runtime/core/glob.js

@@ -50,23 +50,25 @@ export async function expandPatterns(host, root, patterns) {
     return out;
 }
 /**
- * Discover deployables under a convention directory (`resources/`), **shallow, one level deep**:
- * the files directly under `dir` plus the files one sub-directory down (`dir/<subdir>/*`), but
- * never deeper. The shallow bound is deliberate — deploy dedupes by basename (filename only), so a
- * deep recursive walk would reintroduce cross-directory basename-collision risk. Sub-directory
- * descent needs `host.listSubdirs`; a host that can't enumerate directories yields only the
- * top-level files. Returns root-prefixed paths, sorted for determinism.
+ * Discover deployables under a convention directory (`resources/`), **recursively** — every file
+ * directly under `dir` and under every sub-directory at any depth (issue #231). Recursive descent
+ * is safe because deploy now keys a convention resource by its path *relative to* `resources/`
+ * (POSIX), not its bare basename, so two files sharing a filename in different sub-dirs
+ * (`a/x.md`, `b/x.md`) resolve to distinct `resourceId`s and can never collide. Descent needs
+ * `host.listSubdirs`; a host that can't enumerate directories yields only the top-level files.
+ * Returns root-prefixed paths, sorted for determinism.
  */
 export async function discoverResources(host, root, dir) {
     const base = joinPath(root, dir);
     const out = [];
-    for (const name of await host.listDir(base))
-        out.push(joinPath(base, name));
-    const subdirs = host.listSubdirs ? await host.listSubdirs(base) : [];
-    for (const sub of subdirs.slice().sort()) {
-        const subBase = joinPath(base, sub);
-        for (const name of await host.listDir(subBase))
-            out.push(joinPath(subBase, name));
-    }
+    const walk = async (current) => {
+        for (const name of await host.listDir(current))
+            out.push(joinPath(current, name));
+        const subdirs = host.listSubdirs ? await host.listSubdirs(current) : [];
+        for (const sub of subdirs.slice().sort()) {
+            await walk(joinPath(current, sub));
+        }
+    };
+    await walk(base);
     return out.sort();
 }

package/dist/runtime/core/host.d.ts

@@ -233,7 +233,10 @@ export interface FormSchema {
  * it against a live engine; tests implement it in-memory. Core modules depend only on this.
  */
 export interface EngineClient {
-    /** Deploy model resources (BPMN/DMN/forms). Returns the number deployed. */
+    /** Deploy model resources (BPMN/DMN/forms) and generic resources (prompts, scripts, and other
+     *  arbitrary files, content-typed e.g. `text/markdown`/`application/octet-stream`; the engine
+     *  versions each generic resource per its `resourceId` — carried on `name`). Returns the number
+     *  deployed. */
     deployResources(resources: {
         name: string;
         content: string;

package/dist/runtime/core/lineage.d.ts

@@ -0,0 +1,116 @@
+import { type JobExecContext } from "./execContext.ts";
+/** The reserved variable namespace the lineage envelope lives under on every
+ *  instance/message (`_urban.lineage`). Kept as one object so future framework
+ *  conventions can share the `_urban.*` namespace without colliding. */
+export declare const LINEAGE_NAMESPACE = "_urban";
+/** The key of the lineage envelope within {@link LINEAGE_NAMESPACE}. */
+export declare const LINEAGE_KEY = "lineage";
+/**
+ * The lineage envelope, a reserved convention on every instance/message:
+ * `_urban.lineage = { rootRequestKey, causedByInstanceKey? }`.
+ *  - `rootRequestKey` threads every descendant of a single top-level request back to
+ *    it; it is PRESERVED verbatim across the whole causal tree.
+ *  - `causedByInstanceKey` is the instance that directly caused this one (the weak
+ *    parent edge). Absent on a genuine top-level request (a fresh root).
+ */
+export interface LineageEnvelope {
+    readonly rootRequestKey: string;
+    readonly causedByInstanceKey?: string;
+}
+/** Options for {@link applyAmbientLineage}, injectable for deterministic tests. */
+export interface ApplyLineageOptions {
+    /** Override the ambient job context (defaults to {@link currentJobContext}). */
+    readonly ambient?: JobExecContext | undefined;
+    /** Override the fresh-root minter (defaults to {@link mintRootRequestKey}). */
+    readonly mintRootRequestKey?: () => string;
+}
+/** Mint a fresh `rootRequestKey` for a genuine top-level request (no ambient lineage).
+ *  Uses `crypto.randomUUID` where available (Node ≥ 16.7 / Deno expose it as a global),
+ *  with a time+random fallback so this stays host-agnostic and never throws. */
+export declare function mintRootRequestKey(): string;
+/**
+ * Read the `_urban.lineage` envelope from a variables map, or `undefined` when absent or
+ * malformed (no/blank `rootRequestKey`). Tolerant by design: a bad envelope degrades to
+ * "no ambient lineage" rather than throwing on the hot instance-creation path.
+ */
+export declare function readLineage(variables: unknown): LineageEnvelope | undefined;
+/**
+ * Return a COPY of `variables` with `envelope` written under `_urban.lineage`, preserving
+ * any other `_urban.*` keys. Never mutates the input.
+ */
+export declare function writeLineage(variables: Record<string, unknown> | undefined, envelope: LineageEnvelope): Record<string, unknown>;
+/**
+ * Derive the envelope to attach to a NEW instance/message given the ambient job context.
+ *  - Ambient lineage present → PROPAGATE it: preserve `rootRequestKey`, set
+ *    `causedByInstanceKey` to the current instance (the cause).
+ *  - Ambient job with an instance but no envelope → that instance is itself a root; the
+ *    child inherits `rootRequestKey = <ambient instance>` and is caused by it.
+ *  - No ambient job at all (a genuine top-level request) → MINT a fresh `rootRequestKey`.
+ */
+export declare function deriveLineage(ambient: JobExecContext | undefined, mint?: () => string): LineageEnvelope;
+/**
+ * The single, adapter-agnostic step that auto-threads lineage onto a `createInstance` /
+ * `publishMessage` call's variables. Both the live `SdkEngineClient` and the testkit's
+ * `WasmEngineClient` route through this (No Drift Surfaces), so lineage threads identically
+ * in production and in-harness.
+ *
+ * An EXPLICIT caller-supplied `_urban.lineage` always wins (start a new root or re-parent
+ * deliberately) — it is returned untouched. Otherwise the envelope is derived from the
+ * ambient job context ({@link deriveLineage}) and merged in.
+ */
+export declare function applyAmbientLineage(variables: Record<string, unknown> | undefined, opts?: ApplyLineageOptions): Record<string, unknown>;
+/** How a node connects to its cause. `weak` = the causal envelope edge; `strong` = the
+ *  engine-native execution edge (`parentProcessInstanceKey`, Magikcraft/nano-bpm#808). */
+export type LineageEdgeType = "weak" | "strong";
+/** One directed edge cause → effect in a lineage tree. `causedByInstanceKey` is absent on a
+ *  root's own edge. */
+export interface LineageEdge {
+    readonly rootRequestKey: string;
+    /** The effect / descendant instance this edge lands on. */
+    readonly instanceKey: string;
+    /** The cause / parent instance, or `undefined` for a root. */
+    readonly causedByInstanceKey?: string;
+    readonly edgeType: LineageEdgeType;
+}
+/** An app-registered domain row attached to a lineage node (a PR, a task, …). The framework
+ *  stores it opaquely by `(nodeKey, kind, ref)` without knowing the app's schema. */
+export interface LineageAttachment {
+    /** The instance key this row hangs off. */
+    readonly nodeKey: string;
+    /** App-defined category, e.g. `"pull_request"`, `"task"`. */
+    readonly kind: string;
+    /** App-defined reference into its own store, e.g. a PR key. */
+    readonly ref: string;
+    /** Optional human-readable label. */
+    readonly label?: string;
+}
+/** A node in the stitched lineage tree. */
+export interface LineageNode {
+    readonly instanceKey: string;
+    /** How this node connects to its parent; `undefined` for the root. */
+    readonly edgeType?: LineageEdgeType;
+    readonly causedByInstanceKey?: string;
+    readonly attachments: LineageAttachment[];
+    readonly children: LineageNode[];
+}
+/** The stitched descendant tree for one `rootRequestKey`. */
+export interface LineageTree {
+    readonly rootRequestKey: string;
+    /** The root node of the stitched tree, always present. Normally the top-level request's own
+     *  instance; when `rootRequestKey` is a minted synthetic key, the parentless root instance it
+     *  threads. Falls back to a synthetic node keyed by `rootRequestKey` when no edges exist. */
+    readonly root: LineageNode;
+    /** Every node keyed by instance, in insertion order — a convenience flat view. */
+    readonly nodes: LineageNode[];
+}
+/**
+ * Build the stitched descendant tree for `rootRequestKey` by unioning weak and strong edges.
+ * When both edge sources connect the SAME node, the STRONG (engine execution) edge wins — it
+ * is the authoritative parent — so #808's native edge supersedes the envelope's weak guess
+ * without duplicating it. Nodes whose parent chain does not reach the root stay unattached
+ * (they still appear in `nodes`). The root is the instance keyed by `rootRequestKey` when that
+ * is itself an instance, else the single parentless recorded instance (a minted `rootRequestKey`
+ * is a synthetic correlation key, not an instance), else a synthetic node. Pure and
+ * deterministic — the store is a thin persistence layer over this.
+ */
+export declare function buildLineageTree(rootRequestKey: string, edges: readonly LineageEdge[], attachments?: readonly LineageAttachment[]): LineageTree;

package/dist/runtime/core/lineage.js

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