@fluojs/runtime 2.0.1 → 3.0.0

package/dist/platform-shell.js

@@ -1,113 +1,22 @@
 import { InvariantError } from '@fluojs/core';
-function isRegistration(value) {
-  return typeof value === 'object' && value !== null && 'component' in value;
-}
-function normalizeRegistration(input) {
-  if (isRegistration(input)) {
-    return {
-      component: input.component,
-      dependencies: [...(input.dependencies ?? [])]
-    };
-  }
-  return {
-    component: input,
-    dependencies: []
-  };
-}
-function toRegisteredComponents(components) {
-  return (components ?? []).map(component => normalizeRegistration(component));
-}
-function createUnknownFailureIssue(componentId, phase, error) {
-  return {
-    cause: error instanceof Error ? error.message : String(error),
-    code: 'RUNTIME_PLATFORM_COMPONENT_FAILURE',
-    componentId,
-    fixHint: 'Inspect component implementation and ensure validate/start/ready/health/snapshot contracts are deterministic.',
-    message: `Platform component failed during ${phase}.`,
-    severity: 'error'
-  };
-}
-function aggregateReadiness(reports) {
-  const hasCriticalNotReady = reports.some(report => report.critical && report.status === 'not-ready');
-  const hasNotReady = reports.some(report => report.status === 'not-ready');
-  const hasDegraded = reports.some(report => report.status === 'degraded');
-  const hasCritical = reports.some(report => report.critical);
-  if (hasCriticalNotReady) {
-    const reason = reports.find(report => report.critical && report.status === 'not-ready')?.reason;
-    return {
-      critical: hasCritical,
-      reason: reason ?? 'One or more critical platform components are not ready.',
-      status: 'not-ready'
-    };
-  }
-  if (hasNotReady || hasDegraded) {
-    const reason = reports.find(report => report.status !== 'ready')?.reason;
-    return {
-      critical: hasCritical,
-      reason: reason ?? 'One or more platform components are degraded or not ready.',
-      status: 'degraded'
-    };
-  }
-  return {
-    critical: hasCritical,
-    status: 'ready'
-  };
-}
-function aggregateHealth(reports) {
-  const hasUnhealthy = reports.some(report => report.status === 'unhealthy');
-  const hasDegraded = reports.some(report => report.status === 'degraded');
-  if (hasUnhealthy) {
-    const reason = reports.find(report => report.status === 'unhealthy')?.reason;
-    return {
-      reason: reason ?? 'One or more platform components are unhealthy.',
-      status: 'unhealthy'
-    };
-  }
-  if (hasDegraded) {
-    const reason = reports.find(report => report.status === 'degraded')?.reason;
-    return {
-      reason: reason ?? 'One or more platform components are degraded.',
-      status: 'degraded'
-    };
-  }
-  return {
-    status: 'healthy'
-  };
-}
-function createEmptyShellSnapshot(diagnostics) {
-  return {
-    components: [],
-    diagnostics,
-    generatedAt: new Date().toISOString(),
-    health: {
-      status: 'healthy'
-    },
-    readiness: {
-      critical: false,
-      status: 'ready'
-    }
-  };
-}
-function normalizeSnapshot(snapshot, component, dependencies) {
-  return {
-    ...snapshot,
-    dependencies: [...dependencies],
-    id: component.id,
-    kind: component.kind
-  };
-}
+import { PlatformLifecycleConflictError } from './errors.js';
+import { assertValidPlatformComponentGraph, orderPlatformComponents, registerPlatformComponents } from './platform-component-registry.js';
+import { createPlatformFailureIssue, createPlatformValidationFailureIssue, PlatformDiagnosticRetention } from './platform-diagnostic-retention.js';
+import { PlatformShellProbeCollector } from './platform-shell-probes.js';
 /**
  * A runtime implementation of the {@link PlatformShell} that manages the lifecycle
  * of registered platform components, including dependency ordering and diagnostics.
  */
 export class RuntimePlatformShell {
   started = false;
-  stopped = false;
   orderedComponents = [];
   rollbackPendingComponents = [];
-  diagnostics = [];
+  diagnostics = new PlatformDiagnosticRetention();
+  probes;
+  activeLifecycleTransition;
   constructor(registeredComponents) {
     this.registeredComponents = registeredComponents;
+    this.probes = new PlatformShellProbeCollector(registeredComponents, this.diagnostics);
   }
 
   /**
@@ -117,31 +26,55 @@ export class RuntimePlatformShell {
    * @returns A new {@link RuntimePlatformShell} instance.
    */
   static fromInputs(components) {
-    return new RuntimePlatformShell(toRegisteredComponents(components));
+    return new RuntimePlatformShell(registerPlatformComponents(components));
   }
   hasRegisteredComponents() {
     return this.registeredComponents.length > 0;
   }
-  async start() {
+  start() {
+    return this.runLifecycleTransition('start', () => this.startComponents());
+  }
+  stop() {
+    return this.runLifecycleTransition('stop', () => this.stopComponents());
+  }
+  runLifecycleTransition(operation, run) {
+    const activeTransition = this.activeLifecycleTransition;
+    if (activeTransition) {
+      return Promise.reject(new PlatformLifecycleConflictError(activeTransition.operation, operation));
+    }
+    const transition = {
+      operation
+    };
+    this.activeLifecycleTransition = transition;
+    const promise = Promise.resolve(run());
+    const clearActiveTransition = () => {
+      if (this.activeLifecycleTransition === transition) {
+        this.activeLifecycleTransition = undefined;
+      }
+    };
+    void promise.then(clearActiveTransition, clearActiveTransition);
+    return promise;
+  }
+  async startComponents() {
     if (!this.hasRegisteredComponents() || this.started) {
       return;
     }
     if (this.rollbackPendingComponents.length > 0) {
-      await this.stop();
+      await this.stopComponents();
     }
-    this.validateIdentityAndDependencies();
+    assertValidPlatformComponentGraph(this.registeredComponents);
     const validationFailures = await this.validateComponents();
     if (validationFailures.length > 0) {
       throw new InvariantError(`Platform shell validation failed: ${validationFailures.map(issue => `${issue.componentId}:${issue.code}`).join(', ')}`);
     }
-    this.orderedComponents = this.orderByDependency();
+    this.orderedComponents = orderPlatformComponents(this.registeredComponents);
     const startedComponents = [];
     for (const component of this.orderedComponents) {
       try {
         await component.component.start();
         startedComponents.push(component);
       } catch (error) {
-        this.diagnostics.push(createUnknownFailureIssue(component.component.id, 'start', error));
+        this.diagnostics.append([createPlatformFailureIssue(component.component.id, 'start', error)]);
         const startFailure = new InvariantError(`Platform component "${component.component.id}" failed to start: ${error instanceof Error ? error.message : String(error)}`, {
           cause: error
         });
@@ -149,170 +82,32 @@ export class RuntimePlatformShell {
           await this.stopStartedComponents(startedComponents);
           this.rollbackPendingComponents = [];
         } catch (rollbackError) {
-          this.rollbackPendingComponents = [...startedComponents];
-          this.diagnostics.push(createUnknownFailureIssue(component.component.id, 'start-rollback', rollbackError));
+          this.diagnostics.append([createPlatformFailureIssue(component.component.id, 'start-rollback', rollbackError)]);
         }
         throw startFailure;
       }
     }
     this.started = true;
-    this.stopped = false;
     this.rollbackPendingComponents = [];
   }
-  async stop() {
+  async stopComponents() {
     const hasRollbackPending = this.rollbackPendingComponents.length > 0;
-    if (!this.started && !hasRollbackPending || this.stopped) {
+    if (!this.started && !hasRollbackPending) {
       return;
     }
     const toStop = hasRollbackPending ? [...this.rollbackPendingComponents] : this.orderedComponents.length > 0 ? [...this.orderedComponents] : [...this.registeredComponents];
+    this.started = false;
     await this.stopStartedComponents(toStop);
     this.rollbackPendingComponents = [];
-    this.started = false;
-    this.stopped = true;
   }
-  async ready() {
-    if (!this.hasRegisteredComponents()) {
-      return {
-        critical: false,
-        status: 'ready'
-      };
-    }
-    const reports = [];
-    for (const component of this.registeredComponents) {
-      try {
-        reports.push(await component.component.ready());
-      } catch (error) {
-        const issue = createUnknownFailureIssue(component.component.id, 'ready', error);
-        this.diagnostics.push(issue);
-        reports.push({
-          critical: true,
-          reason: issue.cause,
-          status: 'not-ready'
-        });
-      }
-    }
-    return aggregateReadiness(reports);
+  ready() {
+    return this.probes.ready();
   }
-  async health() {
-    if (!this.hasRegisteredComponents()) {
-      return {
-        status: 'healthy'
-      };
-    }
-    const reports = [];
-    for (const component of this.registeredComponents) {
-      try {
-        reports.push(await component.component.health());
-      } catch (error) {
-        const issue = createUnknownFailureIssue(component.component.id, 'health', error);
-        this.diagnostics.push(issue);
-        reports.push({
-          reason: issue.cause,
-          status: 'unhealthy'
-        });
-      }
-    }
-    return aggregateHealth(reports);
-  }
-  async snapshot() {
-    if (!this.hasRegisteredComponents()) {
-      return createEmptyShellSnapshot([...this.diagnostics]);
-    }
-    const probeResults = await Promise.all(this.registeredComponents.map(registration => this.collectSnapshotProbe(registration)));
-    const components = probeResults.map(result => result.snapshot);
-    const readiness = aggregateReadiness(probeResults.map(result => result.readiness));
-    const health = aggregateHealth(probeResults.map(result => result.health));
-    const diagnostics = probeResults.flatMap(result => result.diagnostics);
-    this.diagnostics.push(...diagnostics);
-    return {
-      components,
-      diagnostics: [...this.diagnostics],
-      generatedAt: new Date().toISOString(),
-      health,
-      readiness
-    };
-  }
-  async collectSnapshotProbe(registration) {
-    const [snapshot, readiness, health] = await Promise.all([this.collectComponentSnapshot(registration), this.collectComponentReadiness(registration), this.collectComponentHealth(registration)]);
-    return {
-      diagnostics: [...snapshot.diagnostics, ...readiness.diagnostics, ...health.diagnostics],
-      health: health.health,
-      readiness: readiness.readiness,
-      snapshot: snapshot.snapshot
-    };
+  health() {
+    return this.probes.health();
   }
-  collectComponentSnapshot(registration) {
-    try {
-      const snapshot = registration.component.snapshot();
-      return {
-        diagnostics: [],
-        snapshot: normalizeSnapshot(snapshot, registration.component, registration.dependencies)
-      };
-    } catch (error) {
-      const issue = createUnknownFailureIssue(registration.component.id, 'snapshot', error);
-      return {
-        diagnostics: [issue],
-        snapshot: {
-          dependencies: [...registration.dependencies],
-          details: {},
-          health: {
-            reason: issue.cause,
-            status: 'unhealthy'
-          },
-          id: registration.component.id,
-          kind: registration.component.kind,
-          ownership: {
-            externallyManaged: false,
-            ownsResources: false
-          },
-          readiness: {
-            critical: true,
-            reason: issue.cause,
-            status: 'not-ready'
-          },
-          state: 'failed',
-          telemetry: {
-            namespace: 'fluo.platform',
-            tags: {}
-          }
-        }
-      };
-    }
-  }
-  async collectComponentReadiness(registration) {
-    try {
-      return {
-        diagnostics: [],
-        readiness: await registration.component.ready()
-      };
-    } catch (error) {
-      const issue = createUnknownFailureIssue(registration.component.id, 'ready', error);
-      return {
-        diagnostics: [issue],
-        readiness: {
-          critical: true,
-          reason: issue.cause,
-          status: 'not-ready'
-        }
-      };
-    }
-  }
-  async collectComponentHealth(registration) {
-    try {
-      return {
-        diagnostics: [],
-        health: await registration.component.health()
-      };
-    } catch (error) {
-      const issue = createUnknownFailureIssue(registration.component.id, 'health', error);
-      return {
-        diagnostics: [issue],
-        health: {
-          reason: issue.cause,
-          status: 'unhealthy'
-        }
-      };
-    }
+  snapshot() {
+    return this.probes.snapshot();
   }
   async assertCriticalReadiness() {
     const readiness = await this.ready();
@@ -320,28 +115,6 @@ export class RuntimePlatformShell {
       throw new InvariantError(`Runtime platform shell is not ready: ${readiness.reason ?? 'critical platform component is unavailable.'}`);
     }
   }
-  validateIdentityAndDependencies() {
-    const ids = new Set();
-    for (const registration of this.registeredComponents) {
-      if (!registration.component.id || registration.component.id.trim().length === 0) {
-        throw new InvariantError('Platform component id must be a non-empty string.');
-      }
-      if (ids.has(registration.component.id)) {
-        throw new InvariantError(`Duplicate platform component id "${registration.component.id}" is not allowed.`);
-      }
-      ids.add(registration.component.id);
-    }
-    for (const registration of this.registeredComponents) {
-      for (const dependency of registration.dependencies) {
-        if (!ids.has(dependency)) {
-          throw new InvariantError(`Platform component "${registration.component.id}" depends on unknown component "${dependency}".`);
-        }
-        if (dependency === registration.component.id) {
-          throw new InvariantError(`Platform component "${registration.component.id}" cannot depend on itself.`);
-        }
-      }
-    }
-  }
   async validateComponents() {
     const failures = [];
     for (const registration of this.registeredComponents) {
@@ -349,61 +122,36 @@ export class RuntimePlatformShell {
       try {
         result = await registration.component.validate();
       } catch (error) {
-        const issue = createUnknownFailureIssue(registration.component.id, 'validate', error);
-        this.diagnostics.push(issue);
+        const issue = createPlatformFailureIssue(registration.component.id, 'validate', error);
+        this.diagnostics.append([issue]);
         failures.push(issue);
         continue;
       }
       if (result.warnings) {
-        this.diagnostics.push(...result.warnings);
+        this.diagnostics.append(result.warnings);
       }
       if (!result.ok || result.issues.some(issue => issue.severity === 'error')) {
-        this.diagnostics.push(...result.issues);
-        failures.push(...result.issues);
+        const reportedIssues = result.issues.length > 0 ? result.issues : [createPlatformValidationFailureIssue(registration.component.id)];
+        this.diagnostics.append(reportedIssues);
+        failures.push(...reportedIssues);
       }
     }
     return failures;
   }
-  orderByDependency() {
-    const byId = new Map(this.registeredComponents.map(registration => [registration.component.id, registration]));
-    const visiting = new Set();
-    const visited = new Set();
-    const ordered = [];
-    const visit = id => {
-      if (visited.has(id)) {
-        return;
-      }
-      if (visiting.has(id)) {
-        throw new InvariantError(`Platform component dependency cycle detected at "${id}".`);
-      }
-      visiting.add(id);
-      const registration = byId.get(id);
-      if (!registration) {
-        throw new InvariantError(`Platform component "${id}" is missing from runtime registration.`);
-      }
-      for (const dependency of registration.dependencies) {
-        visit(dependency);
-      }
-      visiting.delete(id);
-      visited.add(id);
-      ordered.push(registration);
-    };
-    for (const registration of this.registeredComponents) {
-      visit(registration.component.id);
-    }
-    return ordered;
-  }
   async stopStartedComponents(startedComponents) {
     const errors = [];
+    const pendingComponents = [];
     for (const component of [...startedComponents].reverse()) {
       try {
         await component.component.stop();
       } catch (error) {
         errors.push(error);
-        this.diagnostics.push(createUnknownFailureIssue(component.component.id, 'stop', error));
+        pendingComponents.unshift(component);
+        this.diagnostics.append([createPlatformFailureIssue(component.component.id, 'stop', error)]);
       }
     }
     if (errors.length > 0) {
+      this.rollbackPendingComponents = pendingComponents;
       throw new AggregateError(errors, 'One or more platform components failed to stop cleanly.');
     }
   }

package/dist/retryable-shutdown.d.ts

@@ -0,0 +1,7 @@
+export type RetryableShutdownState<TPhase> = {
+    complete(phase: TPhase): void;
+    isComplete(phase: TPhase): boolean;
+};
+export declare function createLifecycleCloseError(errors: readonly unknown[]): Error;
+export declare function createRetryableShutdownState<TPhase>(): RetryableShutdownState<TPhase>;
+//# sourceMappingURL=retryable-shutdown.d.ts.map

package/dist/retryable-shutdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retryable-shutdown.d.ts","sourceRoot":"","sources":["../src/retryable-shutdown.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,sBAAsB,CAAC,MAAM,IAAI;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CACpC,CAAC;AAMF,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,GAAG,KAAK,CAM3E;AAED,wBAAgB,4BAA4B,CAAC,MAAM,KAAK,sBAAsB,CAAC,MAAM,CAAC,CAWrF"}

package/dist/retryable-shutdown.js

@@ -0,0 +1,20 @@
+function toError(error) {
+  return error instanceof Error ? error : new Error(String(error));
+}
+export function createLifecycleCloseError(errors) {
+  if (errors.length === 1) {
+    return toError(errors[0]);
+  }
+  return new AggregateError(errors, 'Application close failed for one or more shutdown steps.');
+}
+export function createRetryableShutdownState() {
+  const completedPhases = new Set();
+  return {
+    complete(phase) {
+      completedPhases.add(phase);
+    },
+    isComplete(phase) {
+      return completedPhases.has(phase);
+    }
+  };
+}

package/dist/route-inspection.d.ts

@@ -0,0 +1,56 @@
+import type { HandlerDescriptor, HttpMethod } from '@fluojs/http/portable';
+import type { PlatformShellSnapshot } from './platform-contract.js';
+/**
+ * Read-only, serializable description of one compiled HTTP handler.
+ *
+ * @remarks
+ * Values are projected from authoritative `HandlerDescriptor` fields after HTTP route
+ * compilation. `kind` is `http` unless a framework integration records a more specific
+ * runtime-neutral inspection marker. This contract never participates in matching,
+ * conflict detection, or dispatch.
+ */
+export interface RuntimeRouteInspection {
+    readonly controller: string;
+    readonly handler: string;
+    readonly id: string;
+    readonly kind: string;
+    readonly method: HttpMethod;
+    readonly module?: string;
+    readonly params: readonly string[];
+    readonly path: string;
+    readonly version?: string;
+}
+/** Runtime platform snapshot extended with compiled route inspection data. */
+export interface RuntimeInspectionSnapshot extends PlatformShellSnapshot {
+    readonly routes: readonly RuntimeRouteInspection[];
+}
+/**
+ * Creates the stable identifier shared by route inspection consumers.
+ *
+ * @param descriptor Compiled HTTP handler descriptor to identify.
+ * @returns Stable identifier containing method, effective path, controller, and handler.
+ */
+export declare function createRuntimeRouteInspectionId(descriptor: HandlerDescriptor): string;
+/**
+ * Projects one compiled HTTP descriptor into immutable machine-readable route data.
+ *
+ * @param descriptor Authoritative descriptor produced by the HTTP handler mapping.
+ * @returns Frozen route inspection entry detached from mutable descriptor collections.
+ */
+export declare function createRuntimeRouteInspection(descriptor: HandlerDescriptor): RuntimeRouteInspection;
+/**
+ * Projects compiled HTTP descriptors into an immutable route catalog for diagnostics.
+ *
+ * @param descriptors Authoritative descriptors produced by the HTTP handler mapping.
+ * @returns Frozen route entries in descriptor registration order.
+ */
+export declare function createRuntimeRouteCatalog(descriptors: readonly HandlerDescriptor[]): readonly RuntimeRouteInspection[];
+/**
+ * Adds immutable route inspection data to a runtime platform snapshot.
+ *
+ * @param snapshot Existing runtime-owned platform snapshot.
+ * @param descriptors Authoritative compiled HTTP descriptors.
+ * @returns A new frozen snapshot with a read-only `routes` collection.
+ */
+export declare function createRuntimeInspectionSnapshot(snapshot: PlatformShellSnapshot, descriptors: readonly HandlerDescriptor[]): RuntimeInspectionSnapshot;
+//# sourceMappingURL=route-inspection.d.ts.map

package/dist/route-inspection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-inspection.d.ts","sourceRoot":"","sources":["../src/route-inspection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAG3E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAEpE;;;;;;;;GAQG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,8EAA8E;AAC9E,MAAM,WAAW,yBAA0B,SAAQ,qBAAqB;IACtE,QAAQ,CAAC,MAAM,EAAE,SAAS,sBAAsB,EAAE,CAAC;CACpD;AAMD;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,UAAU,EAAE,iBAAiB,GAAG,MAAM,CAOpF;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,iBAAiB,GAAG,sBAAsB,CAkBlG;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,SAAS,iBAAiB,EAAE,GACxC,SAAS,sBAAsB,EAAE,CAEnC;AAED;;;;;;GAMG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,qBAAqB,EAC/B,WAAW,EAAE,SAAS,iBAAiB,EAAE,GACxC,yBAAyB,CAK3B"}

package/dist/route-inspection.js

@@ -0,0 +1,80 @@
+import { getRuntimeRouteInspectionMetadata } from './internal/route-inspection-metadata.js';
+
+/**
+ * Read-only, serializable description of one compiled HTTP handler.
+ *
+ * @remarks
+ * Values are projected from authoritative `HandlerDescriptor` fields after HTTP route
+ * compilation. `kind` is `http` unless a framework integration records a more specific
+ * runtime-neutral inspection marker. This contract never participates in matching,
+ * conflict detection, or dispatch.
+ */
+
+/** Runtime platform snapshot extended with compiled route inspection data. */
+
+function effectivePath(descriptor) {
+  return descriptor.metadata.effectivePath || descriptor.route.path;
+}
+
+/**
+ * Creates the stable identifier shared by route inspection consumers.
+ *
+ * @param descriptor Compiled HTTP handler descriptor to identify.
+ * @returns Stable identifier containing method, effective path, controller, and handler.
+ */
+export function createRuntimeRouteInspectionId(descriptor) {
+  return [descriptor.route.method, effectivePath(descriptor), descriptor.controllerToken.name || '<anonymous-controller>', descriptor.methodName].join(' ');
+}
+
+/**
+ * Projects one compiled HTTP descriptor into immutable machine-readable route data.
+ *
+ * @param descriptor Authoritative descriptor produced by the HTTP handler mapping.
+ * @returns Frozen route inspection entry detached from mutable descriptor collections.
+ */
+export function createRuntimeRouteInspection(descriptor) {
+  const route = {
+    controller: descriptor.controllerToken.name || '<anonymous-controller>',
+    handler: descriptor.methodName,
+    id: createRuntimeRouteInspectionId(descriptor),
+    kind: getRuntimeRouteInspectionMetadata(descriptor.controllerToken, descriptor.methodName)?.kind ?? 'http',
+    method: descriptor.route.method,
+    params: Object.freeze([...descriptor.metadata.pathParams]),
+    path: effectivePath(descriptor)
+  };
+  const moduleName = descriptor.metadata.moduleType?.name;
+  const version = descriptor.metadata.effectiveVersion ?? descriptor.route.version;
+  return Object.freeze({
+    ...route,
+    ...(moduleName ? {
+      module: moduleName
+    } : {}),
+    ...(version ? {
+      version
+    } : {})
+  });
+}
+
+/**
+ * Projects compiled HTTP descriptors into an immutable route catalog for diagnostics.
+ *
+ * @param descriptors Authoritative descriptors produced by the HTTP handler mapping.
+ * @returns Frozen route entries in descriptor registration order.
+ */
+export function createRuntimeRouteCatalog(descriptors) {
+  return Object.freeze(descriptors.map(descriptor => createRuntimeRouteInspection(descriptor)));
+}
+
+/**
+ * Adds immutable route inspection data to a runtime platform snapshot.
+ *
+ * @param snapshot Existing runtime-owned platform snapshot.
+ * @param descriptors Authoritative compiled HTTP descriptors.
+ * @returns A new frozen snapshot with a read-only `routes` collection.
+ */
+export function createRuntimeInspectionSnapshot(snapshot, descriptors) {
+  return Object.freeze({
+    ...snapshot,
+    routes: createRuntimeRouteCatalog(descriptors)
+  });
+}

package/dist/tokens.d.ts

@@ -1,10 +1,8 @@
 import type { Token } from '@fluojs/core';
 import type { Container } from '@fluojs/di';
-import type { HttpApplicationAdapter } from '@fluojs/http';
-import type { ApplicationLogger } from './types.js';
-import type { CompiledModule } from './types.js';
-import type { RuntimeCleanupRegistration } from './types.js';
+import type { HttpApplicationAdapter } from '@fluojs/http/portable';
 import type { PlatformShell } from './platform-contract.js';
+import type { ApplicationLogger, CompiledModule, RuntimeCleanupRegistration } from './types.js';
 /** Internal signal that resolves only after application bootstrap reaches runtime readiness. */
 export interface BootstrapReadySignal {
     /** Waits until every bootstrap hook and runtime readiness transition has completed. */
@@ -18,6 +16,10 @@ export declare const APPLICATION_LOGGER: Token<ApplicationLogger>;
  * Injection token for the runtime container.
  */
 export declare const RUNTIME_CONTAINER: Token<Container>;
+/**
+ * Injection token for the effective provider tokens supplied to the application bootstrap.
+ */
+export declare const BOOTSTRAP_PROVIDER_TOKENS: Token<ReadonlySet<Token>>;
 /**
  * Injection token for the compiled module list.
  */

package/dist/tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAE3D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5D,gGAAgG;AAChG,MAAM,WAAW,oBAAoB;IACnC,uFAAuF;IACvF,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,KAAK,CAAC,iBAAiB,CAAiD,CAAC;AAE1G;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,SAAS,CAA+B,CAAC;AAE/E;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,SAAS,cAAc,EAAE,CAA8B,CAAC;AAE7F;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,KAAK,CAAC,sBAAsB,CAAsC,CAAC;AAE1G;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,aAAa,CAA4B,CAAC;AAE7E;;GAEG;AACH,eAAO,MAAM,4BAA4B,EAAE,KAAK,CAAC,0BAA0B,CAA0C,CAAC;AAEtH,mGAAmG;AACnG,eAAO,MAAM,sBAAsB,EAAE,KAAK,CAAC,oBAAoB,CAAoC,CAAC"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAEpE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,cAAc,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAEhG,gGAAgG;AAChG,MAAM,WAAW,oBAAoB;IACnC,uFAAuF;IACvF,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,KAAK,CAAC,iBAAiB,CAAiD,CAAC;AAE1G;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,SAAS,CAA+B,CAAC;AAE/E;;GAEG;AACH,eAAO,MAAM,yBAAyB,EAAE,KAAK,CAAC,WAAW,CAAC,KAAK,CAAC,CAAuC,CAAC;AAExG;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,SAAS,cAAc,EAAE,CAA8B,CAAC;AAE7F;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,KAAK,CAAC,sBAAsB,CAAsC,CAAC;AAE1G;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,KAAK,CAAC,aAAa,CAA4B,CAAC;AAE7E;;GAEG;AACH,eAAO,MAAM,4BAA4B,EAAE,KAAK,CAAC,0BAA0B,CAA0C,CAAC;AAEtH,mGAAmG;AACnG,eAAO,MAAM,sBAAsB,EAAE,KAAK,CAAC,oBAAoB,CAAoC,CAAC"}

package/dist/tokens.js

@@ -10,6 +10,11 @@ export const APPLICATION_LOGGER = Symbol.for('fluo.runtime.application-logger');
  */
 export const RUNTIME_CONTAINER = Symbol('RUNTIME_CONTAINER');
 
+/**
+ * Injection token for the effective provider tokens supplied to the application bootstrap.
+ */
+export const BOOTSTRAP_PROVIDER_TOKENS = Symbol('BOOTSTRAP_PROVIDER_TOKENS');
+
 /**
  * Injection token for the compiled module list.
  */