cognitive-modules-cli 2.2.10 → 2.2.12

package/dist/policy-summary.d.ts

@@ -0,0 +1,16 @@
+import type { ExecutionPolicy, JsonSchemaMode, StructuredOutputPreference } from './types.js';
+export type EffectiveValidation = {
+    validateInput: boolean;
+    validateOutput: boolean;
+    reason?: string | null;
+};
+export type EffectiveStructured = {
+    requested: StructuredOutputPreference;
+    applied: JsonSchemaMode | 'off';
+    reason?: string | null;
+};
+export declare function compactReason(reason: string | null | undefined, maxLen?: number): string | null;
+export declare function formatPolicySummaryLine(policy: ExecutionPolicy, effectiveValidation: EffectiveValidation, effectiveStructured: EffectiveStructured, extras?: {
+    enableRepair?: boolean;
+    requireV22?: boolean;
+}): string;

package/dist/policy-summary.js

@@ -0,0 +1,33 @@
+function oneLine(s) {
+    return s.replace(/\s+/g, ' ').trim();
+}
+export function compactReason(reason, maxLen = 90) {
+    if (!reason)
+        return null;
+    const s = oneLine(reason);
+    if (s.length <= maxLen)
+        return s;
+    return `${s.slice(0, Math.max(0, maxLen - 1))}…`;
+}
+function fmtOnOff(v) {
+    return v ? 'on' : 'off';
+}
+export function formatPolicySummaryLine(policy, effectiveValidation, effectiveStructured, extras) {
+    const validateMode = policy.validate;
+    const vReason = compactReason(effectiveValidation.reason ?? null);
+    const sReason = compactReason(effectiveStructured.reason ?? null);
+    const parts = [];
+    parts.push(`profile=${policy.profile}`);
+    parts.push(`validate=${validateMode}(in:${fmtOnOff(effectiveValidation.validateInput)} out:${fmtOnOff(effectiveValidation.validateOutput)})`);
+    if (vReason)
+        parts.push(`validate_reason="${vReason}"`);
+    const structuredArrow = effectiveStructured.requested === 'auto' ? '->' : ':';
+    parts.push(`structured=${effectiveStructured.requested}${structuredArrow}${effectiveStructured.applied}`);
+    if (sReason)
+        parts.push(`structured_reason="${sReason}"`);
+    parts.push(`audit=${fmtOnOff(Boolean(policy.audit))}`);
+    if (typeof extras?.enableRepair === 'boolean')
+        parts.push(`repair=${fmtOnOff(extras.enableRepair)}`);
+    parts.push(`requireV22=${fmtOnOff(Boolean(extras?.requireV22 ?? policy.requireV22))}`);
+    return `Policy: ${parts.join(' | ')}`;
+}

package/dist/profile.d.ts

@@ -4,5 +4,6 @@ export interface ResolvePolicyInput {
     validate?: string | null;
     noValidate?: boolean;
     audit?: boolean;
+    structured?: string | null;
 }
 export declare function resolveExecutionPolicy(input: ResolvePolicyInput): ExecutionPolicy;

package/dist/profile.js

@@ -1,14 +1,14 @@
-function normalizeProfile(raw) {
+function parseProfile(raw) {
     const v = (raw ?? '').trim().toLowerCase();
     if (v === 'core')
-        return 'core';
-    if (v === 'default' || v === '')
-        return 'default';
-    if (v === 'strict')
-        return 'strict';
+        return { profile: 'core' };
+    if (v === 'standard' || v === '' || v === 'default')
+        return { profile: 'standard' };
     if (v === 'certified' || v === 'cert')
-        return 'certified';
-    throw new Error(`Invalid --profile: ${raw}. Expected one of: core|default|strict|certified`);
+        return { profile: 'certified' };
+    if (v === 'strict')
+        return { profile: 'standard', legacyPreset: 'strict' }; // deprecated alias
+    throw new Error(`Invalid --profile: ${raw}. Expected one of: core|standard|certified`);
 }
 function normalizeValidate(raw) {
     const v = (raw ?? '').trim().toLowerCase();
@@ -20,24 +20,42 @@ function normalizeValidate(raw) {
         return 'off';
     throw new Error(`Invalid --validate: ${raw}. Expected one of: auto|on|off`);
 }
+function normalizeStructured(raw) {
+    const v = (raw ?? '').trim().toLowerCase();
+    if (v === '' || v === 'auto')
+        return 'auto';
+    if (v === 'off' || v === 'none' || v === 'false' || v === '0')
+        return 'off';
+    if (v === 'prompt')
+        return 'prompt';
+    if (v === 'native')
+        return 'native';
+    throw new Error(`Invalid --structured: ${raw}. Expected one of: auto|off|prompt|native`);
+}
 export function resolveExecutionPolicy(input) {
-    const profile = normalizeProfile(input.profile);
+    const { profile, legacyPreset } = parseProfile(input.profile);
     // Base defaults per profile.
-    let validate = profile === 'core' ? 'off' : 'on';
+    // standard: auto validation chooses based on module tier/strictness in the runner
+    let validate = profile === 'core' ? 'off' : 'auto';
     let audit = false;
     let enableRepair = true;
     let requireV22 = false;
-    if (profile === 'strict') {
-        validate = 'on';
-        audit = false;
-        enableRepair = true;
-        requireV22 = false;
-    }
+    let structured = 'auto';
     if (profile === 'certified') {
         validate = 'on';
         audit = true;
         enableRepair = false; // certification prefers fail-fast over runtime repair
         requireV22 = true;
+        structured = 'auto';
+    }
+    // Legacy preset: strict = validate on, no audit, keep repair on, do not require v2.2.
+    // This keeps backward compatibility while presenting only core/standard/certified externally.
+    if (legacyPreset === 'strict') {
+        validate = 'on';
+        audit = false;
+        enableRepair = true;
+        requireV22 = false;
+        structured = 'auto';
     }
     // CLI overrides.
     const validateExplicit = input.validate != null || Boolean(input.noValidate);
@@ -50,10 +68,13 @@ export function resolveExecutionPolicy(input) {
     if (typeof input.audit === 'boolean') {
         audit = input.audit;
     }
+    if (input.structured != null) {
+        structured = normalizeStructured(input.structured);
+    }
     // Trigger rule: if audit is enabled and validate wasn't explicitly turned off,
     // force validation on (auditing without validation is usually not meaningful).
     if (audit && !(validateExplicit && validate === 'off')) {
         validate = 'on';
     }
-    return { profile, validate, audit, enableRepair, requireV22 };
+    return { profile, validate, audit, enableRepair, structured, requireV22 };
 }

package/dist/providers/base.d.ts

@@ -1,11 +1,12 @@
 /**
  * Base Provider - Abstract class for all LLM providers
  */
-import type { Provider, InvokeParams, InvokeResult } from '../types.js';
+import type { Provider, InvokeParams, InvokeResult, ProviderCapabilities } from '../types.js';
 export declare abstract class BaseProvider implements Provider {
     abstract name: string;
     abstract invoke(params: InvokeParams): Promise<InvokeResult>;
     abstract isConfigured(): boolean;
+    getCapabilities(): ProviderCapabilities;
     /**
      * Check if this provider supports streaming.
      * Override in subclasses that implement streaming.

package/dist/providers/base.js

@@ -2,6 +2,12 @@
  * Base Provider - Abstract class for all LLM providers
  */
 export class BaseProvider {
+    getCapabilities() {
+        return {
+            structuredOutput: 'prompt',
+            streaming: this.supportsStreaming(),
+        };
+    }
     /**
      * Check if this provider supports streaming.
      * Override in subclasses that implement streaming.

package/dist/providers/gemini.d.ts

@@ -16,6 +16,11 @@ export declare class GeminiProvider extends BaseProvider {
      * Gemini supports streaming.
      */
     supportsStreaming(): boolean;
+    getCapabilities(): {
+        structuredOutput: "native";
+        streaming: boolean;
+        nativeSchemaDialect: "gemini-responseSchema";
+    };
     /**
      * Clean JSON Schema for Gemini API compatibility
      * Removes unsupported fields like additionalProperties

package/dist/providers/gemini.js

@@ -23,6 +23,16 @@ export class GeminiProvider extends BaseProvider {
     supportsStreaming() {
         return true;
     }
+    getCapabilities() {
+        // Gemini has a native response schema surface (generationConfig.responseSchema),
+        // but it is NOT JSON Schema. The runner will treat this as "native but non-JSON-schema"
+        // and will safely downgrade to prompt-guided JSON unless/ until a real dialect mapping exists.
+        return {
+            structuredOutput: 'native',
+            streaming: true,
+            nativeSchemaDialect: 'gemini-responseSchema',
+        };
+    }
     /**
      * Clean JSON Schema for Gemini API compatibility
      * Removes unsupported fields like additionalProperties
@@ -36,10 +46,36 @@ export class GeminiProvider extends BaseProvider {
             if (obj && typeof obj === 'object') {
                 const result = {};
                 for (const [key, value] of Object.entries(obj)) {
-                    // Gemini's responseSchema does not accept JSON-Schema `const`.
-                    // Convert `{ const: X }` into `{ enum: [X] }` for compatibility.
+                    // Gemini's responseSchema has a restricted schema subset.
+                    // In particular:
+                    // - `const` is not supported
+                    // - `enum` values appear to be string-only in the API surface
                     if (key === 'const') {
-                        result.enum = [clean(value)];
+                        // Preserve type info as best-effort but drop the exact-value constraint.
+                        // (Core runtime will still validate/repair the envelope.)
+                        if (value === null) {
+                            // Leave unconstrained; null typing is not consistently supported.
+                        }
+                        else if (typeof value === 'boolean') {
+                            result.type = 'boolean';
+                        }
+                        else if (typeof value === 'number') {
+                            result.type = 'number';
+                        }
+                        else if (typeof value === 'string') {
+                            result.type = 'string';
+                            // String enums are supported, so we can keep a single-value constraint.
+                            result.enum = [value];
+                        }
+                        continue;
+                    }
+                    if (key === 'enum') {
+                        if (Array.isArray(value) && value.every((v) => typeof v === 'string')) {
+                            result.enum = value.map((v) => v);
+                        }
+                        else {
+                            // Drop non-string enums for Gemini compatibility.
+                        }
                         continue;
                     }
                     if (!unsupportedFields.includes(key)) {
@@ -56,15 +92,29 @@ export class GeminiProvider extends BaseProvider {
      * Build request body for Gemini API
      */
     buildRequestBody(params) {
+        // If the caller wants schema guidance but not native enforcement, inject the schema into the prompt.
+        // (Gemini's native responseSchema supports only a restricted schema subset and can reject valid JSON Schema.)
+        const mode = params.jsonSchemaMode ?? (params.jsonSchema ? 'prompt' : undefined);
+        let messages = params.messages;
+        if (params.jsonSchema && mode === 'prompt') {
+            const lastUserIdx = messages.findLastIndex(m => m.role === 'user');
+            if (lastUserIdx >= 0) {
+                messages = [...messages];
+                messages[lastUserIdx] = {
+                    ...messages[lastUserIdx],
+                    content: messages[lastUserIdx].content + this.buildJsonPrompt(params.jsonSchema),
+                };
+            }
+        }
         // Convert messages to Gemini format
-        const contents = params.messages
+        const contents = messages
             .filter(m => m.role !== 'system')
             .map(m => ({
             role: m.role === 'assistant' ? 'model' : 'user',
             parts: [{ text: m.content }]
         }));
         // Add system instruction if present
-        const systemMessage = params.messages.find(m => m.role === 'system');
+        const systemMessage = messages.find(m => m.role === 'system');
         const body = {
             contents,
             generationConfig: {
@@ -75,8 +125,8 @@ export class GeminiProvider extends BaseProvider {
         if (systemMessage) {
             body.systemInstruction = { parts: [{ text: systemMessage.content }] };
         }
-        // Add JSON schema constraint if provided
-        if (params.jsonSchema) {
+        // Add JSON schema constraint if provided and caller requested native mode.
+        if (params.jsonSchema && mode === 'native') {
             const cleanedSchema = this.cleanSchemaForGemini(params.jsonSchema);
             body.generationConfig = {
                 ...body.generationConfig,

package/dist/providers/index.d.ts

@@ -1,7 +1,11 @@
 /**
  * Provider Registry
+ *
+ * Publish-grade note:
+ * Providers expose a small capability surface (structured output, streaming).
+ * The runner uses this to decide whether to pass native schemas or prompt-only guidance.
  */
-import type { Provider } from '../types.js';
+import type { Provider, StructuredOutputMode } from '../types.js';
 export { BaseProvider } from './base.js';
 export { GeminiProvider } from './gemini.js';
 export { OpenAIProvider } from './openai.js';
@@ -16,4 +20,9 @@ export declare function listProviders(): Array<{
     name: string;
     configured: boolean;
     model: string;
+    structuredOutput: StructuredOutputMode;
+    structuredJsonSchema: Exclude<StructuredOutputMode, 'native'> | 'native';
+    nativeSchemaDialect?: string;
+    maxNativeSchemaBytes?: number;
+    streaming: boolean;
 }>;

package/dist/providers/index.js

@@ -1,5 +1,9 @@
 /**
  * Provider Registry
+ *
+ * Publish-grade note:
+ * Providers expose a small capability surface (structured output, streaming).
+ * The runner uses this to decide whether to pass native schemas or prompt-only guidance.
  */
 import { GeminiProvider } from './gemini.js';
 import { OpenAIProvider } from './openai.js';
@@ -60,15 +64,37 @@ export function getProvider(name, model) {
     }
     return factory(modelOverride);
 }
+function safeCapabilities(p) {
+    const caps = p.getCapabilities?.();
+    if (caps)
+        return caps;
+    return { structuredOutput: 'prompt', streaming: p.supportsStreaming?.() ?? false };
+}
+function providerRow(name, configured, model, make) {
+    const caps = safeCapabilities(make());
+    const structuredJsonSchema = caps.structuredOutput === 'native' && (caps.nativeSchemaDialect ?? 'json-schema') !== 'json-schema'
+        ? 'prompt'
+        : caps.structuredOutput;
+    return {
+        name,
+        configured,
+        model,
+        structuredOutput: caps.structuredOutput,
+        structuredJsonSchema,
+        nativeSchemaDialect: caps.nativeSchemaDialect,
+        maxNativeSchemaBytes: caps.maxNativeSchemaBytes,
+        streaming: caps.streaming,
+    };
+}
 export function listProviders() {
     return [
-        { name: 'gemini', configured: !!process.env.GEMINI_API_KEY, model: 'gemini-3-flash' },
-        { name: 'openai', configured: !!process.env.OPENAI_API_KEY, model: 'gpt-5.2' },
-        { name: 'anthropic', configured: !!process.env.ANTHROPIC_API_KEY, model: 'claude-sonnet-4.5' },
-        { name: 'deepseek', configured: !!process.env.DEEPSEEK_API_KEY, model: 'deepseek-v3.2' },
-        { name: 'minimax', configured: !!process.env.MINIMAX_API_KEY, model: 'MiniMax-M2.1' },
-        { name: 'moonshot', configured: !!process.env.MOONSHOT_API_KEY, model: 'kimi-k2.5' },
-        { name: 'qwen', configured: !!(process.env.DASHSCOPE_API_KEY || process.env.QWEN_API_KEY), model: 'qwen3-max' },
-        { name: 'ollama', configured: true, model: 'llama4 (local)' },
+        providerRow('gemini', !!process.env.GEMINI_API_KEY, 'gemini-3-flash', () => 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()),
     ];
 }

package/dist/providers/moonshot.d.ts

@@ -10,5 +10,8 @@ export declare class MoonshotProvider extends BaseProvider {
     private baseUrl;
     constructor(apiKey?: string, model?: string);
     isConfigured(): boolean;
+    private buildRequestBody;
+    private parseRequiredTemperature;
+    private fetchOnce;
     invoke(params: InvokeParams): Promise<InvokeResult>;
 }

package/dist/providers/moonshot.js

@@ -15,31 +15,56 @@ export class MoonshotProvider extends BaseProvider {
     isConfigured() {
         return !!this.apiKey;
     }
-    async invoke(params) {
-        if (!this.isConfigured()) {
-            throw new Error('Moonshot API key not configured. Set MOONSHOT_API_KEY environment variable.');
-        }
-        const url = `${this.baseUrl}/chat/completions`;
+    buildRequestBody(params, overrides) {
+        // Moonshot (Kimi) model-specific constraints:
+        // - Some Kimi models reject arbitrary temperatures (e.g. `kimi-k2.5` only allows 1).
+        const model = this.model;
+        let temperature = overrides?.temperature ?? params.temperature ?? 0.7;
+        if (model === 'kimi-k2.5')
+            temperature = 1;
         const body = {
-            model: this.model,
-            messages: params.messages.map(m => ({ role: m.role, content: m.content })),
-            temperature: params.temperature ?? 0.7,
+            model,
+            messages: params.messages.map((m) => ({ role: m.role, content: m.content })),
+            temperature,
             max_tokens: params.maxTokens ?? 4096,
         };
         // Add JSON mode if schema provided
         if (params.jsonSchema) {
             body.response_format = { type: 'json_object' };
-            const lastUserIdx = params.messages.findLastIndex(m => m.role === 'user');
+            const lastUserIdx = params.messages.findLastIndex((m) => m.role === 'user');
             if (lastUserIdx >= 0) {
                 const messages = [...params.messages];
                 messages[lastUserIdx] = {
                     ...messages[lastUserIdx],
                     content: messages[lastUserIdx].content + this.buildJsonPrompt(params.jsonSchema),
                 };
-                body.messages = messages.map(m => ({ role: m.role, content: m.content }));
+                body.messages = messages.map((m) => ({ role: m.role, content: m.content }));
             }
         }
-        const response = await fetch(url, {
+        return body;
+    }
+    parseRequiredTemperature(errorText) {
+        const s = String(errorText ?? '');
+        // Example: {"error":{"message":"invalid temperature: only 1 is allowed for this model","type":"invalid_request_error"}}
+        // Also tolerate plain text.
+        const m = s.match(/invalid temperature[^0-9]*only\s+([0-9]+(?:\.[0-9]+)?)\s+is allowed/i);
+        if (m?.[1]) {
+            const n = Number(m[1]);
+            if (Number.isFinite(n))
+                return n;
+        }
+        // Some variants omit "only" but still contain a single allowed value.
+        const m2 = s.match(/invalid temperature[^0-9]*([0-9]+(?:\.[0-9]+)?)\s+is allowed/i);
+        if (m2?.[1]) {
+            const n = Number(m2[1]);
+            if (Number.isFinite(n))
+                return n;
+        }
+        return null;
+    }
+    async fetchOnce(body) {
+        const url = `${this.baseUrl}/chat/completions`;
+        return await fetch(url, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/json',
@@ -47,9 +72,29 @@ export class MoonshotProvider extends BaseProvider {
             },
             body: JSON.stringify(body),
         });
+    }
+    async invoke(params) {
+        if (!this.isConfigured()) {
+            throw new Error('Moonshot API key not configured. Set MOONSHOT_API_KEY environment variable.');
+        }
+        // Moonshot is strict about some generation params for certain models.
+        // Keep UX stable: if we hit a known parameter-compat error, retry once with a safer value.
+        const initialBody = this.buildRequestBody(params);
+        let response = await this.fetchOnce(initialBody);
         if (!response.ok) {
-            const error = await response.text();
-            throw new Error(`Moonshot API error: ${response.status} - ${error}`);
+            const errorText = await response.text();
+            const requiredTemp = this.parseRequiredTemperature(errorText);
+            if (response.status === 400 && requiredTemp !== null) {
+                const retryBody = this.buildRequestBody(params, { temperature: requiredTemp });
+                response = await this.fetchOnce(retryBody);
+                if (!response.ok) {
+                    const retryError = await response.text();
+                    throw new Error(`Moonshot API error: ${response.status} - ${retryError}`);
+                }
+            }
+            else {
+                throw new Error(`Moonshot API error: ${response.status} - ${errorText}`);
+            }
         }
         const data = await response.json();
         const content = data.choices?.[0]?.message?.content || '';

package/dist/registry/assets.d.ts

@@ -39,9 +39,17 @@ export interface RegistryVerifyResult {
     checked: number;
     passed: number;
     failed: number;
+    /**
+     * Failure diagnostics (best-effort).
+     *
+     * This structure is intentionally extensible. Consumers should treat unknown keys as optional.
+     */
     failures: Array<{
         module: string;
         reason: string;
+        phase?: 'entry' | 'download' | 'size' | 'checksum' | 'extract' | 'files' | 'identity';
+        tarball_ref?: string;
+        tarball_resolved?: string;
     }>;
 }
 export declare function buildRegistryAssets(opts: BuildRegistryOptions): Promise<RegistryBuildResult>;

package/dist/registry/assets.js

@@ -24,6 +24,21 @@ function tarballFileName(tarballRef) {
     }
     return path.basename(tarballRef);
 }
+function resolveRemoteUrl(indexUrl, ref) {
+    if (isHttpUrl(ref))
+        return ref;
+    // Allow relative tarball refs in remote indexes for portability.
+    // Example:
+    // - index: https://host/registry.json
+    // - tarball: demo-1.0.0.tar.gz
+    // resolves to https://host/demo-1.0.0.tar.gz
+    try {
+        return new URL(ref, indexUrl).toString();
+    }
+    catch {
+        return ref;
+    }
+}
 async function fetchTextWithLimit(url, maxBytes, timeoutMs) {
     const controller = new AbortController();
     const t = setTimeout(() => controller.abort(), timeoutMs);
@@ -578,8 +593,9 @@ export async function verifyRegistryAssets(opts) {
     const concurrency = Math.max(1, Math.min(8, Math.floor(desiredConcurrency)));
     const localTarPath = async (moduleName, tarballRef) => {
         const fileName = tarballFileName(tarballRef);
-        // Avoid collisions when we download into a temp dir (remote verify).
-        if (wantRemote && tmpAssetsRoot && !opts.assetsDir) {
+        // Avoid collisions on remote verify (query strings can produce identical basenames).
+        // Even when the caller provides --assets-dir, we isolate per module to keep verification correct.
+        if (wantRemote) {
             const p = path.join(assetsDir, moduleName, fileName);
             await fs.mkdir(path.dirname(p), { recursive: true });
             return p;
@@ -589,24 +605,30 @@ export async function verifyRegistryAssets(opts) {
     const verifyOne = async (moduleName, entry) => {
         checked += 1;
         let tarPathForCleanup = null;
+        let phase = 'entry';
         try {
             const dist = entry.distribution ?? {};
-            const tarballUrl = String(dist.tarball ?? '');
+            const tarballRef = String(dist.tarball ?? '');
             const checksum = String(dist.checksum ?? '');
-            const sizeBytes = Number(dist.size_bytes ?? NaN);
+            const sizeBytesRaw = dist.size_bytes;
+            const expectedSizeBytes = Number.isFinite(Number(sizeBytesRaw)) ? Number(sizeBytesRaw) : null;
             const expectedFiles = Array.isArray(dist.files) ? dist.files.map(String) : [];
-            if (!tarballUrl)
+            if (!tarballRef)
                 throw new Error('Missing distribution.tarball');
+            const tarballUrl = wantRemote ? resolveRemoteUrl(opts.registryIndexPath, tarballRef) : tarballRef;
             const tarPath = await localTarPath(moduleName, tarballUrl);
             tarPathForCleanup = tarPath;
             if (wantRemote) {
                 if (!isHttpUrl(tarballUrl)) {
-                    throw new Error(`Remote verify requires http(s) tarball URL, got: ${tarballUrl}`);
+                    throw new Error(`Remote verify requires http(s) tarball URL (or a relative URL), got: ${tarballRef}`);
                 }
+                phase = 'download';
                 const downloaded = await downloadToFileWithSha256(tarballUrl, tarPath, maxTarballBytes, fetchTimeoutMs);
-                if (Number.isFinite(sizeBytes) && downloaded.sizeBytes !== sizeBytes) {
-                    throw new Error(`Size mismatch: expected ${sizeBytes}, got ${downloaded.sizeBytes}`);
+                phase = 'size';
+                if (expectedSizeBytes !== null && downloaded.sizeBytes !== expectedSizeBytes) {
+                    throw new Error(`Size mismatch: expected ${expectedSizeBytes}, got ${downloaded.sizeBytes}`);
                 }
+                phase = 'checksum';
                 const m = checksum.match(/^sha256:([a-f0-9]{64})$/);
                 if (!m)
                     throw new Error(`Unsupported checksum format: ${checksum}`);
@@ -615,11 +637,12 @@ export async function verifyRegistryAssets(opts) {
                     throw new Error(`Checksum mismatch: expected ${expectedSha}, got ${downloaded.sha256}`);
                 }
             }
+            phase = 'size';
             const st = await fs.stat(tarPath);
-            if (!Number.isFinite(sizeBytes))
-                throw new Error('Missing distribution.size_bytes');
-            if (st.size !== sizeBytes)
-                throw new Error(`Size mismatch: expected ${sizeBytes}, got ${st.size}`);
+            if (expectedSizeBytes !== null && st.size !== expectedSizeBytes) {
+                throw new Error(`Size mismatch: expected ${expectedSizeBytes}, got ${st.size}`);
+            }
+            phase = 'checksum';
             const m = checksum.match(/^sha256:([a-f0-9]{64})$/);
             if (!m)
                 throw new Error(`Unsupported checksum format: ${checksum}`);
@@ -630,6 +653,7 @@ export async function verifyRegistryAssets(opts) {
             // Extract and validate contents (layout + file list).
             const tmp = await fs.mkdtemp(path.join(tmpdir(), 'cog-reg-verify-'));
             try {
+                phase = 'extract';
                 const extractedRoot = path.join(tmp, 'pkg');
                 await fs.mkdir(extractedRoot, { recursive: true });
                 await extractTarGzFile(tarPath, extractedRoot, {
@@ -651,6 +675,7 @@ export async function verifyRegistryAssets(opts) {
                     throw new Error('Root directory is not a valid module');
                 }
                 if (expectedFiles.length > 0) {
+                    phase = 'files';
                     const actualFiles = await listFiles(moduleDir);
                     const exp = expectedFiles.slice().sort();
                     const act = actualFiles.slice().sort();
@@ -664,6 +689,7 @@ export async function verifyRegistryAssets(opts) {
                 }
                 // Basic identity check: module.yaml version matches registry identity.version
                 try {
+                    phase = 'identity';
                     const y = await readModuleMeta(path.join(moduleDir, 'module.yaml'));
                     const identityVersion = String(entry.identity?.version ?? '').trim();
                     if (identityVersion && y.version !== identityVersion) {
@@ -684,7 +710,16 @@ export async function verifyRegistryAssets(opts) {
             passed += 1;
         }
         catch (e) {
-            failures.push({ module: moduleName, reason: e instanceof Error ? e.message : String(e) });
+            const dist = entry?.distribution ?? {};
+            const tarball_ref = typeof dist.tarball === 'string' ? dist.tarball : undefined;
+            const tarball_resolved = tarball_ref && wantRemote ? resolveRemoteUrl(opts.registryIndexPath, tarball_ref) : tarball_ref;
+            failures.push({
+                module: moduleName,
+                reason: e instanceof Error ? e.message : String(e),
+                phase: (typeof phase === 'string' ? phase : undefined),
+                tarball_ref,
+                tarball_resolved,
+            });
         }
         finally {
             // If we downloaded tarballs into a temp dir, keep disk usage bounded.