@btravstack/core 0.12.0 → 0.13.0

package/README.md

@@ -68,8 +68,8 @@ const ticker: Runtime<typeof Greeter> = {
       // and stays out of it. A timer has nowhere to return one, so it observes
       // it instead; dropping it would hide the work's `Err` *and* a `Defect`.
       void host
-        .run({ kind: "tick", id: `${Date.now()}` }, (ctx, signal) =>
-          signal.aborted ? Ok("") : Ok(ctx.get(Greeter).greet("world")),
+        .run({ kind: "tick", id: `${Date.now()}` }, (unit, signal) =>
+          signal.aborted ? Ok("") : Ok(unit.ctx.get(Greeter).greet("world")),
         )
         .tapFailure((failure) => {
           process.stderr.write(`${JSON.stringify({ tick: failure.tag })}\n`);
@@ -145,8 +145,9 @@ them and none should own a private copy:
   bad value is a `ConfigInvalid` naming every fault at once, and exit `78`.
 - **Teardown on every path**, with failing finalisers in
   `ExitReport.teardownErrors`, never masking the exit reason.
-- **A per-unit scope no handler manages** — pass a module as
-  `StartOptions.unit` and the kernel forks it around every unit.
+- **A per-unit scope no handler manages** — the runtime calls
+  `unit.fork(module, seed)` from inside `host.run`'s work callback, and the
+  kernel closes the scope when the unit settles.
 - **An ambient record, not an ambient container** — `currentUnit()` reads
   `{ unitId, traceId, tenantId, signal }`; services never travel
   there. `signal` is the very `AbortSignal` the unit's work callback is handed,

package/dist/index.cjs

@@ -613,15 +613,43 @@ const start = (module, options = {}) => {
 			runtimeName = runtime.name;
 			healthChecks = ctx.get(HealthChecks);
 			const runtimeCtx = ctx;
-			const unit = options.unit;
 			const run = (meta, work) => registry.run(meta, (signal) => {
-				if (unit === void 0) return work(runtimeCtx, signal);
-				const fork = _btravstack_di.Module.forkScope;
-				return fork(ctx, unit, (forked) => (0, unthrown.fromSafePromise)((async () => await work(forked, signal))()).flatMap((result) => result), { onTeardownError: (port, cause) => emit({
-					type: "teardownError",
-					port,
-					cause
-				}) });
+				const settled = Promise.withResolvers();
+				let closing;
+				let hasSettled = false;
+				const fork = (module, seed) => {
+					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) => {
+						ready.resolve(forked);
+						return (0, unthrown.fromSafePromise)(settled.promise);
+					}, {
+						seed,
+						onTeardownError: (port, cause) => emit({
+							type: "teardownError",
+							port,
+							cause
+						})
+					}).recoverDefect((cause) => {
+						ready.reject(cause);
+						return (0, unthrown.Ok)();
+					}).get();
+					return (0, unthrown.fromSafePromise)(ready.promise);
+				};
+				const outcome = (async () => {
+					try {
+						return await work({
+							ctx: runtimeCtx,
+							fork
+						}, signal);
+					} finally {
+						hasSettled = true;
+						settled.resolve();
+						if (closing !== void 0) await closing;
+					}
+				})();
+				return (0, unthrown.fromSafePromise)(outcome).flatMap((result) => result);
 			});
 			const host = {
 				ctx: runtimeCtx,

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { AsyncResult, Result } from "unthrown";
-import { AnyPort, Context, Module, PortClass, PortInstance, Scope, ServiceOf } from "@btravstack/di";
+import { AnyPort, Context, DependencyGate, Module, PortClass, PortInstance, Scope, SeedEntry, ServiceOf } from "@btravstack/di";
 import { Env, Environment } from "@btravstack/config";
 //#region src/instrumentation.d.ts
 /**
@@ -372,11 +372,28 @@ declare class RuntimeStartFailed extends RuntimeStartFailed_base<{
  * `UnitMeta.id` must be unique per unit unless a `traceId` is supplied — see
  * {@link UnitMeta}.
  *
- * With a `StartOptions.unit` module in play, `work` runs only once the fork is
- * built. A runtime that subscribes to an event from inside `work` must first
- * check whether it has already fired.
+ * A runtime forks the unit's scope itself, through `UnitHost.fork`, at the
+ * moment it holds the unit's input; the kernel closes that scope when the
+ * unit settles, after the response is flushed. Work that subscribes to an
+ * event after a `fork` must first check whether it already fired.
  */
-type RunUnit<Resolves extends AnyPort> = <T, E>(meta: UnitMeta, work: (ctx: Context<InstanceType<Resolves>>, signal: AbortSignal) => ReturnType<UnitWork<T, E>>) => AsyncResult<T, E>;
+type RunUnit<Resolves extends AnyPort> = <T, E>(meta: UnitMeta, work: (unit: UnitHost<Resolves>, signal: AbortSignal) => ReturnType<UnitWork<T, E>>) => AsyncResult<T, E>;
+/**
+ * What the kernel hands a unit's work: the application context, and the one
+ * way to open the unit's own scope.
+ *
+ * `fork` builds `module` over the application context plus `seed` and hands
+ * the forked context back. The scope is torn down when the unit closes —
+ * inside the registry's unit, so the unit is not counted closed until its
+ * finalisers have run, and inside the unit's ambient record, so a teardown
+ * log line carries the unit's ids. A construction failure rides the unit's
+ * defect path. A unit forks once; a second call is a defect, and so is a call
+ * made after the unit has settled — nothing awaits that scope's teardown.
+ */
+type UnitHost<Resolves extends AnyPort> = {
+  readonly ctx: Context<InstanceType<Resolves>>;
+  readonly fork: <UnitX, N, Seeded extends AnyPort = never>(module: Module<UnitX, never, N> & DependencyGate<Exclude<N, InstanceType<Resolves> | InstanceType<Seeded> | Scope>>, seed: readonly SeedEntry<Seeded>[]) => AsyncResult<Context<InstanceType<Resolves> | UnitX | InstanceType<Seeded>>, never>;
+};
 /**
  * What a runtime is handed at `start`: the application services **and** the
  * kernel's {@link RunUnit}. Handing it a bare `Context` would leave every
@@ -388,8 +405,8 @@ type RunUnit<Resolves extends AnyPort> = <T, E>(meta: UnitMeta, work: (ctx: Cont
  * {@link RunUnit}), and `UnitMeta.id` must be unique per unit unless a
  * `traceId` is supplied (see {@link UnitMeta}).
  *
- * `ctx` is the **application** context: a port a `StartOptions.unit` module
- * provides exists only while a unit is open, so a runtime naming it in
+ * `ctx` is the **application** context: a port a unit's `fork` module provides
+ * exists only in the `Context` `fork` hands back, so a runtime naming it in
  * `resolves` is rejected at `start`'s call site.
  */
 type RuntimeHost<Resolves extends AnyPort> = {
@@ -430,8 +447,12 @@ declare const RuntimePort: PortClass<"Runtime">;
 type RuntimeInstance = InstanceType<PortClass<"Runtime">>;
 /** The `Runtime<Resolves, Info>` a module exports, or `never` when it exports none. */
 type RuntimeOf<X> = ServiceOf<Extract<X, RuntimeInstance>>;
-type RuntimeResolvesOf<X> = RuntimeOf<X> extends Runtime<infer Resolves, unknown> ? Resolves : never;
-type RuntimeInfoOf<X> = RuntimeOf<X> extends Runtime<AnyPort, infer Info> ? Info : never;
+type RuntimeResolvesOf<X> = RuntimeOf<X> extends {
+  readonly resolves: readonly (infer Resolves extends AnyPort)[];
+} ? Resolves : never;
+type RuntimeInfoOf<X> = RuntimeOf<X> extends {
+  readonly start: (host: never) => AsyncResult<Serving<infer Info>, RuntimeStartFailed>;
+} ? Info : never;
 /**
  * The trace id inside a W3C `traceparent` header, and nothing else of it.
  *
@@ -555,26 +576,13 @@ type ExitReport = {
   readonly teardownErrors: readonly TeardownError[];
   readonly uptimeMs: number;
 };
-type StartOptions<UnitX = never, UnitNeeds = never> = {
+type StartOptions = {
   /**
    * The environment the graph is configured from, provided to it as the `Env`
    * port and read for the kernel's own `PROBE_PORT`. Defaults to
    * `process.env`.
    */
   readonly env?: Environment;
-  /**
-   * A module forked around **every unit** — a unit being one bounded piece of
-   * work, whatever the transport calls it: an HTTP request, a Temporal
-   * activity, an AMQP delivery. Built as the unit opens, torn down as it
-   * closes — while the unit's ambient record is still open — reading anything
-   * the application context carries.
-   *
-   * A failing unit finaliser is reported as a `teardownError` event and never
-   * in `ExitReport.teardownErrors`. With this option the unit's work runs only
-   * once the fork is built, so a runtime that subscribes to an event from
-   * inside its work must be ready for it to have already fired.
-   */
-  readonly unit?: Module<UnitX, never, UnitNeeds>;
   readonly clock?: Clock;
   readonly signals?: boolean;
   /**
@@ -627,15 +635,18 @@ type RunningApp<E, Info = never> = {
 /**
  * The phantom marker `start`, `runMain` and `Boot` all intersect onto their
  * `module` parameter: `unknown` — and invisible — when nothing the module
- * needs is unprovided, it exports a runtime, its exports cover what that
- * runtime resolves and they cover the unit module's needs; a diagnostic
- * otherwise, printed at the call site as the parameter type the argument did
- * not match.
+ * needs is unprovided, it exports a runtime and its exports cover what that
+ * runtime resolves; a diagnostic otherwise, printed at the call site as the
+ * parameter type the argument did not match.
  *
  * `unknown` is the satisfied arm because intersecting it leaves the module
  * type untouched. A runtime's `resolves` is checked against the module's
- * exports only, never the unit module's: `RuntimeHost.ctx` is the application
- * context, so a unit-only port would resolve to nothing there.
+ * exports only: `RuntimeHost.ctx` is the application context, so a port only
+ * a `fork` provides would resolve to nothing there. A `fork`'s own needs are
+ * not this marker's business at all — a `fork` module is forked over the
+ * application context, so its needs are exactly what a starter's own `needs`
+ * channel already asks the composition root to supply, and di's ordinary
+ * `UNSATISFIED DEPENDENCIES` gate is what refuses a root that does not.
  *
  * **Unmet needs are checked FIRST, and answered in di's own words rather than
  * a sentence of the kernel's.** A root that forgot `provides: [router]` used
@@ -654,10 +665,10 @@ type RunningApp<E, Info = never> = {
  * name is reached.
  */
 type PortIdOf<P> = P extends PortInstance<infer Id, infer _Service> ? Id : P;
-type StartGate<X, UnitNeeds = never, N = never> = [Exclude<N, Scope | Env>] extends [never] ? [Extract<X, RuntimeInstance>] extends [never] ? "NO RUNTIME — the module exports no port declared over RuntimePort" : [InstanceType<RuntimeResolvesOf<X>>] extends [X] ? [Exclude<UnitNeeds, X | Scope | Env>] extends [never] ? unknown : "UNSATISFIED UNIT NEEDS — the unit module needs a port the module does not export" : "UNSATISFIED RUNTIME PORTS — the runtime resolves a port the module does not export" : {
+type StartGate<X, N = never> = [Exclude<N, Scope | Env>] extends [never] ? [Extract<X, RuntimeInstance>] extends [never] ? "NO RUNTIME — the module exports no port declared over RuntimePort" : [InstanceType<RuntimeResolvesOf<X>>] extends [X] ? unknown : "UNSATISFIED RUNTIME PORTS — the runtime resolves a port the module does not export" : {
   readonly "UNSATISFIED DEPENDENCIES — nothing provides": PortIdOf<Exclude<N, Scope | Env>>;
 };
-declare const start: <X, E, N, UnitX = never, UnitNeeds = never>(module: Module<X, E, N> & StartGate<X, UnitNeeds, N>, options?: StartOptions<UnitX, UnitNeeds>) => RunningApp<E, RuntimeInfoOf<X>>;
+declare const start: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>, options?: StartOptions) => RunningApp<E, RuntimeInfoOf<X>>;
 //#endregion
 //#region src/run-main.d.ts
 /**
@@ -692,6 +703,6 @@ declare const start: <X, E, N, UnitX = never, UnitNeeds = never>(module: Module<
  * await runMain(OrderApi);
  * ```
  */
-declare const runMain: <X, E, N, UnitX = never, UnitNeeds = never>(module: Module<X, E, N> & StartGate<X, UnitNeeds, N>, options?: StartOptions<UnitX, UnitNeeds>, exit?: (code: number) => void) => Promise<void>;
+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, type Clock, type ComponentHealth, type Counter, type DrainReport, type EventSink, type ExitReport, type HealthCheck, HealthCheckFailed, HealthChecks, type HealthReport, type Histogram, type InstrumentationLoader, Instrumentations, type KernelEvent, LEVELS, type Level, Logger, type LoggerService, Meter, type MeterService, Observers, type Operation, type Phase, type RunUnit, type RunningApp, type Runtime, type RuntimeHost, type RuntimeInfoOf, RuntimePort, RuntimeStartFailed, SPAN_STATUS, type Serving, type Settle, type Settled, type Span, type SpanStatusCode, type StartGate, type StartOptions, type TeardownError, Tracer, type TracerService, type UnitMeta, type UnitRecord, type UnitRegistry, type UnitWork, currentUnit, noObserver, observe, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock, traceIdOfTraceparent };
+export { type Attributes, type Clock, type ComponentHealth, type Counter, type DrainReport, type EventSink, type ExitReport, type HealthCheck, HealthCheckFailed, HealthChecks, type HealthReport, type Histogram, type InstrumentationLoader, Instrumentations, type KernelEvent, LEVELS, type Level, Logger, type LoggerService, Meter, type MeterService, Observers, type Operation, type Phase, type RunUnit, type RunningApp, type Runtime, type RuntimeHost, type RuntimeInfoOf, RuntimePort, RuntimeStartFailed, SPAN_STATUS, type Serving, type Settle, type Settled, type Span, type SpanStatusCode, type StartGate, type StartOptions, type TeardownError, Tracer, type TracerService, type UnitHost, type UnitMeta, type UnitRecord, type UnitRegistry, type UnitWork, currentUnit, noObserver, observe, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock, traceIdOfTraceparent };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AnyPort, Context, Module, PortClass, PortInstance, Scope, ServiceOf } from "@btravstack/di";
+import { AnyPort, Context, DependencyGate, Module, PortClass, PortInstance, Scope, SeedEntry, ServiceOf } from "@btravstack/di";
 import { AsyncResult, Result } from "unthrown";
 import { Env, Environment } from "@btravstack/config";
 //#region src/instrumentation.d.ts
@@ -372,11 +372,28 @@ declare class RuntimeStartFailed extends RuntimeStartFailed_base<{
  * `UnitMeta.id` must be unique per unit unless a `traceId` is supplied — see
  * {@link UnitMeta}.
  *
- * With a `StartOptions.unit` module in play, `work` runs only once the fork is
- * built. A runtime that subscribes to an event from inside `work` must first
- * check whether it has already fired.
+ * A runtime forks the unit's scope itself, through `UnitHost.fork`, at the
+ * moment it holds the unit's input; the kernel closes that scope when the
+ * unit settles, after the response is flushed. Work that subscribes to an
+ * event after a `fork` must first check whether it already fired.
  */
-type RunUnit<Resolves extends AnyPort> = <T, E>(meta: UnitMeta, work: (ctx: Context<InstanceType<Resolves>>, signal: AbortSignal) => ReturnType<UnitWork<T, E>>) => AsyncResult<T, E>;
+type RunUnit<Resolves extends AnyPort> = <T, E>(meta: UnitMeta, work: (unit: UnitHost<Resolves>, signal: AbortSignal) => ReturnType<UnitWork<T, E>>) => AsyncResult<T, E>;
+/**
+ * What the kernel hands a unit's work: the application context, and the one
+ * way to open the unit's own scope.
+ *
+ * `fork` builds `module` over the application context plus `seed` and hands
+ * the forked context back. The scope is torn down when the unit closes —
+ * inside the registry's unit, so the unit is not counted closed until its
+ * finalisers have run, and inside the unit's ambient record, so a teardown
+ * log line carries the unit's ids. A construction failure rides the unit's
+ * defect path. A unit forks once; a second call is a defect, and so is a call
+ * made after the unit has settled — nothing awaits that scope's teardown.
+ */
+type UnitHost<Resolves extends AnyPort> = {
+  readonly ctx: Context<InstanceType<Resolves>>;
+  readonly fork: <UnitX, N, Seeded extends AnyPort = never>(module: Module<UnitX, never, N> & DependencyGate<Exclude<N, InstanceType<Resolves> | InstanceType<Seeded> | Scope>>, seed: readonly SeedEntry<Seeded>[]) => AsyncResult<Context<InstanceType<Resolves> | UnitX | InstanceType<Seeded>>, never>;
+};
 /**
  * What a runtime is handed at `start`: the application services **and** the
  * kernel's {@link RunUnit}. Handing it a bare `Context` would leave every
@@ -388,8 +405,8 @@ type RunUnit<Resolves extends AnyPort> = <T, E>(meta: UnitMeta, work: (ctx: Cont
  * {@link RunUnit}), and `UnitMeta.id` must be unique per unit unless a
  * `traceId` is supplied (see {@link UnitMeta}).
  *
- * `ctx` is the **application** context: a port a `StartOptions.unit` module
- * provides exists only while a unit is open, so a runtime naming it in
+ * `ctx` is the **application** context: a port a unit's `fork` module provides
+ * exists only in the `Context` `fork` hands back, so a runtime naming it in
  * `resolves` is rejected at `start`'s call site.
  */
 type RuntimeHost<Resolves extends AnyPort> = {
@@ -430,8 +447,12 @@ declare const RuntimePort: PortClass<"Runtime">;
 type RuntimeInstance = InstanceType<PortClass<"Runtime">>;
 /** The `Runtime<Resolves, Info>` a module exports, or `never` when it exports none. */
 type RuntimeOf<X> = ServiceOf<Extract<X, RuntimeInstance>>;
-type RuntimeResolvesOf<X> = RuntimeOf<X> extends Runtime<infer Resolves, unknown> ? Resolves : never;
-type RuntimeInfoOf<X> = RuntimeOf<X> extends Runtime<AnyPort, infer Info> ? Info : never;
+type RuntimeResolvesOf<X> = RuntimeOf<X> extends {
+  readonly resolves: readonly (infer Resolves extends AnyPort)[];
+} ? Resolves : never;
+type RuntimeInfoOf<X> = RuntimeOf<X> extends {
+  readonly start: (host: never) => AsyncResult<Serving<infer Info>, RuntimeStartFailed>;
+} ? Info : never;
 /**
  * The trace id inside a W3C `traceparent` header, and nothing else of it.
  *
@@ -555,26 +576,13 @@ type ExitReport = {
   readonly teardownErrors: readonly TeardownError[];
   readonly uptimeMs: number;
 };
-type StartOptions<UnitX = never, UnitNeeds = never> = {
+type StartOptions = {
   /**
    * The environment the graph is configured from, provided to it as the `Env`
    * port and read for the kernel's own `PROBE_PORT`. Defaults to
    * `process.env`.
    */
   readonly env?: Environment;
-  /**
-   * A module forked around **every unit** — a unit being one bounded piece of
-   * work, whatever the transport calls it: an HTTP request, a Temporal
-   * activity, an AMQP delivery. Built as the unit opens, torn down as it
-   * closes — while the unit's ambient record is still open — reading anything
-   * the application context carries.
-   *
-   * A failing unit finaliser is reported as a `teardownError` event and never
-   * in `ExitReport.teardownErrors`. With this option the unit's work runs only
-   * once the fork is built, so a runtime that subscribes to an event from
-   * inside its work must be ready for it to have already fired.
-   */
-  readonly unit?: Module<UnitX, never, UnitNeeds>;
   readonly clock?: Clock;
   readonly signals?: boolean;
   /**
@@ -627,15 +635,18 @@ type RunningApp<E, Info = never> = {
 /**
  * The phantom marker `start`, `runMain` and `Boot` all intersect onto their
  * `module` parameter: `unknown` — and invisible — when nothing the module
- * needs is unprovided, it exports a runtime, its exports cover what that
- * runtime resolves and they cover the unit module's needs; a diagnostic
- * otherwise, printed at the call site as the parameter type the argument did
- * not match.
+ * needs is unprovided, it exports a runtime and its exports cover what that
+ * runtime resolves; a diagnostic otherwise, printed at the call site as the
+ * parameter type the argument did not match.
  *
  * `unknown` is the satisfied arm because intersecting it leaves the module
  * type untouched. A runtime's `resolves` is checked against the module's
- * exports only, never the unit module's: `RuntimeHost.ctx` is the application
- * context, so a unit-only port would resolve to nothing there.
+ * exports only: `RuntimeHost.ctx` is the application context, so a port only
+ * a `fork` provides would resolve to nothing there. A `fork`'s own needs are
+ * not this marker's business at all — a `fork` module is forked over the
+ * application context, so its needs are exactly what a starter's own `needs`
+ * channel already asks the composition root to supply, and di's ordinary
+ * `UNSATISFIED DEPENDENCIES` gate is what refuses a root that does not.
  *
  * **Unmet needs are checked FIRST, and answered in di's own words rather than
  * a sentence of the kernel's.** A root that forgot `provides: [router]` used
@@ -654,10 +665,10 @@ type RunningApp<E, Info = never> = {
  * name is reached.
  */
 type PortIdOf<P> = P extends PortInstance<infer Id, infer _Service> ? Id : P;
-type StartGate<X, UnitNeeds = never, N = never> = [Exclude<N, Scope | Env>] extends [never] ? [Extract<X, RuntimeInstance>] extends [never] ? "NO RUNTIME — the module exports no port declared over RuntimePort" : [InstanceType<RuntimeResolvesOf<X>>] extends [X] ? [Exclude<UnitNeeds, X | Scope | Env>] extends [never] ? unknown : "UNSATISFIED UNIT NEEDS — the unit module needs a port the module does not export" : "UNSATISFIED RUNTIME PORTS — the runtime resolves a port the module does not export" : {
+type StartGate<X, N = never> = [Exclude<N, Scope | Env>] extends [never] ? [Extract<X, RuntimeInstance>] extends [never] ? "NO RUNTIME — the module exports no port declared over RuntimePort" : [InstanceType<RuntimeResolvesOf<X>>] extends [X] ? unknown : "UNSATISFIED RUNTIME PORTS — the runtime resolves a port the module does not export" : {
   readonly "UNSATISFIED DEPENDENCIES — nothing provides": PortIdOf<Exclude<N, Scope | Env>>;
 };
-declare const start: <X, E, N, UnitX = never, UnitNeeds = never>(module: Module<X, E, N> & StartGate<X, UnitNeeds, N>, options?: StartOptions<UnitX, UnitNeeds>) => RunningApp<E, RuntimeInfoOf<X>>;
+declare const start: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>, options?: StartOptions) => RunningApp<E, RuntimeInfoOf<X>>;
 //#endregion
 //#region src/run-main.d.ts
 /**
@@ -692,6 +703,6 @@ declare const start: <X, E, N, UnitX = never, UnitNeeds = never>(module: Module<
  * await runMain(OrderApi);
  * ```
  */
-declare const runMain: <X, E, N, UnitX = never, UnitNeeds = never>(module: Module<X, E, N> & StartGate<X, UnitNeeds, N>, options?: StartOptions<UnitX, UnitNeeds>, exit?: (code: number) => void) => Promise<void>;
+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, type Clock, type ComponentHealth, type Counter, type DrainReport, type EventSink, type ExitReport, type HealthCheck, HealthCheckFailed, HealthChecks, type HealthReport, type Histogram, type InstrumentationLoader, Instrumentations, type KernelEvent, LEVELS, type Level, Logger, type LoggerService, Meter, type MeterService, Observers, type Operation, type Phase, type RunUnit, type RunningApp, type Runtime, type RuntimeHost, type RuntimeInfoOf, RuntimePort, RuntimeStartFailed, SPAN_STATUS, type Serving, type Settle, type Settled, type Span, type SpanStatusCode, type StartGate, type StartOptions, type TeardownError, Tracer, type TracerService, type UnitMeta, type UnitRecord, type UnitRegistry, type UnitWork, currentUnit, noObserver, observe, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock, traceIdOfTraceparent };
+export { type Attributes, type Clock, type ComponentHealth, type Counter, type DrainReport, type EventSink, type ExitReport, type HealthCheck, HealthCheckFailed, HealthChecks, type HealthReport, type Histogram, type InstrumentationLoader, Instrumentations, type KernelEvent, LEVELS, type Level, Logger, type LoggerService, Meter, type MeterService, Observers, type Operation, type Phase, type RunUnit, type RunningApp, type Runtime, type RuntimeHost, type RuntimeInfoOf, RuntimePort, RuntimeStartFailed, SPAN_STATUS, type Serving, type Settle, type Settled, type Span, type SpanStatusCode, type StartGate, type StartOptions, type TeardownError, Tracer, type TracerService, type UnitHost, type UnitMeta, type UnitRecord, type UnitRegistry, type UnitWork, currentUnit, noObserver, observe, releasedBy, runHealthChecks, runMain, start, stderrSink, systemClock, traceIdOfTraceparent };

package/dist/index.mjs

@@ -612,15 +612,43 @@ const start = (module, options = {}) => {
 			runtimeName = runtime.name;
 			healthChecks = ctx.get(HealthChecks);
 			const runtimeCtx = ctx;
-			const unit = options.unit;
 			const run = (meta, work) => registry.run(meta, (signal) => {
-				if (unit === void 0) return work(runtimeCtx, signal);
-				const fork = Module.forkScope;
-				return fork(ctx, unit, (forked) => fromSafePromise((async () => await work(forked, signal))()).flatMap((result) => result), { onTeardownError: (port, cause) => emit({
-					type: "teardownError",
-					port,
-					cause
-				}) });
+				const settled = Promise.withResolvers();
+				let closing;
+				let hasSettled = false;
+				const fork = (module, seed) => {
+					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) => {
+						ready.resolve(forked);
+						return fromSafePromise(settled.promise);
+					}, {
+						seed,
+						onTeardownError: (port, cause) => emit({
+							type: "teardownError",
+							port,
+							cause
+						})
+					}).recoverDefect((cause) => {
+						ready.reject(cause);
+						return Ok();
+					}).get();
+					return fromSafePromise(ready.promise);
+				};
+				const outcome = (async () => {
+					try {
+						return await work({
+							ctx: runtimeCtx,
+							fork
+						}, signal);
+					} finally {
+						hasSettled = true;
+						settled.resolve();
+						if (closing !== void 0) await closing;
+					}
+				})();
+				return fromSafePromise(outcome).flatMap((result) => result);
 			});
 			const host = {
 				ctx: runtimeCtx,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/core",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "The application kernel: boot a di module into a running process, and stop it without losing work",
   "keywords": [
     "application",
@@ -45,7 +45,7 @@
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@btravstack/tsconfig": "0.2.0",
+    "@btravstack/tsconfig": "0.4.0",
     "@types/node": "26.4.0",
     "@unthrown/vitest": "5.7.0",
     "@vitest/coverage-v8": "4.1.11",
@@ -53,13 +53,13 @@
     "typescript": "7.0.2",
     "unthrown": "5.7.0",
     "vitest": "4.1.11",
-    "@btravstack/config": "0.12.0",
-    "@btravstack/di": "0.12.0"
+    "@btravstack/config": "0.13.0",
+    "@btravstack/di": "0.13.0"
   },
   "peerDependencies": {
     "unthrown": "^5.0.0",
-    "@btravstack/config": "^0.12.0",
-    "@btravstack/di": "^0.12.0"
+    "@btravstack/config": "^0.13.0",
+    "@btravstack/di": "^0.13.0"
   },
   "engines": {
     "node": ">=22"