cognitive-modules-cli 2.2.0 → 2.2.1

package/dist/modules/runner.js

@@ -1,24 +1,712 @@
 /**
  * Module Runner - Execute Cognitive Modules
  * v2.2: Envelope format with meta/data separation, risk_rule, repair pass
+ * v2.2.1: Version field, enhanced error taxonomy, observability hooks, streaming
  */
+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 = {};
@@ -54,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,
@@ -62,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) {
@@ -85,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),
@@ -97,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',
@@ -107,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
@@ -128,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) {
@@ -202,70 +995,364 @@ export async function runModule(module, provider, options = {}) {
         { 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
-            };
+        // 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 ---');
         }
-        // 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
-            };
+        // Calculate latency
+        const latencyMs = Date.now() - startTime;
+        // 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 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;
     }
-    // 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 ?? {});
+    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 {
-            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
+            type,
+            timestamp_ms: Date.now() - startTime,
+            module_name: moduleName,
+            ...extra,
         };
     }
-    return legacyResult;
+    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 {
+                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 {
+            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 });
+        }
+        // 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;
+                    }
+                }
+            }
+        }
+        else if (!response.ok && enableRepair) {
+            response = repairErrorEnvelope(response);
+            response.version = ENVELOPE_VERSION;
+        }
+        // Emit complete event
+        yield makeEvent('complete', { result: response });
+    }
+    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 });
+    }
 }
+// =============================================================================
+// Helper Functions
+// =============================================================================
 /**
  * Check if response is in envelope format
  */
@@ -360,6 +1447,12 @@ function parseLegacyResponse(output, raw) {
 }
 /**
  * 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 buildPrompt(module, input) {
     let prompt = module.prompt;
@@ -368,16 +1461,22 @@ function buildPrompt(module, input) {
         const strValue = typeof value === 'string' ? value : JSON.stringify(value);
         prompt = prompt.replace(new RegExp(`\\$\\{${key}\\}`, 'g'), strValue);
     }
-    // v1 compatibility: substitute $ARGUMENTS
+    // v1 compatibility: get args value
     const argsValue = input.code || input.query || '';
-    prompt = prompt.replace(/\$ARGUMENTS/g, argsValue);
-    // Substitute $N placeholders (v1 compatibility)
+    // 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+/);
-        argsList.forEach((arg, i) => {
+        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);
-        });
+        }
     }
+    // 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';
@@ -405,3 +1504,61 @@ function looksLikeCode(str) {
     ];
     return codeIndicators.some(re => re.test(str));
 }
+/**
+ * Run a cognitive module (legacy API, returns raw output).
+ * For backward compatibility. Throws on error instead of returning error envelope.
+ */
+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 {
+        const error = 'error' in result ? result.error : { code: 'UNKNOWN', message: 'Unknown error' };
+        throw new Error(`${error?.code ?? 'UNKNOWN'}: ${error?.message ?? 'Unknown error'}`);
+    }
+}
+// =============================================================================
+// Convenience Functions
+// =============================================================================
+/**
+ * Extract meta from v2.2 envelope for routing/logging.
+ */
+export function extractMeta(result) {
+    return result.meta ?? {
+        confidence: 0.5,
+        risk: 'medium',
+        explain: 'No meta available',
+    };
+}
+// Alias for backward compatibility
+export const extractMetaV22 = extractMeta;
+/**
+ * Determine if result should be escalated to human review based on meta.
+ */
+export function shouldEscalate(result, confidenceThreshold = 0.7) {
+    const meta = extractMeta(result);
+    // Escalate if low confidence
+    if (meta.confidence < confidenceThreshold) {
+        return true;
+    }
+    // Escalate if high risk
+    if (meta.risk === 'high') {
+        return true;
+    }
+    // Escalate if error
+    if (!result.ok) {
+        return true;
+    }
+    return false;
+}
+// Alias for backward compatibility
+export const shouldEscalateV22 = shouldEscalate;