cognitive-runtime 0.4.0 → 0.5.0

package/README.md

@@ -65,6 +65,45 @@ echo "review this code" | cog pipe --module code-reviewer
 cog doctor
 ```
 
+## Module Formats
+
+### v2 (Recommended)
+
+```
+my-module/
+├── module.yaml      # Machine-readable manifest
+├── prompt.md        # Human-readable prompt
+├── schema.json      # IO contract
+└── tests/
+    ├── case1.input.json
+    └── case1.expected.json
+```
+
+**module.yaml**:
+```yaml
+name: my-module
+version: 2.0.0
+responsibility: What this module does
+constraints:
+  no_network: true
+  no_side_effects: true
+output:
+  mode: json_strict
+  require_confidence: true
+  require_rationale: true
+  require_behavior_equivalence: true
+tools:
+  allowed: []
+```
+
+### v1 (Legacy, still supported)
+
+```
+my-module/
+├── MODULE.md        # Frontmatter + prompt combined
+└── schema.json
+```
+
 ## Providers
 
 | Provider   | Environment Variable   | Default Model        |

package/dist/cli.js

@@ -10,7 +10,7 @@
 import { parseArgs } from 'node:util';
 import { getProvider, listProviders } from './providers/index.js';
 import { run, list, pipe, init } from './commands/index.js';
-const VERSION = '0.4.0';
+const VERSION = '0.5.0';
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];

package/dist/commands/pipe.js

@@ -37,16 +37,20 @@ export async function pipe(ctx, options) {
             args: inputData ? undefined : input,
             input: inputData,
         });
-        // Output JSON to stdout
-        console.log(JSON.stringify(result.output));
+        // Output envelope format to stdout
+        console.log(JSON.stringify(result));
         return {
-            success: true,
+            success: result.ok,
             data: result,
         };
     }
     catch (e) {
         const error = e instanceof Error ? e.message : String(e);
-        console.error(JSON.stringify({ error }));
+        // Output error in envelope format
+        console.log(JSON.stringify({
+            ok: false,
+            error: { code: 'RUNTIME_ERROR', message: error }
+        }));
         return {
             success: false,
             error,

package/dist/commands/run.js

@@ -32,10 +32,29 @@ export async function run(moduleName, ctx, options = {}) {
             input: inputData,
             verbose: options.verbose || ctx.verbose,
         });
-        return {
-            success: true,
-            data: options.pretty ? result : result.output,
-        };
+        // Return envelope format or extracted data
+        if (options.pretty) {
+            return {
+                success: result.ok,
+                data: result,
+            };
+        }
+        else {
+            // For non-pretty mode, return data (success) or error (failure)
+            if (result.ok) {
+                return {
+                    success: true,
+                    data: result.data,
+                };
+            }
+            else {
+                return {
+                    success: false,
+                    error: `${result.error?.code}: ${result.error?.message}`,
+                    data: result.partial_data,
+                };
+            }
+        }
     }
     catch (e) {
         return {

package/dist/modules/loader.js

@@ -57,9 +57,11 @@ async function loadModuleV2(modulePath) {
         responsibility: manifest.responsibility || '',
         excludes: manifest.excludes || [],
         constraints: manifest.constraints,
+        policies: manifest.policies,
         tools: manifest.tools,
         output: manifest.output,
         failure: manifest.failure,
+        runtimeRequirements: manifest.runtime_requirements,
         context: manifest.context,
         prompt,
         inputSchema,

package/dist/modules/runner.d.ts

@@ -1,11 +1,12 @@
 /**
  * Module Runner - Execute Cognitive Modules
- * v2: Clean input mapping, no CLI pollution
+ * v2.1: Envelope format support, clean input mapping
  */
 import type { Provider, CognitiveModule, ModuleResult, ModuleInput } from '../types.js';
 export interface RunOptions {
     input?: ModuleInput;
     args?: string;
     verbose?: boolean;
+    useEnvelope?: boolean;
 }
 export declare function runModule(module: CognitiveModule, provider: Provider, options?: RunOptions): Promise<ModuleResult>;

package/dist/modules/runner.js

@@ -1,9 +1,11 @@
 /**
  * Module Runner - Execute Cognitive Modules
- * v2: Clean input mapping, no CLI pollution
+ * v2.1: Envelope format support, clean input mapping
  */
 export async function runModule(module, provider, options = {}) {
-    const { args, input, verbose = false } = options;
+    const { args, input, verbose = false, useEnvelope } = options;
+    // Determine if we should use envelope format
+    const shouldUseEnvelope = useEnvelope ?? (module.output?.envelope === true || module.format === 'v2');
     // Build clean input data (v2 style: no $ARGUMENTS pollution)
     const inputData = input || {};
     // Map legacy --args to clean input
@@ -22,6 +24,7 @@ export async function runModule(module, provider, options = {}) {
         console.error('--- Module ---');
         console.error(`Name: ${module.name} (${module.format})`);
         console.error(`Responsibility: ${module.responsibility}`);
+        console.error(`Envelope: ${shouldUseEnvelope}`);
         console.error('--- Input ---');
         console.error(JSON.stringify(inputData, null, 2));
         console.error('--- Prompt ---');
@@ -53,12 +56,27 @@ export async function runModule(module, provider, options = {}) {
         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}`);
     }
-    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');
+    // Add envelope format instructions
+    if (shouldUseEnvelope) {
+        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') },
@@ -76,28 +94,90 @@ export async function runModule(module, provider, options = {}) {
         console.error('--- End Response ---');
     }
     // Parse response
-    let output;
+    let parsed;
     try {
         const jsonMatch = result.content.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
         const jsonStr = jsonMatch ? jsonMatch[1] : result.content;
-        output = JSON.parse(jsonStr.trim());
+        parsed = JSON.parse(jsonStr.trim());
     }
     catch {
         throw new Error(`Failed to parse JSON response: ${result.content.substring(0, 500)}`);
     }
-    // Extract standard fields
+    // Handle envelope format
+    if (shouldUseEnvelope && isEnvelopeResponse(parsed)) {
+        return parseEnvelopeResponse(parsed, result.content);
+    }
+    // Handle legacy format (non-envelope)
+    return parseLegacyResponse(parsed, result.content);
+}
+/**
+ * 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
+ */
+function parseEnvelopeResponse(response, raw) {
+    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 {
-        output,
-        confidence,
-        rationale,
-        behaviorEquivalence,
-        raw: result.content,
+        ok: true,
+        data: {
+            ...outputObj,
+            confidence,
+            rationale,
+            behavior_equivalence: behaviorEquivalence,
+        },
+        raw,
     };
 }
 /**

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 /**
  * Cognitive Runtime - Core Types
- * Version 2.0 - With tools policy, failure contract, and behavior equivalence
+ * Version 2.1 - With envelope format, tools policy, failure contract
  */
 export interface Provider {
     name: string;
@@ -31,9 +31,11 @@ export interface CognitiveModule {
     responsibility: string;
     excludes: string[];
     constraints?: ModuleConstraints;
+    policies?: ModulePolicies;
     tools?: ToolsPolicy;
     output?: OutputContract;
     failure?: FailureContract;
+    runtimeRequirements?: RuntimeRequirements;
     context?: 'fork' | 'main';
     prompt: string;
     inputSchema?: object;
@@ -47,20 +49,68 @@ export interface ModuleConstraints {
     no_side_effects?: boolean;
     no_file_write?: boolean;
     no_inventing_data?: boolean;
+    behavior_equivalence_false_max_confidence?: number;
+}
+export interface ModulePolicies {
+    network?: 'allow' | 'deny';
+    filesystem_write?: 'allow' | 'deny';
+    side_effects?: 'allow' | 'deny';
+    code_execution?: 'allow' | 'deny';
 }
 export interface ToolsPolicy {
+    policy?: 'allow_by_default' | 'deny_by_default';
     allowed: string[];
+    denied?: string[];
 }
 export interface OutputContract {
-    mode?: 'json_strict' | 'json_lenient' | 'text';
+    format?: 'json_strict' | 'json_lenient' | 'text';
+    envelope?: boolean;
+    require?: string[];
     require_confidence?: boolean;
     require_rationale?: boolean;
     require_behavior_equivalence?: boolean;
 }
 export interface FailureContract {
+    contract?: 'error_union' | 'throw';
+    partial_allowed?: boolean;
+    must_return_error_schema?: boolean;
     schema?: object;
 }
+export interface RuntimeRequirements {
+    structured_output?: boolean;
+    max_input_tokens?: number;
+    preferred_capabilities?: string[];
+}
+export interface EnvelopeSuccess<T = unknown> {
+    ok: true;
+    data: T;
+}
+export interface EnvelopeError {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+    partial_data?: unknown;
+}
+export type EnvelopeResponse<T = unknown> = EnvelopeSuccess<T> | EnvelopeError;
+export interface ModuleResultData {
+    [key: string]: unknown;
+    confidence: number;
+    rationale: string;
+    behavior_equivalence?: boolean;
+}
 export interface ModuleResult {
+    ok: boolean;
+    data?: ModuleResultData;
+    error?: {
+        code: string;
+        message: string;
+    };
+    partial_data?: unknown;
+    raw?: string;
+}
+export interface LegacyModuleResult {
     output: unknown;
     confidence: number;
     rationale: string;

package/dist/types.js

@@ -1,5 +1,5 @@
 /**
  * Cognitive Runtime - Core Types
- * Version 2.0 - With tools policy, failure contract, and behavior equivalence
+ * Version 2.1 - With envelope format, tools policy, failure contract
  */
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cognitive-runtime",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Cognitive Runtime - Structured AI Task Execution",
   "type": "module",
   "main": "dist/index.js",

package/src/cli.ts

@@ -13,7 +13,7 @@ import { getProvider, listProviders } from './providers/index.js';
 import { run, list, pipe, init } from './commands/index.js';
 import type { CommandContext } from './types.js';
 
-const VERSION = '0.4.0';
+const VERSION = '0.5.0';
 
 async function main() {
   const args = process.argv.slice(2);

package/src/commands/pipe.ts

@@ -54,16 +54,20 @@ export async function pipe(
       input: inputData,
     });
 
-    // Output JSON to stdout
-    console.log(JSON.stringify(result.output));
+    // Output envelope format to stdout
+    console.log(JSON.stringify(result));
 
     return {
-      success: true,
+      success: result.ok,
       data: result,
     };
   } catch (e) {
     const error = e instanceof Error ? e.message : String(e);
-    console.error(JSON.stringify({ error }));
+    // Output error in envelope format
+    console.log(JSON.stringify({
+      ok: false,
+      error: { code: 'RUNTIME_ERROR', message: error }
+    }));
     return {
       success: false,
       error,

package/src/commands/run.ts

@@ -50,10 +50,27 @@ export async function run(
       verbose: options.verbose || ctx.verbose,
     });
 
-    return {
-      success: true,
-      data: options.pretty ? result : result.output,
-    };
+    // Return envelope format or extracted data
+    if (options.pretty) {
+      return {
+        success: result.ok,
+        data: result,
+      };
+    } else {
+      // For non-pretty mode, return data (success) or error (failure)
+      if (result.ok) {
+        return {
+          success: true,
+          data: result.data,
+        };
+      } else {
+        return {
+          success: false,
+          error: `${result.error?.code}: ${result.error?.message}`,
+          data: result.partial_data,
+        };
+      }
+    }
   } catch (e) {
     return {
       success: false,

package/src/modules/loader.ts

@@ -6,7 +6,7 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import yaml from 'js-yaml';
-import type { CognitiveModule, ModuleConstraints, ToolsPolicy, OutputContract, FailureContract } from '../types.js';
+import type { CognitiveModule, ModuleConstraints, ModulePolicies, ToolsPolicy, OutputContract, FailureContract, RuntimeRequirements } from '../types.js';
 
 const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n([\s\S]*))?/;
 
@@ -64,9 +64,11 @@ async function loadModuleV2(modulePath: string): Promise<CognitiveModule> {
     responsibility: manifest.responsibility as string || '',
     excludes: (manifest.excludes as string[]) || [],
     constraints: manifest.constraints as ModuleConstraints | undefined,
+    policies: manifest.policies as ModulePolicies | undefined,
     tools: manifest.tools as ToolsPolicy | undefined,
     output: manifest.output as OutputContract | undefined,
     failure: manifest.failure as FailureContract | undefined,
+    runtimeRequirements: manifest.runtime_requirements as RuntimeRequirements | undefined,
     context: manifest.context as 'fork' | 'main' | undefined,
     prompt,
     inputSchema,

package/src/modules/runner.ts

@@ -1,9 +1,17 @@
 /**
  * Module Runner - Execute Cognitive Modules
- * v2: Clean input mapping, no CLI pollution
+ * v2.1: Envelope format support, clean input mapping
  */
 
-import type { Provider, CognitiveModule, ModuleResult, Message, ModuleInput } from '../types.js';
+import type { 
+  Provider, 
+  CognitiveModule, 
+  ModuleResult, 
+  Message, 
+  ModuleInput,
+  EnvelopeResponse,
+  ModuleResultData
+} from '../types.js';
 
 export interface RunOptions {
   // Clean input (v2 style)
@@ -14,6 +22,9 @@ export interface RunOptions {
   
   // Runtime options
   verbose?: boolean;
+  
+  // Force envelope format (default: auto-detect from module.output.envelope)
+  useEnvelope?: boolean;
 }
 
 export async function runModule(
@@ -21,7 +32,10 @@ export async function runModule(
   provider: Provider,
   options: RunOptions = {}
 ): Promise<ModuleResult> {
-  const { args, input, verbose = false } = options;
+  const { args, input, verbose = false, useEnvelope } = options;
+
+  // Determine if we should use envelope format
+  const shouldUseEnvelope = useEnvelope ?? (module.output?.envelope === true || module.format === 'v2');
 
   // Build clean input data (v2 style: no $ARGUMENTS pollution)
   const inputData: ModuleInput = input || {};
@@ -43,6 +57,7 @@ export async function runModule(
     console.error('--- Module ---');
     console.error(`Name: ${module.name} (${module.format})`);
     console.error(`Responsibility: ${module.responsibility}`);
+    console.error(`Envelope: ${shouldUseEnvelope}`);
     console.error('--- Input ---');
     console.error(JSON.stringify(inputData, null, 2));
     console.error('--- Prompt ---');
@@ -74,13 +89,28 @@ export async function runModule(
     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}`);
   }
 
-  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');
+  // Add envelope format instructions
+  if (shouldUseEnvelope) {
+    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: Message[] = [
@@ -102,16 +132,63 @@ export async function runModule(
   }
 
   // Parse response
-  let output: unknown;
+  let parsed: unknown;
   try {
     const jsonMatch = result.content.match(/```(?:json)?\s*([\s\S]*?)\s*```/);
     const jsonStr = jsonMatch ? jsonMatch[1] : result.content;
-    output = JSON.parse(jsonStr.trim());
+    parsed = JSON.parse(jsonStr.trim());
   } catch {
     throw new Error(`Failed to parse JSON response: ${result.content.substring(0, 500)}`);
   }
 
-  // Extract standard fields
+  // Handle envelope format
+  if (shouldUseEnvelope && isEnvelopeResponse(parsed)) {
+    return parseEnvelopeResponse(parsed, result.content);
+  }
+
+  // Handle legacy format (non-envelope)
+  return parseLegacyResponse(parsed, result.content);
+}
+
+/**
+ * Check if response is in envelope format
+ */
+function isEnvelopeResponse(obj: unknown): obj is EnvelopeResponse {
+  if (typeof obj !== 'object' || obj === null) return false;
+  const o = obj as Record<string, unknown>;
+  return typeof o.ok === 'boolean';
+}
+
+/**
+ * Parse envelope format response
+ */
+function parseEnvelopeResponse(response: EnvelopeResponse, raw: string): ModuleResult {
+  if (response.ok) {
+    const data = response.data as ModuleResultData;
+    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: unknown, raw: string): ModuleResult {
   const outputObj = output as Record<string, unknown>;
   const confidence = typeof outputObj.confidence === 'number' ? outputObj.confidence : 0.5;
   const rationale = typeof outputObj.rationale === 'string' ? outputObj.rationale : '';
@@ -119,12 +196,30 @@ export async function runModule(
     ? 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 as Record<string, unknown>;
+    if (typeof errorObj.code === 'string') {
+      return {
+        ok: false,
+        error: {
+          code: errorObj.code,
+          message: typeof errorObj.message === 'string' ? errorObj.message : 'Unknown error',
+        },
+        raw,
+      };
+    }
+  }
+
   return {
-    output,
-    confidence,
-    rationale,
-    behaviorEquivalence,
-    raw: result.content,
+    ok: true,
+    data: {
+      ...outputObj,
+      confidence,
+      rationale,
+      behavior_equivalence: behaviorEquivalence,
+    } as ModuleResultData,
+    raw,
   };
 }
 

package/src/types.ts

@@ -1,6 +1,6 @@
 /**
  * Cognitive Runtime - Core Types
- * Version 2.0 - With tools policy, failure contract, and behavior equivalence
+ * Version 2.1 - With envelope format, tools policy, failure contract
  */
 
 // Provider interface - all LLM providers implement this
@@ -31,7 +31,7 @@ export interface InvokeResult {
   };
 }
 
-// Module types (v2)
+// Module types (v2.1)
 export interface CognitiveModule {
   // Core identity
   name: string;
@@ -42,6 +42,9 @@ export interface CognitiveModule {
   excludes: string[];
   constraints?: ModuleConstraints;
   
+  // Unified policies (v2.1)
+  policies?: ModulePolicies;
+  
   // Tools policy
   tools?: ToolsPolicy;
   
@@ -51,6 +54,9 @@ export interface CognitiveModule {
   // Failure contract
   failure?: FailureContract;
   
+  // Runtime requirements
+  runtimeRequirements?: RuntimeRequirements;
+  
   // Execution context
   context?: 'fork' | 'main';
   
@@ -72,24 +78,82 @@ export interface ModuleConstraints {
   no_side_effects?: boolean;
   no_file_write?: boolean;
   no_inventing_data?: boolean;
+  behavior_equivalence_false_max_confidence?: number;
+}
+
+export interface ModulePolicies {
+  network?: 'allow' | 'deny';
+  filesystem_write?: 'allow' | 'deny';
+  side_effects?: 'allow' | 'deny';
+  code_execution?: 'allow' | 'deny';
 }
 
 export interface ToolsPolicy {
+  policy?: 'allow_by_default' | 'deny_by_default';
   allowed: string[];
+  denied?: string[];
 }
 
 export interface OutputContract {
-  mode?: 'json_strict' | 'json_lenient' | 'text';
+  format?: 'json_strict' | 'json_lenient' | 'text';
+  envelope?: boolean;  // v2.1: Use {ok, data/error} wrapper
+  require?: string[];
   require_confidence?: boolean;
   require_rationale?: boolean;
   require_behavior_equivalence?: boolean;
 }
 
 export interface FailureContract {
+  contract?: 'error_union' | 'throw';
+  partial_allowed?: boolean;
+  must_return_error_schema?: boolean;
   schema?: object;
 }
 
+export interface RuntimeRequirements {
+  structured_output?: boolean;
+  max_input_tokens?: number;
+  preferred_capabilities?: string[];
+}
+
+// Envelope response format (v2.1)
+export interface EnvelopeSuccess<T = unknown> {
+  ok: true;
+  data: T;
+}
+
+export interface EnvelopeError {
+  ok: false;
+  error: {
+    code: string;
+    message: string;
+  };
+  partial_data?: unknown;
+}
+
+export type EnvelopeResponse<T = unknown> = EnvelopeSuccess<T> | EnvelopeError;
+
+// Module result types
+export interface ModuleResultData {
+  [key: string]: unknown;
+  confidence: number;
+  rationale: string;
+  behavior_equivalence?: boolean;
+}
+
 export interface ModuleResult {
+  ok: boolean;
+  data?: ModuleResultData;
+  error?: {
+    code: string;
+    message: string;
+  };
+  partial_data?: unknown;
+  raw?: string;
+}
+
+// Legacy result format (for backward compatibility)
+export interface LegacyModuleResult {
   output: unknown;
   confidence: number;
   rationale: string;