@x12i/ai-gateway 9.2.0 → 9.3.0

package/dist/index.d.ts

@@ -17,7 +17,9 @@ export { AIGateway } from './gateway.js';
 export { InstructionNotFoundError, InstructionBackendError } from './instruction-errors.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
 export type { GatewayConfig, ProviderModelRef, ModelConfig, RetryConfig, ChatRequest, AIInvokeRequest, AIRequest, GatewayActionType, GatewayInvokeRejectionMetadata, GatewayTraceRequestIds, GatewayTraceMergedConfig, EnhancedLLMResponse, InstructionMetadata, ValidationRule, TemplateRenderOptions, SmartInputConfig, SmartInputRenderOptions } from './types.js';
-export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, hasNonZeroTokenUsage } from './gateway-utils.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, hasNonZeroTokenUsage } from './gateway-utils.js';
+export { getGatewayOperationalMode, isProdGatewayMode, resolveGatewayDefaultModel, parseModelProviderSpec, CODE_DEFAULT_MODEL } from './gateway-mode.js';
+export type { GatewayOperationalMode, GatewayDefaultModelSource, DefaultModelSubstitutionReason, ResolvedGatewayDefault } from './gateway-mode.js';
 export type { ActivityCostStatus, ResolvedActivityCost } from './gateway-utils.js';
 export { contractSpecToFieldKeys, enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';
 export type { OutputContractSpec } from './output-contract-normalizer.js';

package/dist/index.js

@@ -17,7 +17,8 @@ export * from '@x12i/ai-providers-router';
 export { AIGateway } from './gateway.js';
 export { InstructionNotFoundError, InstructionBackendError } from './instruction-errors.js';
 export { autoRegisterProviders } from './gateway-provider-auto-register.js';
-export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, hasNonZeroTokenUsage } from './gateway-utils.js';
+export { attachGatewayInvokeRejectionMetadata, buildInvokeRejectionMetadata, tryExtractRouterLikePayloadFromErrorChain, pickRequestIdsFromRouterLike, resolveActivityCostCompletion, resolveCostCompletionForActivity, resolveCostCompletionWithAiTools, hasNonZeroTokenUsage } from './gateway-utils.js';
+export { getGatewayOperationalMode, isProdGatewayMode, resolveGatewayDefaultModel, parseModelProviderSpec, CODE_DEFAULT_MODEL } from './gateway-mode.js';
 export { contractSpecToFieldKeys, enrichParsedContentForOutputContract, resolveOutputContractFieldKeys } from './output-contract-normalizer.js';
 export { mergeGatewayAndRequestTemplateRenderOptions, mergeTemplateRenderOptions } from './template-render-merge.js';
 export { GATEWAY_DUAL_MEMORY_ROOTS, buildMemoryResolutionRootFromWorkingMemory, coalesceMergedInputBucket, extractCallerInputsBag, mapSmartInputPathsInputsToInput, parseLooseJsonObject, prepareWorkingMemoryForTemplateRender, resolveGatewayMemoryPathValue } from './memory-path-resolution.js';

package/dist/types.d.ts

@@ -340,6 +340,27 @@ export interface GatewayConfig extends Omit<RouterConfig, 'defaultEngine' | 'log
     openRouter?: {
         enabled?: boolean;
     };
+    /**
+     * Operational mode override (`process.env.mode` / `MODE` when omitted).
+     * - `prod`: unresolved models fall back to {@link AI_GATEWAY_DEFAULT_MODEL} / packaged default (with Logxer warn).
+     * - `dev` / `debug`: unresolved models throw {@link ModelResolutionError} from `@x12i/ai-tools`.
+     */
+    mode?: 'dev' | 'debug' | 'prod';
+    /**
+     * @x12i/ai-tools integration: catalog model resolution (request) and cost calculation (response).
+     */
+    aiTools?: {
+        /** @default true */
+        enabled?: boolean;
+        /** Inject Catalox; otherwise `createCataloxFromEnv()` from `@x12i/catalox/firebase`. */
+        catalox?: import('@x12i/catalox').Catalox;
+        cacheTtlMs?: number;
+        /** @default true */
+        resolveModels?: boolean;
+        /** @default true */
+        calculateCost?: boolean;
+        costIncludeBreakdown?: boolean;
+    };
     /**
      * InstructionsBlocks overrides
      * Key: block name, Value: block content

package/dist-cjs/activity-manager.cjs

@@ -1,16 +1,12 @@
-"use strict";
 /**
  * Activity Manager
  *
  * Manages activity tracking for LLM requests.
  * Wraps the ActivityTracker and provides convenience methods.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ActivityManager = void 0;
-exports.ensureGatewayRequestIdentity = ensureGatewayRequestIdentity;
-const activix_1 = require("@x12i/activix");
-const activity_tracking_config_js_1 = require("./config/activity-tracking-config.cjs");
-const gateway_log_meta_js_1 = require("./gateway-log-meta.cjs");
+import { Activix, activixActivityIo, activixOuterTier, resolveActivixLogsDatabaseName, resolveActivixMongoUriFromEnv } from '@x12i/activix';
+import { resolveActivityTrackingConfig } from './config/activity-tracking-config.js';
+import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
 function readAiRequestIdFromRequest(request) {
     const aiRequestId = request.aiRequestId;
     if (typeof aiRequestId === 'string' && aiRequestId.trim().length > 0) {
@@ -116,10 +112,10 @@ function resolveSessionIdForRequest(request, incomingIdentity, aiRequestId) {
 function logUpstreamIdentityWarnings(logger, incomingIdentity, merged) {
     const aiRequestId = merged.aiRequestId;
     if (!incomingIdentity || typeof incomingIdentity !== 'object') {
-        logger?.warn('missingRuntimeIdentityObject', (0, gateway_log_meta_js_1.withActivityIdentity)(merged, {
+        logger?.warn('missingRuntimeIdentityObject', withActivityIdentity(merged, {
             message: 'request.identity is missing; upstream must send the mandatory runtime identity object',
             aiRequestId,
-            debugKind: gateway_log_meta_js_1.gatewayLogDebug.anomaly
+            debugKind: gatewayLogDebug.anomaly
         }));
         return;
     }
@@ -129,11 +125,11 @@ function logUpstreamIdentityWarnings(logger, incomingIdentity, merged) {
     if (!trimIdentityString(incomingIdentity.taskId))
         missing.push('taskId');
     if (missing.length > 0) {
-        logger?.warn('missingUpstreamIdentityFields', (0, gateway_log_meta_js_1.withActivityIdentity)(merged, {
+        logger?.warn('missingUpstreamIdentityFields', withActivityIdentity(merged, {
             message: `Upstream identity is missing required field(s): ${missing.join(', ')}. jobId and taskId must be set on request.identity by the client; the gateway does not generate them.`,
             missingFields: missing,
             aiRequestId,
-            debugKind: gateway_log_meta_js_1.gatewayLogDebug.anomaly
+            debugKind: gatewayLogDebug.anomaly
         }));
     }
 }
@@ -218,7 +214,7 @@ function mergeGatewayActivityIdentity(request, aiRequestId, extras) {
  *
  * @param logger - Optional Logxer used to WARN when mandatory upstream `identity.jobId` / `identity.taskId` are absent.
  */
-function ensureGatewayRequestIdentity(request, extras, logger) {
+export function ensureGatewayRequestIdentity(request, extras, logger) {
     const aiRequestId = readAiRequestIdFromRequest(request);
     const identity = mergeGatewayActivityIdentity(request, aiRequestId, {
         ...graphIdentityExtrasFromRequest(request),
@@ -236,12 +232,12 @@ function buildActivixStartIo(aiRequestId, activityType, requestData) {
         Object.keys(requestData).length > 0
         ? { activityType, request: requestData }
         : { activityType };
-    return (0, activix_1.activixActivityIo)((0, activix_1.activixOuterTier)(input, null, { aiRequestId }));
+    return activixActivityIo(activixOuterTier(input, null, { aiRequestId }));
 }
 /**
  * Manages activity tracking lifecycle
  */
-class ActivityManager {
+export class ActivityManager {
     activix;
     initPromise;
     mainCollectionName;
@@ -251,7 +247,7 @@ class ActivityManager {
     constructor(config) {
         this.logger = config.logger;
         if (config.enableActivityTracking) {
-            const { collectionName, badRequestsCollectionName } = (0, activity_tracking_config_js_1.resolveActivityTrackingConfig)();
+            const { collectionName, badRequestsCollectionName } = resolveActivityTrackingConfig();
             this.mainCollectionName = collectionName;
             this.badRequestsCollectionName = badRequestsCollectionName;
             try {
@@ -263,7 +259,7 @@ class ActivityManager {
                     failed: 'failed',
                     timeout: 'timeout'
                 };
-                this.activix = config.customTracker ?? new activix_1.Activix({
+                this.activix = config.customTracker ?? new Activix({
                     // Keep mode explicit for operational clarity (matches integration checklist expectations).
                     storageMode: 'automatic',
                     collections: [
@@ -312,8 +308,8 @@ class ActivityManager {
                         return;
                     }
                     const backend = ax.storageBackend;
-                    const mongoDb = backend === 'database' ? (0, activix_1.resolveActivixLogsDatabaseName)() : undefined;
-                    const mongoUriConfigured = Boolean((0, activix_1.resolveActivixMongoUriFromEnv)());
+                    const mongoDb = backend === 'database' ? resolveActivixLogsDatabaseName() : undefined;
+                    const mongoUriConfigured = Boolean(resolveActivixMongoUriFromEnv());
                     this.logger.info('Activity tracking persistence backend ready', {
                         storageBackend: backend,
                         mongoDatabase: mongoDb,
@@ -1162,4 +1158,3 @@ class ActivityManager {
         }
     }
 }
-exports.ActivityManager = ActivityManager;

package/dist-cjs/ai-tools-client.cjs

@@ -0,0 +1,91 @@
+/**
+ * Lazy @x12i/ai-tools catalog + cost calculator bootstrap.
+ */
+import { AiModelsCatalogClient, CostCalculator, ensureAiModelsCatalog } from '@x12i/ai-tools';
+import { gatewayLogDebug, withActivityIdentity } from './gateway-log-meta.js';
+let sharedClientPromise = null;
+let sharedConfigKey;
+let bootstrapFailedLogged = false;
+function configKey(config) {
+    const injected = config.aiTools?.catalox ? 'injected' : 'env';
+    return `${injected}:${config.aiTools?.cacheTtlMs ?? ''}:${config.aiTools?.costIncludeBreakdown ?? ''}`;
+}
+/**
+ * Returns catalog + calculator, or null when disabled or bootstrap fails.
+ */
+export async function getAiToolsClient(config, logger) {
+    if (config.aiTools?.enabled === false) {
+        return null;
+    }
+    const key = configKey(config);
+    if (sharedClientPromise && sharedConfigKey !== key) {
+        sharedClientPromise = null;
+    }
+    sharedConfigKey = key;
+    if (!sharedClientPromise) {
+        sharedClientPromise = bootstrapAiTools(config, logger);
+    }
+    return sharedClientPromise;
+}
+/** Reset singleton (tests). */
+export function resetAiToolsClientForTests() {
+    sharedClientPromise = null;
+    sharedConfigKey = undefined;
+    bootstrapFailedLogged = false;
+}
+async function bootstrapAiTools(config, logger) {
+    try {
+        let catalox = config.aiTools?.catalox;
+        if (!catalox) {
+            const { createCataloxFromEnv } = await import('@x12i/catalox/firebase');
+            const bootstrapped = createCataloxFromEnv();
+            catalox = bootstrapped.catalox;
+        }
+        await ensureAiModelsCatalog(catalox);
+        const catalog = new AiModelsCatalogClient({
+            catalox,
+            cacheTtlMs: config.aiTools?.cacheTtlMs
+        });
+        const calculator = new CostCalculator(catalog, {
+            includeBreakdown: config.aiTools?.costIncludeBreakdown === true
+        });
+        logger.debug('ai-tools catalog client ready', {
+            debugKind: gatewayLogDebug.state
+        });
+        return { catalog, calculator };
+    }
+    catch (error) {
+        if (!bootstrapFailedLogged) {
+            bootstrapFailedLogged = true;
+            logger.warn('ai-tools catalog bootstrap failed; model resolution and catalog cost calculation disabled', withActivityIdentity(undefined, {
+                error: error instanceof Error ? error.message : String(error),
+                debugKind: gatewayLogDebug.anomaly
+            }));
+        }
+        return null;
+    }
+}
+/**
+ * Map catalog resolution to router config provider/model fields.
+ */
+export function applyModelResolution(merged, resolution, gatewayDefaultEngine) {
+    if (resolution.routedViaOpenRouter) {
+        merged.provider = 'openrouter';
+        merged.model = resolution.modelId;
+        return;
+    }
+    const slash = resolution.modelId.indexOf('/');
+    if (slash > 0) {
+        merged.provider = resolution.record?.providerId ?? resolution.modelId.slice(0, slash);
+        merged.model = resolution.modelId.slice(slash + 1);
+    }
+    else {
+        merged.model = resolution.modelId;
+        if (resolution.record?.providerId) {
+            merged.provider = resolution.record.providerId;
+        }
+    }
+    if (!merged.provider && gatewayDefaultEngine) {
+        merged.provider = gatewayDefaultEngine;
+    }
+}

package/dist-cjs/ai-tools-client.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Lazy @x12i/ai-tools catalog + cost calculator bootstrap.
+ */
+import { AiModelsCatalogClient, CostCalculator, type ModelResolutionSuccess } from '@x12i/ai-tools';
+import type { Logxer } from '@x12i/logxer';
+import type { ChatRequest, GatewayConfig } from './types.js';
+export type AiToolsClientBundle = {
+    catalog: AiModelsCatalogClient;
+    calculator: CostCalculator;
+};
+/**
+ * Returns catalog + calculator, or null when disabled or bootstrap fails.
+ */
+export declare function getAiToolsClient(config: GatewayConfig, logger: Logxer): Promise<AiToolsClientBundle | null>;
+/** Reset singleton (tests). */
+export declare function resetAiToolsClientForTests(): void;
+/**
+ * Map catalog resolution to router config provider/model fields.
+ */
+export declare function applyModelResolution(merged: NonNullable<ChatRequest['config']>, resolution: ModelResolutionSuccess, gatewayDefaultEngine?: string): void;

package/dist-cjs/config/activity-tracking-config.cjs

@@ -1,14 +1,11 @@
-"use strict";
 /**
  * Centralized activity tracking configuration.
  * Package-level Mongo collection names are fixed literals here (no env override).
  * Main gateway rows: `ai-actions`; bad requests: `bad-requests` (see constants below).
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveActivityTrackingConfig = resolveActivityTrackingConfig;
 const ACTIVITY_COLLECTION_NAME = 'ai-actions';
 const BAD_REQUESTS_COLLECTION_NAME = 'bad-requests';
-function resolveActivityTrackingConfig() {
+export function resolveActivityTrackingConfig() {
     // Collection names are intentionally hardcoded at package level.
     return {
         mongoUri: '',

package/dist-cjs/content-normalizer/content-normalizer.cjs

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * Content Normalizer
  *
@@ -6,10 +5,6 @@
  * Fixes the "[object Object]" bug by properly handling objects.
  * Preserves both rawText and parsedContent for downstream consumers.
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeContent = normalizeContent;
-exports.isEmptyContent = isEmptyContent;
-exports.getResponseDiagnostics = getResponseDiagnostics;
 /**
  * Extracts content from router response, checking multiple possible locations
  *
@@ -187,7 +182,7 @@ function determineContentType(value, parsedContent) {
  * @param response - Router response object
  * @returns Normalized content with metadata
  */
-function normalizeContent(response, logger) {
+export function normalizeContent(response, logger) {
     // Extract content value from response
     const contentValue = extractContentValue(response);
     // CRITICAL: Check if router already converted object to "[object Object]" string
@@ -375,7 +370,7 @@ function normalizeContent(response, logger) {
  * @param normalized - Normalized content result
  * @returns True if content is empty
  */
-function isEmptyContent(normalized) {
+export function isEmptyContent(normalized) {
     return !normalized.content || normalized.content.trim().length === 0;
 }
 /**
@@ -385,7 +380,7 @@ function isEmptyContent(normalized) {
  * @param response - Router response object
  * @returns Diagnostic information
  */
-function getResponseDiagnostics(response) {
+export function getResponseDiagnostics(response) {
     return {
         responseKeys: Object.keys(response),
         hasMessage: !!(response?.message),

package/dist-cjs/content-normalizer/index.cjs

@@ -1,12 +1,6 @@
-"use strict";
 /**
  * Content Normalizer Module
  *
  * Exports all public APIs for content normalization
  */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.getResponseDiagnostics = exports.isEmptyContent = exports.normalizeContent = void 0;
-var content_normalizer_js_1 = require("./content-normalizer.cjs");
-Object.defineProperty(exports, "normalizeContent", { enumerable: true, get: function () { return content_normalizer_js_1.normalizeContent; } });
-Object.defineProperty(exports, "isEmptyContent", { enumerable: true, get: function () { return content_normalizer_js_1.isEmptyContent; } });
-Object.defineProperty(exports, "getResponseDiagnostics", { enumerable: true, get: function () { return content_normalizer_js_1.getResponseDiagnostics; } });
+export { normalizeContent, isEmptyContent, getResponseDiagnostics } from './content-normalizer.js';

package/dist-cjs/content-normalizer/types.cjs

@@ -1,5 +1,4 @@
-"use strict";
 /**
  * Type definitions for Content Normalizer
  */
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};

package/dist-cjs/flex-md-loader.cjs

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * @x12i/flex-md Loader
  *
@@ -14,55 +13,9 @@
  * - Native output format support: Extracts and uses flex-md native output formats from instructions
  *   based on compliance level when no explicit format is provided
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadFlexMd = loadFlexMd;
-exports.extractJsonFromFlexMd = extractJsonFromFlexMd;
-exports.parseMarkdownSectionsFromContent = parseMarkdownSectionsFromContent;
-exports.isFlexMdAvailable = isFlexMdAvailable;
-exports.getModelMaxTokensFromFlexMd = getModelMaxTokensFromFlexMd;
-exports.getFlexMdModule = getFlexMdModule;
-exports.buildDynamicInstructions = buildDynamicInstructions;
-exports.enrichInstructionsWithFlexMd = enrichInstructionsWithFlexMd;
-exports.getStrictnessDefaults = getStrictnessDefaults;
-exports.enforceFlexMdFormat = enforceFlexMdFormat;
-exports.hasFlexMdContract = hasFlexMdContract;
-exports.detectComplianceLevel = detectComplianceLevel;
-const path = __importStar(require("path"));
-const url_1 = require("url");
-const logxer_1 = require("@x12i/logxer");
+import * as path from 'path';
+import { pathToFileURL } from 'url';
+import { DebugLogAbstract } from '@x12i/logxer';
 let flexMdModule = null;
 let flexMdLoadError = null;
 let flexMdLoading = null;
@@ -79,7 +32,7 @@ async function importFlexMdModule() {
         const { createRequire } = await importModule('module');
         const requireFn = typeof require === 'function' ? require : createRequire(path.join(process.cwd(), 'noop.cjs'));
         const cjsEntryPath = requireFn.resolve('@x12i/flex-md');
-        const cjsEntryUrl = (0, url_1.pathToFileURL)(cjsEntryPath).href;
+        const cjsEntryUrl = pathToFileURL(cjsEntryPath).href;
         try {
             return await importModule(cjsEntryUrl);
         }
@@ -97,7 +50,7 @@ async function importFlexMdModule() {
  * Load flex-md module (ES Module) asynchronously
  * Caches the result to avoid multiple imports
  */
-async function loadFlexMd() {
+export async function loadFlexMd() {
     // Return cached module if available
     if (flexMdModule) {
         return flexMdModule;
@@ -376,7 +329,7 @@ async function extractFlexMdOutputFormatFromInstructions(instructions, complianc
  *   - Other flex-md options
  * @returns Parsed JSON object and method used, or null if parsing fails
  */
-async function extractJsonFromFlexMd(content, logger) {
+export async function extractJsonFromFlexMd(content, logger) {
     // ARCHITECTURE: ai-gateway layer only handles unstructured parsing
     // Schema-driven parsing is handled at skills layer with nx-md-parser
     // No schema parameter - this layer doesn't know about schemas
@@ -406,8 +359,8 @@ async function extractJsonFromFlexMd(content, logger) {
                 if (result && typeof result === 'object' && result !== null) {
                     const json = result.json || result.data || result.result || result;
                     if (json && typeof json === 'object' && json !== null) {
-                        logger?.debug('extractJsonFromFlexMd: using extractFromMarkdown', { debugKind: logxer_1.DebugLogAbstract.TRACE });
-                        logger?.debug('extractJsonFromFlexMd: parsed json', { json, debugKind: logxer_1.DebugLogAbstract.STATE });
+                        logger?.debug('extractJsonFromFlexMd: using extractFromMarkdown', { debugKind: DebugLogAbstract.TRACE });
+                        logger?.debug('extractJsonFromFlexMd: parsed json', { json, debugKind: DebugLogAbstract.STATE });
                         return { json, method: 'extractFromMarkdown' };
                     }
                 }
@@ -531,11 +484,11 @@ function fallbackMarkdownParser(content, logger) {
         result[key] = parseMarkdownList(currentContent);
         detectedHeaders.push(key);
     }
-    logger?.debug('Fallback parser detected headers', { detectedHeaders, debugKind: logxer_1.DebugLogAbstract.STATE });
+    logger?.debug('Fallback parser detected headers', { detectedHeaders, debugKind: DebugLogAbstract.STATE });
     const expectedHeaders = ['shortAnswer', 'fullAnswer', 'assumptions', 'unknowns', 'evidence'];
     const missingHeaders = expectedHeaders.filter(h => !detectedHeaders.includes(h));
     if (missingHeaders.length > 0) {
-        logger?.debug('Fallback parser missing expected headers', { missingHeaders, debugKind: logxer_1.DebugLogAbstract.STATE });
+        logger?.debug('Fallback parser missing expected headers', { missingHeaders, debugKind: DebugLogAbstract.STATE });
     }
     // If we extracted some structure, return it
     if (Object.keys(result).length > 0) {
@@ -554,7 +507,7 @@ function fallbackMarkdownParser(content, logger) {
  * Section-based markdown → camelCase field map (e.g. `### Short Answer` → `shortAnswer`).
  * Used when output contracts need structured `parsed` fields but flex-md returned only `rawText`.
  */
-function parseMarkdownSectionsFromContent(content, logger) {
+export function parseMarkdownSectionsFromContent(content, logger) {
     const parsed = fallbackMarkdownParser(content, logger);
     const json = parsed.json;
     if (json != null && typeof json === 'object' && !Array.isArray(json)) {
@@ -597,7 +550,7 @@ function extractJsonFallback(content) {
 /**
  * Check if flex-md module is available
  */
-function isFlexMdAvailable() {
+export function isFlexMdAvailable() {
     return flexMdModule !== null;
 }
 /**
@@ -608,7 +561,7 @@ function isFlexMdAvailable() {
  * @param model - Model name (e.g., 'gpt-4', 'claude-3-opus')
  * @returns maxTokens if found, null otherwise
  */
-async function getModelMaxTokensFromFlexMd(provider, model) {
+export async function getModelMaxTokensFromFlexMd(provider, model) {
     try {
         const flexMd = await loadFlexMd();
         if (!flexMd || typeof flexMd !== 'object') {
@@ -687,7 +640,7 @@ async function getModelMaxTokensFromFlexMd(provider, model) {
 /**
  * Get flex-md module directly (must call loadFlexMd() first)
  */
-function getFlexMdModule() {
+export function getFlexMdModule() {
     if (!flexMdModule) {
         throw new Error('flex-md module not loaded. Call loadFlexMd() first.');
     }
@@ -754,7 +707,7 @@ function generateFormatInstructionsFromSchema(schema, options) {
     parts.push('\n\nIMPORTANT: Return your answer as JSON inside the markdown fenced block. The JSON must match the schema above exactly.');
     return parts.join('\n');
 }
-async function buildDynamicInstructions(schemaObject, options) {
+export async function buildDynamicInstructions(schemaObject, options) {
     try {
         const flexMd = await loadFlexMd();
         // Check if dynamic instruction feature is available (flex-md 3.1+)
@@ -786,7 +739,7 @@ async function buildDynamicInstructions(schemaObject, options) {
  * @param strictnessLevel - Compliance level ('L0' | 'L1' | 'L2' | 'L3')
  * @returns Enriched instructions with flex-md guidance
  */
-async function enrichInstructionsWithFlexMd(instructions, strictnessLevel = 'L0') {
+export async function enrichInstructionsWithFlexMd(instructions, strictnessLevel = 'L0') {
     try {
         const flexMd = await loadFlexMd();
         // Use native flex-md function if available (flex-md 3.2+)
@@ -814,7 +767,7 @@ async function enrichInstructionsWithFlexMd(instructions, strictnessLevel = 'L0'
  * @param strictnessLevel - Compliance level ('L0' | 'L1' | 'L2' | 'L3')
  * @returns Configuration object with level-specific defaults
  */
-async function getStrictnessDefaults(strictnessLevel = 'L0') {
+export async function getStrictnessDefaults(strictnessLevel = 'L0') {
     try {
         const flexMd = await loadFlexMd();
         if (flexMd.strictnessDefaults && typeof flexMd.strictnessDefaults === 'function') {
@@ -835,7 +788,7 @@ async function getStrictnessDefaults(strictnessLevel = 'L0') {
  * @param strictnessLevel - Compliance level ('L0' | 'L1' | 'L2' | 'L3')
  * @returns Instructions with flex-md enforcement rules
  */
-async function enforceFlexMdFormat(instructions, outputFormatSpec, strictnessLevel = 'L0') {
+export async function enforceFlexMdFormat(instructions, outputFormatSpec, strictnessLevel = 'L0') {
     try {
         const flexMd = await loadFlexMd();
         if (flexMd.enforceFlexMd && typeof flexMd.enforceFlexMd === 'function') {
@@ -861,7 +814,7 @@ async function enforceFlexMdFormat(instructions, outputFormatSpec, strictnessLev
  * @param complianceLevel - Required compliance level
  * @returns true if instructions meet the compliance level
  */
-async function hasFlexMdContract(instructions, complianceLevel = 'L0') {
+export async function hasFlexMdContract(instructions, complianceLevel = 'L0') {
     if (!instructions || instructions.trim() === '') {
         return false;
     }
@@ -929,7 +882,7 @@ async function hasFlexMdContract(instructions, complianceLevel = 'L0') {
  * @param instructions - Instructions text to check
  * @returns The highest compliance level met ('L0' | 'L1' | 'L2' | 'L3' | null if none)
  */
-async function detectComplianceLevel(instructions) {
+export async function detectComplianceLevel(instructions) {
     if (!instructions || instructions.trim() === '') {
         return null;
     }