@nanobpm/urban 0.52.0 → 0.54.0

package/src/runtime/core/extensions.test.ts

@@ -0,0 +1,378 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createLogger } from "./logger.ts";
+import type { AppApi } from "./context.ts";
+import {
+  URBAN_EVENT_MODES,
+  createUrbanEvents,
+  mountExtensions,
+  urbanEventMode,
+  type GateDecision,
+  type GateRequest,
+  type UrbanEventName,
+  type UrbanExtension,
+} from "./extensions.ts";
+import { EventBus } from "./events.ts";
+
+// A minimal AppApi double — the extension host only reaches for `log` (and hands
+// `app` through to extensions untouched). The typed-but-unused fields are filled
+// via `JSON.parse` (returns `any`) per AGENTS.md, never an `as`-cast.
+function unused<T>(): T {
+  return JSON.parse("null");
+}
+
+function fakeApi(): AppApi {
+  return {
+    manifest: unused(),
+    data: unused(),
+    engine: unused(),
+    env: () => undefined,
+    log: createLogger(() => {}),
+  };
+}
+
+test("taxonomy — the typed channels agree with the documented mode table", () => {
+  assert.equal(URBAN_EVENT_MODES.lifecycle, "emit");
+  assert.equal(URBAN_EVENT_MODES["extension/register"], "serial");
+  assert.equal(URBAN_EVENT_MODES["request/dispatch"], "waterfall");
+  assert.equal(URBAN_EVENT_MODES["security/gate"], "waterfall");
+  assert.equal(URBAN_EVENT_MODES.reconcile, "parallel");
+  assert.equal(urbanEventMode("security/gate"), "waterfall");
+});
+
+test("taxonomy — createUrbanEvents declares every seam exactly once on a bus", () => {
+  const bus = new EventBus();
+  const events = createUrbanEvents(bus);
+  assert.equal(events.lifecycle.mode, "emit");
+  assert.equal(events.extensionRegister.mode, "serial");
+  assert.equal(events.requestDispatch.mode, "waterfall");
+  assert.equal(events.securityGate.mode, "waterfall");
+  assert.equal(events.reconcile.mode, "parallel");
+});
+
+test("taxonomy — every typed channel derives its mode from URBAN_EVENT_MODES, with exact seam coverage (no drift)", () => {
+  const bus = new EventBus();
+  const events = createUrbanEvents(bus);
+  // Bind each typed channel to its canonical seam name, then assert the mode is
+  // read from URBAN_EVENT_MODES rather than hardcoded — so changing the table (or
+  // a channel's declared mode) without matching the other fails this guard.
+  const bindings: ReadonlyArray<[{ readonly event: string; readonly mode: string }, UrbanEventName]> = [
+    [events.lifecycle, "lifecycle"],
+    [events.extensionRegister, "extension/register"],
+    [events.requestDispatch, "request/dispatch"],
+    [events.securityGate, "security/gate"],
+    [events.reconcile, "reconcile"],
+  ];
+  for (const [channel, seam] of bindings) {
+    assert.equal(channel.event, seam, `channel declares seam "${channel.event}", expected "${seam}"`);
+    assert.equal(channel.mode, URBAN_EVENT_MODES[seam], `channel "${seam}" mode drifted from URBAN_EVENT_MODES`);
+  }
+  // Coverage is exact: every documented seam is bound to a channel and vice versa.
+  assert.deepEqual(new Set(bindings.map(([, seam]) => seam)), new Set(Object.keys(URBAN_EVENT_MODES)));
+});
+
+test("mountExtensions — runs the connector-pack / agentic-family surface through the taxonomy in a deterministic order", async () => {
+  const registered: string[] = [];
+  const mk = (name: string, order?: number): UrbanExtension => ({
+    name,
+    order,
+    setup(ctx) {
+      registered.push(name);
+      ctx.events.lifecycle.on(() => {});
+    },
+  });
+
+  // Hand them in a shuffled order; `order` (then registration order) decides.
+  const host = await mountExtensions(fakeApi(), [mk("slack-pack", 10), mk("agentic-family"), mk("cron-pack", 5)]);
+  assert.deepEqual(registered, ["agentic-family", "cron-pack", "slack-pack"]);
+  await host.stop();
+});
+
+test("composition — order + short-circuit via the security/gate waterfall, then disposal", async () => {
+  const audit: string[] = [];
+  // Two connector-pack-style extensions each contribute a permission middleware.
+  const allowAll: UrbanExtension = {
+    name: "allow-all",
+    order: 20,
+    setup(ctx) {
+      ctx.events.securityGate.on(async (req, next) => {
+        audit.push(`allow-all:${req.action}`);
+        return next(req);
+      });
+    },
+  };
+  const denyDeploy: UrbanExtension = {
+    name: "deny-deploy",
+    order: 10, // runs first — its short-circuit wins
+    setup(ctx) {
+      ctx.events.securityGate.on((req, next) => {
+        audit.push(`deny-deploy:${req.action}`);
+        if (req.action === "deploy") return { allow: false, reason: "deploy locked" };
+        // Not our concern — delegate down the chain so later gates still run.
+        return next(req);
+      });
+    },
+  };
+
+  // Private bus (no options): the host owns it, so `stop()` unwinds the whole ladder.
+  const host = await mountExtensions(fakeApi(), [allowAll, denyDeploy]);
+
+  const base = (_req: GateRequest): GateDecision => ({ allow: true });
+  const decision = await host.events.securityGate.run({ subject: "u", action: "deploy", resource: "models" }, base);
+
+  // deny-deploy ran first and short-circuited: allow-all never saw the request.
+  assert.deepEqual(decision, { allow: false, reason: "deploy locked" });
+  assert.deepEqual(audit, ["deny-deploy:deploy"]);
+
+  // A non-deploy request is *not* deny-deploy's concern: it delegates via `next`, so
+  // the downstream allow-all also runs. (Returning a bare decision instead of
+  // `next(req)` would short-circuit the waterfall and starve allow-all.)
+  audit.length = 0;
+  const allowed = await host.events.securityGate.run({ subject: "u", action: "read", resource: "models" }, base);
+  assert.deepEqual(allowed, { allow: true });
+  assert.deepEqual(audit, ["deny-deploy:read", "allow-all:read"]);
+
+  // Disposal: stop() unwinds every registration these extensions made.
+  assert.ok(host.listenerCount >= 2);
+  await host.stop();
+  assert.equal(host.listenerCount, 0);
+});
+
+test("containment — a throwing extension setup never strands app boot or its siblings", async () => {
+  const registered: string[] = [];
+  const good1: UrbanExtension = {
+    name: "good-1",
+    order: 1,
+    setup() {
+      registered.push("good-1");
+    },
+  };
+  const bad: UrbanExtension = {
+    name: "bad",
+    order: 2,
+    setup() {
+      throw new Error("plugin blew up during setup");
+    },
+  };
+  const good2: UrbanExtension = {
+    name: "good-2",
+    order: 3,
+    setup() {
+      registered.push("good-2");
+    },
+  };
+
+  // Must resolve (boot not stranded) and still mount the healthy siblings.
+  const host = await mountExtensions(fakeApi(), [good1, bad, good2]);
+  assert.deepEqual(registered, ["good-1", "good-2"]);
+  await host.stop();
+});
+
+test("containment — a throwing listener does not strand a request going through the taxonomy", async () => {
+  const throwing: UrbanExtension = {
+    name: "throws-on-dispatch",
+    setup(ctx) {
+      ctx.events.requestDispatch.on(() => {
+        throw new Error("bad middleware");
+      });
+    },
+  };
+  const host = await mountExtensions(fakeApi(), [throwing], { onError: () => {} });
+  const res = await host.events.requestDispatch.run({ kind: "http", payload: "ping" }, (req) => ({
+    handled: true,
+    payload: `pong:${String(req.payload)}`,
+  }));
+  assert.deepEqual(res, { handled: true, payload: "pong:ping" });
+  await host.stop();
+});
+
+test("onError — the option is ignored on a shared bus; the shared bus's own sink contains the throw", async () => {
+  const sharedErrors: string[] = [];
+  const optionErrors: string[] = [];
+  const bus = new EventBus({ onError: (_e, info) => sharedErrors.push(info.event) });
+  const events = createUrbanEvents(bus);
+  const throwing: UrbanExtension = {
+    name: "throws-on-lifecycle",
+    setup(ctx) {
+      ctx.events.lifecycle.on(() => {
+        throw new Error("bad listener");
+      });
+    },
+  };
+  const host = await mountExtensions(fakeApi(), [throwing], {
+    bus,
+    events,
+    onError: (_e, info) => optionErrors.push(info.event),
+  });
+  events.lifecycle.emit({ app: "test", phase: "starting" });
+  assert.deepEqual(optionErrors, [], "onError option must be ignored when a shared bus is passed");
+  assert.ok(sharedErrors.length > 0, "the shared bus's own error sink must contain the throw");
+  await host.stop();
+});
+
+test("HMR — start→stop→start leaks no listeners across cycles", async () => {
+  const ext: UrbanExtension = {
+    name: "leaky-candidate",
+    setup(ctx) {
+      ctx.events.lifecycle.on(() => {});
+      ctx.events.reconcile.on(() => {});
+      ctx.effect(() => {});
+    },
+  };
+
+  for (let cycle = 0; cycle < 3; cycle++) {
+    // Private bus per cycle: the host owns disposal, so stop() must fully unwind it.
+    const host = await mountExtensions(fakeApi(), [ext]);
+    assert.ok(host.listenerCount >= 3, `cycle ${cycle} registered listeners`);
+    await host.stop();
+    assert.equal(host.listenerCount, 0, `cycle ${cycle} disposed cleanly`);
+  }
+});
+
+test("ownership — stop() leaves a shared app-wide bus for its owner to dispose", async () => {
+  const bus = new EventBus();
+  const events = createUrbanEvents(bus);
+  // A core registration the owner (e.g. the runtime) makes outside the extension host.
+  let coreDisposed = false;
+  events.lifecycle.on(() => {});
+  bus.effect(() => {
+    coreDisposed = true;
+  });
+
+  const ext: UrbanExtension = {
+    name: "pack",
+    setup(ctx) {
+      ctx.events.reconcile.on(() => {});
+    },
+  };
+  const host = await mountExtensions(fakeApi(), [ext], { bus, events });
+
+  await host.stop();
+  // stop() does not own the shared bus, so it tears nothing down — the owner's core
+  // registration survives until the owner itself disposes the bus.
+  assert.equal(coreDisposed, false);
+  assert.ok(bus.listenerCount >= 2);
+
+  // The owner (runtime teardown) unwinds the whole ladder in one call.
+  bus.dispose();
+  assert.equal(coreDisposed, true);
+  assert.equal(bus.listenerCount, 0);
+});
+
+test("mountExtensions — rejects a bus/events pair that is only half-provided", async () => {
+  const bus = new EventBus();
+  const events = createUrbanEvents(bus);
+  await assert.rejects(() => mountExtensions(fakeApi(), [], { bus }), /provided together or both omitted/);
+  await assert.rejects(() => mountExtensions(fakeApi(), [], { events }), /provided together or both omitted/);
+});
+
+test("effect() — an extension's arbitrary resource is torn down on stop", async () => {
+  let timerCleared = false;
+  const ext: UrbanExtension = {
+    name: "poller",
+    setup(ctx) {
+      const timer = setInterval(() => {}, 1000);
+      ctx.effect(() => {
+        clearInterval(timer);
+        timerCleared = true;
+      });
+    },
+  };
+  const host = await mountExtensions(fakeApi(), [ext]);
+  try {
+    assert.equal(timerCleared, false);
+  } finally {
+    await host.stop();
+  }
+  assert.equal(timerCleared, true);
+});
+
+test("reconcile — parallel fan-out gives every extension's listener an independent chance", async () => {
+  const bus = new EventBus({ onError: () => {} });
+  const events = createUrbanEvents(bus);
+  const ticks: string[] = [];
+  const a: UrbanExtension = {
+    name: "reconciler-a",
+    setup(ctx) {
+      ctx.events.reconcile.on(async () => {
+        await Promise.resolve();
+        ticks.push("a");
+      });
+    },
+  };
+  const b: UrbanExtension = {
+    name: "reconciler-b",
+    setup(ctx) {
+      ctx.events.reconcile.on(() => {
+        throw new Error("b unhealthy");
+      });
+    },
+  };
+  const c: UrbanExtension = {
+    name: "reconciler-c",
+    setup(ctx) {
+      ctx.events.reconcile.on(async () => {
+        await Promise.resolve();
+        ticks.push("c");
+      });
+    },
+  };
+  const host = await mountExtensions(fakeApi(), [a, b, c], { bus, events });
+  await events.reconcile.run({ source: "test", at: 0 });
+  assert.deepEqual(ticks.sort(), ["a", "c"]);
+  await host.stop();
+});
+
+test("effect() — returns the idempotent disposer so an extension can detach early before stop", async () => {
+  let cleared = 0;
+  let earlyDisposer: (() => void) | undefined;
+  const ext: UrbanExtension = {
+    name: "early-detach",
+    setup(ctx) {
+      earlyDisposer = ctx.effect(() => {
+        cleared++;
+      });
+    },
+  };
+  const host = await mountExtensions(fakeApi(), [ext]);
+  // `effect()` must hand back the disposer so the author can clean up early AND
+  // remove the effect from the ladder so `stop()` won't run it a second time.
+  assert.equal(typeof earlyDisposer, "function");
+  earlyDisposer?.();
+  assert.equal(cleared, 1);
+  assert.equal(host.listenerCount, 0);
+  await host.stop();
+  assert.equal(cleared, 1, "already-detached effect must not run again on stop");
+});
+
+test("containment — a throwing setup rolls back its own partial registrations (atomic)", async () => {
+  const bus = new EventBus({ onError: () => {} });
+  const events = createUrbanEvents(bus);
+  const seen: string[] = [];
+  const partial: UrbanExtension = {
+    name: "registers-then-throws",
+    order: 1,
+    setup(ctx) {
+      ctx.events.lifecycle.on(() => seen.push("partial-listener"));
+      ctx.effect(() => {});
+      throw new Error("boom after partial registration");
+    },
+  };
+  const healthy: UrbanExtension = {
+    name: "healthy",
+    order: 2,
+    setup(ctx) {
+      ctx.events.lifecycle.on(() => seen.push("healthy-listener"));
+    },
+  };
+  const host = await mountExtensions(fakeApi(), [partial, healthy], { bus, events });
+  // The failed extension left nothing live: only the healthy listener remains.
+  assert.equal(host.listenerCount, 1);
+  // A contained-and-skipped extension must not influence later dispatches.
+  events.lifecycle.emit({ app: "x", phase: "started" });
+  assert.deepEqual(seen, ["healthy-listener"]);
+  await host.stop();
+  // Bus is caller-owned, so the owner disposes it; the healthy listener then unwinds.
+  bus.dispose();
+  assert.equal(bus.listenerCount, 0);
+});

package/src/runtime/core/extensions.ts

@@ -0,0 +1,276 @@
+// extensions — the typed Urban **extension-event taxonomy** and the extension host
+// that runs the agentic-family / connector-pack surface through it (issue #262).
+//
+// `runtime.ts` used to wire every module directly and let extensions reach for
+// whatever they needed; ordering and failure-isolation were implicit. This module
+// formalizes the extension seams as a small set of **typed channels**, each with a
+// declared dispatch mode (see `events.ts`), and gives extensions a single, uniform
+// way to plug in: a `UrbanExtension` whose `setup()` registers listeners and
+// disposable effects onto the app's dispose ladder.
+//
+// The first concrete consumer is exactly the informal plugin surface Urban already
+// stresses today: nwf's agentic families ("drop a family module under
+// `app/agentic/families/`, never edit `main.ts`") and connector packs. Each becomes
+// a `UrbanExtension`; the runtime runs them through the `extension/register` serial
+// checkpoint in a deterministic order, and everything they register tears down on
+// `stop()` / dev-server HMR because it rode the dispose ladder.
+
+import type { AppApi, Mounted } from "./context.ts";
+import type { Logger } from "./logger.ts";
+import {
+  EventBus,
+  type Disposer,
+  type DispatchMode,
+  type EmitChannel,
+  type ParallelChannel,
+  type SerialChannel,
+  type WaterfallChannel,
+} from "./events.ts";
+
+// ---------------------------------------------------------------------------
+// The taxonomy — the documented set of typed Urban extension events.
+//
+// Each seam is a canonical event *name* paired with its deliberate *dispatch
+// mode*. This object is the single source of truth for the modes; the ADR's
+// "feature → mechanism map" and the typed `UrbanEvents` channels below are both
+// checked against it — `createUrbanEvents` enumerates the seams by hand, but a
+// drift-guard test asserts every channel's `.mode` equals `URBAN_EVENT_MODES`
+// for its seam (and that coverage is exact), so the docs and the code cannot
+// silently drift.
+// ---------------------------------------------------------------------------
+
+export const URBAN_EVENT_MODES = {
+  /** Boot / start / stop notifications — observers never change the outcome. */
+  "lifecycle": "emit",
+  /** The ordered extension-registration checkpoint (this module's first consumer). */
+  "extension/register": "serial",
+  /** Request / action dispatch — around-middleware for transform / short-circuit. */
+  "request/dispatch": "waterfall",
+  /** Security / permission gate — a listener may short-circuit with a deny. */
+  "security/gate": "waterfall",
+  /** Instance-tracking reconcile — fan-out where every listener gets its chance. */
+  "reconcile": "parallel",
+} as const;
+
+export type UrbanEventName = keyof typeof URBAN_EVENT_MODES;
+
+/** A boot/start/stop lifecycle notification (the `lifecycle` emit seam). */
+export interface LifecycleEvent {
+  readonly app: string;
+  readonly phase: "starting" | "started" | "stopping" | "stopped";
+}
+
+/** The payload handed to each extension as it registers (the `extension/register`
+ *  serial seam): the just-registered extension plus its setup context. */
+export interface ExtensionRegistered {
+  readonly extension: string;
+  readonly context: ExtensionSetupContext;
+}
+
+/** A request/action flowing through the `request/dispatch` waterfall seam. An
+ *  extension middleware may transform it, short-circuit with a response, or
+ *  recover a downstream throw. Kept transport-agnostic on purpose. */
+export interface DispatchRequest {
+  readonly kind: string;
+  readonly payload: unknown;
+}
+
+export interface DispatchResponse {
+  readonly handled: boolean;
+  readonly payload: unknown;
+}
+
+/** A permission check flowing through the `security/gate` waterfall seam. A
+ *  listener that denies short-circuits (never calls `next`). */
+export interface GateRequest {
+  readonly subject: string;
+  readonly action: string;
+  readonly resource: string;
+}
+
+export interface GateDecision {
+  readonly allow: boolean;
+  readonly reason?: string;
+}
+
+/** A reconcile tick fanned out on the `reconcile` parallel seam. */
+export interface ReconcileEvent {
+  readonly source: string;
+  readonly at: number;
+}
+
+/** The typed Urban extension-event taxonomy: one channel per seam, each already
+ *  bound to its declared dispatch mode. Modules and extensions adopt seams by
+ *  registering on these channels; the dispatch semantics come from the channel,
+ *  not the call site. */
+export interface UrbanEvents {
+  /** **emit** — lifecycle notifications. */
+  readonly lifecycle: EmitChannel<LifecycleEvent>;
+  /** **serial** — the ordered extension-registration checkpoint. */
+  readonly extensionRegister: SerialChannel<ExtensionRegistered>;
+  /** **waterfall** — request/action dispatch middleware. */
+  readonly requestDispatch: WaterfallChannel<DispatchRequest, DispatchResponse>;
+  /** **waterfall** — security/permission gate (short-circuit deny). */
+  readonly securityGate: WaterfallChannel<GateRequest, GateDecision>;
+  /** **parallel** — instance-tracking reconcile fan-out. */
+  readonly reconcile: ParallelChannel<ReconcileEvent>;
+}
+
+/** Declare the whole Urban taxonomy on a bus — each seam exactly once, with the
+ *  mode `URBAN_EVENT_MODES` records for it. */
+export function createUrbanEvents(bus: EventBus): UrbanEvents {
+  return {
+    lifecycle: bus.emit<LifecycleEvent>("lifecycle"),
+    extensionRegister: bus.serial<ExtensionRegistered>("extension/register"),
+    requestDispatch: bus.waterfall<DispatchRequest, DispatchResponse>("request/dispatch"),
+    securityGate: bus.waterfall<GateRequest, GateDecision>("security/gate"),
+    reconcile: bus.parallel<ReconcileEvent>("reconcile"),
+  };
+}
+
+/** Assert (at construction) that the typed taxonomy and the documented mode table
+ *  agree — a guard against the two drifting apart. */
+export function urbanEventMode(name: UrbanEventName): DispatchMode {
+  return URBAN_EVENT_MODES[name];
+}
+
+// ---------------------------------------------------------------------------
+// The extension host — the first consumer of the taxonomy.
+// ---------------------------------------------------------------------------
+
+/** What an extension's `setup()` gets: the app API, the typed taxonomy to hook
+ *  onto, a structured logger, and `effect()` to hang any other disposable resource
+ *  (a timer, a subscription) on the dispose ladder. */
+export interface ExtensionSetupContext {
+  readonly app: AppApi;
+  readonly events: UrbanEvents;
+  readonly log: Logger;
+  /** Register a disposable effect (a timer, listener, subscription). It joins the
+   *  dispose ladder, so `stop()` / HMR tears it down with everything else. Returns
+   *  the idempotent disposer so an extension can clean up early — which also detaches
+   *  the effect from the ladder, so `stop()` won't run it a second time. */
+  effect(dispose: Disposer): Disposer;
+}
+
+/** A pluggable Urban extension — the uniform shape an agentic family or a
+ *  connector pack presents to the runtime. `setup()` wires the extension onto the
+ *  taxonomy; anything it registers is an effect on the dispose ladder. */
+export interface UrbanExtension {
+  readonly name: string;
+  /** Explicit ordering for the `extension/register` serial checkpoint; lower runs
+   *  first. Extensions with equal (or absent) order keep registration order. */
+  readonly order?: number;
+  setup(context: ExtensionSetupContext): void | Promise<void>;
+}
+
+export interface ExtensionHost extends Mounted {
+  /** The typed taxonomy this host mounted the extensions onto. */
+  readonly events: UrbanEvents;
+  /** Live registration count on the bus — proxies `EventBus.listenerCount`, so it
+   *  counts every channel listener AND every `effect()` on the dispose ladder, not
+   *  only channel listeners. 0 after a `stop()` that owns its bus. Use it for leak
+   *  assertions. */
+  readonly listenerCount: number;
+}
+
+export interface MountExtensionsOptions {
+  /** Reports a contained extension throw (defaults to the app logger's `warn`).
+   *  Only honoured when `mountExtensions` creates its *own* private bus (i.e. `bus`
+   *  and `events` are omitted). When a shared `bus` is passed, that bus already owns
+   *  its error sink and this option is ignored — set the sink on the shared bus. */
+  onError?: (err: unknown, info: { event: string; mode: DispatchMode }) => void;
+  /** A pre-built taxonomy/bus to mount onto (the runtime shares one app-wide). When
+   *  omitted a private bus is created — handy for isolated tests. */
+  bus?: EventBus;
+  events?: UrbanEvents;
+}
+
+/** Run `extensions` through the taxonomy: deterministically order them, `setup()`
+ *  each directly (a throwing extension is contained and never strands the others
+ *  or app boot), then notify the `extension/register` serial checkpoint so
+ *  observers react in a deterministic order, and return a `Mounted` whose `stop()`
+ *  disposes the bus — unwinding the whole dispose ladder LIFO — only when
+ *  `mountExtensions` created that bus; onto a shared app-wide bus, disposal is the
+ *  caller's responsibility. So a start→stop→start cycle (or HMR reload) over an
+ *  owned bus leaks no listeners. */
+export async function mountExtensions(
+  api: AppApi,
+  extensions: readonly UrbanExtension[],
+  options: MountExtensionsOptions = {},
+): Promise<ExtensionHost> {
+  const log = api.log.child({ module: "extensions" });
+  // Share a caller-owned bus+taxonomy or build a private pair — never a mismatched
+  // one. With only `events`, listeners would register on its bus while `effect()`
+  // and disposal target a *different* private bus (leaked registrations, and a
+  // reused bus could redeclare channels); with only `bus`, callers lose the typed
+  // taxonomy they meant to share. Require both-or-neither.
+  if ((options.bus === undefined) !== (options.events === undefined)) {
+    throw new Error("mountExtensions: `bus` and `events` must be provided together or both omitted");
+  }
+  // Ownership: a bus we created is ours to dispose; a shared app-wide bus belongs
+  // to the caller (the runtime disposes it in teardown). `stop()` honours this so
+  // it never unwinds registrations it did not make.
+  const ownsBus = options.bus === undefined;
+  const bus =
+    options.bus ??
+    new EventBus({
+      onError:
+        options.onError ??
+        ((err, info) => log.warn("extension listener threw and was contained", { event: info.event, mode: info.mode, error: String(err) })),
+    });
+  const events = options.events ?? createUrbanEvents(bus);
+
+  // Deterministic order: primary by `order` (default 0), stable within ties by the
+  // order the host handed them to us. A sibling dropping a family module gets a
+  // predictable slot without editing anyone else's registration.
+  const ordered = extensions
+    .map((extension, index) => ({ extension, index }))
+    .sort((a, b) => (a.extension.order ?? 0) - (b.extension.order ?? 0) || a.index - b.index)
+    .map((entry) => entry.extension);
+
+  const context: ExtensionSetupContext = {
+    app: api,
+    events,
+    log,
+    effect(dispose) {
+      return bus.effect(dispose);
+    },
+  };
+
+  for (const extension of ordered) {
+    // `setup()` is the checkpoint's unit of work, made atomic by a per-extension
+    // rollback scope: a throw is contained here so one bad extension never strands
+    // app boot or its siblings, AND its partial registrations are rolled back so a
+    // "failed" extension can't leave live listeners/effects that influence later
+    // dispatches or leak on teardown.
+    const rollback = bus.scope();
+    try {
+      await extension.setup(context);
+    } catch (err) {
+      rollback();
+      log.warn("extension setup threw and was contained", { extension: extension.name, error: String(err) });
+      continue;
+    }
+    // Notify the ordered `extension/register` serial checkpoint so observers react
+    // in a deterministic order (also contained, per `SerialChannel.run`).
+    await events.extensionRegister.run({ extension: extension.name, context });
+    log.info("extension mounted", { extension: extension.name });
+  }
+
+  return {
+    name: "extensions",
+    events,
+    get listenerCount() {
+      return bus.listenerCount;
+    },
+    async stop() {
+      // Only dispose a bus we own. When the runtime shares its app-wide bus, tearing
+      // it down here would unwind unrelated core registrations — disposal is then the
+      // owner's job (runtime teardown calls `bus.dispose()`).
+      if (ownsBus) bus.dispose();
+    },
+    describe() {
+      return { extensions: ordered.map((e) => e.name), listeners: bus.listenerCount };
+    },
+  };
+}