@btravstack/core 0.16.0 → 0.17.0

package/dist/index.cjs

@@ -1,6 +1,7 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _btravstack_di = require("@btravstack/di");
 let unthrown = require("unthrown");
+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");
@@ -69,10 +70,11 @@ const answeringWithin = (health, ms) => {
 * rather than a recovery.** Neither recovery above can see one: there is no
 * error and no defect, only silence, so `/healthz` held a socket open per hit
 * while kubelet timed out against a report that named nothing. Each check now
-* races {@link HealthOptions.timeoutMs}, and the component that hung is named
+* races its own `timeoutMs` (default {@link DEFAULT_HEALTH_TIMEOUT_MS}), and
+* the component that hung is named
 * in the report like any other unhealthy one.
 */
-const runHealthChecks = (checks, options = {}) => (0, unthrown.allAsync)(checks.map((health) => answeringWithin(health, health.timeoutMs ?? options.timeoutMs ?? 800).map(() => ({
+const runHealthChecks = (checks) => (0, unthrown.allAsync)(checks.map((health) => answeringWithin(health, health.timeoutMs ?? 800).map(() => ({
 	name: health.name,
 	status: "healthy"
 })).recoverErrCases((matcher) => matcher.with(unthrown.P.tag("HealthCheckFailed"), (error) => ({
@@ -153,22 +155,10 @@ const observed = (observers, operation, call, settled = {}) => {
 //#region src/clock.ts
 const systemClock = {
 	now: () => Date.now(),
-	sleep: (ms, signal) => (0, unthrown.fromSafePromise)(new Promise((resolve) => {
-		if (signal?.aborted === true) {
-			resolve();
-			return;
-		}
-		const timer = setTimeout(() => {
-			signal?.removeEventListener("abort", onAbort);
-			resolve();
-		}, ms);
-		timer.unref?.();
-		function onAbort() {
-			clearTimeout(timer);
-			resolve();
-		}
-		signal?.addEventListener("abort", onAbort, { once: true });
-	}))
+	sleep: (ms, signal) => (0, unthrown.fromSafePromise)((0, node_timers_promises.setTimeout)(ms, void 0, {
+		signal,
+		ref: false
+	}).catch(() => {}))
 };
 //#endregion
 //#region src/events.ts
@@ -621,6 +611,11 @@ const start = (module, options = {}) => {
 	const health = () => runHealthChecks(healthChecks);
 	const probeBound = Promise.withResolvers();
 	const runtimePublished = Promise.withResolvers();
+	const leaveStartup = () => {
+		runtimePublished.resolve(void 0);
+		tracker.advanceTo("stopping");
+		disposeAll();
+	};
 	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) => {
@@ -640,9 +635,7 @@ const start = (module, options = {}) => {
 			afterMs: void 0
 		});
 		registry.abortAll();
-		runtimePublished.resolve(void 0);
-		tracker.advanceTo("stopping");
-		disposeAll();
+		leaveStartup();
 		return reportOf(reason, void 0, "build");
 	});
 	const abandonBuild = (reason) => {
@@ -673,11 +666,7 @@ const start = (module, options = {}) => {
 			cause: failure.tag === "Err" ? failure.error : failure.cause
 		});
 		probeBound.resolve(void 0);
-		runtimePublished.resolve(void 0);
-		tracker.advanceTo("stopping");
-		disposeSignals();
-		disposeUncaught();
-		tracker.advanceTo("exited");
+		leaveStartup();
 	});
 	const root = (0, _btravstack_di.Module)("Kernel")({
 		imports: providesEnv(module) ? [module] : [module, (0, _btravstack_di.Module)("Environment")({
@@ -794,9 +783,7 @@ const start = (module, options = {}) => {
 			type: "startFailed",
 			cause: failure.tag === "Err" ? failure.error : failure.cause
 		});
-		runtimePublished.resolve(void 0);
-		tracker.advanceTo("stopping");
-		disposeAll();
+		leaveStartup();
 	}).tap(onLifecycleSettled).tapFailure(onLifecycleSettled);
 	return {
 		exited: probesStarted.flatMap(() => (0, unthrown.fromSafePromise)(Promise.race([
@@ -872,6 +859,97 @@ const runMain = async (module, options = {}, exit = (code) => {
 	await awaitExit(start(module, options), exit);
 };
 //#endregion
+//#region src/unit-record.ts
+/**
+* Where {@link dispatchUnit} leaves the forked context for {@link withUnitRecord}
+* to read. A symbol rather than a name: the library merges it into the context
+* every piece sees, and a string key would appear on the record a piece written
+* against the `{ inject, sync }` arm destructures.
+*/
+const UNIT_SCOPE = Symbol("@btravstack/core/unit-scope");
+/**
+* The declared record, as a getter per name resolved on read out of the fork.
+* Neither writable nor configurable — a piece reads what the fork holds, and
+* cannot reshape the record under the next unit. With no unit module bound
+* there is nothing to resolve from, so the record is empty whatever was
+* declared.
+*/
+const unitRecordOf = (forked, record) => {
+	const unit = {};
+	if (forked === void 0) return unit;
+	for (const [name, port] of Object.entries(record)) Object.defineProperty(unit, name, {
+		enumerable: true,
+		get: () => forked.get(port)
+	});
+	return 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.
+*/
+const withUnitRecord = (record, implementation) => (helpers, input) => {
+	const { [UNIT_SCOPE]: forked, ...rest } = helpers.context ?? {};
+	return implementation({
+		...helpers,
+		context: {
+			...rest,
+			unit: unitRecordOf(forked, record)
+		}
+	}, input);
+};
+/**
+* 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.
+*/
+const dispatchUnit = (dispatch) => observed(dispatch.observers, dispatch.operation, () => dispatch.host.run(dispatch.meta, (scope) => dispatch.unit === void 0 ? dispatch.next() : scope.fork(dispatch.unit, [dispatch.seed]).flatMap((forked) => dispatch.next({ context: { [UNIT_SCOPE]: forked } }))));
+//#endregion
+//#region src/pieces.ts
+/**
+* The runtime half of a starter's piece factory — `AmqpHandler(contract, key)`,
+* `TemporalWorkflowActivities(contract, key)`: a provider on `port` whose
+* service is what `sync` answers, wrapped once by `withUnit` so it reads the
+* record the piece declared. The starter keeps the types; this keeps the body.
+*/
+const mintPiece = (port, withUnit) => (options) => (0, _btravstack_di.Provider)(port)({
+	inject: options.inject,
+	sync: (services) => withUnit(options.unit ?? {}, options.sync(services))
+});
+/**
+* The runtime half of a starter's composing provider — `AmqpHandlers(contract)`,
+* `TemporalActivities(contract)` — and its two arms. An array of pieces is
+* composed into one record keyed by each piece's port id less `prefix`, so the
+* services record IS the composed record; a `{ inject, unit?, sync }` record
+* has `withUnit` applied to every entry `sync` answers.
+*/
+const composeByPrefix = (port, prefix, withUnit) => {
+	const whole = mintPiece(port, (record, entries) => Object.fromEntries(Object.entries(entries).map(([key, entry]) => [key, withUnit(record, entry)])));
+	return (first) => Array.isArray(first) ? (0, _btravstack_di.Provider)(port)({
+		inject: Object.fromEntries(first.map((piece) => [piece.port.portId.slice(prefix.length), piece.port])),
+		sync: (services) => services
+	}) : whole(first);
+};
+//#endregion
+//#region src/starter.ts
+/**
+* The no-op member every module reading {@link Observers} provides, so the set
+* it reads is never the empty dependency di refuses: a graph composing no
+* observability still starts. One provider, shared — di de-duplicates a graph's
+* providers by reference, so however many modules contribute it, an operation
+* costs one inert call.
+*/
+const noObserverMember = _btravstack_di.Provider.member(Observers)({
+	inject: {},
+	value: noObserver
+});
+//#endregion
 exports.HealthCheckFailed = HealthCheckFailed;
 exports.HealthChecks = HealthChecks;
 exports.Instrumentations = Instrumentations;
@@ -883,8 +961,12 @@ exports.RuntimePort = RuntimePort;
 exports.RuntimeStartFailed = RuntimeStartFailed;
 exports.SPAN_STATUS = SPAN_STATUS;
 exports.Tracer = Tracer;
+exports.composeByPrefix = composeByPrefix;
 exports.currentUnit = currentUnit;
+exports.dispatchUnit = dispatchUnit;
+exports.mintPiece = mintPiece;
 exports.noObserver = noObserver;
+exports.noObserverMember = noObserverMember;
 exports.observe = observe;
 exports.observed = observed;
 exports.releasedBy = releasedBy;
@@ -894,3 +976,4 @@ exports.start = start;
 exports.stderrSink = stderrSink;
 exports.systemClock = systemClock;
 exports.traceIdOfTraceparent = traceIdOfTraceparent;
+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, Scope, SeedEntry, ServiceOf } from "@btravstack/di";
+import { AnyPort, Context, DependencyGate, Module, PortClass, PortInstance, Provider, Scope, SeedEntry, ServiceOf } from "@btravstack/di";
 import { Env, Environment } from "@btravstack/config";
 //#region src/instrumentation.d.ts
 /**
@@ -8,10 +8,10 @@ import { Env, Environment } from "@btravstack/config";
  * **Async, and answers `undefined` rather than failing, because the package
  * supplying the instrumentation is an OPTIONAL peer.** A starter cannot know at
  * composition time whether the consumer installed it, so it contributes the
- * ATTEMPT and the collector drops what did not load — which is what lets
- * `@btravstack/prisma` declare engine tracing without making every consumer
- * install `@prisma/instrumentation`. A contributor that wants to say why its
- * load answered nothing logs that itself; it is the one that knows.
+ * ATTEMPT and the collector drops what did not load — which is what lets a
+ * starter declare an instrumentation without making every consumer install the
+ * package that supplies it. A contributor that wants to say why its load
+ * answered nothing logs that itself; it is the one that knows.
  *
  * The instrumentation is `unknown` on purpose. Naming OpenTelemetry's
  * `Instrumentation` would put the vendor in the package every other one peers
@@ -48,7 +48,8 @@ type HealthCheck = {
   readonly name: string;
   readonly check: () => AsyncResult<void, HealthCheckFailed>;
   /**
-   * How long this component gets to answer, overriding the fold's own default.
+   * How long this component gets to answer, overriding
+   * {@link DEFAULT_HEALTH_TIMEOUT_MS}.
    *
    * It is on the CONTRIBUTION because only the contributor knows: a `SELECT 1`
    * over a warm pool and an SMTP relay's greeting are two orders of magnitude
@@ -78,10 +79,6 @@ type HealthReport = {
   readonly status: "healthy" | "unhealthy";
   readonly components: readonly ComponentHealth[];
 };
-type HealthOptions = {
-  /** Per check, not for the fold: the checks run concurrently. Default {@link DEFAULT_HEALTH_TIMEOUT_MS}. */
-  readonly timeoutMs?: number;
-};
 /**
  * Runs every check and folds the results into one report — the whole app is
  * unhealthy if any single component is.
@@ -99,10 +96,11 @@ type HealthOptions = {
  * rather than a recovery.** Neither recovery above can see one: there is no
  * error and no defect, only silence, so `/healthz` held a socket open per hit
  * while kubelet timed out against a report that named nothing. Each check now
- * races {@link HealthOptions.timeoutMs}, and the component that hung is named
+ * races its own `timeoutMs` (default {@link DEFAULT_HEALTH_TIMEOUT_MS}), and
+ * the component that hung is named
  * in the report like any other unhealthy one.
  */
-export declare const runHealthChecks: (checks: readonly HealthCheck[], options?: HealthOptions) => AsyncResult<HealthReport, never>;
+export declare const runHealthChecks: (checks: readonly HealthCheck[]) => AsyncResult<HealthReport, never>;
 //#endregion
 //#region src/observability.d.ts
 /**
@@ -133,7 +131,6 @@ type Attributes = Readonly<Record<string, string | number | boolean | undefined>
  * failure with nothing else to say.
  */
 type LoggerService = {
-  readonly log: (level: Level, message: string, attributes?: Attributes, cause?: unknown) => void;
   readonly trace: (message: string, attributes?: Attributes, cause?: unknown) => void;
   readonly debug: (message: string, attributes?: Attributes, cause?: unknown) => void;
   readonly info: (message: string, attributes?: Attributes, cause?: unknown) => void;
@@ -257,15 +254,12 @@ type Operation = {
   /**
    * Whether a tracing observer should open a span (default `true`).
    *
-   * `false` is for a component whose spans already come from somewhere better —
-   * a vendor tracer reaching below what the contributor can see, where a second
-   * span would cost one more per operation for strictly less information.
-   * Counting and timing still happen.
-   *
-   * **No starter here passes `false` today.** `@btravstack/prisma` did, while
-   * Prisma 7's engine-level `@prisma/instrumentation` was the better source;
-   * Prisma 8 has no engine and ships no tracer, so its middleware is the only
-   * span there is and it opens one.
+   * `false` is for an operation a span would say nothing about — one whose
+   * spans already come from somewhere better, or one with no duration at all.
+   * Counting and timing still happen. `@btravstack/amqp-worker`'s broker
+   * diagnostics pass it, being zero-length events; `@btravstack/prisma` no
+   * longer does, since Prisma 8 ships no engine tracer and its middleware is
+   * the only span there is.
    *
    * Whether a span is worth opening is the CONTRIBUTOR's knowledge, which is
    * why it rides the operation rather than being configured on the observer.
@@ -840,4 +834,112 @@ 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
-export type { Attributes, Clock, ComponentHealth, Counter, DrainReport, EventSink, ExitReport, HealthCheck, HealthReport, Histogram, InstrumentationLoader, KernelEvent, Level, LoggerService, MeterService, Operation, Phase, RunUnit, RunningApp, Runtime, RuntimeHost, RuntimeInfoOf, Serving, Settle, Settled, Span, SpanStatusCode, StartGate, StartOptions, TeardownError, TracerService, UnitHost, UnitMeta, UnitRecord, UnitRegistry, UnitWork };
+//#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/pieces.d.ts
+/**
+ * A refused array: as long as the array the caller wrote, its head the caller's
+ * own elements — which match — and its LAST element the marker paired with what
+ * is wrong.
+ *
+ * TypeScript compares two equal-length tuples element by element, so the extra
+ * diagnostic it reports lands on the trailing element and carries both the
+ * sentence and the missing key. A fixed two-element tuple named the key only
+ * when the array happened to be two elements long; every other arity was a
+ * length mismatch, and the developer diffed the contract against the array by
+ * hand.
+ */
+type Refuse<T extends readonly unknown[], Marker extends string, Detail> = T extends readonly [...infer Head, unknown] ? readonly [...Head, readonly [Marker, Detail]] : readonly [readonly [Marker, Detail]];
+/** How a starter puts a piece's declared `unit:` record on one of its entries. */
+type EntryWrapper = (record: Readonly<Record<string, AnyPort>>, entry: unknown) => unknown;
+/** A piece's `{ inject, unit?, sync }` options, with the types each starter states erased. */
+type PieceOptions = {
+  readonly inject: Readonly<Record<string, AnyPort>>;
+  readonly unit?: Readonly<Record<string, AnyPort>>;
+  readonly sync: (services: never) => unknown;
+};
+/**
+ * The runtime half of a starter's piece factory — `AmqpHandler(contract, key)`,
+ * `TemporalWorkflowActivities(contract, key)`: a provider on `port` whose
+ * service is what `sync` answers, wrapped once by `withUnit` so it reads the
+ * record the piece declared. The starter keeps the types; this keeps the body.
+ */
+export declare const mintPiece: (port: AnyPort, withUnit: EntryWrapper) => (options: PieceOptions) => unknown;
+/**
+ * The runtime half of a starter's composing provider — `AmqpHandlers(contract)`,
+ * `TemporalActivities(contract)` — and its two arms. An array of pieces is
+ * composed into one record keyed by each piece's port id less `prefix`, so the
+ * services record IS the composed record; a `{ inject, unit?, sync }` record
+ * has `withUnit` applied to every entry `sync` answers.
+ */
+export declare const composeByPrefix: (port: AnyPort, prefix: string, withUnit: EntryWrapper) => ((first: unknown) => unknown);
+//#endregion
+//#region src/starter.d.ts
+/**
+ * The no-op member every module reading {@link Observers} provides, so the set
+ * it reads is never the empty dependency di refuses: a graph composing no
+ * observability still starts. One provider, shared — di de-duplicates a graph's
+ * providers by reference, so however many modules contribute it, an operation
+ * costs one inert call.
+ */
+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 };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AnyPort, Context, DependencyGate, Module, PortClass, PortInstance, Scope, SeedEntry, ServiceOf } from "@btravstack/di";
+import { AnyPort, 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
@@ -8,10 +8,10 @@ import { Env, Environment } from "@btravstack/config";
  * **Async, and answers `undefined` rather than failing, because the package
  * supplying the instrumentation is an OPTIONAL peer.** A starter cannot know at
  * composition time whether the consumer installed it, so it contributes the
- * ATTEMPT and the collector drops what did not load — which is what lets
- * `@btravstack/prisma` declare engine tracing without making every consumer
- * install `@prisma/instrumentation`. A contributor that wants to say why its
- * load answered nothing logs that itself; it is the one that knows.
+ * ATTEMPT and the collector drops what did not load — which is what lets a
+ * starter declare an instrumentation without making every consumer install the
+ * package that supplies it. A contributor that wants to say why its load
+ * answered nothing logs that itself; it is the one that knows.
  *
  * The instrumentation is `unknown` on purpose. Naming OpenTelemetry's
  * `Instrumentation` would put the vendor in the package every other one peers
@@ -48,7 +48,8 @@ type HealthCheck = {
   readonly name: string;
   readonly check: () => AsyncResult<void, HealthCheckFailed>;
   /**
-   * How long this component gets to answer, overriding the fold's own default.
+   * How long this component gets to answer, overriding
+   * {@link DEFAULT_HEALTH_TIMEOUT_MS}.
    *
    * It is on the CONTRIBUTION because only the contributor knows: a `SELECT 1`
    * over a warm pool and an SMTP relay's greeting are two orders of magnitude
@@ -78,10 +79,6 @@ type HealthReport = {
   readonly status: "healthy" | "unhealthy";
   readonly components: readonly ComponentHealth[];
 };
-type HealthOptions = {
-  /** Per check, not for the fold: the checks run concurrently. Default {@link DEFAULT_HEALTH_TIMEOUT_MS}. */
-  readonly timeoutMs?: number;
-};
 /**
  * Runs every check and folds the results into one report — the whole app is
  * unhealthy if any single component is.
@@ -99,10 +96,11 @@ type HealthOptions = {
  * rather than a recovery.** Neither recovery above can see one: there is no
  * error and no defect, only silence, so `/healthz` held a socket open per hit
  * while kubelet timed out against a report that named nothing. Each check now
- * races {@link HealthOptions.timeoutMs}, and the component that hung is named
+ * races its own `timeoutMs` (default {@link DEFAULT_HEALTH_TIMEOUT_MS}), and
+ * the component that hung is named
  * in the report like any other unhealthy one.
  */
-export declare const runHealthChecks: (checks: readonly HealthCheck[], options?: HealthOptions) => AsyncResult<HealthReport, never>;
+export declare const runHealthChecks: (checks: readonly HealthCheck[]) => AsyncResult<HealthReport, never>;
 //#endregion
 //#region src/observability.d.ts
 /**
@@ -133,7 +131,6 @@ type Attributes = Readonly<Record<string, string | number | boolean | undefined>
  * failure with nothing else to say.
  */
 type LoggerService = {
-  readonly log: (level: Level, message: string, attributes?: Attributes, cause?: unknown) => void;
   readonly trace: (message: string, attributes?: Attributes, cause?: unknown) => void;
   readonly debug: (message: string, attributes?: Attributes, cause?: unknown) => void;
   readonly info: (message: string, attributes?: Attributes, cause?: unknown) => void;
@@ -257,15 +254,12 @@ type Operation = {
   /**
    * Whether a tracing observer should open a span (default `true`).
    *
-   * `false` is for a component whose spans already come from somewhere better —
-   * a vendor tracer reaching below what the contributor can see, where a second
-   * span would cost one more per operation for strictly less information.
-   * Counting and timing still happen.
-   *
-   * **No starter here passes `false` today.** `@btravstack/prisma` did, while
-   * Prisma 7's engine-level `@prisma/instrumentation` was the better source;
-   * Prisma 8 has no engine and ships no tracer, so its middleware is the only
-   * span there is and it opens one.
+   * `false` is for an operation a span would say nothing about — one whose
+   * spans already come from somewhere better, or one with no duration at all.
+   * Counting and timing still happen. `@btravstack/amqp-worker`'s broker
+   * diagnostics pass it, being zero-length events; `@btravstack/prisma` no
+   * longer does, since Prisma 8 ships no engine tracer and its middleware is
+   * the only span there is.
    *
    * Whether a span is worth opening is the CONTRIBUTOR's knowledge, which is
    * why it rides the operation rather than being configured on the observer.
@@ -840,4 +834,112 @@ 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
-export type { Attributes, Clock, ComponentHealth, Counter, DrainReport, EventSink, ExitReport, HealthCheck, HealthReport, Histogram, InstrumentationLoader, KernelEvent, Level, LoggerService, MeterService, Operation, Phase, RunUnit, RunningApp, Runtime, RuntimeHost, RuntimeInfoOf, Serving, Settle, Settled, Span, SpanStatusCode, StartGate, StartOptions, TeardownError, TracerService, UnitHost, UnitMeta, UnitRecord, UnitRegistry, UnitWork };
+//#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/pieces.d.ts
+/**
+ * A refused array: as long as the array the caller wrote, its head the caller's
+ * own elements — which match — and its LAST element the marker paired with what
+ * is wrong.
+ *
+ * TypeScript compares two equal-length tuples element by element, so the extra
+ * diagnostic it reports lands on the trailing element and carries both the
+ * sentence and the missing key. A fixed two-element tuple named the key only
+ * when the array happened to be two elements long; every other arity was a
+ * length mismatch, and the developer diffed the contract against the array by
+ * hand.
+ */
+type Refuse<T extends readonly unknown[], Marker extends string, Detail> = T extends readonly [...infer Head, unknown] ? readonly [...Head, readonly [Marker, Detail]] : readonly [readonly [Marker, Detail]];
+/** How a starter puts a piece's declared `unit:` record on one of its entries. */
+type EntryWrapper = (record: Readonly<Record<string, AnyPort>>, entry: unknown) => unknown;
+/** A piece's `{ inject, unit?, sync }` options, with the types each starter states erased. */
+type PieceOptions = {
+  readonly inject: Readonly<Record<string, AnyPort>>;
+  readonly unit?: Readonly<Record<string, AnyPort>>;
+  readonly sync: (services: never) => unknown;
+};
+/**
+ * The runtime half of a starter's piece factory — `AmqpHandler(contract, key)`,
+ * `TemporalWorkflowActivities(contract, key)`: a provider on `port` whose
+ * service is what `sync` answers, wrapped once by `withUnit` so it reads the
+ * record the piece declared. The starter keeps the types; this keeps the body.
+ */
+export declare const mintPiece: (port: AnyPort, withUnit: EntryWrapper) => (options: PieceOptions) => unknown;
+/**
+ * The runtime half of a starter's composing provider — `AmqpHandlers(contract)`,
+ * `TemporalActivities(contract)` — and its two arms. An array of pieces is
+ * composed into one record keyed by each piece's port id less `prefix`, so the
+ * services record IS the composed record; a `{ inject, unit?, sync }` record
+ * has `withUnit` applied to every entry `sync` answers.
+ */
+export declare const composeByPrefix: (port: AnyPort, prefix: string, withUnit: EntryWrapper) => ((first: unknown) => unknown);
+//#endregion
+//#region src/starter.d.ts
+/**
+ * The no-op member every module reading {@link Observers} provides, so the set
+ * it reads is never the empty dependency di refuses: a graph composing no
+ * observability still starts. One provider, shared — di de-duplicates a graph's
+ * providers by reference, so however many modules contribute it, an operation
+ * costs one inert call.
+ */
+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 };

package/dist/index.mjs

@@ -1,5 +1,6 @@
 import { Module, Port, Provider } from "@btravstack/di";
 import { Err, Ok, OkAsync, P, TaggedError, allAsync, fromSafePromise } from "unthrown";
+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";
@@ -68,10 +69,11 @@ const answeringWithin = (health, ms) => {
 * rather than a recovery.** Neither recovery above can see one: there is no
 * error and no defect, only silence, so `/healthz` held a socket open per hit
 * while kubelet timed out against a report that named nothing. Each check now
-* races {@link HealthOptions.timeoutMs}, and the component that hung is named
+* races its own `timeoutMs` (default {@link DEFAULT_HEALTH_TIMEOUT_MS}), and
+* the component that hung is named
 * in the report like any other unhealthy one.
 */
-const runHealthChecks = (checks, options = {}) => allAsync(checks.map((health) => answeringWithin(health, health.timeoutMs ?? options.timeoutMs ?? 800).map(() => ({
+const runHealthChecks = (checks) => allAsync(checks.map((health) => answeringWithin(health, health.timeoutMs ?? 800).map(() => ({
 	name: health.name,
 	status: "healthy"
 })).recoverErrCases((matcher) => matcher.with(P.tag("HealthCheckFailed"), (error) => ({
@@ -152,22 +154,10 @@ const observed = (observers, operation, call, settled = {}) => {
 //#region src/clock.ts
 const systemClock = {
 	now: () => Date.now(),
-	sleep: (ms, signal) => fromSafePromise(new Promise((resolve) => {
-		if (signal?.aborted === true) {
-			resolve();
-			return;
-		}
-		const timer = setTimeout(() => {
-			signal?.removeEventListener("abort", onAbort);
-			resolve();
-		}, ms);
-		timer.unref?.();
-		function onAbort() {
-			clearTimeout(timer);
-			resolve();
-		}
-		signal?.addEventListener("abort", onAbort, { once: true });
-	}))
+	sleep: (ms, signal) => fromSafePromise(setTimeout$1(ms, void 0, {
+		signal,
+		ref: false
+	}).catch(() => {}))
 };
 //#endregion
 //#region src/events.ts
@@ -620,6 +610,11 @@ const start = (module, options = {}) => {
 	const health = () => runHealthChecks(healthChecks);
 	const probeBound = Promise.withResolvers();
 	const runtimePublished = Promise.withResolvers();
+	const leaveStartup = () => {
+		runtimePublished.resolve(void 0);
+		tracker.advanceTo("stopping");
+		disposeAll();
+	};
 	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) => {
@@ -639,9 +634,7 @@ const start = (module, options = {}) => {
 			afterMs: void 0
 		});
 		registry.abortAll();
-		runtimePublished.resolve(void 0);
-		tracker.advanceTo("stopping");
-		disposeAll();
+		leaveStartup();
 		return reportOf(reason, void 0, "build");
 	});
 	const abandonBuild = (reason) => {
@@ -672,11 +665,7 @@ const start = (module, options = {}) => {
 			cause: failure.tag === "Err" ? failure.error : failure.cause
 		});
 		probeBound.resolve(void 0);
-		runtimePublished.resolve(void 0);
-		tracker.advanceTo("stopping");
-		disposeSignals();
-		disposeUncaught();
-		tracker.advanceTo("exited");
+		leaveStartup();
 	});
 	const root = Module("Kernel")({
 		imports: providesEnv(module) ? [module] : [module, Module("Environment")({
@@ -793,9 +782,7 @@ const start = (module, options = {}) => {
 			type: "startFailed",
 			cause: failure.tag === "Err" ? failure.error : failure.cause
 		});
-		runtimePublished.resolve(void 0);
-		tracker.advanceTo("stopping");
-		disposeAll();
+		leaveStartup();
 	}).tap(onLifecycleSettled).tapFailure(onLifecycleSettled);
 	return {
 		exited: probesStarted.flatMap(() => fromSafePromise(Promise.race([
@@ -871,4 +858,95 @@ const runMain = async (module, options = {}, exit = (code) => {
 	await awaitExit(start(module, options), exit);
 };
 //#endregion
-export { HealthCheckFailed, HealthChecks, Instrumentations, LEVELS, Logger, Meter, Observers, RuntimePort, RuntimeStartFailed, SPAN_STATUS, Tracer, currentUnit, noObserver, observe, observed, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock, traceIdOfTraceparent };
+//#region src/unit-record.ts
+/**
+* Where {@link dispatchUnit} leaves the forked context for {@link withUnitRecord}
+* to read. A symbol rather than a name: the library merges it into the context
+* every piece sees, and a string key would appear on the record a piece written
+* against the `{ inject, sync }` arm destructures.
+*/
+const UNIT_SCOPE = Symbol("@btravstack/core/unit-scope");
+/**
+* The declared record, as a getter per name resolved on read out of the fork.
+* Neither writable nor configurable — a piece reads what the fork holds, and
+* cannot reshape the record under the next unit. With no unit module bound
+* there is nothing to resolve from, so the record is empty whatever was
+* declared.
+*/
+const unitRecordOf = (forked, record) => {
+	const unit = {};
+	if (forked === void 0) return unit;
+	for (const [name, port] of Object.entries(record)) Object.defineProperty(unit, name, {
+		enumerable: true,
+		get: () => forked.get(port)
+	});
+	return 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.
+*/
+const withUnitRecord = (record, implementation) => (helpers, input) => {
+	const { [UNIT_SCOPE]: forked, ...rest } = helpers.context ?? {};
+	return implementation({
+		...helpers,
+		context: {
+			...rest,
+			unit: unitRecordOf(forked, record)
+		}
+	}, input);
+};
+/**
+* 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.
+*/
+const dispatchUnit = (dispatch) => observed(dispatch.observers, dispatch.operation, () => dispatch.host.run(dispatch.meta, (scope) => dispatch.unit === void 0 ? dispatch.next() : scope.fork(dispatch.unit, [dispatch.seed]).flatMap((forked) => dispatch.next({ context: { [UNIT_SCOPE]: forked } }))));
+//#endregion
+//#region src/pieces.ts
+/**
+* The runtime half of a starter's piece factory — `AmqpHandler(contract, key)`,
+* `TemporalWorkflowActivities(contract, key)`: a provider on `port` whose
+* service is what `sync` answers, wrapped once by `withUnit` so it reads the
+* record the piece declared. The starter keeps the types; this keeps the body.
+*/
+const mintPiece = (port, withUnit) => (options) => Provider(port)({
+	inject: options.inject,
+	sync: (services) => withUnit(options.unit ?? {}, options.sync(services))
+});
+/**
+* The runtime half of a starter's composing provider — `AmqpHandlers(contract)`,
+* `TemporalActivities(contract)` — and its two arms. An array of pieces is
+* composed into one record keyed by each piece's port id less `prefix`, so the
+* services record IS the composed record; a `{ inject, unit?, sync }` record
+* has `withUnit` applied to every entry `sync` answers.
+*/
+const composeByPrefix = (port, prefix, withUnit) => {
+	const whole = mintPiece(port, (record, entries) => Object.fromEntries(Object.entries(entries).map(([key, entry]) => [key, withUnit(record, entry)])));
+	return (first) => Array.isArray(first) ? Provider(port)({
+		inject: Object.fromEntries(first.map((piece) => [piece.port.portId.slice(prefix.length), piece.port])),
+		sync: (services) => services
+	}) : whole(first);
+};
+//#endregion
+//#region src/starter.ts
+/**
+* The no-op member every module reading {@link Observers} provides, so the set
+* it reads is never the empty dependency di refuses: a graph composing no
+* observability still starts. One provider, shared — di de-duplicates a graph's
+* providers by reference, so however many modules contribute it, an operation
+* costs one inert call.
+*/
+const noObserverMember = Provider.member(Observers)({
+	inject: {},
+	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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/core",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "The application kernel: boot a di module into a running process, and stop it without losing work",
   "keywords": [
     "application",
@@ -45,20 +45,20 @@
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@btravstack/config": "0.16.0",
-    "@btravstack/di": "0.16.0",
+    "@btravstack/config": "0.17.0",
+    "@btravstack/di": "0.17.0",
     "@btravstack/tsconfig": "0.4.0",
-    "@types/node": "26.4.1",
-    "@unthrown/vitest": "5.8.0",
-    "@vitest/coverage-v8": "4.1.11",
+    "@types/node": "26.6.4",
+    "@unthrown/vitest": "5.12.0",
+    "@vitest/coverage-v8": "5.0.3",
     "tsdown": "0.23.0",
     "typescript": "7.0.2",
-    "unthrown": "5.8.0",
-    "vitest": "4.1.11"
+    "unthrown": "5.12.0",
+    "vitest": "5.0.3"
   },
   "peerDependencies": {
-    "@btravstack/config": "^0.16.0",
-    "@btravstack/di": "^0.16.0",
+    "@btravstack/config": "^0.17.0",
+    "@btravstack/di": "^0.17.0",
     "unthrown": "^5.0.0"
   },
   "engines": {