@btravstack/core 0.32.0 → 0.33.0

package/dist/index.cjs

@@ -455,6 +455,36 @@ const installUncaughtHandlers = (onUncaught) => {
 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));
+/** Every port `module`'s tree provides, by its class. */
+const providedPorts = (module) => [...module.imports.flatMap(providedPorts), ...module.provides.map((provider) => provider.port)];
+/**
+* A check, per unit module, that it provides no port the application scope
+* already provides. A fork builds its whole module tree per unit, so such a
+* provider would shadow the application's instance with a fresh one per unit,
+* released per unit — the application's configuration re-parsed, its clients
+* reopened. A unit's member of the SAME set port is the one exemption, since
+* the fork appends it to the application's members; a set port meeting an
+* ordinary one, or two classes sharing an id, is refused like any other.
+*
+* Answers the refusal rather than throwing it, so the boot can throw it and a
+* fork can reject with it. A module is walked once, however often it forks.
+*/
+const rebuildGuard = (runtime, application) => {
+	const owned = new Map(providedPorts(application).map((port) => [port.portId, port]));
+	const clean = /* @__PURE__ */ new WeakSet();
+	return (module) => {
+		if (clean.has(module)) return void 0;
+		const rebuilt = providedPorts(module).find((port) => {
+			const owner = owned.get(port.portId);
+			return owner !== void 0 && !(owner === port && port.many === true);
+		});
+		if (rebuilt === void 0) {
+			clean.add(module);
+			return;
+		}
+		return /* @__PURE__ */ new Error(`[core] unit module "${module.name}" of runtime "${runtime}" provides port ${JSON.stringify(rebuilt.portId)}, which the application scope already provides — a unit would rebuild it per unit; remove it from the unit module and let the unit read the application's`);
+	};
+};
 /**
 * 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
@@ -804,6 +834,11 @@ const start = (module, options = {}) => {
 		runtimeName = runtime.name;
 		healthChecks = ctx.get(HealthChecks);
 		const runtimeCtx = ctx;
+		const rebuilt = rebuildGuard(runtime.name, root);
+		for (const unit of Object.values(runtime.units ?? {})) {
+			const refusal = unit === void 0 ? void 0 : rebuilt(unit);
+			if (refusal !== void 0) throw refusal;
+		}
 		const substitutes = unitSubstitutes(runtime.name, runtime.units ?? {}, ctx.get(UnitOverrides));
 		const run = (meta, work) => registry.run(meta, (signal) => {
 			const settled = Promise.withResolvers();
@@ -812,6 +847,8 @@ const start = (module, options = {}) => {
 			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 refusal = rebuilt(module);
+				if (refusal !== void 0) return (0, unthrown.fromSafePromise)(Promise.reject(refusal));
 				const ready = Promise.withResolvers();
 				closing = _btravstack_di.Module.forkScope(ctx, substitutes.get(module) ?? module, (forked) => {
 					ready.resolve(forked);
@@ -948,8 +985,7 @@ const awaitExit = async (app, exit) => {
 *
 * @example
 * ```ts
-* // `OrderApi` imports the application next to `http()` and exports
-* // `HttpRuntime`. `PORT`, `HOST` and `PROBE_PORT` are read inside the graph.
+* // `OrderApi` is an `HttpModule`, which exports `HttpRuntime`. `PORT`, `HOST` and `PROBE_PORT` are read inside the graph.
 * await runMain(OrderApi);
 * ```
 */

package/dist/index.d.cts

@@ -418,20 +418,25 @@ 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.
+ * fork seed discharges. `Env` is replaced by a refusal nothing provides, so
+ * `start` names it: a unit forks per unit of work, so configuration read there
+ * would be parsed per request rather than once at boot. Inline rather than a
+ * named alias, so a consumer's declaration emit never has to name it.
  */
-type UnitNeedsOf<Unit, Seeded = never> = Unit extends Module<never, never, infer N> ? Exclude<N, Scope | Seeded> : never;
+type UnitNeedsOf<Unit, Seeded = never> = Unit extends Module<never, never, infer N> ? Exclude<N, Scope | Seeded | Env> | ([Extract<N, Env>] extends [never] ? never : PortInstance<"UNIT READS CONFIGURATION — Env is application-scoped: parse it in a root provider and inject the result", never>) : 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]>>; };
+type UnprovidedBy<Unit, Declared> = [Unit] extends [never] ? NonNullable<Declared> : Unit extends unknown ? Exclude<NonNullable<Declared>, UnitExportsOf<Unit>> : never;
 /**
  * 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.
+ * whose pieces declare no `unit:` is gated on nothing. A union of modules is
+ * checked module by module.
  */
-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>>;
+type UnitGate<Unit, Declared> = [UnprovidedBy<Unit, Declared>] extends [never] ? unknown : {
+  readonly "UNIT DOES NOT PROVIDE — a piece injects a port the bound unit module does not export": UnprovidedBy<Unit, Declared>;
 };
 /**
  * One `(helpers, input)` implementation with its piece's declared record put on
@@ -942,8 +947,7 @@ export declare const start: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>,
  *
  * @example
  * ```ts
- * // `OrderApi` imports the application next to `http()` and exports
- * // `HttpRuntime`. `PORT`, `HOST` and `PROBE_PORT` are read inside the graph.
+ * // `OrderApi` is an `HttpModule`, which exports `HttpRuntime`. `PORT`, `HOST` and `PROBE_PORT` are read inside the graph.
  * await runMain(OrderApi);
  * ```
  */

package/dist/index.d.mts

@@ -418,20 +418,25 @@ 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.
+ * fork seed discharges. `Env` is replaced by a refusal nothing provides, so
+ * `start` names it: a unit forks per unit of work, so configuration read there
+ * would be parsed per request rather than once at boot. Inline rather than a
+ * named alias, so a consumer's declaration emit never has to name it.
  */
-type UnitNeedsOf<Unit, Seeded = never> = Unit extends Module<never, never, infer N> ? Exclude<N, Scope | Seeded> : never;
+type UnitNeedsOf<Unit, Seeded = never> = Unit extends Module<never, never, infer N> ? Exclude<N, Scope | Seeded | Env> | ([Extract<N, Env>] extends [never] ? never : PortInstance<"UNIT READS CONFIGURATION — Env is application-scoped: parse it in a root provider and inject the result", never>) : 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]>>; };
+type UnprovidedBy<Unit, Declared> = [Unit] extends [never] ? NonNullable<Declared> : Unit extends unknown ? Exclude<NonNullable<Declared>, UnitExportsOf<Unit>> : never;
 /**
  * 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.
+ * whose pieces declare no `unit:` is gated on nothing. A union of modules is
+ * checked module by module.
  */
-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>>;
+type UnitGate<Unit, Declared> = [UnprovidedBy<Unit, Declared>] extends [never] ? unknown : {
+  readonly "UNIT DOES NOT PROVIDE — a piece injects a port the bound unit module does not export": UnprovidedBy<Unit, Declared>;
 };
 /**
  * One `(helpers, input)` implementation with its piece's declared record put on
@@ -942,8 +947,7 @@ export declare const start: <X, E, N>(module: Module<X, E, N> & StartGate<X, N>,
  *
  * @example
  * ```ts
- * // `OrderApi` imports the application next to `http()` and exports
- * // `HttpRuntime`. `PORT`, `HOST` and `PROBE_PORT` are read inside the graph.
+ * // `OrderApi` is an `HttpModule`, which exports `HttpRuntime`. `PORT`, `HOST` and `PROBE_PORT` are read inside the graph.
  * await runMain(OrderApi);
  * ```
  */

package/dist/index.mjs

@@ -454,6 +454,36 @@ const installUncaughtHandlers = (onUncaught) => {
 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));
+/** Every port `module`'s tree provides, by its class. */
+const providedPorts = (module) => [...module.imports.flatMap(providedPorts), ...module.provides.map((provider) => provider.port)];
+/**
+* A check, per unit module, that it provides no port the application scope
+* already provides. A fork builds its whole module tree per unit, so such a
+* provider would shadow the application's instance with a fresh one per unit,
+* released per unit — the application's configuration re-parsed, its clients
+* reopened. A unit's member of the SAME set port is the one exemption, since
+* the fork appends it to the application's members; a set port meeting an
+* ordinary one, or two classes sharing an id, is refused like any other.
+*
+* Answers the refusal rather than throwing it, so the boot can throw it and a
+* fork can reject with it. A module is walked once, however often it forks.
+*/
+const rebuildGuard = (runtime, application) => {
+	const owned = new Map(providedPorts(application).map((port) => [port.portId, port]));
+	const clean = /* @__PURE__ */ new WeakSet();
+	return (module) => {
+		if (clean.has(module)) return void 0;
+		const rebuilt = providedPorts(module).find((port) => {
+			const owner = owned.get(port.portId);
+			return owner !== void 0 && !(owner === port && port.many === true);
+		});
+		if (rebuilt === void 0) {
+			clean.add(module);
+			return;
+		}
+		return /* @__PURE__ */ new Error(`[core] unit module "${module.name}" of runtime "${runtime}" provides port ${JSON.stringify(rebuilt.portId)}, which the application scope already provides — a unit would rebuild it per unit; remove it from the unit module and let the unit read the application's`);
+	};
+};
 /**
 * 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
@@ -803,6 +833,11 @@ const start = (module, options = {}) => {
 		runtimeName = runtime.name;
 		healthChecks = ctx.get(HealthChecks);
 		const runtimeCtx = ctx;
+		const rebuilt = rebuildGuard(runtime.name, root);
+		for (const unit of Object.values(runtime.units ?? {})) {
+			const refusal = unit === void 0 ? void 0 : rebuilt(unit);
+			if (refusal !== void 0) throw refusal;
+		}
 		const substitutes = unitSubstitutes(runtime.name, runtime.units ?? {}, ctx.get(UnitOverrides));
 		const run = (meta, work) => registry.run(meta, (signal) => {
 			const settled = Promise.withResolvers();
@@ -811,6 +846,8 @@ const start = (module, options = {}) => {
 			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 refusal = rebuilt(module);
+				if (refusal !== void 0) return fromSafePromise(Promise.reject(refusal));
 				const ready = Promise.withResolvers();
 				closing = Module.forkScope(ctx, substitutes.get(module) ?? module, (forked) => {
 					ready.resolve(forked);
@@ -947,8 +984,7 @@ const awaitExit = async (app, exit) => {
 *
 * @example
 * ```ts
-* // `OrderApi` imports the application next to `http()` and exports
-* // `HttpRuntime`. `PORT`, `HOST` and `PROBE_PORT` are read inside the graph.
+* // `OrderApi` is an `HttpModule`, which exports `HttpRuntime`. `PORT`, `HOST` and `PROBE_PORT` are read inside the graph.
 * await runMain(OrderApi);
 * ```
 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/core",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "The application kernel: boot a di module into a running process, and stop it without losing work",
   "keywords": [
     "application",
@@ -45,8 +45,8 @@
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@btravstack/config": "0.32.0",
-    "@btravstack/di": "0.32.0",
+    "@btravstack/config": "0.33.0",
+    "@btravstack/di": "0.33.0",
     "@btravstack/tsconfig": "0.4.0",
     "@stryker-mutator/core": "10.0.0",
     "@stryker-mutator/vitest-runner": "10.0.0",
@@ -60,8 +60,8 @@
     "vitest": "5.0.3"
   },
   "peerDependencies": {
-    "@btravstack/config": "^0.32.0",
-    "@btravstack/di": "^0.32.0",
+    "@btravstack/config": "^0.33.0",
+    "@btravstack/di": "^0.33.0",
     "unthrown": "^5.0.0"
   },
   "engines": {