@nanobpm/urban 0.51.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/engine/nanosdk.test.ts

@@ -11,6 +11,9 @@ import {
   type NanoSdkJobWorkerConfig,
 } from "./nanosdk.ts";
 import { BpmnError } from "../core/host.ts";
+import { __resetExecStoreForTests, installExecStore, runInJobContext } from "../core/execContext.ts";
+import { readLineage } from "../core/lineage.ts";
+import { createNodeHost } from "../adapters/node.ts";
 
 /** A fake nano-sdk client that records calls and lets a test drive its job worker. */
 function fakeSdkClient(overrides: Partial<NanoSdkClient> = {}): NanoSdkClient & {
@@ -133,7 +136,8 @@ test("createInstance routes through the SDK and coerces the key", async () => {
   const engine = new SdkEngineClient(client);
   const res = await engine.createInstance({ processDefinitionId: "p", variables: { a: 1 } });
   assert.equal(res.processInstanceKey, "99");
-  assert.deepEqual(res.variables, { a: 1 });
+  // Caller variables are preserved (the SDK also auto-threads a `_urban.lineage` envelope, tested below).
+  assert.equal(res.variables?.a, 1);
   assert.ok(client.calls.includes("createProcessInstance"));
 });
 
@@ -162,7 +166,7 @@ test("cancelInstance routes through the SDK", async () => {
   assert.ok(client.calls.includes("cancelProcessInstance") || seen !== undefined);
 });
 
-test("publishMessage defaults correlationKey/variables", async () => {
+test("publishMessage defaults correlationKey and auto-threads lineage onto variables", async () => {
   let seen: Record<string, unknown> | undefined;
   const client = fakeSdkClient({
     publishMessage: async (input) => {
@@ -172,7 +176,12 @@ test("publishMessage defaults correlationKey/variables", async () => {
   });
   const engine = new SdkEngineClient(client);
   await engine.publishMessage({ name: "m" });
-  assert.deepEqual(seen, { name: "m", correlationKey: "", variables: {} });
+  assert.equal(seen?.name, "m");
+  assert.equal(seen?.correlationKey, "");
+  // With no ambient job context this is a top-level publish: a fresh root envelope is minted.
+  const env = readLineage(seen?.variables);
+  assert.ok(env, "a lineage envelope is threaded onto the message variables");
+  assert.equal(env?.causedByInstanceKey, undefined);
 });
 
 test("searchUserTasks passes zero-wait consistency and maps items", async () => {
@@ -670,3 +679,88 @@ test("createNanoSdkEngineClient uses an injected client factory with the resolve
   assert.deepEqual(seen, { restAddress: "http://x/v2", token: "t", transport: "falcon" });
   assert.ok(engine);
 });
+
+// --- Lineage auto-threading (issue #254) ---------------------------------------
+
+/** A fake client that captures the variables handed to createProcessInstance/publishMessage. */
+function capturingClient(): NanoSdkClient & { createVars?: Record<string, unknown>; msgVars?: Record<string, unknown> } {
+  const base = fakeSdkClient();
+  const cap: NanoSdkClient & { createVars?: Record<string, unknown>; msgVars?: Record<string, unknown> } = {
+    ...base,
+    async createProcessInstance(input) {
+      cap.createVars = input.variables;
+      return { processInstanceKey: 99, variables: input.variables };
+    },
+    async publishMessage(input) {
+      cap.msgVars = input.variables;
+      return { key: 1 };
+    },
+  };
+  return cap;
+}
+
+test("createInstance mints a fresh root envelope for a top-level request (no ambient)", async () => {
+  __resetExecStoreForTests();
+  const client = capturingClient();
+  const engine = new SdkEngineClient(client);
+  await engine.createInstance({ processDefinitionId: "p", variables: { a: 1 } });
+  const env = readLineage(client.createVars);
+  assert.ok(env, "an envelope was threaded onto the variables");
+  assert.notEqual(env?.rootRequestKey, "");
+  assert.equal(env?.causedByInstanceKey, undefined, "a fresh root has no cause");
+  assert.equal(client.createVars?.a, 1, "caller variables are preserved");
+});
+
+test("createInstance propagates the ambient lineage and stamps causedByInstanceKey", async () => {
+  __resetExecStoreForTests();
+  const host = createNodeHost({ cwd: process.cwd(), log: () => {} });
+  installExecStore(() => host.createAsyncStore?.());
+  const client = capturingClient();
+  const engine = new SdkEngineClient(client);
+  try {
+    await runInJobContext({ instanceKey: "pi-parent", rootRequestKey: "root-1", jobType: "w" }, () =>
+      engine.createInstance({ processDefinitionId: "child" }),
+    );
+  } finally {
+    __resetExecStoreForTests();
+  }
+  assert.deepEqual(readLineage(client.createVars), {
+    rootRequestKey: "root-1",
+    causedByInstanceKey: "pi-parent",
+  });
+});
+
+test("createInstance leaves an explicit caller-supplied envelope untouched (override wins)", async () => {
+  __resetExecStoreForTests();
+  const host = createNodeHost({ cwd: process.cwd(), log: () => {} });
+  installExecStore(() => host.createAsyncStore?.());
+  const client = capturingClient();
+  const engine = new SdkEngineClient(client);
+  try {
+    await runInJobContext({ instanceKey: "pi-parent", rootRequestKey: "root-1", jobType: "w" }, () =>
+      engine.createInstance({
+        processDefinitionId: "child",
+        variables: { _urban: { lineage: { rootRequestKey: "explicit" } } },
+      }),
+    );
+  } finally {
+    __resetExecStoreForTests();
+  }
+  assert.deepEqual(readLineage(client.createVars), { rootRequestKey: "explicit", causedByInstanceKey: undefined });
+});
+
+test("publishMessage threads lineage so message-started instances inherit it", async () => {
+  __resetExecStoreForTests();
+  const host = createNodeHost({ cwd: process.cwd(), log: () => {} });
+  installExecStore(() => host.createAsyncStore?.());
+  const client = capturingClient();
+  const engine = new SdkEngineClient(client);
+  try {
+    await runInJobContext({ instanceKey: "pi-9", rootRequestKey: "root-9", jobType: "w" }, () =>
+      engine.publishMessage({ name: "start" }),
+    );
+  } finally {
+    __resetExecStoreForTests();
+  }
+  assert.deepEqual(readLineage(client.msgVars), { rootRequestKey: "root-9", causedByInstanceKey: "pi-9" });
+});

package/src/runtime/engine/nanosdk.ts

@@ -31,6 +31,7 @@ import {
 } from "../core/form-contract.ts";
 import type { EngineSdkClient } from "./sdk.ts";
 import { isRecord } from "../core/guards.ts";
+import { applyAmbientLineage } from "../core/lineage.ts";
 
 /** 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. */
@@ -193,9 +194,12 @@ export class SdkEngineClient implements EngineClient {
     variables?: Record<string, unknown>;
     awaitCompletion?: boolean;
   }): Promise<{ processInstanceKey: string; variables?: Record<string, unknown> }> {
+    // 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;
@@ -217,10 +221,12 @@ export class SdkEngineClient implements EngineClient {
     correlationKey?: string;
     variables?: Record<string, unknown>;
   }): Promise<void> {
+    // 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),
     });
   }
 

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,
@@ -143,6 +174,67 @@ export type {
 } from "./core/modules/llm.ts";
 export { evalCorrelation } from "./core/modules/triggers.ts";
 
+// 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.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";
+
+// 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");
+}