@nanobpm/urban 0.51.0 → 0.52.0

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

@@ -9,6 +9,11 @@ export interface JobExecContext {
     elementId?: string;
     /** The job type (worker) currently executing. */
     jobType?: string;
+    /** The lineage `rootRequestKey` the running instance belongs to (its own envelope's root,
+     *  or — for a root instance with no envelope — its own instance key). Threaded so that when a
+     *  handler spawns an instance or publishes a message, the SDK propagates the same root and
+     *  sets `causedByInstanceKey` to {@link instanceKey} (issue #254, see `./lineage.ts`). */
+    rootRequestKey?: string;
 }
 /**
  * Install the host-backed ambient store once per process. Idempotent — the first store created

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

package/dist/runtime/core/modules/datasource.d.ts

@@ -101,6 +101,12 @@ export declare class DataLayer {
     private readonly types;
     constructor(sources: Map<string, ProvisionedSource>, defaultSource: string | undefined, types: Record<string, DomainType>);
     source(name?: string): ProvisionedSource;
+    /**
+     * Whether a default data source is *configured* — not whether it provisions. Lets a caller
+     * distinguish the expected "no source at all" case from a genuine misconfiguration (a default is
+     * named but its source is missing, so {@link source} throws `no such data source`).
+     */
+    hasDefaultSource(): boolean;
     /** A typed accessor for a declared domain type (uses the default source). */
     repo(typeName: string, sourceName?: string): TypeRepo;
     /** The record-oriented `DataSource` gateway for a source (the default when omitted) — the

package/dist/runtime/core/modules/datasource.js

@@ -223,6 +223,14 @@ export class DataLayer {
             throw new Error(`no such data source "${key}"`);
         return s;
     }
+    /**
+     * Whether a default data source is *configured* — not whether it provisions. Lets a caller
+     * distinguish the expected "no source at all" case from a genuine misconfiguration (a default is
+     * named but its source is missing, so {@link source} throws `no such data source`).
+     */
+    hasDefaultSource() {
+        return this.defaultSource !== undefined;
+    }
     /** A typed accessor for a declared domain type (uses the default source). */
     repo(typeName, sourceName) {
         const def = this.types[typeName];

package/dist/runtime/core/modules/lineage-store.d.ts

@@ -0,0 +1,81 @@
+import type { SqliteDb } from "../host.ts";
+import { type LineageAttachment, type LineageEdge, type LineageTree } 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 declare 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 declare 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 declare const LINEAGE_SCHEMA_SQL = "CREATE TABLE IF NOT EXISTS _urban_lineage_edges (\n  root_request_key       TEXT NOT NULL,\n  instance_key           TEXT NOT NULL,\n  caused_by_instance_key TEXT,\n  edge_type              TEXT NOT NULL DEFAULT 'weak',\n  created_at             TEXT NOT NULL,\n  PRIMARY KEY (instance_key, edge_type)\n);\nCREATE INDEX IF NOT EXISTS idx__urban_lineage_edges_root ON _urban_lineage_edges (root_request_key);\nCREATE TABLE IF NOT EXISTS _urban_lineage_attachments (\n  root_request_key TEXT NOT NULL,\n  node_key         TEXT NOT NULL,\n  kind             TEXT NOT NULL,\n  ref              TEXT NOT NULL,\n  label            TEXT,\n  created_at       TEXT NOT NULL,\n  PRIMARY KEY (node_key, kind, ref)\n);\nCREATE INDEX IF NOT EXISTS idx__urban_lineage_attachments_root ON _urban_lineage_attachments (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 declare const systemClock: Clock;
+/** 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;
+}
+export declare class LineageStore {
+    #private;
+    constructor(db: SqliteDb, options?: LineageStoreOptions);
+    /** 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /** The persisted edges for one root, in insertion order. */
+    edges(rootRequestKey: string): LineageEdge[];
+    /** The persisted attachments for one root, in insertion order. */
+    attachments(rootRequestKey: string): LineageAttachment[];
+    /**
+     * 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;
+}

package/dist/runtime/core/modules/lineage-store.js

@@ -0,0 +1,175 @@
+// 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 { buildLineageTree, readLineage, } from "../lineage.js";
+/** 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);`;
+/** The default clock: `Date.now()`. */
+export const systemClock = { now: () => Date.now() };
+function normalizeEdgeType(raw) {
+    return raw === "strong" ? "strong" : "weak";
+}
+export class LineageStore {
+    #db;
+    #clock;
+    constructor(db, options = {}) {
+        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() {
+        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) {
+        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, variables) {
+        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) {
+        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, attachment) {
+        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) {
+        const rows = this.#db.all(`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) {
+        const rows = this.#db.all(`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) {
+        return buildLineageTree(rootRequestKey, this.edges(rootRequestKey), this.attachments(rootRequestKey));
+    }
+}