@nanobpm/urban 0.52.0 → 0.53.0

package/src/runtime/core/runtime.ts

@@ -20,6 +20,8 @@ import { mountTriggers } from "./modules/triggers.ts";
 import { mountInstanceTracking } from "./modules/instance-tracking.ts";
 import type { SchedulerDeps } from "./modules/scheduler.ts";
 import { mountSecurity, type SecurityPolicy } from "./modules/security.ts";
+import { EventBus } from "./events.ts";
+import { createUrbanEvents, mountExtensions, 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. */
@@ -82,6 +84,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 {
@@ -112,6 +122,14 @@ 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 async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<UrbanApp> {
@@ -137,6 +155,20 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
   // 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.
@@ -162,6 +194,8 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
   // 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();
@@ -189,12 +223,18 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
     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: UrbanApp = {
     manifest,
     root,
     log: appLog,
+    events,
     get data() {
       return data;
     },
@@ -212,6 +252,7 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
     async start() {
       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);
         if (flags.deploy) describe.deploy = await deployModels(ctx);
@@ -237,6 +278,13 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
           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: Route[] = [];
         let hasUiSurfaces = false;
         if (flags.surfaces) {
@@ -308,6 +356,7 @@ export async function createUrbanApp(opts: CreateUrbanAppOptions): Promise<Urban
           }
         }
         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,
         // a bound port) or wedged in the "already started" state.

package/src/runtime/devserver.test.ts

@@ -4,6 +4,8 @@ import { runDev, shouldReload, type DevDeps } from "./devserver.ts";
 import type { HostContext } from "./core/host.ts";
 import type { UrbanApp } from "./core/runtime.ts";
 import { createLogger } from "./core/logger.ts";
+import { createUrbanEvents } from "./core/extensions.ts";
+import { EventBus } from "./core/events.ts";
 
 const delay = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
 
@@ -232,6 +234,7 @@ function fakeApp(stops: string[], id: string): UrbanApp {
     security: undefined,
     httpPort: undefined,
     httpServer: undefined,
+    events: createUrbanEvents(new EventBus()),
   };
 }
 

package/src/runtime/index.ts

@@ -8,6 +8,37 @@ export type {
   UrbanApp,
 } from "./core/runtime.ts";
 
+// Extension-event taxonomy + microkernel (issue #262)
+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";
+
 // Manifest
 export {
   bindModeToHost,
@@ -178,6 +209,32 @@ export type {
   LineageStoreOptions,
 } from "./core/modules/lineage-store.ts";
 
+// 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.ts";
+export type {
+  CrumbKind,
+  CrumbSource,
+  DerivePhaseOptions,
+  FurthestReached,
+  InstancePhase,
+  LineagePhaseRollup,
+  Phase,
+  PhaseCrumb,
+  PhaseGranularity,
+  ProvenanceProgressRow,
+  ScopeElement,
+  ScopeIndex,
+} from "./core/phase.ts";
+
 // Model deploy (deploy-by-convention under `resources/`, ADR 0062)
 export { deployModels, RESOURCES_DIR } from "./core/modules/deploy.ts";
 export { defaultScheduler, MAX_TIMER_DELAY_MS } from "./core/modules/scheduler.ts";

package/src/toolkit/derivers/system-brief.test.ts

@@ -0,0 +1,150 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  buildSystemBrief,
+  deriveSystemBrief,
+  emitSystemBriefMd,
+  foldOwnership,
+  scanModelDecisions,
+  SYSTEM_BRIEF_JSON,
+  SYSTEM_BRIEF_MD,
+  type SystemBrief,
+} from "./system-brief.ts";
+import type { ModelSource } from "./worker-io.ts";
+
+// A model with a service task (worker), a business-rule task (decision), and ownership
+// `nano:meta` (single-valued + two repeated `adr`s).
+const ORDER_XML = `
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL"
+  xmlns:zeebe="http://camunda.org/schema/zeebe/1.0">
+  <bpmn:process id="order-fulfilment">
+    <bpmn:extensionElements>
+      <nano:meta xmlns:nano="urn:nano" key="owner" value="payments-team" />
+      <nano:meta xmlns:nano="urn:nano" key="slack" value="#payments" />
+      <nano:meta xmlns:nano="urn:nano" key="adr" value="ADR 0040" />
+      <nano:meta xmlns:nano="urn:nano" key="adr" value="ADR 0060" />
+    </bpmn:extensionElements>
+    <bpmn:serviceTask id="charge">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="charge-card" />
+        <zeebe:ioMapping>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="io.acme.ChargeReq" />
+          <zeebe:property name="io.nanobpm.dataEnvelope.out" value="io.acme.ChargeRes" />
+        </zeebe:ioMapping>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:businessRuleTask id="risk">
+      <bpmn:extensionElements>
+        <zeebe:calledDecision decisionId="fraud-score" resultVariable="score" />
+      </bpmn:extensionElements>
+    </bpmn:businessRuleTask>
+  </bpmn:process>
+</bpmn:definitions>`;
+
+const models: ModelSource[] = [{ path: "order.bpmn", xml: ORDER_XML }];
+
+test("scanModelDecisions extracts businessRuleTask → calledDecision", () => {
+  const decisions = scanModelDecisions(ORDER_XML);
+  assert.deepEqual(decisions, [
+    { process: "order-fulfilment", elementId: "risk", decisionId: "fraud-score" },
+  ]);
+});
+
+test("foldOwnership folds reserved meta keys, accumulating repeated `adr`", () => {
+  const own = foldOwnership(models);
+  assert.equal(own.owner, "payments-team");
+  assert.equal(own.slack, "#payments");
+  assert.deepEqual(own.adrs, ["ADR 0040", "ADR 0060"]);
+  assert.equal(own.team, undefined);
+});
+
+// `nano:meta` keys are user-authored, so a crafted key that collides with an
+// `Object.prototype` member (e.g. `toString`) must NOT be treated as a reserved
+// ownership key. Guards against prototype-chain membership checks (`k in OWNERSHIP_KEYS`).
+test("foldOwnership ignores Object.prototype keys in crafted meta", () => {
+  const xml = `
+<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL">
+  <bpmn:process id="hostile">
+    <bpmn:extensionElements>
+      <nano:meta xmlns:nano="urn:nano" key="toString" value="pwned" />
+      <nano:meta xmlns:nano="urn:nano" key="constructor" value="pwned" />
+      <nano:meta xmlns:nano="urn:nano" key="hasOwnProperty" value="pwned" />
+    </bpmn:extensionElements>
+  </bpmn:process>
+</bpmn:definitions>`;
+  const own = foldOwnership([{ path: "hostile.bpmn", xml }]);
+  assert.deepEqual(own, { adrs: [] });
+});
+
+test("buildSystemBrief folds processes, call graph, decisions, ownership", () => {
+  const b: SystemBrief = buildSystemBrief(models, "acme-orders");
+  assert.equal(b.app, "acme-orders");
+  assert.deepEqual(b.processes, ["order-fulfilment"]);
+  assert.equal(b.workers.length, 1);
+  assert.equal(b.workers[0].taskType, "charge-card");
+  assert.equal(b.workers[0].in, "io.acme.ChargeReq");
+  assert.equal(b.decisions[0].decisionId, "fraud-score");
+  assert.equal(b.ownership.owner, "payments-team");
+});
+
+test("emitSystemBriefMd renders owner, call graph, and decisions", () => {
+  const md = emitSystemBriefMd(buildSystemBrief(models, "acme-orders"));
+  assert.match(md, /# acme-orders — system brief/);
+  assert.match(md, /payments-team/);
+  assert.match(md, /ADR 0040, ADR 0060/);
+  assert.match(md, /charge-card/);
+  assert.match(md, /fraud-score/);
+});
+
+test("emitSystemBriefMd degrades gracefully with no ownership meta", () => {
+  const bare = `<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL">
+    <bpmn:process id="p1"></bpmn:process></bpmn:definitions>`;
+  const md = emitSystemBriefMd(buildSystemBrief([{ path: "p.bpmn", xml: bare }]));
+  assert.match(md, /No ownership metadata declared/);
+  assert.match(md, /## Processes/);
+});
+
+test("emitSystemBriefMd escapes `|` and newlines in model-authored ownership cells", () => {
+  const evil = `<bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL">
+    <bpmn:process id="p1">
+      <bpmn:extensionElements>
+        <nano:meta xmlns:nano="urn:nano" key="owner" value="a | b" />
+      </bpmn:extensionElements>
+    </bpmn:process></bpmn:definitions>`;
+  const md = emitSystemBriefMd(buildSystemBrief([{ path: "p.bpmn", xml: evil }]));
+  const ownerLine = md.split("\n").find((l) => l.startsWith("| Owner |"));
+  assert.ok(ownerLine, "owner row rendered");
+  // The literal `|` from the meta value must be escaped so it can't add a phantom column.
+  assert.match(ownerLine!, /a \\\| b/);
+});
+
+test("processId only recognises `bpmn:process` (consistent with scanModelWorkers)", () => {
+  // A non-`bpmn:`-prefixed process must not be listed, otherwise the brief would show a process
+  // id while every worker/decision row carried an empty Process column.
+  const other = `<definitions xmlns:foo="urn:foo">
+    <foo:process id="not-bpmn"></foo:process></definitions>`;
+  const b = buildSystemBrief([{ path: "o.bpmn", xml: other }]);
+  assert.deepEqual(b.processes, []);
+});
+
+test("deriveSystemBrief emits both artifacts with valid JSON", () => {
+  const arts = deriveSystemBrief(models, "acme-orders");
+  const md = arts.find((a) => a.path.endsWith(SYSTEM_BRIEF_MD));
+  const json = arts.find((a) => a.path.endsWith(SYSTEM_BRIEF_JSON));
+  assert.ok(md && json);
+  const parsed: unknown = JSON.parse(json!.content);
+  assertSystemBriefShape(parsed);
+  assert.equal(parsed.app, "acme-orders");
+  assert.equal(parsed.workers[0].taskType, "charge-card");
+});
+
+/** Runtime-validate the parsed JSON shape (no `as` cast — banned in this repo) and narrow it to
+ * `SystemBrief` for the assertions that follow. */
+function assertSystemBriefShape(v: unknown): asserts v is SystemBrief {
+  assert.ok(typeof v === "object" && v !== null, "brief is an object");
+  assert.ok(!("app" in v) || typeof v.app === "string", "app is absent or a string");
+  assert.ok("workers" in v && Array.isArray(v.workers), "workers is an array");
+  assert.ok("processes" in v && Array.isArray(v.processes), "processes is an array");
+  assert.ok("decisions" in v && Array.isArray(v.decisions), "decisions is an array");
+  assert.ok("ownership" in v && typeof v.ownership === "object" && v.ownership !== null, "ownership is an object");
+}

package/src/toolkit/derivers/system-brief.ts

@@ -0,0 +1,210 @@
+// 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 type { DerivedArtifact, Deriver } from "../artifact.ts";
+import { GENERATED_DIR } from "../artifact.ts";
+import { byModelPath, type ModelSource, scanModelWorkers, type WorkerIo } from "./worker-io.ts";
+import { scanModelMeta } from "./meta.ts";
+
+/** Basenames of the two emitted artifacts. */
+export const SYSTEM_BRIEF_MD = "system-brief.md";
+export 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;
+}
+
+function attr(tag: string, name: string): string | undefined {
+  const m = tag.match(new RegExp(`\\b${name}\\s*=\\s*"([^"]*)"`));
+  return m ? m[1] : undefined;
+}
+
+function processId(xml: string): string | undefined {
+  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: string): DecisionRef[] {
+  const proc = processId(xml);
+  const out: DecisionRef[] = [];
+  const blockRe = /<bpmn:businessRuleTask\b([^>]*)>([\s\S]*?)<\/bpmn:businessRuleTask>/g;
+  let m: RegExpExecArray | null;
+  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: Record<string, Exclude<keyof Ownership, "adrs">> = {
+  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: ModelSource[]): Ownership {
+  const own: Ownership = { 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: ModelSource[], app?: string): SystemBrief {
+  const sorted = [...models].sort(byModelPath);
+  const workers: WorkerIo[] = [];
+  const decisions: DecisionRef[] = [];
+  const processes: string[] = [];
+  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: string): string {
+  return s.replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+
+function mdTable(headers: string[], rows: string[][]): string {
+  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: SystemBrief): string {
+  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: ModelSource[], app?: string): DerivedArtifact[] {
+  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: Deriver<{ models: ModelSource[]; app?: string }> = {
+  id: "system-brief",
+  describe: "App institutional-memory brief (processes, call graph, decisions, ownership) — ADR 0060",
+  derive: ({ models, app }) => deriveSystemBrief(models, app),
+};

package/src/toolkit/gen.test.ts

@@ -74,7 +74,7 @@ function fixture(): Record<string, string> {
   };
 }
 
-test("runGen writes migrations, the worker index, the meta accessor, and the message map", async () => {
+test("runGen writes migrations, the worker index, the meta accessor, the message map, and the system brief", async () => {
   const io = memIO(fixture());
   const res = await runGen({ root: "/app", io });
   const paths = res.artifacts.map((a) => a.path).sort();
@@ -83,6 +83,8 @@ test("runGen writes migrations, the worker index, the meta accessor, and the mes
     "nano-generated/domain-rows.d.ts",
     "nano-generated/message-io.d.ts",
     "nano-generated/meta.ts",
+    "nano-generated/system-brief.json",
+    "nano-generated/system-brief.md",
     "nano-generated/worker-io.d.ts",
   ]);
   assert.ok(io.files["/app/nano-generated/app.schema.sql"].includes("CREATE TABLE"));
@@ -91,6 +93,27 @@ test("runGen writes migrations, the worker index, the meta accessor, and the mes
   assert.ok(io.files["/app/nano-generated/message-io.d.ts"].includes("export type MessageName"));
   assert.ok(io.files["/app/nano-generated/domain-rows.d.ts"].includes('"greetings": Greetings;'));
   assert.ok(io.files["/app/nano-generated/domain-rows.d.ts"].includes('"greeting": {'));
+  // The system brief threads the app id from the manifest and folds the process + call graph.
+  assert.ok(io.files["/app/nano-generated/system-brief.md"].includes("# demo — system brief"));
+  assert.ok(io.files["/app/nano-generated/system-brief.md"].includes("demo.do"));
+  const brief = JSON.parse(io.files["/app/nano-generated/system-brief.json"]);
+  assert.equal(brief.app, "demo");
+  assert.deepEqual(brief.processes, ["p"]);
+  assert.equal(brief.workers[0].taskType, "demo.do");
+});
+
+test("the system brief is drift-checked and swept like its sibling artifacts", async () => {
+  const io = memIO(fixture());
+  await runGen({ root: "/app", io });
+  // Drift gate owns the brief: a hand-edit is reported by --check.
+  io.files["/app/nano-generated/system-brief.json"] = "{ tampered: true }";
+  const check = await runGen({ root: "/app", io, check: true });
+  assert.ok(check.drift.includes("nano-generated/system-brief.json"), "brief drift is reported");
+  // Stale sweep owns the brief: a renamed-away brief artifact is removed on the next write.
+  io.files["/app/nano-generated/system-brief.old.md"] = "# stale brief";
+  const res = await runGen({ root: "/app", io });
+  assert.ok(res.swept.includes("nano-generated/system-brief.old.md"), "stale brief swept");
+  assert.ok("/app/nano-generated/system-brief.md" in io.files, "fresh brief kept");
 });
 
 test("gen --check reports no drift right after a write", async () => {
@@ -345,13 +368,14 @@ test("readModels: a models block without processes suppresses the resources/ con
   const io = memIO({
     "/app/resources/a.bpmn": "<bpmn:definitions/>",
     "/app/resources/sub/b.bpmn": "<bpmn:definitions/>",
+    "/app/resources/sub/deeper/c.bpmn": "<bpmn:definitions/>",
   });
-  // No models block at all → convention scans resources/ (shallow, one level deep).
+  // No models block at all → convention scans resources/ recursively (issue #231).
   const byConvention = await readModels("/app", io, {});
   assert.deepEqual(
     byConvention.map((m) => m.path).sort(),
-    ["resources/a.bpmn", "resources/sub/b.bpmn"],
-    "with no models block, gen discovers under resources/ by convention",
+    ["resources/a.bpmn", "resources/sub/b.bpmn", "resources/sub/deeper/c.bpmn"],
+    "with no models block, gen discovers under resources/ recursively by convention",
   );
   // A declared models block (even one that resolves to zero process files) is an explicit override:
   // the convention scan must be skipped entirely, matching runtime deployModels.