cognitive-modules-cli 1.0.1 → 1.2.0

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,16 @@ 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';
+/** Risk aggregation rule */
+export type RiskRule = 'max_changes_risk' | 'max_issues_risk' | 'explicit';
 export interface CognitiveModule {
     name: string;
     version: string;
@@ -36,13 +46,22 @@ export interface CognitiveModule {
     output?: OutputContract;
     failure?: FailureContract;
     runtimeRequirements?: RuntimeRequirements;
+    tier?: ModuleTier;
+    schemaStrictness?: SchemaStrictness;
+    overflow?: OverflowConfig;
+    enums?: EnumConfig;
+    compat?: CompatConfig;
+    metaConfig?: MetaConfig;
     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,11 +100,77 @@ 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';
+}
+/** Meta field configuration (v2.2) */
+export interface MetaConfig {
+    required?: string[];
+    risk_rule?: RiskRule;
+    confidence?: {
+        min?: number;
+        max?: number;
+    };
+    explain?: {
+        max_chars?: number;
+    };
+}
+/**
+ * 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;
+export interface EnvelopeSuccessV21<T = unknown> {
     ok: true;
     data: T;
 }
-export interface EnvelopeError {
+export interface EnvelopeErrorV21 {
     ok: false;
     error: {
         code: string;
@@ -93,15 +178,46 @@ 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>;
+/** 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 +226,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 +265,20 @@ 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>, riskRule?: RiskRule): EnvelopeMeta;
+/**
+ * Aggregate risk based on configured rule.
+ *
+ * Rules:
+ * - max_changes_risk: max(data.changes[*].risk) - default
+ * - max_issues_risk: max(data.issues[*].risk) - for review modules
+ * - explicit: return "medium", module should set risk explicitly
+ */
+export declare function aggregateRisk(data: Record<string, unknown>, riskRule?: RiskRule): 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,92 @@
 /**
  * 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, riskRule = 'max_changes_risk') {
+    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: aggregateRisk(data, riskRule),
+            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 items */
+function aggregateRiskFromList(items) {
+    const riskLevels = { none: 0, low: 1, medium: 2, high: 3 };
+    const riskNames = ['none', 'low', 'medium', 'high'];
+    if (!items || items.length === 0) {
+        return 'medium';
+    }
+    let maxLevel = 0;
+    for (const item of items) {
+        const level = riskLevels[item.risk ?? 'medium'];
+        maxLevel = Math.max(maxLevel, level);
+    }
+    return riskNames[maxLevel];
+}
+/**
+ * Aggregate risk based on configured rule.
+ *
+ * Rules:
+ * - max_changes_risk: max(data.changes[*].risk) - default
+ * - max_issues_risk: max(data.issues[*].risk) - for review modules
+ * - explicit: return "medium", module should set risk explicitly
+ */
+export function aggregateRisk(data, riskRule = 'max_changes_risk') {
+    if (riskRule === 'max_changes_risk') {
+        const changes = data.changes ?? [];
+        return aggregateRiskFromList(changes);
+    }
+    else if (riskRule === 'max_issues_risk') {
+        const issues = data.issues ?? [];
+        return aggregateRiskFromList(issues);
+    }
+    else if (riskRule === 'explicit') {
+        return 'medium'; // Module should override
+    }
+    // Fallback to changes
+    const changes = data.changes ?? [];
+    return aggregateRiskFromList(changes);
+}
+/** 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.2.0",
   "description": "Cognitive Modules - Structured AI Task Execution with version management",
   "type": "module",
   "main": "dist/index.js",

package/src/modules/loader.ts

@@ -6,7 +6,21 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import yaml from 'js-yaml';
-import type { CognitiveModule, ModuleConstraints, ModulePolicies, ToolsPolicy, OutputContract, FailureContract, RuntimeRequirements } from '../types.js';
+import type { 
+  CognitiveModule, 
+  ModuleConstraints, 
+  ModulePolicies, 
+  ToolsPolicy, 
+  OutputContract, 
+  FailureContract, 
+  RuntimeRequirements,
+  OverflowConfig,
+  EnumConfig,
+  CompatConfig,
+  MetaConfig,
+  ModuleTier,
+  SchemaStrictness
+} from '../types.js';
 
 const FRONTMATTER_REGEX = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n([\s\S]*))?/;
 
@@ -23,6 +37,19 @@ async function detectFormat(modulePath: string): Promise<'v1' | 'v2'> {
   }
 }
 
+/**
+ * Detect v2.x sub-version from manifest
+ */
+function detectV2Version(manifest: Record<string, unknown>): string {
+  if (manifest.tier || manifest.overflow || manifest.enums) {
+    return 'v2.2';
+  }
+  if (manifest.policies || manifest.failure) {
+    return 'v2.1';
+  }
+  return 'v2.0';
+}
+
 /**
  * Load v2 format module (module.yaml + prompt.md)
  */
@@ -35,6 +62,9 @@ async function loadModuleV2(modulePath: string): Promise<CognitiveModule> {
   const manifestContent = await fs.readFile(manifestFile, 'utf-8');
   const manifest = yaml.load(manifestContent) as Record<string, unknown>;
 
+  // Detect v2.x version
+  const formatVersion = detectV2Version(manifest);
+
   // Read prompt.md
   let prompt = '';
   try {
@@ -46,18 +76,68 @@ async function loadModuleV2(modulePath: string): Promise<CognitiveModule> {
   // Read schema.json
   let inputSchema: object | undefined;
   let outputSchema: object | undefined;
+  let dataSchema: object | undefined;
+  let metaSchema: object | undefined;
   let errorSchema: object | undefined;
   
   try {
     const schemaContent = await fs.readFile(schemaFile, 'utf-8');
     const schema = JSON.parse(schemaContent);
     inputSchema = schema.input;
-    outputSchema = schema.output;
+    // Support both "data" (v2.2) and "output" (v2.1) aliases
+    dataSchema = schema.data || schema.output;
+    outputSchema = dataSchema; // Backward compat
+    metaSchema = schema.meta;
     errorSchema = schema.error;
   } catch {
     // Schema file is optional but recommended
   }
 
+  // Extract v2.2 fields
+  const tier = manifest.tier as ModuleTier | undefined;
+  const schemaStrictness = (manifest.schema_strictness as SchemaStrictness) || 'medium';
+  
+  // Determine default max_items based on strictness (SPEC-v2.2)
+  const strictnessMaxItems: Record<SchemaStrictness, number> = {
+    high: 0,
+    medium: 5,
+    low: 20
+  };
+  const defaultMaxItems = strictnessMaxItems[schemaStrictness] ?? 5;
+  const defaultEnabled = schemaStrictness !== 'high';
+  
+  // Parse overflow config with strictness-based defaults
+  const overflowRaw = (manifest.overflow as Record<string, unknown>) || {};
+  const overflow: OverflowConfig = {
+    enabled: (overflowRaw.enabled as boolean) ?? defaultEnabled,
+    recoverable: (overflowRaw.recoverable as boolean) ?? true,
+    max_items: (overflowRaw.max_items as number) ?? defaultMaxItems,
+    require_suggested_mapping: (overflowRaw.require_suggested_mapping as boolean) ?? true
+  };
+  
+  // Parse enums config
+  const enumsRaw = (manifest.enums as Record<string, unknown>) || {};
+  const enums: EnumConfig = {
+    strategy: (enumsRaw.strategy as 'strict' | 'extensible') ?? 
+      (tier === 'exec' ? 'strict' : 'extensible'),
+    unknown_tag: (enumsRaw.unknown_tag as string) ?? 'custom'
+  };
+  
+  // Parse compat config
+  const compatRaw = (manifest.compat as Record<string, unknown>) || {};
+  const compat: CompatConfig = {
+    accepts_v21_payload: (compatRaw.accepts_v21_payload as boolean) ?? true,
+    runtime_auto_wrap: (compatRaw.runtime_auto_wrap as boolean) ?? true,
+    schema_output_alias: (compatRaw.schema_output_alias as 'data' | 'output') ?? 'data'
+  };
+  
+  // Parse meta config (including risk_rule)
+  const metaRaw = (manifest.meta as Record<string, unknown>) || {};
+  const metaConfig: MetaConfig = {
+    required: metaRaw.required as string[] | undefined,
+    risk_rule: metaRaw.risk_rule as 'max_changes_risk' | 'max_issues_risk' | 'explicit' | undefined,
+  };
+
   return {
     name: manifest.name as string || path.basename(modulePath),
     version: manifest.version as string || '1.0.0',
@@ -69,13 +149,26 @@ async function loadModuleV2(modulePath: string): Promise<CognitiveModule> {
     output: manifest.output as OutputContract | undefined,
     failure: manifest.failure as FailureContract | undefined,
     runtimeRequirements: manifest.runtime_requirements as RuntimeRequirements | undefined,
+    // v2.2 fields
+    tier,
+    schemaStrictness,
+    overflow,
+    enums,
+    compat,
+    metaConfig,
+    // Context and prompt
     context: manifest.context as 'fork' | 'main' | undefined,
     prompt,
+    // Schemas
     inputSchema,
     outputSchema,
+    dataSchema,
+    metaSchema,
     errorSchema,
+    // Metadata
     location: modulePath,
     format: 'v2',
+    formatVersion,
   };
 }