bazis 0.99.6 → 0.100.1

package/core/kernel/LifecycleCoordinator.ts

@@ -3,7 +3,7 @@ import type { Token } from "../di";
 import { LIFECYCLE_HOOK } from "./lifecycleHooks";
 import { LOGGER } from "./logging/Logger";
 import type { LifecycleHook } from "./types";
-import { ShutdownTimeoutError } from "./errors";
+import { ShutdownTimeoutError, StartupFailuresError, type StartupFailure } from "./errors";
 import { awaitAbortable } from "./internal/awaitAbortable";
 import { resolveHostedServices, validateHostedServicePlan } from "../di/extensions/hosted-service";
 import { awaitShutdown } from "./internal/awaitShutdown";
@@ -21,11 +21,28 @@ interface LifecycleResolver {
  * the {@link Kernel}, which bounds the whole graceful-stop sequence.
  */
 export class LifecycleCoordinator {
-  private startingName?: string;
+  private readonly pending = new Set<string>();
+  private readonly timings: StartupBatchTiming[] = [];
+  private readonly failed: string[] = [];
 
-  /** The hosted service whose `start` is running now, for the startup timeout. */
+  /** Hosted services whose start failed, for the failure screen. */
+  public get failedServiceNames(): readonly string[] {
+    return this.failed;
+  }
+
+  /** The hosted services whose `start` is running now, for the startup timeout. */
   public get startingServiceName(): string | undefined {
-    return this.startingName;
+    return this.pending.size === 0 ? undefined : [...this.pending].join(", ");
+  }
+
+  /** The same as a list, for the waiting indicator of the startup screen. */
+  public get startingServiceNames(): readonly string[] {
+    return [...this.pending];
+  }
+
+  /** Wall time of every started batch, in start order. */
+  public get startTimings(): readonly StartupBatchTiming[] {
+    return this.timings;
   }
 
   private hooks: readonly LifecycleHook[] = [];
@@ -85,10 +102,17 @@ export class LifecycleCoordinator {
 
       const phases = groupByPhase(hosted);
       for (let phaseIndex = 0; phaseIndex < phases.length; phaseIndex += 1) {
-        const group = phases[phaseIndex] as HostedService[];
-        for (let index = 0; index < group.length; index += 1) {
-          const service = group[index] as HostedService;
-          this.startingName = service.diagnosticName ?? service.constructor?.name;
+        for (const batch of batchesOf(phases[phaseIndex] as HostedService[])) {
+          if (batch.length > 1) {
+            await this.startBatch(batch, signal);
+            continue;
+          }
+          // One service starts inline: a failed start reaches the rollback
+          // below before a late stop of an abandoned start is scheduled.
+          const service = batch[0] as HostedService;
+          const name = serviceName(service);
+          const startedAt = performance.now();
+          this.pending.add(name);
           const starting = Promise.resolve().then(() => {
             signal?.throwIfAborted();
             return service.start(signal);
@@ -96,6 +120,7 @@ export class LifecycleCoordinator {
           try {
             await awaitAbortable(starting, signal);
           } catch (error) {
+            this.failed.push(name);
             if (signal?.aborted) {
               // A legacy service may ignore the signal and finish after startup
               // has already been cancelled. Observe it and stop it immediately
@@ -103,9 +128,11 @@ export class LifecycleCoordinator {
               void starting.then(() => service.stop()).catch(() => undefined);
             }
             throw error;
+          } finally {
+            this.pending.delete(name);
+            this.timings.push(Object.freeze({ names: Object.freeze([name]), phase: service.phase ?? 0, ms: performance.now() - startedAt }));
           }
           this.started.push(service);
-          this.startingName = undefined;
         }
       }
       this.hostedCount = this.started.length;
@@ -129,6 +156,50 @@ export class LifecycleCoordinator {
     }
   }
 
+  /**
+   * Starts one service, or several `concurrentStart` services together. Every
+   * failure of the batch is reported at once: three unreachable connections
+   * are three problems on one screen, not three restarts.
+   */
+  private async startBatch(batch: readonly HostedService[], signal?: AbortSignal): Promise<void> {
+    const names = batch.map(serviceName);
+    for (const name of names) this.pending.add(name);
+    const startedAt = performance.now();
+    const results = await Promise.allSettled(batch.map((service) => this.startService(service, signal)));
+    for (const name of names) this.pending.delete(name);
+    this.timings.push(Object.freeze({ names: Object.freeze(names), phase: batch[0]?.phase ?? 0, ms: performance.now() - startedAt }));
+    const failures: StartupFailure[] = [];
+    results.forEach((result, index) => {
+      if (result.status === "fulfilled") this.started.push(batch[index] as HostedService);
+      else {
+        failures.push(Object.freeze({ name: names[index] as string, error: result.reason }));
+        this.failed.push(names[index] as string);
+      }
+    });
+    if (failures.length === 0) return;
+    // A timeout or a stop request aborts every pending start with one reason.
+    if (signal?.aborted || failures.length === 1) throw (failures[0] as StartupFailure).error;
+    throw new StartupFailuresError(failures);
+  }
+
+  private async startService(service: HostedService, signal?: AbortSignal): Promise<void> {
+    const starting = Promise.resolve().then(() => {
+      signal?.throwIfAborted();
+      return service.start(signal);
+    });
+    try {
+      await awaitAbortable(starting, signal);
+    } catch (error) {
+      if (signal?.aborted) {
+        // A legacy service may ignore the signal and finish after startup
+        // has already been cancelled. Observe it and stop it immediately
+        // so the late listener/connection cannot escape rollback.
+        void starting.then(() => service.stop()).catch(() => undefined);
+      }
+      throw error;
+    }
+  }
+
   private invokeHook(callback: () => void | Promise<void>, signal?: AbortSignal): Promise<void> {
     this.hookWork = Promise.resolve().then(() => {
       signal?.throwIfAborted();
@@ -206,6 +277,27 @@ export class LifecycleCoordinator {
   }
 }
 
+export interface StartupBatchTiming {
+  readonly names: readonly string[];
+  readonly phase: number;
+  readonly ms: number;
+}
+
+function serviceName(service: HostedService): string {
+  return service.diagnosticName ?? service.constructor?.name ?? "HostedService";
+}
+
+/** Neighbouring `concurrentStart` services start together; the rest one by one, in order. */
+function batchesOf(group: readonly HostedService[]): HostedService[][] {
+  const batches: HostedService[][] = [];
+  for (const service of group) {
+    const last = batches.at(-1);
+    if (service.concurrentStart === true && last !== undefined && last[0]?.concurrentStart === true) last.push(service);
+    else batches.push([service]);
+  }
+  return batches;
+}
+
 /** Groups by ascending `phase` (default 0), keeping registration order inside a group. */
 function groupByPhase(services: readonly HostedService[]): HostedService[][] {
   const byPhase = new Map<number, HostedService[]>();

package/core/kernel/config/ConfigRegistry.ts

@@ -2,6 +2,7 @@ import { DI, type ProviderDefinition } from "../../di";
 import { KernelError } from "../errors";
 import type { EnvironmentName } from "../types";
 import type { Configuration } from "./Configuration";
+import { ConfigValidationError } from "./ConfigValidationError";
 import { isConfigDefinition, type AppConfig, type ConfigDefinition, type ConfigInspection, type ConfigView, type ValidatableConfig } from "./defineConfig";
 
 /** One immutable set of resolved module configurations per kernel. */
@@ -29,6 +30,10 @@ export class ConfigRegistry {
         issues.push(error instanceof Error ? error.message : "Configuration validation failed.");
       }
     }
+    // Invalid keys of every config come as one error, so they are fixed in one pass.
+    if (errors.length > 1 && errors.every((error) => error instanceof ConfigValidationError)) {
+      throw new ConfigValidationError(environment, errors.flatMap((error) => (error as ConfigValidationError).issues));
+    }
     if (errors.length === 1) throw errors[0];
     if (errors.length > 1) throw new AggregateError(errors, `Configuration validation failed:\n${issues.join("\n")}`);
     this.providers = Object.freeze(providers);

package/core/kernel/config/ConfigValidationError.ts

@@ -0,0 +1,37 @@
+import { KernelError } from "../errors";
+
+export type ConfigIssueKind = "missing-secret" | "development-secret" | "number" | "boolean" | "string" | "enum" | "validator" | "conflict";
+
+/** One invalid configuration key, with what can change it. */
+export interface ConfigIssue {
+  /** Full key: `db.password`. */
+  readonly key: string;
+  /** Config prefix: `db`; empty for a config without one. */
+  readonly section: string;
+  readonly kind: ConfigIssueKind;
+  /** The problem without the key: `expected a finite number, got "x" (BAZIS_DB__PORT)`. */
+  readonly message: string;
+  /** Environment variables that set the key. */
+  readonly env: readonly string[];
+  /** The variable that supplied the wrong value. */
+  readonly source?: string;
+  readonly allowed?: readonly string[];
+  /** The file with the `defineConfig` call. */
+  readonly declaredIn?: string;
+  readonly environment: "development" | "test" | "production";
+}
+
+/**
+ * The configuration is invalid. `issues` lists every invalid key of every
+ * config at once, so the startup screen shows them together.
+ */
+export class ConfigValidationError extends KernelError {
+  public readonly issues: readonly ConfigIssue[];
+
+  public constructor(public readonly environment: string, issues: readonly ConfigIssue[]) {
+    // "key — text", not "key: text": the console redaction would read
+    // "db.password: required" as a secret value and hide the word "required".
+    super(`Invalid configuration (environment "${environment}"): ${issues.map((issue) => `${issue.key} — ${issue.message}`).join("; ")}.`);
+    this.issues = Object.freeze([...issues]);
+  }
+}

package/core/kernel/config/callerFile.ts

@@ -0,0 +1,23 @@
+import path from "node:path";
+
+const FRAME = /\(?((?:file:\/\/)?(?:\/|[A-Za-z]:\\)[^():]+):(\d+):\d+\)?\s*$/;
+
+/** Frames of the configuration code itself are skipped: the caller is what matters. */
+const OWN_DIRECTORY = import.meta.dir;
+
+/**
+ * `src/app/config/db.config.ts:3` of the first stack frame outside the
+ * configuration code, relative to the working directory; undefined when the
+ * stack has no such frame (a compiled executable keeps only virtual paths).
+ */
+export function callerFile(stack: string | undefined, cwd = process.cwd()): string | undefined {
+  for (const line of (stack ?? "").split("\n").slice(1)) {
+    const match = FRAME.exec(line.trim());
+    if (!match) continue;
+    const file = match[1]!.replace(/^file:\/\//, "");
+    if (file.startsWith(OWN_DIRECTORY) || file.includes("$bunfs")) continue;
+    const relative = path.relative(cwd, file);
+    return `${relative.startsWith("..") ? file : relative}:${match[2]}`;
+  }
+  return undefined;
+}

package/core/kernel/config/defineConfig.ts

@@ -5,6 +5,8 @@ import { Configuration } from "./Configuration";
 import { Secret } from "./Secret";
 import { ENV_PREFIX } from "./sources";
 import { isSensitiveKey, redactSensitiveText } from "../../../library/redaction";
+import { ConfigValidationError, type ConfigIssue, type ConfigIssueKind } from "./ConfigValidationError";
+import { callerFile } from "./callerFile";
 
 type Stand = "development" | "test" | "production";
 type Primitive = string | number | boolean;
@@ -126,6 +128,8 @@ export function defineConfig<T extends object>(schema: SchemaFor<T>): ConfigDefi
 export function defineConfig<T extends object>(prefix: string, schema: SchemaFor<T>): ConfigDefinition<T>;
 export function defineConfig(prefixOrSchema: string | ConfigSchema<Defaults>, maybeSchema?: ConfigSchema<Defaults>): ConfigDefinition<ConfigShape> {
   const prefix = typeof prefixOrSchema === "string" ? prefixOrSchema : "";
+  // The file that declared the config, for "declared in" of a startup failure.
+  const declaredIn = callerFile(new Error().stack);
   const input = typeof prefixOrSchema === "string" ? maybeSchema! : prefixOrSchema;
   const schema = Object.freeze({
     default: Object.freeze(Object.fromEntries(Object.entries(input.default).map(([key, value]) => [key, copyCell(value)]))),
@@ -153,12 +157,17 @@ export function defineConfig(prefixOrSchema: string | ConfigSchema<Defaults>, ma
     if (!["development", "test", "production"].includes(environment)) throw new KernelError("Unknown configuration environment.");
     const values = new Map<string, ConfigValueType>();
     const inspection: ConfigInspection[] = [];
-    const issues: string[] = [];
+    const issues: ConfigIssue[] = [];
+    const issue = (key: string, kind: ConfigIssueKind, message: string, extra: Partial<ConfigIssue> = {}) => issues.push(Object.freeze({
+      key: fullKey(key), section: prefix, kind, message, env: names.get(key)!, environment,
+      ...(declaredIn === undefined ? {} : { declaredIn }), ...extra,
+    }));
     // A wrong value names what came and where to change it: the variable that
     // supplied it, or the variables that can override the value from the code.
     // A key with a sensitive name never shows its value.
     const got = (key: string, raw: unknown) => raw === undefined || isSensitiveKey(fullKey(key)) ? "" : `, got ${JSON.stringify(String(raw)).slice(0, 80)}`;
     const source = (key: string, selected: { readonly name: string } | undefined) => ` (${selected ? selected.name : names.get(key)!.join(", ")})`;
+    const from = (selected: { readonly name: string } | undefined): Partial<ConfigIssue> => selected ? { source: selected.name } : {};
     for (const key of keys) {
       const base = schema.default[key]!;
       const override = schema[environment]?.[key];
@@ -175,46 +184,41 @@ export function defineConfig(prefixOrSchema: string | ConfigSchema<Defaults>, ma
       const priority = Math.max(...candidates.map(candidate => candidate.priority));
       const winners = candidates.filter(candidate => candidate.priority === priority);
       const selected = winners[0];
-      if (winners.some(candidate => candidate.raw !== selected?.raw)) issues.push(`${fullKey(key)} — conflicting environment aliases`);
+      if (winners.some(candidate => candidate.raw !== selected?.raw)) issue(key, "conflict", "conflicting environment aliases");
       const raw = selected?.raw ?? (isSecret(cell) || isEnum(cell) ? cell.default : cell);
       let value: ConfigValueType | undefined;
       if (type === "secret") {
-        if (typeof raw !== "string" || !raw.trim()) issues.push(`${fullKey(key)} — required non-empty secret is not set (${names.get(key)!.join(", ")})`);
+        if (typeof raw !== "string" || !raw.trim()) issue(key, "missing-secret", `required non-empty secret is not set (${names.get(key)!.join(", ")})`);
         // A secret default in the code is a development value; production must
         // get the secret from a source or declare its own value explicitly.
         // No "apiKey: …" in the hint: the console redaction would hide it.
-        else if (environment === "production" && selected === undefined && override === undefined) issues.push(`${fullKey(key)} — production would use the development default secret from the code; set ${names.get(key)!.join(" or ")}, or declare ${key} in the production section`);
+        else if (environment === "production" && selected === undefined && override === undefined) issue(key, "development-secret", `production would use the development default secret from the code; set ${names.get(key)!.join(" or ")}, or declare ${key} in the production section`);
         else value = new Secret(raw);
       } else if (type === "number") {
         const parsed = Number(raw);
-        if (raw === undefined || (typeof raw === "string" && !raw.trim()) || !Number.isFinite(parsed)) issues.push(`${fullKey(key)} — expected a finite number${got(key, raw)}${source(key, selected)}`);
+        if (raw === undefined || (typeof raw === "string" && !raw.trim()) || !Number.isFinite(parsed)) issue(key, "number", `expected a finite number${got(key, raw)}${source(key, selected)}`, from(selected));
         else value = parsed;
       } else if (type === "boolean") {
         const normalized = String(raw).toLowerCase();
         if (normalized === "true" || normalized === "1") value = true;
         else if (normalized === "false" || normalized === "0") value = false;
-        else issues.push(`${fullKey(key)} — expected a boolean (true, false, 1, 0)${got(key, raw)}${source(key, selected)}`);
+        else issue(key, "boolean", `expected a boolean (true, false, 1, 0)${got(key, raw)}${source(key, selected)}`, from(selected));
       } else if (typeof raw === "string") value = raw;
-      else issues.push(`${fullKey(key)} — expected a string`);
+      else issue(key, "string", "expected a string");
       if (value === undefined) continue;
-      if (isEnum(base) && !base.values.includes(value as string | number)) issues.push(`${fullKey(key)} — ${isSensitiveKey(fullKey(key)) ? "the value" : JSON.stringify(value)} is not allowed, use one of: ${base.values.join(", ")}${source(key, selected)}`);
+      if (isEnum(base) && !base.values.includes(value as string | number)) issue(key, "enum", `${isSensitiveKey(fullKey(key)) ? "the value" : JSON.stringify(value)} is not allowed, use one of: ${base.values.join(", ")}${source(key, selected)}`, { ...from(selected), allowed: Object.freeze(base.values.map(String)) });
       try {
-        const issue = validators[key]?.(value);
+        const problem = validators[key]?.(value);
         // A validator may quote its own value; hide it in that message only.
         // Replacing secrets across the whole text turned a one-letter secret
         // into "m***il.***piKey".
         const sensitive = value instanceof Secret ? value.reveal() : typeof value === "string" && isSensitiveKey(fullKey(key)) ? value : "";
-        if (issue) issues.push(`${fullKey(key)} — ${sensitive.trim() ? issue.replaceAll(sensitive, "***") : issue}`);
-      } catch { issues.push(`${fullKey(key)} — validator failed`); }
+        if (problem) issue(key, "validator", sensitive.trim() ? problem.replaceAll(sensitive, "***") : problem, from(selected));
+      } catch { issue(key, "validator", "validator failed", from(selected)); }
       values.set(key, value);
       inspection.push(Object.freeze({ key: fullKey(key), type: type as ConfigInspection["type"], env: names.get(key)!, source: selected?.source ?? (override === undefined ? "default" : environment), value: safeValue(fullKey(key), value) }));
     }
-    if (issues.length) {
-      // "key — text", not "key: text": the console redaction would read
-      // "db.password: required" as a secret value and hide the word "required".
-      const message = issues.join("; ");
-      throw new KernelError(`Invalid configuration (environment "${environment}"): ${message}.`);
-    }
+    if (issues.length) throw new ConfigValidationError(environment, issues);
     const rows = Object.freeze(inspection);
     return Object.freeze({
       environment,

package/core/kernel/errors/StartupFailuresError.ts

@@ -0,0 +1,17 @@
+/** One hosted service that failed to start, by its diagnostic name. */
+export interface StartupFailure {
+  readonly name: string;
+  readonly error: unknown;
+}
+
+/**
+ * Several services that start together (connections of the infrastructure
+ * manifest) failed. `failures` keeps every one with its name, so the startup
+ * screen shows all of them at once.
+ */
+export class StartupFailuresError extends AggregateError {
+  public constructor(public readonly failures: readonly StartupFailure[]) {
+    super(failures.map((failure) => failure.error), `${failures.length} services failed to start: ${failures.map((failure) => failure.name).join(", ")}.`);
+    this.name = "StartupFailuresError";
+  }
+}

package/core/kernel/errors/index.ts

@@ -3,3 +3,4 @@ export { KernelError } from "./KernelError";
 export { ShutdownTimeoutError } from "./ShutdownTimeoutError";
 export { StartupAbortedError } from "./StartupAbortedError";
 export { StartupTimeoutError } from "./StartupTimeoutError";
+export { StartupFailuresError, type StartupFailure } from "./StartupFailuresError";

package/core/kernel/index.ts

@@ -11,6 +11,7 @@ export { ConsoleLogger, type ConsoleLoggerOptions } from "./logging/ConsoleLogge
 
 export { Configuration, loadConfiguration } from "./config/Configuration";
 export { ConfigRegistry } from "./config/ConfigRegistry";
+export { ConfigValidationError, type ConfigIssue, type ConfigIssueKind } from "./config/ConfigValidationError";
 export { Secret } from "./config/Secret";
 export {
   defineConfig,
@@ -86,7 +87,18 @@ export {
   ShutdownTimeoutError,
   StartupAbortedError,
   StartupTimeoutError,
+  StartupFailuresError,
+  type StartupFailure,
 } from "./errors";
+export {
+  StartupReport,
+  type ConnectionDescription,
+  type ConnectionFact,
+  type ListenerFact,
+  type RouteFact,
+  type SchemaFact,
+  type TimingFact,
+} from "./report/StartupReport";
 export type {
   ConfigSource,
   EnvironmentName,

package/core/kernel/report/StartupReport.ts

@@ -0,0 +1,134 @@
+import type { ConfigInspection } from "../config/defineConfig";
+
+/**
+ * What the application found and did while it started: connections, schema
+ * changes, routes, listeners and warnings. Subsystems record facts here
+ * (`InfraLifecycle`, `OrmLifecycle`, `HttpServer`); the kernel renders them as
+ * the startup screen, or as one log line when the output is not a terminal.
+ *
+ * One report per kernel. It is registered in the container, so a subsystem
+ * takes it with `resolver.has(StartupReport)` and records only when present.
+ */
+export class StartupReport {
+  private readonly connectionList = new Map<string, ConnectionFact>();
+  private readonly schemaList: SchemaFact[] = [];
+  private readonly routeList: RouteFact[] = [];
+  private readonly listenerList: ListenerFact[] = [];
+  private readonly warningList: string[] = [];
+  private readonly timingList: TimingFact[] = [];
+  private configRows: readonly ConfigInspection[] = [];
+
+  /**
+   * Whether facts are rendered on the startup screen. Subsystems that used to
+   * print their own lines (ORM schema changes) print them only when it is off.
+   */
+  constructor(public readonly screen: boolean = false) {}
+
+  connection(fact: ConnectionFact): void {
+    this.connectionList.set(fact.name, { ...this.connectionList.get(fact.name), ...fact });
+  }
+
+  schema(fact: SchemaFact): void {
+    this.schemaList.push(fact);
+  }
+
+  routes(routes: readonly RouteFact[]): void {
+    this.routeList.push(...routes);
+  }
+
+  listener(fact: ListenerFact): void {
+    this.listenerList.push(fact);
+  }
+
+  warn(text: string): void {
+    if (!this.warningList.includes(text)) this.warningList.push(text);
+  }
+
+  timing(fact: TimingFact): void {
+    this.timingList.push(fact);
+  }
+
+  /** Resolved configuration keys with masked secrets, recorded when the kernel is built. */
+  configuration(rows: readonly ConfigInspection[]): void {
+    this.configRows = rows;
+  }
+
+  get config(): readonly ConfigInspection[] { return this.configRows; }
+
+  get connections(): readonly ConnectionFact[] { return [...this.connectionList.values()]; }
+  get schemas(): readonly SchemaFact[] { return this.schemaList; }
+  get routeFacts(): readonly RouteFact[] { return this.routeList; }
+  get listeners(): readonly ListenerFact[] { return this.listenerList; }
+  get warnings(): readonly string[] { return this.warningList; }
+  get timings(): readonly TimingFact[] { return this.timingList; }
+}
+
+/** A connection of the infrastructure manifest. */
+export interface ConnectionFact {
+  /** Manifest key: `db`, `cache`. */
+  readonly name: string;
+  readonly status: "up" | "down" | "wait";
+  /** What it connects to, from the connector's `describe()`: `PostgreSQL 17.6`. */
+  readonly kind?: string;
+  /** Address without credentials: `postgres@127.0.0.1:55432/shop`. */
+  readonly address?: string;
+  /** Short facts: `pool 10`, `green`. */
+  readonly details?: readonly string[];
+  /** Environment variables that change the address, for fix hints. */
+  readonly settings?: readonly string[];
+  readonly ms?: number;
+  readonly error?: unknown;
+}
+
+/** What a connector says about its connection, for the startup screen and failures. */
+export interface ConnectionDescription {
+  /** Product and version: `PostgreSQL 17.6`, `Redis 7.4`. */
+  readonly kind?: string;
+  /** Address without credentials. */
+  readonly address?: string;
+  readonly details?: readonly string[];
+  /** Environment variables or config keys that change the address, for fix hints. */
+  readonly settings?: readonly string[];
+}
+
+/** Schema work of one database context at start. */
+export interface SchemaFact {
+  readonly context: string;
+  readonly mode: string;
+  readonly applied: readonly string[];
+  readonly migrated: readonly string[];
+  readonly baselined: readonly string[];
+  readonly warnings: readonly string[];
+  readonly ms?: number;
+}
+
+export interface RouteFact {
+  readonly method: string;
+  readonly path: string;
+  /** `TaskController.list`. */
+  readonly handler: string;
+  /** Not protected by `@Authorize`. */
+  readonly open: boolean;
+  /** Policy or roles for a protected route. */
+  readonly access?: string;
+  /** Request model, list query, cache. */
+  readonly notes?: readonly string[];
+  /** Built-in endpoints (`/health`, `/docs`) are listed separately. */
+  readonly builtIn?: boolean;
+}
+
+export interface ListenerFact {
+  readonly protocol: "http" | "grpc";
+  readonly url: string;
+  readonly hostname: string;
+  readonly port: number;
+  readonly health?: string;
+  readonly docs?: string;
+}
+
+/** Wall time of one startup stage. */
+export interface TimingFact {
+  readonly stage: "infrastructure" | "schema" | "services";
+  readonly names: readonly string[];
+  readonly ms: number;
+}