cognitive-modules-cli 1.4.1 → 2.2.1

package/dist/modules/runner.js

@@ -1,28 +1,712 @@
 /**
  * Module Runner - Execute Cognitive Modules
- * v2.5: Streaming response and multimodal support
+ * v2.2: Envelope format with meta/data separation, risk_rule, repair pass
+ * v2.2.1: Version field, enhanced error taxonomy, observability hooks, streaming
  */
-import { aggregateRisk, isV22Envelope, isProviderV25, isModuleV25, moduleSupportsStreaming, moduleSupportsMultimodal, getModuleInputModalities, ErrorCodesV25, DEFAULT_RUNTIME_CAPABILITIES } from '../types.js';
-import { randomUUID } from 'crypto';
-import { readFile } from 'fs/promises';
-import { existsSync } from 'fs';
-import { extname } from 'path';
+import _Ajv from 'ajv';
+const Ajv = _Ajv.default || _Ajv;
+import { aggregateRisk, isV22Envelope } from '../types.js';
+// =============================================================================
+// Schema Validation
+// =============================================================================
+const ajv = new Ajv({ allErrors: true, strict: false });
+/**
+ * Validate data against JSON schema. Returns list of errors.
+ */
+export function validateData(data, schema, label = 'Data') {
+    const errors = [];
+    if (!schema || Object.keys(schema).length === 0) {
+        return errors;
+    }
+    try {
+        const validate = ajv.compile(schema);
+        const valid = validate(data);
+        if (!valid && validate.errors) {
+            for (const err of validate.errors) {
+                const path = err.instancePath || '/';
+                errors.push(`${label} validation error: ${err.message} at ${path}`);
+            }
+        }
+    }
+    catch (e) {
+        errors.push(`Schema error: ${e.message}`);
+    }
+    return errors;
+}
+/** Tool categories for automatic policy mapping */
+const TOOL_POLICY_MAPPING = {
+    // Network tools
+    'fetch': ['network'],
+    'http': ['network'],
+    'request': ['network'],
+    'curl': ['network'],
+    'wget': ['network'],
+    'api_call': ['network'],
+    // Filesystem tools
+    'write_file': ['filesystem_write', 'side_effects'],
+    'create_file': ['filesystem_write', 'side_effects'],
+    'delete_file': ['filesystem_write', 'side_effects'],
+    'rename_file': ['filesystem_write', 'side_effects'],
+    'mkdir': ['filesystem_write', 'side_effects'],
+    'rmdir': ['filesystem_write', 'side_effects'],
+    // Code execution tools
+    'shell': ['code_execution', 'side_effects'],
+    'exec': ['code_execution', 'side_effects'],
+    'run_code': ['code_execution', 'side_effects'],
+    'code_interpreter': ['code_execution', 'side_effects'],
+    'eval': ['code_execution', 'side_effects'],
+    // Database tools
+    'sql_query': ['side_effects'],
+    'db_write': ['side_effects'],
+};
+/**
+ * Check if a tool is allowed by the module's tools policy.
+ *
+ * @param toolName The name of the tool to check
+ * @param module The cognitive module config
+ * @returns PolicyCheckResult indicating if the tool is allowed
+ *
+ * @example
+ * const result = checkToolPolicy('write_file', module);
+ * if (!result.allowed) {
+ *   throw new Error(result.reason);
+ * }
+ */
+export function checkToolPolicy(toolName, module) {
+    const toolsPolicy = module.tools;
+    // No policy = allow all
+    if (!toolsPolicy) {
+        return { allowed: true };
+    }
+    const normalizedName = toolName.toLowerCase().replace(/[-\s]/g, '_');
+    // Check explicit denied list first
+    if (toolsPolicy.denied?.some(d => d.toLowerCase().replace(/[-\s]/g, '_') === normalizedName)) {
+        return {
+            allowed: false,
+            reason: `Tool '${toolName}' is explicitly denied by module tools policy`,
+            policy: 'tools.denied'
+        };
+    }
+    // Check policy mode
+    if (toolsPolicy.policy === 'deny_by_default') {
+        // In deny_by_default mode, tool must be in allowed list
+        const isAllowed = toolsPolicy.allowed?.some(a => a.toLowerCase().replace(/[-\s]/g, '_') === normalizedName);
+        if (!isAllowed) {
+            return {
+                allowed: false,
+                reason: `Tool '${toolName}' not in allowed list (policy: deny_by_default)`,
+                policy: 'tools.policy'
+            };
+        }
+    }
+    return { allowed: true };
+}
+/**
+ * Check if an action is allowed by the module's policies.
+ *
+ * @param action The action to check (network, filesystem_write, etc.)
+ * @param module The cognitive module config
+ * @returns PolicyCheckResult indicating if the action is allowed
+ *
+ * @example
+ * const result = checkPolicy('network', module);
+ * if (!result.allowed) {
+ *   throw new Error(result.reason);
+ * }
+ */
+export function checkPolicy(action, module) {
+    const policies = module.policies;
+    // No policies = allow all
+    if (!policies) {
+        return { allowed: true };
+    }
+    // Check the specific policy
+    if (policies[action] === 'deny') {
+        return {
+            allowed: false,
+            reason: `Action '${action}' is denied by module policy`,
+            policy: `policies.${action}`
+        };
+    }
+    return { allowed: true };
+}
+/**
+ * Check if a tool is allowed considering both tools policy and general policies.
+ * This performs a comprehensive check that:
+ * 1. Checks the tools policy (allowed/denied lists)
+ * 2. Maps the tool to policy actions and checks those
+ *
+ * @param toolName The name of the tool to check
+ * @param module The cognitive module config
+ * @returns PolicyCheckResult with detailed information
+ *
+ * @example
+ * const result = checkToolAllowed('write_file', module);
+ * if (!result.allowed) {
+ *   return makeErrorResponse({
+ *     code: 'POLICY_VIOLATION',
+ *     message: result.reason,
+ *   });
+ * }
+ */
+export function checkToolAllowed(toolName, module) {
+    // First check explicit tools policy
+    const toolCheck = checkToolPolicy(toolName, module);
+    if (!toolCheck.allowed) {
+        return toolCheck;
+    }
+    // Then check mapped policies
+    const normalizedName = toolName.toLowerCase().replace(/[-\s]/g, '_');
+    const mappedActions = TOOL_POLICY_MAPPING[normalizedName] || [];
+    for (const action of mappedActions) {
+        const policyCheck = checkPolicy(action, module);
+        if (!policyCheck.allowed) {
+            return {
+                allowed: false,
+                reason: `Tool '${toolName}' requires '${action}' which is denied by policy`,
+                policy: policyCheck.policy
+            };
+        }
+    }
+    return { allowed: true };
+}
+/**
+ * Validate that a list of tools are all allowed by the module's policies.
+ * Returns all violations found.
+ *
+ * @param toolNames List of tool names to check
+ * @param module The cognitive module config
+ * @returns Array of PolicyCheckResult for denied tools
+ */
+export function validateToolsAllowed(toolNames, module) {
+    const violations = [];
+    for (const toolName of toolNames) {
+        const result = checkToolAllowed(toolName, module);
+        if (!result.allowed) {
+            violations.push(result);
+        }
+    }
+    return violations;
+}
+/**
+ * Get all denied actions for a module based on its policies.
+ * Useful for informing LLM about restrictions.
+ */
+export function getDeniedActions(module) {
+    const denied = [];
+    const policies = module.policies;
+    if (!policies)
+        return denied;
+    const actions = ['network', 'filesystem_write', 'side_effects', 'code_execution'];
+    for (const action of actions) {
+        if (policies[action] === 'deny') {
+            denied.push(action);
+        }
+    }
+    return denied;
+}
+/**
+ * Get all denied tools for a module based on its tools policy.
+ */
+export function getDeniedTools(module) {
+    return module.tools?.denied || [];
+}
+/**
+ * Get all allowed tools for a module (only meaningful in deny_by_default mode).
+ */
+export function getAllowedTools(module) {
+    if (module.tools?.policy === 'deny_by_default') {
+        return module.tools.allowed || [];
+    }
+    return null; // null means "all allowed except denied list"
+}
+/**
+ * ToolCallInterceptor - Intercepts and validates tool calls against module policies.
+ *
+ * Use this class to wrap tool execution with policy enforcement:
+ *
+ * @example
+ * const interceptor = new ToolCallInterceptor(module);
+ *
+ * // Register tool executors
+ * interceptor.registerTool('read_file', async (args) => {
+ *   return fs.readFile(args.path as string, 'utf-8');
+ * });
+ *
+ * // Execute tool with policy check
+ * const result = await interceptor.execute({
+ *   name: 'write_file',
+ *   arguments: { path: '/tmp/test.txt', content: 'hello' }
+ * });
+ *
+ * if (!result.success) {
+ *   console.error('Tool blocked:', result.error);
+ * }
+ */
+export class ToolCallInterceptor {
+    module;
+    tools = new Map();
+    callLog = [];
+    constructor(module) {
+        this.module = module;
+    }
+    /**
+     * Register a tool executor.
+     */
+    registerTool(name, executor) {
+        this.tools.set(name.toLowerCase(), executor);
+    }
+    /**
+     * Register multiple tools at once.
+     */
+    registerTools(tools) {
+        for (const [name, executor] of Object.entries(tools)) {
+            this.registerTool(name, executor);
+        }
+    }
+    /**
+     * Check if a tool call is allowed without executing it.
+     */
+    checkAllowed(toolName) {
+        return checkToolAllowed(toolName, this.module);
+    }
+    /**
+     * Execute a tool call with policy enforcement.
+     *
+     * @param request The tool call request
+     * @returns ToolCallResult with success/error
+     */
+    async execute(request) {
+        const { name, arguments: args } = request;
+        const timestamp = Date.now();
+        // Check policy
+        const policyResult = checkToolAllowed(name, this.module);
+        if (!policyResult.allowed) {
+            this.callLog.push({ tool: name, allowed: false, timestamp });
+            return {
+                success: false,
+                error: {
+                    code: 'TOOL_NOT_ALLOWED',
+                    message: policyResult.reason || `Tool '${name}' is not allowed`,
+                },
+            };
+        }
+        // Find executor
+        const executor = this.tools.get(name.toLowerCase());
+        if (!executor) {
+            return {
+                success: false,
+                error: {
+                    code: 'TOOL_NOT_FOUND',
+                    message: `Tool '${name}' is not registered`,
+                },
+            };
+        }
+        // Execute
+        try {
+            this.callLog.push({ tool: name, allowed: true, timestamp });
+            const result = await executor(args);
+            return { success: true, result };
+        }
+        catch (e) {
+            return {
+                success: false,
+                error: {
+                    code: 'TOOL_EXECUTION_ERROR',
+                    message: e.message,
+                },
+            };
+        }
+    }
+    /**
+     * Execute multiple tool calls in sequence.
+     * Stops on first policy violation.
+     */
+    async executeMany(requests) {
+        const results = [];
+        for (const request of requests) {
+            const result = await this.execute(request);
+            results.push(result);
+            // Stop on policy violation (not execution error)
+            if (!result.success && result.error?.code === 'TOOL_NOT_ALLOWED') {
+                break;
+            }
+        }
+        return results;
+    }
+    /**
+     * Get the call log for auditing.
+     */
+    getCallLog() {
+        return [...this.callLog];
+    }
+    /**
+     * Get summary of denied calls.
+     */
+    getDeniedCalls() {
+        return this.callLog
+            .filter(c => !c.allowed)
+            .map(({ tool, timestamp }) => ({ tool, timestamp }));
+    }
+    /**
+     * Clear the call log.
+     */
+    clearLog() {
+        this.callLog = [];
+    }
+    /**
+     * Get policy summary for this module.
+     */
+    getPolicySummary() {
+        return {
+            deniedActions: getDeniedActions(this.module),
+            deniedTools: getDeniedTools(this.module),
+            allowedTools: getAllowedTools(this.module),
+            toolsPolicy: this.module.tools?.policy,
+        };
+    }
+}
+/**
+ * Create a policy-aware tool executor wrapper.
+ *
+ * @example
+ * const safeExecutor = createPolicyAwareExecutor(module, 'write_file', async (args) => {
+ *   return fs.writeFile(args.path, args.content);
+ * });
+ *
+ * // This will throw if write_file is denied
+ * await safeExecutor({ path: '/tmp/test.txt', content: 'hello' });
+ */
+export function createPolicyAwareExecutor(module, toolName, executor) {
+    return async (args) => {
+        const policyResult = checkToolAllowed(toolName, module);
+        if (!policyResult.allowed) {
+            throw new Error(`Policy violation: ${policyResult.reason}`);
+        }
+        return executor(args);
+    };
+}
+// =============================================================================
+// v2.2 Runtime Enforcement - Overflow & Enum
+// =============================================================================
+/**
+ * Validate overflow.insights against module's max_items config.
+ *
+ * @param data The response data object
+ * @param module The cognitive module config
+ * @returns Array of errors if insights exceed limit
+ */
+export function validateOverflowLimits(data, module) {
+    const errors = [];
+    const overflowConfig = module.overflow;
+    if (!overflowConfig?.enabled) {
+        // If overflow disabled, insights should not exist
+        const extensions = data.extensions;
+        if (extensions?.insights && Array.isArray(extensions.insights) && extensions.insights.length > 0) {
+            errors.push('Overflow is disabled but extensions.insights contains data');
+        }
+        return errors;
+    }
+    const maxItems = overflowConfig.max_items ?? 5;
+    const extensions = data.extensions;
+    if (extensions?.insights && Array.isArray(extensions.insights)) {
+        const insights = extensions.insights;
+        if (insights.length > maxItems) {
+            errors.push(`overflow.max_items exceeded: ${insights.length} > ${maxItems}`);
+        }
+        // Check require_suggested_mapping
+        if (overflowConfig.require_suggested_mapping) {
+            for (let i = 0; i < insights.length; i++) {
+                const insight = insights[i];
+                if (!insight.suggested_mapping) {
+                    errors.push(`insight[${i}] missing required suggested_mapping`);
+                }
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Validate enum values against module's enum strategy.
+ * For strict mode, custom enum objects are not allowed.
+ *
+ * @param data The response data object
+ * @param module The cognitive module config
+ * @returns Array of errors if enum violations found
+ */
+export function validateEnumStrategy(data, module) {
+    const errors = [];
+    const enumStrategy = module.enums?.strategy ?? 'strict';
+    if (enumStrategy === 'strict') {
+        // In strict mode, custom enum objects (with 'custom' key) are not allowed
+        const checkForCustomEnums = (obj, path) => {
+            if (obj === null || obj === undefined)
+                return;
+            if (Array.isArray(obj)) {
+                obj.forEach((item, i) => checkForCustomEnums(item, `${path}[${i}]`));
+            }
+            else if (typeof obj === 'object') {
+                const record = obj;
+                // Check if this is a custom enum object
+                if ('custom' in record && 'reason' in record && Object.keys(record).length === 2) {
+                    errors.push(`Custom enum not allowed in strict mode at ${path}: { custom: "${record.custom}" }`);
+                    return;
+                }
+                // Recurse into nested objects
+                for (const [key, value] of Object.entries(record)) {
+                    checkForCustomEnums(value, `${path}.${key}`);
+                }
+            }
+        };
+        checkForCustomEnums(data, 'data');
+    }
+    return errors;
+}
+// =============================================================================
+// Constants
+// =============================================================================
+const ENVELOPE_VERSION = '2.2';
+// =============================================================================
+// Utility Functions
+// =============================================================================
+/**
+ * Deep clone an object to avoid mutation issues.
+ * Handles nested objects, arrays, and primitive values.
+ */
+function deepClone(obj) {
+    if (obj === null || typeof obj !== 'object') {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(item => deepClone(item));
+    }
+    const cloned = {};
+    for (const key in obj) {
+        if (Object.prototype.hasOwnProperty.call(obj, key)) {
+            cloned[key] = deepClone(obj[key]);
+        }
+    }
+    return cloned;
+}
+// Global hook registries
+const _beforeCallHooks = [];
+const _afterCallHooks = [];
+const _errorHooks = [];
+/**
+ * Decorator to register a before-call hook.
+ *
+ * @example
+ * onBeforeCall((moduleName, inputData, config) => {
+ *   console.log(`Calling ${moduleName} with`, inputData);
+ * });
+ */
+export function onBeforeCall(hook) {
+    _beforeCallHooks.push(hook);
+    return hook;
+}
+/**
+ * Decorator to register an after-call hook.
+ *
+ * @example
+ * onAfterCall((moduleName, result, latencyMs) => {
+ *   console.log(`${moduleName} completed in ${latencyMs}ms`);
+ * });
+ */
+export function onAfterCall(hook) {
+    _afterCallHooks.push(hook);
+    return hook;
+}
+/**
+ * Decorator to register an error hook.
+ *
+ * @example
+ * onError((moduleName, error, partialResult) => {
+ *   console.error(`Error in ${moduleName}:`, error);
+ * });
+ */
+export function onError(hook) {
+    _errorHooks.push(hook);
+    return hook;
+}
+/**
+ * Register a hook programmatically.
+ */
+export function registerHook(hookType, hook) {
+    if (hookType === 'before_call') {
+        _beforeCallHooks.push(hook);
+    }
+    else if (hookType === 'after_call') {
+        _afterCallHooks.push(hook);
+    }
+    else if (hookType === 'error') {
+        _errorHooks.push(hook);
+    }
+    else {
+        throw new Error(`Unknown hook type: ${hookType}`);
+    }
+}
+/**
+ * Unregister a hook. Returns true if found and removed.
+ */
+export function unregisterHook(hookType, hook) {
+    let hooks;
+    if (hookType === 'before_call') {
+        hooks = _beforeCallHooks;
+    }
+    else if (hookType === 'after_call') {
+        hooks = _afterCallHooks;
+    }
+    else if (hookType === 'error') {
+        hooks = _errorHooks;
+    }
+    else {
+        return false;
+    }
+    const index = hooks.indexOf(hook);
+    if (index !== -1) {
+        hooks.splice(index, 1);
+        return true;
+    }
+    return false;
+}
+/**
+ * Clear all registered hooks.
+ */
+export function clearHooks() {
+    _beforeCallHooks.length = 0;
+    _afterCallHooks.length = 0;
+    _errorHooks.length = 0;
+}
+function _invokeBeforeHooks(moduleName, inputData, moduleConfig) {
+    for (const hook of _beforeCallHooks) {
+        try {
+            hook(moduleName, inputData, moduleConfig);
+        }
+        catch {
+            // Hooks should not break the main flow
+        }
+    }
+}
+function _invokeAfterHooks(moduleName, result, latencyMs) {
+    for (const hook of _afterCallHooks) {
+        try {
+            hook(moduleName, result, latencyMs);
+        }
+        catch {
+            // Hooks should not break the main flow
+        }
+    }
+}
+function _invokeErrorHooks(moduleName, error, partialResult) {
+    for (const hook of _errorHooks) {
+        try {
+            hook(moduleName, error, partialResult);
+        }
+        catch {
+            // Hooks should not break the main flow
+        }
+    }
+}
+// =============================================================================
+// Error Response Builder
+// =============================================================================
+/** Error codes and their default properties */
+export const ERROR_PROPERTIES = {
+    MODULE_NOT_FOUND: { recoverable: false, retry_after_ms: null },
+    INVALID_INPUT: { recoverable: false, retry_after_ms: null },
+    PARSE_ERROR: { recoverable: true, retry_after_ms: 1000 },
+    SCHEMA_VALIDATION_FAILED: { recoverable: true, retry_after_ms: 1000 },
+    META_VALIDATION_FAILED: { recoverable: true, retry_after_ms: 1000 },
+    POLICY_VIOLATION: { recoverable: false, retry_after_ms: null },
+    TOOL_NOT_ALLOWED: { recoverable: false, retry_after_ms: null },
+    LLM_ERROR: { recoverable: true, retry_after_ms: 5000 },
+    RATE_LIMITED: { recoverable: true, retry_after_ms: 10000 },
+    TIMEOUT: { recoverable: true, retry_after_ms: 5000 },
+    UNKNOWN: { recoverable: false, retry_after_ms: null },
+};
+/**
+ * Build a standardized error response with enhanced taxonomy.
+ */
+export function makeErrorResponse(options) {
+    const { code, message, explain, partialData, details, recoverable, retryAfterMs, confidence = 0.0, risk = 'high', } = options;
+    // Get default properties from error code
+    const defaults = ERROR_PROPERTIES[code] || ERROR_PROPERTIES.UNKNOWN;
+    const errorObj = {
+        code,
+        message,
+    };
+    // Add recoverable flag
+    const isRecoverable = recoverable ?? defaults.recoverable;
+    if (isRecoverable !== undefined) {
+        errorObj.recoverable = isRecoverable;
+    }
+    // Add retry suggestion
+    const retryMs = retryAfterMs ?? defaults.retry_after_ms;
+    if (retryMs !== null) {
+        errorObj.retry_after_ms = retryMs;
+    }
+    // Add details if provided
+    if (details) {
+        errorObj.details = details;
+    }
+    return {
+        ok: false,
+        version: ENVELOPE_VERSION,
+        meta: {
+            confidence,
+            risk,
+            explain: (explain || message).slice(0, 280),
+        },
+        error: errorObj,
+        partial_data: partialData,
+    };
+}
+/**
+ * Build a standardized success response.
+ */
+export function makeSuccessResponse(options) {
+    const { data, confidence, risk, explain, latencyMs, model, traceId } = options;
+    const meta = {
+        confidence: Math.max(0.0, Math.min(1.0, confidence)),
+        risk,
+        explain: explain ? explain.slice(0, 280) : 'No explanation provided',
+    };
+    if (latencyMs !== undefined) {
+        meta.latency_ms = latencyMs;
+    }
+    if (model) {
+        meta.model = model;
+    }
+    if (traceId) {
+        meta.trace_id = traceId;
+    }
+    return {
+        ok: true,
+        version: ENVELOPE_VERSION,
+        meta,
+        data,
+    };
+}
 // =============================================================================
 // Repair Pass (v2.2)
 // =============================================================================
 /**
  * Attempt to repair envelope format issues without changing semantics.
  *
- * Repairs (lossless only):
+ * Repairs (mostly lossless, except explain truncation):
  * - Missing meta fields (fill with conservative defaults)
  * - Truncate explain if too long
  * - Trim whitespace from string fields
+ * - Clamp confidence to [0, 1] range
  *
  * Does NOT repair:
  * - Invalid enum values (treated as validation failure)
+ *
+ * Note: Returns a deep copy to avoid modifying the original data.
  */
 function repairEnvelope(response, riskRule = 'max_changes_risk', maxExplainLength = 280) {
-    const repaired = { ...response };
+    // Deep clone to avoid mutation
+    const repaired = deepClone(response);
     // Ensure meta exists
     if (!repaired.meta || typeof repaired.meta !== 'object') {
         repaired.meta = {};
@@ -58,7 +742,7 @@ function repairEnvelope(response, riskRule = 'max_changes_risk', maxExplainLengt
     if (meta.explain.length > maxExplainLength) {
         meta.explain = meta.explain.slice(0, maxExplainLength - 3) + '...';
     }
-    // Build proper v2.2 response
+    // Build proper v2.2 response with version
     const builtMeta = {
         confidence: meta.confidence,
         risk: meta.risk,
@@ -66,21 +750,63 @@ function repairEnvelope(response, riskRule = 'max_changes_risk', maxExplainLengt
     };
     const result = repaired.ok === false ? {
         ok: false,
+        version: ENVELOPE_VERSION,
         meta: builtMeta,
         error: repaired.error ?? { code: 'UNKNOWN', message: 'Unknown error' },
         partial_data: repaired.partial_data
     } : {
         ok: true,
+        version: ENVELOPE_VERSION,
         meta: builtMeta,
         data: repaired.data
     };
     return result;
 }
+/**
+ * Repair error envelope format.
+ *
+ * Note: Returns a deep copy to avoid modifying the original data.
+ */
+function repairErrorEnvelope(data, maxExplainLength = 280) {
+    // Deep clone to avoid mutation
+    const repaired = deepClone(data);
+    // Ensure meta exists for errors
+    if (!repaired.meta || typeof repaired.meta !== 'object') {
+        repaired.meta = {};
+    }
+    const meta = repaired.meta;
+    // Set default meta for errors
+    if (typeof meta.confidence !== 'number') {
+        meta.confidence = 0.0;
+    }
+    if (!meta.risk) {
+        meta.risk = 'high';
+    }
+    if (typeof meta.explain !== 'string') {
+        const error = (repaired.error ?? {});
+        meta.explain = (error.message ?? 'An error occurred').slice(0, maxExplainLength);
+    }
+    return {
+        ok: false,
+        version: ENVELOPE_VERSION,
+        meta: {
+            confidence: meta.confidence,
+            risk: meta.risk,
+            explain: meta.explain,
+        },
+        error: repaired.error ?? { code: 'UNKNOWN', message: 'Unknown error' },
+        partial_data: repaired.partial_data,
+    };
+}
 /**
  * Wrap v2.1 response to v2.2 format
  */
 function wrapV21ToV22(response, riskRule = 'max_changes_risk') {
     if (isV22Envelope(response)) {
+        // Already v2.2, but ensure version field exists
+        if (!('version' in response) || !response.version) {
+            return { ...deepClone(response), version: ENVELOPE_VERSION };
+        }
         return response;
     }
     if (response.ok) {
@@ -89,6 +815,7 @@ function wrapV21ToV22(response, riskRule = 'max_changes_risk') {
         const rationale = data.rationale ?? '';
         return {
             ok: true,
+            version: ENVELOPE_VERSION,
             meta: {
                 confidence,
                 risk: aggregateRisk(data, riskRule),
@@ -101,6 +828,7 @@ function wrapV21ToV22(response, riskRule = 'max_changes_risk') {
         const errorMsg = response.error?.message ?? 'Unknown error';
         return {
             ok: false,
+            version: ENVELOPE_VERSION,
             meta: {
                 confidence: 0,
                 risk: 'high',
@@ -111,8 +839,51 @@ function wrapV21ToV22(response, riskRule = 'max_changes_risk') {
         };
     }
 }
+/**
+ * Convert legacy format (no envelope) to v2.2 envelope.
+ */
+function convertLegacyToEnvelope(data, isError = false) {
+    if (isError || 'error' in data) {
+        const error = (data.error ?? {});
+        const errorMsg = typeof error === 'object'
+            ? (error.message ?? String(error))
+            : String(error);
+        return {
+            ok: false,
+            version: ENVELOPE_VERSION,
+            meta: {
+                confidence: 0.0,
+                risk: 'high',
+                explain: errorMsg.slice(0, 280),
+            },
+            error: {
+                code: (typeof error === 'object' ? error.code : undefined) ?? 'UNKNOWN',
+                message: errorMsg,
+            },
+            partial_data: undefined,
+        };
+    }
+    else {
+        const confidence = data.confidence ?? 0.5;
+        const rationale = data.rationale ?? '';
+        return {
+            ok: true,
+            version: ENVELOPE_VERSION,
+            meta: {
+                confidence,
+                risk: aggregateRisk(data),
+                explain: rationale.slice(0, 280) || 'No explanation provided',
+            },
+            data,
+        };
+    }
+}
+// =============================================================================
+// Main Runner
+// =============================================================================
 export async function runModule(module, provider, options = {}) {
-    const { args, input, verbose = false, useEnvelope, useV22, enableRepair = true } = options;
+    const { args, input, verbose = false, validateInput = true, validateOutput = true, useEnvelope, useV22, enableRepair = true, traceId, model: modelOverride } = options;
+    const startTime = Date.now();
     // Determine if we should use envelope format
     const shouldUseEnvelope = useEnvelope ?? (module.output?.envelope === true || module.format === 'v2');
     // Determine if we should use v2.2 format
@@ -132,6 +903,24 @@ export async function runModule(module, provider, options = {}) {
             inputData.query = args;
         }
     }
+    // Invoke before hooks
+    _invokeBeforeHooks(module.name, inputData, module);
+    // Validate input against schema
+    if (validateInput && module.inputSchema && Object.keys(module.inputSchema).length > 0) {
+        const inputErrors = validateData(inputData, module.inputSchema, 'Input');
+        if (inputErrors.length > 0) {
+            const errorResult = makeErrorResponse({
+                code: 'INVALID_INPUT',
+                message: inputErrors.join('; '),
+                explain: 'Input validation failed.',
+                confidence: 1.0,
+                risk: 'none',
+                details: { validation_errors: inputErrors },
+            });
+            _invokeErrorHooks(module.name, new Error(inputErrors.join('; ')), null);
+            return errorResult;
+        }
+    }
     // Build prompt with clean substitution
     const prompt = buildPrompt(module, inputData);
     if (verbose) {
@@ -184,490 +973,400 @@ export async function runModule(module, provider, options = {}) {
             systemParts.push('- meta.risk must be one of: "none", "low", "medium", "high"');
         }
         else {
-            systemParts.push('', 'RESPONSE FORMAT (Envelope):');
-            systemParts.push('- Wrap your response in the envelope format');
-            systemParts.push('- Success: { "ok": true, "data": { ...your output... } }');
-            systemParts.push('- Error: { "ok": false, "error": { "code": "ERROR_CODE", "message": "..." } }');
-            systemParts.push('- Include "confidence" (0-1) and "rationale" in data');
-        }
-        if (module.output?.require_behavior_equivalence) {
-            systemParts.push('- Include "behavior_equivalence" (boolean) in data');
-        }
-    }
-    else {
-        systemParts.push('', 'OUTPUT FORMAT:');
-        systemParts.push('- Respond with ONLY valid JSON');
-        systemParts.push('- Include "confidence" (0-1) and "rationale" fields');
-        if (module.output?.require_behavior_equivalence) {
-            systemParts.push('- Include "behavior_equivalence" (boolean) field');
-        }
-    }
-    const messages = [
-        { role: 'system', content: systemParts.join('\n') },
-        { role: 'user', content: prompt },
-    ];
-    // Invoke provider
-    const result = await provider.invoke({
-        messages,
-        jsonSchema: module.outputSchema,
-        temperature: 0.3,
-    });
-    if (verbose) {
-        console.error('--- Response ---');
-        console.error(result.content);
-        console.error('--- End Response ---');
-    }
-    // Parse response
-    let parsed;
-    try {
-        const jsonMatch = result.content.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
-        const jsonStr = jsonMatch ? jsonMatch[1] : result.content;
-        parsed = JSON.parse(jsonStr.trim());
-    }
-    catch {
-        throw new Error(`Failed to parse JSON response: ${result.content.substring(0, 500)}`);
-    }
-    // Handle envelope format
-    if (shouldUseEnvelope && isEnvelopeResponse(parsed)) {
-        let response = parseEnvelopeResponse(parsed, result.content);
-        // Upgrade to v2.2 if needed
-        if (shouldUseV22 && response.ok && !('meta' in response && response.meta)) {
-            const upgraded = wrapV21ToV22(parsed, riskRule);
-            response = {
-                ok: true,
-                meta: upgraded.meta,
-                data: upgraded.data,
-                raw: result.content
-            };
-        }
-        // Apply repair pass if enabled and response needs it
-        if (enableRepair && response.ok && shouldUseV22) {
-            const repaired = repairEnvelope(response, riskRule);
-            response = {
-                ok: true,
-                meta: repaired.meta,
-                data: repaired.data,
-                raw: result.content
-            };
-        }
-        return response;
-    }
-    // Handle legacy format (non-envelope)
-    const legacyResult = parseLegacyResponse(parsed, result.content);
-    // Upgrade to v2.2 if requested
-    if (shouldUseV22 && legacyResult.ok) {
-        const data = (legacyResult.data ?? {});
-        return {
-            ok: true,
-            meta: {
-                confidence: data.confidence ?? 0.5,
-                risk: aggregateRisk(data, riskRule),
-                explain: (data.rationale ?? '').slice(0, 280) || 'No explanation provided'
-            },
-            data: legacyResult.data,
-            raw: result.content
-        };
-    }
-    return legacyResult;
-}
-/**
- * Check if response is in envelope format
- */
-function isEnvelopeResponse(obj) {
-    if (typeof obj !== 'object' || obj === null)
-        return false;
-    const o = obj;
-    return typeof o.ok === 'boolean';
-}
-/**
- * Parse envelope format response (supports both v2.1 and v2.2)
- */
-function parseEnvelopeResponse(response, raw) {
-    // Check if v2.2 format (has meta)
-    if (isV22Envelope(response)) {
-        if (response.ok) {
-            return {
-                ok: true,
-                meta: response.meta,
-                data: response.data,
-                raw,
-            };
-        }
-        else {
-            return {
-                ok: false,
-                meta: response.meta,
-                error: response.error,
-                partial_data: response.partial_data,
-                raw,
-            };
-        }
-    }
-    // v2.1 format
-    if (response.ok) {
-        const data = (response.data ?? {});
-        return {
-            ok: true,
-            data: {
-                ...data,
-                confidence: typeof data.confidence === 'number' ? data.confidence : 0.5,
-                rationale: typeof data.rationale === 'string' ? data.rationale : '',
-                behavior_equivalence: data.behavior_equivalence,
-            },
-            raw,
-        };
-    }
-    else {
-        return {
-            ok: false,
-            error: response.error,
-            partial_data: response.partial_data,
-            raw,
-        };
-    }
-}
-/**
- * Parse legacy (non-envelope) format response
- */
-function parseLegacyResponse(output, raw) {
-    const outputObj = output;
-    const confidence = typeof outputObj.confidence === 'number' ? outputObj.confidence : 0.5;
-    const rationale = typeof outputObj.rationale === 'string' ? outputObj.rationale : '';
-    const behaviorEquivalence = typeof outputObj.behavior_equivalence === 'boolean'
-        ? outputObj.behavior_equivalence
-        : undefined;
-    // Check if this is an error response (has error.code)
-    if (outputObj.error && typeof outputObj.error === 'object') {
-        const errorObj = outputObj.error;
-        if (typeof errorObj.code === 'string') {
-            return {
-                ok: false,
-                error: {
-                    code: errorObj.code,
-                    message: typeof errorObj.message === 'string' ? errorObj.message : 'Unknown error',
-                },
-                raw,
-            };
-        }
-    }
-    // Return as v2.1 format (data includes confidence)
-    return {
-        ok: true,
-        data: {
-            ...outputObj,
-            confidence,
-            rationale,
-            behavior_equivalence: behaviorEquivalence,
-        },
-        raw,
-    };
-}
-/**
- * Build prompt with clean variable substitution
- */
-function buildPrompt(module, input) {
-    let prompt = module.prompt;
-    // v2 style: substitute ${variable} placeholders
-    for (const [key, value] of Object.entries(input)) {
-        const strValue = typeof value === 'string' ? value : JSON.stringify(value);
-        prompt = prompt.replace(new RegExp(`\\$\\{${key}\\}`, 'g'), strValue);
-    }
-    // v1 compatibility: substitute $ARGUMENTS
-    const argsValue = input.code || input.query || '';
-    prompt = prompt.replace(/\$ARGUMENTS/g, argsValue);
-    // Substitute $N placeholders (v1 compatibility)
-    if (typeof argsValue === 'string') {
-        const argsList = argsValue.split(/\s+/);
-        argsList.forEach((arg, i) => {
-            prompt = prompt.replace(new RegExp(`\\$${i}\\b`, 'g'), arg);
-        });
-    }
-    // Append input summary if not already in prompt
-    if (!prompt.includes(argsValue) && argsValue) {
-        prompt += '\n\n## Input\n\n';
-        if (input.code) {
-            prompt += '```\n' + input.code + '\n```\n';
-        }
-        if (input.query) {
-            prompt += input.query + '\n';
-        }
-        if (input.language) {
-            prompt += `\nLanguage: ${input.language}\n`;
-        }
-    }
-    return prompt;
-}
-/**
- * Heuristic to detect if input looks like code
- */
-function looksLikeCode(str) {
-    const codeIndicators = [
-        /^(def|function|class|const|let|var|import|export|public|private)\s/,
-        /[{};()]/,
-        /=>/,
-        /\.(py|js|ts|go|rs|java|cpp|c|rb)$/,
-    ];
-    return codeIndicators.some(re => re.test(str));
-}
-/**
- * Create a new streaming session
- */
-function createStreamingSession(moduleName) {
-    return {
-        session_id: `sess_${randomUUID().slice(0, 12)}`,
-        module_name: moduleName,
-        started_at: Date.now(),
-        chunks_sent: 0,
-        accumulated_data: {},
-        accumulated_text: {}
-    };
-}
-/**
- * Create meta chunk (initial streaming response)
- */
-function createMetaChunk(session, meta) {
-    return {
-        ok: true,
-        streaming: true,
-        session_id: session.session_id,
-        meta
-    };
-}
-/**
- * Create delta chunk (incremental content)
- * Note: Delta chunks don't include session_id per v2.5 spec
- */
-function createDeltaChunk(session, field, delta) {
-    session.chunks_sent++;
-    return {
-        chunk: {
-            seq: session.chunks_sent,
-            type: 'delta',
-            field,
-            delta
-        }
-    };
-}
-/**
- * Create progress chunk
- * Note: Progress chunks don't include session_id per v2.5 spec
- */
-function createProgressChunk(_session, percent, stage, message) {
-    return {
-        progress: {
-            percent,
-            stage,
-            message
-        }
-    };
-}
-/**
- * Create final chunk (completion signal)
- * Note: Final chunks don't include session_id per v2.5 spec
- */
-function createFinalChunk(_session, meta, data, usage) {
-    return {
-        final: true,
-        meta,
-        data,
-        usage
-    };
-}
-/**
- * Create error chunk
- */
-function createErrorChunk(session, code, message, recoverable = false, partialData) {
-    return {
-        ok: false,
-        streaming: true,
-        session_id: session.session_id,
-        error: {
-            code,
-            message,
-            recoverable
-        },
-        partial_data: partialData
-    };
-}
-/**
- * Run module with streaming response
- *
- * @param module - The cognitive module to execute
- * @param provider - The LLM provider
- * @param options - Run options including streaming callbacks
- * @yields Streaming chunks
- */
-export async function* runModuleStream(module, provider, options = {}) {
-    const { onChunk, onProgress, heartbeatInterval = 15000, maxDuration = 300000, ...runOptions } = options;
-    // Create streaming session
-    const session = createStreamingSession(module.name);
-    const startTime = Date.now();
-    // Check if module supports streaming
-    if (!moduleSupportsStreaming(module)) {
-        // Fallback to sync execution
-        const result = await runModule(module, provider, runOptions);
-        // Emit as single final chunk
-        if (result.ok && 'meta' in result) {
-            const finalChunk = createFinalChunk(session, result.meta, result.data);
-            yield finalChunk;
-            onChunk?.(finalChunk);
-            return result;
-        }
-        return result;
-    }
-    // Check if provider supports streaming
-    if (!isProviderV25(provider) || !provider.supportsStreaming?.()) {
-        // Fallback to sync with warning
-        console.warn('[cognitive] Provider does not support streaming, falling back to sync');
-        const result = await runModule(module, provider, runOptions);
-        if (result.ok && 'meta' in result) {
-            const finalChunk = createFinalChunk(session, result.meta, result.data);
-            yield finalChunk;
-            onChunk?.(finalChunk);
-        }
-        return result;
-    }
-    // Emit initial meta chunk
-    const metaChunk = createMetaChunk(session, {
-        confidence: undefined,
-        risk: 'low',
-        explain: 'Processing...'
-    });
-    yield metaChunk;
-    onChunk?.(metaChunk);
-    // Build prompt and messages (same as sync)
-    const { input, args, verbose = false, useEnvelope, useV22 } = runOptions;
-    const shouldUseEnvelope = useEnvelope ?? (module.output?.envelope === true || module.format === 'v2');
-    const isV22Module = module.tier !== undefined || module.formatVersion === 'v2.2';
-    const shouldUseV22 = useV22 ?? (isV22Module || module.compat?.runtime_auto_wrap === true);
-    const riskRule = module.metaConfig?.risk_rule ?? 'max_changes_risk';
-    const inputData = input || {};
-    if (args && !inputData.code && !inputData.query) {
-        if (looksLikeCode(args)) {
-            inputData.code = args;
-        }
-        else {
-            inputData.query = args;
+            systemParts.push('', 'RESPONSE FORMAT (Envelope):');
+            systemParts.push('- Wrap your response in the envelope format');
+            systemParts.push('- Success: { "ok": true, "data": { ...your output... } }');
+            systemParts.push('- Error: { "ok": false, "error": { "code": "ERROR_CODE", "message": "..." } }');
+            systemParts.push('- Include "confidence" (0-1) and "rationale" in data');
+        }
+        if (module.output?.require_behavior_equivalence) {
+            systemParts.push('- Include "behavior_equivalence" (boolean) in data');
+        }
+    }
+    else {
+        systemParts.push('', 'OUTPUT FORMAT:');
+        systemParts.push('- Respond with ONLY valid JSON');
+        systemParts.push('- Include "confidence" (0-1) and "rationale" fields');
+        if (module.output?.require_behavior_equivalence) {
+            systemParts.push('- Include "behavior_equivalence" (boolean) field');
         }
     }
-    // Extract media from input
-    const mediaInputs = extractMediaInputs(inputData);
-    // Build prompt with media placeholders
-    const prompt = buildPromptWithMedia(module, inputData, mediaInputs);
-    // Build system message
-    const systemParts = buildSystemMessage(module, shouldUseEnvelope, shouldUseV22);
     const messages = [
         { role: 'system', content: systemParts.join('\n') },
         { role: 'user', content: prompt },
     ];
     try {
-        // Start streaming invocation
-        const streamResult = await provider.invokeStream({
+        // Invoke provider
+        const result = await provider.invoke({
             messages,
             jsonSchema: module.outputSchema,
             temperature: 0.3,
-            stream: true,
-            images: mediaInputs.images,
-            audio: mediaInputs.audio,
-            video: mediaInputs.video
         });
-        let accumulatedContent = '';
-        let lastProgressTime = Date.now();
-        // Process stream
-        for await (const chunk of streamResult.stream) {
-            // Check timeout
-            if (Date.now() - startTime > maxDuration) {
-                const errorChunk = createErrorChunk(session, ErrorCodesV25.STREAM_TIMEOUT, `Stream exceeded max duration of ${maxDuration}ms`, false, { partial_content: accumulatedContent });
-                yield errorChunk;
-                onChunk?.(errorChunk);
-                return undefined;
-            }
-            // Accumulate content
-            accumulatedContent += chunk;
-            // Emit delta chunk
-            const deltaChunk = createDeltaChunk(session, 'data.rationale', chunk);
-            yield deltaChunk;
-            onChunk?.(deltaChunk);
-            // Emit progress periodically
-            const now = Date.now();
-            if (now - lastProgressTime > 1000) {
-                const elapsed = now - startTime;
-                const estimatedPercent = Math.min(90, Math.floor(elapsed / maxDuration * 100));
-                const progressChunk = createProgressChunk(session, estimatedPercent, 'generating', 'Generating response...');
-                yield progressChunk;
-                onProgress?.(estimatedPercent, 'Generating response...');
-                lastProgressTime = now;
-            }
+        if (verbose) {
+            console.error('--- Response ---');
+            console.error(result.content);
+            console.error('--- End Response ---');
         }
-        // Parse accumulated response
+        // Calculate latency
+        const latencyMs = Date.now() - startTime;
+        // Parse response
         let parsed;
         try {
-            const jsonMatch = accumulatedContent.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
-            const jsonStr = jsonMatch ? jsonMatch[1] : accumulatedContent;
+            const jsonMatch = result.content.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+            const jsonStr = jsonMatch ? jsonMatch[1] : result.content;
             parsed = JSON.parse(jsonStr.trim());
         }
-        catch {
-            // Try to extract partial JSON
-            const errorChunk = createErrorChunk(session, 'E3001', `Failed to parse JSON response`, false, { raw: accumulatedContent });
-            yield errorChunk;
-            onChunk?.(errorChunk);
-            return undefined;
-        }
-        // Process parsed response
-        let result;
-        if (shouldUseEnvelope && typeof parsed === 'object' && parsed !== null && 'ok' in parsed) {
-            const response = parseEnvelopeResponseLocal(parsed, accumulatedContent);
-            if (shouldUseV22 && response.ok && !('meta' in response && response.meta)) {
-                const upgraded = wrapV21ToV22Local(parsed, riskRule);
-                result = {
-                    ok: true,
-                    meta: upgraded.meta,
-                    data: upgraded.data,
-                    raw: accumulatedContent
-                };
+        catch (e) {
+            const errorResult = makeErrorResponse({
+                code: 'PARSE_ERROR',
+                message: `Failed to parse JSON response: ${e.message}`,
+                explain: 'Failed to parse LLM response as JSON.',
+                details: { raw_response: result.content.substring(0, 500) },
+            });
+            _invokeErrorHooks(module.name, e, null);
+            return errorResult;
+        }
+        // Convert to v2.2 envelope
+        let response;
+        if (isV22Envelope(parsed)) {
+            response = parsed;
+        }
+        else if (isEnvelopeResponse(parsed)) {
+            response = wrapV21ToV22(parsed, riskRule);
+        }
+        else {
+            response = convertLegacyToEnvelope(parsed);
+        }
+        // Add version and meta fields
+        response.version = ENVELOPE_VERSION;
+        if (response.meta) {
+            response.meta.latency_ms = latencyMs;
+            if (traceId) {
+                response.meta.trace_id = traceId;
+            }
+            if (modelOverride) {
+                response.meta.model = modelOverride;
+            }
+        }
+        // Validate and potentially repair output
+        if (response.ok && validateOutput) {
+            // Get data schema (support both "data" and "output" aliases)
+            const dataSchema = module.dataSchema || module.outputSchema;
+            const metaSchema = module.metaSchema;
+            const dataToValidate = response.data ?? {};
+            if (dataSchema && Object.keys(dataSchema).length > 0) {
+                let dataErrors = validateData(dataToValidate, dataSchema, 'Data');
+                if (dataErrors.length > 0 && enableRepair) {
+                    // Attempt repair pass
+                    response = repairEnvelope(response, riskRule);
+                    response.version = ENVELOPE_VERSION;
+                    // Re-validate after repair
+                    const repairedData = response.data ?? {};
+                    dataErrors = validateData(repairedData, dataSchema, 'Data');
+                }
+                if (dataErrors.length > 0) {
+                    const errorResult = makeErrorResponse({
+                        code: 'SCHEMA_VALIDATION_FAILED',
+                        message: dataErrors.join('; '),
+                        explain: 'Schema validation failed after repair attempt.',
+                        partialData: response.data,
+                        details: { validation_errors: dataErrors },
+                    });
+                    _invokeErrorHooks(module.name, new Error(dataErrors.join('; ')), response.data);
+                    return errorResult;
+                }
+            }
+            // v2.2: Validate overflow limits
+            const overflowErrors = validateOverflowLimits(dataToValidate, module);
+            if (overflowErrors.length > 0) {
+                const errorResult = makeErrorResponse({
+                    code: 'SCHEMA_VALIDATION_FAILED',
+                    message: overflowErrors.join('; '),
+                    explain: 'Overflow validation failed.',
+                    partialData: dataToValidate,
+                    details: { overflow_errors: overflowErrors },
+                });
+                _invokeErrorHooks(module.name, new Error(overflowErrors.join('; ')), dataToValidate);
+                return errorResult;
+            }
+            // v2.2: Validate enum strategy
+            const enumErrors = validateEnumStrategy(dataToValidate, module);
+            if (enumErrors.length > 0) {
+                const errorResult = makeErrorResponse({
+                    code: 'SCHEMA_VALIDATION_FAILED',
+                    message: enumErrors.join('; '),
+                    explain: 'Enum strategy validation failed.',
+                    partialData: dataToValidate,
+                    details: { enum_errors: enumErrors },
+                });
+                _invokeErrorHooks(module.name, new Error(enumErrors.join('; ')), dataToValidate);
+                return errorResult;
+            }
+            // Validate meta if schema exists
+            if (metaSchema && Object.keys(metaSchema).length > 0) {
+                let metaErrors = validateData(response.meta ?? {}, metaSchema, 'Meta');
+                if (metaErrors.length > 0 && enableRepair) {
+                    response = repairEnvelope(response, riskRule);
+                    response.version = ENVELOPE_VERSION;
+                    // Re-validate meta after repair
+                    metaErrors = validateData(response.meta ?? {}, metaSchema, 'Meta');
+                    if (metaErrors.length > 0) {
+                        const errorResult = makeErrorResponse({
+                            code: 'META_VALIDATION_FAILED',
+                            message: metaErrors.join('; '),
+                            explain: 'Meta schema validation failed after repair attempt.',
+                            partialData: response.data,
+                            details: { validation_errors: metaErrors },
+                        });
+                        _invokeErrorHooks(module.name, new Error(metaErrors.join('; ')), response.data);
+                        return errorResult;
+                    }
+                }
+            }
+        }
+        else if (enableRepair) {
+            // Repair error envelopes to ensure they have proper meta fields
+            response = repairErrorEnvelope(response);
+            response.version = ENVELOPE_VERSION;
+        }
+        // Invoke after hooks
+        const finalLatencyMs = Date.now() - startTime;
+        _invokeAfterHooks(module.name, response, finalLatencyMs);
+        return response;
+    }
+    catch (e) {
+        const latencyMs = Date.now() - startTime;
+        const errorResult = makeErrorResponse({
+            code: 'UNKNOWN',
+            message: e.message,
+            explain: `Unexpected error: ${e.name}`,
+            details: { exception_type: e.name },
+        });
+        if (errorResult.meta) {
+            errorResult.meta.latency_ms = latencyMs;
+        }
+        _invokeErrorHooks(module.name, e, null);
+        return errorResult;
+    }
+}
+/**
+ * Run a cognitive module with streaming output.
+ *
+ * Yields StreamEvent objects as the module executes:
+ * - type="start": Module execution started
+ * - type="chunk": Incremental data chunk (if LLM supports streaming)
+ * - type="meta": Meta information available early
+ * - type="complete": Final complete result
+ * - type="error": Error occurred
+ *
+ * @example
+ * for await (const event of runModuleStream(module, provider, options)) {
+ *   if (event.type === 'chunk') {
+ *     process.stdout.write(event.chunk);
+ *   } else if (event.type === 'complete') {
+ *     console.log('Result:', event.result);
+ *   }
+ * }
+ */
+export async function* runModuleStream(module, provider, options = {}) {
+    const { input, args, validateInput = true, validateOutput = true, useV22 = true, enableRepair = true, traceId, model } = options;
+    const startTime = Date.now();
+    const moduleName = module.name;
+    function makeEvent(type, extra = {}) {
+        return {
+            type,
+            timestamp_ms: Date.now() - startTime,
+            module_name: moduleName,
+            ...extra,
+        };
+    }
+    try {
+        // Emit start event
+        yield makeEvent('start');
+        // Build input data
+        const inputData = input || {};
+        if (args && !inputData.code && !inputData.query) {
+            if (looksLikeCode(args)) {
+                inputData.code = args;
             }
             else {
-                result = response;
+                inputData.query = args;
+            }
+        }
+        // Validate input if enabled
+        if (validateInput && module.inputSchema && Object.keys(module.inputSchema).length > 0) {
+            const inputErrors = validateData(inputData, module.inputSchema, 'Input');
+            if (inputErrors.length > 0) {
+                const errorResult = makeErrorResponse({
+                    code: 'INVALID_INPUT',
+                    message: inputErrors.join('; '),
+                    confidence: 1.0,
+                    risk: 'none',
+                });
+                const errorObj = errorResult.error;
+                yield makeEvent('error', { error: errorObj });
+                yield makeEvent('complete', { result: errorResult });
+                return;
             }
         }
+        // Get risk_rule from module config
+        const riskRule = module.metaConfig?.risk_rule ?? 'max_changes_risk';
+        // Build prompt
+        const prompt = buildPrompt(module, inputData);
+        // Build messages
+        const systemParts = [
+            `You are executing the "${module.name}" Cognitive Module.`,
+            '',
+            `RESPONSIBILITY: ${module.responsibility}`,
+        ];
+        if (useV22) {
+            systemParts.push('', 'RESPONSE FORMAT (Envelope v2.2):');
+            systemParts.push('- Wrap your response in the v2.2 envelope format');
+            systemParts.push('- Success: { "ok": true, "meta": { "confidence": 0.9, "risk": "low", "explain": "short summary" }, "data": { ...payload... } }');
+            systemParts.push('- Return ONLY valid JSON.');
+        }
+        const messages = [
+            { role: 'system', content: systemParts.join('\n') },
+            { role: 'user', content: prompt },
+        ];
+        // Invoke provider (streaming not yet supported in provider interface, so we fallback)
+        const result = await provider.invoke({
+            messages,
+            jsonSchema: module.outputSchema,
+            temperature: 0.3,
+        });
+        // Emit chunk event with full response
+        yield makeEvent('chunk', { chunk: result.content });
+        // Parse response
+        let parsed;
+        try {
+            const jsonMatch = result.content.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
+            const jsonStr = jsonMatch ? jsonMatch[1] : result.content;
+            parsed = JSON.parse(jsonStr.trim());
+        }
+        catch (e) {
+            const errorResult = makeErrorResponse({
+                code: 'PARSE_ERROR',
+                message: `Failed to parse JSON: ${e.message}`,
+            });
+            // errorResult is always an error response from makeErrorResponse
+            const errorObj = errorResult.error;
+            yield makeEvent('error', { error: errorObj });
+            yield makeEvent('complete', { result: errorResult });
+            return;
+        }
+        // Convert to v2.2 envelope
+        let response;
+        if (isV22Envelope(parsed)) {
+            response = parsed;
+        }
+        else if (isEnvelopeResponse(parsed)) {
+            response = wrapV21ToV22(parsed, riskRule);
+        }
         else {
-            result = parseLegacyResponseLocal(parsed, accumulatedContent);
-            if (shouldUseV22 && result.ok) {
-                const data = (result.data ?? {});
-                result = {
-                    ok: true,
-                    meta: {
-                        confidence: data.confidence ?? 0.5,
-                        risk: aggregateRisk(data, riskRule),
-                        explain: (data.rationale ?? '').slice(0, 280) || 'No explanation provided'
-                    },
-                    data: result.data,
-                    raw: accumulatedContent
-                };
+            response = convertLegacyToEnvelope(parsed);
+        }
+        // Add version and meta
+        response.version = ENVELOPE_VERSION;
+        const latencyMs = Date.now() - startTime;
+        if (response.meta) {
+            response.meta.latency_ms = latencyMs;
+            if (traceId) {
+                response.meta.trace_id = traceId;
+            }
+            if (model) {
+                response.meta.model = model;
             }
+            // Emit meta event early
+            yield makeEvent('meta', { meta: response.meta });
         }
-        // Emit final chunk
-        if (result.ok && 'meta' in result) {
-            const finalChunk = createFinalChunk(session, result.meta, result.data, streamResult.usage ? {
-                input_tokens: streamResult.usage.promptTokens,
-                output_tokens: streamResult.usage.completionTokens,
-                total_tokens: streamResult.usage.totalTokens
-            } : undefined);
-            yield finalChunk;
-            onChunk?.(finalChunk);
-            onProgress?.(100, 'Complete');
+        // Validate and repair output
+        if (response.ok && validateOutput) {
+            const dataSchema = module.dataSchema || module.outputSchema;
+            const metaSchema = module.metaSchema;
+            if (dataSchema && Object.keys(dataSchema).length > 0) {
+                const dataToValidate = response.data ?? {};
+                let dataErrors = validateData(dataToValidate, dataSchema, 'Data');
+                if (dataErrors.length > 0 && enableRepair) {
+                    response = repairEnvelope(response, riskRule);
+                    response.version = ENVELOPE_VERSION;
+                    // Re-validate after repair
+                    const repairedData = response.data ?? {};
+                    dataErrors = validateData(repairedData, dataSchema, 'Data');
+                }
+                if (dataErrors.length > 0) {
+                    const errorResult = makeErrorResponse({
+                        code: 'SCHEMA_VALIDATION_FAILED',
+                        message: dataErrors.join('; '),
+                        explain: 'Schema validation failed after repair attempt.',
+                        partialData: response.data,
+                        details: { validation_errors: dataErrors },
+                    });
+                    const errorObj = errorResult.error;
+                    yield makeEvent('error', { error: errorObj });
+                    yield makeEvent('complete', { result: errorResult });
+                    return;
+                }
+            }
+            // Validate meta if schema exists
+            if (metaSchema && Object.keys(metaSchema).length > 0) {
+                let metaErrors = validateData(response.meta ?? {}, metaSchema, 'Meta');
+                if (metaErrors.length > 0 && enableRepair) {
+                    response = repairEnvelope(response, riskRule);
+                    response.version = ENVELOPE_VERSION;
+                    metaErrors = validateData(response.meta ?? {}, metaSchema, 'Meta');
+                    if (metaErrors.length > 0) {
+                        const errorResult = makeErrorResponse({
+                            code: 'META_VALIDATION_FAILED',
+                            message: metaErrors.join('; '),
+                            explain: 'Meta validation failed after repair attempt.',
+                            partialData: response.data,
+                            details: { validation_errors: metaErrors },
+                        });
+                        const errorObj = errorResult.error;
+                        yield makeEvent('error', { error: errorObj });
+                        yield makeEvent('complete', { result: errorResult });
+                        return;
+                    }
+                }
+            }
         }
-        return result;
+        else if (!response.ok && enableRepair) {
+            response = repairErrorEnvelope(response);
+            response.version = ENVELOPE_VERSION;
+        }
+        // Emit complete event
+        yield makeEvent('complete', { result: response });
     }
-    catch (error) {
-        const errorChunk = createErrorChunk(session, ErrorCodesV25.STREAM_INTERRUPTED, error instanceof Error ? error.message : 'Stream interrupted', true);
-        yield errorChunk;
-        onChunk?.(errorChunk);
-        return undefined;
+    catch (e) {
+        const errorResult = makeErrorResponse({
+            code: 'UNKNOWN',
+            message: e.message,
+            explain: `Unexpected error: ${e.name}`,
+        });
+        // errorResult is always an error response from makeErrorResponse
+        const errorObj = errorResult.error;
+        yield makeEvent('error', { error: errorObj });
+        yield makeEvent('complete', { result: errorResult });
     }
 }
-// Local versions of helper functions to avoid circular issues
-function parseEnvelopeResponseLocal(response, raw) {
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Check if response is in envelope format
+ */
+function isEnvelopeResponse(obj) {
+    if (typeof obj !== 'object' || obj === null)
+        return false;
+    const o = obj;
+    return typeof o.ok === 'boolean';
+}
+/**
+ * Parse envelope format response (supports both v2.1 and v2.2)
+ */
+function parseEnvelopeResponse(response, raw) {
+    // Check if v2.2 format (has meta)
     if (isV22Envelope(response)) {
         if (response.ok) {
             return {
@@ -687,6 +1386,7 @@ function parseEnvelopeResponseLocal(response, raw) {
             };
         }
     }
+    // v2.1 format
     if (response.ok) {
         const data = (response.data ?? {});
         return {
@@ -709,45 +1409,17 @@ function parseEnvelopeResponseLocal(response, raw) {
         };
     }
 }
-function wrapV21ToV22Local(response, riskRule = 'max_changes_risk') {
-    if (isV22Envelope(response)) {
-        return response;
-    }
-    if (response.ok) {
-        const data = (response.data ?? {});
-        const confidence = data.confidence ?? 0.5;
-        const rationale = data.rationale ?? '';
-        return {
-            ok: true,
-            meta: {
-                confidence,
-                risk: aggregateRisk(data, riskRule),
-                explain: rationale.slice(0, 280) || 'No explanation provided'
-            },
-            data: data
-        };
-    }
-    else {
-        const errorMsg = response.error?.message ?? 'Unknown error';
-        return {
-            ok: false,
-            meta: {
-                confidence: 0,
-                risk: 'high',
-                explain: errorMsg.slice(0, 280)
-            },
-            error: response.error ?? { code: 'UNKNOWN', message: errorMsg },
-            partial_data: response.partial_data
-        };
-    }
-}
-function parseLegacyResponseLocal(output, raw) {
+/**
+ * Parse legacy (non-envelope) format response
+ */
+function parseLegacyResponse(output, raw) {
     const outputObj = output;
     const confidence = typeof outputObj.confidence === 'number' ? outputObj.confidence : 0.5;
     const rationale = typeof outputObj.rationale === 'string' ? outputObj.rationale : '';
     const behaviorEquivalence = typeof outputObj.behavior_equivalence === 'boolean'
         ? outputObj.behavior_equivalence
         : undefined;
+    // Check if this is an error response (has error.code)
     if (outputObj.error && typeof outputObj.error === 'object') {
         const errorObj = outputObj.error;
         if (typeof errorObj.code === 'string') {
@@ -761,6 +1433,7 @@ function parseLegacyResponseLocal(output, raw) {
             };
         }
     }
+    // Return as v2.1 format (data includes confidence)
     return {
         ok: true,
         data: {
@@ -773,237 +1446,119 @@ function parseLegacyResponseLocal(output, raw) {
     };
 }
 /**
- * Extract media inputs from module input data
+ * Build prompt with clean variable substitution
+ *
+ * Substitution order (important to avoid partial replacements):
+ * 1. ${variable} - v2 style placeholders
+ * 2. $ARGUMENTS[N] - indexed access (descending order to avoid $1 matching $10)
+ * 3. $N - shorthand indexed access (descending order)
+ * 4. $ARGUMENTS - full argument string (LAST to avoid partial matches)
  */
-function extractMediaInputs(input) {
-    const images = [];
-    const audio = [];
-    const video = [];
-    // Check for images array
-    if (Array.isArray(input.images)) {
-        for (const img of input.images) {
-            if (isValidMediaInput(img)) {
-                images.push(img);
-            }
-        }
+function buildPrompt(module, input) {
+    let prompt = module.prompt;
+    // v2 style: substitute ${variable} placeholders
+    for (const [key, value] of Object.entries(input)) {
+        const strValue = typeof value === 'string' ? value : JSON.stringify(value);
+        prompt = prompt.replace(new RegExp(`\\$\\{${key}\\}`, 'g'), strValue);
     }
-    // Check for audio array
-    if (Array.isArray(input.audio)) {
-        for (const aud of input.audio) {
-            if (isValidMediaInput(aud)) {
-                audio.push(aud);
-            }
+    // v1 compatibility: get args value
+    const argsValue = input.code || input.query || '';
+    // Substitute $ARGUMENTS[N] and $N placeholders FIRST (v1 compatibility)
+    // Process in descending order to avoid $1 replacing part of $10
+    if (typeof argsValue === 'string') {
+        const argsList = argsValue.split(/\s+/);
+        for (let i = argsList.length - 1; i >= 0; i--) {
+            const arg = argsList[i];
+            // Replace $ARGUMENTS[N] first
+            prompt = prompt.replace(new RegExp(`\\$ARGUMENTS\\[${i}\\]`, 'g'), arg);
+            // Replace $N shorthand
+            prompt = prompt.replace(new RegExp(`\\$${i}\\b`, 'g'), arg);
         }
     }
-    // Check for video array
-    if (Array.isArray(input.video)) {
-        for (const vid of input.video) {
-            if (isValidMediaInput(vid)) {
-                video.push(vid);
-            }
+    // Replace $ARGUMENTS LAST (after indexed forms to avoid partial matches)
+    prompt = prompt.replace(/\$ARGUMENTS/g, argsValue);
+    // Append input summary if not already in prompt
+    if (!prompt.includes(argsValue) && argsValue) {
+        prompt += '\n\n## Input\n\n';
+        if (input.code) {
+            prompt += '```\n' + input.code + '\n```\n';
+        }
+        if (input.query) {
+            prompt += input.query + '\n';
+        }
+        if (input.language) {
+            prompt += `\nLanguage: ${input.language}\n`;
         }
-    }
-    return { images, audio, video };
-}
-/**
- * Validate media input structure
- */
-function isValidMediaInput(input) {
-    if (typeof input !== 'object' || input === null)
-        return false;
-    const obj = input;
-    if (obj.type === 'url' && typeof obj.url === 'string')
-        return true;
-    if (obj.type === 'base64' && typeof obj.data === 'string' && typeof obj.media_type === 'string')
-        return true;
-    if (obj.type === 'file' && typeof obj.path === 'string')
-        return true;
-    return false;
-}
-/**
- * Build prompt with media placeholders
- */
-function buildPromptWithMedia(module, input, media) {
-    let prompt = buildPrompt(module, input);
-    // Replace $MEDIA_INPUTS placeholder
-    if (prompt.includes('$MEDIA_INPUTS')) {
-        const mediaSummary = buildMediaSummary(media);
-        prompt = prompt.replace(/\$MEDIA_INPUTS/g, mediaSummary);
     }
     return prompt;
 }
 /**
- * Build summary of media inputs for prompt
+ * Heuristic to detect if input looks like code
  */
-function buildMediaSummary(media) {
-    const parts = [];
-    if (media.images.length > 0) {
-        parts.push(`[${media.images.length} image(s) attached]`);
-    }
-    if (media.audio.length > 0) {
-        parts.push(`[${media.audio.length} audio file(s) attached]`);
-    }
-    if (media.video.length > 0) {
-        parts.push(`[${media.video.length} video file(s) attached]`);
-    }
-    return parts.length > 0 ? parts.join('\n') : '[No media attached]';
+function looksLikeCode(str) {
+    const codeIndicators = [
+        /^(def|function|class|const|let|var|import|export|public|private)\s/,
+        /[{};()]/,
+        /=>/,
+        /\.(py|js|ts|go|rs|java|cpp|c|rb)$/,
+    ];
+    return codeIndicators.some(re => re.test(str));
 }
 /**
- * Build system message for module execution
+ * Run a cognitive module (legacy API, returns raw output).
+ * For backward compatibility. Throws on error instead of returning error envelope.
  */
-function buildSystemMessage(module, shouldUseEnvelope, shouldUseV22) {
-    const systemParts = [
-        `You are executing the "${module.name}" Cognitive Module.`,
-        '',
-        `RESPONSIBILITY: ${module.responsibility}`,
-    ];
-    if (module.excludes.length > 0) {
-        systemParts.push('', 'YOU MUST NOT:');
-        module.excludes.forEach(e => systemParts.push(`- ${e}`));
-    }
-    if (module.constraints) {
-        systemParts.push('', 'CONSTRAINTS:');
-        if (module.constraints.no_network)
-            systemParts.push('- No network access');
-        if (module.constraints.no_side_effects)
-            systemParts.push('- No side effects');
-        if (module.constraints.no_file_write)
-            systemParts.push('- No file writes');
-        if (module.constraints.no_inventing_data)
-            systemParts.push('- Do not invent data');
-    }
-    if (module.output?.require_behavior_equivalence) {
-        systemParts.push('', 'BEHAVIOR EQUIVALENCE:');
-        systemParts.push('- You MUST set behavior_equivalence=true ONLY if the output is functionally identical');
-        systemParts.push('- If unsure, set behavior_equivalence=false and explain in rationale');
-        const maxConfidence = module.constraints?.behavior_equivalence_false_max_confidence ?? 0.7;
-        systemParts.push(`- If behavior_equivalence=false, confidence MUST be <= ${maxConfidence}`);
-    }
-    // Add multimodal instructions if module supports it
-    if (isModuleV25(module) && moduleSupportsMultimodal(module)) {
-        const inputModalities = getModuleInputModalities(module);
-        systemParts.push('', 'MULTIMODAL INPUT:');
-        systemParts.push(`- This module accepts: ${inputModalities.join(', ')}`);
-        systemParts.push('- Analyze any attached media carefully');
-        systemParts.push('- Reference specific elements from the media in your analysis');
-    }
-    // Add envelope format instructions
-    if (shouldUseEnvelope) {
-        if (shouldUseV22) {
-            systemParts.push('', 'RESPONSE FORMAT (Envelope v2.2):');
-            systemParts.push('- Wrap your response in the v2.2 envelope format with separate meta and data');
-            systemParts.push('- Success: { "ok": true, "meta": { "confidence": 0.9, "risk": "low", "explain": "short summary" }, "data": { ...payload... } }');
-            systemParts.push('- Error: { "ok": false, "meta": { "confidence": 0.0, "risk": "high", "explain": "error summary" }, "error": { "code": "ERROR_CODE", "message": "..." } }');
-            systemParts.push('- meta.explain must be ≤280 characters. data.rationale can be longer for detailed reasoning.');
-            systemParts.push('- meta.risk must be one of: "none", "low", "medium", "high"');
-        }
-        else {
-            systemParts.push('', 'RESPONSE FORMAT (Envelope):');
-            systemParts.push('- Wrap your response in the envelope format');
-            systemParts.push('- Success: { "ok": true, "data": { ...your output... } }');
-            systemParts.push('- Error: { "ok": false, "error": { "code": "ERROR_CODE", "message": "..." } }');
-            systemParts.push('- Include "confidence" (0-1) and "rationale" in data');
-        }
-        if (module.output?.require_behavior_equivalence) {
-            systemParts.push('- Include "behavior_equivalence" (boolean) in data');
-        }
+export async function runModuleLegacy(module, provider, input, options = {}) {
+    const { validateInput = true, validateOutput = true, model } = options;
+    const result = await runModule(module, provider, {
+        input,
+        validateInput,
+        validateOutput,
+        useEnvelope: false,
+        useV22: false,
+        model,
+    });
+    if (result.ok && 'data' in result) {
+        return result.data;
     }
     else {
-        systemParts.push('', 'OUTPUT FORMAT:');
-        systemParts.push('- Respond with ONLY valid JSON');
-        systemParts.push('- Include "confidence" (0-1) and "rationale" fields');
-        if (module.output?.require_behavior_equivalence) {
-            systemParts.push('- Include "behavior_equivalence" (boolean) field');
-        }
+        const error = 'error' in result ? result.error : { code: 'UNKNOWN', message: 'Unknown error' };
+        throw new Error(`${error?.code ?? 'UNKNOWN'}: ${error?.message ?? 'Unknown error'}`);
     }
-    return systemParts;
 }
+// =============================================================================
+// Convenience Functions
+// =============================================================================
 /**
- * Load media file as base64
+ * Extract meta from v2.2 envelope for routing/logging.
  */
-export async function loadMediaAsBase64(path) {
-    try {
-        if (!existsSync(path)) {
-            return null;
-        }
-        const buffer = await readFile(path);
-        const data = buffer.toString('base64');
-        const media_type = getMediaTypeFromExtension(extname(path));
-        return { data, media_type };
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Get MIME type from file extension
- */
-function getMediaTypeFromExtension(ext) {
-    const mimeTypes = {
-        '.jpg': 'image/jpeg',
-        '.jpeg': 'image/jpeg',
-        '.png': 'image/png',
-        '.gif': 'image/gif',
-        '.webp': 'image/webp',
-        '.mp3': 'audio/mpeg',
-        '.wav': 'audio/wav',
-        '.ogg': 'audio/ogg',
-        '.webm': 'audio/webm',
-        '.mp4': 'video/mp4',
-        '.mov': 'video/quicktime',
-        '.pdf': 'application/pdf'
+export function extractMeta(result) {
+    return result.meta ?? {
+        confidence: 0.5,
+        risk: 'medium',
+        explain: 'No meta available',
     };
-    return mimeTypes[ext.toLowerCase()] ?? 'application/octet-stream';
 }
+// Alias for backward compatibility
+export const extractMetaV22 = extractMeta;
 /**
- * Validate media input against module constraints
+ * Determine if result should be escalated to human review based on meta.
  */
-export function validateMediaInput(media, module, maxSizeMb = 20) {
-    // Check if module supports multimodal
-    if (!moduleSupportsMultimodal(module)) {
-        return {
-            valid: false,
-            error: 'Module does not support multimodal input',
-            code: ErrorCodesV25.MULTIMODAL_NOT_SUPPORTED
-        };
+export function shouldEscalate(result, confidenceThreshold = 0.7) {
+    const meta = extractMeta(result);
+    // Escalate if low confidence
+    if (meta.confidence < confidenceThreshold) {
+        return true;
     }
-    // Validate media type
-    if (media.type === 'base64') {
-        const mediaType = media.media_type;
-        if (!isValidMediaType(mediaType)) {
-            return {
-                valid: false,
-                error: `Unsupported media type: ${mediaType}`,
-                code: ErrorCodesV25.UNSUPPORTED_MEDIA_TYPE
-            };
-        }
+    // Escalate if high risk
+    if (meta.risk === 'high') {
+        return true;
     }
-    // Size validation would require fetching/checking actual data
-    // This is a placeholder for the check
-    return { valid: true };
-}
-/**
- * Check if media type is supported
- */
-function isValidMediaType(mediaType) {
-    const supported = [
-        'image/jpeg', 'image/png', 'image/webp', 'image/gif',
-        'audio/mpeg', 'audio/wav', 'audio/ogg', 'audio/webm',
-        'video/mp4', 'video/webm', 'video/quicktime',
-        'application/pdf'
-    ];
-    return supported.includes(mediaType);
-}
-/**
- * Get runtime capabilities
- */
-export function getRuntimeCapabilities() {
-    return { ...DEFAULT_RUNTIME_CAPABILITIES };
-}
-/**
- * Check if runtime supports a specific modality
- */
-export function runtimeSupportsModality(modality, direction = 'input') {
-    const caps = getRuntimeCapabilities();
-    return caps.multimodal[direction].includes(modality);
+    // Escalate if error
+    if (!result.ok) {
+        return true;
+    }
+    return false;
 }
+// Alias for backward compatibility
+export const shouldEscalateV22 = shouldEscalate;