@nanobpm/urban 0.51.0 → 0.53.0

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

@@ -0,0 +1,17 @@
+import type { RuntimeContext } from "../context.ts";
+import { type Route } from "../router.ts";
+export interface AgentHandle {
+    readonly name: string;
+    routes: Route[];
+    describe(): Record<string, unknown>;
+}
+/**
+ * Mount the `/app/agent` (+ `/app/agent.json`) institutional-memory brief routes. Reads the
+ * `urban gen`-derived artifacts through the host file port, resolving each under `ctx.root` via
+ * the shared `resolveAppPath` (like every other runtime module) so serving never depends on the
+ * host's current working directory. A genuinely absent artifact — checked with `host.exists`
+ * rather than a blanket catch — yields a 404 (gen never ran, or the app has no models); any other
+ * read failure (permissions, transient I/O) is left to surface as a 500 rather than being masked
+ * as "not generated".
+ */
+export declare function mountAgent(ctx: RuntimeContext): AgentHandle;

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

@@ -0,0 +1,63 @@
+// agent — the app-scoped institutional-memory brief surface (ADR 0060 §2). The app-level mirror
+// of the node `/agent` brief (ADR 0051): where the node brief describes the whole runtime, this
+// serves ONE app's derived `system-brief.md` / `system-brief.json` so an agent (or human) opening
+// work on the app starts grounded in the app's own system model — its processes, service-task call
+// graph, decisions, and ownership.
+//
+//   GET /app/agent       → nano-generated/system-brief.md   (text/markdown)
+//   GET /app/agent.json  → nano-generated/system-brief.json (application/json)
+//
+// The brief is derived by `urban gen` (systemBriefDeriver, wired in gen.ts) into the app's
+// `nano-generated/` dir, so this route is a thin read-through of that artifact — no re-derivation
+// at request time (the derived file is the single source of truth, kept honest by
+// `urban gen --check`). Mounted unconditionally: the brief is a property of the app's models, not
+// of any opt-in surface, so it is always addressable when a brief has been generated. An app whose
+// models produced no brief (never ran gen) returns 404.
+import { GENERATED_DIR } from "../../../toolkit/artifact.js";
+import { SYSTEM_BRIEF_JSON, SYSTEM_BRIEF_MD } from "../../../toolkit/derivers/system-brief.js";
+import { json } from "../router.js";
+import { resolveAppPath } from "./datasource.js";
+/** The app-relative path of a generated brief artifact. */
+const briefPath = (name) => `${GENERATED_DIR}/${name}`;
+function markdown(body) {
+    return { status: 200, headers: { "content-type": "text/markdown; charset=utf-8" }, body };
+}
+/**
+ * Mount the `/app/agent` (+ `/app/agent.json`) institutional-memory brief routes. Reads the
+ * `urban gen`-derived artifacts through the host file port, resolving each under `ctx.root` via
+ * the shared `resolveAppPath` (like every other runtime module) so serving never depends on the
+ * host's current working directory. A genuinely absent artifact — checked with `host.exists`
+ * rather than a blanket catch — yields a 404 (gen never ran, or the app has no models); any other
+ * read failure (permissions, transient I/O) is left to surface as a 500 rather than being masked
+ * as "not generated".
+ */
+export function mountAgent(ctx) {
+    const artifactPath = (name) => resolveAppPath(ctx.root, briefPath(name));
+    const notGenerated = () => json({ error: "system brief not generated — run `urban gen`" }, 404);
+    const serve = async (name, toResponse) => {
+        const path = artifactPath(name);
+        if (!(await ctx.host.exists(path)))
+            return notGenerated();
+        return toResponse(await ctx.host.readTextFile(path));
+    };
+    const routes = [
+        {
+            method: "GET",
+            path: "/app/agent",
+            source: "surface:agent",
+            handler: () => serve(SYSTEM_BRIEF_MD, markdown),
+        },
+        {
+            method: "GET",
+            path: "/app/agent.json",
+            source: "surface:agent",
+            handler: () => serve(SYSTEM_BRIEF_JSON, (body) => ({
+                status: 200,
+                headers: { "content-type": "application/json" },
+                body,
+            })),
+        },
+    ];
+    ctx.host.log("info", "agent brief surface mounted", { routes: routes.length });
+    return { name: "agent", routes, describe: () => ({ routes: routes.map((r) => r.path) }) };
+}

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/deploy.d.ts

@@ -1,12 +1,15 @@
 import type { RuntimeContext } from "../context.ts";
-/** The convention directory: deploy-only, walked one level deep when no `models` are declared. */
+/** The convention directory: deploy-only, walked recursively when no `models` are declared. */
 export declare const RESOURCES_DIR = "resources";
 /**
- * Deploy the app's processes, decisions and forms.
+ * Deploy the app's resources.
  *
- * With no manifest `models`, deployables are discovered by convention under `resources/` (shallow,
- * one level deep). With `models` globs declared, those are used verbatim. Basename collisions are a
- * hard error in either mode.
+ * With no manifest `models`, deployables are discovered by convention under `resources/`
+ * (recursively — every file at any depth) and each is keyed by its path relative to `resources/`
+ * (POSIX). With `models` globs declared, those are used verbatim and keyed by basename (a basename
+ * collision is a hard error). Content is deployed verbatim (no template substitution); each file is
+ * content-typed by extension so a generic resource (e.g. a prompt `.md`) deploys as a versioned
+ * generic resource the engine resolves via `zeebe:linkedResource bindingType:latest`.
  */
 export declare function deployModels(ctx: RuntimeContext): Promise<{
     deployed: number;

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

@@ -2,18 +2,42 @@
 //
 // Resources are found by ONE of two paths:
 //   1. Convention (the default, ADR 0062): when the manifest declares no `models`, deployables are
-//      discovered by walking `resources/` — shallow, one level deep. `resources/` is deploy-only:
-//      everything under it (and nothing outside it) is deployed. Docs (`docs/`, `AGENTS.md`,
-//      top-level `*.md`) live outside `resources/` and are never swept in.
+//      discovered by walking `resources/` **recursively** — every file under it, at any depth
+//      (issue #231). `resources/` is deploy-only: everything under it (and nothing outside it) is
+//      deployed. Docs (`docs/`, `AGENTS.md`, top-level `*.md`) live outside `resources/` and are
+//      never swept in. A convention resource's deploy key (`resourceId`) is its path **relative to
+//      `resources/`** (POSIX-normalised), e.g. `resources/prompts/plan.md` → `prompts/plan.md`, so
+//      a linked service task references it with `zeebe:linkedResource resourceId="prompts/plan.md"`.
+//      The relative path (not the bare basename) preserves sub-directory structure and lets two
+//      files sharing a filename in different sub-dirs (`a/x.md`, `b/x.md`) deploy as distinct
+//      resources — there is no basename-collision hazard.
 //   2. Explicit override: when the manifest declares `models` globs, those are used exactly (the
-//      convention walk is skipped) — the escape hatch for a non-convention layout.
+//      convention walk is skipped) — the escape hatch for a non-convention layout. Override
+//      resources are keyed by basename (filename only), so a basename collision across the declared
+//      globs is a hard error, detected up front.
 //
-// Either way the deploy dedupe key is the resource's basename (filename only), so a basename
-// collision — two files with the same name in different directories — would silently clobber one
-// resource with another at the engine. We detect that up front and fail loudly instead.
+// Content is deployed **verbatim** — there is no deploy-time `{{token}}` substitution (removed in
+// ADR 0062) — so a generic resource (a prompt `.md`, an RPA/script file) is deployed as-is.
+// The deploy pipeline is **UTF-8 text only**, end-to-end: `host.readTextFile()` yields a `string`
+// and the engine's `deployResources` takes `content: string`, so there is no byte channel and
+// arbitrary binary is out of scope by design. "Verbatim" therefore means the UTF-8 text is passed
+// through unchanged; a non-UTF-8/binary file swept into `resources/` is not a supported input (see
+// `contentTypeFor`'s `application/octet-stream` note).
 import { discoverResources, expandPatterns } from "../glob.js";
-/** The convention directory: deploy-only, walked one level deep when no `models` are declared. */
+/** The convention directory: deploy-only, walked recursively when no `models` are declared. */
 export const RESOURCES_DIR = "resources";
+/**
+ * Classify a file into an engine content type by extension. Models get their real XML/JSON types;
+ * generic resources get a real text content type where the extension is known (`.md`, `.json`,
+ * `.txt`), falling back to `application/octet-stream` for anything unrecognised (so an unknown
+ * extension is never mislabelled as a specific text type). Note the deploy pipeline is UTF-8 text
+ * only (`readTextFile` → engine `content: string`): the `octet-stream` fallback is a conservative
+ * MIME label for an unrecognised *text* resource (e.g. a script with an uncommon extension), not a
+ * promise of binary fidelity — a genuinely binary file cannot be preserved byte-for-byte and is
+ * out of scope. The engine deploys a non-model content type as a generic resource
+ * (versioned per `resourceId`); a service task resolves it via
+ * `zeebe:linkedResource resourceId="<id>" bindingType:latest`.
+ */
 function contentTypeFor(path) {
     if (path.endsWith(".bpmn"))
         return "text/xml";
@@ -21,14 +45,30 @@ function contentTypeFor(path) {
         return "text/xml";
     if (path.endsWith(".form"))
         return "application/json";
+    if (path.endsWith(".md"))
+        return "text/markdown";
+    if (path.endsWith(".json"))
+        return "application/json";
+    if (path.endsWith(".txt"))
+        return "text/plain";
     return "application/octet-stream";
 }
 function baseName(path) {
     const i = path.lastIndexOf("/");
     return i >= 0 ? path.slice(i + 1) : path;
 }
-/** Fail loudly when two resolved files share a basename (the deploy dedupe key), naming the
- *  colliding paths so the author can rename or relocate one. */
+/**
+ * A convention resource's `resourceId`: its path relative to `<root>/resources/` (POSIX). Given a
+ * root-prefixed discovered path (`/app/resources/prompts/plan.md`) it returns `prompts/plan.md`.
+ * Falls back to the basename if — defensively — the path is not under the resources prefix.
+ */
+function relativeResourceId(path, root) {
+    const prefix = `${root.replace(/\/+$/, "")}/${RESOURCES_DIR}/`;
+    return path.startsWith(prefix) ? path.slice(prefix.length) : baseName(path);
+}
+/** Fail loudly when two resolved files share a basename (the override dedupe key), naming the
+ *  colliding paths so the author can rename or relocate one. Only relevant for the `models`
+ *  override path; convention resources are keyed by relative path and cannot collide. */
 function assertNoBasenameCollisions(files) {
     const byName = new Map();
     for (const path of files) {
@@ -49,11 +89,14 @@ function assertNoBasenameCollisions(files) {
         `the same name would clobber each other. Rename or relocate one of:\n${detail}`);
 }
 /**
- * Deploy the app's processes, decisions and forms.
+ * Deploy the app's resources.
  *
- * With no manifest `models`, deployables are discovered by convention under `resources/` (shallow,
- * one level deep). With `models` globs declared, those are used verbatim. Basename collisions are a
- * hard error in either mode.
+ * With no manifest `models`, deployables are discovered by convention under `resources/`
+ * (recursively — every file at any depth) and each is keyed by its path relative to `resources/`
+ * (POSIX). With `models` globs declared, those are used verbatim and keyed by basename (a basename
+ * collision is a hard error). Content is deployed verbatim (no template substitution); each file is
+ * content-typed by extension so a generic resource (e.g. a prompt `.md`) deploys as a versioned
+ * generic resource the engine resolves via `zeebe:linkedResource bindingType:latest`.
  */
 export async function deployModels(ctx) {
     const models = ctx.manifest.models;
@@ -79,9 +122,12 @@ export async function deployModels(ctx) {
         }
         return { deployed: 0, files: [] };
     }
-    assertNoBasenameCollisions(files);
+    // Convention resources are keyed by their (unique) relative path; only the override path, whose
+    // basename key can collide across globs, needs the collision guard.
+    if (!byConvention)
+        assertNoBasenameCollisions(files);
     const resources = await Promise.all(files.map(async (path) => ({
-        name: baseName(path),
+        name: byConvention ? relativeResourceId(path, ctx.root) : baseName(path),
         content: await ctx.host.readTextFile(path),
         contentType: contentTypeFor(path),
     })));

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