@nanobpm/urban 0.51.0 → 0.53.0

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

@@ -4,6 +4,7 @@ import { DataLayer } from "./modules/datasource.ts";
 import { type Logger } from "./logger.ts";
 import type { SchedulerDeps } from "./modules/scheduler.ts";
 import { type SecurityPolicy } from "./modules/security.ts";
+import { type UrbanEvents, type UrbanExtension } from "./extensions.ts";
 /** Resolve the HTTP port: explicit option, else $PORT, else 8090. Throws a clear
  * error when $PORT is set but not a valid integer in 0..65535. */
 export declare function resolvePort(explicit: number | undefined, envPort: string | undefined): number;
@@ -40,6 +41,14 @@ export interface CreateUrbanAppOptions {
      * so one injected scheduler drives them both (no per-module wiring, no drift).
      */
     scheduler?: SchedulerDeps;
+    /**
+     * Pluggable Urban {@link UrbanExtension}s — the agentic families and connector
+     * packs that extend the app lifecycle through the typed extension-event taxonomy
+     * (issue #262) instead of editing the runtime. The runtime runs each through the
+     * `extension/register` serial checkpoint in a deterministic order and disposes
+     * everything they register on `stop()` / HMR. Empty by default.
+     */
+    extensions?: readonly UrbanExtension[];
 }
 export interface UrbanApp {
     readonly manifest: AppManifest;
@@ -69,5 +78,13 @@ export interface UrbanApp {
      * `undefined` before `start()`, after `stop()`, and on hosts that don't surface one (Deno).
      */
     readonly httpServer: object | undefined;
+    /**
+     * The app's typed extension-event taxonomy (issue #262): lifecycle notifications,
+     * the extension-registration checkpoint, request/security waterfall gates, and
+     * the reconcile fan-out — each a channel with a declared dispatch mode. Modules
+     * and {@link UrbanExtension}s hook onto these seams instead of wiring directly;
+     * every registration is an effect on a dispose ladder that `stop()` unwinds.
+     */
+    readonly events: UrbanEvents;
 }
 export declare function createUrbanApp(opts: CreateUrbanAppOptions): Promise<UrbanApp>;

package/dist/runtime/core/runtime.js

@@ -15,6 +15,8 @@ import { mountSurfaces } from "./modules/surfaces.js";
 import { mountTriggers } from "./modules/triggers.js";
 import { mountInstanceTracking } from "./modules/instance-tracking.js";
 import { mountSecurity } from "./modules/security.js";
+import { EventBus } from "./events.js";
+import { createUrbanEvents, mountExtensions } from "./extensions.js";
 /** Resolve the HTTP port: explicit option, else $PORT, else 8090. Throws a clear
  * error when $PORT is set but not a valid integer in 0..65535. */
 export function resolvePort(explicit, envPort) {
@@ -53,6 +55,18 @@ export async function createUrbanApp(opts) {
     // `app.log`) and the per-invocation `AppApi.log` (workers/route delegates `child()` it with their
     // correlation context).
     const appLog = createLogger((l, m, f) => host.log(l, m, f));
+    // The app-wide extension-event microkernel (issue #262): one typed taxonomy over
+    // one dispose ladder. Contained listener throws land in the structured log rather
+    // than stranding the pipeline. Modules and extensions hook onto `events`; the
+    // whole ladder unwinds on teardown.
+    const bus = new EventBus({
+        onError: (err, info) => appLog.warn("extension listener threw and was contained", {
+            event: info.event,
+            mode: info.mode,
+            error: String(err),
+        }),
+    });
+    const events = createUrbanEvents(bus);
     // Install the ambient job-execution store once per process (idempotent) so worker dispatch can
     // stamp write-provenance onto DataLayer inserts. Absent-safe: a host without `createAsyncStore`
     // leaves provenance capture disabled.
@@ -74,6 +88,8 @@ export async function createUrbanApp(opts) {
     // Release every mounted resource and reset internal state so a subsequent
     // start() begins clean. Used by stop() and by start()'s failure path.
     const teardown = async () => {
+        // Notify lifecycle listeners before we start tearing seams down (issue #262).
+        events.lifecycle.emit({ app: manifest.id, phase: "stopping" });
         if (server) {
             try {
                 await server.stop();
@@ -106,11 +122,17 @@ export async function createUrbanApp(opts) {
         data = undefined;
         security = undefined;
         started = false;
+        // Terminal lifecycle notification, then unwind the whole dispose ladder LIFO:
+        // every extension listener/effect (and the lifecycle channel itself) is torn
+        // down, so a subsequent start() — or a dev-server HMR reload — leaks nothing.
+        events.lifecycle.emit({ app: manifest.id, phase: "stopped" });
+        bus.dispose();
     };
     const app = {
         manifest,
         root,
         log: appLog,
+        events,
         get data() {
             return data;
         },
@@ -128,6 +150,7 @@ export async function createUrbanApp(opts) {
             if (started)
                 throw new Error("app already started");
             started = true;
+            events.lifecycle.emit({ app: manifest.id, phase: "starting" });
             try {
                 if (flags.security)
                     security = mountSecurity(ctx);
@@ -153,6 +176,12 @@ export async function createUrbanApp(opts) {
                     if (c.jobTypes.length > 0)
                         describe.connectors = c.describe?.();
                 }
+                // Run the agentic-family / connector-pack extension surface through the
+                // typed taxonomy (issue #262). Everything an extension registers rides the
+                // shared dispose ladder, so teardown's single `bus.dispose()` unwinds it —
+                // the extension host is deliberately NOT pushed onto `mounted`.
+                const extHost = await mountExtensions(api, opts.extensions ?? [], { bus, events });
+                describe.extensions = extHost.describe?.();
                 const routes = [];
                 let hasUiSurfaces = false;
                 if (flags.surfaces) {
@@ -226,6 +255,7 @@ export async function createUrbanApp(opts) {
                     }
                 }
                 host.log("info", `urban app "${manifest.id}" started`, {});
+                events.lifecycle.emit({ app: manifest.id, phase: "started" });
             }
             catch (err) {
                 // A failed start must not leave the app half-mounted (leaked workers,

package/dist/runtime/engine/nanosdk.js

@@ -21,6 +21,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { isBpmnError } from "../core/host.js";
 import { buildFormSchema, parseFormSchema, pickFormLinkage, resolveFormIdentifier, } from "../core/form-contract.js";
 import { isRecord } from "../core/guards.js";
+import { applyAmbientLineage } from "../core/lineage.js";
 /** Coerce an engine response's process-instance key to a non-empty string, or
  * throw — a missing key means a malformed/partial response, not a real instance. */
 export function requireProcessInstanceKey(key) {
@@ -76,9 +77,12 @@ export class SdkEngineClient {
         return { deployed: resources.length };
     }
     async createInstance(input) {
+        // Auto-thread the `_urban.lineage` envelope (issue #254): a handler that spawns an
+        // instance propagates its `rootRequestKey` and stamps `causedByInstanceKey`; a genuine
+        // top-level request mints a fresh root. An explicit caller-supplied envelope wins.
         const body = await this.client.createProcessInstance({
             processDefinitionId: input.processDefinitionId,
-            variables: input.variables ?? {},
+            variables: applyAmbientLineage(input.variables),
             awaitCompletion: input.awaitCompletion ?? false,
         });
         const rawKey = body.processInstanceKey ?? body.key;
@@ -93,10 +97,12 @@ export class SdkEngineClient {
         await this.client.cancelProcessInstance({ processInstanceKey: input.processInstanceKey });
     }
     async publishMessage(input) {
+        // Message-started instances inherit lineage too (issue #254): thread the envelope onto the
+        // message variables so the instance the message starts carries `_urban.lineage`.
         await this.client.publishMessage({
             name: input.name,
             correlationKey: input.correlationKey ?? "",
-            variables: input.variables ?? {},
+            variables: applyAmbientLineage(input.variables),
         });
     }
     async searchUserTasks(filter) {

package/dist/runtime/index.d.ts

@@ -1,5 +1,9 @@
 export { createUrbanApp } from "./core/runtime.ts";
 export type { CreateUrbanAppOptions, MountFlags, UrbanApp, } from "./core/runtime.ts";
+export { EventBus } from "./core/events.ts";
+export type { DispatchMode, Disposer, EmitChannel, ErrorSink, EventBusOptions, Listener, Middleware, ParallelChannel, SerialChannel, WaterfallChannel, } from "./core/events.ts";
+export { URBAN_EVENT_MODES, createUrbanEvents, mountExtensions, urbanEventMode } from "./core/extensions.ts";
+export type { DispatchRequest, DispatchResponse, ExtensionHost, ExtensionRegistered, ExtensionSetupContext, GateDecision, GateRequest, LifecycleEvent, MountExtensionsOptions, ReconcileEvent, UrbanEventName, UrbanEvents, UrbanExtension, } from "./core/extensions.ts";
 export { bindModeToHost, expandEnv, expandEnvString, isBindMode, loadManifest, parseManifest, resolveBindHost, resolveBindMode, workerJobType, ALL_INTERFACES_HOST, BIND_ENV_VAR, LOOPBACK_HOST, } from "./core/manifest.ts";
 export type { ActionDecl, AppManifest, BindMode, ChatSurface, DataSource, DomainField, DomainType, LlmBinding, NetworkConfig, PagesSurface, Surfaces, TaskInboxSurface, Trigger, Worker, } from "./core/manifest.ts";
 export { collectManifestIssues, ManifestValidationError, validateManifest, } from "./core/validate.ts";
@@ -31,6 +35,12 @@ export { resolveHandler, sdkDecisionEvaluator } from "./core/modules/workers.ts"
 export { buildMessages, callLlm, resolveProvider, runLlmJob, } from "./core/modules/llm.ts";
 export type { ChatMessage, DecisionEvaluator, EnvLookup, LlmRuntime, LlmVars, ProviderConfig, } from "./core/modules/llm.ts";
 export { evalCorrelation } from "./core/modules/triggers.ts";
+export { applyAmbientLineage, buildLineageTree, deriveLineage, LINEAGE_KEY, LINEAGE_NAMESPACE, mintRootRequestKey, readLineage, writeLineage, } from "./core/lineage.ts";
+export type { ApplyLineageOptions, LineageAttachment, LineageEdge, LineageEdgeType, LineageEnvelope, LineageNode, LineageTree, } from "./core/lineage.ts";
+export { LINEAGE_ATTACHMENTS_TABLE, LINEAGE_EDGES_TABLE, LINEAGE_SCHEMA_SQL, LineageStore, systemClock as lineageSystemClock, } from "./core/modules/lineage-store.ts";
+export type { Clock as LineageClock, LineageJobLike, LineageStoreOptions, } from "./core/modules/lineage-store.ts";
+export { buildScopeIndex, derivePhase, deriveInstancePhases, furthestReached, rollupLineagePhase, SCOPE_CONTAINERS, } from "./core/phase.ts";
+export type { CrumbKind, CrumbSource, DerivePhaseOptions, FurthestReached, InstancePhase, LineagePhaseRollup, Phase, PhaseCrumb, PhaseGranularity, ProvenanceProgressRow, ScopeElement, ScopeIndex, } from "./core/phase.ts";
 export { deployModels, RESOURCES_DIR } from "./core/modules/deploy.ts";
 export { defaultScheduler, MAX_TIMER_DELAY_MS } from "./core/modules/scheduler.ts";
 export type { SchedulerDeps } from "./core/modules/scheduler.ts";

package/dist/runtime/index.js

@@ -1,6 +1,9 @@
 // Public API for the Urban runtime (@nanobpm/urban, subpath ./runtime).
 // Core runtime
 export { createUrbanApp } from "./core/runtime.js";
+// Extension-event taxonomy + microkernel (issue #262)
+export { EventBus } from "./core/events.js";
+export { URBAN_EVENT_MODES, createUrbanEvents, mountExtensions, urbanEventMode } from "./core/extensions.js";
 // Manifest
 export { bindModeToHost, expandEnv, expandEnvString, isBindMode, loadManifest, parseManifest, resolveBindHost, resolveBindMode, workerJobType, ALL_INTERFACES_HOST, BIND_ENV_VAR, LOOPBACK_HOST, } from "./core/manifest.js";
 // Validation
@@ -28,6 +31,15 @@ export { defineOperation, mountApi, resolveOperationHandler, NotImplemented } fr
 export { resolveHandler, sdkDecisionEvaluator } from "./core/modules/workers.js";
 export { buildMessages, callLlm, resolveProvider, runLlmJob, } from "./core/modules/llm.js";
 export { evalCorrelation } from "./core/modules/triggers.js";
+// Lineage — the framework-level lineage primitive (issue #254): the `_urban.lineage`
+// envelope + auto-threading, and the generic read projection that stitches user intent →
+// progress (a root request → the instances/PRs/tasks it causes).
+export { applyAmbientLineage, buildLineageTree, deriveLineage, LINEAGE_KEY, LINEAGE_NAMESPACE, mintRootRequestKey, readLineage, writeLineage, } from "./core/lineage.js";
+export { LINEAGE_ATTACHMENTS_TABLE, LINEAGE_EDGES_TABLE, LINEAGE_SCHEMA_SQL, LineageStore, systemClock as lineageSystemClock, } from "./core/modules/lineage-store.js";
+// Phase — the framework-level *domain phase* primitive (issue #266): derive "which phase is this
+// instance in?" from the BPMN scope hierarchy + write-provenance (Tier 0, zero declaration), an
+// optional `nano:phase` override (Tier 1), and a lineage rollup for the epic frontier (Tier 2).
+export { buildScopeIndex, derivePhase, deriveInstancePhases, furthestReached, rollupLineagePhase, SCOPE_CONTAINERS, } from "./core/phase.js";
 // Model deploy (deploy-by-convention under `resources/`, ADR 0062)
 export { deployModels, RESOURCES_DIR } from "./core/modules/deploy.js";
 export { defaultScheduler, MAX_TIMER_DELAY_MS } from "./core/modules/scheduler.js";

package/dist/toolkit/derivers/system-brief.d.ts

@@ -0,0 +1,62 @@
+import type { DerivedArtifact, Deriver } from "../artifact.ts";
+import { type ModelSource, type WorkerIo } from "./worker-io.ts";
+/** Basenames of the two emitted artifacts. */
+export declare const SYSTEM_BRIEF_MD = "system-brief.md";
+export declare const SYSTEM_BRIEF_JSON = "system-brief.json";
+/** Reserved `nano:meta` keys the brief recognises as ownership / provenance context (ADR 0060
+ * §1). All optional and additive — absence degrades the brief to structure-only. `adr` may be
+ * declared more than once (repeated `nano:meta`, matching the existing scan) to reference
+ * multiple ADRs; the scan collects them into `adrs[]`. */
+export interface Ownership {
+    owner?: string;
+    team?: string;
+    slack?: string;
+    runbook?: string;
+    since?: string;
+    adrs: string[];
+}
+/** One decision the app encodes: a `businessRuleTask` with a `zeebe:calledDecision`. */
+export interface DecisionRef {
+    process?: string;
+    elementId?: string;
+    decisionId: string;
+}
+/** The derived, machine-readable system model — the payload of `system-brief.json` and the
+ * input the runtime injects as session context / the retro plane consumes (ADR 0060 §3). */
+export interface SystemBrief {
+    /** App id/name from the manifest, if provided. */
+    app?: string;
+    /** Every process id the models declare, in scan order. */
+    processes: string[];
+    /** Service-task call graph: each worker binding (task type + in/out envelope + process). The
+     * dependency edges are implicit — a process depends on the task types its service tasks invoke. */
+    workers: WorkerIo[];
+    /** Decisions (`businessRuleTask` → DMN) the models encode. */
+    decisions: DecisionRef[];
+    /** Ownership / provenance folded from reserved `nano:meta` keys. */
+    ownership: Ownership;
+}
+/** Scan one BPMN document for `businessRuleTask` → `zeebe:calledDecision` decision refs, in
+ * document order, tagged with the enclosing process (mirrors `scanModelWorkers`' shape). */
+export declare function scanModelDecisions(xml: string): DecisionRef[];
+/** Fold the models' reserved `nano:meta` entries into `Ownership`. Single-valued keys take the
+ * last (scan-order) write, matching `foldMeta`; `adr` is multi-valued and accumulates. */
+export declare function foldOwnership(models: ModelSource[]): Ownership;
+/** Fold all models + manifest into the machine-readable `SystemBrief`. Deterministic: models
+ * are scanned in path order. */
+export declare function buildSystemBrief(models: ModelSource[], app?: string): SystemBrief;
+/** Emit the agent- and human-readable `system-brief.md` from the machine model. Compact by
+ * design (call graph + owners, not model XML) to keep the per-session prompt budget small
+ * (ADR 0060 §3 / open question 1). */
+export declare function emitSystemBriefMd(b: SystemBrief): string;
+/**
+ * Derive `nano-generated/system-brief.md` + `system-brief.json` from BPMN models (ADR 0060 §1).
+ * Pure and deterministic (path-ordered scan), so it is a drop-in drift-checkable artifact like
+ * its sibling derivers.
+ */
+export declare function deriveSystemBrief(models: ModelSource[], app?: string): DerivedArtifact[];
+/** The `Deriver` binding, peer to `worker-io` / `meta`, for wiring into `gen.ts`. */
+export declare const systemBriefDeriver: Deriver<{
+    models: ModelSource[];
+    app?: string;
+}>;

package/dist/toolkit/derivers/system-brief.js

@@ -0,0 +1,156 @@
+// Deriver: BPMN models + manifest → `system-brief.md` / `system-brief.json`, the app's
+// *institutional-memory* brief (ADR 0060). Where `worker-io.ts` emits worker *types* and
+// `meta.ts` emits a *typed accessor*, this deriver folds the SAME scanned structure into
+// agent- and human-readable **system context**: the app's processes, its service-task call
+// graph, the decisions it encodes, and the ownership / "why" carried on
+// the model as reserved `nano:meta` keys. It reuses the sibling scanners (single parse rule
+// per vocabulary) and is pure (models in, artifacts out) so `urban gen --check` keeps it
+// honest — the brief can never rot the way a hand-written README does (ADR 0060 §1).
+//
+// Wired into `runGen` (gen.ts) as a standard artifact and served at runtime via `/app/agent`
+// (agent.ts, ADR 0060 §2): the shape, scanners, fold, and both emitters are real and tested.
+import { GENERATED_DIR } from "../artifact.js";
+import { byModelPath, scanModelWorkers } from "./worker-io.js";
+import { scanModelMeta } from "./meta.js";
+/** Basenames of the two emitted artifacts. */
+export const SYSTEM_BRIEF_MD = "system-brief.md";
+export const SYSTEM_BRIEF_JSON = "system-brief.json";
+function attr(tag, name) {
+    const m = tag.match(new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`));
+    return m ? m[1] : undefined;
+}
+function processId(xml) {
+    const m = xml.match(/<bpmn:process\b[^>]*>/);
+    return m ? attr(m[0], "id") : undefined;
+}
+/** Scan one BPMN document for `businessRuleTask` → `zeebe:calledDecision` decision refs, in
+ * document order, tagged with the enclosing process (mirrors `scanModelWorkers`' shape). */
+export function scanModelDecisions(xml) {
+    const proc = processId(xml);
+    const out = [];
+    const blockRe = /<bpmn:businessRuleTask\b([^>]*)>([\s\S]*?)<\/bpmn:businessRuleTask>/g;
+    let m;
+    while ((m = blockRe.exec(xml)) !== null) {
+        const elementId = attr(`<x ${m[1]}>`, "id");
+        const cd = m[2].match(/<zeebe:calledDecision\b[^>]*>/);
+        if (!cd)
+            continue;
+        const decisionId = attr(cd[0], "decisionId");
+        if (!decisionId)
+            continue;
+        out.push({ process: proc, elementId, decisionId });
+    }
+    return out;
+}
+/** Reserved single-valued ownership keys → their `Ownership` field. */
+const OWNERSHIP_KEYS = {
+    owner: "owner",
+    team: "team",
+    slack: "slack",
+    runbook: "runbook",
+    since: "since",
+};
+/** Fold the models' reserved `nano:meta` entries into `Ownership`. Single-valued keys take the
+ * last (scan-order) write, matching `foldMeta`; `adr` is multi-valued and accumulates. */
+export function foldOwnership(models) {
+    const own = { adrs: [] };
+    for (const model of [...models].sort(byModelPath)) {
+        for (const { key, value } of scanModelMeta(model.xml)) {
+            const k = key.trim().toLowerCase();
+            if (k === "adr") {
+                if (value && !own.adrs.includes(value))
+                    own.adrs.push(value);
+            }
+            else if (Object.hasOwn(OWNERSHIP_KEYS, k)) {
+                own[OWNERSHIP_KEYS[k]] = value ?? "";
+            }
+        }
+    }
+    return own;
+}
+/** Fold all models + manifest into the machine-readable `SystemBrief`. Deterministic: models
+ * are scanned in path order. */
+export function buildSystemBrief(models, app) {
+    const sorted = [...models].sort(byModelPath);
+    const workers = [];
+    const decisions = [];
+    const processes = [];
+    for (const model of sorted) {
+        const proc = processId(model.xml);
+        if (proc && !processes.includes(proc))
+            processes.push(proc);
+        workers.push(...scanModelWorkers(model.xml));
+        decisions.push(...scanModelDecisions(model.xml));
+    }
+    return { app, processes, workers, decisions, ownership: foldOwnership(models) };
+}
+/** Escape a Markdown table cell: neutralise `|` and newlines, which would otherwise break the
+ * table. Ownership values come from model-authored `nano:meta`, so this both keeps rendering
+ * honest and blunts Markdown/prompt injection into the agent-facing brief. Backticks are left
+ * intact — the emitter deliberately wraps ids in code spans. */
+function mdCell(s) {
+    return s.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+function mdTable(headers, rows) {
+    if (rows.length === 0)
+        return "_none_\n";
+    const head = `| ${headers.join(" | ")} |\n| ${headers.map(() => "---").join(" | ")} |\n`;
+    return head + rows.map((r) => `| ${r.map((c) => mdCell(c || "")).join(" | ")} |`).join("\n") + "\n";
+}
+/** Emit the agent- and human-readable `system-brief.md` from the machine model. Compact by
+ * design (call graph + owners, not model XML) to keep the per-session prompt budget small
+ * (ADR 0060 §3 / open question 1). */
+export function emitSystemBriefMd(b) {
+    const o = b.ownership;
+    let m = `# ${b.app ?? "App"} — system brief\n\n`;
+    m += "_Auto-derived from the process models (ADR 0060). Do not edit — regenerated by " +
+        "`urban gen`; drift fails `urban gen --check`._\n\n";
+    m += "## Ownership\n\n";
+    const ownRows = [
+        ["Owner", o.owner ?? ""],
+        ["Team", o.team ?? ""],
+        ["Slack", o.slack ?? ""],
+        ["Runbook", o.runbook ?? ""],
+        ["Since", o.since ?? ""],
+        ["ADRs", o.adrs.join(", ")],
+    ].filter((r) => r[1]);
+    m += ownRows.length ? mdTable(["Field", "Value"], ownRows) : "_No ownership metadata declared " +
+        "(add reserved `nano:meta` keys: owner, team, slack, runbook, adr, since)._\n";
+    m += "\n";
+    m += "## Processes\n\n";
+    m += b.processes.length ? b.processes.map((p) => `- \`${p}\``).join("\n") + "\n" : "_none_\n";
+    m += "\n";
+    m += "## Service-task call graph (dependency edges)\n\n";
+    m += mdTable(["Process", "Task type (dependency)", "In", "Out"], b.workers.map((w) => [
+        w.process ? `\`${w.process}\`` : "",
+        `\`${w.taskType}\``,
+        w.in ? `\`${w.in}\`` : "",
+        w.out ? `\`${w.out}\`` : "",
+    ]));
+    m += "\n";
+    m += "## Decisions (DMN)\n\n";
+    m += mdTable(["Process", "Element", "Decision"], b.decisions.map((d) => [
+        d.process ? `\`${d.process}\`` : "",
+        d.elementId ? `\`${d.elementId}\`` : "",
+        `\`${d.decisionId}\``,
+    ]));
+    return m;
+}
+/**
+ * Derive `nano-generated/system-brief.md` + `system-brief.json` from BPMN models (ADR 0060 §1).
+ * Pure and deterministic (path-ordered scan), so it is a drop-in drift-checkable artifact like
+ * its sibling derivers.
+ */
+export function deriveSystemBrief(models, app) {
+    const brief = buildSystemBrief(models, app);
+    return [
+        { path: `${GENERATED_DIR}/${SYSTEM_BRIEF_MD}`, content: emitSystemBriefMd(brief) },
+        { path: `${GENERATED_DIR}/${SYSTEM_BRIEF_JSON}`, content: JSON.stringify(brief, null, 2) + "\n" },
+    ];
+}
+/** The `Deriver` binding, peer to `worker-io` / `meta`, for wiring into `gen.ts`. */
+export const systemBriefDeriver = {
+    id: "system-brief",
+    describe: "App institutional-memory brief (processes, call graph, decisions, ownership) — ADR 0060",
+    derive: ({ models, app }) => deriveSystemBrief(models, app),
+};

package/dist/toolkit/gen.d.ts

@@ -57,13 +57,13 @@ declare function dirOf(p: string): string;
 /** Resolve a `dir/*.ext` (or literal) manifest pattern to file paths relative to root. */
 export declare function expandPattern(root: string, io: GenIO, pattern: string): Promise<string[]>;
 /** The deploy-by-convention directory (ADR 0062): when the manifest declares no `models`, both the
- *  runtime deploy and this codegen scan discover deployables/models under it — shallow, one level
- *  deep (`resources/*` and `resources/<subdir>/*`). Deploy-only by convention. */
+ *  runtime deploy and this codegen scan discover deployables/models under it — **recursively**,
+ *  every file at any depth (issue #231). Deploy-only by convention. */
 export declare const RESOURCES_DIR = "resources";
 /**
- * Discover model files under `resources/` by convention — shallow, one level deep (`resources/*`
- * and `resources/<subdir>/*`), never deeper — mirroring the runtime deploy walk so the codegen scan
- * and the deploy see the same set. Returns root-relative paths, sorted. Descending one level needs
+ * Discover model files under `resources/` by convention — **recursively**, every `.bpmn`/`.dmn`
+ * under `resources/` at any depth (issue #231) — mirroring the runtime deploy walk so the codegen
+ * scan and the deploy see the same set. Returns root-relative paths, sorted. Descending needs
  * `io.listSubdirs`; without it only the files directly under `resources/` are scanned.
  */
 export declare function discoverResourceModels(root: string, io: GenIO): Promise<string[]>;

package/dist/toolkit/gen.js

@@ -10,6 +10,7 @@ import { deriveMeta } from "./derivers/meta.js";
 import { deriveMessageBindings } from "./derivers/messages.js";
 import { resolveShapes, scanModelShapes } from "./derivers/shapes.js";
 import { deriveApi } from "./derivers/api.js";
+import { deriveSystemBrief } from "./derivers/system-brief.js";
 import { parseSpec, sharedRequestBodySchemas } from "../openapi/spec.js";
 import { deriveModels, MODEL_PROVENANCE } from "./models.js";
 function join(root, rel) {
@@ -47,31 +48,31 @@ export async function expandPattern(root, io, pattern) {
         .sort();
 }
 /** The deploy-by-convention directory (ADR 0062): when the manifest declares no `models`, both the
- *  runtime deploy and this codegen scan discover deployables/models under it — shallow, one level
- *  deep (`resources/*` and `resources/<subdir>/*`). Deploy-only by convention. */
+ *  runtime deploy and this codegen scan discover deployables/models under it — **recursively**,
+ *  every file at any depth (issue #231). Deploy-only by convention. */
 export const RESOURCES_DIR = "resources";
 /** Model file extensions the `nano:shape`/code-first scan reads by convention (BPMN + DMN). */
 const MODEL_EXTS = [".bpmn", ".dmn"];
 /**
- * Discover model files under `resources/` by convention — shallow, one level deep (`resources/*`
- * and `resources/<subdir>/*`), never deeper — mirroring the runtime deploy walk so the codegen scan
- * and the deploy see the same set. Returns root-relative paths, sorted. Descending one level needs
+ * Discover model files under `resources/` by convention — **recursively**, every `.bpmn`/`.dmn`
+ * under `resources/` at any depth (issue #231) — mirroring the runtime deploy walk so the codegen
+ * scan and the deploy see the same set. Returns root-relative paths, sorted. Descending needs
  * `io.listSubdirs`; without it only the files directly under `resources/` are scanned.
  */
 export async function discoverResourceModels(root, io) {
     const isModel = (n) => MODEL_EXTS.some((e) => n.endsWith(e));
     const out = [];
-    for (const n of await io.listDir(join(root, RESOURCES_DIR))) {
-        if (isModel(n))
-            out.push(`${RESOURCES_DIR}/${n}`);
-    }
-    const subdirs = io.listSubdirs ? await io.listSubdirs(join(root, RESOURCES_DIR)) : [];
-    for (const sub of subdirs.slice().sort()) {
-        for (const n of await io.listDir(join(root, `${RESOURCES_DIR}/${sub}`))) {
+    const walk = async (rel) => {
+        for (const n of await io.listDir(join(root, rel))) {
             if (isModel(n))
-                out.push(`${RESOURCES_DIR}/${sub}/${n}`);
+                out.push(`${rel}/${n}`);
         }
-    }
+        const subdirs = io.listSubdirs ? await io.listSubdirs(join(root, rel)) : [];
+        for (const sub of subdirs.slice().sort()) {
+            await walk(`${rel}/${sub}`);
+        }
+    };
+    await walk(RESOURCES_DIR);
     return out.sort();
 }
 /**
@@ -162,6 +163,11 @@ async function collectAll(opts) {
             artifacts.push(...deriveWorkerBindings(models, declaredTypeIds));
             artifacts.push(...deriveMeta(models));
             artifacts.push(...deriveMessageBindings(models, declaredTypeIds));
+            // Institutional-memory brief (ADR 0060): fold the same scanned model structure into the
+            // app's agent/human-readable system brief. Flows through `artifacts` like its siblings, so
+            // the `nano-generated/` stale sweep and the `urban gen --check` drift gate own the two new
+            // artifacts (system-brief.md / .json) with no extra bookkeeping.
+            artifacts.push(...deriveSystemBrief(models, manifest.id));
             // Surface genuine data-envelope conflicts: a taskType whose variants disagree on a field's
             // TYPE. The emitted contract is the union of the variants (sound for a shared handler), so a
             // type clash would silently widen to `A | B` — warn instead so the author unifies the envelope.

package/dist/toolkit/index.d.ts

@@ -14,6 +14,8 @@ export type { MetaDecl } from "./derivers/meta.ts";
 export { deriveMessageBindings, emitMessageBindings, emitMessageBindingsRuntime, messagesDeriver, scanModelMessages, MESSAGE_BINDINGS_DTS, MESSAGE_BINDINGS_TS, } from "./derivers/messages.ts";
 export type { MessageIo, MessageBindingDecl } from "./derivers/messages.ts";
 export { apiDeriver, deriveApi, emitApiBindings, emitApiBindingsRuntime, emitApiController, schemaToTs, API_BINDINGS_DTS, API_BINDINGS_TS, API_CONTROLLER_TS, } from "./derivers/api.ts";
+export { buildSystemBrief, deriveSystemBrief, emitSystemBriefMd, foldOwnership, scanModelDecisions, systemBriefDeriver, SYSTEM_BRIEF_JSON, SYSTEM_BRIEF_MD, } from "./derivers/system-brief.ts";
+export type { DecisionRef, Ownership, SystemBrief } from "./derivers/system-brief.ts";
 export { collectOperations, HTTP_METHODS, isSafeOperationId, operationsWithoutId, operationsWithUnsafeId, parseSpec, refName, resolveSchema, toRouteMatcher, undeclaredPathParams, validateValue, } from "../openapi/spec.ts";
 export type { HttpMethodLower, OpenApiDoc, OpenApiParameter, OpenApiSchema, OperationInfo, } from "../openapi/spec.ts";
 export declare const DERIVERS: readonly [import("./artifact.ts").Deriver<import("./derivers/migrations.ts").ToolkitManifest>, import("./artifact.ts").Deriver<import("./derivers/migrations.ts").ToolkitManifest>, import("./artifact.ts").Deriver<{
@@ -28,6 +30,9 @@ export declare const DERIVERS: readonly [import("./artifact.ts").Deriver<import(
     doc: import("../openapi/spec.ts").OpenApiDoc;
     operationsDir?: string;
     surfaceEject?: boolean;
+}>, import("./artifact.ts").Deriver<{
+    models: import("./derivers/worker-io.ts").ModelSource[];
+    app?: string;
 }>];
 export { collectArtifacts, runGen, joinPath, readModels, expandPattern, previewModels } from "./gen.ts";
 export type { GenIO, GenOptions, GenResult } from "./gen.ts";

package/dist/toolkit/index.js

@@ -12,6 +12,7 @@ export { byModelPath, typeRefFor } from "./derivers/worker-io.js";
 export { deriveMeta, emitMeta, foldMeta, metaDeriver, scanModelMeta, META_TS, } from "./derivers/meta.js";
 export { deriveMessageBindings, emitMessageBindings, emitMessageBindingsRuntime, messagesDeriver, scanModelMessages, MESSAGE_BINDINGS_DTS, MESSAGE_BINDINGS_TS, } from "./derivers/messages.js";
 export { apiDeriver, deriveApi, emitApiBindings, emitApiBindingsRuntime, emitApiController, schemaToTs, API_BINDINGS_DTS, API_BINDINGS_TS, API_CONTROLLER_TS, } from "./derivers/api.js";
+export { buildSystemBrief, deriveSystemBrief, emitSystemBriefMd, foldOwnership, scanModelDecisions, systemBriefDeriver, SYSTEM_BRIEF_JSON, SYSTEM_BRIEF_MD, } from "./derivers/system-brief.js";
 // The OpenAPI machinery the deriver + runtime share (ADR 0058).
 export { collectOperations, HTTP_METHODS, isSafeOperationId, operationsWithoutId, operationsWithUnsafeId, parseSpec, refName, resolveSchema, toRouteMatcher, undeclaredPathParams, validateValue, } from "../openapi/spec.js";
 // The registry of all derivers (for discovery / IDE migration).
@@ -21,6 +22,7 @@ import { workerIoDeriver } from "./derivers/worker-io.js";
 import { metaDeriver } from "./derivers/meta.js";
 import { messagesDeriver } from "./derivers/messages.js";
 import { apiDeriver } from "./derivers/api.js";
+import { systemBriefDeriver } from "./derivers/system-brief.js";
 export const DERIVERS = [
     migrationsDeriver,
     domainDeriver,
@@ -28,6 +30,7 @@ export const DERIVERS = [
     metaDeriver,
     messagesDeriver,
     apiDeriver,
+    systemBriefDeriver,
 ];
 // Gen orchestrator + IO
 export { collectArtifacts, runGen, joinPath, readModels, expandPattern, previewModels } from "./gen.js";

package/dist/toolkit/models.d.ts

@@ -5,9 +5,10 @@ import type { ModelSource } from "./derivers/worker-io.ts";
 /** Default source glob for code-first flows (matches the code-first scaffold layout). */
 export declare const DEFAULT_WORKFLOW_PATTERNS: string[];
 /** Default output dir for derived models when the manifest declares no `models.processes`: under
- * the deploy-by-convention `resources/` tree (ADR 0062), one level deep, so a derived model lands
- * exactly where the convention deploy + codegen scan look for it. When `models.processes` IS set,
- * `processesOutDir` derives the dir from that glob instead (the model-first override). */
+ * the deploy-by-convention `resources/` tree (ADR 0062), so a derived model lands where the
+ * convention deploy + codegen scan (which walk `resources/` recursively) look for it. When
+ * `models.processes` IS set, `processesOutDir` derives the dir from that glob instead (the
+ * model-first override). */
 export declare const PROCESSES_DIR = "resources/processes";
 /** Marker stamped into every derived `.bpmn` (an XML comment) so re-gen overwrites and the
  * stale sweep deletes ONLY derived output — never an authored, human-owned model. */

package/dist/toolkit/models.js

@@ -14,9 +14,10 @@ import { isRecord } from "../runtime/core/guards.js";
 /** Default source glob for code-first flows (matches the code-first scaffold layout). */
 export const DEFAULT_WORKFLOW_PATTERNS = ["workflows/*.ts"];
 /** Default output dir for derived models when the manifest declares no `models.processes`: under
- * the deploy-by-convention `resources/` tree (ADR 0062), one level deep, so a derived model lands
- * exactly where the convention deploy + codegen scan look for it. When `models.processes` IS set,
- * `processesOutDir` derives the dir from that glob instead (the model-first override). */
+ * the deploy-by-convention `resources/` tree (ADR 0062), so a derived model lands where the
+ * convention deploy + codegen scan (which walk `resources/` recursively) look for it. When
+ * `models.processes` IS set, `processesOutDir` derives the dir from that glob instead (the
+ * model-first override). */
 export const PROCESSES_DIR = "resources/processes";
 /** Marker stamped into every derived `.bpmn` (an XML comment) so re-gen overwrites and the
  * stale sweep deletes ONLY derived output — never an authored, human-owned model. */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.51.0",
+	"version": "0.53.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",