@bleedingdev/modern-js-server-runtime-extensions 0.0.0-trusted-publisher-bootstrap

package/dist/types/contractGateAutopilot.d.ts

@@ -0,0 +1,35 @@
+import { type ContractGateSnapshotStore } from './contractGateSnapshotStore';
+import type { TelemetryCanaryOrchestrator } from './telemetryCore';
+type LoggerLike = {
+    info?: (message: string) => void;
+    warn?: (message: string) => void;
+};
+export type ContractGateAutopilotOptions = {
+    orchestrator: TelemetryCanaryOrchestrator;
+    gateSnapshotPath?: string;
+    gateSnapshotStore?: ContractGateSnapshotStore;
+    pollIntervalMs?: number;
+    gateStaleAfterMs?: number;
+    logger?: LoggerLike;
+};
+export declare class ContractGateAutopilot {
+    private readonly orchestrator;
+    private readonly gateSnapshotStore;
+    private readonly gateSnapshotPath?;
+    private readonly pollIntervalMs;
+    private readonly gateStaleAfterMs;
+    private readonly logger?;
+    private poller?;
+    private lastSnapshotFingerprint?;
+    private readonly appliedGateFingerprints;
+    constructor(options: ContractGateAutopilotOptions);
+    start(): Promise<void>;
+    stop(): void;
+    syncOnce(): Promise<number>;
+    private loadSnapshot;
+    private normalizeSnapshot;
+    private normalizeGateValue;
+    private normalizeUpdatedAt;
+    private normalizeExpiresAt;
+}
+export {};

package/dist/types/contractGateSnapshotStore.d.ts

@@ -0,0 +1,57 @@
+export declare const CONTRACT_GATE_SNAPSHOT_SCHEMA_VERSION = 1;
+export declare const DEFAULT_CONTRACT_GATE_SNAPSHOT_PATH = ".modern/contract-gates.json";
+export type GateSnapshotGateValue = boolean | {
+    passed?: boolean;
+    reason?: string;
+    updatedAt?: number;
+    expiresAt?: number;
+    [key: string]: unknown;
+};
+export type GateSnapshot = {
+    schemaVersion?: number;
+    updatedAt?: number;
+    gates?: Record<string, GateSnapshotGateValue>;
+};
+type LoggerLike = {
+    info?: (message: string) => void;
+    warn?: (message: string) => void;
+};
+export type ContractGateSnapshotStore = {
+    name: string;
+    readSnapshot: () => Promise<GateSnapshot | undefined>;
+    writeSnapshot: (snapshot: GateSnapshot) => Promise<void>;
+};
+export type ContractGateSnapshotStoreFactoryContext = {
+    appDirectory: string;
+    gateSnapshotPath: string;
+    options?: Record<string, unknown>;
+    logger?: LoggerLike;
+};
+export type ContractGateSnapshotStoreFactory = (context: ContractGateSnapshotStoreFactoryContext) => Promise<ContractGateSnapshotStore> | ContractGateSnapshotStore;
+export type ContractGateSnapshotStoreModule = {
+    createContractGateSnapshotStore?: ContractGateSnapshotStoreFactory;
+    default?: ContractGateSnapshotStoreFactory | {
+        createContractGateSnapshotStore?: ContractGateSnapshotStoreFactory;
+    };
+};
+export type ContractGateSnapshotStoreUserConfig = {
+    module: string;
+    options?: Record<string, unknown>;
+};
+export type ContractGateSnapshotHttpStoreOptions = {
+    endpoint: string;
+    readMethod?: string;
+    writeMethod?: string;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+};
+export declare const createHttpContractGateSnapshotStore: (options: ContractGateSnapshotHttpStoreOptions) => ContractGateSnapshotStore;
+export declare const resolveContractGateSnapshotPath: (appDirectory: string, configuredPath: string | undefined) => string;
+export declare const createFileContractGateSnapshotStore: (gateSnapshotPath: string) => ContractGateSnapshotStore;
+export declare const resolveContractGateSnapshotStore: (input: {
+    appDirectory: string;
+    gateSnapshotPath: string;
+    stateStore?: ContractGateSnapshotStoreUserConfig;
+    logger?: LoggerLike;
+}) => Promise<ContractGateSnapshotStore>;
+export {};

package/dist/types/env.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Single typed pass over the statically-known environment variables consumed
+ * by the ultramodern.js server runtime extensions (telemetry pipeline and
+ * contract-gate canary autopilot).
+ *
+ * Modules in this package read this environment state through
+ * `parseServerRuntimeExtensionsEnv()` so the surface is documented and
+ * testable in one place, with one documented exception: the telemetry
+ * runtime-fallback-signal auth config can name an arbitrary token variable
+ * via `auth.expectedValueEnv`, which is necessarily read dynamically from
+ * `process.env` when that config is normalized. See the package README for
+ * per-variable docs.
+ */
+export declare const DEFAULT_ENVIRONMENT_NAME = "development";
+export interface ServerRuntimeExtensionsEnv {
+    /**
+     * `MODERN_ENV` — deployment environment name loaded by the Modern.js env
+     * bootstrap (`.env.{MODERN_ENV}`). Undefined when unset or blank.
+     */
+    modernEnv?: string;
+    /** `NODE_ENV` — standard Node.js environment name. Undefined when unset or blank. */
+    nodeEnv?: string;
+    /**
+     * Effective telemetry environment label:
+     * `MODERN_ENV` || `NODE_ENV` || `"development"`.
+     */
+    environmentName: string;
+    /**
+     * `MODERN_CONTRACT_GATES_FILE` — path of the contract-gate snapshot file
+     * (absolute, or relative to the app directory). Undefined when unset.
+     */
+    contractGatesFile?: string;
+}
+/**
+ * Parse the statically-known environment variables consumed by this package
+ * in one typed, documented pass. Defaults are applied here so consumers never
+ * touch `process.env` directly (except the documented `expectedValueEnv`
+ * indirection above).
+ */
+export declare const parseServerRuntimeExtensionsEnv: (env?: Record<string, string | undefined>) => ServerRuntimeExtensionsEnv;

package/dist/types/index.d.ts

@@ -0,0 +1,6 @@
+export { ContractGateAutopilot, type ContractGateAutopilotOptions, } from './contractGateAutopilot';
+export { CONTRACT_GATE_SNAPSHOT_SCHEMA_VERSION, type ContractGateSnapshotHttpStoreOptions, type ContractGateSnapshotStore, type ContractGateSnapshotStoreFactory, type ContractGateSnapshotStoreFactoryContext, type ContractGateSnapshotStoreModule, type ContractGateSnapshotStoreUserConfig, createFileContractGateSnapshotStore, createHttpContractGateSnapshotStore, DEFAULT_CONTRACT_GATE_SNAPSHOT_PATH, type GateSnapshot, type GateSnapshotGateValue, resolveContractGateSnapshotPath, resolveContractGateSnapshotStore, } from './contractGateSnapshotStore';
+export { DEFAULT_ENVIRONMENT_NAME, parseServerRuntimeExtensionsEnv, type ServerRuntimeExtensionsEnv, } from './env';
+export { getRequestPathname, injectMfAssetCacheHeadersPlugin, isMfManifestAsset, isMfRemoteEntryAsset, resolveMfAssetCacheHeaders, } from './mfCache';
+export { type CollectDirectRemoteModuleFederationCssOptions, collectDirectRemoteModuleFederationCss, collectDirectRemoteModuleFederationCssWithMeta, collectModuleFederationManifestCss, createModuleFederationCssCollector, injectModuleFederationCssPlugin, type ModuleFederationCssCollectorOptions, type ModuleFederationCssPluginOptions, type ModuleFederationManifest, type RemoteModuleFederationCssCollection, } from './moduleFederationCss';
+export { createOtlpTelemetryExporter, createRuntimeFallbackSignalRuntimeState, createRuntimeSignalError, createTelemetryAwareMetrics, createVictoriaMetricsTelemetryExporter, DEFAULT_RUNTIME_FALLBACK_SIGNAL_ENDPOINT, DEFAULT_RUNTIME_STATUS_ENDPOINT, enforceRuntimeFallbackSignalAuthToken, enforceRuntimeFallbackSignalTrustPolicy, getRuntimeSignalErrorStatusCode, hasEnabledTelemetryExporters, injectTelemetryPlugin, normalizeRequiredRuntimeFallbackSignalAuthConfig, normalizeRuntimeFallbackSignalAuthConfig, normalizeRuntimeFallbackTrustPolicy, type OtlpExporterOptions, parseRuntimeFallbackSignalPayloadFromRawBody, type RuntimeFallbackSignalAuthConfig, type RuntimeFallbackSignalRuntimeState, type RuntimeFallbackSignalSource, type RuntimeFallbackSignalTrustContext, type RuntimeFallbackSignalTrustPolicy, type RuntimeSignalError, type RuntimeSignalErrorCode, resolveRuntimeFallbackSignalEndpoint, resolveTelemetrySloOptions, type TelemetryCanaryDecision, TelemetryCanaryOrchestrator, type TelemetryCanaryStatusSnapshot, type TelemetryEnvelope, type TelemetryExporter, type TelemetryQueueStats, TelemetryRegistry, type TelemetryRegistryOptions, type TelemetrySignalType, type TelemetrySloAlert, TelemetryStartupHealthError, type VictoriaMetricsExporterOptions, } from './telemetry';

package/dist/types/mfCache.d.ts

@@ -0,0 +1,27 @@
+import type { ServerPlugin } from '@modern-js/server-core';
+export declare function getRequestPathname(url: string): string;
+export declare function isMfManifestAsset(pathname: string): boolean;
+export declare function isMfRemoteEntryAsset(pathname: string): boolean;
+export declare function resolveMfAssetCacheHeaders(url: string, query?: Record<string, unknown>): {
+    'cache-control': string;
+    pragma: string;
+    expires: string;
+} | {
+    pragma?: undefined;
+    expires?: undefined;
+    'cache-control': string;
+} | undefined;
+/**
+ * Applies the documented MF asset cache-header policy (ADR-0002) to responses
+ * for module federation manifest/remoteEntry endpoints:
+ *
+ * - `mf-manifest.json` / `mf-stats.json` are never cached (`no-store`), so
+ *   hosts always observe remote redeploys;
+ * - `remoteEntry*.js` revalidates unless explicitly version-pinned via a
+ *   `mfv`/`v`/`version` query parameter, in which case it is immutable.
+ *
+ * Registered by @modern-js/prod-server next to the other fork plugins; the
+ * middleware runs in the `pre` phase so it wraps the static-file middleware
+ * that actually serves these assets.
+ */
+export declare const injectMfAssetCacheHeadersPlugin: () => ServerPlugin;

package/dist/types/moduleFederationCss.d.ts

@@ -0,0 +1,87 @@
+import type { ServerPlugin } from '@modern-js/server-core';
+import type { Monitors } from '@modern-js/types';
+type ModuleFederationAssets = {
+    css?: {
+        sync?: string[];
+        async?: string[];
+    };
+};
+export type ModuleFederationManifest = {
+    metaData?: {
+        publicPath?: string;
+    };
+    shared?: Array<{
+        assets?: ModuleFederationAssets;
+    }>;
+    remotes?: Array<{
+        entry?: string;
+        assets?: ModuleFederationAssets;
+    }>;
+    exposes?: Array<{
+        assets?: ModuleFederationAssets;
+    }>;
+};
+type FetchLike = (input: string, init?: {
+    signal?: AbortSignal;
+}) => Promise<Response>;
+export type CollectDirectRemoteModuleFederationCssOptions = {
+    fetcher?: FetchLike;
+    monitors?: Monitors;
+    timeout?: number;
+};
+export declare const collectModuleFederationManifestCss: (manifest: ModuleFederationManifest, manifestUrl: string) => string[];
+export type RemoteModuleFederationCssCollection = {
+    assets: string[];
+    /**
+     * True when at least one remote manifest fetch failed, i.e. `assets` may be
+     * incomplete and should not be cached long-term.
+     */
+    errored: boolean;
+};
+export declare const collectDirectRemoteModuleFederationCssWithMeta: (pwd: string, options?: CollectDirectRemoteModuleFederationCssOptions) => Promise<RemoteModuleFederationCssCollection>;
+export declare const collectDirectRemoteModuleFederationCss: (pwd: string, options?: CollectDirectRemoteModuleFederationCssOptions) => Promise<string[]>;
+export type ModuleFederationCssCollectorOptions = CollectDirectRemoteModuleFederationCssOptions & {
+    /**
+     * How long a successful remote CSS collection may be served from cache.
+     * `0` disables caching (beyond in-flight request coalescing).
+     */
+    ttlMs?: number;
+    /** Clock override for tests. */
+    now?: () => number;
+};
+/**
+ * TTL cache around remote MF CSS collection. Remote manifests mutate
+ * independently of the host (that is the point of module federation), so the
+ * collection must expire: a boot-time-forever cache serves stale or broken
+ * CSS links after any remote redeploy.
+ *
+ * Error handling: a collection where any remote fetch failed is never cached.
+ * The last known-good asset list is served instead (stale-on-error) and the
+ * next request retries the collection.
+ */
+export declare const createModuleFederationCssCollector: (pwd: string, options?: ModuleFederationCssCollectorOptions) => {
+    collect(monitors?: Monitors): Promise<string[]>;
+};
+export type ModuleFederationCssPluginOptions = {
+    /**
+     * TTL for the cached remote CSS collection in production.
+     *
+     * @default 30000 in production, 0 (no caching) otherwise
+     */
+    remoteCssCacheTtlMs?: number;
+};
+/**
+ * Enriches the request-scoped server manifest with CSS assets collected from
+ * direct module federation remotes, so SSR/CSR-RSC rendering can inline
+ * `<link>` tags for remote CSS.
+ *
+ * In production the collection is cached with a TTL (default 30s) instead of
+ * being pinned at boot: remote manifests change on every remote redeploy, and
+ * fetch failures must not pin an empty/partial list for the process lifetime.
+ *
+ * This plugin must be registered after `injectResourcePlugin()` (which sets
+ * `serverManifest` on the request context). @modern-js/prod-server wires it
+ * into its plugin assembly for both production and dev servers.
+ */
+export declare const injectModuleFederationCssPlugin: (options?: ModuleFederationCssPluginOptions) => ServerPlugin;
+export {};

package/dist/types/runtimeFallbackSignal.d.ts

@@ -0,0 +1,94 @@
+import type { Context, ServerEnv } from '@modern-js/server-core';
+import { type ContractGateSnapshotStore } from './contractGateSnapshotStore';
+export declare const DEFAULT_RUNTIME_FALLBACK_SIGNAL_ENDPOINT = "/_modern/contract-gates/runtime-fallback";
+export declare const DEFAULT_RUNTIME_STATUS_ENDPOINT = "/_modern/runtime/status";
+export declare const DEFAULT_RUNTIME_FALLBACK_GATE_NAME = "runtime-mf-fallback-health";
+export declare const DEFAULT_RUNTIME_FALLBACK_FAILURE_HOLD_MS: number;
+export declare const DEFAULT_RUNTIME_FALLBACK_MAX_BODY_BYTES: number;
+export type RuntimeSignalErrorCode = 'PAYLOAD_TOO_LARGE' | 'INVALID_PAYLOAD' | 'RATE_LIMITED' | 'UNAUTHORIZED' | 'UNTRUSTED_SOURCE';
+export type RuntimeSignalError = Error & {
+    code?: RuntimeSignalErrorCode;
+};
+export type RuntimeFallbackSignalTrustPolicy = {
+    allowedApps: string[];
+    allowedEntryOrigins: string[];
+    expectedRuntimeDigests: Record<string, string>;
+    enforceRuntimeDigest: boolean;
+    maxSignalsPerWindow: number;
+    windowMs: number;
+    dedupeWindowMs: number;
+};
+type RuntimeFallbackSignalRateLimitState = {
+    count: number;
+    windowStartedAt: number;
+};
+export type RuntimeFallbackSignalAuthConfig = {
+    enabled: boolean;
+    headerName: string;
+    expectedValue?: string;
+};
+export type RuntimeFallbackSignalRuntimeState = {
+    rateLimitBySource: Map<string, RuntimeFallbackSignalRateLimitState>;
+    dedupeByFingerprint: Map<string, number>;
+};
+export type RuntimeFallbackSignalTrustContext = {
+    trustPolicy: RuntimeFallbackSignalTrustPolicy;
+    runtimeState: RuntimeFallbackSignalRuntimeState;
+};
+export type RuntimeFallbackSignalConfig = {
+    endpoint: string;
+    gateName: string;
+    gateSnapshotStore: Promise<ContractGateSnapshotStore>;
+    failureHoldMs: number;
+    maxBodyBytes: number;
+    auth: RuntimeFallbackSignalAuthConfig;
+    trustPolicy: RuntimeFallbackSignalTrustPolicy;
+    runtimeState: RuntimeFallbackSignalRuntimeState;
+};
+export declare function resolveRuntimeFallbackSignalEndpoint(configuredEndpoint?: string): string;
+export declare function createRuntimeSignalError(message: string, code: RuntimeSignalError['code']): RuntimeSignalError;
+export declare function normalizeRuntimeFallbackSignalAuthConfig(configured: {
+    enabled?: boolean;
+    headerName?: string;
+    expectedValue?: string;
+    expectedValueEnv?: string;
+} | undefined): RuntimeFallbackSignalAuthConfig;
+/**
+ * Normalizes the auth config for the runtime fallback signal endpoint when the
+ * endpoint itself is enabled. The endpoint can persist failing contract gates
+ * (a canary kill switch), so it always requires a token: auth cannot be
+ * disabled and a token must be configured via `auth.expectedValue` or
+ * `auth.expectedValueEnv`.
+ */
+export declare function normalizeRequiredRuntimeFallbackSignalAuthConfig(configured: Parameters<typeof normalizeRuntimeFallbackSignalAuthConfig>[0]): RuntimeFallbackSignalAuthConfig;
+export declare function enforceRuntimeFallbackSignalAuthToken(token: string | undefined, authConfig: RuntimeFallbackSignalAuthConfig): void;
+export declare function enforceRuntimeFallbackSignalAuth(c: Context<ServerEnv>, runtimeSignalConfig: RuntimeFallbackSignalConfig): void;
+export declare function normalizeRuntimeFallbackTrustPolicy(configured: {
+    allowedApps?: string[];
+    allowedEntryOrigins?: string[];
+    expectedRuntimeDigests?: Record<string, string>;
+    enforceRuntimeDigest?: boolean;
+    maxSignalsPerWindow?: number;
+    windowMs?: number;
+    dedupeWindowMs?: number;
+} | undefined): RuntimeFallbackSignalTrustPolicy;
+export declare function createRuntimeFallbackSignalRuntimeState(): RuntimeFallbackSignalRuntimeState;
+export type RuntimeFallbackSignalSource = {
+    /**
+     * Server-trusted connection identity (socket remote address). Never derive
+     * this from request headers or the payload: both are attacker-controlled
+     * and would let callers reset their own rate-limit budget.
+     */
+    remoteAddress?: string;
+};
+export declare function enforceRuntimeFallbackSignalTrustPolicy(payload: Record<string, unknown>, runtimeSignalContext: RuntimeFallbackSignalTrustContext, source?: RuntimeFallbackSignalSource): {
+    deduped: boolean;
+};
+export declare function parseRuntimeFallbackSignalPayload(c: Context<ServerEnv>, maxBodyBytes: number): Promise<{
+    rawBody: string;
+    payload: Record<string, unknown>;
+}>;
+export declare function parseRuntimeFallbackSignalPayloadFromRawBody(rawBody: string, maxBodyBytes: number): Record<string, unknown>;
+export declare function getRuntimeSignalErrorStatusCode(signalError: RuntimeSignalError): 400 | 401 | 403 | 413 | 429 | 500;
+export declare function persistRuntimeFallbackContractGate(payload: Record<string, unknown>, runtimeSignalConfig: RuntimeFallbackSignalConfig): Promise<void>;
+export {};

package/dist/types/telemetry.d.ts

@@ -0,0 +1,12 @@
+import type { ServerPlugin, ServerTelemetryUserConfig } from '@modern-js/server-core';
+import { type TelemetryRegistryOptions } from './telemetryCore';
+export { createRuntimeFallbackSignalRuntimeState, createRuntimeSignalError, DEFAULT_RUNTIME_FALLBACK_SIGNAL_ENDPOINT, DEFAULT_RUNTIME_STATUS_ENDPOINT, enforceRuntimeFallbackSignalAuthToken, enforceRuntimeFallbackSignalTrustPolicy, getRuntimeSignalErrorStatusCode, normalizeRequiredRuntimeFallbackSignalAuthConfig, normalizeRuntimeFallbackSignalAuthConfig, normalizeRuntimeFallbackTrustPolicy, parseRuntimeFallbackSignalPayloadFromRawBody, type RuntimeFallbackSignalAuthConfig, type RuntimeFallbackSignalRuntimeState, type RuntimeFallbackSignalSource, type RuntimeFallbackSignalTrustContext, type RuntimeFallbackSignalTrustPolicy, type RuntimeSignalError, type RuntimeSignalErrorCode, resolveRuntimeFallbackSignalEndpoint, } from './runtimeFallbackSignal';
+export { createOtlpTelemetryExporter, createTelemetryAwareMetrics, createVictoriaMetricsTelemetryExporter, type OtlpExporterOptions, type TelemetryCanaryAction, type TelemetryCanaryContractGateStatus, type TelemetryCanaryDecision, type TelemetryCanaryFailure, type TelemetryCanaryFailureReason, TelemetryCanaryOrchestrator, type TelemetryCanaryOrchestratorOptions, type TelemetryCanaryState, type TelemetryCanaryStatusSnapshot, type TelemetryEnvelope, type TelemetryExporter, type TelemetryExporterHealthStatus, type TelemetryQueueStats, TelemetryRegistry, type TelemetryRegistryOptions, type TelemetrySignalType, type TelemetrySloAlert, type TelemetrySloAlertType, TelemetryStartupHealthError, type VictoriaMetricsExporterOptions, } from './telemetryCore';
+export declare const hasEnabledTelemetryExporters: (config: ServerTelemetryUserConfig | undefined) => boolean;
+/**
+ * Builds the registry SLO options from `server.telemetry.slo`, attaching a
+ * logger sink so threshold breaches surface as server warnings (parity with
+ * the pre-extraction prod-server harness).
+ */
+export declare const resolveTelemetrySloOptions: (sloConfig: ServerTelemetryUserConfig['slo'], warnSink?: (message: string) => void) => NonNullable<TelemetryRegistryOptions['slo']>;
+export declare const injectTelemetryPlugin: () => ServerPlugin;

package/dist/types/telemetryCore.d.ts

@@ -0,0 +1,257 @@
+import type { Metrics, MonitorEvent } from '@modern-js/types';
+export type TelemetrySignalType = 'log' | 'metric' | 'trace';
+export interface TelemetryEnvelope {
+    timestamp: number;
+    service: string;
+    module: string;
+    environment: string;
+    signalType: TelemetrySignalType;
+    name: string;
+    level?: string;
+    value?: number;
+    unit?: string;
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    tags?: Record<string, string>;
+    attributes?: Record<string, unknown>;
+    error?: {
+        name?: string;
+        message: string;
+        stack?: string;
+    };
+}
+export interface TelemetryExporter {
+    name: string;
+    init?: (context: {
+        service: string;
+        module: string;
+        environment: string;
+    }) => void | Promise<void>;
+    emit: (batch: TelemetryEnvelope[]) => void | Promise<void>;
+    flush?: () => void | Promise<void>;
+    shutdown?: () => void | Promise<void>;
+}
+export interface TelemetryRegistryOptions {
+    service: string;
+    module: string;
+    environment: string;
+    samplingRate?: number;
+    flushIntervalMs?: number;
+    maxBatchSize?: number;
+    maxQueueSize?: number;
+    redactionKeys?: string[];
+    slo?: {
+        queueUtilizationWarnThreshold?: number;
+        queueDroppedWarnThreshold?: number;
+        alertCooldownMs?: number;
+        onAlert?: (alert: TelemetrySloAlert) => void;
+    };
+}
+export type TelemetrySloAlertType = 'queue.utilization' | 'queue.drop';
+export interface TelemetrySloAlert {
+    timestamp: number;
+    service: string;
+    module: string;
+    environment: string;
+    type: TelemetrySloAlertType;
+    value: number;
+    threshold: number;
+    queueDepth: number;
+    queueCapacity: number;
+    queueUtilization: number;
+    totalDropped: number;
+}
+export interface TelemetryQueueStats {
+    depth: number;
+    capacity: number;
+    utilization: number;
+    pendingDropped: number;
+    totalDropped: number;
+}
+export type TelemetryCanaryState = 'canary' | 'promoted' | 'rolled_back';
+export type TelemetryCanaryAction = 'hold' | 'promote' | 'rollback';
+export type TelemetryCanaryFailureReason = 'queue_utilization' | 'queue_dropped' | 'unhealthy_exporter' | 'contract_gate_missing' | 'contract_gate_failed';
+export interface TelemetryCanaryFailure {
+    reason: TelemetryCanaryFailureReason;
+    gate?: string;
+    message?: string;
+    threshold?: number;
+    value?: number;
+}
+export interface TelemetryCanaryContractGateStatus {
+    name: string;
+    passed: boolean;
+    reason?: string;
+    updatedAt: number;
+}
+export interface TelemetryCanaryDecision {
+    timestamp: number;
+    action: TelemetryCanaryAction;
+    state: TelemetryCanaryState;
+    consecutiveHealthy: number;
+    consecutiveFailures: number;
+    failures: TelemetryCanaryFailure[];
+    queueStats: TelemetryQueueStats;
+    unhealthyExporterCount: number;
+    contractGates: TelemetryCanaryContractGateStatus[];
+}
+export interface TelemetryCanaryStatusSnapshot {
+    timestamp: number;
+    state: TelemetryCanaryState;
+    consecutiveHealthy: number;
+    consecutiveFailures: number;
+    queueStats: TelemetryQueueStats;
+    unhealthyExporterCount: number;
+    requiredContractGates: string[];
+    contractGates: TelemetryCanaryContractGateStatus[];
+    failurePreview: TelemetryCanaryFailure[];
+}
+export interface TelemetryCanaryOrchestratorOptions {
+    registry: TelemetryRegistry;
+    evaluationIntervalMs?: number;
+    minConsecutiveHealthyEvaluations?: number;
+    rollbackConsecutiveFailures?: number;
+    maxQueueUtilization?: number;
+    maxTotalDropped?: number;
+    maxUnhealthyExporters?: number;
+    requiredContractGates?: string[];
+    onEvaluate?: (decision: TelemetryCanaryDecision) => void;
+    onPromote?: (decision: TelemetryCanaryDecision) => void;
+    onRollback?: (decision: TelemetryCanaryDecision) => void;
+}
+export interface TelemetryExporterHealthStatus {
+    name: string;
+    healthy: boolean;
+    failures: number;
+    lastError?: string;
+    lastSuccessAt?: number;
+    lastFailureAt?: number;
+}
+export declare class TelemetryStartupHealthError extends Error {
+    readonly code = "TELEMETRY_EXPORTER_STARTUP_HEALTH_FAILED";
+    readonly failedExporters: TelemetryExporterHealthStatus[];
+    constructor(failedExporters: TelemetryExporterHealthStatus[]);
+}
+export interface OtlpExporterOptions {
+    endpoint?: string;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}
+export interface VictoriaMetricsExporterOptions extends OtlpExporterOptions {
+    metricPrefix?: string;
+}
+export declare function toTelemetryEnvelope(event: MonitorEvent, input: {
+    service: string;
+    module: string;
+    environment: string;
+    traceId?: string;
+    spanId?: string;
+    attributes?: Record<string, unknown>;
+}): TelemetryEnvelope;
+export declare function createOtlpTelemetryExporter(options?: OtlpExporterOptions): TelemetryExporter;
+export declare function createVictoriaMetricsTelemetryExporter(options?: VictoriaMetricsExporterOptions): TelemetryExporter;
+export declare class TelemetryRegistry {
+    private readonly exporters;
+    private readonly queue;
+    private readonly redactionKeys;
+    private readonly service;
+    private readonly module;
+    private readonly environment;
+    private readonly samplingRate;
+    private readonly maxBatchSize;
+    private readonly maxQueueSize;
+    private readonly flushIntervalMs;
+    private readonly flushTimer?;
+    private droppedCount;
+    private totalDroppedCount;
+    private flushing;
+    private readonly exporterHealth;
+    private readonly queueUtilizationWarnThreshold;
+    private readonly queueDroppedWarnThreshold;
+    private readonly alertCooldownMs;
+    private readonly onSloAlert?;
+    private readonly lastSloAlertAt;
+    constructor(options: TelemetryRegistryOptions);
+    register(exporter: TelemetryExporter): Promise<void>;
+    private getOrCreateExporterHealth;
+    private markExporterHealthy;
+    private markExporterFailure;
+    private maybeEmitSloAlert;
+    enqueue(envelope: TelemetryEnvelope): void;
+    enqueueMetric(input: {
+        name: string;
+        value: number;
+        unit?: string;
+        traceId?: string;
+        spanId?: string;
+        parentSpanId?: string;
+        tags?: Record<string, string>;
+        attributes?: Record<string, unknown>;
+    }): void;
+    enqueueLog(input: {
+        name: string;
+        level: string;
+        traceId?: string;
+        spanId?: string;
+        parentSpanId?: string;
+        tags?: Record<string, string>;
+        attributes?: Record<string, unknown>;
+        error?: TelemetryEnvelope['error'];
+    }): void;
+    enqueueTrace(input: {
+        name: string;
+        traceId?: string;
+        spanId?: string;
+        parentSpanId?: string;
+        tags?: Record<string, string>;
+        attributes?: Record<string, unknown>;
+    }): void;
+    private buildDroppedEnvelope;
+    private buildQueueDepthEnvelope;
+    private buildQueueUtilizationEnvelope;
+    private emitBatch;
+    private buildStartupProbeEnvelope;
+    startupHealthCheck(options?: {
+        failLoud?: boolean;
+    }): Promise<void>;
+    getExporterHealth(): TelemetryExporterHealthStatus[];
+    getQueueStats(): TelemetryQueueStats;
+    private flushInternal;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export declare class TelemetryCanaryOrchestrator {
+    private readonly registry;
+    private readonly evaluationIntervalMs;
+    private readonly minConsecutiveHealthyEvaluations;
+    private readonly rollbackConsecutiveFailures;
+    private readonly maxQueueUtilization;
+    private readonly maxTotalDropped;
+    private readonly maxUnhealthyExporters;
+    private requiredContractGates;
+    private readonly onEvaluate?;
+    private readonly onPromote?;
+    private readonly onRollback?;
+    private readonly contractGates;
+    private state;
+    private consecutiveHealthy;
+    private consecutiveFailures;
+    private evaluationTimer?;
+    constructor(options: TelemetryCanaryOrchestratorOptions);
+    setRequiredContractGates(gates: string[]): void;
+    addRequiredContractGate(name: string): void;
+    setContractGate(name: string, passed: boolean, reason?: string): void;
+    setContractGates(gates: Record<string, boolean | {
+        passed: boolean;
+        reason?: string;
+    }>): void;
+    resetToCanary(): void;
+    private collectFailures;
+    evaluate(): TelemetryCanaryDecision;
+    getStatusSnapshot(): TelemetryCanaryStatusSnapshot;
+    start(): void;
+    stop(): void;
+}
+export declare const createTelemetryAwareMetrics: <T extends Metrics>(baseMetrics: T, registry: TelemetryRegistry) => T;
+export declare function maybeWarnLegacyOtlpEndpoint(endpoint: string | undefined): void;