monora-ai 2.1.0 → 2.1.4

package/dist/runtime.js

@@ -12,11 +12,17 @@ exports.llmCall = llmCall;
 exports.toolCall = toolCall;
 exports.agentStep = agentStep;
 exports.ensureState = ensureState;
+exports.getState = getState;
 exports.emitEvent = emitEvent;
+exports.emitInternal = emitInternal;
+exports.notifyViolation = notifyViolation;
 exports.executeCall = executeCall;
+exports.applyQuotaLimits = applyQuotaLimits;
 exports.buildLlmBody = buildLlmBody;
 exports.buildToolBody = buildToolBody;
 exports.buildAgentBody = buildAgentBody;
+exports.extractUsageMetrics = extractUsageMetrics;
+exports.estimateUsageCost = estimateUsageCost;
 exports.isPromise = isPromise;
 const perf_hooks_1 = require("perf_hooks");
 const logger_1 = require("./logger");
@@ -39,7 +45,26 @@ const instrumentation_1 = require("./instrumentation");
 const telemetry_1 = require("./telemetry");
 const attribution_1 = require("./attribution");
 const config_migrations_1 = require("./config_migrations");
+const quotas_1 = require("./quotas");
 let state = null;
+let cachedVerifyEventHash = null;
+let verifyEventHashResolved = false;
+function getVerifyEventHash() {
+    if (verifyEventHashResolved) {
+        return cachedVerifyEventHash;
+    }
+    verifyEventHashResolved = true;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const verifyModule = require('./verify');
+        cachedVerifyEventHash = verifyModule.verifyEventHash;
+    }
+    catch (error) {
+        logger_1.logger.error('Real-time verification unavailable: %s', error);
+        cachedVerifyEventHash = null;
+    }
+    return cachedVerifyEventHash;
+}
 /**
  * Initialize Monora with simplified configuration.
  *
@@ -56,14 +81,25 @@ let state = null;
  * init({ configPath: 'monora.yml' });        // Load from config file
  * init({ configDict: {...} });               // Provide full config dict
  * ```
+ *
+ * @remarks
+ * Cross-SDK Parity: This function is async (returns Promise) in Node.js but
+ * synchronous in Python. This is an intentional language difference:
+ * - Node.js: `await monora.init({ preset: 'production' })`
+ * - Python: `monora.init("production")`
  */
 async function init(options) {
-    const { preset, serviceName, sink, policies, configPath, configDict, envPrefix = 'MONORA_', failFast = false, } = options || {};
+    const { preset, serviceName, sink, policies, configPath, configDict, envPrefix = 'MONORA_', failFast = false, onEvent: eventCallback, promptAttribution = false, } = options || {};
     if (state) {
         if (state.traceCompletionUnregister) {
             state.traceCompletionUnregister();
         }
+        if (state.traceStartUnregister) {
+            state.traceStartUnregister();
+        }
         state.dispatcher.close();
+        // Clear any previously registered callbacks to avoid duplicates on re-init
+        (0, dispatcher_1.clearAuditCallbacks)();
         state = null;
     }
     // Auto-detect environment and service info
@@ -109,7 +145,23 @@ async function init(options) {
     }
     // Check for production readiness warnings
     checkProductionReadiness(config, effectivePreset);
-    await initWithConfig(config, failFast);
+    enforceOnboardingGate(config);
+    // Register user-provided event callback before init
+    if (eventCallback) {
+        (0, dispatcher_1.onEvent)(eventCallback);
+    }
+    await initWithConfig(config, failFast, { promptAttribution });
+    // Send startup telemetry event (opt-in only)
+    if ((0, attribution_1.isTelemetryEnabled)()) {
+        (0, attribution_1.sendTelemetryEvent)({
+            eventType: 'startup',
+            environment: detectedEnv,
+            eventData: {
+                preset: effectivePreset,
+                service_name: config.defaults?.service_name,
+            },
+        });
+    }
 }
 /**
  * Check configuration for production readiness and log warnings.
@@ -130,10 +182,32 @@ function checkProductionReadiness(config, presetName) {
         (0, config_migrations_1.logProductionWarnings)(warnings);
     }
 }
+function enforceOnboardingGate(config) {
+    const environment = String(config.defaults?.environment || '').toLowerCase();
+    if (environment !== 'production') {
+        return;
+    }
+    const onboarding = config.onboarding;
+    if (!onboarding || typeof onboarding !== 'object') {
+        return;
+    }
+    if (!onboarding.enabled) {
+        return;
+    }
+    if (onboarding.required_in_production === false) {
+        return;
+    }
+    const status = String(onboarding.status || 'draft').toLowerCase();
+    if (status === 'completed') {
+        return;
+    }
+    throw new Error('Onboarding is required for production but is not completed. ' +
+        'Run `npx monora-ai onboard validate` and `npx monora-ai onboard complete` first.');
+}
 /**
  * Initialize Monora with a pre-built configuration.
  */
-async function initWithConfig(config, failFast) {
+async function initWithConfig(config, failFast, options) {
     const sinks = buildSinks(config.sinks || [], failFast);
     const dispatcher = new dispatcher_1.EventDispatcher(sinks, config);
     const registry = new registry_1.ModelRegistry(config.registry || {});
@@ -153,7 +227,9 @@ async function initWithConfig(config, failFast) {
         reportManager,
         wal,
         signer,
+        quotaManager: new quotas_1.QuotaManager(config.quotas || {}),
     };
+    state.emitInternal = emitInternal;
     // Recover uncommitted events from WAL
     if (config.wal?.enabled && config.wal?.recovery_on_startup !== false) {
         try {
@@ -176,8 +252,11 @@ async function initWithConfig(config, failFast) {
             }
         }
     }
+    state.traceStartUnregister = (0, context_1.registerTraceStartHandler)((span) => {
+        handleTraceStart(span);
+    });
     state.traceCompletionUnregister = (0, context_1.registerTraceCompletionHandler)((span) => {
-        handleTraceCompletion(span.traceId);
+        handleTraceCompletion(span);
     });
     // Initialize telemetry/metrics collection
     await (0, telemetry_1.initMetrics)({ telemetry: config.telemetry });
@@ -200,6 +279,18 @@ async function initWithConfig(config, failFast) {
     }
     dispatcher.start();
     applyAttributionConfig(config);
+    const envValue = config.defaults?.environment || undefined;
+    if (options?.promptAttribution) {
+        await (0, attribution_1.promptForRegistration)({
+            environment: envValue,
+        });
+    }
+    else {
+        // Show first-run registration prompt if needed (one-time only)
+        (0, attribution_1.showFirstRunPromptIfNeeded)({
+            environment: envValue,
+        });
+    }
     emitSdkInit(state);
 }
 function getSdkVersion() {
@@ -251,9 +342,9 @@ function applyAttributionConfig(config) {
             }
             : undefined,
         apiKeyEnv: telemetry.api_key_env ?? undefined,
-        timeoutMs: typeof telemetry.timeout_sec === 'number' ? telemetry.timeout_sec * 1000 : undefined,
+        timeoutSec: typeof telemetry.timeout_sec === 'number' ? telemetry.timeout_sec : undefined,
         retryAttempts: typeof telemetry.retry_attempts === 'number' ? telemetry.retry_attempts : undefined,
-        backoffBaseMs: typeof telemetry.backoff_base_sec === 'number' ? telemetry.backoff_base_sec * 1000 : undefined,
+        backoffBaseSec: typeof telemetry.backoff_base_sec === 'number' ? telemetry.backoff_base_sec : undefined,
     });
     if (telemetry.enabled || telemetry.send_data || attribution.enabled) {
         (0, attribution_1.enableTelemetry)({
@@ -407,11 +498,26 @@ function recordFeatureFlags(config, attribution) {
  * 1. Verifies all pending trace chains (if verify_on_shutdown enabled)
  * 2. Finalizes all pending traces and emits report summaries
  * 3. Closes all sinks and dispatchers
+ *
+ * @remarks
+ * Cross-SDK Parity: This function is async (returns Promise) in Node.js but
+ * synchronous in Python. This is an intentional language difference:
+ * - Node.js: `await monora.shutdown()`
+ * - Python: `monora.shutdown()`
  */
 async function shutdown() {
     if (!state) {
         return;
     }
+    // Send shutdown telemetry event (opt-in only)
+    if ((0, attribution_1.isTelemetryEnabled)()) {
+        (0, attribution_1.sendTelemetryEvent)({
+            eventType: 'shutdown',
+            eventData: {
+                service_name: state.config.defaults?.service_name,
+            },
+        });
+    }
     // AUTOMATIC VERIFICATION ON SHUTDOWN
     const immutability = state.config.immutability || {};
     if (immutability.verify_on_shutdown !== false) {
@@ -420,6 +526,9 @@ async function shutdown() {
     if (state.traceCompletionUnregister) {
         state.traceCompletionUnregister();
     }
+    if (state.traceStartUnregister) {
+        state.traceStartUnregister();
+    }
     state.dispatcher.close();
     // Cleanup and close WAL
     if (state.config.wal?.enabled) {
@@ -456,7 +565,23 @@ function exportTrustPackage(traceId, options) {
     if (!events) {
         throw new Error('No events found for trust package; provide events, inputPath, or configure a file sink.');
     }
-    let trustPackage = (0, trust_package_1.buildTrustPackage)(traceId, events, config);
+    let trustPackage = (0, trust_package_1.buildTrustPackage)(traceId, events, config, {
+        evidenceManifest: options?.evidenceManifest,
+        evidenceManifestPath: options?.evidenceManifestPath,
+        evidenceManifestAuto: options?.evidenceManifestAuto,
+        evidenceManifestStandard: options?.evidenceManifestStandard,
+        evidenceManifestIncludeLineage: options?.evidenceManifestIncludeLineage,
+        evidenceManifestIncludeHashChain: options?.evidenceManifestIncludeHashChain,
+        evidenceManifestIncludeWorkflowState: options?.evidenceManifestIncludeWorkflowState,
+        evidenceManifestIncludeAimsState: options?.evidenceManifestIncludeAimsState,
+        controlCatalog: options?.controlCatalog,
+        controlCatalogPath: options?.controlCatalogPath,
+        controlCatalogStandard: options?.controlCatalogStandard,
+        controlWorkflowState: options?.controlWorkflowState,
+        controlWorkflowStatePath: options?.controlWorkflowStatePath,
+        controlCoverageTarget: options?.controlCoverageTarget,
+        controlCoveragePath: options?.controlCoveragePath,
+    });
     if (options?.sign || options?.gpgKey || options?.gpgHome) {
         trustPackage = (0, trust_package_1.applyGpgSignature)(trustPackage, {
             gpgKey: options?.gpgKey,
@@ -549,6 +674,13 @@ function ensureState() {
     }
     return state;
 }
+/**
+ * Get the current Monora state, or null if not initialized.
+ * Use this for optional event emission where initialization isn't required.
+ */
+function getState() {
+    return state;
+}
 function isRecoveredEventValid(event, config) {
     if (!event || typeof event !== 'object') {
         return false;
@@ -640,7 +772,7 @@ function emitEvent(event, options) {
         }
         return;
     }
-    if ((0, context_1.getCurrentSpan)() || recovered) {
+    if ((0, context_1.getCurrentSpan)()) {
         try {
             current.reportManager.recordEvent(event);
         }
@@ -650,6 +782,38 @@ function emitEvent(event, options) {
     }
     current.dispatcher.emit(event);
 }
+function emitInternal(payload, body, options) {
+    const current = getState();
+    if (!current) {
+        return null;
+    }
+    const raw = typeof payload === 'object' && payload ? payload : {};
+    const eventType = (typeof payload === 'string' ? payload : undefined) ||
+        raw.event_type ||
+        'custom';
+    const eventBody = body !== undefined ? body : (raw.body || {});
+    const normalizedBody = eventBody && typeof eventBody === 'object' && !Array.isArray(eventBody)
+        ? eventBody
+        : { value: eventBody };
+    const built = current.eventBuilder.build(eventType, normalizedBody, {
+        dataClassification: options?.dataClassification ||
+            raw.data_classification ||
+            current.config.defaults?.data_classification ||
+            'internal',
+        purpose: options?.purpose ||
+            raw.purpose ||
+            current.config.defaults?.purpose ||
+            'governance',
+        reason: options?.reason || raw.reason || undefined,
+        parentEventId: options?.parentEventId || raw.parent_event_id || undefined,
+    });
+    const traceId = options?.traceId || raw.trace_id;
+    if (traceId) {
+        built.trace_id = traceId;
+    }
+    emitEvent(built);
+    return built;
+}
 /**
  * Verify event hash in real-time as it's emitted.
  *
@@ -657,8 +821,10 @@ function emitEvent(event, options) {
  * Failures are logged as warnings (user decision: don't block).
  */
 function verifyEventRealTime(event, expectedPrevHash) {
-    // Lazy import to avoid circular dependency
-    const { verifyEventHash } = require('./verify');
+    const verifyEventHash = getVerifyEventHash();
+    if (!verifyEventHash) {
+        return;
+    }
     try {
         if (!verifyEventHash(event)) {
             logger_1.logger.error('Real-time verification FAILED: event %s has invalid hash', event.event_id);
@@ -673,8 +839,8 @@ function verifyEventRealTime(event, expectedPrevHash) {
 }
 function notifyViolation(violation) {
     const current = ensureState();
-    // Record violation metric
-    const policyType = violation.policyName || 'model_policy';
+    // Record violation metric (policyType matches Python SDK's policy_type attribute)
+    const policyType = violation.policyType || 'model_policy';
     const model = violation.model || 'unknown';
     (0, telemetry_1.recordViolation)(policyType, model);
     if (!current.violationHandler) {
@@ -687,14 +853,43 @@ function notifyViolation(violation) {
         logger_1.logger.error('Violation handler error: %s', error);
     }
 }
-function handleTraceCompletion(traceId) {
+function emitSpanEvent(current, span, eventType, durationMs) {
+    const tracingConfig = current.config.tracing || {};
+    if (tracingConfig.emit_span_events === false) {
+        return;
+    }
+    const body = {
+        name: span.name,
+        metadata: span.metadata,
+    };
+    if (durationMs !== undefined) {
+        body.duration_ms = durationMs;
+    }
+    const event = current.eventBuilder.build(eventType, body);
+    emitEvent(event);
+}
+function handleTraceStart(span) {
+    const current = state;
+    if (!current) {
+        return;
+    }
+    emitSpanEvent(current, span, 'span_start');
+}
+function handleTraceCompletion(span) {
     const current = state;
-    if (!current || !current.reportManager.isEnabled()) {
+    if (!current) {
+        return;
+    }
+    const traceStart = (0, context_1.getTraceStartTime)(span.traceId);
+    const durationMs = traceStart !== undefined ? Math.max(0, Date.now() - traceStart) : undefined;
+    emitSpanEvent(current, span, 'span_end', durationMs);
+    current.quotaManager.removeTrace(span.traceId);
+    if (!current.reportManager.isEnabled()) {
         return;
     }
     try {
         const registryMetadata = buildRegistryMetadata(current.registry);
-        const result = current.reportManager.finalizeTrace(traceId, registryMetadata);
+        const result = current.reportManager.finalizeTrace(span.traceId, registryMetadata);
         if (!result) {
             return;
         }
@@ -755,6 +950,8 @@ function executeCall(current, fn, args, config, context) {
     const purpose = options.purpose || current.config.defaults?.purpose || 'general';
     const reason = options.reason;
     const resolvedModel = options.model || resolveModelFromArgs(args, current.registry);
+    const span = (0, context_1.getCurrentSpan)();
+    const traceId = span ? span.traceId : null;
     if (config.eventType === 'tool_call' && options.toolName) {
         try {
             const violation = current.toolPolicyEngine.checkTool(options.toolName);
@@ -870,6 +1067,9 @@ function executeCall(current, fn, args, config, context) {
             throw violation;
         }
     }
+    if (config.eventType === 'llm_call') {
+        applyQuotaLimits(current, traceId, resolvedModel, dataClassification, purpose, reason);
+    }
     const startTime = perf_hooks_1.performance.now();
     const stepNumber = config.eventType === 'agent_step' ? (0, context_1.nextStepNumber)() : undefined;
     try {
@@ -899,9 +1099,17 @@ function executeCall(current, fn, args, config, context) {
                     reason,
                 });
                 emitEvent(event);
+                if (config.eventType === 'llm_call') {
+                    const { tokens, usage } = extractUsageMetrics(response);
+                    const cost = estimateUsageCost(current, resolvedModel, usage, tokens);
+                    applyQuotaLimits(current, traceId, resolvedModel, dataClassification, purpose, reason, tokens || [0, 0], cost ?? undefined);
+                }
                 return response;
             })
                 .catch((error) => {
+                if (error instanceof quotas_1.QuotaExceededError) {
+                    throw error;
+                }
                 const durationMs = perf_hooks_1.performance.now() - startTime;
                 const logErrors = current.config.error_handling?.log_user_exceptions !== false;
                 const body = config.buildBody({
@@ -925,6 +1133,9 @@ function executeCall(current, fn, args, config, context) {
                     reason,
                 });
                 emitEvent(event);
+                if (config.eventType === 'llm_call') {
+                    applyQuotaLimits(current, traceId, resolvedModel, dataClassification, purpose, reason, [0, 0], undefined, false);
+                }
                 throw error;
             });
         }
@@ -950,10 +1161,17 @@ function executeCall(current, fn, args, config, context) {
             reason,
         });
         emitEvent(event);
+        if (config.eventType === 'llm_call') {
+            const { tokens, usage } = extractUsageMetrics(result);
+            const cost = estimateUsageCost(current, resolvedModel, usage, tokens);
+            applyQuotaLimits(current, traceId, resolvedModel, dataClassification, purpose, reason, tokens || [0, 0], cost ?? undefined);
+        }
         return result;
     }
     catch (error) {
-        if (error instanceof data_handling_1.DataHandlingViolation || error instanceof policy_1.PolicyViolation) {
+        if (error instanceof data_handling_1.DataHandlingViolation ||
+            error instanceof policy_1.PolicyViolation ||
+            error instanceof quotas_1.QuotaExceededError) {
             throw error;
         }
         const durationMs = perf_hooks_1.performance.now() - startTime;
@@ -979,6 +1197,9 @@ function executeCall(current, fn, args, config, context) {
             reason,
         });
         emitEvent(event);
+        if (config.eventType === 'llm_call') {
+            applyQuotaLimits(current, traceId, resolvedModel, dataClassification, purpose, reason, [0, 0], undefined, false);
+        }
         throw error;
     }
 }
@@ -1030,6 +1251,48 @@ function emitRegistryOverride(current, model, dataClassification, purpose, reaso
     emitEvent(event);
     return event.event_id || null;
 }
+function applyQuotaLimits(current, traceId, model, dataClassification, purpose, reason, tokens, cost, raiseOnBlock = true) {
+    if (!traceId || !current.quotaManager.isEnabled()) {
+        return;
+    }
+    const tracker = current.quotaManager.getTracker(traceId);
+    if (tokens || cost !== undefined) {
+        const [promptTokens, completionTokens] = tokens || [0, 0];
+        tracker.recordTokenUsage(promptTokens, completionTokens, cost);
+    }
+    const result = tracker.checkQuotas();
+    if (result.allowed) {
+        return;
+    }
+    emitQuotaViolation(current.eventBuilder, model, result, dataClassification, purpose, reason);
+    const violation = new quotas_1.QuotaExceededError(result.exceededQuota || 'unknown', result.currentValue || 0, result.limitValue || 0, model);
+    notifyViolation(violation);
+    const action = tracker.getConfig().action;
+    if (action === 'block' && raiseOnBlock) {
+        throw violation;
+    }
+    logger_1.logger.warning('Quota warning: %s', result.message);
+}
+function emitQuotaViolation(builder, model, result, dataClassification, purpose, reason) {
+    const body = {
+        model,
+        policy_name: `quota.${result.exceededQuota || 'unknown'}`,
+        message: result.message,
+        status: 'policy_violation',
+        error: null,
+        quota: {
+            type: result.exceededQuota ?? null,
+            current_value: result.currentValue ?? null,
+            limit_value: result.limitValue ?? null,
+        },
+    };
+    const event = builder.build('llm_call', body, {
+        dataClassification,
+        purpose,
+        reason,
+    });
+    emitEvent(event);
+}
 function buildLlmBody(params) {
     const responseDetails = params.response ? extractResponseDetails(params.response) : null;
     let explanation;
@@ -1101,6 +1364,132 @@ function extractResponseDetails(response) {
     }
     return { content, finish_reason: finishReason, usage };
 }
+function extractUsageMetrics(response) {
+    if (!response) {
+        return { tokens: null, usage: null };
+    }
+    const details = extractResponseDetails(response);
+    const usage = details && typeof details === 'object' ? details.usage : null;
+    return { tokens: normalizeTokenUsage(usage), usage };
+}
+function estimateUsageCost(current, model, usage, tokens) {
+    if (!usage || typeof usage !== 'object') {
+        return null;
+    }
+    for (const key of ['total_cost', 'cost', 'estimated_cost', 'total_cost_usd', 'cost_usd']) {
+        const value = usage[key];
+        const cost = coerceCost(value);
+        if (cost !== null) {
+            return cost;
+        }
+    }
+    if (!model || !tokens) {
+        return null;
+    }
+    const metadata = current.registry.getModelMetadata(model);
+    const pricing = metadata && typeof metadata === 'object' ? metadata.pricing : null;
+    return estimateCostFromPricing(pricing, tokens);
+}
+function estimateCostFromPricing(pricing, tokens) {
+    if (!pricing || typeof pricing !== 'object') {
+        return null;
+    }
+    const [promptTokens, completionTokens] = tokens;
+    const pickRatePerToken = (candidates) => {
+        for (const candidate of candidates) {
+            if (!(candidate.key in pricing)) {
+                continue;
+            }
+            const cost = coerceCost(pricing[candidate.key]);
+            if (cost === null) {
+                continue;
+            }
+            return cost / candidate.scale;
+        }
+        return null;
+    };
+    const totalRate = pickRatePerToken([
+        { key: 'cost_per_token', scale: 1 },
+        { key: 'cost_per_1k_tokens', scale: 1000 },
+        { key: 'total_cost_per_1k', scale: 1000 },
+        { key: 'cost_per_1m_tokens', scale: 1000000 },
+        { key: 'total_cost_per_1m', scale: 1000000 },
+    ]);
+    const promptRate = pickRatePerToken([
+        { key: 'prompt_cost_per_token', scale: 1 },
+        { key: 'input_cost_per_token', scale: 1 },
+        { key: 'prompt_cost_per_1k', scale: 1000 },
+        { key: 'input_cost_per_1k', scale: 1000 },
+        { key: 'prompt_cost_per_1m', scale: 1000000 },
+        { key: 'input_cost_per_1m', scale: 1000000 },
+    ]);
+    const completionRate = pickRatePerToken([
+        { key: 'completion_cost_per_token', scale: 1 },
+        { key: 'output_cost_per_token', scale: 1 },
+        { key: 'completion_cost_per_1k', scale: 1000 },
+        { key: 'output_cost_per_1k', scale: 1000 },
+        { key: 'completion_cost_per_1m', scale: 1000000 },
+        { key: 'output_cost_per_1m', scale: 1000000 },
+    ]);
+    if (totalRate !== null) {
+        return (promptTokens + completionTokens) * totalRate;
+    }
+    if (promptRate === null && completionRate === null) {
+        return null;
+    }
+    let cost = 0;
+    if (promptRate !== null) {
+        cost += promptTokens * promptRate;
+    }
+    if (completionRate !== null) {
+        cost += completionTokens * completionRate;
+    }
+    return cost;
+}
+function normalizeTokenUsage(usage) {
+    if (!usage || typeof usage !== 'object') {
+        return null;
+    }
+    let prompt = coerceToken(usage.prompt_tokens);
+    let completion = coerceToken(usage.completion_tokens);
+    if (prompt === null) {
+        prompt = coerceToken(usage.input_tokens);
+    }
+    if (completion === null) {
+        completion = coerceToken(usage.output_tokens);
+    }
+    const total = coerceToken(usage.total_tokens);
+    if (prompt === null && completion === null && total === null) {
+        return null;
+    }
+    if (prompt === null) {
+        prompt = Math.max(0, (total || 0) - (completion || 0));
+    }
+    if (completion === null) {
+        completion = Math.max(0, (total || 0) - (prompt || 0));
+    }
+    return [prompt || 0, completion || 0];
+}
+function coerceToken(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    const number = Number(value);
+    if (!Number.isFinite(number)) {
+        return null;
+    }
+    return Math.trunc(number);
+}
+function coerceCost(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    const number = Number(value);
+    if (!Number.isFinite(number)) {
+        return null;
+    }
+    return number;
+}
 function formatError(error) {
     return { type: error.name || 'Error', message: error.message || String(error) };
 }
@@ -1180,7 +1569,7 @@ function buildSinks(sinkConfigs, failFast) {
         const sinkType = String(config.type || '').toLowerCase();
         try {
             if (sinkType === 'stdout') {
-                sinks.push(new sinks_1.StdoutSink(config.format || 'json'));
+                sinks.push(new sinks_1.StdoutSink(config.format || 'pretty'));
             }
             else if (sinkType === 'file') {
                 sinks.push(new sinks_1.FileSink(config.path, {
@@ -1188,6 +1577,7 @@ function buildSinks(sinkConfigs, failFast) {
                     flushIntervalSec: config.flush_interval_sec || 5.0,
                     rotation: config.rotation || 'none',
                     maxSizeMb: config.max_size_mb,
+                    symlink: config.symlink,
                 }));
             }
             else if (sinkType === 'https' || sinkType === 'http') {
@@ -1206,6 +1596,12 @@ function buildSinks(sinkConfigs, failFast) {
                         headerName: config.idempotency.header_name,
                     }
                     : undefined;
+                const dataResidencyConfig = config.data_residency
+                    ? {
+                        residency: config.data_residency,
+                        action: config.data_residency_action,
+                    }
+                    : undefined;
                 sinks.push(new sinks_1.HttpSink(config.endpoint, headers, {
                     batchSize: config.batch_size || 50,
                     timeoutSec: config.timeout_sec || 10.0,
@@ -1214,6 +1610,7 @@ function buildSinks(sinkConfigs, failFast) {
                     circuitBreaker: config.circuit_breaker,
                     retryQueue: retryQueueConfig,
                     idempotency: idempotencyConfig,
+                    dataResidency: dataResidencyConfig,
                 }));
             }
             else if (sinkType) {
@@ -1252,5 +1649,6 @@ function findEventSource(config) {
             return String(sink.path);
         }
     }
-    return config.error_handling?.fallback_path;
+    const fallback = config.error_handling?.fallback_path;
+    return fallback ? String(fallback) : undefined;
 }