@nanobpm/urban 0.52.0 → 0.53.0

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";
@@ -35,6 +39,8 @@ export { applyAmbientLineage, buildLineageTree, deriveLineage, LINEAGE_KEY, LINE
 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
@@ -33,6 +36,10 @@ export { evalCorrelation } from "./core/modules/triggers.js";
 // 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.52.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",