@gobing-ai/knowledge-kit 0.0.29 → 0.0.30

package/plugins/generations/episode-plan-gen/src/index.ts

@@ -635,6 +635,8 @@ export interface FilterConfig {
     minImportance: number;
     minUrgency: number;
     minImpact: number;
+    /** Episode floor: when fewer docs survive, importance-only rejects backfill up to this count. */
+    minEpisodeItems: number;
 }
 
 /** A doc the filter dropped, with every failed check (`category:not-in-allowlist`, `quality:2<3`, …). */
@@ -659,6 +661,13 @@ export const DEFAULT_FILTER_CONFIG: FilterConfig = {
     minImportance: 3,
     minUrgency: 2,
     minImpact: 1,
+    // 20261002 dogfood: a weak, policy-heavy day collapsed the episode to 2 spoken items
+    // (~5 min audio) because importance (source-tier base) is the first dimension a tail-source
+    // day fails. Backfill admits importance-only rejects — quality/urgency/impact/category
+    // minimums stay hard — so a thin news day deepens instead of shipping a stub. Floor is 8,
+    // not 6: the prompt-layer 选题边界 (script-write) drops policy items AFTER this gate (today
+    // 2 of 5), so the floor compensates upstream to land ~4-6 spoken items on a thin day.
+    minEpisodeItems: 8,
 };
 
 /** One QC_MIN_* threshold: an integer 0–5 or absent (→ fallback); anything else fails loud — never clamped. */
@@ -671,6 +680,17 @@ function parseFilterThreshold(raw: string | undefined, name: string, fallback: n
     return parsed;
 }
 
+/** QC_MIN_EPISODE_ITEMS: a positive integer count or absent (→ fallback); anything else fails loud. */
+function parseFloorCount(raw: string | undefined, name: string, fallback: number): number {
+    if (raw === undefined || raw.trim() === '') return fallback;
+    const value = raw.trim();
+    if (!/^\d+$/.test(value)) throw new Error(`${name}='${raw}' is not a positive integer (fail loud, no clamping)`);
+    const parsed = Number.parseInt(value, 10);
+    if (parsed < 1)
+        throw new Error(`${name}=${parsed} must be >= 1 (a 0 floor disables the gate — drop the env instead)`);
+    return parsed;
+}
+
 /** QC_CATEGORIES: a comma list of MECE categories; unknown entries fail loud (no silent drops). */
 function parseFilterCategories(raw: string | undefined): Category[] {
     if (raw === undefined || raw.trim() === '') return [...DEFAULT_FILTER_CONFIG.categories];
@@ -697,6 +717,11 @@ export function filterConfigFromEnv(env: Record<string, string | undefined> = pr
         ),
         minUrgency: parseFilterThreshold(env.QC_MIN_URGENCY, 'QC_MIN_URGENCY', DEFAULT_FILTER_CONFIG.minUrgency),
         minImpact: parseFilterThreshold(env.QC_MIN_IMPACT, 'QC_MIN_IMPACT', DEFAULT_FILTER_CONFIG.minImpact),
+        minEpisodeItems: parseFloorCount(
+            env.QC_MIN_EPISODE_ITEMS,
+            'QC_MIN_EPISODE_ITEMS',
+            DEFAULT_FILTER_CONFIG.minEpisodeItems,
+        ),
     };
 }
 
@@ -749,6 +774,53 @@ export function filterAnnotated(docs: Doc[], config: FilterConfig): { kept: Doc[
     return { kept, rejected };
 }
 
+function importanceOf(doc: Doc): number {
+    const scores = asRecord(asRecord(doc.metadata).scores);
+    return typeof scores.importance === 'number' ? scores.importance : 0;
+}
+
+function planScoreOf(doc: Doc): number {
+    const value = asRecord(doc.metadata).planScore;
+    return typeof value === 'number' ? value : 0;
+}
+
+/**
+ * Episode floor (20261002): when the strict filter leaves fewer than `minEpisodeItems` docs,
+ * backfill from rejects that failed ONLY the importance minimum — importance is the source-tier
+ * base (tail sources carry 2), so on a thin day it is the softest dimension, while quality/
+ * urgency/impact/category stay hard gates. Admission order: importance desc, planScore desc,
+ * plan order. Admitted docs are stamped `metadata.backfilled: true` and leave the rejected
+ * audit (they are spoken, not dropped). Pure: input docs are never mutated.
+ */
+export function backfillToFloor(
+    kept: Doc[],
+    rejected: RejectedDoc[],
+    config: FilterConfig,
+): { kept: Doc[]; rejected: RejectedDoc[]; admitted: Doc[] } {
+    if (kept.length >= config.minEpisodeItems) return { kept, rejected, admitted: [] };
+    const eligible = rejected
+        .map((entry, index) => ({ entry, index }))
+        .filter(({ entry }) => entry.reasons.length > 0 && entry.reasons.every((r) => r.startsWith('importance:')));
+    eligible.sort((a, b) => {
+        const byImportance = importanceOf(b.entry.doc) - importanceOf(a.entry.doc);
+        if (byImportance !== 0) return byImportance;
+        const byPlanScore = planScoreOf(b.entry.doc) - planScoreOf(a.entry.doc);
+        if (byPlanScore !== 0) return byPlanScore;
+        return a.index - b.index;
+    });
+    const taken = eligible.slice(0, config.minEpisodeItems - kept.length);
+    const takenIds = new Set(taken.map(({ entry }) => entry.doc.id));
+    const admitted = taken.map(({ entry }) => ({
+        ...entry.doc,
+        metadata: { ...asRecord(entry.doc.metadata), backfilled: true },
+    }));
+    return {
+        kept: [...kept, ...admitted],
+        rejected: rejected.filter((entry) => !takenIds.has(entry.doc.id)),
+        admitted,
+    };
+}
+
 /** Sibling rejected-audit path: `<out>.json` → `<out>.rejected.json` (candidates.json → candidates.rejected.json). */
 export function rejectedOutPath(outputPath: string): string {
     return outputPath.endsWith('.json')
@@ -792,9 +864,15 @@ async function processFilterIO(inputPath: string, outputPath: string): Promise<C
     const config = filterConfigFromEnv();
     const docs = DocListSchema.parse(await readJsonFile(inputPath));
     const { kept, rejected } = filterAnnotated(docs, config);
-    const content = planContent(kept, resolvePlanDate());
+    const filled = backfillToFloor(kept, rejected, config);
+    if (filled.admitted.length > 0) {
+        echoError(
+            `episode floor backfill: admitted ${filled.admitted.length} importance-only reject(s) to reach ${config.minEpisodeItems} items (${filled.admitted.map((d) => d.id).join(', ')})`,
+        );
+    }
+    const content = planContent(filled.kept, resolvePlanDate());
     await atomicWrite(outputPath, content);
-    await atomicWrite(rejectedOutPath(outputPath), { rejected, config, total: docs.length });
+    await atomicWrite(rejectedOutPath(outputPath), { rejected: filled.rejected, config, total: docs.length });
     return content;
 }
 

package/plugins/generations/image-gen/dist/index.js

@@ -21818,23 +21818,101 @@ async function readBytes(path2) {
   return new Uint8Array(await readFile(path2));
 }
 function imageDimensions(bytes) {
+  if (isPng(bytes))
+    return pngDimensions(bytes);
+  if (isJpeg(bytes))
+    return jpegDimensions(bytes);
+  if (isWebp(bytes))
+    return webpDimensions(bytes);
+  return null;
+}
+function isPng(b) {
   const PNG_SIG = [137, 80, 78, 71, 13, 10, 26, 10];
-  if (bytes.byteLength < 24) {
-    throw new Error("imageDimensions: not a PNG \u2014 buffer too small");
-  }
+  if (b.byteLength < 24)
+    return false;
   for (let i = 0;i < 8; i++) {
-    if (bytes[i] !== PNG_SIG[i]) {
-      throw new Error("imageDimensions: not a PNG \u2014 invalid signature");
-    }
+    if (b[i] !== PNG_SIG[i])
+      return false;
   }
-  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  return true;
+}
+function pngDimensions(b) {
+  const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
   const ihdrLength = view.getUint32(8, false);
-  if (ihdrLength !== 13 || bytes[12] !== 73 || bytes[13] !== 72 || bytes[14] !== 68 || bytes[15] !== 82) {
-    throw new Error("imageDimensions: not a PNG \u2014 IHDR chunk not found at offset 8");
+  if (ihdrLength !== 13 || view.getUint32(12, false) !== 1229472850) {
+    return null;
   }
-  const width = view.getUint32(16, false);
-  const height = view.getUint32(20, false);
-  return { width, height };
+  return { width: view.getUint32(16, false), height: view.getUint32(20, false) };
+}
+function isJpeg(b) {
+  const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+  return b.byteLength >= 4 && view.getUint16(0, false) === 65496 && view.getUint8(2) === 255;
+}
+function jpegDimensions(b) {
+  const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+  let at = 2;
+  while (at + 4 <= b.byteLength) {
+    if (view.getUint8(at) !== 255)
+      return null;
+    const marker = view.getUint8(at + 1);
+    at += 2;
+    if (marker === 1 || marker >= 208 && marker <= 215)
+      continue;
+    if (at + 2 > b.byteLength)
+      return null;
+    const length = view.getUint16(at, false);
+    if (length < 2)
+      return null;
+    const isSof = marker >= 192 && marker <= 207 && marker !== 196 && marker !== 200 && marker !== 204;
+    if (isSof) {
+      if (at + 7 > b.byteLength)
+        return null;
+      return { height: view.getUint16(at + 3, false), width: view.getUint16(at + 5, false) };
+    }
+    at += length;
+  }
+  return null;
+}
+function isWebp(b) {
+  if (b.byteLength < 20)
+    return false;
+  const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+  return view.getUint32(0, true) === 1179011410 && view.getUint32(8, true) === 1346520407;
+}
+function webpDimensions(b) {
+  const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+  let at = 12;
+  while (at + 8 <= b.byteLength) {
+    const id = String.fromCharCode(view.getUint8(at), view.getUint8(at + 1), view.getUint8(at + 2), view.getUint8(at + 3));
+    const size = view.getUint32(at + 4, true);
+    const body = at + 8;
+    if (id === "VP8 ") {
+      if (size < 10 || body + 10 > b.byteLength)
+        return null;
+      if (view.getUint8(body + 3) !== 157 || view.getUint8(body + 4) !== 1 || view.getUint8(body + 5) !== 42) {
+        return null;
+      }
+      return {
+        width: view.getUint16(body + 6, true) & 16383,
+        height: view.getUint16(body + 8, true) & 16383
+      };
+    }
+    if (id === "VP8L") {
+      if (size < 5 || body + 5 > b.byteLength || view.getUint8(body) !== 47)
+        return null;
+      const bits = view.getUint32(body + 1, true);
+      return { width: (bits & 16383) + 1, height: (bits >>> 14 & 16383) + 1 };
+    }
+    if (id === "VP8X") {
+      if (size < 10 || body + 10 > b.byteLength)
+        return null;
+      const width = view.getUint8(body + 4) | view.getUint8(body + 5) << 8 | view.getUint8(body + 6) << 16;
+      const height = view.getUint8(body + 7) | view.getUint8(body + 8) << 8 | view.getUint8(body + 9) << 16;
+      return { width: width + 1, height: height + 1 };
+    }
+    at = body + size + size % 2;
+  }
+  return null;
 }
 var init_bytes = () => {};
 
@@ -24240,11 +24318,14 @@ import { Buffer as Buffer7 } from "buffer";
 var DEFAULT_MODEL9 = "image-01";
 var MAX_REFERENCE_IMAGE_BYTES = 10 * 1024 * 1024;
 var SUPPORTED_ASPECT_RATIOS = new Set(["1:1", "16:9", "4:3", "3:2", "2:3", "3:4", "9:16", "21:9"]);
+function isAcceptablePixelSize(width, height) {
+  return width >= 512 && width <= 2048 && height >= 512 && height <= 2048 && width % 8 === 0 && height % 8 === 0;
+}
 function validatePixelSize(width, height) {
-  if (width < 512 || width > 2048 || height < 512 || height > 2048) {
-    throw new Error("MiniMax custom size must keep width and height between 512 and 2048.");
-  }
-  if (width % 8 !== 0 || height % 8 !== 0) {
+  if (!isAcceptablePixelSize(width, height)) {
+    if (width < 512 || width > 2048 || height < 512 || height > 2048) {
+      throw new Error("MiniMax custom size must keep width and height between 512 and 2048.");
+    }
     throw new Error("MiniMax custom size requires width and height divisible by 8.");
   }
 }
@@ -24326,6 +24407,7 @@ var createMinimax = (options) => {
     defaultModel: () => DEFAULT_MODEL9,
     isAvailable: () => readEnv("MINIMAX_API_KEY") !== "",
     supportsReferenceImages: () => true,
+    exactSize: (model, width, height) => model === "image-01" && isAcceptablePixelSize(width, height),
     validate(req) {
       requestBody(req.prompt, req.model, req);
     },
@@ -25489,15 +25571,17 @@ async function processGeneratorIO(inputPath, outputPath, options = {}) {
         }
         const provider = at === 0 ? primary : createCandidate(name);
         const model = at === 0 ? spec.model ?? provider.defaultModel() : provider.defaultModel();
+        const exact = format.width !== undefined && format.height !== undefined && provider.exactSize?.(model, format.width, format.height) === true;
         const request = {
           prompt,
           model,
-          aspectRatio: format.aspectRatio,
+          ...exact ? { width: format.width, height: format.height } : { aspectRatio: format.aspectRatio },
           ...spec.referenceImages !== undefined && spec.referenceImages.length > 0 ? { referenceImages: spec.referenceImages } : {}
         };
         try {
           provider.validate?.(request);
-          return await provider.generate(request);
+          const result = await provider.generate(request);
+          return { result, sizeRequest: exact ? "exact" : "aspect" };
         } catch (err) {
           if (spec.fallback === undefined) {
             throw err;
@@ -25520,7 +25604,15 @@ async function processGeneratorIO(inputPath, outputPath, options = {}) {
     };
     let body = doc2?.body ?? "";
     for (const [index, prompt] of prompts.entries()) {
-      const result = await generateWithFallback(index + 1, prompt);
+      const { result, sizeRequest } = await generateWithFallback(index + 1, prompt);
+      const delivered = imageDimensions(result.bytes);
+      if (format.width !== undefined && format.height !== undefined) {
+        if (delivered === null) {
+          echoError(`WARN image-gen: ${result.provider}/${result.model} delivered unparseable image bytes; dimensions omitted`);
+        } else if (delivered.width !== format.width || delivered.height !== format.height) {
+          echoError(`WARN image-gen: ${result.provider}/${result.model} delivered ${delivered.width}x${delivered.height}; format '${format.name}' declares ${format.width}x${format.height}`);
+        }
+      }
       let anchor;
       if (spec.job === "illustration") {
         anchor = positions?.[index];
@@ -25564,6 +25656,9 @@ async function processGeneratorIO(inputPath, outputPath, options = {}) {
         await writeBytes(cardPath, cardBytes);
         written.push(cardPath);
         const dims = imageDimensions(cardBytes);
+        if (dims === null) {
+          throw new Error(`compose: composed card dimensions are unparseable; format '${format.name}' requires ${format.width}x${format.height}`);
+        }
         if (dims.width !== format.width || dims.height !== format.height) {
           throw new Error(`compose: card dimensions ${dims.width}x${dims.height} do not match format canvas ${format.width}x${format.height}`);
         }
@@ -25571,13 +25666,19 @@ async function processGeneratorIO(inputPath, outputPath, options = {}) {
         artifactBytes = cardBytes.byteLength;
         artifactWidth = dims.width;
         artifactHeight = dims.height;
-        illustrationMeta = { path: illustrationArtifactPath, bytes: result.bytes.byteLength };
+        illustrationMeta = {
+          path: illustrationArtifactPath,
+          bytes: result.bytes.byteLength,
+          ...delivered !== null ? { width: delivered.width, height: delivered.height } : {}
+        };
       } else {
         const path2 = artifactPath(outputPath, stem, format.name, index + 1, result.extension);
         await writeBytes(path2, result.bytes);
         written.push(path2);
         artifactPathValue = path2;
         artifactBytes = result.bytes.byteLength;
+        artifactWidth = delivered?.width;
+        artifactHeight = delivered?.height;
       }
       const artifact = {
         path: artifactPathValue,
@@ -25587,6 +25688,7 @@ async function processGeneratorIO(inputPath, outputPath, options = {}) {
         model: result.model,
         prompt,
         bytes: artifactBytes,
+        sizeRequest,
         ...artifactWidth !== undefined ? { width: artifactWidth } : {},
         ...artifactHeight !== undefined ? { height: artifactHeight } : {},
         ...illustrationMeta !== undefined ? { illustration: illustrationMeta } : {}

package/plugins/generations/image-gen/src/bytes.ts

@@ -19,29 +19,117 @@ export async function readBytes(path: string): Promise<Uint8Array> {
 }
 
 /**
- * Task 0180 — pure PNG-only dimension reader (IHDR chunk).
- * Reads `width` and `height` from the PNG IHDR chunk. Non-PNG bytes and
- * truncated headers throw. Task 0182 will extend this to JPEG/WebP (escalation
- * decision A — do not preempt that task's scope here).
+ * Task 0180 (PNG) + task 0182 (JPEG/WebP, `null` contract) — pure header-only dimension
+ * reader. Reads `width`/`height` from PNG (IHDR), JPEG (SOF0–SOF15 except DHT/DAC/JPG)
+ * and WebP (VP8 lossy, VP8L lossless, VP8X extended) bytes; no decode. Returns `null`
+ * when the bytes cannot be parsed — the caller decides whether that is fatal (the compose
+ * canvas assertion) or a WARN with dimensions omitted (artifact recording, R3: the bytes
+ * are already paid for).
  */
-export function imageDimensions(bytes: Uint8Array): { width: number; height: number } {
-    // PNG signature (8 bytes) + IHDR chunk length (4) + 'IHDR' tag (4) + width (4) + height (4) = 24
+export function imageDimensions(bytes: Uint8Array): { width: number; height: number } | null {
+    if (isPng(bytes)) return pngDimensions(bytes);
+    if (isJpeg(bytes)) return jpegDimensions(bytes);
+    if (isWebp(bytes)) return webpDimensions(bytes);
+    return null;
+}
+
+function isPng(b: Uint8Array): boolean {
     const PNG_SIG = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
-    if (bytes.byteLength < 24) {
-        throw new Error('imageDimensions: not a PNG — buffer too small');
-    }
+    if (b.byteLength < 24) return false;
     for (let i = 0; i < 8; i++) {
-        if (bytes[i] !== PNG_SIG[i]) {
-            throw new Error('imageDimensions: not a PNG — invalid signature');
-        }
+        if (b[i] !== PNG_SIG[i]) return false;
     }
+    return true;
+}
+
+function pngDimensions(b: Uint8Array): { width: number; height: number } | null {
     // IHDR chunk: offset 8 = chunk data length (must be 13), offset 12 = 'IHDR' tag.
-    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
     const ihdrLength = view.getUint32(8, false);
-    if (ihdrLength !== 13 || bytes[12] !== 0x49 || bytes[13] !== 0x48 || bytes[14] !== 0x44 || bytes[15] !== 0x52) {
-        throw new Error('imageDimensions: not a PNG — IHDR chunk not found at offset 8');
+    if (ihdrLength !== 13 || view.getUint32(12, false) !== 0x49484452) {
+        return null;
+    }
+    return { width: view.getUint32(16, false), height: view.getUint32(20, false) };
+}
+
+function isJpeg(b: Uint8Array): boolean {
+    const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    // SOI + the first marker's 0xFF prefix.
+    return b.byteLength >= 4 && view.getUint16(0, false) === 0xffd8 && view.getUint8(2) === 0xff;
+}
+
+function jpegDimensions(b: Uint8Array): { width: number; height: number } | null {
+    const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    let at = 2; // after SOI
+    while (at + 4 <= b.byteLength) {
+        if (view.getUint8(at) !== 0xff) return null; // marker desync — not a parseable JPEG stream
+        const marker = view.getUint8(at + 1);
+        at += 2;
+        // Standalone markers (TEM, RSTn) carry no length segment.
+        if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd7)) continue;
+        if (at + 2 > b.byteLength) return null;
+        const length = view.getUint16(at, false);
+        if (length < 2) return null;
+        // SOF0–SOF15 minus DHT (C4), JPG (C8) and DAC (CC) carry the canvas.
+        const isSof = marker >= 0xc0 && marker <= 0xcf && marker !== 0xc4 && marker !== 0xc8 && marker !== 0xcc;
+        if (isSof) {
+            // SOF segment: length(2) precision(1) height(2) width(2).
+            if (at + 7 > b.byteLength) return null;
+            return { height: view.getUint16(at + 3, false), width: view.getUint16(at + 5, false) };
+        }
+        at += length;
+    }
+    return null;
+}
+
+function isWebp(b: Uint8Array): boolean {
+    if (b.byteLength < 20) return false;
+    const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    return view.getUint32(0, true) === 0x46464952 && view.getUint32(8, true) === 0x50424557; // 'RIFF' 'WEBP'
+}
+
+function webpDimensions(b: Uint8Array): { width: number; height: number } | null {
+    const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
+    // Walk the RIFF chunks after the 12-byte file header until a size-bearing chunk appears.
+    let at = 12;
+    while (at + 8 <= b.byteLength) {
+        const id = String.fromCharCode(
+            view.getUint8(at),
+            view.getUint8(at + 1),
+            view.getUint8(at + 2),
+            view.getUint8(at + 3),
+        );
+        const size = view.getUint32(at + 4, true);
+        const body = at + 8;
+        if (id === 'VP8 ') {
+            // Lossy: frame tag (3) + sync code 0x9d 0x01 0x2a + 14-bit LE width/height.
+            if (size < 10 || body + 10 > b.byteLength) return null;
+            if (
+                view.getUint8(body + 3) !== 0x9d ||
+                view.getUint8(body + 4) !== 0x01 ||
+                view.getUint8(body + 5) !== 0x2a
+            ) {
+                return null;
+            }
+            return {
+                width: view.getUint16(body + 6, true) & 0x3fff,
+                height: view.getUint16(body + 8, true) & 0x3fff,
+            };
+        }
+        if (id === 'VP8L') {
+            // Lossless: signature 0x2f, then 14-bit width-1 / height-1 packed little-endian.
+            if (size < 5 || body + 5 > b.byteLength || view.getUint8(body) !== 0x2f) return null;
+            const bits = view.getUint32(body + 1, true);
+            return { width: (bits & 0x3fff) + 1, height: ((bits >>> 14) & 0x3fff) + 1 };
+        }
+        if (id === 'VP8X') {
+            // Extended: 4 flag/reserved bytes, then 24-bit LE width-1 / height-1.
+            if (size < 10 || body + 10 > b.byteLength) return null;
+            const width = view.getUint8(body + 4) | (view.getUint8(body + 5) << 8) | (view.getUint8(body + 6) << 16);
+            const height = view.getUint8(body + 7) | (view.getUint8(body + 8) << 8) | (view.getUint8(body + 9) << 16);
+            return { width: width + 1, height: height + 1 };
+        }
+        at = body + size + (size % 2); // RIFF chunks pad to even sizes
     }
-    const width = view.getUint32(16, false);
-    const height = view.getUint32(20, false);
-    return { width, height };
+    return null;
 }

package/plugins/generations/image-gen/src/index.ts

@@ -390,7 +390,10 @@ export async function processGeneratorIO(
         const captions: CaptionEntry[] = [];
         const attempts: ProviderAttempt[] = [];
         let at = 0; // sticky index into `order`
-        const generateWithFallback = async (image: number, prompt: string): Promise<ImageResult> => {
+        const generateWithFallback = async (
+            image: number,
+            prompt: string,
+        ): Promise<{ result: ImageResult; sizeRequest: 'exact' | 'aspect' }> => {
             const start = attempts.length; // this image's failed attempts begin here (R5 summarises the slice)
             for (;;) {
                 const name = order[at];
@@ -401,17 +404,26 @@ export async function processGeneratorIO(
                 const provider = at === 0 ? primary : createCandidate(name);
                 // spec.model is provider-specific (D6): only the requested provider receives it.
                 const model = at === 0 ? (spec.model ?? provider.defaultModel()) : provider.defaultModel();
+                // 0182 R1/R4: the exact-size gate runs per candidate, with that candidate's own
+                // model and its own capability report. Without it the request keeps today's
+                // aspect-only shape (R2); on the exact path aspectRatio is omitted (R1 — MiniMax
+                // reads width/height only when aspect_ratio is absent).
+                const exact =
+                    format.width !== undefined &&
+                    format.height !== undefined &&
+                    provider.exactSize?.(model, format.width, format.height) === true;
                 const request: ImageRequest = {
                     prompt,
                     model,
-                    aspectRatio: format.aspectRatio,
+                    ...(exact ? { width: format.width, height: format.height } : { aspectRatio: format.aspectRatio }),
                     ...(spec.referenceImages !== undefined && spec.referenceImages.length > 0
                         ? { referenceImages: spec.referenceImages }
                         : {}),
                 };
                 try {
                     provider.validate?.(request);
-                    return await provider.generate(request);
+                    const result = await provider.generate(request);
+                    return { result, sizeRequest: exact ? 'exact' : 'aspect' };
                 } catch (err: unknown) {
                     if (spec.fallback === undefined) {
                         throw err; // D6 R1: strict mode propagates the original error, unwrapped.
@@ -441,7 +453,22 @@ export async function processGeneratorIO(
         };
         let body = doc?.body ?? '';
         for (const [index, prompt] of prompts.entries()) {
-            const result = await generateWithFallback(index + 1, prompt);
+            const { result, sizeRequest } = await generateWithFallback(index + 1, prompt);
+            // 0182 R3: measure the raw provider delivery once — both branches read it. A declared
+            // canvas that came back different (or unparseable) warns and never fails: the bytes
+            // are already paid for, and failing would delete them through the cleanup path.
+            const delivered = imageDimensions(result.bytes);
+            if (format.width !== undefined && format.height !== undefined) {
+                if (delivered === null) {
+                    echoError(
+                        `WARN image-gen: ${result.provider}/${result.model} delivered unparseable image bytes; dimensions omitted`,
+                    );
+                } else if (delivered.width !== format.width || delivered.height !== format.height) {
+                    echoError(
+                        `WARN image-gen: ${result.provider}/${result.model} delivered ${delivered.width}x${delivered.height}; format '${format.name}' declares ${format.width}x${format.height}`,
+                    );
+                }
+            }
             // Re-check against the spliced body; the pre-spend plan check is assertAnchorPlan (0169).
             let anchor: string | undefined;
             if (spec.job === 'illustration') {
@@ -505,6 +532,11 @@ export async function processGeneratorIO(
 
                 // 4. Measure the card dimensions via imageDimensions and assert canvas.
                 const dims = imageDimensions(cardBytes);
+                if (dims === null) {
+                    throw new Error(
+                        `compose: composed card dimensions are unparseable; format '${format.name}' requires ${format.width}x${format.height}`,
+                    );
+                }
                 if (dims.width !== format.width || dims.height !== format.height) {
                     throw new Error(
                         `compose: card dimensions ${dims.width}x${dims.height} do not match format canvas ${format.width}x${format.height}`,
@@ -515,14 +547,21 @@ export async function processGeneratorIO(
                 artifactBytes = cardBytes.byteLength;
                 artifactWidth = dims.width;
                 artifactHeight = dims.height;
-                illustrationMeta = { path: illustrationArtifactPath, bytes: result.bytes.byteLength };
+                illustrationMeta = {
+                    path: illustrationArtifactPath,
+                    bytes: result.bytes.byteLength,
+                    // 0182 R3/R5: the raw provider delivery, measured from its own bytes.
+                    ...(delivered !== null ? { width: delivered.width, height: delivered.height } : {}),
+                };
             } else {
-                // Non-compose: existing path (R6).
+                // Non-compose: existing path (R6); the artifact records the delivered size (0182 R3).
                 const path = artifactPath(outputPath, stem, format.name, index + 1, result.extension);
                 await writeBytes(path, result.bytes);
                 written.push(path);
                 artifactPathValue = path;
                 artifactBytes = result.bytes.byteLength;
+                artifactWidth = delivered?.width;
+                artifactHeight = delivered?.height;
             }
 
             const artifact: ImageArtifact = {
@@ -533,6 +572,7 @@ export async function processGeneratorIO(
                 model: result.model,
                 prompt,
                 bytes: artifactBytes,
+                sizeRequest,
                 ...(artifactWidth !== undefined ? { width: artifactWidth } : {}),
                 ...(artifactHeight !== undefined ? { height: artifactHeight } : {}),
                 ...(illustrationMeta !== undefined ? { illustration: illustrationMeta } : {}),

package/plugins/generations/image-gen/src/job.ts

@@ -76,6 +76,12 @@ export interface ImageArtifact {
     /** The exact prompt string sent. */
     prompt: string;
     seed?: number;
+    /**
+     * 0182 R3: what the provider was asked for — 'exact' when the request carried the
+     * preset's declared width/height (the provider reported it could honour them for this
+     * model), 'aspect' for the aspect-only shape. Present on every written artifact.
+     */
+    sizeRequest?: 'exact' | 'aspect';
     width?: number;
     height?: number;
     bytes: number;

package/plugins/generations/image-gen/src/providers/minimax.ts

@@ -50,11 +50,17 @@ export function parsePixelSize(size: string): { width: number; height: number }
     return { width, height };
 }
 
+/** 0182 R4: image-01 accepts an exact canvas of 512..2048 per edge, divisible by 8. */
+function isAcceptablePixelSize(width: number, height: number): boolean {
+    return width >= 512 && width <= 2048 && height >= 512 && height <= 2048 && width % 8 === 0 && height % 8 === 0;
+}
+
+/** Throwing twin of {@link isAcceptablePixelSize} for the request-body path; messages are frozen (tests pin them). */
 function validatePixelSize(width: number, height: number): void {
-    if (width < 512 || width > 2048 || height < 512 || height > 2048) {
-        throw new Error('MiniMax custom size must keep width and height between 512 and 2048.');
-    }
-    if (width % 8 !== 0 || height % 8 !== 0) {
+    if (!isAcceptablePixelSize(width, height)) {
+        if (width < 512 || width > 2048 || height < 512 || height > 2048) {
+            throw new Error('MiniMax custom size must keep width and height between 512 and 2048.');
+        }
         throw new Error('MiniMax custom size requires width and height divisible by 8.');
     }
 }
@@ -146,6 +152,8 @@ export const createMinimax: ProviderFactory = (options?: ProviderOptions): Image
         defaultModel: () => DEFAULT_MODEL,
         isAvailable: () => readEnv('MINIMAX_API_KEY') !== '',
         supportsReferenceImages: () => true,
+        exactSize: (model: string, width: number, height: number): boolean =>
+            model === 'image-01' && isAcceptablePixelSize(width, height),
         validate(req: ImageRequest): void {
             requestBody(req.prompt, req.model, req);
         },

package/plugins/generations/image-gen/src/providers/types.ts

@@ -32,7 +32,11 @@ export interface ImageRequest {
     model: string;
     /** e.g. '21:9' — from FormatPreset.aspectRatio (0102). */
     aspectRatio?: string;
-    /** Optional exact pixels; providers that only take an aspect ratio ignore them. */
+    /**
+     * Declared preset canvas (0182 R1). Sent only when the resolved provider's
+     * `exactSize(model, width, height)` returns true — with `aspectRatio` omitted;
+     * every other provider receives the aspect-only request shape and never sees them.
+     */
     width?: number;
     height?: number;
     quality?: ImageQuality;
@@ -64,6 +68,13 @@ export interface ImageProvider {
     isAvailable(): boolean;
     /** Queryable ref-image capability; 0105 routes `--ref` work on this fact. */
     supportsReferenceImages(model: string): boolean;
+    /**
+     * Exact-size capability (0182 R1/R4): can this adapter deliver the exact pixel canvas
+     * for this model? Absent = aspect-only — `processGeneratorIO` then sends only
+     * `aspectRatio`, byte-for-byte as before 0182. Adapters opt in one at a time, on
+     * measured evidence (task 0182 Q&A, closed).
+     */
+    exactSize?(model: string, width: number, height: number): boolean;
     /** Throw on an impossible combination (e.g. Imagen + referenceImages) before spending money. */
     validate?(req: ImageRequest): void;
     generate(req: ImageRequest): Promise<ImageResult>;