cognitive-modules-cli 1.0.1 → 1.1.0

package/dist/modules/runner.js

@@ -169,6 +169,7 @@ function parseLegacyResponse(output, raw) {
             };
         }
     }
+    // Return as v2.1 format (data includes confidence)
     return {
         ok: true,
         data: {

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 /**
  * Cognitive Runtime - Core Types
- * Version 2.1 - With envelope format, tools policy, failure contract
+ * Version 2.2 - With Control/Data plane separation, tier, overflow, extensible enums
  */
 export interface Provider {
     name: string;
@@ -25,6 +25,14 @@ export interface InvokeResult {
         totalTokens: number;
     };
 }
+/** Module classification for schema strictness */
+export type ModuleTier = 'exec' | 'decision' | 'exploration';
+/** Schema validation strictness level */
+export type SchemaStrictness = 'high' | 'medium' | 'low';
+/** Risk level (used in both meta and changes) */
+export type RiskLevel = 'none' | 'low' | 'medium' | 'high';
+/** Enum extension strategy */
+export type EnumStrategy = 'strict' | 'extensible';
 export interface CognitiveModule {
     name: string;
     version: string;
@@ -36,13 +44,21 @@ export interface CognitiveModule {
     output?: OutputContract;
     failure?: FailureContract;
     runtimeRequirements?: RuntimeRequirements;
+    tier?: ModuleTier;
+    schemaStrictness?: SchemaStrictness;
+    overflow?: OverflowConfig;
+    enums?: EnumConfig;
+    compat?: CompatConfig;
     context?: 'fork' | 'main';
     prompt: string;
     inputSchema?: object;
     outputSchema?: object;
+    dataSchema?: object;
+    metaSchema?: object;
     errorSchema?: object;
     location: string;
-    format: 'v1' | 'v2';
+    format: 'v0' | 'v1' | 'v2';
+    formatVersion?: string;
 }
 export interface ModuleConstraints {
     no_network?: boolean;
@@ -81,27 +97,112 @@ export interface RuntimeRequirements {
     max_input_tokens?: number;
     preferred_capabilities?: string[];
 }
-export interface EnvelopeSuccess<T = unknown> {
+/** Overflow configuration for extensions.insights */
+export interface OverflowConfig {
+    enabled: boolean;
+    recoverable?: boolean;
+    max_items?: number;
+    require_suggested_mapping?: boolean;
+}
+/** Enum extension configuration */
+export interface EnumConfig {
+    strategy: EnumStrategy;
+    unknown_tag?: string;
+}
+/** Compatibility configuration for migration */
+export interface CompatConfig {
+    accepts_v21_payload?: boolean;
+    runtime_auto_wrap?: boolean;
+    schema_output_alias?: 'data' | 'output';
+}
+/**
+ * Control plane metadata - unified across all modules.
+ * Used for routing, logging, UI cards, and middleware decisions.
+ */
+export interface EnvelopeMeta {
+    /** Confidence score [0, 1] - unified across all modules */
+    confidence: number;
+    /** Aggregated risk level: max(changes[*].risk) */
+    risk: RiskLevel;
+    /** Short explanation for middleware/UI (max 280 chars) */
+    explain: string;
+    /** Distributed tracing ID */
+    trace_id?: string;
+    /** Provider and model identifier */
+    model?: string;
+    /** Execution latency in milliseconds */
+    latency_ms?: number;
+}
+/** Success response in v2.2 envelope format */
+export interface EnvelopeSuccessV22<T = unknown> {
     ok: true;
+    meta: EnvelopeMeta;
     data: T;
 }
-export interface EnvelopeError {
+/** Error response in v2.2 envelope format */
+export interface EnvelopeErrorV22 {
     ok: false;
+    meta: EnvelopeMeta;
     error: {
         code: string;
         message: string;
     };
     partial_data?: unknown;
 }
-export type EnvelopeResponse<T = unknown> = EnvelopeSuccess<T> | EnvelopeError;
+/** v2.2 envelope response (union type) */
+export type EnvelopeResponseV22<T = unknown> = EnvelopeSuccessV22<T> | EnvelopeErrorV22;
+export interface EnvelopeSuccessV21<T = unknown> {
+    ok: true;
+    data: T;
+}
+export interface EnvelopeErrorV21 {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+    partial_data?: unknown;
+}
+export type EnvelopeResponseV21<T = unknown> = EnvelopeSuccessV21<T> | EnvelopeErrorV21;
+/** Generic envelope response (supports both v2.1 and v2.2) */
+export type EnvelopeResponse<T = unknown> = EnvelopeResponseV22<T> | EnvelopeResponseV21<T>;
+/** An insight that doesn't fit the schema but is valuable */
+export interface Insight {
+    /** The observation or insight */
+    text: string;
+    /** Suggested field/enum to add to schema for future versions */
+    suggested_mapping: string;
+    /** Supporting evidence for this insight */
+    evidence?: string;
+}
+/** Extensions container for overflow data */
+export interface Extensions {
+    insights?: Insight[];
+}
+/**
+ * Extensible enum type - allows both predefined values and custom extensions.
+ *
+ * Usage:
+ * type ChangeType = ExtensibleEnum<'remove_redundancy' | 'simplify_logic' | 'other'>;
+ *
+ * Valid values:
+ * - "remove_redundancy" (predefined)
+ * - { custom: "inline_callback", reason: "Converted callback to arrow function" }
+ */
+export type ExtensibleEnum<T extends string> = T | {
+    custom: string;
+    reason: string;
+};
+/** Base interface for module result data */
 export interface ModuleResultData {
     [key: string]: unknown;
-    confidence: number;
     rationale: string;
-    behavior_equivalence?: boolean;
+    extensions?: Extensions;
 }
-export interface ModuleResult {
+/** v2.2 module result with meta and data separation */
+export interface ModuleResultV22 {
     ok: boolean;
+    meta: EnvelopeMeta;
     data?: ModuleResultData;
     error?: {
         code: string;
@@ -110,6 +211,21 @@ export interface ModuleResult {
     partial_data?: unknown;
     raw?: string;
 }
+/** Legacy module result (v2.1) */
+export interface ModuleResultV21 {
+    ok: boolean;
+    data?: ModuleResultData & {
+        confidence: number;
+    };
+    error?: {
+        code: string;
+        message: string;
+    };
+    partial_data?: unknown;
+    raw?: string;
+}
+/** Generic module result */
+export type ModuleResult = ModuleResultV22 | ModuleResultV21;
 export interface LegacyModuleResult {
     output: unknown;
     confidence: number;
@@ -134,3 +250,15 @@ export interface ModuleInput {
     options?: Record<string, unknown>;
     [key: string]: unknown;
 }
+/** Check if response is v2.2 format */
+export declare function isV22Envelope<T>(response: EnvelopeResponse<T>): response is EnvelopeResponseV22<T>;
+/** Check if response is successful */
+export declare function isEnvelopeSuccess<T>(response: EnvelopeResponse<T>): response is EnvelopeSuccessV22<T> | EnvelopeSuccessV21<T>;
+/** Extract meta from any envelope response */
+export declare function extractMeta<T>(response: EnvelopeResponse<T>): EnvelopeMeta;
+/** Aggregate risk from list of changes */
+export declare function aggregateRisk(changes: Array<{
+    risk?: RiskLevel;
+}>): RiskLevel;
+/** Check if result should be escalated to human review */
+export declare function shouldEscalate<T>(response: EnvelopeResponse<T>, confidenceThreshold?: number): boolean;

package/dist/types.js

@@ -1,5 +1,68 @@
 /**
  * Cognitive Runtime - Core Types
- * Version 2.1 - With envelope format, tools policy, failure contract
+ * Version 2.2 - With Control/Data plane separation, tier, overflow, extensible enums
  */
-export {};
+// =============================================================================
+// Utility Types
+// =============================================================================
+/** Check if response is v2.2 format */
+export function isV22Envelope(response) {
+    return 'meta' in response;
+}
+/** Check if response is successful */
+export function isEnvelopeSuccess(response) {
+    return response.ok === true;
+}
+/** Extract meta from any envelope response */
+export function extractMeta(response) {
+    if (isV22Envelope(response)) {
+        return response.meta;
+    }
+    // Synthesize meta from v2.1 response
+    if (response.ok) {
+        const data = response.data;
+        return {
+            confidence: data?.confidence ?? 0.5,
+            risk: 'medium',
+            explain: (data?.rationale ?? '').slice(0, 280) || 'No explanation',
+        };
+    }
+    else {
+        return {
+            confidence: 0,
+            risk: 'high',
+            explain: response.error?.message?.slice(0, 280) ?? 'Error occurred',
+        };
+    }
+}
+/** Aggregate risk from list of changes */
+export function aggregateRisk(changes) {
+    const riskLevels = { none: 0, low: 1, medium: 2, high: 3 };
+    const riskNames = ['none', 'low', 'medium', 'high'];
+    if (!changes || changes.length === 0) {
+        return 'medium';
+    }
+    let maxLevel = 0;
+    for (const change of changes) {
+        const level = riskLevels[change.risk ?? 'medium'];
+        maxLevel = Math.max(maxLevel, level);
+    }
+    return riskNames[maxLevel];
+}
+/** Check if result should be escalated to human review */
+export function shouldEscalate(response, confidenceThreshold = 0.7) {
+    const meta = extractMeta(response);
+    // Escalate if low confidence
+    if (meta.confidence < confidenceThreshold) {
+        return true;
+    }
+    // Escalate if high risk
+    if (meta.risk === 'high') {
+        return true;
+    }
+    // Escalate if error
+    if (!response.ok) {
+        return true;
+    }
+    return false;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cognitive-modules-cli",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Cognitive Modules - Structured AI Task Execution with version management",
   "type": "module",
   "main": "dist/index.js",

package/src/modules/runner.ts

@@ -7,6 +7,7 @@ import type {
   Provider, 
   CognitiveModule, 
   ModuleResult, 
+  ModuleResultV21,
   Message, 
   ModuleInput,
   EnvelopeResponse,
@@ -211,6 +212,7 @@ function parseLegacyResponse(output: unknown, raw: string): ModuleResult {
     }
   }
 
+  // Return as v2.1 format (data includes confidence)
   return {
     ok: true,
     data: {
@@ -218,9 +220,9 @@ function parseLegacyResponse(output: unknown, raw: string): ModuleResult {
       confidence,
       rationale,
       behavior_equivalence: behaviorEquivalence,
-    } as ModuleResultData,
+    },
     raw,
-  };
+  } as ModuleResultV21;
 }
 
 /**

package/src/types.ts

@@ -1,9 +1,12 @@
 /**
  * Cognitive Runtime - Core Types
- * Version 2.1 - With envelope format, tools policy, failure contract
+ * Version 2.2 - With Control/Data plane separation, tier, overflow, extensible enums
  */
 
-// Provider interface - all LLM providers implement this
+// =============================================================================
+// Provider Interface
+// =============================================================================
+
 export interface Provider {
   name: string;
   invoke(params: InvokeParams): Promise<InvokeResult>;
@@ -31,7 +34,26 @@ export interface InvokeResult {
   };
 }
 
-// Module types (v2.1)
+// =============================================================================
+// v2.2 Core Types
+// =============================================================================
+
+/** Module classification for schema strictness */
+export type ModuleTier = 'exec' | 'decision' | 'exploration';
+
+/** Schema validation strictness level */
+export type SchemaStrictness = 'high' | 'medium' | 'low';
+
+/** Risk level (used in both meta and changes) */
+export type RiskLevel = 'none' | 'low' | 'medium' | 'high';
+
+/** Enum extension strategy */
+export type EnumStrategy = 'strict' | 'extensible';
+
+// =============================================================================
+// Module Configuration (v2.2)
+// =============================================================================
+
 export interface CognitiveModule {
   // Core identity
   name: string;
@@ -42,7 +64,7 @@ export interface CognitiveModule {
   excludes: string[];
   constraints?: ModuleConstraints;
   
-  // Unified policies (v2.1)
+  // Unified policies (v2.1+)
   policies?: ModulePolicies;
   
   // Tools policy
@@ -57,6 +79,21 @@ export interface CognitiveModule {
   // Runtime requirements
   runtimeRequirements?: RuntimeRequirements;
   
+  // v2.2: Module tier
+  tier?: ModuleTier;
+  
+  // v2.2: Schema strictness
+  schemaStrictness?: SchemaStrictness;
+  
+  // v2.2: Overflow configuration
+  overflow?: OverflowConfig;
+  
+  // v2.2: Enum configuration
+  enums?: EnumConfig;
+  
+  // v2.2: Compatibility configuration
+  compat?: CompatConfig;
+  
   // Execution context
   context?: 'fork' | 'main';
   
@@ -65,12 +102,15 @@ export interface CognitiveModule {
   
   // Schemas
   inputSchema?: object;
-  outputSchema?: object;
+  outputSchema?: object;  // v2.1 compat
+  dataSchema?: object;    // v2.2: same as outputSchema
+  metaSchema?: object;    // v2.2: control plane schema
   errorSchema?: object;
   
   // Metadata
   location: string;
-  format: 'v1' | 'v2';  // v1 = MODULE.md, v2 = module.yaml + prompt.md
+  format: 'v0' | 'v1' | 'v2';
+  formatVersion?: string;  // v2.0, v2.1, v2.2
 }
 
 export interface ModuleConstraints {
@@ -96,7 +136,7 @@ export interface ToolsPolicy {
 
 export interface OutputContract {
   format?: 'json_strict' | 'json_lenient' | 'text';
-  envelope?: boolean;  // v2.1: Use {ok, data/error} wrapper
+  envelope?: boolean;
   require?: string[];
   require_confidence?: boolean;
   require_rationale?: boolean;
@@ -116,13 +156,90 @@ export interface RuntimeRequirements {
   preferred_capabilities?: string[];
 }
 
-// Envelope response format (v2.1)
-export interface EnvelopeSuccess<T = unknown> {
+// =============================================================================
+// v2.2 New Configuration Types
+// =============================================================================
+
+/** Overflow configuration for extensions.insights */
+export interface OverflowConfig {
+  enabled: boolean;
+  recoverable?: boolean;
+  max_items?: number;
+  require_suggested_mapping?: boolean;
+}
+
+/** Enum extension configuration */
+export interface EnumConfig {
+  strategy: EnumStrategy;
+  unknown_tag?: string;  // How to represent unknown enums (default: "custom")
+}
+
+/** Compatibility configuration for migration */
+export interface CompatConfig {
+  accepts_v21_payload?: boolean;
+  runtime_auto_wrap?: boolean;
+  schema_output_alias?: 'data' | 'output';
+}
+
+// =============================================================================
+// Envelope Types (v2.2)
+// =============================================================================
+
+/**
+ * Control plane metadata - unified across all modules.
+ * Used for routing, logging, UI cards, and middleware decisions.
+ */
+export interface EnvelopeMeta {
+  /** Confidence score [0, 1] - unified across all modules */
+  confidence: number;
+  
+  /** Aggregated risk level: max(changes[*].risk) */
+  risk: RiskLevel;
+  
+  /** Short explanation for middleware/UI (max 280 chars) */
+  explain: string;
+  
+  /** Distributed tracing ID */
+  trace_id?: string;
+  
+  /** Provider and model identifier */
+  model?: string;
+  
+  /** Execution latency in milliseconds */
+  latency_ms?: number;
+}
+
+/** Success response in v2.2 envelope format */
+export interface EnvelopeSuccessV22<T = unknown> {
+  ok: true;
+  meta: EnvelopeMeta;
+  data: T;
+}
+
+/** Error response in v2.2 envelope format */
+export interface EnvelopeErrorV22 {
+  ok: false;
+  meta: EnvelopeMeta;
+  error: {
+    code: string;
+    message: string;
+  };
+  partial_data?: unknown;
+}
+
+/** v2.2 envelope response (union type) */
+export type EnvelopeResponseV22<T = unknown> = EnvelopeSuccessV22<T> | EnvelopeErrorV22;
+
+// =============================================================================
+// Legacy Envelope Types (v2.1 - for backward compatibility)
+// =============================================================================
+
+export interface EnvelopeSuccessV21<T = unknown> {
   ok: true;
   data: T;
 }
 
-export interface EnvelopeError {
+export interface EnvelopeErrorV21 {
   ok: false;
   error: {
     code: string;
@@ -131,18 +248,63 @@ export interface EnvelopeError {
   partial_data?: unknown;
 }
 
-export type EnvelopeResponse<T = unknown> = EnvelopeSuccess<T> | EnvelopeError;
+export type EnvelopeResponseV21<T = unknown> = EnvelopeSuccessV21<T> | EnvelopeErrorV21;
+
+/** Generic envelope response (supports both v2.1 and v2.2) */
+export type EnvelopeResponse<T = unknown> = EnvelopeResponseV22<T> | EnvelopeResponseV21<T>;
+
+// =============================================================================
+// Overflow Types (v2.2)
+// =============================================================================
+
+/** An insight that doesn't fit the schema but is valuable */
+export interface Insight {
+  /** The observation or insight */
+  text: string;
+  
+  /** Suggested field/enum to add to schema for future versions */
+  suggested_mapping: string;
+  
+  /** Supporting evidence for this insight */
+  evidence?: string;
+}
+
+/** Extensions container for overflow data */
+export interface Extensions {
+  insights?: Insight[];
+}
+
+// =============================================================================
+// Extensible Enum Pattern (v2.2)
+// =============================================================================
+
+/**
+ * Extensible enum type - allows both predefined values and custom extensions.
+ * 
+ * Usage:
+ * type ChangeType = ExtensibleEnum<'remove_redundancy' | 'simplify_logic' | 'other'>;
+ * 
+ * Valid values:
+ * - "remove_redundancy" (predefined)
+ * - { custom: "inline_callback", reason: "Converted callback to arrow function" }
+ */
+export type ExtensibleEnum<T extends string> = T | { custom: string; reason: string };
+
+// =============================================================================
+// Module Result Types
+// =============================================================================
 
-// Module result types
+/** Base interface for module result data */
 export interface ModuleResultData {
   [key: string]: unknown;
-  confidence: number;
   rationale: string;
-  behavior_equivalence?: boolean;
+  extensions?: Extensions;
 }
 
-export interface ModuleResult {
+/** v2.2 module result with meta and data separation */
+export interface ModuleResultV22 {
   ok: boolean;
+  meta: EnvelopeMeta;
   data?: ModuleResultData;
   error?: {
     code: string;
@@ -152,7 +314,25 @@ export interface ModuleResult {
   raw?: string;
 }
 
-// Legacy result format (for backward compatibility)
+/** Legacy module result (v2.1) */
+export interface ModuleResultV21 {
+  ok: boolean;
+  data?: ModuleResultData & { confidence: number };
+  error?: {
+    code: string;
+    message: string;
+  };
+  partial_data?: unknown;
+  raw?: string;
+}
+
+/** Generic module result */
+export type ModuleResult = ModuleResultV22 | ModuleResultV21;
+
+// =============================================================================
+// Legacy Types (for backward compatibility)
+// =============================================================================
+
 export interface LegacyModuleResult {
   output: unknown;
   confidence: number;
@@ -161,7 +341,10 @@ export interface LegacyModuleResult {
   raw?: string;
 }
 
-// Command types
+// =============================================================================
+// Command Types
+// =============================================================================
+
 export interface CommandContext {
   cwd: string;
   provider: Provider;
@@ -174,7 +357,10 @@ export interface CommandResult {
   error?: string;
 }
 
-// Module input (clean, no CLI pollution)
+// =============================================================================
+// Module Input
+// =============================================================================
+
 export interface ModuleInput {
   code?: string;
   query?: string;
@@ -182,3 +368,85 @@ export interface ModuleInput {
   options?: Record<string, unknown>;
   [key: string]: unknown;
 }
+
+// =============================================================================
+// Utility Types
+// =============================================================================
+
+/** Check if response is v2.2 format */
+export function isV22Envelope<T>(response: EnvelopeResponse<T>): response is EnvelopeResponseV22<T> {
+  return 'meta' in response;
+}
+
+/** Check if response is successful */
+export function isEnvelopeSuccess<T>(
+  response: EnvelopeResponse<T>
+): response is EnvelopeSuccessV22<T> | EnvelopeSuccessV21<T> {
+  return response.ok === true;
+}
+
+/** Extract meta from any envelope response */
+export function extractMeta<T>(response: EnvelopeResponse<T>): EnvelopeMeta {
+  if (isV22Envelope(response)) {
+    return response.meta;
+  }
+  
+  // Synthesize meta from v2.1 response
+  if (response.ok) {
+    const data = response.data as Record<string, unknown>;
+    return {
+      confidence: (data?.confidence as number) ?? 0.5,
+      risk: 'medium',
+      explain: ((data?.rationale as string) ?? '').slice(0, 280) || 'No explanation',
+    };
+  } else {
+    return {
+      confidence: 0,
+      risk: 'high',
+      explain: response.error?.message?.slice(0, 280) ?? 'Error occurred',
+    };
+  }
+}
+
+/** Aggregate risk from list of changes */
+export function aggregateRisk(changes: Array<{ risk?: RiskLevel }>): RiskLevel {
+  const riskLevels: Record<RiskLevel, number> = { none: 0, low: 1, medium: 2, high: 3 };
+  const riskNames: RiskLevel[] = ['none', 'low', 'medium', 'high'];
+  
+  if (!changes || changes.length === 0) {
+    return 'medium';
+  }
+  
+  let maxLevel = 0;
+  for (const change of changes) {
+    const level = riskLevels[change.risk ?? 'medium'];
+    maxLevel = Math.max(maxLevel, level);
+  }
+  
+  return riskNames[maxLevel];
+}
+
+/** Check if result should be escalated to human review */
+export function shouldEscalate<T>(
+  response: EnvelopeResponse<T>,
+  confidenceThreshold: number = 0.7
+): boolean {
+  const meta = extractMeta(response);
+  
+  // Escalate if low confidence
+  if (meta.confidence < confidenceThreshold) {
+    return true;
+  }
+  
+  // Escalate if high risk
+  if (meta.risk === 'high') {
+    return true;
+  }
+  
+  // Escalate if error
+  if (!response.ok) {
+    return true;
+  }
+  
+  return false;
+}