cognitive-modules-cli 2.2.13 → 2.2.15

package/CHANGELOG.md

@@ -2,15 +2,28 @@
 
 All notable changes to this package are documented in this file.
 
-## 2.2.12 - 2026-02-08
+## 2.2.15 - 2026-03-09
 
-- Conformance: add `runtime` suite (offline, deterministic vectors) to validate publish-grade JSON parsing and profile gates.
-- UX: conformance help/usage now documents `--suite runtime` explicitly.
+- Runtime: add schema-guided output canonicalization so enum labels and unordered arrays can be normalized before validation/repair.
+- Benchmarks: tighten gate/extraction contracts around canonical labels and publish `Benchmark Evidence` showing Gemini + MiniMax contract stability.
+- Use case: add the official `pr-risk-gate` module plus a copy-paste GitHub Actions template for blocking risky PRs in CI.
+
+## 2.2.14 - 2026-03-08
+
+- Release: add docs build to `release:check`, so docs regressions fail before npm publish.
+- Hardening: `packages/cogn` now runs the primary runtime release gate before alias-package publish checks.
+- Providers: preserve Anthropic streaming input/output token accounting correctly.
+- Test coverage: add request-shaping tests for the full stable provider set (`openai`, `anthropic`, `gemini`, `minimax`, `deepseek`, `qwen`).
 
 ## 2.2.13 - 2026-02-08
 
 - Fix: do not repair/convert successful envelopes into error envelopes when output validation is disabled (`--profile core`/`validate=off`).
 
+## 2.2.12 - 2026-02-08
+
+- Conformance: add `runtime` suite (offline, deterministic vectors) to validate publish-grade JSON parsing and profile gates.
+- UX: conformance help/usage now documents `--suite runtime` explicitly.
+
 ## 2.2.11 - 2026-02-07
 
 - Fix: Gemini `responseSchema` compatibility by dropping non-string `enum`/`const` constraints (Gemini rejects boolean enums).

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://badge.fury.io/js/cognitive-modules-cli.svg)](https://www.npmjs.com/package/cognitive-modules-cli)
 
-Node.js/TypeScript 版本的 Cognitive Modules CLI。文档统一使用明确入口 `npx cogn@2.2.13 ...`，避免 PATH/命令冲突。
+Node.js/TypeScript 版本的 Cognitive Modules CLI。文档统一使用明确入口 `npx cogn@2.2.15 ...`，避免 PATH/命令冲突。
 
 > 这是 [cognitive-modules](../../README.md) monorepo 的一部分。
 
@@ -10,11 +10,11 @@ Node.js/TypeScript 版本的 Cognitive Modules CLI。文档统一使用明确入
 
 ```bash
 # 零安装（推荐）
-npx cogn@2.2.13 --help
+npx cogn@2.2.15 --help
 
 # 全局安装（可选）
-npm install -g cogn@2.2.13
-# 或：npm install -g cognitive-modules-cli@2.2.13
+npm install -g cogn@2.2.15
+# 或：npm install -g cognitive-modules-cli@2.2.15
 ```
 
 ## 快速开始
@@ -24,43 +24,56 @@ npm install -g cogn@2.2.13
 export OPENAI_API_KEY=sk-xxx
 
 # 查看 providers 能力矩阵（结构化输出/流式）
-npx cogn@2.2.13 providers --pretty
+npx cogn@2.2.15 providers --pretty
 
 # 运行模块
-npx cogn@2.2.13 run code-reviewer --args "def login(u,p): return db.query(f'SELECT * FROM users WHERE name={u}')" --pretty
+npx cogn@2.2.15 run code-reviewer --args "def login(u,p): return db.query(f'SELECT * FROM users WHERE name={u}')" --pretty
 
 # 列出模块
-npx cogn@2.2.13 list
+npx cogn@2.2.15 list
 
 # 管道模式
-echo "review this code" | npx cogn@2.2.13 pipe --module code-reviewer
+echo "review this code" | npx cogn@2.2.15 pipe --module code-reviewer
 ```
 
 ## 支持的 Provider
 
-| Provider | 环境变量 | 说明 |
+对外“稳定支持面”收敛为 6 个 provider（减少认知负担与维护成本）：
+
+| Provider（Stable） | 环境变量 | 说明 |
 |----------|----------|------|
-| OpenAI | `OPENAI_API_KEY` | OpenAI API |
-| Anthropic | `ANTHROPIC_API_KEY` | Claude |
+| OpenAI (ChatGPT) | `OPENAI_API_KEY` | OpenAI API |
+| Anthropic (Claude) | `ANTHROPIC_API_KEY` | Claude |
 | Gemini | `GEMINI_API_KEY` | Google Gemini |
-| DeepSeek | `DEEPSEEK_API_KEY` | DeepSeek |
 | MiniMax | `MINIMAX_API_KEY` | MiniMax |
-| Moonshot | `MOONSHOT_API_KEY` | Kimi |
-| Qwen | `DASHSCOPE_API_KEY` / `QWEN_API_KEY` | 通义千问 |
-| Ollama | `OLLAMA_HOST` | 本地模型 |
+| DeepSeek | `DEEPSEEK_API_KEY` | DeepSeek API |
+| Qwen (DashScope) | `DASHSCOPE_API_KEY` / `QWEN_API_KEY` | 通义千问 |
+
+实验/社区 provider 仍保留实现，但默认不在文档/能力矩阵中承诺稳定性（需要显式指定 `--provider`）：
+
+| Provider（Experimental/Community） | 环境变量 | 说明 |
+|----------|----------|------|
+| Moonshot (Kimi) | `MOONSHOT_API_KEY` | experimental |
+| Ollama (local) | `OLLAMA_HOST` | community |
+
+查看全部 provider（含实验/社区）：
+
+```bash
+npx cogn@2.2.15 providers --pretty --all
+```
 
 ## 命令
 
 ```bash
 # Core（单文件极简路径）
-npx cogn@2.2.13 core new                       # 生成 demo.md
-npx cogn@2.2.13 core run demo.md --args "..."  # 运行单文件模块
-npx cogn@2.2.13 core promote demo.md           # 升级为 v2 模块目录
+npx cogn@2.2.15 core new                       # 生成 demo.md
+npx cogn@2.2.15 core run demo.md --args "..."  # 运行单文件模块
+npx cogn@2.2.15 core promote demo.md           # 升级为 v2 模块目录
 
 # 渐进复杂度（Profiles）
-npx cogn@2.2.13 run code-reviewer --args "..." --profile core       # 极简：跳过校验
-npx cogn@2.2.13 run code-reviewer --args "..." --profile standard   # 推荐：日常默认
-npx cogn@2.2.13 run code-reviewer --args "..." --profile certified  # 最严格：v2.2 + 审计 + registry provenance/完整性门禁
+npx cogn@2.2.15 run code-reviewer --args "..." --profile core       # 极简：跳过校验
+npx cogn@2.2.15 run code-reviewer --args "..." --profile standard   # 推荐：日常默认
+npx cogn@2.2.15 run code-reviewer --args "..." --profile certified  # 最严格：v2.2 + 审计 + registry provenance/完整性门禁
 # 兼容别名（不推荐写进新文档）：
 # - default -> standard
 # - strict  -> standard（deprecated preset）
@@ -70,41 +83,41 @@ npx cogn@2.2.13 run code-reviewer --args "..." --profile certified  # 最严格
 # - --audit（写入 ~/.cognitive/audit/）
 
 # 模块操作
-npx cogn@2.2.13 list                      # 列出模块
-npx cogn@2.2.13 run <module> --args "..." # 运行模块
-npx cogn@2.2.13 add <url> -m <module>     # 从 GitHub 添加模块
-npx cogn@2.2.13 update <module>           # 更新模块
-npx cogn@2.2.13 remove <module>           # 删除模块
-npx cogn@2.2.13 versions <url>            # 查看可用版本
-npx cogn@2.2.13 init <name>               # 创建新模块
-npx cogn@2.2.13 pipe --module <name>      # 管道模式
+npx cogn@2.2.15 list                      # 列出模块
+npx cogn@2.2.15 run <module> --args "..." # 运行模块
+npx cogn@2.2.15 add <url> -m <module>     # 从 GitHub 添加模块
+npx cogn@2.2.15 update <module>           # 更新模块
+npx cogn@2.2.15 remove <module>           # 删除模块
+npx cogn@2.2.15 versions <url>            # 查看可用版本
+npx cogn@2.2.15 init <name>               # 创建新模块
+npx cogn@2.2.15 pipe --module <name>      # 管道模式
 
 # 组合执行
-npx cogn@2.2.13 compose <module> --args "..."
-npx cogn@2.2.13 compose-info <module>
+npx cogn@2.2.15 compose <module> --args "..."
+npx cogn@2.2.15 compose-info <module>
 
 # 校验与迁移
-npx cogn@2.2.13 validate <module> --v22
-npx cogn@2.2.13 validate --all
-npx cogn@2.2.13 migrate <module> --dry-run
-npx cogn@2.2.13 migrate --all --no-backup
+npx cogn@2.2.15 validate <module> --v22
+npx cogn@2.2.15 validate --all
+npx cogn@2.2.15 migrate <module> --dry-run
+npx cogn@2.2.15 migrate --all --no-backup
 
 # 服务器
-npx cogn@2.2.13 serve --port 8000         # 启动 HTTP API 服务
-npx cogn@2.2.13 mcp                       # 启动 MCP 服务（Claude Code / Cursor）
+npx cogn@2.2.15 serve --port 8000         # 启动 HTTP API 服务
+npx cogn@2.2.15 mcp                       # 启动 MCP 服务（Claude Code / Cursor）
 
 # 环境检查
-npx cogn@2.2.13 doctor
+npx cogn@2.2.15 doctor
 
 # Registry（索引与分发）
 # 默认 registry index（latest）：
 #   https://github.com/Cognary/cognitive/releases/latest/download/cognitive-registry.v2.json
 # 可通过环境变量或全局参数覆盖：
-COGNITIVE_REGISTRY_URL=... npx cogn@2.2.13 search
-COGNITIVE_REGISTRY_TIMEOUT_MS=15000 COGNITIVE_REGISTRY_MAX_BYTES=2097152 npx cogn@2.2.13 search
-npx cogn@2.2.13 search --registry https://github.com/Cognary/cognitive/releases/download/vX.Y.Z/cognitive-registry.v2.json
-npx cogn@2.2.13 registry verify --remote --index https://github.com/Cognary/cognitive/releases/latest/download/cognitive-registry.v2.json
-npx cogn@2.2.13 registry verify --remote --concurrency 2
+COGNITIVE_REGISTRY_URL=... npx cogn@2.2.15 search
+COGNITIVE_REGISTRY_TIMEOUT_MS=15000 COGNITIVE_REGISTRY_MAX_BYTES=2097152 npx cogn@2.2.15 search
+npx cogn@2.2.15 search --registry https://github.com/Cognary/cognitive/releases/download/vX.Y.Z/cognitive-registry.v2.json
+npx cogn@2.2.15 registry verify --remote --index https://github.com/Cognary/cognitive/releases/latest/download/cognitive-registry.v2.json
+npx cogn@2.2.15 registry verify --remote --concurrency 2
 ```
 
 ## 开发
@@ -127,6 +140,27 @@ npm run dev -- run code-reviewer --args "..."
 npm run release:check
 ```
 
+## Cognitive 对照基准
+
+如果你要验证“使用 Cognitive”和“直接 prompt/skill 风格 JSON 提示”之间的差异，可以运行内置对照基准：
+
+```bash
+# 先确保 dist 已构建
+npm run build
+
+# 只看计划，不实际调用模型
+npm run bench:cognitive-vs-raw -- --provider gemini --plan
+
+# 实际运行（示例）
+npm run bench:cognitive-vs-raw -- --provider gemini --model gemini-3-pro-preview --runs 3
+```
+
+相关文件：
+
+- `benchmarks/cognitive-vs-raw/README.md`
+- `benchmarks/cognitive-vs-raw/suite.example.json`
+- `benchmarks/cognitive-vs-raw/report-template.md`
+
 ## License
 
 MIT

package/dist/cli.js

@@ -62,14 +62,39 @@ async function main() {
             process.exit(1);
         }
     }
-    // Get provider
+    const commandRequiresProvider = (() => {
+        if (command === 'core')
+            return positionals[0] === 'run';
+        switch (command) {
+            case 'run':
+            case 'pipe':
+            case 'compose':
+            case 'test':
+            case 'conformance':
+            case 'serve':
+            case 'mcp':
+                return true;
+            default:
+                return false;
+        }
+    })();
+    // Get provider (only required for commands that actually invoke an LLM).
+    // For non-provider commands (list/validate/registry/docs helpers), we keep the CLI usable even
+    // when no API keys are configured by using a placeholder provider that should not be invoked.
     let provider;
-    try {
-        provider = getProvider(values.provider, values.model);
+    if (commandRequiresProvider) {
+        try {
+            provider = getProvider(values.provider, values.model);
+        }
+        catch (e) {
+            console.error(`Error: ${e instanceof Error ? e.message : e}`);
+            process.exit(1);
+        }
     }
-    catch (e) {
-        console.error(`Error: ${e instanceof Error ? e.message : e}`);
-        process.exit(1);
+    else {
+        // If the user explicitly asked for a provider, respect it even if unconfigured.
+        // Otherwise, pick a stable placeholder.
+        provider = getProvider(values.provider ?? 'openai', values.model);
     }
     let policy;
     try {
@@ -248,7 +273,7 @@ async function main() {
                 console.log('');
                 // 2. Provider configuration
                 console.log('LLM Providers:');
-                const providers = listProviders();
+                const providers = listProviders({ all: Boolean(values.all) });
                 let hasConfiguredProvider = false;
                 for (const p of providers) {
                     const status = p.configured ? '✓' : '–';
@@ -257,6 +282,7 @@ async function main() {
                     console.log(`      Model: ${p.model}`);
                     console.log(`      Structured output: ${p.structuredOutput}`);
                     console.log(`      Streaming: ${p.streaming ? 'yes' : 'no'}`);
+                    console.log(`      Support: ${p.support}`);
                     console.log(`      Status: ${apiKeyStatus}`);
                     if (p.configured)
                         hasConfiguredProvider = true;
@@ -270,7 +296,8 @@ async function main() {
                 }
                 catch {
                     console.log('  ✗ None configured');
-                    console.log('    → Set one of: OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, etc.');
+                    console.log('    → Set one of: OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, MINIMAX_API_KEY, DEEPSEEK_API_KEY, DASHSCOPE_API_KEY/QWEN_API_KEY');
+                    console.log('    → Experimental providers require explicit --provider (see: cog providers --all)');
                 }
                 console.log('');
                 // 4. Module scan
@@ -355,7 +382,7 @@ async function main() {
                 break;
             }
             case 'providers': {
-                const providers = listProviders();
+                const providers = listProviders({ all: Boolean(values.all) });
                 console.log(JSON.stringify({ providers }, null, values.pretty ? 2 : 0));
                 break;
             }
@@ -1008,7 +1035,7 @@ OPTIONS:
   -t, --tag <version>   Git tag/version (for add/update)
   -b, --branch <name>   Git branch (for add)
   -M, --model <name>    LLM model (e.g., gpt-4o, gemini-2.0-flash)
-  -p, --provider <name> LLM provider (gemini, openai, anthropic, deepseek, minimax, moonshot, qwen, ollama)
+  -p, --provider <name> LLM provider (stable: openai, anthropic, gemini, minimax, deepseek, qwen)
   --pretty              Pretty-print JSON output
   -V, --verbose         Verbose output
   --no-validate         Skip schema validation
@@ -1022,7 +1049,7 @@ OPTIONS:
   --v22                 Use strict v2.2 validation (for validate)
   --dry-run             Show what would be done without changes (for migrate)
   --no-backup           Skip backup before migration (for migrate)
-  --all                 Process all modules (for validate/migrate)
+  --all                 Process all modules (validate/migrate/test) OR include experimental providers (providers/doctor)
   --conformance         Run official spec vectors (for test)
   --suite <name>        Conformance suite: envelope|runtime|stream|registry|all
   --level <n>           Conformance level: 1|2|3
@@ -1100,15 +1127,17 @@ ENVIRONMENT:
   GEMINI_API_KEY      Google Gemini
   OPENAI_API_KEY      OpenAI
   ANTHROPIC_API_KEY   Anthropic Claude
-  DEEPSEEK_API_KEY    DeepSeek
   MINIMAX_API_KEY     MiniMax
-  MOONSHOT_API_KEY    Moonshot (Kimi)
+  DEEPSEEK_API_KEY    DeepSeek
   DASHSCOPE_API_KEY   Alibaba Qwen (通义千问)
-  OLLAMA_HOST         Ollama local (default: localhost:11434)
   COG_MODEL           Override default model for any provider
   COGNITIVE_REGISTRY_URL  Override registry index URL
   COGNITIVE_REGISTRY_TIMEOUT_MS  Registry index fetch timeout (ms)
   COGNITIVE_REGISTRY_MAX_BYTES   Registry index max bytes
+
+EXPERIMENTAL/COMMUNITY (not in the stable support promise; use --provider explicitly):
+  MOONSHOT_API_KEY    Moonshot (Kimi)
+  OLLAMA_HOST         Ollama local (default: localhost:11434)
 `);
 }
 main().catch(e => {

package/dist/modules/runner.js

@@ -21,6 +21,74 @@ function safeSnippet(s, max = 500) {
         return raw;
     return raw.slice(0, max) + `…(+${raw.length - max} chars)`;
 }
+function stableCanonicalKey(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableCanonicalKey(item)).join(',')}]`;
+    }
+    if (value && typeof value === 'object') {
+        const obj = value;
+        return `{${Object.keys(obj).sort().map((key) => `${JSON.stringify(key)}:${stableCanonicalKey(obj[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function normalizeStringValue(value, hint) {
+    let normalized = value.trim().replace(/\s+/g, ' ');
+    switch (hint) {
+        case 'lowercase':
+            normalized = normalized.toLowerCase();
+            break;
+        case 'lower_snake_case':
+            normalized = normalized
+                .toLowerCase()
+                .replace(/[^a-z0-9]+/g, '_')
+                .replace(/^_+|_+$/g, '');
+            break;
+        default:
+            break;
+    }
+    return normalized;
+}
+function canonicalizeDataBySchema(value, schema) {
+    if (!schema || typeof schema !== 'object' || schema === null) {
+        return typeof value === 'string' ? normalizeStringValue(value) : value;
+    }
+    const schemaObj = schema;
+    const type = schemaObj.type;
+    if (typeof value === 'string') {
+        const hint = typeof schemaObj['x-cognitive-string-normalize'] === 'string'
+            ? String(schemaObj['x-cognitive-string-normalize'])
+            : undefined;
+        const normalized = normalizeStringValue(value, hint);
+        if (Array.isArray(schemaObj.enum)) {
+            const enumMatch = schemaObj.enum.find((candidate) => {
+                if (typeof candidate !== 'string')
+                    return false;
+                return normalizeStringValue(candidate, hint).toLowerCase() === normalized.toLowerCase();
+            });
+            return enumMatch ?? normalized;
+        }
+        return normalized;
+    }
+    if (Array.isArray(value)) {
+        const itemSchema = schemaObj.items;
+        const normalizedItems = value.map((item) => canonicalizeDataBySchema(item, itemSchema));
+        if (schemaObj['x-cognitive-unordered'] === true) {
+            normalizedItems.sort((a, b) => stableCanonicalKey(a).localeCompare(stableCanonicalKey(b)));
+        }
+        return normalizedItems;
+    }
+    if (value && typeof value === 'object' && !Array.isArray(value) && type === 'object') {
+        const properties = (schemaObj.properties && typeof schemaObj.properties === 'object')
+            ? schemaObj.properties
+            : {};
+        const normalized = {};
+        for (const [key, child] of Object.entries(value)) {
+            normalized[key] = canonicalizeDataBySchema(child, properties[key]);
+        }
+        return normalized;
+    }
+    return value;
+}
 function parseJsonWithCandidates(raw) {
     const candidates = extractJsonCandidates(raw);
     const attempts = [];
@@ -936,6 +1004,12 @@ function repairEnvelope(response, riskRule = 'max_changes_risk', maxExplainLengt
     if (meta.explain.length > maxExplainLength) {
         meta.explain = meta.explain.slice(0, maxExplainLength - 3) + '...';
     }
+    // data.rationale is commonly required by module contracts and is safely
+    // synthesizable from meta.explain when the model omitted the longer field.
+    if (typeof data.rationale !== 'string' || data.rationale.trim().length === 0) {
+        data.rationale = meta.explain;
+        repaired.data = data;
+    }
     // Build proper v2.2 response with version
     const builtMeta = {
         confidence: meta.confidence,
@@ -947,8 +1021,9 @@ function repairEnvelope(response, riskRule = 'max_changes_risk', maxExplainLengt
         version: ENVELOPE_VERSION,
         meta: builtMeta,
         // E4000 is an internal/runtime error fallback (should rarely happen after repair).
-        error: repaired.error ?? { code: 'E4000', message: 'Unknown error' },
-        partial_data: repaired.partial_data
+        error: repaired.error ??
+            { code: 'E4000', message: typeof meta.explain === 'string' && meta.explain.trim() ? meta.explain : 'Unknown error' },
+        partial_data: repaired.partial_data ?? repaired.data
     } : {
         ok: true,
         version: ENVELOPE_VERSION,
@@ -990,10 +1065,38 @@ function repairErrorEnvelope(data, maxExplainLength = 280) {
             explain: meta.explain,
         },
         // E4000 is an internal/runtime error fallback (should rarely happen after repair).
-        error: repaired.error ?? { code: 'E4000', message: 'Unknown error' },
-        partial_data: repaired.partial_data,
+        error: repaired.error ??
+            { code: 'E4000', message: typeof meta.explain === 'string' && meta.explain.trim() ? meta.explain : 'Unknown error' },
+        partial_data: repaired.partial_data ?? repaired.data,
     };
 }
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function normalizeEnvelopeLikeObject(parsed) {
+    if (!isPlainRecord(parsed) || !isPlainRecord(parsed.meta) || typeof parsed.ok !== 'boolean') {
+        return parsed;
+    }
+    const normalized = deepClone(parsed);
+    const reserved = new Set(['ok', 'version', 'meta', 'data', 'error', 'partial_data']);
+    const payloadEntries = Object.entries(normalized).filter(([key]) => !reserved.has(key));
+    if (normalized.ok === true) {
+        if (!isPlainRecord(normalized.data) && payloadEntries.length > 0) {
+            normalized.data = Object.fromEntries(payloadEntries);
+            for (const [key] of payloadEntries)
+                delete normalized[key];
+        }
+        return normalized;
+    }
+    const hasError = isPlainRecord(normalized.error) && typeof normalized.error.code === 'string';
+    if (!hasError && payloadEntries.length > 0) {
+        normalized.data = Object.fromEntries(payloadEntries);
+        for (const [key] of payloadEntries)
+            delete normalized[key];
+        normalized.ok = true;
+    }
+    return normalized;
+}
 /**
  * Wrap v2.1 response to v2.2 format
  */
@@ -1671,14 +1774,15 @@ export async function runModule(module, provider, options = {}) {
         }
         // Convert to v2.2 envelope
         let response;
-        if (isV22Envelope(parsed)) {
-            response = parsed;
+        const normalizedParsed = normalizeEnvelopeLikeObject(parsed);
+        if (isV22Envelope(normalizedParsed)) {
+            response = normalizedParsed;
         }
-        else if (isEnvelopeResponse(parsed)) {
-            response = wrapV21ToV22(parsed, riskRule);
+        else if (isEnvelopeResponse(normalizedParsed)) {
+            response = wrapV21ToV22(normalizedParsed, riskRule);
         }
         else {
-            response = convertLegacyToEnvelope(parsed);
+            response = convertLegacyToEnvelope(normalizedParsed);
         }
         // Add version and meta fields
         response.version = ENVELOPE_VERSION;
@@ -1727,6 +1831,9 @@ export async function runModule(module, provider, options = {}) {
             // Get data schema (support both "data" and "output" aliases)
             const dataSchema = module.dataSchema || module.outputSchema;
             const metaSchema = module.metaSchema;
+            if (dataSchema) {
+                response.data = canonicalizeDataBySchema(response.data ?? {}, dataSchema);
+            }
             const dataToValidate = response.data ?? {};
             if (dataSchema && Object.keys(dataSchema).length > 0) {
                 let dataErrors = validateData(dataToValidate, dataSchema, 'Data');
@@ -1735,7 +1842,8 @@ export async function runModule(module, provider, options = {}) {
                     response = repairEnvelope(response, riskRule);
                     response.version = ENVELOPE_VERSION;
                     // Re-validate after repair
-                    const repairedData = response.data ?? {};
+                    const repairedData = canonicalizeDataBySchema(response.data ?? {}, dataSchema);
+                    response.data = repairedData;
                     dataErrors = validateData(repairedData, dataSchema, 'Data');
                 }
                 if (dataErrors.length > 0) {
@@ -2115,14 +2223,15 @@ export async function* runModuleStream(module, provider, options = {}) {
         }
         // Convert to v2.2 envelope
         let response;
-        if (isV22Envelope(parsed)) {
-            response = parsed;
+        const normalizedParsed = normalizeEnvelopeLikeObject(parsed);
+        if (isV22Envelope(normalizedParsed)) {
+            response = normalizedParsed;
         }
-        else if (isEnvelopeResponse(parsed)) {
-            response = wrapV21ToV22(parsed, riskRule);
+        else if (isEnvelopeResponse(normalizedParsed)) {
+            response = wrapV21ToV22(normalizedParsed, riskRule);
         }
         else {
-            response = convertLegacyToEnvelope(parsed);
+            response = convertLegacyToEnvelope(normalizedParsed);
         }
         // Add version and meta
         response.version = ENVELOPE_VERSION;
@@ -2172,12 +2281,15 @@ export async function* runModuleStream(module, provider, options = {}) {
             const metaSchema = module.metaSchema;
             if (dataSchema && Object.keys(dataSchema).length > 0) {
                 let dataToValidate = response.data ?? {};
+                dataToValidate = canonicalizeDataBySchema(dataToValidate, dataSchema);
+                response.data = dataToValidate;
                 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 ?? {};
+                    const repairedData = canonicalizeDataBySchema(response.data ?? {}, dataSchema);
+                    response.data = repairedData;
                     dataToValidate = repairedData;
                     dataErrors = validateData(repairedData, dataSchema, 'Data');
                 }

package/dist/modules/subagent.d.ts

@@ -19,6 +19,8 @@ export interface CallDirective {
     module: string;
     args: string;
     match: string;
+    start: number;
+    end: number;
 }
 export interface SubagentRunOptions {
     input?: ModuleInput;
@@ -47,7 +49,9 @@ export declare function parseCalls(text: string): CallDirective[];
  * Replace @call directives with their results
  */
 export declare function substituteCallResults(text: string, callResults: Array<{
-    match: string;
+    match?: string;
+    start?: number;
+    end?: number;
     module: string;
     result: unknown;
 }>): string;

package/dist/modules/subagent.js

@@ -65,7 +65,9 @@ export function parseCalls(text) {
         calls.push({
             module: match[1],
             args: match[2] || '',
-            match: match[0]
+            match: match[0],
+            start: match.index,
+            end: match.index + match[0].length
         });
     }
     return calls;
@@ -74,14 +76,38 @@ export function parseCalls(text) {
  * Replace @call directives with their results
  */
 export function substituteCallResults(text, callResults) {
-    let result = text;
-    for (const entry of callResults) {
+    const buildReplacement = (entry) => {
         const resultStr = typeof entry.result === 'object'
             ? JSON.stringify(entry.result, null, 2)
             : String(entry.result);
-        const replacement = `[Result from ${entry.module}]:\n${resultStr}`;
+        return `[Result from ${entry.module}]:\n${resultStr}`;
+    };
+    const hasRanges = callResults.every((entry) => typeof entry.start === 'number' && typeof entry.end === 'number');
+    if (hasRanges) {
+        const sorted = [...callResults].sort((a, b) => (a.start ?? 0) - (b.start ?? 0));
+        let cursor = 0;
+        let result = '';
+        for (const entry of sorted) {
+            const start = entry.start;
+            const end = entry.end;
+            if (start < cursor) {
+                continue;
+            }
+            result += text.slice(cursor, start);
+            result += buildReplacement(entry);
+            cursor = end;
+        }
+        result += text.slice(cursor);
+        return result;
+    }
+    let result = text;
+    for (const entry of callResults) {
+        if (!entry.match) {
+            continue;
+        }
         const idx = result.indexOf(entry.match);
         if (idx !== -1) {
+            const replacement = buildReplacement(entry);
             result = result.slice(0, idx) + replacement + result.slice(idx + entry.match.length);
         }
     }
@@ -147,10 +173,22 @@ export class SubagentOrchestrator {
                 }, childContext);
                 // Store result
                 if (childResult.ok && 'data' in childResult) {
-                    callResults.push({ match: call.match, module: call.module, result: childResult.data });
+                    callResults.push({
+                        match: call.match,
+                        start: call.start,
+                        end: call.end,
+                        module: call.module,
+                        result: childResult.data
+                    });
                 }
                 else if ('error' in childResult) {
-                    callResults.push({ match: call.match, module: call.module, result: { error: childResult.error } });
+                    callResults.push({
+                        match: call.match,
+                        start: call.start,
+                        end: call.end,
+                        module: call.module,
+                        result: { error: childResult.error }
+                    });
                 }
             }
             // Substitute call results into prompt

package/dist/providers/anthropic.d.ts

@@ -20,6 +20,7 @@ export declare class AnthropicProvider extends BaseProvider {
      * Build request body for Anthropic API
      */
     private buildRequestBody;
+    private mergeUsage;
     invoke(params: InvokeParams): Promise<InvokeResult>;
     /**
      * Stream-based invoke using Anthropic's streaming API.

package/dist/providers/anthropic.js

@@ -53,6 +53,17 @@ export class AnthropicProvider extends BaseProvider {
         }
         return { body, systemContent: systemMessage?.content };
     }
+    mergeUsage(current, next) {
+        if (!next)
+            return current;
+        const promptTokens = next.input_tokens ?? current?.promptTokens ?? 0;
+        const completionTokens = next.output_tokens ?? current?.completionTokens ?? 0;
+        return {
+            promptTokens,
+            completionTokens,
+            totalTokens: promptTokens + completionTokens,
+        };
+    }
     async invoke(params) {
         if (!this.isConfigured()) {
             throw new Error('Anthropic API key not configured. Set ANTHROPIC_API_KEY environment variable.');
@@ -140,20 +151,11 @@ export class AnthropicProvider extends BaseProvider {
                             }
                             // Extract usage info (message_delta or message_stop event)
                             if (data.type === 'message_delta' && data.usage) {
-                                usage = {
-                                    promptTokens: data.usage.input_tokens || 0,
-                                    completionTokens: data.usage.output_tokens || 0,
-                                    totalTokens: (data.usage.input_tokens || 0) + (data.usage.output_tokens || 0),
-                                };
+                                usage = this.mergeUsage(usage, data.usage);
                             }
                             // Also check message_start for input tokens
                             if (data.type === 'message_start' && data.message?.usage) {
-                                const inputTokens = data.message.usage.input_tokens || 0;
-                                usage = {
-                                    promptTokens: inputTokens,
-                                    completionTokens: usage?.completionTokens || 0,
-                                    totalTokens: inputTokens + (usage?.completionTokens || 0),
-                                };
+                                usage = this.mergeUsage(usage, data.message.usage);
                             }
                         }
                         catch {
@@ -179,19 +181,10 @@ export class AnthropicProvider extends BaseProvider {
                             }
                         }
                         if (data.type === 'message_delta' && data.usage) {
-                            usage = {
-                                promptTokens: data.usage.input_tokens || 0,
-                                completionTokens: data.usage.output_tokens || 0,
-                                totalTokens: (data.usage.input_tokens || 0) + (data.usage.output_tokens || 0),
-                            };
+                            usage = this.mergeUsage(usage, data.usage);
                         }
                         if (data.type === 'message_start' && data.message?.usage) {
-                            const inputTokens = data.message.usage.input_tokens || 0;
-                            usage = {
-                                promptTokens: inputTokens,
-                                completionTokens: usage?.completionTokens || 0,
-                                totalTokens: inputTokens + (usage?.completionTokens || 0),
-                            };
+                            usage = this.mergeUsage(usage, data.message.usage);
                         }
                     }
                     catch {

package/dist/providers/index.d.ts

@@ -15,9 +15,13 @@ export { DeepSeekProvider } from './deepseek.js';
 export { MoonshotProvider } from './moonshot.js';
 export { QwenProvider } from './qwen.js';
 export { OllamaProvider } from './ollama.js';
+export type ProviderSupportTier = 'stable' | 'experimental' | 'community';
 export declare function getProvider(name?: string, model?: string): Provider;
-export declare function listProviders(): Array<{
+export declare function listProviders(opts?: {
+    all?: boolean;
+}): Array<{
     name: string;
+    support: ProviderSupportTier;
     configured: boolean;
     model: string;
     structuredOutput: StructuredOutputMode;

package/dist/providers/index.js

@@ -22,6 +22,14 @@ export { DeepSeekProvider } from './deepseek.js';
 export { MoonshotProvider } from './moonshot.js';
 export { QwenProvider } from './qwen.js';
 export { OllamaProvider } from './ollama.js';
+// Public promise: these providers are the "supported surface" for the open-source npm runtime.
+// Everything else is intentionally treated as experimental/community to reduce user confusion and
+// avoid over-promising stability across a long tail of provider quirks.
+const STABLE_PROVIDERS = ['openai', 'anthropic', 'gemini', 'minimax', 'deepseek', 'qwen'];
+const EXPERIMENTAL_PROVIDERS = ['moonshot', 'ollama'];
+function isStableProvider(name) {
+    return STABLE_PROVIDERS.includes(name);
+}
 const providers = {
     gemini: (model) => new GeminiProvider(undefined, model),
     openai: (model) => new OpenAIProvider(undefined, model),
@@ -39,24 +47,27 @@ const providers = {
 export function getProvider(name, model) {
     // Check for model override from environment
     const modelOverride = model || process.env.COG_MODEL;
-    // Auto-detect if not specified
+    // Auto-detect if not specified.
+    //
+    // Important: we only auto-select within the "stable" provider set.
+    // Experimental/community providers can still be used, but require explicit `--provider`,
+    // so users don't accidentally end up on a provider they didn't intend (or that isn't
+    // part of the stable support promise).
     if (!name) {
-        if (process.env.GEMINI_API_KEY)
-            return new GeminiProvider(undefined, modelOverride);
         if (process.env.OPENAI_API_KEY)
             return new OpenAIProvider(undefined, modelOverride);
         if (process.env.ANTHROPIC_API_KEY)
             return new AnthropicProvider(undefined, modelOverride);
-        if (process.env.DEEPSEEK_API_KEY)
-            return new DeepSeekProvider(undefined, modelOverride);
+        if (process.env.GEMINI_API_KEY)
+            return new GeminiProvider(undefined, modelOverride);
         if (process.env.MINIMAX_API_KEY)
             return new MiniMaxProvider(undefined, modelOverride);
-        if (process.env.MOONSHOT_API_KEY)
-            return new MoonshotProvider(undefined, modelOverride);
+        if (process.env.DEEPSEEK_API_KEY)
+            return new DeepSeekProvider(undefined, modelOverride);
         if (process.env.DASHSCOPE_API_KEY || process.env.QWEN_API_KEY)
             return new QwenProvider(undefined, modelOverride);
-        // Ollama is always available as fallback if nothing else is configured
-        return new OllamaProvider(modelOverride);
+        throw new Error(`No stable provider configured. Set one of: OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, MINIMAX_API_KEY, DEEPSEEK_API_KEY, DASHSCOPE_API_KEY/QWEN_API_KEY. ` +
+            `To use experimental providers, pass --provider (e.g. --provider moonshot).`);
     }
     const factory = providers[name.toLowerCase()];
     if (!factory) {
@@ -70,13 +81,14 @@ function safeCapabilities(p) {
         return caps;
     return { structuredOutput: 'prompt', streaming: p.supportsStreaming?.() ?? false };
 }
-function providerRow(name, configured, model, make) {
+function providerRow(name, configured, model, make, support) {
     const caps = safeCapabilities(make());
     const structuredJsonSchema = caps.structuredOutput === 'native' && (caps.nativeSchemaDialect ?? 'json-schema') !== 'json-schema'
         ? 'prompt'
         : caps.structuredOutput;
     return {
         name,
+        support,
         configured,
         model,
         structuredOutput: caps.structuredOutput,
@@ -86,15 +98,20 @@ function providerRow(name, configured, model, make) {
         streaming: caps.streaming,
     };
 }
-export function listProviders() {
-    return [
-        providerRow('gemini', !!process.env.GEMINI_API_KEY, 'gemini-3-pro-preview', () => new GeminiProvider('')),
-        providerRow('openai', !!process.env.OPENAI_API_KEY, 'gpt-5.2', () => new OpenAIProvider('')),
-        providerRow('anthropic', !!process.env.ANTHROPIC_API_KEY, 'claude-sonnet-4.5', () => new AnthropicProvider('')),
-        providerRow('deepseek', !!process.env.DEEPSEEK_API_KEY, 'deepseek-v3.2', () => new DeepSeekProvider('')),
-        providerRow('minimax', !!process.env.MINIMAX_API_KEY, 'MiniMax-M2.1', () => new MiniMaxProvider('')),
-        providerRow('moonshot', !!process.env.MOONSHOT_API_KEY, 'kimi-k2.5', () => new MoonshotProvider('')),
-        providerRow('qwen', !!(process.env.DASHSCOPE_API_KEY || process.env.QWEN_API_KEY), 'qwen3-max', () => new QwenProvider('')),
-        providerRow('ollama', true, 'llama4 (local)', () => new OllamaProvider()),
+export function listProviders(opts) {
+    const stable = [
+        providerRow('openai', !!process.env.OPENAI_API_KEY, 'gpt-5.2', () => new OpenAIProvider(''), 'stable'),
+        providerRow('anthropic', !!process.env.ANTHROPIC_API_KEY, 'claude-sonnet-4.5', () => new AnthropicProvider(''), 'stable'),
+        providerRow('gemini', !!process.env.GEMINI_API_KEY, 'gemini-3-pro-preview', () => new GeminiProvider(''), 'stable'),
+        providerRow('minimax', !!process.env.MINIMAX_API_KEY, 'MiniMax-M2.1', () => new MiniMaxProvider(''), 'stable'),
+        providerRow('deepseek', !!process.env.DEEPSEEK_API_KEY, 'deepseek-chat', () => new DeepSeekProvider(''), 'stable'),
+        providerRow('qwen', !!(process.env.DASHSCOPE_API_KEY || process.env.QWEN_API_KEY), 'qwen3-max', () => new QwenProvider(''), 'stable'),
+    ];
+    if (!opts?.all)
+        return stable;
+    const experimental = [
+        providerRow('moonshot', !!process.env.MOONSHOT_API_KEY, 'kimi-k2.5', () => new MoonshotProvider(''), 'experimental'),
+        providerRow('ollama', !!process.env.OLLAMA_HOST, 'llama4 (local)', () => new OllamaProvider(), 'community'),
     ];
+    return [...stable, ...experimental];
 }

package/dist/providers/minimax.js

@@ -2,15 +2,17 @@
  * MiniMax Provider - MiniMax API
  */
 import { BaseProvider } from './base.js';
+const DEFAULT_MINIMAX_BASE_URL = 'https://api.minimax.io/v1';
 export class MiniMaxProvider extends BaseProvider {
     name = 'minimax';
     apiKey;
     model;
-    baseUrl = 'https://api.minimax.chat/v1';
+    baseUrl;
     constructor(apiKey, model = 'MiniMax-M2.1') {
         super();
         this.apiKey = apiKey || process.env.MINIMAX_API_KEY || '';
         this.model = model;
+        this.baseUrl = (process.env.MINIMAX_BASE_URL || DEFAULT_MINIMAX_BASE_URL).replace(/\/+$/, '');
     }
     isConfigured() {
         return !!this.apiKey;

package/dist/types.js

@@ -7,7 +7,17 @@
 // =============================================================================
 /** Check if response is v2.2 format */
 export function isV22Envelope(response) {
-    return 'meta' in response;
+    if (typeof response !== 'object' || response === null)
+        return false;
+    const envelope = response;
+    if (typeof envelope.ok !== 'boolean')
+        return false;
+    if (typeof envelope.meta !== 'object' || envelope.meta === null || Array.isArray(envelope.meta))
+        return false;
+    if (envelope.ok === true) {
+        return 'data' in envelope;
+    }
+    return typeof envelope.error === 'object' && envelope.error !== null && !Array.isArray(envelope.error);
 }
 /** Check if response is successful */
 export function isEnvelopeSuccess(response) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cognitive-modules-cli",
-  "version": "2.2.13",
+  "version": "2.2.15",
   "description": "Cognitive Modules - Structured AI Task Execution with version management",
   "type": "module",
   "main": "dist/index.js",
@@ -24,8 +24,9 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "bench:cognitive-vs-raw": "node benchmarks/cognitive-vs-raw/run.mjs",
     "pack:check": "npm pack --dry-run --json --cache ../../.npm-cache",
-    "release:check": "npm run build && npm test && npm run pack:check",
+    "release:check": "node ../../scripts/release/check-docs-build.js && npm run build && npm test && npm run pack:check",
     "prepublishOnly": "npm run release:check"
   },
   "keywords": [