@fluojs/runtime 1.0.0-beta.1

package/dist/platform-contract.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Shared configuration knobs understood by runtime platform components.
+ */
+export interface PlatformOptionsBase {
+    id?: string;
+    enabled?: boolean;
+    readiness?: {
+        critical?: boolean;
+        timeoutMs?: number;
+    };
+    shutdown?: {
+        timeoutMs?: number;
+    };
+    diagnostics?: {
+        expose?: boolean;
+        tags?: Record<string, string>;
+    };
+    telemetry?: {
+        namespace?: string;
+        tags?: Record<string, string>;
+    };
+}
+/** Lifecycle states emitted by platform components and the platform shell. */
+export type PlatformState = 'created' | 'validated' | 'starting' | 'ready' | 'degraded' | 'stopping' | 'stopped' | 'failed';
+/**
+ * Runtime-managed infrastructure component that participates in validation,
+ * startup, readiness, health, diagnostics, and shutdown orchestration.
+ */
+export interface PlatformComponent {
+    id: string;
+    kind: string;
+    state(): PlatformState;
+    validate(): Promise<PlatformValidationResult> | PlatformValidationResult;
+    start(): Promise<void>;
+    ready(): Promise<PlatformReadinessReport>;
+    health(): Promise<PlatformHealthReport>;
+    snapshot(): PlatformSnapshot;
+    stop(): Promise<void>;
+}
+/** Registration wrapper used when a component declares platform dependencies. */
+export interface PlatformComponentRegistration {
+    component: PlatformComponent;
+    dependencies?: readonly string[];
+}
+/** Component registration input accepted by runtime bootstrap options. */
+export type PlatformComponentInput = PlatformComponent | PlatformComponentRegistration;
+/** Outcome for one named readiness or health probe inside a platform report. */
+export interface PlatformCheckResult {
+    name: string;
+    status: 'pass' | 'fail' | 'degraded';
+    message?: string;
+}
+/**
+ * Readiness semantics for one component or the aggregated platform shell.
+ */
+export interface PlatformReadinessReport {
+    status: 'ready' | 'not-ready' | 'degraded';
+    critical: boolean;
+    reason?: string;
+    checks?: PlatformCheckResult[];
+}
+/**
+ * Health semantics for one component or the aggregated platform shell.
+ */
+export interface PlatformHealthReport {
+    status: 'healthy' | 'unhealthy' | 'degraded';
+    reason?: string;
+    checks?: PlatformCheckResult[];
+}
+/** Snapshot payload stored when persistence-backed platform status is exported. */
+export interface PersistencePlatformStatusSnapshot {
+    readiness: PlatformReadinessReport;
+    health: PlatformHealthReport;
+    ownership: PlatformSnapshot['ownership'];
+    details: Record<string, unknown>;
+}
+/** Machine-readable diagnostic issue reported during platform validation. */
+export interface PlatformDiagnosticIssue {
+    code: string;
+    severity: 'error' | 'warning' | 'info';
+    componentId: string;
+    message: string;
+    cause?: string;
+    fixHint?: string;
+    dependsOn?: string[];
+    docsUrl?: string;
+}
+/** Validation result returned before platform startup proceeds. */
+export interface PlatformValidationResult {
+    ok: boolean;
+    issues: PlatformDiagnosticIssue[];
+    warnings?: PlatformDiagnosticIssue[];
+}
+/** Immutable component snapshot included in runtime diagnostics and telemetry. */
+export interface PlatformSnapshot {
+    id: string;
+    kind: string;
+    state: PlatformState;
+    readiness: {
+        status: PlatformReadinessReport['status'];
+        critical: boolean;
+        reason?: string;
+    };
+    health: {
+        status: PlatformHealthReport['status'];
+        reason?: string;
+    };
+    dependencies: string[];
+    telemetry: {
+        namespace: string;
+        tags: Record<string, string>;
+    };
+    ownership: {
+        ownsResources: boolean;
+        externallyManaged: boolean;
+    };
+    details: Record<string, unknown>;
+}
+/**
+ * Aggregate platform snapshot emitted by the shell after collecting component
+ * health, readiness, and validation diagnostics.
+ */
+export interface PlatformShellSnapshot {
+    generatedAt: string;
+    readiness: PlatformReadinessReport;
+    health: PlatformHealthReport;
+    components: PlatformSnapshot[];
+    diagnostics: PlatformDiagnosticIssue[];
+}
+/**
+ * High-level runtime facade that coordinates platform components as one unit.
+ */
+export interface PlatformShell {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    ready(): Promise<PlatformReadinessReport>;
+    health(): Promise<PlatformHealthReport>;
+    snapshot(): Promise<PlatformShellSnapshot>;
+}
+//# sourceMappingURL=platform-contract.d.ts.map

package/dist/platform-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-contract.d.ts","sourceRoot":"","sources":["../src/platform-contract.ts"],"names":[],"mappings":"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"}

package/dist/platform-contract.js

@@ -0,0 +1 @@
+export {};

package/dist/platform-shell.d.ts

@@ -0,0 +1,45 @@
+import type { PlatformComponent, PlatformComponentInput, PlatformHealthReport, PlatformReadinessReport, PlatformShell, PlatformShellSnapshot } from './platform-contract.js';
+interface RegisteredPlatformComponent {
+    component: PlatformComponent;
+    dependencies: readonly string[];
+}
+/**
+ * A runtime implementation of the {@link PlatformShell} that manages the lifecycle
+ * of registered platform components, including dependency ordering and diagnostics.
+ */
+export declare class RuntimePlatformShell implements PlatformShell {
+    private readonly registeredComponents;
+    private started;
+    private stopped;
+    private orderedComponents;
+    private rollbackPendingComponents;
+    private readonly diagnostics;
+    constructor(registeredComponents: RegisteredPlatformComponent[]);
+    /**
+     * Creates a {@link RuntimePlatformShell} from an optional array of platform component inputs.
+     *
+     * @param components - The platform component inputs to register in the shell.
+     * @returns A new {@link RuntimePlatformShell} instance.
+     */
+    static fromInputs(components: readonly PlatformComponentInput[] | undefined): RuntimePlatformShell;
+    hasRegisteredComponents(): boolean;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    ready(): Promise<PlatformReadinessReport>;
+    health(): Promise<PlatformHealthReport>;
+    snapshot(): Promise<PlatformShellSnapshot>;
+    assertCriticalReadiness(): Promise<void>;
+    private validateIdentityAndDependencies;
+    private validateComponents;
+    private orderByDependency;
+    private stopStartedComponents;
+}
+/**
+ * Creates a {@link RuntimePlatformShell} instance to manage platform component lifecycles.
+ *
+ * @param components - The platform component inputs to register in the shell.
+ * @returns A new {@link RuntimePlatformShell} instance.
+ */
+export declare function createRuntimePlatformShell(components: readonly PlatformComponentInput[] | undefined): RuntimePlatformShell;
+export {};
+//# sourceMappingURL=platform-shell.d.ts.map

package/dist/platform-shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-shell.d.ts","sourceRoot":"","sources":["../src/platform-shell.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,iBAAiB,EACjB,sBAAsB,EAGtB,oBAAoB,EACpB,uBAAuB,EACvB,aAAa,EACb,qBAAqB,EAGtB,MAAM,wBAAwB,CAAC;AAEhC,UAAU,2BAA2B;IACnC,SAAS,EAAE,iBAAiB,CAAC;IAC7B,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CACjC;AAkHD;;;GAGG;AACH,qBAAa,oBAAqB,YAAW,aAAa;IAO5C,OAAO,CAAC,QAAQ,CAAC,oBAAoB;IANjD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,iBAAiB,CAAqC;IAC9D,OAAO,CAAC,yBAAyB,CAAqC;IACtE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiC;gBAEhC,oBAAoB,EAAE,2BAA2B,EAAE;IAEhF;;;;;OAKG;IACH,MAAM,CAAC,UAAU,CAAC,UAAU,EAAE,SAAS,sBAAsB,EAAE,GAAG,SAAS,GAAG,oBAAoB;IAIlG,uBAAuB,IAAI,OAAO;IAI5B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAiDtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBrB,KAAK,IAAI,OAAO,CAAC,uBAAuB,CAAC;IA2BzC,MAAM,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAyBvC,QAAQ,IAAI,OAAO,CAAC,qBAAqB,CAAC;IAmD1C,uBAAuB,IAAI,OAAO,CAAC,IAAI,CAAC;IAU9C,OAAO,CAAC,+BAA+B;YAgCzB,kBAAkB;IA4BhC,OAAO,CAAC,iBAAiB;YAsCX,qBAAqB;CAgBpC;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,SAAS,sBAAsB,EAAE,GAAG,SAAS,GAAG,oBAAoB,CAE1H"}

package/dist/platform-shell.js

@@ -0,0 +1,368 @@
+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
+  };
+}
+
+/**
+ * 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 = [];
+  constructor(registeredComponents) {
+    this.registeredComponents = registeredComponents;
+  }
+
+  /**
+   * Creates a {@link RuntimePlatformShell} from an optional array of platform component inputs.
+   *
+   * @param components - The platform component inputs to register in the shell.
+   * @returns A new {@link RuntimePlatformShell} instance.
+   */
+  static fromInputs(components) {
+    return new RuntimePlatformShell(toRegisteredComponents(components));
+  }
+  hasRegisteredComponents() {
+    return this.registeredComponents.length > 0;
+  }
+  async start() {
+    if (!this.hasRegisteredComponents() || this.started) {
+      return;
+    }
+    if (this.rollbackPendingComponents.length > 0) {
+      await this.stop();
+    }
+    this.validateIdentityAndDependencies();
+    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();
+    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));
+        const startFailure = new InvariantError(`Platform component "${component.component.id}" failed to start: ${error instanceof Error ? error.message : String(error)}`, {
+          cause: error
+        });
+        try {
+          await this.stopStartedComponents(startedComponents);
+          this.rollbackPendingComponents = [];
+        } catch (rollbackError) {
+          this.rollbackPendingComponents = [...startedComponents];
+          this.diagnostics.push(createUnknownFailureIssue(component.component.id, 'start-rollback', rollbackError));
+        }
+        throw startFailure;
+      }
+    }
+    this.started = true;
+    this.stopped = false;
+    this.rollbackPendingComponents = [];
+  }
+  async stop() {
+    const hasRollbackPending = this.rollbackPendingComponents.length > 0;
+    if (!this.started && !hasRollbackPending || this.stopped) {
+      return;
+    }
+    const toStop = hasRollbackPending ? [...this.rollbackPendingComponents] : this.orderedComponents.length > 0 ? [...this.orderedComponents] : [...this.registeredComponents];
+    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);
+  }
+  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 components = [];
+    for (const registration of this.registeredComponents) {
+      try {
+        const snapshot = registration.component.snapshot();
+        components.push(normalizeSnapshot(snapshot, registration.component, registration.dependencies));
+      } catch (error) {
+        const issue = createUnknownFailureIssue(registration.component.id, 'snapshot', error);
+        this.diagnostics.push(issue);
+        components.push({
+          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: {}
+          }
+        });
+      }
+    }
+    const [readiness, health] = await Promise.all([this.ready(), this.health()]);
+    return {
+      components,
+      diagnostics: [...this.diagnostics],
+      generatedAt: new Date().toISOString(),
+      health,
+      readiness
+    };
+  }
+  async assertCriticalReadiness() {
+    const readiness = await this.ready();
+    if (readiness.status === 'not-ready') {
+      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) {
+      let result;
+      try {
+        result = await registration.component.validate();
+      } catch (error) {
+        const issue = createUnknownFailureIssue(registration.component.id, 'validate', error);
+        this.diagnostics.push(issue);
+        failures.push(issue);
+        continue;
+      }
+      if (result.warnings) {
+        this.diagnostics.push(...result.warnings);
+      }
+      if (!result.ok || result.issues.some(issue => issue.severity === 'error')) {
+        this.diagnostics.push(...result.issues);
+        failures.push(...result.issues);
+      }
+    }
+    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 = [];
+    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));
+      }
+    }
+    if (errors.length > 0) {
+      throw new AggregateError(errors, 'One or more platform components failed to stop cleanly.');
+    }
+  }
+}
+
+/**
+ * Creates a {@link RuntimePlatformShell} instance to manage platform component lifecycles.
+ *
+ * @param components - The platform component inputs to register in the shell.
+ * @returns A new {@link RuntimePlatformShell} instance.
+ */
+export function createRuntimePlatformShell(components) {
+  return RuntimePlatformShell.fromInputs(components);
+}

package/dist/request-transaction.d.ts

@@ -0,0 +1,17 @@
+export type RequestAbortContext = {
+    controller: AbortController;
+    cleanup(): void;
+    signal: AbortSignal;
+};
+export type ActiveRequestTransaction = {
+    abort(reason?: unknown): void;
+    settled: Promise<void>;
+};
+export type ActiveRequestTransactionHandle = {
+    active: ActiveRequestTransaction;
+    settle(): void;
+};
+export declare function createRequestAbortContext(signal?: AbortSignal): RequestAbortContext;
+export declare function trackActiveRequestTransaction(activeRequestTransactions: Set<ActiveRequestTransaction>, controller: AbortController): ActiveRequestTransactionHandle;
+export declare function untrackActiveRequestTransaction(activeRequestTransactions: Set<ActiveRequestTransaction>, handle: ActiveRequestTransactionHandle): void;
+//# sourceMappingURL=request-transaction.d.ts.map

package/dist/request-transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-transaction.d.ts","sourceRoot":"","sources":["../src/request-transaction.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,mBAAmB,GAAG;IAChC,UAAU,EAAE,eAAe,CAAC;IAC5B,OAAO,IAAI,IAAI,CAAC;IAChB,MAAM,EAAE,WAAW,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC9B,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,8BAA8B,GAAG;IAC3C,MAAM,EAAE,wBAAwB,CAAC;IACjC,MAAM,IAAI,IAAI,CAAC;CAChB,CAAC;AAEF,wBAAgB,yBAAyB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,mBAAmB,CAiBnF;AAED,wBAAgB,6BAA6B,CAC3C,yBAAyB,EAAE,GAAG,CAAC,wBAAwB,CAAC,EACxD,UAAU,EAAE,eAAe,GAC1B,8BAA8B,CAgBhC;AAED,wBAAgB,+BAA+B,CAC7C,yBAAyB,EAAE,GAAG,CAAC,wBAAwB,CAAC,EACxD,MAAM,EAAE,8BAA8B,GACrC,IAAI,CAGN"}

package/dist/request-transaction.js

@@ -0,0 +1,39 @@
+export function createRequestAbortContext(signal) {
+  const controller = new AbortController();
+  const forwardAbort = () => controller.abort(signal?.reason);
+  if (signal?.aborted) {
+    forwardAbort();
+  } else {
+    signal?.addEventListener('abort', forwardAbort, {
+      once: true
+    });
+  }
+  return {
+    controller,
+    cleanup: () => {
+      signal?.removeEventListener('abort', forwardAbort);
+    },
+    signal: controller.signal
+  };
+}
+export function trackActiveRequestTransaction(activeRequestTransactions, controller) {
+  let settle;
+  const settled = new Promise(resolve => {
+    settle = resolve;
+  });
+  const active = {
+    abort(reason) {
+      controller.abort(reason);
+    },
+    settled
+  };
+  activeRequestTransactions.add(active);
+  return {
+    active,
+    settle
+  };
+}
+export function untrackActiveRequestTransaction(activeRequestTransactions, handle) {
+  activeRequestTransactions.delete(handle.active);
+  handle.settle();
+}

package/dist/tokens.d.ts

@@ -0,0 +1,27 @@
+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 { PlatformShell } from './platform-contract.js';
+/**
+ * Injection token for the application logger.
+ */
+export declare const APPLICATION_LOGGER: Token<ApplicationLogger>;
+/**
+ * Injection token for the runtime container.
+ */
+export declare const RUNTIME_CONTAINER: Token<Container>;
+/**
+ * Injection token for the compiled module list.
+ */
+export declare const COMPILED_MODULES: Token<readonly CompiledModule[]>;
+/**
+ * Injection token for the HTTP application adapter.
+ */
+export declare const HTTP_APPLICATION_ADAPTER: Token<HttpApplicationAdapter>;
+/**
+ * Injection token for the platform shell.
+ */
+export declare const PLATFORM_SHELL: Token<PlatformShell>;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -0,0 +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,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5D;;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"}

package/dist/tokens.js

@@ -0,0 +1,24 @@
+/**
+ * Injection token for the application logger.
+ */
+export const APPLICATION_LOGGER = Symbol.for('fluo.runtime.application-logger');
+
+/**
+ * Injection token for the runtime container.
+ */
+export const RUNTIME_CONTAINER = Symbol('RUNTIME_CONTAINER');
+
+/**
+ * Injection token for the compiled module list.
+ */
+export const COMPILED_MODULES = Symbol('COMPILED_MODULES');
+
+/**
+ * Injection token for the HTTP application adapter.
+ */
+export const HTTP_APPLICATION_ADAPTER = Symbol('HTTP_APPLICATION_ADAPTER');
+
+/**
+ * Injection token for the platform shell.
+ */
+export const PLATFORM_SHELL = Symbol('PLATFORM_SHELL');