@x12i/ai-gateway 9.6.7 → 9.6.9

package/dist/defaults/log-diagnostics.json

@@ -0,0 +1,176 @@
+{
+  "GATEWAY_ZERO_USAGE_OR_COST": {
+    "defaultLevel": "warn",
+    "title": "Successful invoke reported zero token usage and/or zero cost",
+    "impact": "Billing and usage metadata may be missing from the provider adapter.",
+    "possibleCauses": [
+      "Router adapter did not populate usage fields.",
+      "Provider response omitted token counts.",
+      "Cost calculation was skipped or returned zero."
+    ],
+    "remediation": [
+      "Verify router adapter usage extraction.",
+      "Confirm ai-tools cost resolution is enabled when pricing is expected."
+    ],
+    "retryable": false,
+    "userActionRequired": false,
+    "confidence": "medium"
+  },
+  "GATEWAY_FALLBACK_CHAIN_EXHAUSTED": {
+    "defaultLevel": "error",
+    "title": "Provider fallback chain exhausted without a successful response",
+    "impact": "The AI request failed after all configured provider/model candidates were tried.",
+    "possibleCauses": [
+      "All providers in the chain returned errors.",
+      "Rate limits or auth failures across candidates.",
+      "Model or profile misconfiguration."
+    ],
+    "remediation": [
+      "Inspect fallbackAttempts in the log evidence.",
+      "Verify API keys and provider registration.",
+      "Review trace-mode metadata.attempts when enabled."
+    ],
+    "retryable": true,
+    "userActionRequired": true,
+    "confidence": "high"
+  },
+  "GATEWAY_FLEX_MD_EXTRACTION_FAILED": {
+    "defaultLevel": "warn",
+    "title": "Flex-md extraction did not produce structured output",
+    "impact": "Parsed content falls back to a rawText wrapper; downstream contract validation may fail.",
+    "possibleCauses": [
+      "Model response was plain text without expected markdown structure.",
+      "flex-md headers or fenced blocks were missing.",
+      "Response was truncated before structured content completed."
+    ],
+    "remediation": [
+      "Inspect raw response sample.",
+      "Tighten instructions for markdown/JSON output format.",
+      "Check max token allocation."
+    ],
+    "retryable": true,
+    "userActionRequired": false,
+    "confidence": "medium"
+  },
+  "GATEWAY_FLEX_MD_EXTRACTION_ERROR": {
+    "defaultLevel": "warn",
+    "title": "Flex-md extraction threw during parsing",
+    "impact": "Structured parsing failed; gateway uses rawText fallback.",
+    "possibleCauses": [
+      "flex-md library compatibility or loader issue.",
+      "Malformed markdown in the model response.",
+      "Unexpected response shape from the provider."
+    ],
+    "remediation": [
+      "Review the exception evidence.",
+      "Confirm flex-md version alignment with the gateway.",
+      "Inspect raw provider content."
+    ],
+    "retryable": true,
+    "userActionRequired": false,
+    "confidence": "medium"
+  },
+  "GATEWAY_DEFAULT_MODEL_SUBSTITUTED": {
+    "defaultLevel": "warn",
+    "title": "Gateway substituted the configured default model",
+    "impact": "The request may run on a different provider/model than the caller specified.",
+    "possibleCauses": [
+      "Request omitted model while gateway defaults apply.",
+      "Operational mode requires a packaged default engine.",
+      "Profile resolution fell back to gateway defaults."
+    ],
+    "remediation": [
+      "Pass an explicit model on the request when substitution is undesired.",
+      "Review default model configuration and AI_TOOLS routing."
+    ],
+    "retryable": false,
+    "userActionRequired": false,
+    "confidence": "high"
+  },
+  "GATEWAY_RETRY_MAX_EXCEEDED": {
+    "defaultLevel": "warn",
+    "title": "Provider invoke retries exhausted",
+    "impact": "The router call failed after the configured retry budget.",
+    "possibleCauses": [
+      "Transient network or server errors persisted.",
+      "Throttling (429) without sufficient backoff.",
+      "Non-recoverable provider outage."
+    ],
+    "remediation": [
+      "Inspect error and status code evidence.",
+      "Increase retry limits or backoff if appropriate.",
+      "Check provider status and rate limits."
+    ],
+    "retryable": true,
+    "userActionRequired": false,
+    "confidence": "high"
+  },
+  "GATEWAY_RETRY_ATTEMPT": {
+    "defaultLevel": "warn",
+    "title": "Retrying provider invoke after error",
+    "impact": "Request latency increases while the gateway retries.",
+    "possibleCauses": [
+      "Transient HTTP or network failure.",
+      "Rate limiting with backoff.",
+      "Timeout from the provider."
+    ],
+    "remediation": [
+      "Monitor retry counts per job.",
+      "Tune retry policy if retries are frequent."
+    ],
+    "retryable": true,
+    "userActionRequired": false,
+    "confidence": "medium"
+  },
+  "GATEWAY_OPTIMIXER_ACTIVIX_UNAVAILABLE": {
+    "defaultLevel": "warn",
+    "title": "Optimixer enabled but Activix is unavailable",
+    "impact": "Adaptive max_tokens prediction is disabled for this gateway instance.",
+    "possibleCauses": [
+      "Activity tracking is disabled or Activix failed to initialize.",
+      "Mongo connection or collection configuration is missing."
+    ],
+    "remediation": [
+      "Enable activity tracking with a working Activix connection.",
+      "Verify activixCollection configuration."
+    ],
+    "retryable": false,
+    "userActionRequired": true,
+    "confidence": "high"
+  },
+  "GATEWAY_OPTIMIXER_INIT_FAILED": {
+    "defaultLevel": "warn",
+    "title": "Optimixer initialization failed",
+    "impact": "Adaptive max_tokens prediction is disabled.",
+    "possibleCauses": [
+      "Activix schema or collection mismatch.",
+      "Optimixer configuration error.",
+      "Dependency or network failure during create()."
+    ],
+    "remediation": [
+      "Check Activix connectivity and collection names.",
+      "Review optimixer gateway config."
+    ],
+    "retryable": false,
+    "userActionRequired": true,
+    "confidence": "high"
+  },
+  "GATEWAY_OPTIMIXER_PREDICT_FAILED": {
+    "defaultLevel": "warn",
+    "title": "Optimixer predictAiMaxTokens failed",
+    "impact": "Caller should use fallback max_tokens for the invoke.",
+    "possibleCauses": [
+      "Insufficient historical samples for the template.",
+      "Token estimation or profile resolution failed.",
+      "Optimixer internal error."
+    ],
+    "remediation": [
+      "Set explicit max_tokens on the request.",
+      "Verify templateId and model profile fields.",
+      "Check prediction history in Activix."
+    ],
+    "retryable": true,
+    "userActionRequired": false,
+    "confidence": "medium"
+  }
+}

package/dist/gateway-config.js

@@ -162,7 +162,10 @@ export function initializeGatewayComponents(config) {
     const logger = createGatewayLogger({
         enableLogging: config.enableLogging ?? true,
         packageName: config.packageName,
-        customLogger: config.logger
+        customLogger: config.logger,
+        logging: config.logging,
+        packageLogLevels: config.packageLogLevels,
+        logLevel: config.logLevel
     });
     const { defaultModelConfig, defaultInstructionsBlocks, defaultTemplateRendering } = loadConfig(logger);
     logger.verbose('Gateway initializing', {
@@ -194,6 +197,12 @@ export function initializeGatewayComponents(config) {
         routerConfig.autoDiscover = config.autoDiscover;
     if (config.usageTracker !== undefined)
         routerConfig.usageTracker = config.usageTracker;
+    if (config.verbose !== undefined)
+        routerConfig.verbose = config.verbose;
+    if (config.logLevel !== undefined)
+        routerConfig.logLevel = config.logLevel;
+    if (config.logging !== undefined)
+        routerConfig.logging = config.logging;
     // OpenRouter: always pass apiKey when set (fallback for providers without direct keys).
     // USE_OPENROUTER=false only disables *preferring* OpenRouter when direct provider keys exist.
     const openRouterKey = resolveOpenRouterApiKey(config);

package/dist/gateway-log-diagnostics.d.ts

@@ -0,0 +1,23 @@
+import { exceptionEvidence, fieldEvidence, type LogMeta, type Logxer } from '@x12i/logxer';
+import type { ActivityIdentity } from './types.js';
+export { exceptionEvidence, fieldEvidence };
+/** Stable diagnostic codes backed by `src/defaults/log-diagnostics.json`. */
+export declare const GatewayLogCode: {
+    readonly ZERO_USAGE_OR_COST: "GATEWAY_ZERO_USAGE_OR_COST";
+    readonly FALLBACK_CHAIN_EXHAUSTED: "GATEWAY_FALLBACK_CHAIN_EXHAUSTED";
+    readonly FLEX_MD_EXTRACTION_FAILED: "GATEWAY_FLEX_MD_EXTRACTION_FAILED";
+    readonly FLEX_MD_EXTRACTION_ERROR: "GATEWAY_FLEX_MD_EXTRACTION_ERROR";
+    readonly DEFAULT_MODEL_SUBSTITUTED: "GATEWAY_DEFAULT_MODEL_SUBSTITUTED";
+    readonly RETRY_MAX_EXCEEDED: "GATEWAY_RETRY_MAX_EXCEEDED";
+    readonly RETRY_ATTEMPT: "GATEWAY_RETRY_ATTEMPT";
+    readonly OPTIMIXER_ACTIVIX_UNAVAILABLE: "GATEWAY_OPTIMIXER_ACTIVIX_UNAVAILABLE";
+    readonly OPTIMIXER_INIT_FAILED: "GATEWAY_OPTIMIXER_INIT_FAILED";
+    readonly OPTIMIXER_PREDICT_FAILED: "GATEWAY_OPTIMIXER_PREDICT_FAILED";
+};
+export type GatewayLogCode = (typeof GatewayLogCode)[keyof typeof GatewayLogCode];
+/** Resolve packaged `defaults/log-diagnostics.json` for createLogxer diagnostics.catalogPath. */
+export declare function resolveLogDiagnosticsCatalogPath(): string | undefined;
+export declare function gatewayWarnCode(logger: Logxer, code: GatewayLogCode | string, identity: Partial<ActivityIdentity> | undefined, data?: LogMeta): void;
+export declare function gatewayErrorCode(logger: Logxer, code: GatewayLogCode | string, identity: Partial<ActivityIdentity> | undefined, data?: LogMeta): void;
+export declare function gatewayInfoCode(logger: Logxer, code: GatewayLogCode | string, identity: Partial<ActivityIdentity> | undefined, data?: LogMeta): void;
+export declare function gatewayAnomalyMeta(identity: Partial<ActivityIdentity> | undefined, data?: LogMeta): LogMeta;

package/dist/gateway-log-diagnostics.js

@@ -0,0 +1,72 @@
+/**
+ * Logxer 4.4+ diagnostic catalog codes and helpers for structured anomaly logging.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { exceptionEvidence, fieldEvidence } from '@x12i/logxer';
+import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
+export { exceptionEvidence, fieldEvidence };
+/** Stable diagnostic codes backed by `src/defaults/log-diagnostics.json`. */
+export const GatewayLogCode = {
+    ZERO_USAGE_OR_COST: 'GATEWAY_ZERO_USAGE_OR_COST',
+    FALLBACK_CHAIN_EXHAUSTED: 'GATEWAY_FALLBACK_CHAIN_EXHAUSTED',
+    FLEX_MD_EXTRACTION_FAILED: 'GATEWAY_FLEX_MD_EXTRACTION_FAILED',
+    FLEX_MD_EXTRACTION_ERROR: 'GATEWAY_FLEX_MD_EXTRACTION_ERROR',
+    DEFAULT_MODEL_SUBSTITUTED: 'GATEWAY_DEFAULT_MODEL_SUBSTITUTED',
+    RETRY_MAX_EXCEEDED: 'GATEWAY_RETRY_MAX_EXCEEDED',
+    RETRY_ATTEMPT: 'GATEWAY_RETRY_ATTEMPT',
+    OPTIMIXER_ACTIVIX_UNAVAILABLE: 'GATEWAY_OPTIMIXER_ACTIVIX_UNAVAILABLE',
+    OPTIMIXER_INIT_FAILED: 'GATEWAY_OPTIMIXER_INIT_FAILED',
+    OPTIMIXER_PREDICT_FAILED: 'GATEWAY_OPTIMIXER_PREDICT_FAILED'
+};
+function getModuleDir() {
+    if (typeof __dirname !== 'undefined') {
+        return __dirname;
+    }
+    try {
+        const getMetaUrl = new Function('return import.meta.url');
+        const metaUrl = getMetaUrl();
+        if (metaUrl && metaUrl.startsWith('file:')) {
+            return path.dirname(fileURLToPath(metaUrl));
+        }
+    }
+    catch {
+        // fall through
+    }
+    return process.cwd();
+}
+/** Resolve packaged `defaults/log-diagnostics.json` for createLogxer diagnostics.catalogPath. */
+export function resolveLogDiagnosticsCatalogPath() {
+    const moduleDir = getModuleDir();
+    const cwd = process.cwd();
+    const candidates = [
+        moduleDir,
+        path.resolve(moduleDir, '..'),
+        path.resolve(moduleDir, '../dist'),
+        path.resolve(moduleDir, '../dist-cjs'),
+        path.resolve(moduleDir, '../src'),
+        path.join(cwd, 'dist'),
+        path.join(cwd, 'dist-cjs'),
+        path.join(cwd, 'src')
+    ];
+    for (const dir of candidates) {
+        const catalogPath = path.join(dir, 'defaults', 'log-diagnostics.json');
+        if (fs.existsSync(catalogPath)) {
+            return catalogPath;
+        }
+    }
+    return undefined;
+}
+export function gatewayWarnCode(logger, code, identity, data) {
+    logger.warnCode(code, withActivityIdentity(identity, data));
+}
+export function gatewayErrorCode(logger, code, identity, data) {
+    logger.errorCode(code, withActivityIdentity(identity, data));
+}
+export function gatewayInfoCode(logger, code, identity, data) {
+    logger.infoCode(code, withActivityIdentity(identity, data));
+}
+export function gatewayAnomalyMeta(identity, data) {
+    return withActivityIdentity(identity, data, gatewayLogDebug.anomaly);
+}

package/dist/gateway-log-levels.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Logxer ≥ 4.5 — process-wide package log levels for the gateway dependency stack.
+ * @see node_modules/@x12i/logxer/docs/package-log-levels-stack.md
+ */
+import { type PackageLogLevelsConfig } from '@x12i/logxer';
+/** Stable ERC 2.0 env prefix — controls `AI_GATEWAY_LOGS_LEVEL`, etc. */
+export declare const GATEWAY_LOG_ENV_PREFIX = "AI_GATEWAY";
+/** Known `envPrefix` values in this package's dependency stack (for hosts / `.env`). */
+export declare const GATEWAY_STACK_LOG_PREFIXES: {
+    readonly gateway: "AI_GATEWAY";
+    readonly router: "AI_PROVIDER_ROUTER";
+    readonly flexMd: "FLEX_MD";
+    readonly optimixer: "OPTIMIXER";
+};
+/**
+ * Load bulk env (`LOGXER_PACKAGE_LEVELS`, `LOGXER_PACKAGE_LOGS_DEFAULT`) and merge optional host config.
+ * Idempotent — safe to call from `createGatewayLogger` / `initializeGatewayComponents`.
+ */
+export declare function initializeGatewayPackageLogLevels(options?: {
+    packageLogLevels?: PackageLogLevelsConfig;
+}): void;
+/** Reset init flag (tests). */
+export declare function resetGatewayPackageLogLevelsInit(): void;

package/dist/gateway-log-levels.js

@@ -0,0 +1,33 @@
+/**
+ * Logxer ≥ 4.5 — process-wide package log levels for the gateway dependency stack.
+ * @see node_modules/@x12i/logxer/docs/package-log-levels-stack.md
+ */
+import { applyPackageLogLevelsFromEnv, mergePackageLogLevelsConfig } from '@x12i/logxer';
+import { ROUTER_LOG_ENV_PREFIX } from '@x12i/ai-providers-router';
+/** Stable ERC 2.0 env prefix — controls `AI_GATEWAY_LOGS_LEVEL`, etc. */
+export const GATEWAY_LOG_ENV_PREFIX = 'AI_GATEWAY';
+/** Known `envPrefix` values in this package's dependency stack (for hosts / `.env`). */
+export const GATEWAY_STACK_LOG_PREFIXES = {
+    gateway: GATEWAY_LOG_ENV_PREFIX,
+    router: ROUTER_LOG_ENV_PREFIX,
+    flexMd: 'FLEX_MD',
+    optimixer: 'OPTIMIXER'
+};
+let packageLogLevelsInitialized = false;
+/**
+ * Load bulk env (`LOGXER_PACKAGE_LEVELS`, `LOGXER_PACKAGE_LOGS_DEFAULT`) and merge optional host config.
+ * Idempotent — safe to call from `createGatewayLogger` / `initializeGatewayComponents`.
+ */
+export function initializeGatewayPackageLogLevels(options) {
+    if (!packageLogLevelsInitialized) {
+        applyPackageLogLevelsFromEnv();
+        packageLogLevelsInitialized = true;
+    }
+    if (options?.packageLogLevels) {
+        mergePackageLogLevelsConfig(options.packageLogLevels);
+    }
+}
+/** Reset init flag (tests). */
+export function resetGatewayPackageLogLevelsInit() {
+    packageLogLevelsInitialized = false;
+}

package/dist/gateway-mode.js

@@ -1,7 +1,8 @@
 /**
  * Gateway operational mode (prod vs dev/debug) and default model resolution.
  */
-import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
+import { gatewayLogDebug } from './gateway-log-meta.js';
+import { fieldEvidence, GatewayLogCode, gatewayWarnCode } from './gateway-log-diagnostics.js';
 /** Profile name resolved via ai-tools + {@link @x12i/ai-profiles} when catalog is enabled. */
 export const CODE_DEFAULT_MODEL = 'cheap';
 /**
@@ -69,8 +70,16 @@ export function resolveGatewayDefaultModel(defaultModelConfig, gatewayDefaultEng
     };
 }
 export function warnDefaultModelSubstitution(logger, identity, details) {
-    logger.warn('Gateway substituted default model for request', withActivityIdentity(identity, {
+    gatewayWarnCode(logger, GatewayLogCode.DEFAULT_MODEL_SUBSTITUTED, identity, {
         ...details,
-        debugKind: gatewayLogDebug.anomaly
-    }));
+        debugKind: gatewayLogDebug.anomaly,
+        evidence: [
+            fieldEvidence('defaultModel', details.defaultModel),
+            fieldEvidence('defaultSource', details.defaultSource),
+            fieldEvidence('reason', details.reason),
+            fieldEvidence('mode', details.mode),
+            ...(details.originalModel ? [fieldEvidence('originalModel', details.originalModel)] : []),
+            ...(details.originalProvider ? [fieldEvidence('originalProvider', details.originalProvider)] : [])
+        ]
+    });
 }

package/dist/gateway-retry.js

@@ -5,6 +5,7 @@
  * NOTE: Retry delays use SIMPLE SLEEP (not smart rate limiting).
  * Between-calls rate limiting is handled separately in gateway-rate-limiter.ts (smart).
  */
+import { exceptionEvidence, fieldEvidence, GatewayLogCode, gatewayWarnCode } from './gateway-log-diagnostics.js';
 /**
  * Determines if an error is a network error (fetch failed, DNS, connectivity)
  */
@@ -146,12 +147,18 @@ export async function invokeWithRetry(routerRequest, retryConfig, jobId, router,
             }
             // If this was the last attempt, throw the error
             if (attempt >= maxRetries) {
-                logger.warn('Max retries exceeded', {
+                gatewayWarnCode(logger, GatewayLogCode.RETRY_MAX_EXCEEDED, undefined, {
                     jobId,
                     error: lastError.message,
                     errorName: lastError.name,
                     totalAttempts: attempt + 1,
-                    maxRetries
+                    maxRetries,
+                    evidence: [
+                        fieldEvidence('jobId', jobId),
+                        fieldEvidence('totalAttempts', attempt + 1),
+                        fieldEvidence('maxRetries', maxRetries),
+                        exceptionEvidence(lastError)
+                    ]
                 });
                 throw lastError;
             }
@@ -187,7 +194,7 @@ export async function invokeWithRetry(routerRequest, retryConfig, jobId, router,
                 errorType,
                 delayMs: Math.round(delay)
             });
-            logger.warn('Retrying request after error', {
+            gatewayWarnCode(logger, GatewayLogCode.RETRY_ATTEMPT, undefined, {
                 jobId,
                 error: lastError.message,
                 errorName: lastError.name,
@@ -195,7 +202,15 @@ export async function invokeWithRetry(routerRequest, retryConfig, jobId, router,
                 attempt: attempt + 1,
                 maxRetries: maxRetries + 1,
                 delayMs: Math.round(delay),
-                statusCode
+                statusCode,
+                evidence: [
+                    fieldEvidence('jobId', jobId),
+                    fieldEvidence('attempt', attempt + 1),
+                    fieldEvidence('errorType', errorType),
+                    fieldEvidence('delayMs', Math.round(delay)),
+                    ...(statusCode !== undefined ? [fieldEvidence('statusCode', statusCode)] : []),
+                    exceptionEvidence(lastError)
+                ]
             });
             await sleep(delay);
         }

package/dist/gateway.js

@@ -16,6 +16,7 @@ import { autoRegisterProviders } from './gateway-provider-auto-register.js';
 import { applyOpenRouterInvokePolicy } from './ai-tools-client.js';
 import { setGatewayLastJobId, setGatewayRuntimeClients } from './runtime-objects.js';
 import { gatewayLogDebug, withActivityIdentity, withGatewayLogContext } from './gateway-log-meta.js';
+import { exceptionEvidence, fieldEvidence, GatewayLogCode, gatewayErrorCode, gatewayWarnCode } from './gateway-log-diagnostics.js';
 import { invokeWithRetry } from './gateway-retry.js';
 /** Error message thrown by the router when no provider is registered or specified */
 const NO_PROVIDER_ERROR = 'No provider specified and no providers registered';
@@ -28,16 +29,24 @@ function warnIfSuccessfulInvokeReportsZeroUsageOrCost(logger, identity, meta, in
     const zeroCost = typeof cost === 'number' && cost === 0;
     if (!zeroTokens && !zeroCostUsd && !zeroCost)
         return;
-    logger.warn('Successful provider response reported zero token usage and/or zero cost; verify router adapter usage and billing metadata', withActivityIdentity(identity, {
+    gatewayWarnCode(logger, GatewayLogCode.ZERO_USAGE_OR_COST, identity, {
         invokeKind,
         zeroTokens,
         zeroCostUsd,
         zeroCostField: zeroCost,
-        tokens,
-        costUsd,
-        cost,
-        debugKind: gatewayLogDebug.anomaly
-    }));
+        debugKind: gatewayLogDebug.anomaly,
+        evidence: [
+            fieldEvidence('tokens.prompt', tokens.prompt),
+            fieldEvidence('tokens.completion', tokens.completion),
+            fieldEvidence('tokens.total', tokens.total),
+            fieldEvidence('costUsd', costUsd),
+            fieldEvidence('cost', cost)
+        ],
+        diagnostics: {
+            expected: 'Successful invoke should include non-zero token usage or cost when billing metadata is available.',
+            actual: `zeroTokens=${zeroTokens}, zeroCostUsd=${zeroCostUsd}, zeroCost=${zeroCost}`
+        }
+    });
 }
 /**
  * Simplified AI Gateway - Clean proxy implementation
@@ -494,12 +503,20 @@ export class AIGateway {
                     if (!response) {
                         const fallbackAttempts = buildGatewayFallbackAttemptsFromTrace(traceAttempts, deduped, lastError);
                         const providersTried = [...new Set(deduped.map((c) => c.provider))];
-                        this.logger.error('Trace fallback chain exhausted', withActivityIdentity(request.identity, {
+                        gatewayErrorCode(this.logger, GatewayLogCode.FALLBACK_CHAIN_EXHAUSTED, request.identity, {
                             providersTried,
-                            candidates: deduped,
-                            fallbackAttempts,
-                            debugKind: gatewayLogDebug.anomaly
-                        }));
+                            debugKind: gatewayLogDebug.anomaly,
+                            evidence: [
+                                fieldEvidence('providersTried', providersTried),
+                                fieldEvidence('candidateCount', deduped.length),
+                                fieldEvidence('fallbackAttempts', fallbackAttempts),
+                                ...(lastError ? [fieldEvidence('lastError.message', lastError.message)] : [])
+                            ],
+                            diagnostics: {
+                                expected: 'At least one provider/model candidate in the fallback chain should succeed.',
+                                actual: 'All candidates failed or returned no response.'
+                            }
+                        });
                         const exhausted = new FallbackExhaustedError(mapGatewayFallbackAttemptsToRouter(fallbackAttempts));
                         exhausted.message = formatFallbackExhaustionMessage(fallbackAttempts, deduped);
                         if (lastError) {
@@ -570,23 +587,32 @@ export class AIGateway {
                     }
                     else {
                         // Extraction failed, fall back to raw text wrapper
-                        this.logger.warn('Flex-md extraction failed - no structured data extracted', withActivityIdentity(request.identity, {
+                        gatewayWarnCode(this.logger, GatewayLogCode.FLEX_MD_EXTRACTION_FAILED, request.identity, {
                             hasResult: !!extractionResult,
                             method: extractionResult?.method || 'none',
-                            debugKind: gatewayLogDebug.anomaly
-                        }));
+                            debugKind: gatewayLogDebug.anomaly,
+                            evidence: [
+                                fieldEvidence('content.length', content.length),
+                                fieldEvidence('extraction.method', extractionResult?.method || 'none')
+                            ]
+                        });
                         parsedContent = { rawText: content };
                     }
                 }
                 catch (extractionError) {
                     // Extraction failed, fall back to raw text wrapper
                     const errorMessage = extractionError instanceof Error ? extractionError.message : String(extractionError);
-                    this.logger.warn('Flex-md extraction failed - flex-md library compatibility issue', withActivityIdentity(request.identity, {
+                    gatewayWarnCode(this.logger, GatewayLogCode.FLEX_MD_EXTRACTION_ERROR, request.identity, {
                         error: errorMessage,
-                        issue: 'flex-md uses require() in ES module context - needs fixing in flex-md-loader.ts',
                         fallback: 'using rawText wrapper',
-                        debugKind: gatewayLogDebug.anomaly
-                    }));
+                        debugKind: gatewayLogDebug.anomaly,
+                        evidence: [
+                            fieldEvidence('content.length', content.length),
+                            ...(extractionError instanceof Error
+                                ? [exceptionEvidence(extractionError)]
+                                : [fieldEvidence('error.message', errorMessage)])
+                        ]
+                    });
                     parsedContent = { rawText: content };
                 }
                 contentType = 'structured';

package/dist/index.d.ts

@@ -35,9 +35,13 @@ export { ActivityManager, ensureGatewayRequestIdentity } from './activity-manage
 export { OptimixerManager } from './optimixer-manager.js';
 export type { ActivityIdentity } from './types.js';
 export { activityIdentityToLogContext, activityIdentityToLogMeta, withActivityIdentity, withGatewayLogContext, gatewayLogDebug } from './gateway-log-meta.js';
-export { createGatewayLogger, GATEWAY_LOG_ENV_PREFIX } from './logger-factory.js';
-export { createLogxer, DebugLogAbstract, runWithLogContext, getStationRuntimeIdentity, mergeRuntimeIdentity } from '@x12i/logxer';
-export type { Logxer, LogMeta, RuntimeIdentity, LogRuntimeContext, GetJobLogsInput, GetJobLogsResult, QueryableLogLine } from '@x12i/logxer';
+export { createGatewayLogger } from './logger-factory.js';
+export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_STACK_LOG_PREFIXES, initializeGatewayPackageLogLevels, resetGatewayPackageLogLevelsInit } from './gateway-log-levels.js';
+export { GatewayLogCode, gatewayErrorCode, gatewayInfoCode, gatewayWarnCode, gatewayAnomalyMeta, resolveLogDiagnosticsCatalogPath, exceptionEvidence, fieldEvidence } from './gateway-log-diagnostics.js';
+export type { GatewayLogCode as GatewayDiagnosticCode } from './gateway-log-diagnostics.js';
+export { createLogxer, DebugLogAbstract, runWithLogContext, getStationRuntimeIdentity, mergeRuntimeIdentity, conditionEvidence, sourceEvidence, logReferenceEvidence, readAgentLoggingInstructions, resolveAgentLoggingInstructionsPath, applyPackageLogLevelsFromEnv, configurePackageLogLevels, mergePackageLogLevelsConfig, setPackageLogLevel, resolveStackLogLevelForPrefix, resolvePackageLogsLevel, parseLogxerPackageLevelsEnv, LOGXER_PACKAGE_LEVELS_ENV, LOGXER_PACKAGE_LOGS_DEFAULT_ENV } from '@x12i/logxer';
+export { ROUTER_LOG_ENV_PREFIX } from '@x12i/ai-providers-router';
+export type { Logxer, LogMeta, RuntimeIdentity, LogRuntimeContext, GetJobLogsInput, GetJobLogsResult, QueryableLogLine, LogDiagnostics, DiagnosticEvidence, ScopeCriteria, ScopeLogsResult, StackLoggingOptions, PackageLogLevelsConfig, PackageLogLevelSetting } from '@x12i/logxer';
 export { runtimeObjects } from './runtime-objects.js';
 export type { ActivixQueryableClient, LogxerQueryableClient, PackageRuntimeObjects, RuntimeObjects } from './runtime-objects.js';
 export { GatewayRateLimiter } from './gateway-rate-limiter.js';

package/dist/index.js

@@ -30,9 +30,12 @@ export { normalizeToActivixCostShape } from '@x12i/activix';
 export { ActivityManager, ensureGatewayRequestIdentity } from './activity-manager.js';
 export { OptimixerManager } from './optimixer-manager.js';
 export { activityIdentityToLogContext, activityIdentityToLogMeta, withActivityIdentity, withGatewayLogContext, gatewayLogDebug } from './gateway-log-meta.js';
-export { createGatewayLogger, GATEWAY_LOG_ENV_PREFIX } from './logger-factory.js';
+export { createGatewayLogger } from './logger-factory.js';
+export { GATEWAY_LOG_ENV_PREFIX, GATEWAY_STACK_LOG_PREFIXES, initializeGatewayPackageLogLevels, resetGatewayPackageLogLevelsInit } from './gateway-log-levels.js';
+export { GatewayLogCode, gatewayErrorCode, gatewayInfoCode, gatewayWarnCode, gatewayAnomalyMeta, resolveLogDiagnosticsCatalogPath, exceptionEvidence, fieldEvidence } from './gateway-log-diagnostics.js';
 // Re-export logging (@x12i/logxer)
-export { createLogxer, DebugLogAbstract, runWithLogContext, getStationRuntimeIdentity, mergeRuntimeIdentity } from '@x12i/logxer';
+export { createLogxer, DebugLogAbstract, runWithLogContext, getStationRuntimeIdentity, mergeRuntimeIdentity, conditionEvidence, sourceEvidence, logReferenceEvidence, readAgentLoggingInstructions, resolveAgentLoggingInstructionsPath, applyPackageLogLevelsFromEnv, configurePackageLogLevels, mergePackageLogLevelsConfig, setPackageLogLevel, resolveStackLogLevelForPrefix, resolvePackageLogsLevel, parseLogxerPackageLevelsEnv, LOGXER_PACKAGE_LEVELS_ENV, LOGXER_PACKAGE_LOGS_DEFAULT_ENV } from '@x12i/logxer';
+export { ROUTER_LOG_ENV_PREFIX } from '@x12i/ai-providers-router';
 // Runtime observability surface (leaf package: no downstream runtime objects)
 export { runtimeObjects } from './runtime-objects.js';
 // Export rate limiter

package/dist/logger-factory.d.ts

@@ -3,9 +3,11 @@
  *
  * Creates and configures logxer instances for the gateway
  */
-import { type Logxer } from '@x12i/logxer';
-/** Stable ERC 2.0 env prefix — controls `AI_GATEWAY_LOGS_LEVEL`, etc. */
-export declare const GATEWAY_LOG_ENV_PREFIX = "AI_GATEWAY";
+import { type LogLevel, type Logxer, type PackageLogLevelsConfig, type StackLoggingOptions } from '@x12i/logxer';
+import { GATEWAY_LOG_ENV_PREFIX } from './gateway-log-levels.js';
+export { GATEWAY_LOG_ENV_PREFIX };
+/** True for the internal no-op logger when `enableLogging` is false. */
+export declare function isNoOpGatewayLogger(logger: Logxer): boolean;
 /**
  * Creates a logger instance based on configuration
  *
@@ -16,4 +18,10 @@ export declare function createGatewayLogger(config: {
     enableLogging: boolean;
     packageName?: string;
     customLogger?: Logxer;
+    /** Parent/host pass-through (logxer ≥ 4.5). Forwarded as `createLogxer(..., { stack })`. */
+    logging?: StackLoggingOptions;
+    /** Merged into the process registry after `applyPackageLogLevelsFromEnv()`. */
+    packageLogLevels?: PackageLogLevelsConfig;
+    /** Explicit level for this gateway logger instance (wins over stack/registry/env). */
+    logLevel?: LogLevel;
 }): Logxer;