@btravstack/core 0.18.0 → 0.20.0

package/dist/index.cjs

@@ -429,6 +429,51 @@ const installUncaughtHandlers = (onUncaught) => {
 	};
 };
 //#endregion
+//#region src/unit-overrides.ts
+/**
+* Providers substituted inside a runtime's unit modules, keyed by the kind
+* the runtime declares on `Runtime.units` — test-facing: `@btravstack/testing`'s
+* `overridden(root, providers, { unit })` is the one contributor, and a
+* production root never names it.
+*
+* Each provider must already carry di's override brand. The kernel applies
+* them at boot, before the runtime starts: every kind named must be one the
+* runtime binds, and every port must be one that kind's module provides, or
+* the boot is a defect — the same drift gate a root-level override has.
+*/
+var UnitOverrides = class extends _btravstack_di.Port.many("UnitOverrides") {};
+/** Whether `module`'s tree carries a provider for `portId`. */
+const provides = (module, portId) => module.provides.some((provider) => provider.port.portId === portId) || module.imports.some((imported) => provides(imported, portId));
+/**
+* Each overridden kind's module, mapped to the module the kernel forks in its
+* place. Keyed by module IDENTITY, because `UnitHost.fork` is handed the
+* module and never the kind — which is why a module bound under two kinds is
+* refused rather than overridden under both.
+*/
+const unitSubstitutes = (runtime, units, overrides) => {
+	const byKind = /* @__PURE__ */ new Map();
+	for (const member of overrides) for (const [kind, providers] of Object.entries(member)) byKind.set(kind, [...byKind.get(kind) ?? [], ...providers]);
+	const substitutes = /* @__PURE__ */ new Map();
+	for (const [kind, providers] of byKind) {
+		const module = units[kind];
+		if (module === void 0) throw new Error(`[core] unit override for kind "${kind}", which runtime "${runtime}" binds no module for`);
+		const shared = Object.keys(units).find((other) => other !== kind && units[other] === module);
+		if (shared !== void 0) throw new Error(`[core] unit override for kind "${kind}", whose module kind "${shared}" binds too — an override cannot reach one without the other`);
+		const seen = /* @__PURE__ */ new Set();
+		for (const provider of providers) {
+			if (seen.has(provider.port.portId)) throw new Error(`[core] two unit overrides registered for port ${JSON.stringify(provider.port.portId)} in kind "${kind}"`);
+			seen.add(provider.port.portId);
+			if (!provides(module, provider.port.portId)) throw new Error(`[core] unit override for port ${JSON.stringify(provider.port.portId)} in kind "${kind}" with nothing to override — its module no longer provides it`);
+		}
+		substitutes.set(module, (0, _btravstack_di.Module)("UnitOverridden")({
+			imports: [module],
+			provides: providers,
+			exports: [module]
+		}));
+	}
+	return substitutes;
+};
+//#endregion
 //#region src/units.ts
 const storage = new node_async_hooks.AsyncLocalStorage();
 const runWithUnit = (record, fn) => storage.run(record, fn);
@@ -498,7 +543,7 @@ const createUnitRegistry = () => {
 * and whose side effects then have to be guarded one by one.
 */
 const withdrawn = () => (0, unthrown.fromSafePromise)(new Promise(() => {}));
-const providesEnv = (module) => module.provides.some((provider) => provider.port.portId === _btravstack_config.Env.portId) || module.imports.some(providesEnv);
+const providesEnv = (module) => provides(module, _btravstack_config.Env.portId);
 /**
 * What the kernel reads from the environment for itself. Each field is pinned
 * by the matching `StartOptions` field — explicit beats environment beats
@@ -545,7 +590,13 @@ const readKernelConfig = (options, env) => {
 const start = (module, options = {}) => {
 	const clock = options.clock ?? systemClock;
 	const env = options.env ?? process.env;
-	const emit = safeSink(options.onEvent ?? stderrSink);
+	const sink = safeSink(options.onEvent ?? stderrSink);
+	let exitedEmitted = false;
+	const emit = (event) => {
+		if (exitedEmitted) return;
+		sink(event);
+		if (event.type === "exited") exitedEmitted = true;
+	};
 	let runtimeName = "";
 	let servingInfo = void 0;
 	let probeBoundPort = void 0;
@@ -597,6 +648,7 @@ const start = (module, options = {}) => {
 		}
 	});
 	const disposeUncaught = options.signals === false ? () => {} : installUncaughtHandlers((cause) => {
+		crashed = true;
 		emit({
 			type: "uncaught",
 			cause
@@ -607,6 +659,8 @@ const start = (module, options = {}) => {
 		abandonBuild("uncaught");
 	});
 	let disposeProbes = () => {};
+	let crashed = false;
+	let startupFailing = false;
 	const disposeAll = () => {
 		disposeSignals();
 		disposeUncaught();
@@ -614,7 +668,7 @@ const start = (module, options = {}) => {
 		disposeProbes();
 	};
 	const reportOf = (reason, drain, abandonedAt) => ({
-		reason,
+		reason: crashed ? "uncaught" : reason,
 		drain,
 		teardownErrors,
 		uptimeMs: clock.now() - startedAt,
@@ -629,16 +683,24 @@ const start = (module, options = {}) => {
 		tracker.advanceTo("stopping");
 		disposeAll();
 	};
+	const leaveFailed = (failure) => {
+		if (tracker.current() !== "stopping") emit({
+			type: "startFailed",
+			cause: failure.tag === "Err" ? failure.error : failure.cause
+		});
+		runtimePublished.resolve(void 0);
+		tracker.advanceTo("stopping");
+	};
 	const stopping = Promise.withResolvers();
-	const stopAbandoned = () => (0, unthrown.fromSafePromise)(stopping.promise).flatMap(({ reason, drain }) => clock.sleep(stopTimeoutMs, stopSettled.signal).flatMap(() => lifecycleSettled ? withdrawn() : (0, unthrown.OkAsync)(abandonStop(reason, drain))));
-	const abandonStop = (reason, drain) => {
+	const stopAbandoned = () => (0, unthrown.fromSafePromise)(stopping.promise).flatMap((abandoned) => clock.sleep(stopTimeoutMs, stopSettled.signal).flatMap(() => lifecycleSettled ? withdrawn() : abandonStop(abandoned)));
+	const abandonStop = (abandoned) => {
 		emit({
 			type: "stoppedWaiting",
 			phase: "stop",
 			afterMs: stopSettled.signal.aborted ? void 0 : stopTimeoutMs
 		});
 		disposeAll();
-		return reportOf(reason, drain, "stop");
+		return abandoned().map(({ reason, drain }) => reportOf(reason, drain, "stop"));
 	};
 	const abandoningBuild = Promise.withResolvers();
 	const buildAbandoned = () => (0, unthrown.fromSafePromise)(abandoningBuild.promise).map((reason) => {
@@ -653,7 +715,7 @@ const start = (module, options = {}) => {
 	});
 	const abandonBuild = (reason) => {
 		const phase = tracker.current();
-		if (phase === "building" || phase === "starting") abandoningBuild.resolve(reason);
+		if (phase === "building" || phase === "starting" || reason === "uncaught" && startupFailing) abandoningBuild.resolve(reason);
 	};
 	emit({ type: "building" });
 	const probesOptions = kernelConfig.map(({ probePort, probeHost }) => options.probes === false ? false : {
@@ -714,22 +776,23 @@ const start = (module, options = {}) => {
 		if (reason !== "signal") registry.abortAll();
 		return (reason === "signal" ? runDrain(serving) : (0, unthrown.OkAsync)(void 0)).flatMap((report) => {
 			tracker.advanceTo("stopping");
-			stopping.resolve({
+			stopping.resolve(() => (0, unthrown.OkAsync)({
 				reason,
 				drain: report
-			});
-			return serving.stop().map(() => {
-				disposeAll();
-				return reportOf(reason, report);
-			});
+			}));
+			return serving.stop().map(() => ({
+				reason,
+				drain: report
+			}));
 		});
 	};
-	const built = () => _btravstack_di.Module.scoped(root, (ctx) => {
+	const serve = (ctx) => {
 		tracker.advanceTo("starting");
 		const runtime = ctx.get(RuntimePort);
 		runtimeName = runtime.name;
 		healthChecks = ctx.get(HealthChecks);
 		const runtimeCtx = ctx;
+		const substitutes = unitSubstitutes(runtime.name, runtime.units ?? {}, ctx.get(UnitOverrides));
 		const run = (meta, work) => registry.run(meta, (signal) => {
 			const settled = Promise.withResolvers();
 			let closing;
@@ -738,12 +801,12 @@ const start = (module, options = {}) => {
 				if (hasSettled) return (0, unthrown.fromSafePromise)(Promise.reject(/* @__PURE__ */ new Error("a unit forks after it has already settled")));
 				if (closing !== void 0) return (0, unthrown.fromSafePromise)(Promise.reject(/* @__PURE__ */ new Error("a unit forks its scope once")));
 				const ready = Promise.withResolvers();
-				closing = _btravstack_di.Module.forkScope(ctx, module, (forked) => {
+				closing = _btravstack_di.Module.forkScope(ctx, substitutes.get(module) ?? module, (forked) => {
 					ready.resolve(forked);
 					return (0, unthrown.fromSafePromise)(settled.promise);
 				}, {
 					seed,
-					onTeardownError: (port, cause) => emit({
+					onTeardownError: (port, cause) => sink({
 						type: "teardownError",
 						port,
 						cause
@@ -781,28 +844,35 @@ const start = (module, options = {}) => {
 			servingInfo = serving.info;
 			tracker.advanceTo("serving");
 			runtimePublished.resolve(serving.info);
-			serving.stopped?.().map(() => {
-				requestShutdown("runtimeStopped");
-			});
+			serving.stopped?.().tap(() => requestShutdown("runtimeStopped")).tapFailure(() => requestShutdown("runtimeStopped"));
 			return (0, unthrown.fromSafePromise)(shutdown.promise).flatMap((reason) => finish(serving, reason));
 		});
-	}, { onTeardownError: (port, cause) => {
-		teardownErrors.push({
-			port,
-			cause
-		});
-		emit({
-			type: "teardownError",
-			port,
-			cause
-		});
-	} }).tapFailure((failure) => {
-		if (tracker.current() !== "stopping") emit({
-			type: "startFailed",
-			cause: failure.tag === "Err" ? failure.error : failure.cause
-		});
-		leaveStartup();
-	}).tap(onLifecycleSettled).tapFailure(onLifecycleSettled);
+	};
+	const built = () => _btravstack_di.Module.scoped(root, (ctx) => (0, unthrown.OkAsync)(ctx).flatMap(serve).tapFailure((failure) => {
+		if (tracker.current() === "starting") startupFailing = true;
+		leaveFailed(failure);
+		stopping.resolve(() => failure.toAsync());
+	}), {
+		onConstructionFailure: (failure) => {
+			startupFailing = true;
+			leaveFailed(failure);
+			stopping.resolve(() => failure.toAsync());
+		},
+		onTeardownError: (port, cause) => {
+			teardownErrors.push({
+				port,
+				cause
+			});
+			emit({
+				type: "teardownError",
+				port,
+				cause
+			});
+		}
+	}).tapFailure((failure) => {
+		leaveFailed(failure);
+		disposeAll();
+	}).map(({ reason, drain }) => reportOf(reason, drain)).tap(disposeAll).tap(onLifecycleSettled).tapFailure(onLifecycleSettled);
 	return {
 		exited: probesStarted.flatMap(() => (0, unthrown.fromSafePromise)(Promise.race([
 			built(),
@@ -979,6 +1049,7 @@ exports.RuntimePort = RuntimePort;
 exports.RuntimeStartFailed = RuntimeStartFailed;
 exports.SPAN_STATUS = SPAN_STATUS;
 exports.Tracer = Tracer;
+exports.UnitOverrides = UnitOverrides;
 exports.composeByPrefix = composeByPrefix;
 exports.currentUnit = currentUnit;
 exports.dispatchUnit = dispatchUnit;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { AsyncResult, FailureView, Result } from "unthrown";
-import { AnyPort, Context, DependencyGate, Module, PortClass, PortInstance, Provider, Scope, SeedEntry, ServiceOf } from "@btravstack/di";
+import { AnyPort, AnyProvider, Context, DependencyGate, Module, PortClass, PortInstance, Provider, Scope, SeedEntry, ServiceOf } from "@btravstack/di";
 import { Env, Environment } from "@btravstack/config";
 //#region src/instrumentation.d.ts
 /**
@@ -395,6 +395,64 @@ type UnitRegistry = {
   readonly awaitIdle: () => AsyncResult<void, never>;
 };
 //#endregion
+//#region src/unit-record.d.ts
+/**
+ * A module a runtime's `unit` option may bind, as the upper bound a starter
+ * constrains its own `Unit` type parameter to. `Module`'s `_exports` channel is
+ * contravariant, so `Exports = never` — never `unknown` — is what makes a REAL
+ * module's own (necessarily narrower) export type assignable to this bound:
+ * `(x: Concrete) => void` is assignable to `(x: never) => void`, not to
+ * `(x: unknown) => void`.
+ */
+type AnyUnitModule = Module<never, never, unknown>;
+/**
+ * The needs a bound unit module still owes, or `never` when none is bound.
+ * `Scope` is excluded, since nothing can ever provide it — the same exemption
+ * `NeedsGate` itself carries — and so is `Seeded`, the port the runtime's own
+ * fork seed discharges.
+ */
+type UnitNeedsOf<Unit, Seeded = never> = Unit extends Module<never, never, infer N> ? Exclude<N, Scope | Seeded> : never;
+/** What a bound unit module exports — the port instances a piece of that kind may read. */
+type UnitExportsOf<M> = M extends Module<infer X, never, unknown> ? X : never;
+/** A piece's declared `unit:` record, as the services it reads off `context.unit`. */
+type UnitRecordOf<U extends Readonly<Record<string, AnyPort>>> = { readonly [N in keyof U]: ServiceOf<InstanceType<U[N]>>; };
+/**
+ * A piece injecting a port the bound unit module does not export. `unknown`
+ * when every declared port is covered — including the empty case, so a worker
+ * whose pieces declare no `unit:` is gated on nothing.
+ */
+type UnitGate<Unit, Declared> = [Exclude<NonNullable<Declared>, UnitExportsOf<Unit>>] extends [never] ? unknown : {
+  readonly "UNIT DOES NOT PROVIDE — a piece injects a port the bound unit module does not export": Exclude<NonNullable<Declared>, UnitExportsOf<Unit>>;
+};
+/**
+ * One `(helpers, input)` implementation with its piece's declared record put on
+ * `helpers.context.unit`, resolved out of the fork {@link dispatchUnit} opened.
+ * Applied once per piece as di constructs it, so a unit costs one record and
+ * one context object. Each worker maps it over its own entry shape.
+ */
+export declare const withUnitRecord: (record: Readonly<Record<string, AnyPort>>, implementation: (helpers: never, input: never) => unknown) => (helpers: {
+  readonly context?: Readonly<Record<string | symbol, unknown>>;
+}, input: never) => unknown;
+/**
+ * A worker middleware's body: observe `operation`, open one kernel unit, fork
+ * `unit` — when one is bound — seeded with `seed`, and call `next` with the
+ * forked context where {@link withUnitRecord} finds it. With no `unit` bound,
+ * `next()` runs unchanged.
+ *
+ * Observed from whichever channel the unit settles on, a defect included: a
+ * defect is a failed unit too, and an errors count that omitted it would be the
+ * reassuring half.
+ */
+export declare const dispatchUnit: <T, E>(dispatch: {
+  readonly host: RuntimeHost<never>;
+  readonly observers: readonly ((operation: Operation) => Settle)[];
+  readonly operation: Operation;
+  readonly meta: UnitMeta;
+  readonly unit: AnyUnitModule | undefined;
+  readonly seed: readonly [AnyPort, unknown];
+  readonly next: (overrides?: never) => AsyncResult<T, E>;
+}) => AsyncResult<T, E>;
+//#endregion
 //#region src/runtime.d.ts
 declare const RuntimeStartFailed_base: import("unthrown").TaggedErrorConstructor<"RuntimeStartFailed">;
 export declare class RuntimeStartFailed extends RuntimeStartFailed_base<{
@@ -504,6 +562,14 @@ type Runtime<Resolves extends AnyPort = never, Info = never> = {
   readonly name: string;
   readonly resolves: readonly Resolves[];
   readonly start: (host: RuntimeHost<Resolves>) => AsyncResult<Serving<Info>, RuntimeStartFailed>;
+  /**
+   * The unit modules this runtime forks, by kind — `{ message: … }`, or one
+   * per HTTP scheme. Optional, and read for one thing only: a test's
+   * `UnitOverrides` name a kind, `fork` is handed a module, and this is
+   * what maps one onto the other. A runtime that omits it refuses every unit
+   * override at boot rather than ignoring it.
+   */
+  readonly units?: Readonly<Record<string, AnyUnitModule | undefined>>;
 };
 /**
  * The port the kernel resolves its runtime from. A runtime is a **service the
@@ -847,63 +913,20 @@ export declare const start: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>,
  */
 export declare const runMain: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>, options?: StartOptions, exit?: (code: number) => void) => Promise<void>;
 //#endregion
-//#region src/unit-record.d.ts
+//#region src/unit-overrides.d.ts
+declare const UnitOverrides_base: import("@btravstack/di").ManyPortClass<"UnitOverrides">;
 /**
- * A module a runtime's `unit` option may bind, as the upper bound a starter
- * constrains its own `Unit` type parameter to. `Module`'s `_exports` channel is
- * contravariant, so `Exports = never` — never `unknown` — is what makes a REAL
- * module's own (necessarily narrower) export type assignable to this bound:
- * `(x: Concrete) => void` is assignable to `(x: never) => void`, not to
- * `(x: unknown) => void`.
- */
-type AnyUnitModule = Module<never, never, unknown>;
-/**
- * The needs a bound unit module still owes, or `never` when none is bound.
- * `Scope` is excluded, since nothing can ever provide it — the same exemption
- * `NeedsGate` itself carries — and so is `Seeded`, the port the runtime's own
- * fork seed discharges.
- */
-type UnitNeedsOf<Unit, Seeded = never> = Unit extends Module<never, never, infer N> ? Exclude<N, Scope | Seeded> : never;
-/** What a bound unit module exports — the port instances a piece of that kind may read. */
-type UnitExportsOf<M> = M extends Module<infer X, never, unknown> ? X : never;
-/** A piece's declared `unit:` record, as the services it reads off `context.unit`. */
-type UnitRecordOf<U extends Readonly<Record<string, AnyPort>>> = { readonly [N in keyof U]: ServiceOf<InstanceType<U[N]>>; };
-/**
- * A piece injecting a port the bound unit module does not export. `unknown`
- * when every declared port is covered — including the empty case, so a worker
- * whose pieces declare no `unit:` is gated on nothing.
- */
-type UnitGate<Unit, Declared> = [Exclude<NonNullable<Declared>, UnitExportsOf<Unit>>] extends [never] ? unknown : {
-  readonly "UNIT DOES NOT PROVIDE — a piece injects a port the bound unit module does not export": Exclude<NonNullable<Declared>, UnitExportsOf<Unit>>;
-};
-/**
- * One `(helpers, input)` implementation with its piece's declared record put on
- * `helpers.context.unit`, resolved out of the fork {@link dispatchUnit} opened.
- * Applied once per piece as di constructs it, so a unit costs one record and
- * one context object. Each worker maps it over its own entry shape.
- */
-export declare const withUnitRecord: (record: Readonly<Record<string, AnyPort>>, implementation: (helpers: never, input: never) => unknown) => (helpers: {
-  readonly context?: Readonly<Record<string | symbol, unknown>>;
-}, input: never) => unknown;
-/**
- * A worker middleware's body: observe `operation`, open one kernel unit, fork
- * `unit` — when one is bound — seeded with `seed`, and call `next` with the
- * forked context where {@link withUnitRecord} finds it. With no `unit` bound,
- * `next()` runs unchanged.
+ * Providers substituted inside a runtime's unit modules, keyed by the kind
+ * the runtime declares on `Runtime.units` — test-facing: `@btravstack/testing`'s
+ * `overridden(root, providers, { unit })` is the one contributor, and a
+ * production root never names it.
  *
- * Observed from whichever channel the unit settles on, a defect included: a
- * defect is a failed unit too, and an errors count that omitted it would be the
- * reassuring half.
+ * Each provider must already carry di's override brand. The kernel applies
+ * them at boot, before the runtime starts: every kind named must be one the
+ * runtime binds, and every port must be one that kind's module provides, or
+ * the boot is a defect — the same drift gate a root-level override has.
  */
-export declare const dispatchUnit: <T, E>(dispatch: {
-  readonly host: RuntimeHost<never>;
-  readonly observers: readonly ((operation: Operation) => Settle)[];
-  readonly operation: Operation;
-  readonly meta: UnitMeta;
-  readonly unit: AnyUnitModule | undefined;
-  readonly seed: readonly [AnyPort, unknown];
-  readonly next: (overrides?: never) => AsyncResult<T, E>;
-}) => AsyncResult<T, E>;
+export declare class UnitOverrides extends UnitOverrides_base<Readonly<Record<string, readonly AnyProvider[]>>> {}
 //#endregion
 //#region src/pieces.d.ts
 /**

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AnyPort, Context, DependencyGate, Module, PortClass, PortInstance, Provider, Scope, SeedEntry, ServiceOf } from "@btravstack/di";
+import { AnyPort, AnyProvider, Context, DependencyGate, Module, PortClass, PortInstance, Provider, Scope, SeedEntry, ServiceOf } from "@btravstack/di";
 import { AsyncResult, FailureView, Result } from "unthrown";
 import { Env, Environment } from "@btravstack/config";
 //#region src/instrumentation.d.ts
@@ -395,6 +395,64 @@ type UnitRegistry = {
   readonly awaitIdle: () => AsyncResult<void, never>;
 };
 //#endregion
+//#region src/unit-record.d.ts
+/**
+ * A module a runtime's `unit` option may bind, as the upper bound a starter
+ * constrains its own `Unit` type parameter to. `Module`'s `_exports` channel is
+ * contravariant, so `Exports = never` — never `unknown` — is what makes a REAL
+ * module's own (necessarily narrower) export type assignable to this bound:
+ * `(x: Concrete) => void` is assignable to `(x: never) => void`, not to
+ * `(x: unknown) => void`.
+ */
+type AnyUnitModule = Module<never, never, unknown>;
+/**
+ * The needs a bound unit module still owes, or `never` when none is bound.
+ * `Scope` is excluded, since nothing can ever provide it — the same exemption
+ * `NeedsGate` itself carries — and so is `Seeded`, the port the runtime's own
+ * fork seed discharges.
+ */
+type UnitNeedsOf<Unit, Seeded = never> = Unit extends Module<never, never, infer N> ? Exclude<N, Scope | Seeded> : never;
+/** What a bound unit module exports — the port instances a piece of that kind may read. */
+type UnitExportsOf<M> = M extends Module<infer X, never, unknown> ? X : never;
+/** A piece's declared `unit:` record, as the services it reads off `context.unit`. */
+type UnitRecordOf<U extends Readonly<Record<string, AnyPort>>> = { readonly [N in keyof U]: ServiceOf<InstanceType<U[N]>>; };
+/**
+ * A piece injecting a port the bound unit module does not export. `unknown`
+ * when every declared port is covered — including the empty case, so a worker
+ * whose pieces declare no `unit:` is gated on nothing.
+ */
+type UnitGate<Unit, Declared> = [Exclude<NonNullable<Declared>, UnitExportsOf<Unit>>] extends [never] ? unknown : {
+  readonly "UNIT DOES NOT PROVIDE — a piece injects a port the bound unit module does not export": Exclude<NonNullable<Declared>, UnitExportsOf<Unit>>;
+};
+/**
+ * One `(helpers, input)` implementation with its piece's declared record put on
+ * `helpers.context.unit`, resolved out of the fork {@link dispatchUnit} opened.
+ * Applied once per piece as di constructs it, so a unit costs one record and
+ * one context object. Each worker maps it over its own entry shape.
+ */
+export declare const withUnitRecord: (record: Readonly<Record<string, AnyPort>>, implementation: (helpers: never, input: never) => unknown) => (helpers: {
+  readonly context?: Readonly<Record<string | symbol, unknown>>;
+}, input: never) => unknown;
+/**
+ * A worker middleware's body: observe `operation`, open one kernel unit, fork
+ * `unit` — when one is bound — seeded with `seed`, and call `next` with the
+ * forked context where {@link withUnitRecord} finds it. With no `unit` bound,
+ * `next()` runs unchanged.
+ *
+ * Observed from whichever channel the unit settles on, a defect included: a
+ * defect is a failed unit too, and an errors count that omitted it would be the
+ * reassuring half.
+ */
+export declare const dispatchUnit: <T, E>(dispatch: {
+  readonly host: RuntimeHost<never>;
+  readonly observers: readonly ((operation: Operation) => Settle)[];
+  readonly operation: Operation;
+  readonly meta: UnitMeta;
+  readonly unit: AnyUnitModule | undefined;
+  readonly seed: readonly [AnyPort, unknown];
+  readonly next: (overrides?: never) => AsyncResult<T, E>;
+}) => AsyncResult<T, E>;
+//#endregion
 //#region src/runtime.d.ts
 declare const RuntimeStartFailed_base: import("unthrown").TaggedErrorConstructor<"RuntimeStartFailed">;
 export declare class RuntimeStartFailed extends RuntimeStartFailed_base<{
@@ -504,6 +562,14 @@ type Runtime<Resolves extends AnyPort = never, Info = never> = {
   readonly name: string;
   readonly resolves: readonly Resolves[];
   readonly start: (host: RuntimeHost<Resolves>) => AsyncResult<Serving<Info>, RuntimeStartFailed>;
+  /**
+   * The unit modules this runtime forks, by kind — `{ message: … }`, or one
+   * per HTTP scheme. Optional, and read for one thing only: a test's
+   * `UnitOverrides` name a kind, `fork` is handed a module, and this is
+   * what maps one onto the other. A runtime that omits it refuses every unit
+   * override at boot rather than ignoring it.
+   */
+  readonly units?: Readonly<Record<string, AnyUnitModule | undefined>>;
 };
 /**
  * The port the kernel resolves its runtime from. A runtime is a **service the
@@ -847,63 +913,20 @@ export declare const start: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>,
  */
 export declare const runMain: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>, options?: StartOptions, exit?: (code: number) => void) => Promise<void>;
 //#endregion
-//#region src/unit-record.d.ts
+//#region src/unit-overrides.d.ts
+declare const UnitOverrides_base: import("@btravstack/di").ManyPortClass<"UnitOverrides">;
 /**
- * A module a runtime's `unit` option may bind, as the upper bound a starter
- * constrains its own `Unit` type parameter to. `Module`'s `_exports` channel is
- * contravariant, so `Exports = never` — never `unknown` — is what makes a REAL
- * module's own (necessarily narrower) export type assignable to this bound:
- * `(x: Concrete) => void` is assignable to `(x: never) => void`, not to
- * `(x: unknown) => void`.
- */
-type AnyUnitModule = Module<never, never, unknown>;
-/**
- * The needs a bound unit module still owes, or `never` when none is bound.
- * `Scope` is excluded, since nothing can ever provide it — the same exemption
- * `NeedsGate` itself carries — and so is `Seeded`, the port the runtime's own
- * fork seed discharges.
- */
-type UnitNeedsOf<Unit, Seeded = never> = Unit extends Module<never, never, infer N> ? Exclude<N, Scope | Seeded> : never;
-/** What a bound unit module exports — the port instances a piece of that kind may read. */
-type UnitExportsOf<M> = M extends Module<infer X, never, unknown> ? X : never;
-/** A piece's declared `unit:` record, as the services it reads off `context.unit`. */
-type UnitRecordOf<U extends Readonly<Record<string, AnyPort>>> = { readonly [N in keyof U]: ServiceOf<InstanceType<U[N]>>; };
-/**
- * A piece injecting a port the bound unit module does not export. `unknown`
- * when every declared port is covered — including the empty case, so a worker
- * whose pieces declare no `unit:` is gated on nothing.
- */
-type UnitGate<Unit, Declared> = [Exclude<NonNullable<Declared>, UnitExportsOf<Unit>>] extends [never] ? unknown : {
-  readonly "UNIT DOES NOT PROVIDE — a piece injects a port the bound unit module does not export": Exclude<NonNullable<Declared>, UnitExportsOf<Unit>>;
-};
-/**
- * One `(helpers, input)` implementation with its piece's declared record put on
- * `helpers.context.unit`, resolved out of the fork {@link dispatchUnit} opened.
- * Applied once per piece as di constructs it, so a unit costs one record and
- * one context object. Each worker maps it over its own entry shape.
- */
-export declare const withUnitRecord: (record: Readonly<Record<string, AnyPort>>, implementation: (helpers: never, input: never) => unknown) => (helpers: {
-  readonly context?: Readonly<Record<string | symbol, unknown>>;
-}, input: never) => unknown;
-/**
- * A worker middleware's body: observe `operation`, open one kernel unit, fork
- * `unit` — when one is bound — seeded with `seed`, and call `next` with the
- * forked context where {@link withUnitRecord} finds it. With no `unit` bound,
- * `next()` runs unchanged.
+ * Providers substituted inside a runtime's unit modules, keyed by the kind
+ * the runtime declares on `Runtime.units` — test-facing: `@btravstack/testing`'s
+ * `overridden(root, providers, { unit })` is the one contributor, and a
+ * production root never names it.
  *
- * Observed from whichever channel the unit settles on, a defect included: a
- * defect is a failed unit too, and an errors count that omitted it would be the
- * reassuring half.
+ * Each provider must already carry di's override brand. The kernel applies
+ * them at boot, before the runtime starts: every kind named must be one the
+ * runtime binds, and every port must be one that kind's module provides, or
+ * the boot is a defect — the same drift gate a root-level override has.
  */
-export declare const dispatchUnit: <T, E>(dispatch: {
-  readonly host: RuntimeHost<never>;
-  readonly observers: readonly ((operation: Operation) => Settle)[];
-  readonly operation: Operation;
-  readonly meta: UnitMeta;
-  readonly unit: AnyUnitModule | undefined;
-  readonly seed: readonly [AnyPort, unknown];
-  readonly next: (overrides?: never) => AsyncResult<T, E>;
-}) => AsyncResult<T, E>;
+export declare class UnitOverrides extends UnitOverrides_base<Readonly<Record<string, readonly AnyProvider[]>>> {}
 //#endregion
 //#region src/pieces.d.ts
 /**

package/dist/index.mjs

@@ -428,6 +428,51 @@ const installUncaughtHandlers = (onUncaught) => {
 	};
 };
 //#endregion
+//#region src/unit-overrides.ts
+/**
+* Providers substituted inside a runtime's unit modules, keyed by the kind
+* the runtime declares on `Runtime.units` — test-facing: `@btravstack/testing`'s
+* `overridden(root, providers, { unit })` is the one contributor, and a
+* production root never names it.
+*
+* Each provider must already carry di's override brand. The kernel applies
+* them at boot, before the runtime starts: every kind named must be one the
+* runtime binds, and every port must be one that kind's module provides, or
+* the boot is a defect — the same drift gate a root-level override has.
+*/
+var UnitOverrides = class extends Port.many("UnitOverrides") {};
+/** Whether `module`'s tree carries a provider for `portId`. */
+const provides = (module, portId) => module.provides.some((provider) => provider.port.portId === portId) || module.imports.some((imported) => provides(imported, portId));
+/**
+* Each overridden kind's module, mapped to the module the kernel forks in its
+* place. Keyed by module IDENTITY, because `UnitHost.fork` is handed the
+* module and never the kind — which is why a module bound under two kinds is
+* refused rather than overridden under both.
+*/
+const unitSubstitutes = (runtime, units, overrides) => {
+	const byKind = /* @__PURE__ */ new Map();
+	for (const member of overrides) for (const [kind, providers] of Object.entries(member)) byKind.set(kind, [...byKind.get(kind) ?? [], ...providers]);
+	const substitutes = /* @__PURE__ */ new Map();
+	for (const [kind, providers] of byKind) {
+		const module = units[kind];
+		if (module === void 0) throw new Error(`[core] unit override for kind "${kind}", which runtime "${runtime}" binds no module for`);
+		const shared = Object.keys(units).find((other) => other !== kind && units[other] === module);
+		if (shared !== void 0) throw new Error(`[core] unit override for kind "${kind}", whose module kind "${shared}" binds too — an override cannot reach one without the other`);
+		const seen = /* @__PURE__ */ new Set();
+		for (const provider of providers) {
+			if (seen.has(provider.port.portId)) throw new Error(`[core] two unit overrides registered for port ${JSON.stringify(provider.port.portId)} in kind "${kind}"`);
+			seen.add(provider.port.portId);
+			if (!provides(module, provider.port.portId)) throw new Error(`[core] unit override for port ${JSON.stringify(provider.port.portId)} in kind "${kind}" with nothing to override — its module no longer provides it`);
+		}
+		substitutes.set(module, Module("UnitOverridden")({
+			imports: [module],
+			provides: providers,
+			exports: [module]
+		}));
+	}
+	return substitutes;
+};
+//#endregion
 //#region src/units.ts
 const storage = new AsyncLocalStorage();
 const runWithUnit = (record, fn) => storage.run(record, fn);
@@ -497,7 +542,7 @@ const createUnitRegistry = () => {
 * and whose side effects then have to be guarded one by one.
 */
 const withdrawn = () => fromSafePromise(new Promise(() => {}));
-const providesEnv = (module) => module.provides.some((provider) => provider.port.portId === Env.portId) || module.imports.some(providesEnv);
+const providesEnv = (module) => provides(module, Env.portId);
 /**
 * What the kernel reads from the environment for itself. Each field is pinned
 * by the matching `StartOptions` field — explicit beats environment beats
@@ -544,7 +589,13 @@ const readKernelConfig = (options, env) => {
 const start = (module, options = {}) => {
 	const clock = options.clock ?? systemClock;
 	const env = options.env ?? process.env;
-	const emit = safeSink(options.onEvent ?? stderrSink);
+	const sink = safeSink(options.onEvent ?? stderrSink);
+	let exitedEmitted = false;
+	const emit = (event) => {
+		if (exitedEmitted) return;
+		sink(event);
+		if (event.type === "exited") exitedEmitted = true;
+	};
 	let runtimeName = "";
 	let servingInfo = void 0;
 	let probeBoundPort = void 0;
@@ -596,6 +647,7 @@ const start = (module, options = {}) => {
 		}
 	});
 	const disposeUncaught = options.signals === false ? () => {} : installUncaughtHandlers((cause) => {
+		crashed = true;
 		emit({
 			type: "uncaught",
 			cause
@@ -606,6 +658,8 @@ const start = (module, options = {}) => {
 		abandonBuild("uncaught");
 	});
 	let disposeProbes = () => {};
+	let crashed = false;
+	let startupFailing = false;
 	const disposeAll = () => {
 		disposeSignals();
 		disposeUncaught();
@@ -613,7 +667,7 @@ const start = (module, options = {}) => {
 		disposeProbes();
 	};
 	const reportOf = (reason, drain, abandonedAt) => ({
-		reason,
+		reason: crashed ? "uncaught" : reason,
 		drain,
 		teardownErrors,
 		uptimeMs: clock.now() - startedAt,
@@ -628,16 +682,24 @@ const start = (module, options = {}) => {
 		tracker.advanceTo("stopping");
 		disposeAll();
 	};
+	const leaveFailed = (failure) => {
+		if (tracker.current() !== "stopping") emit({
+			type: "startFailed",
+			cause: failure.tag === "Err" ? failure.error : failure.cause
+		});
+		runtimePublished.resolve(void 0);
+		tracker.advanceTo("stopping");
+	};
 	const stopping = Promise.withResolvers();
-	const stopAbandoned = () => fromSafePromise(stopping.promise).flatMap(({ reason, drain }) => clock.sleep(stopTimeoutMs, stopSettled.signal).flatMap(() => lifecycleSettled ? withdrawn() : OkAsync(abandonStop(reason, drain))));
-	const abandonStop = (reason, drain) => {
+	const stopAbandoned = () => fromSafePromise(stopping.promise).flatMap((abandoned) => clock.sleep(stopTimeoutMs, stopSettled.signal).flatMap(() => lifecycleSettled ? withdrawn() : abandonStop(abandoned)));
+	const abandonStop = (abandoned) => {
 		emit({
 			type: "stoppedWaiting",
 			phase: "stop",
 			afterMs: stopSettled.signal.aborted ? void 0 : stopTimeoutMs
 		});
 		disposeAll();
-		return reportOf(reason, drain, "stop");
+		return abandoned().map(({ reason, drain }) => reportOf(reason, drain, "stop"));
 	};
 	const abandoningBuild = Promise.withResolvers();
 	const buildAbandoned = () => fromSafePromise(abandoningBuild.promise).map((reason) => {
@@ -652,7 +714,7 @@ const start = (module, options = {}) => {
 	});
 	const abandonBuild = (reason) => {
 		const phase = tracker.current();
-		if (phase === "building" || phase === "starting") abandoningBuild.resolve(reason);
+		if (phase === "building" || phase === "starting" || reason === "uncaught" && startupFailing) abandoningBuild.resolve(reason);
 	};
 	emit({ type: "building" });
 	const probesOptions = kernelConfig.map(({ probePort, probeHost }) => options.probes === false ? false : {
@@ -713,22 +775,23 @@ const start = (module, options = {}) => {
 		if (reason !== "signal") registry.abortAll();
 		return (reason === "signal" ? runDrain(serving) : OkAsync(void 0)).flatMap((report) => {
 			tracker.advanceTo("stopping");
-			stopping.resolve({
+			stopping.resolve(() => OkAsync({
 				reason,
 				drain: report
-			});
-			return serving.stop().map(() => {
-				disposeAll();
-				return reportOf(reason, report);
-			});
+			}));
+			return serving.stop().map(() => ({
+				reason,
+				drain: report
+			}));
 		});
 	};
-	const built = () => Module.scoped(root, (ctx) => {
+	const serve = (ctx) => {
 		tracker.advanceTo("starting");
 		const runtime = ctx.get(RuntimePort);
 		runtimeName = runtime.name;
 		healthChecks = ctx.get(HealthChecks);
 		const runtimeCtx = ctx;
+		const substitutes = unitSubstitutes(runtime.name, runtime.units ?? {}, ctx.get(UnitOverrides));
 		const run = (meta, work) => registry.run(meta, (signal) => {
 			const settled = Promise.withResolvers();
 			let closing;
@@ -737,12 +800,12 @@ const start = (module, options = {}) => {
 				if (hasSettled) return fromSafePromise(Promise.reject(/* @__PURE__ */ new Error("a unit forks after it has already settled")));
 				if (closing !== void 0) return fromSafePromise(Promise.reject(/* @__PURE__ */ new Error("a unit forks its scope once")));
 				const ready = Promise.withResolvers();
-				closing = Module.forkScope(ctx, module, (forked) => {
+				closing = Module.forkScope(ctx, substitutes.get(module) ?? module, (forked) => {
 					ready.resolve(forked);
 					return fromSafePromise(settled.promise);
 				}, {
 					seed,
-					onTeardownError: (port, cause) => emit({
+					onTeardownError: (port, cause) => sink({
 						type: "teardownError",
 						port,
 						cause
@@ -780,28 +843,35 @@ const start = (module, options = {}) => {
 			servingInfo = serving.info;
 			tracker.advanceTo("serving");
 			runtimePublished.resolve(serving.info);
-			serving.stopped?.().map(() => {
-				requestShutdown("runtimeStopped");
-			});
+			serving.stopped?.().tap(() => requestShutdown("runtimeStopped")).tapFailure(() => requestShutdown("runtimeStopped"));
 			return fromSafePromise(shutdown.promise).flatMap((reason) => finish(serving, reason));
 		});
-	}, { onTeardownError: (port, cause) => {
-		teardownErrors.push({
-			port,
-			cause
-		});
-		emit({
-			type: "teardownError",
-			port,
-			cause
-		});
-	} }).tapFailure((failure) => {
-		if (tracker.current() !== "stopping") emit({
-			type: "startFailed",
-			cause: failure.tag === "Err" ? failure.error : failure.cause
-		});
-		leaveStartup();
-	}).tap(onLifecycleSettled).tapFailure(onLifecycleSettled);
+	};
+	const built = () => Module.scoped(root, (ctx) => OkAsync(ctx).flatMap(serve).tapFailure((failure) => {
+		if (tracker.current() === "starting") startupFailing = true;
+		leaveFailed(failure);
+		stopping.resolve(() => failure.toAsync());
+	}), {
+		onConstructionFailure: (failure) => {
+			startupFailing = true;
+			leaveFailed(failure);
+			stopping.resolve(() => failure.toAsync());
+		},
+		onTeardownError: (port, cause) => {
+			teardownErrors.push({
+				port,
+				cause
+			});
+			emit({
+				type: "teardownError",
+				port,
+				cause
+			});
+		}
+	}).tapFailure((failure) => {
+		leaveFailed(failure);
+		disposeAll();
+	}).map(({ reason, drain }) => reportOf(reason, drain)).tap(disposeAll).tap(onLifecycleSettled).tapFailure(onLifecycleSettled);
 	return {
 		exited: probesStarted.flatMap(() => fromSafePromise(Promise.race([
 			built(),
@@ -967,4 +1037,4 @@ const noObserverMember = Provider.member(Observers)({
 	value: noObserver
 });
 //#endregion
-export { HealthCheckFailed, HealthChecks, Instrumentations, LEVELS, Logger, Meter, Observers, RuntimePort, RuntimeStartFailed, SPAN_STATUS, Tracer, composeByPrefix, currentUnit, dispatchUnit, mintPiece, noObserver, noObserverMember, observe, observed, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock, traceIdOfTraceparent, unitOutcome, withUnitRecord };
+export { HealthCheckFailed, HealthChecks, Instrumentations, LEVELS, Logger, Meter, Observers, RuntimePort, RuntimeStartFailed, SPAN_STATUS, Tracer, UnitOverrides, composeByPrefix, currentUnit, dispatchUnit, mintPiece, noObserver, noObserverMember, observe, observed, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock, traceIdOfTraceparent, unitOutcome, withUnitRecord };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/core",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "The application kernel: boot a di module into a running process, and stop it without losing work",
   "keywords": [
     "application",
@@ -45,9 +45,11 @@
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@btravstack/config": "0.18.0",
-    "@btravstack/di": "0.18.0",
+    "@btravstack/config": "0.20.0",
+    "@btravstack/di": "0.20.0",
     "@btravstack/tsconfig": "0.4.0",
+    "@stryker-mutator/core": "10.0.0",
+    "@stryker-mutator/vitest-runner": "10.0.0",
     "@types/node": "26.6.4",
     "@unthrown/vitest": "5.12.0",
     "@vitest/coverage-v8": "5.0.3",
@@ -58,8 +60,8 @@
     "vitest": "5.0.3"
   },
   "peerDependencies": {
-    "@btravstack/config": "^0.18.0",
-    "@btravstack/di": "^0.18.0",
+    "@btravstack/config": "^0.20.0",
+    "@btravstack/di": "^0.20.0",
     "unthrown": "^5.0.0"
   },
   "engines": {
@@ -69,6 +71,7 @@
     "build": "tsdown src/index.ts --format cjs,esm --dts --clean --tsconfig tsconfig.build.json",
     "dev": "tsdown src/index.ts --format cjs,esm --dts --watch --tsconfig tsconfig.build.json",
     "generate": "node ../../docs/scripts/extract-doc-samples.ts --group core --out src/generated/doc-samples",
+    "mutate": "stryker run",
     "test": "vitest run --coverage",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test-d.json && node ./node_modules/typescript-consumer/bin/tsc --noEmit -p tsconfig.test-d.json"
   }