@btravstack/core 0.10.0 → 0.11.0

package/README.md

@@ -132,7 +132,7 @@ is a module that exports no runtime port at all.
 - **A per-unit scope no handler manages** — pass a module as
   `StartOptions.unit` and the kernel forks it around every unit.
 - **An ambient record, not an ambient container** — `currentUnit()` reads
-  `{ unitId, traceId, tenantId, deadline, signal }`; services never travel
+  `{ unitId, traceId, tenantId, signal }`; services never travel
   there. `signal` is the very `AbortSignal` the unit's work callback is handed,
   so a runtime whose work is a library's `next()` — a Temporal activity, an
   AMQP delivery — can still honour the drain deadline.

package/dist/index.cjs

@@ -386,7 +386,6 @@ const createUnitRegistry = () => {
 				unitId: nextId(),
 				traceId: meta.traceId ?? meta.id,
 				tenantId: meta.tenantId,
-				deadline: meta.deadline,
 				signal: controller.signal
 			};
 			return (0, unthrown.fromSafePromise)(runWithUnit(record, async () => {

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { AsyncResult, Result } from "unthrown";
-import { AnyPort, Context, Module, PortClass, Scope, ServiceOf } from "@btravstack/di";
+import { AnyPort, Context, Module, PortClass, PortInstance, Scope, ServiceOf } from "@btravstack/di";
 import { Env, Environment } from "@btravstack/config";
 //#region src/instrumentation.d.ts
 /**
@@ -315,7 +315,6 @@ type UnitRecord = {
   readonly unitId: string;
   readonly traceId: string;
   readonly tenantId: string | undefined;
-  readonly deadline: number | undefined;
   readonly signal: AbortSignal;
 };
 declare const currentUnit: () => UnitRecord | undefined;
@@ -339,7 +338,6 @@ type UnitMeta = {
   readonly id: string;
   readonly traceId?: string;
   readonly tenantId?: string;
-  readonly deadline?: number;
 };
 type UnitWork<T, E> = (signal: AbortSignal) => AsyncResult<T, E> | Promise<Result<T, E>> | Result<T, E>;
 type UnitRegistry = {
@@ -600,18 +598,38 @@ type RunningApp<E, Info = never> = {
 };
 /**
  * The phantom marker `start`, `runMain` and `Boot` all intersect onto their
- * `module` parameter: `unknown` — and invisible — when the module exports a
- * runtime, its exports cover what that runtime resolves and they cover the
- * unit module's needs; one of three sentences otherwise, printed at the call
- * site as the parameter type the argument did not match.
+ * `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.
  *
  * `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.
+ *
+ * **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
+ * to be told `Type 'HttpRouterPort' is not assignable to type 'Scope'` — an
+ * internal phantom nobody has heard of — or, when the port was missing from
+ * `exports` too, `UNSATISFIED RUNTIME PORTS`, which is a correct diagnosis of
+ * the second mistake that reads as a wrong one of the first and steers the fix
+ * into the wrong list. It is the same defect `Module.build` reports, so it
+ * prints the same sentence and ends on the port that is missing.
+ */
+/**
+ * A port's declared id, which is what a marker names it by: an id is the short
+ * string the application wrote in `Port("…")`, where the port TYPE of a
+ * starter's own generic port — `AmqpHandlers` over a contract — expands to
+ * hundreds of characters of the caller's own schema and truncates before the
+ * name is reached.
  */
-type StartGate<X, UnitNeeds = 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";
-declare const start: <X, E, UnitX = never, UnitNeeds = never>(module: Module<X, E, Scope | Env> & StartGate<X, UnitNeeds>, options?: StartOptions<UnitX, UnitNeeds>) => RunningApp<E, RuntimeInfoOf<X>>;
+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" : {
+  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>>;
 //#endregion
 //#region src/run-main.d.ts
 /**
@@ -646,6 +664,6 @@ declare const start: <X, E, UnitX = never, UnitNeeds = never>(module: Module<X,
  * await runMain(OrderApi);
  * ```
  */
-declare const runMain: <X, E, UnitX = never, UnitNeeds = never>(module: Module<X, E, Scope | Env> & StartGate<X, UnitNeeds>, options?: StartOptions<UnitX, UnitNeeds>, exit?: (code: number) => void) => Promise<void>;
+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>;
 //#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 };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AnyPort, Context, Module, PortClass, Scope, ServiceOf } from "@btravstack/di";
+import { AnyPort, Context, Module, PortClass, PortInstance, Scope, ServiceOf } from "@btravstack/di";
 import { AsyncResult, Result } from "unthrown";
 import { Env, Environment } from "@btravstack/config";
 //#region src/instrumentation.d.ts
@@ -315,7 +315,6 @@ type UnitRecord = {
   readonly unitId: string;
   readonly traceId: string;
   readonly tenantId: string | undefined;
-  readonly deadline: number | undefined;
   readonly signal: AbortSignal;
 };
 declare const currentUnit: () => UnitRecord | undefined;
@@ -339,7 +338,6 @@ type UnitMeta = {
   readonly id: string;
   readonly traceId?: string;
   readonly tenantId?: string;
-  readonly deadline?: number;
 };
 type UnitWork<T, E> = (signal: AbortSignal) => AsyncResult<T, E> | Promise<Result<T, E>> | Result<T, E>;
 type UnitRegistry = {
@@ -600,18 +598,38 @@ type RunningApp<E, Info = never> = {
 };
 /**
  * The phantom marker `start`, `runMain` and `Boot` all intersect onto their
- * `module` parameter: `unknown` — and invisible — when the module exports a
- * runtime, its exports cover what that runtime resolves and they cover the
- * unit module's needs; one of three sentences otherwise, printed at the call
- * site as the parameter type the argument did not match.
+ * `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.
  *
  * `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.
+ *
+ * **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
+ * to be told `Type 'HttpRouterPort' is not assignable to type 'Scope'` — an
+ * internal phantom nobody has heard of — or, when the port was missing from
+ * `exports` too, `UNSATISFIED RUNTIME PORTS`, which is a correct diagnosis of
+ * the second mistake that reads as a wrong one of the first and steers the fix
+ * into the wrong list. It is the same defect `Module.build` reports, so it
+ * prints the same sentence and ends on the port that is missing.
+ */
+/**
+ * A port's declared id, which is what a marker names it by: an id is the short
+ * string the application wrote in `Port("…")`, where the port TYPE of a
+ * starter's own generic port — `AmqpHandlers` over a contract — expands to
+ * hundreds of characters of the caller's own schema and truncates before the
+ * name is reached.
  */
-type StartGate<X, UnitNeeds = 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";
-declare const start: <X, E, UnitX = never, UnitNeeds = never>(module: Module<X, E, Scope | Env> & StartGate<X, UnitNeeds>, options?: StartOptions<UnitX, UnitNeeds>) => RunningApp<E, RuntimeInfoOf<X>>;
+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" : {
+  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>>;
 //#endregion
 //#region src/run-main.d.ts
 /**
@@ -646,6 +664,6 @@ declare const start: <X, E, UnitX = never, UnitNeeds = never>(module: Module<X,
  * await runMain(OrderApi);
  * ```
  */
-declare const runMain: <X, E, UnitX = never, UnitNeeds = never>(module: Module<X, E, Scope | Env> & StartGate<X, UnitNeeds>, options?: StartOptions<UnitX, UnitNeeds>, exit?: (code: number) => void) => Promise<void>;
+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>;
 //#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 };

package/dist/index.mjs

@@ -385,7 +385,6 @@ const createUnitRegistry = () => {
 				unitId: nextId(),
 				traceId: meta.traceId ?? meta.id,
 				tenantId: meta.tenantId,
-				deadline: meta.deadline,
 				signal: controller.signal
 			};
 			return fromSafePromise(runWithUnit(record, async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@btravstack/core",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "The application kernel: boot a di module into a running process, and stop it without losing work",
   "keywords": [
     "application",
@@ -53,13 +53,13 @@
     "typescript": "7.0.2",
     "unthrown": "5.7.0",
     "vitest": "4.1.11",
-    "@btravstack/config": "0.10.0",
-    "@btravstack/di": "0.10.0"
+    "@btravstack/di": "0.11.0",
+    "@btravstack/config": "0.11.0"
   },
   "peerDependencies": {
     "unthrown": "^5.0.0",
-    "@btravstack/config": "^0.10.0",
-    "@btravstack/di": "^0.10.0"
+    "@btravstack/config": "^0.11.0",
+    "@btravstack/di": "^0.11.0"
   },
   "engines": {
     "node": ">=22"