@btravstack/core 0.17.0 → 0.19.0

package/dist/index.cjs

@@ -5,6 +5,7 @@ let node_timers_promises = require("node:timers/promises");
 let _btravstack_config = require("@btravstack/config");
 let node_http = require("node:http");
 let node_async_hooks = require("node:async_hooks");
+let node_crypto = require("node:crypto");
 //#region src/instrumentation.ts
 /**
 * The set port a package contributes its instrumentation to.
@@ -428,14 +429,71 @@ 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);
 const currentUnit = () => storage.getStore();
-let counter = 0;
-const nextId = () => {
-	counter += 1;
-	return `u${counter}`;
+const outcomes = /* @__PURE__ */ new WeakMap();
+const settleUnit = (record, outcome) => {
+	outcomes.set(record, outcome);
+};
+/**
+* How the current unit's work settled, for the code that runs AFTER it: a
+* unit module's `onStop`, which tears down inside the record but is handed
+* only its own service. `undefined` outside a unit and while the work is still
+* running. Whether the unit was aborted is the record's own `signal`.
+*
+* It is the kernel's outcome, not the transport's: an HTTP unit that answered
+* a `500` still settled `ok`, since the kernel never maps a status.
+*/
+const unitOutcome = () => {
+	const unit = currentUnit();
+	return unit === void 0 ? void 0 : outcomes.get(unit);
 };
 const createUnitRegistry = () => {
 	const open = /* @__PURE__ */ new Set();
@@ -451,7 +509,7 @@ const createUnitRegistry = () => {
 			const controller = new AbortController();
 			open.add(controller);
 			const record = {
-				unitId: nextId(),
+				unitId: (0, node_crypto.randomUUID)(),
 				traceId: meta.traceId ?? meta.id,
 				tenantId: meta.tenantId,
 				signal: controller.signal
@@ -485,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
@@ -532,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;
@@ -584,6 +648,7 @@ const start = (module, options = {}) => {
 		}
 	});
 	const disposeUncaught = options.signals === false ? () => {} : installUncaughtHandlers((cause) => {
+		crashed = true;
 		emit({
 			type: "uncaught",
 			cause
@@ -594,6 +659,8 @@ const start = (module, options = {}) => {
 		abandonBuild("uncaught");
 	});
 	let disposeProbes = () => {};
+	let crashed = false;
+	let startupFailing = false;
 	const disposeAll = () => {
 		disposeSignals();
 		disposeUncaught();
@@ -601,7 +668,7 @@ const start = (module, options = {}) => {
 		disposeProbes();
 	};
 	const reportOf = (reason, drain, abandonedAt) => ({
-		reason,
+		reason: crashed ? "uncaught" : reason,
 		drain,
 		teardownErrors,
 		uptimeMs: clock.now() - startedAt,
@@ -616,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) => {
@@ -640,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 : {
@@ -701,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;
@@ -725,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
@@ -741,13 +817,18 @@ const start = (module, options = {}) => {
 				}).get();
 				return (0, unthrown.fromSafePromise)(ready.promise);
 			};
+			const record = currentUnit();
 			const outcome = (async () => {
+				let settledAs = "error";
 				try {
-					return await work({
+					const result = await work({
 						ctx: runtimeCtx,
 						fork
 					}, signal);
+					if (result.isOk()) settledAs = "ok";
+					return result;
 				} finally {
+					if (record !== void 0) settleUnit(record, settledAs);
 					hasSettled = true;
 					settled.resolve();
 					if (closing !== void 0) await closing;
@@ -768,23 +849,32 @@ const start = (module, options = {}) => {
 			});
 			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(),
@@ -961,6 +1051,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;
@@ -976,4 +1067,5 @@ exports.start = start;
 exports.stderrSink = stderrSink;
 exports.systemClock = systemClock;
 exports.traceIdOfTraceparent = traceIdOfTraceparent;
+exports.unitOutcome = unitOutcome;
 exports.withUnitRecord = withUnitRecord;

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
 /**
@@ -352,6 +352,18 @@ type UnitRecord = {
   readonly signal: AbortSignal;
 };
 export declare const currentUnit: () => UnitRecord | undefined;
+/** How a unit's work settled: `ok`, or `error` for an `Err`, a `Defect` and a throw alike. */
+type UnitOutcome = "ok" | "error";
+/**
+ * How the current unit's work settled, for the code that runs AFTER it: a
+ * unit module's `onStop`, which tears down inside the record but is handed
+ * only its own service. `undefined` outside a unit and while the work is still
+ * running. Whether the unit was aborted is the record's own `signal`.
+ *
+ * It is the kernel's outcome, not the transport's: an HTTP unit that answered
+ * a `500` still settled `ok`, since the kernel never maps a status.
+ */
+export declare const unitOutcome: () => UnitOutcome | undefined;
 /**
  * What a runtime says about one piece of work as it submits it. `kind` is the
  * category (`"http"`, `"tick"`, `"job"`); `id` identifies **this** unit.
@@ -363,7 +375,8 @@ export declare const currentUnit: () => UnitRecord | undefined;
  * silently defeats the ambient record. A route template is a `kind`.
  *
  * The kernel cannot check this, so uniqueness is the runtime's to guarantee.
- * What it does guarantee is {@link UnitRecord}'s `unitId`, minted per unit;
+ * What it does guarantee is {@link UnitRecord}'s `unitId`, a UUID minted per
+ * unit, so no two units share one across replicas either;
  * `traceId` is the CORRELATION id, which is why it is the one a runtime may
  * supply — it carries an id from outside the process.
  */
@@ -382,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<{
@@ -491,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
@@ -834,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
-/**
- * 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>>;
-};
+//#region src/unit-overrides.d.ts
+declare const UnitOverrides_base: import("@btravstack/di").ManyPortClass<"UnitOverrides">;
 /**
- * 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
 /**
@@ -942,4 +978,4 @@ export declare const noObserverMember: Provider<Observers, never, never> & {
   readonly port: typeof Observers;
 };
 //#endregion
-export type { AnyUnitModule, Attributes, Clock, ComponentHealth, Counter, DrainReport, EventSink, ExitReport, HealthCheck, HealthReport, Histogram, InstrumentationLoader, KernelEvent, Level, LoggerService, MeterService, Operation, Phase, Refuse, RunUnit, RunningApp, Runtime, RuntimeHost, RuntimeInfoOf, Serving, Settle, Settled, Span, SpanStatusCode, StartGate, StartOptions, TeardownError, TracerService, UnitExportsOf, UnitGate, UnitHost, UnitMeta, UnitNeedsOf, UnitRecord, UnitRecordOf, UnitRegistry, UnitWork };
+export type { AnyUnitModule, Attributes, Clock, ComponentHealth, Counter, DrainReport, EventSink, ExitReport, HealthCheck, HealthReport, Histogram, InstrumentationLoader, KernelEvent, Level, LoggerService, MeterService, Operation, Phase, Refuse, RunUnit, RunningApp, Runtime, RuntimeHost, RuntimeInfoOf, Serving, Settle, Settled, Span, SpanStatusCode, StartGate, StartOptions, TeardownError, TracerService, UnitExportsOf, UnitGate, UnitHost, UnitMeta, UnitNeedsOf, UnitOutcome, UnitRecord, UnitRecordOf, UnitRegistry, UnitWork };

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
@@ -352,6 +352,18 @@ type UnitRecord = {
   readonly signal: AbortSignal;
 };
 export declare const currentUnit: () => UnitRecord | undefined;
+/** How a unit's work settled: `ok`, or `error` for an `Err`, a `Defect` and a throw alike. */
+type UnitOutcome = "ok" | "error";
+/**
+ * How the current unit's work settled, for the code that runs AFTER it: a
+ * unit module's `onStop`, which tears down inside the record but is handed
+ * only its own service. `undefined` outside a unit and while the work is still
+ * running. Whether the unit was aborted is the record's own `signal`.
+ *
+ * It is the kernel's outcome, not the transport's: an HTTP unit that answered
+ * a `500` still settled `ok`, since the kernel never maps a status.
+ */
+export declare const unitOutcome: () => UnitOutcome | undefined;
 /**
  * What a runtime says about one piece of work as it submits it. `kind` is the
  * category (`"http"`, `"tick"`, `"job"`); `id` identifies **this** unit.
@@ -363,7 +375,8 @@ export declare const currentUnit: () => UnitRecord | undefined;
  * silently defeats the ambient record. A route template is a `kind`.
  *
  * The kernel cannot check this, so uniqueness is the runtime's to guarantee.
- * What it does guarantee is {@link UnitRecord}'s `unitId`, minted per unit;
+ * What it does guarantee is {@link UnitRecord}'s `unitId`, a UUID minted per
+ * unit, so no two units share one across replicas either;
  * `traceId` is the CORRELATION id, which is why it is the one a runtime may
  * supply — it carries an id from outside the process.
  */
@@ -382,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<{
@@ -491,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
@@ -834,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
-/**
- * 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>>;
-};
+//#region src/unit-overrides.d.ts
+declare const UnitOverrides_base: import("@btravstack/di").ManyPortClass<"UnitOverrides">;
 /**
- * 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
 /**
@@ -942,4 +978,4 @@ export declare const noObserverMember: Provider<Observers, never, never> & {
   readonly port: typeof Observers;
 };
 //#endregion
-export type { AnyUnitModule, Attributes, Clock, ComponentHealth, Counter, DrainReport, EventSink, ExitReport, HealthCheck, HealthReport, Histogram, InstrumentationLoader, KernelEvent, Level, LoggerService, MeterService, Operation, Phase, Refuse, RunUnit, RunningApp, Runtime, RuntimeHost, RuntimeInfoOf, Serving, Settle, Settled, Span, SpanStatusCode, StartGate, StartOptions, TeardownError, TracerService, UnitExportsOf, UnitGate, UnitHost, UnitMeta, UnitNeedsOf, UnitRecord, UnitRecordOf, UnitRegistry, UnitWork };
+export type { AnyUnitModule, Attributes, Clock, ComponentHealth, Counter, DrainReport, EventSink, ExitReport, HealthCheck, HealthReport, Histogram, InstrumentationLoader, KernelEvent, Level, LoggerService, MeterService, Operation, Phase, Refuse, RunUnit, RunningApp, Runtime, RuntimeHost, RuntimeInfoOf, Serving, Settle, Settled, Span, SpanStatusCode, StartGate, StartOptions, TeardownError, TracerService, UnitExportsOf, UnitGate, UnitHost, UnitMeta, UnitNeedsOf, UnitOutcome, UnitRecord, UnitRecordOf, UnitRegistry, UnitWork };

package/dist/index.mjs

@@ -4,6 +4,7 @@ import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import { Config, ConfigInvalid, Env } from "@btravstack/config";
 import { createServer } from "node:http";
 import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
 //#region src/instrumentation.ts
 /**
 * The set port a package contributes its instrumentation to.
@@ -427,14 +428,71 @@ 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);
 const currentUnit = () => storage.getStore();
-let counter = 0;
-const nextId = () => {
-	counter += 1;
-	return `u${counter}`;
+const outcomes = /* @__PURE__ */ new WeakMap();
+const settleUnit = (record, outcome) => {
+	outcomes.set(record, outcome);
+};
+/**
+* How the current unit's work settled, for the code that runs AFTER it: a
+* unit module's `onStop`, which tears down inside the record but is handed
+* only its own service. `undefined` outside a unit and while the work is still
+* running. Whether the unit was aborted is the record's own `signal`.
+*
+* It is the kernel's outcome, not the transport's: an HTTP unit that answered
+* a `500` still settled `ok`, since the kernel never maps a status.
+*/
+const unitOutcome = () => {
+	const unit = currentUnit();
+	return unit === void 0 ? void 0 : outcomes.get(unit);
 };
 const createUnitRegistry = () => {
 	const open = /* @__PURE__ */ new Set();
@@ -450,7 +508,7 @@ const createUnitRegistry = () => {
 			const controller = new AbortController();
 			open.add(controller);
 			const record = {
-				unitId: nextId(),
+				unitId: randomUUID(),
 				traceId: meta.traceId ?? meta.id,
 				tenantId: meta.tenantId,
 				signal: controller.signal
@@ -484,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
@@ -531,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;
@@ -583,6 +647,7 @@ const start = (module, options = {}) => {
 		}
 	});
 	const disposeUncaught = options.signals === false ? () => {} : installUncaughtHandlers((cause) => {
+		crashed = true;
 		emit({
 			type: "uncaught",
 			cause
@@ -593,6 +658,8 @@ const start = (module, options = {}) => {
 		abandonBuild("uncaught");
 	});
 	let disposeProbes = () => {};
+	let crashed = false;
+	let startupFailing = false;
 	const disposeAll = () => {
 		disposeSignals();
 		disposeUncaught();
@@ -600,7 +667,7 @@ const start = (module, options = {}) => {
 		disposeProbes();
 	};
 	const reportOf = (reason, drain, abandonedAt) => ({
-		reason,
+		reason: crashed ? "uncaught" : reason,
 		drain,
 		teardownErrors,
 		uptimeMs: clock.now() - startedAt,
@@ -615,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) => {
@@ -639,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 : {
@@ -700,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;
@@ -724,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
@@ -740,13 +816,18 @@ const start = (module, options = {}) => {
 				}).get();
 				return fromSafePromise(ready.promise);
 			};
+			const record = currentUnit();
 			const outcome = (async () => {
+				let settledAs = "error";
 				try {
-					return await work({
+					const result = await work({
 						ctx: runtimeCtx,
 						fork
 					}, signal);
+					if (result.isOk()) settledAs = "ok";
+					return result;
 				} finally {
+					if (record !== void 0) settleUnit(record, settledAs);
 					hasSettled = true;
 					settled.resolve();
 					if (closing !== void 0) await closing;
@@ -767,23 +848,32 @@ const start = (module, options = {}) => {
 			});
 			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(),
@@ -949,4 +1039,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, 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.17.0",
+  "version": "0.19.0",
   "description": "The application kernel: boot a di module into a running process, and stop it without losing work",
   "keywords": [
     "application",
@@ -45,20 +45,23 @@
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@btravstack/config": "0.17.0",
-    "@btravstack/di": "0.17.0",
+    "@btravstack/config": "0.19.0",
+    "@btravstack/di": "0.19.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",
     "tsdown": "0.23.0",
     "typescript": "7.0.2",
+    "typescript-consumer": "npm:typescript@5.9.3",
     "unthrown": "5.12.0",
     "vitest": "5.0.3"
   },
   "peerDependencies": {
-    "@btravstack/config": "^0.17.0",
-    "@btravstack/di": "^0.17.0",
+    "@btravstack/config": "^0.19.0",
+    "@btravstack/di": "^0.19.0",
     "unthrown": "^5.0.0"
   },
   "engines": {
@@ -68,7 +71,8 @@
     "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"
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test-d.json && node ./node_modules/typescript-consumer/bin/tsc --noEmit -p tsconfig.test-d.json"
   }
 }