cognitive-modules-cli 2.2.7 → 2.2.9

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this package are documented in this file.
 
+## 2.2.9 - 2026-02-07
+
+- Fix: `cog core run` now prints the error envelope (instead of `Error: undefined`) when execution fails.
+- Packaging: add stable `bin.js` entrypoint so publish/install doesn't depend on prebuilt `dist/` existing at publish-time.
+- Core: align core template placeholders with runtime substitution (`${query}` / `${code}`); missing fields are treated as empty for single-file modules.
+
+## 2.2.8 - 2026-02-07
+
+- Fix: `npx cogn` alias compatibility on newer Node (exports + ESM). (Alias fix ships in `cogn@2.2.8`.)
+- Hardening: configurable registry index fetch limits (`--registry-timeout-ms`, `--registry-max-bytes`).
+- Hardening: remote registry verification supports bounded concurrency (`--concurrency`).
+
 ## 2.2.7 - 2026-02-06
 
 - Standardized v2.2 runtime behavior and cross-surface error envelope consistency (CLI/HTTP/MCP).

package/README.md

@@ -10,12 +10,12 @@ Node.js/TypeScript 版本的 Cognitive Modules CLI，提供 `cog` 命令。
 
 ```bash
 # 全局安装（推荐）
-npm install -g cogn@2.2.7
+npm install -g cogn@2.2.9
 # 或使用完整包名（同样提供 `cog` 命令）
-# npm install -g cognitive-modules-cli@2.2.7
+# npm install -g cognitive-modules-cli@2.2.9
 
 # 或使用 npx 零安装
-npx cogn@2.2.7 --help
+npx cogn@2.2.9 --help
 ```
 
 ## 快速开始
@@ -50,6 +50,18 @@ echo "review this code" | cog pipe --module code-reviewer
 ## 命令
 
 ```bash
+# Core（单文件极简路径）
+cog core new                       # 生成 demo.md
+cog core run demo.md --args "..."  # 运行单文件模块
+cog core promote demo.md           # 升级为 v2 模块目录
+
+# 渐进复杂度（Profiles）
+cog run code-reviewer --args "..." --profile core       # 极简：跳过校验
+cog run code-reviewer --args "..." --profile default    # 默认：开启校验
+cog run code-reviewer --args "..." --profile strict     # 更严格：开启校验（更强门禁）
+cog run code-reviewer --args "..." --profile certified  # 最严格：v2.2 + 审计 + registry provenance/完整性门禁
+# 覆盖开关：--validate auto|on|off，--audit（写入 ~/.cognitive/audit/）
+
 # 模块操作
 cog list                      # 列出模块
 cog run <module> --args "..." # 运行模块
@@ -76,6 +88,16 @@ cog mcp                       # 启动 MCP 服务（Claude Code / Cursor）
 
 # 环境检查
 cog doctor
+
+# Registry（索引与分发）
+# 默认 registry index（latest）：
+#   https://github.com/Cognary/cognitive/releases/latest/download/cognitive-registry.v2.json
+# 可通过环境变量或全局参数覆盖：
+COGNITIVE_REGISTRY_URL=... cog search
+COGNITIVE_REGISTRY_TIMEOUT_MS=15000 COGNITIVE_REGISTRY_MAX_BYTES=2097152 cog search
+cog search --registry https://github.com/Cognary/cognitive/releases/download/v2.2.9/cognitive-registry.v2.json
+cog registry verify --remote --index https://github.com/Cognary/cognitive/releases/latest/download/cognitive-registry.v2.json
+cog registry verify --remote --concurrency 2
 ```
 
 ## 开发

package/bin.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * Stable CLI entrypoint.
+ *
+ * Motivation:
+ * - Avoid `npm publish` warnings when `bin` points into `dist/` before build runs.
+ * - Keep runtime entrypoint stable even if build output paths change.
+ *
+ * This file is shipped in the published package and forwards to the compiled CLI.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const cliPath = path.join(__dirname, 'dist', 'cli.js');
+const args = process.argv.slice(2);
+
+const res = spawnSync(process.execPath, [cliPath, ...args], { stdio: 'inherit' });
+
+if (res.error) {
+  console.error(res.error);
+  process.exit(1);
+}
+
+process.exit(res.status ?? 1);
+

package/dist/audit.d.ts

@@ -0,0 +1,13 @@
+export interface AuditRecord {
+    ts: string;
+    kind: 'run' | 'pipe' | 'compose';
+    policy?: unknown;
+    provider?: string;
+    module?: unknown;
+    input?: unknown;
+    result?: unknown;
+    notes?: string[];
+}
+export declare function writeAuditRecord(record: AuditRecord): Promise<{
+    path: string;
+} | null>;

package/dist/audit.js

@@ -0,0 +1,25 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as os from 'node:os';
+function safeSlug(s) {
+    const out = s.trim().toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9._-]/g, '-');
+    return out.length > 0 ? out.slice(0, 80) : 'unknown';
+}
+export async function writeAuditRecord(record) {
+    // Keep it simple and predictable: write under ~/.cognitive/audit/
+    const dir = path.join(os.homedir(), '.cognitive', 'audit');
+    const ts = record.ts.replace(/[:.]/g, '-');
+    const kind = record.kind;
+    const moduleName = safeSlug(typeof record.module?.name === 'string' ? record.module.name : 'module');
+    const filename = `${ts}-${kind}-${moduleName}-${Math.random().toString(16).slice(2, 10)}.json`;
+    try {
+        await fs.mkdir(dir, { recursive: true });
+        const outPath = path.join(dir, filename);
+        await fs.writeFile(outPath, JSON.stringify(record, null, 2) + '\n', 'utf-8');
+        return { path: outPath };
+    }
+    catch {
+        // Audit must never break execution.
+        return null;
+    }
+}

package/dist/cli.js

@@ -15,9 +15,12 @@
  */
 import { parseArgs } from 'node:util';
 import { getProvider, listProviders } from './providers/index.js';
-import { run, list, pipe, init, add, update, remove, versions, compose, composeInfo, validate, validateAll, migrate, migrateAll, test, testAll, search, listCategories, info } from './commands/index.js';
+import { run, list, pipe, init, add, update, remove, versions, compose, composeInfo, validate, validateAll, migrate, migrateAll, test, testAll, search, listCategories, info, core } from './commands/index.js';
 import { listModules, getDefaultSearchPaths } from './modules/loader.js';
 import { VERSION } from './version.js';
+import { resolveExecutionPolicy } from './profile.js';
+import { buildRegistryAssets, verifyRegistryAssets } from './registry/assets.js';
+import { DEFAULT_REGISTRY_URL } from './registry/client.js';
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
@@ -33,6 +36,12 @@ async function main() {
     const { values, positionals } = parseArgs({
         args: args.slice(1),
         options: {
+            help: { type: 'boolean', short: 'h', default: false },
+            stdin: { type: 'boolean', default: false }, // core: read module prompt from stdin
+            force: { type: 'boolean', default: false }, // core promote: overwrite existing target dir
+            profile: { type: 'string' }, // progressive complexity profile
+            validate: { type: 'string' }, // auto|on|off (overrides --no-validate)
+            audit: { type: 'boolean', default: false }, // write audit record to ~/.cognitive/audit/
             args: { type: 'string', short: 'a' },
             input: { type: 'string', short: 'i' },
             module: { type: 'string', short: 'm' },
@@ -62,9 +71,59 @@ async function main() {
             format: { type: 'string', short: 'f' },
             // Search options
             category: { type: 'string', short: 'c' },
+            registry: { type: 'string' }, // override registry index URL (or use env COGNITIVE_REGISTRY_URL)
+            'registry-timeout-ms': { type: 'string' },
+            'registry-max-bytes': { type: 'string' },
+            // Registry build/verify options
+            'modules-dir': { type: 'string' },
+            'v1-registry': { type: 'string' },
+            'out-dir': { type: 'string' },
+            'registry-out': { type: 'string' },
+            namespace: { type: 'string' },
+            'runtime-min': { type: 'string' },
+            repository: { type: 'string' },
+            homepage: { type: 'string' },
+            license: { type: 'string' },
+            timestamp: { type: 'string' },
+            only: { type: 'string', multiple: true },
+            index: { type: 'string' },
+            'assets-dir': { type: 'string' },
+            'tarball-base-url': { type: 'string' },
+            remote: { type: 'boolean', default: false }, // registry verify: fetch index + tarballs over network
+            'fetch-timeout-ms': { type: 'string' },
+            'max-index-bytes': { type: 'string' },
+            'max-tarball-bytes': { type: 'string' },
+            concurrency: { type: 'string' },
         },
         allowPositionals: true,
     });
+    if (values.help) {
+        if (command === 'core') {
+            console.log(JSON.stringify({
+                usage: [
+                    'cog core new [file.md] [--dry-run]',
+                    'cog core schema <file.md> [--pretty]',
+                    'cog core run <file.md> [--args \"...\"] [--pretty] [--stream] [--no-validate]',
+                    'cog core run --stdin [--args \"...\"] [--pretty] [--stream] [--no-validate]',
+                    'cog core promote <file.md> [outDir] [--dry-run] [--force]',
+                ],
+            }, null, values.pretty ? 2 : 0));
+            process.exit(0);
+        }
+        printHelp();
+        process.exit(0);
+    }
+    // Guard Core-only flags so we don't silently ignore them on other commands.
+    if (command !== 'core') {
+        if (values.stdin) {
+            console.error('Error: --stdin is only supported for `cog core run --stdin`');
+            process.exit(1);
+        }
+        if (values.force) {
+            console.error('Error: --force is only supported for `cog core promote --force`');
+            process.exit(1);
+        }
+    }
     // Get provider
     let provider;
     try {
@@ -74,13 +133,72 @@ async function main() {
         console.error(`Error: ${e instanceof Error ? e.message : e}`);
         process.exit(1);
     }
+    let policy;
+    try {
+        policy = resolveExecutionPolicy({
+            profile: values.profile,
+            validate: values.validate,
+            noValidate: values['no-validate'],
+            audit: values.audit,
+        });
+    }
+    catch (e) {
+        console.error(`Error: ${e instanceof Error ? e.message : String(e)}`);
+        process.exit(1);
+    }
+    const parsePositive = (key, raw) => {
+        if (raw === undefined || raw === null || raw === '')
+            return undefined;
+        const n = Number(raw);
+        if (!Number.isFinite(n) || n <= 0) {
+            throw new Error(`Invalid --${key}: ${String(raw)} (expected a positive number)`);
+        }
+        return Math.floor(n);
+    };
     const ctx = {
         cwd: process.cwd(),
         provider,
         verbose: values.verbose,
+        policy,
+        registryUrl: values.registry ?? undefined,
+        registryTimeoutMs: parsePositive('registry-timeout-ms', values['registry-timeout-ms']),
+        registryMaxBytes: parsePositive('registry-max-bytes', values['registry-max-bytes']),
     };
     try {
         switch (command) {
+            case 'core': {
+                const sub = positionals[0];
+                const target = positionals[1];
+                const rest = positionals.slice(2);
+                const result = await core(sub, target, ctx, {
+                    args: values.args,
+                    input: values.input,
+                    noValidate: values['no-validate'],
+                    pretty: values.pretty,
+                    verbose: values.verbose,
+                    stream: values.stream,
+                    dryRun: values['dry-run'],
+                    stdin: values.stdin,
+                    force: values.force,
+                }, rest);
+                if (!result.success) {
+                    // Keep parity with `cog run`: if an error envelope exists, print it.
+                    // This avoids confusing "Error: undefined" when the command returns a valid envelope
+                    // but `error` string is not set.
+                    if (result.data) {
+                        console.log(JSON.stringify(result.data, null, values.pretty ? 2 : 0));
+                    }
+                    else {
+                        console.error(`Error: ${result.error ?? 'Unknown error'}`);
+                    }
+                    process.exit(1);
+                }
+                // Stream mode prints events as NDJSON already (via `cog run`).
+                if (!(values.stream && sub === 'run')) {
+                    console.log(JSON.stringify(result.data, null, values.pretty ? 2 : 0));
+                }
+                break;
+            }
             case 'run': {
                 const moduleName = args[1];
                 if (!moduleName || moduleName.startsWith('-')) {
@@ -90,6 +208,7 @@ async function main() {
                 const result = await run(moduleName, ctx, {
                     args: values.args,
                     input: values.input,
+                    // policy.validate is resolved in run(); keep legacy flag compatibility here.
                     noValidate: values['no-validate'],
                     pretty: values.pretty,
                     verbose: values.verbose,
@@ -388,6 +507,7 @@ async function main() {
                 const result = await compose(moduleName, ctx, {
                     args: values.args,
                     input: values.input,
+                    noValidate: values['no-validate'],
                     maxDepth: values['max-depth'] ? parseInt(values['max-depth'], 10) : undefined,
                     timeout: values.timeout ? parseInt(values.timeout, 10) : undefined,
                     trace: values.trace,
@@ -770,6 +890,52 @@ async function main() {
                     await client.fetchRegistry(true);
                     console.log('✓ Registry cache refreshed');
                 }
+                else if (subCommand === 'build') {
+                    const result = await buildRegistryAssets({
+                        tag: values.tag ?? null,
+                        tarballBaseUrl: values['tarball-base-url'] ?? null,
+                        modulesDir: values['modules-dir'] ?? 'cognitive/modules',
+                        v1RegistryPath: values['v1-registry'] ?? 'cognitive-registry.json',
+                        outDir: values['out-dir'] ?? 'dist/registry-assets',
+                        registryOut: values['registry-out'] ?? 'cognitive-registry.v2.json',
+                        namespace: values.namespace ?? 'official',
+                        runtimeMin: values['runtime-min'] ?? '2.2.0',
+                        repository: values.repository ?? 'https://github.com/Cognary/cognitive',
+                        homepage: values.homepage ?? 'https://cognary.github.io/cognitive/',
+                        license: values.license ?? 'MIT',
+                        timestamp: values.timestamp ?? null,
+                        only: Array.isArray(values.only) ? values.only : (values.only ? [String(values.only)] : []),
+                    });
+                    console.log(JSON.stringify({ ok: true, ...result }, null, values.pretty ? 2 : 0));
+                }
+                else if (subCommand === 'verify') {
+                    const remote = Boolean(values.remote);
+                    const defaultIndex = (typeof process.env.COGNITIVE_REGISTRY_URL === 'string' && process.env.COGNITIVE_REGISTRY_URL.trim()
+                        ? process.env.COGNITIVE_REGISTRY_URL.trim()
+                        : undefined) ??
+                        ctx.registryUrl ??
+                        DEFAULT_REGISTRY_URL;
+                    const indexPath = values.index ??
+                        (remote ? defaultIndex : 'cognitive-registry.v2.json');
+                    const assetsDir = values['assets-dir'] ?? (remote ? undefined : 'dist/registry-assets');
+                    const fetchTimeoutMs = parsePositive('fetch-timeout-ms', values['fetch-timeout-ms']);
+                    const maxIndexBytes = parsePositive('max-index-bytes', values['max-index-bytes']);
+                    const maxTarballBytes = parsePositive('max-tarball-bytes', values['max-tarball-bytes']);
+                    const concurrency = parsePositive('concurrency', values.concurrency);
+                    const verified = await verifyRegistryAssets({
+                        registryIndexPath: indexPath,
+                        assetsDir,
+                        remote,
+                        fetchTimeoutMs,
+                        maxIndexBytes,
+                        maxTarballBytes,
+                        concurrency,
+                    });
+                    console.log(JSON.stringify(verified, null, values.pretty ? 2 : 0));
+                    if (!verified.ok) {
+                        process.exit(1);
+                    }
+                }
                 else {
                     console.error(`Unknown registry subcommand: ${subCommand}`);
                     console.error('');
@@ -778,6 +944,9 @@ async function main() {
                     console.error('  cog registry categories  List categories');
                     console.error('  cog registry info <mod>  Show module details');
                     console.error('  cog registry refresh     Refresh cache');
+                    console.error('  cog registry build       Build registry tarballs + v2 index (local)');
+                    console.error('  cog registry verify      Verify local tarballs against v2 index');
+                    console.error('  cog registry verify --remote --index <url>  Verify remote index+tarballs');
                     process.exit(1);
                 }
                 break;
@@ -805,6 +974,7 @@ USAGE:
   cog <command> [options]
 
 COMMANDS:
+  core <cmd>          Minimal "one-file" workflow (new, schema, run)
   run <module>        Run a Cognitive Module
   test <module>       Run golden tests for a module
   compose <module>    Execute a composed module workflow
@@ -815,7 +985,7 @@ COMMANDS:
   remove <module>     Remove installed module
   versions <url>      List available versions
   search [query]      Search modules in registry
-  registry <cmd>      Registry commands (list, categories, info, refresh)
+  registry <cmd>      Registry commands (list, categories, info, refresh, build, verify)
   validate <module>   Validate module structure
   migrate <module>    Migrate module to v2.2 format
   pipe                Pipe mode (stdin/stdout)
@@ -825,6 +995,9 @@ COMMANDS:
   doctor              Check environment and configuration
 
 OPTIONS:
+  --profile <name>     Progressive complexity profile: core|default|strict|certified
+  --validate <mode>    Validation mode: auto|on|off (overrides --no-validate)
+  --audit              Write an audit record to ~/.cognitive/audit/ (stderr prints path)
   -a, --args <str>      Arguments to pass to module
   -i, --input <json>    JSON input for module
   -m, --module <name>   Module path within repo (for add)
@@ -836,6 +1009,8 @@ OPTIONS:
   --pretty              Pretty-print JSON output
   -V, --verbose         Verbose output
   --no-validate         Skip schema validation
+  --stdin               Read module prompt from stdin (for core run)
+  --force               Overwrite target directory (for core promote)
   -H, --host <host>     Server host (default: 0.0.0.0)
   -P, --port <port>     Server port (default: 8000)
   -d, --max-depth <n>   Max composition depth (default: 5)
@@ -847,11 +1022,21 @@ OPTIONS:
   --all                 Process all modules (for validate/migrate)
   -f, --format <fmt>    Output format: text or json (for validate)
   -c, --category <cat>  Filter by category (for search)
+  --registry <url>      Override registry index URL (or set env COGNITIVE_REGISTRY_URL)
+  --registry-timeout-ms <ms>  Registry index fetch timeout (overrides env COGNITIVE_REGISTRY_TIMEOUT_MS)
+  --registry-max-bytes <n>    Registry index max bytes (overrides env COGNITIVE_REGISTRY_MAX_BYTES)
   -l, --limit <n>       Limit results (for search, versions)
   -v, --version         Show version
   -h, --help            Show this help
 
 EXAMPLES:
+  # One-file Core (no registry required)
+  cog core new demo.md
+  cog core run demo.md --args "hello" --pretty
+  cog core schema demo.md --pretty
+  cog core promote demo.md
+  cog core promote demo.md ./cognitive/modules/demo
+
   # Search and discover modules
   cog search code review           # Search by keywords
   cog search                       # List all available modules
@@ -910,6 +1095,9 @@ ENVIRONMENT:
   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
 `);
 }
 main().catch(e => {

package/dist/commands/add.js

@@ -18,6 +18,7 @@ import { homedir, tmpdir } from 'node:os';
 import { createHash } from 'node:crypto';
 import { RegistryClient } from '../registry/client.js';
 import { extractTarGzFile } from '../registry/tar.js';
+import { PROVENANCE_SPEC, computeModuleIntegrity, writeModuleProvenance } from '../provenance.js';
 // Module storage paths
 const USER_MODULES_DIR = join(homedir(), '.cognitive', 'modules');
 const INSTALLED_MANIFEST = join(homedir(), '.cognitive', 'installed.json');
@@ -340,9 +341,13 @@ function parseModuleSpec(spec) {
 export async function addFromRegistry(moduleSpec, ctx, options = {}) {
     const { name: moduleName, version: requestedVersion } = parseModuleSpec(moduleSpec);
     const { name: customName, registry: registryUrl } = options;
+    const policy = ctx.policy;
     let tempDir;
     try {
-        const client = new RegistryClient(registryUrl);
+        const client = new RegistryClient(registryUrl, {
+            timeoutMs: ctx.registryTimeoutMs,
+            maxBytes: ctx.registryMaxBytes,
+        });
         const moduleInfo = await client.getModule(moduleName);
         if (!moduleInfo) {
             return {
@@ -357,6 +362,14 @@ export async function addFromRegistry(moduleSpec, ctx, options = {}) {
         // Get download info
         const downloadInfo = await client.getDownloadUrl(moduleName);
         if (downloadInfo.isGitHub && downloadInfo.githubInfo) {
+            if (policy?.profile === 'certified') {
+                return {
+                    success: false,
+                    error: `Certified profile requires registry tarball provenance.\n` +
+                        `Registry entry for '${moduleName}' resolves to a GitHub source, which is not allowed in --profile certified.\n` +
+                        `Use a tarball-based registry entry (distribution.tarball + checksum), or run with --profile strict/default.`,
+                };
+            }
             const { org, repo, path, ref } = downloadInfo.githubInfo;
             // Use addFromGitHub() directly (not add() to avoid recursion)
             const result = await addFromGitHub(`${org}/${repo}`, ctx, {
@@ -458,6 +471,35 @@ export async function addFromRegistry(moduleSpec, ctx, options = {}) {
         await mkdir(USER_MODULES_DIR, { recursive: true });
         copyDir(sourcePath, targetPath);
         const version = await getModuleVersion(sourcePath);
+        // Write provenance + integrity (enables certified profile gating).
+        try {
+            const integrity = await computeModuleIntegrity(targetPath);
+            await writeModuleProvenance(targetPath, {
+                spec: PROVENANCE_SPEC,
+                createdAt: new Date().toISOString(),
+                source: {
+                    type: 'registry',
+                    registryUrl: registryUrl ?? null,
+                    moduleName,
+                    requestedVersion: requestedVersion ?? null,
+                    resolvedVersion: version ?? null,
+                    tarballUrl: downloadInfo.url,
+                    checksum: downloadInfo.checksum,
+                    sha256: actualSha256,
+                    quality: {
+                        // moduleInfo is typed loosely (v1/v2); best-effort extract for v2.
+                        verified: moduleInfo?.quality?.verified,
+                        conformance_level: moduleInfo?.quality?.conformance_level,
+                        spec_version: moduleInfo?.identity?.spec_version,
+                    },
+                },
+                integrity,
+            });
+        }
+        catch (e) {
+            // If provenance fails, keep install but warn loudly (non-certified users can still run).
+            console.error(`Warning: failed to write provenance for ${safeInstallName}: ${e.message}`);
+        }
         await recordInstall(safeInstallName, {
             source: downloadInfo.url,
             githubUrl: downloadInfo.url,
@@ -502,6 +544,14 @@ export async function addFromRegistry(moduleSpec, ctx, options = {}) {
 export async function addFromGitHub(url, ctx, options = {}) {
     const { org, repo, fullUrl } = parseGitHubUrl(url);
     const { module: modulePath, name, branch = 'main', tag } = options;
+    const policy = ctx.policy;
+    if (policy?.profile === 'certified') {
+        return {
+            success: false,
+            error: `Certified profile requires registry tarball provenance; GitHub installs are not allowed.\n` +
+                `Use 'cog add <module>' against a tarball-based registry entry, or run with --profile strict/default.`,
+        };
+    }
     // Determine ref (tag takes priority)
     const ref = tag || branch;
     const isTag = !!tag;
@@ -546,6 +596,19 @@ export async function addFromGitHub(url, ctx, options = {}) {
             installedAt: targetPath,
             installedTime: new Date().toISOString(),
         });
+        // Best-effort provenance for non-certified installs (useful for audit/debug).
+        try {
+            const integrity = await computeModuleIntegrity(targetPath);
+            await writeModuleProvenance(targetPath, {
+                spec: PROVENANCE_SPEC,
+                createdAt: new Date().toISOString(),
+                source: { type: 'github', repoUrl: fullUrl, ref, modulePath: modulePath ?? null },
+                integrity,
+            });
+        }
+        catch {
+            // ignore
+        }
         // Cleanup temp directory
         const tempDir = dirname(repoRoot);
         if (tempDir && tempDir !== '/' && tempDir !== '.' && tempDir !== USER_MODULES_DIR) {
@@ -585,6 +648,10 @@ export async function addFromGitHub(url, ctx, options = {}) {
  * Add a module from GitHub or Registry (auto-detect source)
  */
 export async function add(source, ctx, options = {}) {
+    // Allow a global registry override via ctx.registryUrl unless explicitly set.
+    if (!options.registry && ctx.registryUrl) {
+        options = { ...options, registry: ctx.registryUrl };
+    }
     // Determine source type
     if (isGitHubSource(source)) {
         return addFromGitHub(source, ctx, options);

package/dist/commands/compose.d.ts

@@ -13,6 +13,8 @@ export interface ComposeOptions {
     args?: string;
     /** JSON input data */
     input?: string;
+    /** Disable validation */
+    noValidate?: boolean;
     /** Maximum composition depth */
     maxDepth?: number;
     /** Timeout in milliseconds */

package/dist/commands/compose.js

@@ -9,6 +9,7 @@
  */
 import { findModule, getDefaultSearchPaths, executeComposition } from '../modules/index.js';
 import { ErrorCodes, attachContext, makeErrorEnvelope } from '../errors/index.js';
+import { writeAuditRecord } from '../audit.js';
 function looksLikeCode(str) {
     const codeIndicators = [
         /^(def|function|class|const|let|var|import|export|public|private)\s/,
@@ -34,7 +35,19 @@ export async function compose(moduleName, ctx, options = {}) {
             data: errorEnvelope,
         };
     }
+    if (ctx.policy?.requireV22) {
+        if (module.formatVersion !== 'v2.2') {
+            const errorEnvelope = attachContext(makeErrorEnvelope({
+                code: ErrorCodes.INVALID_INPUT,
+                message: `Certified profile requires v2.2 modules; got: ${module.formatVersion ?? 'unknown'} (${module.format})`,
+                suggestion: "Migrate the module to v2.2, or run with `--profile strict` / `--profile default`",
+            }), { module: moduleName, provider: ctx.provider.name });
+            return { success: false, error: errorEnvelope.error.message, data: errorEnvelope };
+        }
+    }
     try {
+        const policy = ctx.policy;
+        const startedAt = Date.now();
         // Parse input if provided as JSON
         let inputData = {};
         if (options.input) {
@@ -67,7 +80,31 @@ export async function compose(moduleName, ctx, options = {}) {
         const result = await executeComposition(moduleName, inputData, ctx.provider, {
             cwd: ctx.cwd,
             maxDepth: options.maxDepth,
-            timeoutMs: options.timeout
+            timeoutMs: options.timeout,
+            policy,
+            validateInput: (() => {
+                if (options.noValidate)
+                    return false;
+                if (!policy)
+                    return true;
+                if (policy.validate === 'off')
+                    return false;
+                if (policy.validate === 'on')
+                    return true;
+                return policy.profile !== 'core';
+            })(),
+            validateOutput: (() => {
+                if (options.noValidate)
+                    return false;
+                if (!policy)
+                    return true;
+                if (policy.validate === 'off')
+                    return false;
+                if (policy.validate === 'on')
+                    return true;
+                return policy.profile !== 'core';
+            })(),
+            enableRepair: policy?.enableRepair ?? true,
         });
         if (options.verbose) {
             console.error('--- Composition Trace ---');
@@ -98,6 +135,28 @@ export async function compose(moduleName, ctx, options = {}) {
                 data: errorEnvelope,
             };
         }
+        if (policy?.audit) {
+            const rec = await writeAuditRecord({
+                ts: new Date().toISOString(),
+                kind: 'compose',
+                policy,
+                provider: ctx.provider.name,
+                module: { name: module.name, version: module.version, location: module.location, formatVersion: module.formatVersion },
+                input: inputData,
+                result: {
+                    ok: result.ok,
+                    result: result.result,
+                    moduleResults: result.moduleResults,
+                    trace: result.trace,
+                    totalTimeMs: result.totalTimeMs,
+                    error: result.error,
+                },
+                notes: [`duration_ms=${Date.now() - startedAt}`],
+            });
+            if (rec) {
+                console.error(`Audit: ${rec.path}`);
+            }
+        }
         // Return result
         if (options.trace) {
             // Include full result with trace