bambu-printer-mcp 1.1.27 → 1.1.29

package/dist/safety/print-file.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { readBoundedPrintFile, loadSafe3mfArchive } from './archive.js';
-import { MACHINE_LIMITS, normalizeMaterial, normalizeModel, validateStartupPurgeTemperature, validateTemperature } from './limits.js';
+import { MACHINE_LIMITS, isDualNozzleModel, normalizeMaterial, normalizeModel, validateStartupPurgeTemperature, validateTemperature } from './limits.js';
 const NUMBER = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)$/;
 const fail = (message) => { throw new Error(`Print safety: ${message}`); };
 function list(value) {
@@ -62,6 +62,11 @@ function stripComments(line) {
 /** A deliberately narrow parameter lexer for commands affecting heat/material selection.
  * Unknown nonthermal vendor commands do not require a global G-code allowlist.
  */
+/** True when the parameter is present, finite and within [low, high]. */
+function inRange(args, key, low, high) {
+    const value = args.get(key);
+    return value !== undefined && Number.isFinite(value) && value >= low && value <= high;
+}
 function parameters(text, flags = '') {
     const result = new Map();
     let rest = text.trim();
@@ -163,6 +168,7 @@ export async function inspectPrintFile(filePath, options) {
     const model = normalizeModel(options.model);
     if (!model)
         return fail(`unknown or missing printer model '${options.model}'`);
+    const dualNozzle = isDualNozzleModel(model);
     const plateIndex = options.plateIndex ?? 0;
     if (!Number.isInteger(plateIndex) || plateIndex < 0)
         return fail('selected plate index must be a nonnegative integer');
@@ -303,6 +309,24 @@ export async function inspectPrintFile(filePath, options) {
         const values = list(value);
         return values.length && values.every(v => !!normalizeMaterial(v)) ? values.map(v => normalizeMaterial(v)) : undefined;
     }, 'filament material');
+    // GCode.cpp uses 1-based filament_map logical extruders and then indexes
+    // physical_extruder_map to select the physical nozzle. Only this selected
+    // plate's headers establish that binding; unsliced project defaults do not.
+    const headerMap = (key, count, low, high) => {
+        const values = metadataValues(headers, [key]);
+        if (!values.length)
+            return undefined;
+        return consistent(values, value => {
+            const entries = list(value);
+            return entries.length === count && entries.every(v => NUMBER.test(v) && Number.isInteger(Number(v)) && Number(v) >= low && Number(v) <= high)
+                ? entries.map(Number) : undefined;
+        }, key.replace(/_/g, ' '));
+    };
+    const physicalExtruderMap = headerMap('physical_extruder_map', nozzleDiameters.length, 0, dualNozzle ? Math.min(nozzleDiameters.length, 2) - 1 : nozzleDiameters.length - 1);
+    if (physicalExtruderMap && new Set(physicalExtruderMap).size !== physicalExtruderMap.length)
+        fail('physical extruder map must be a complete permutation');
+    const filamentMap = headerMap('filament_map', materials.length, 1, nozzleDiameters.length);
+    const filamentNozzleIndices = filamentMap && physicalExtruderMap ? filamentMap.map(logical => physicalExtruderMap[logical - 1]) : undefined;
     const bedValues = metadataValues([...metadata, plate], ['curr_bed_type', 'bed_type']);
     const bedType = bedValues.length ? consistent(bedValues, normalizeBed, 'bed type') : undefined;
     if (options.bedType && (!bedType || normalizeBed(options.bedType) !== bedType))
@@ -365,7 +389,11 @@ export async function inspectPrintFile(filePath, options) {
             let line = stripComments(lines[index]);
             if (!line || line === '%')
                 continue;
-            // The official H2C template emits this literal separator without a semicolon.
+            // Accept only the exact vendor banners in their documented model/scope.
+            // X2D emits its filament-change banner throughout a print; H2C's record
+            // separator stays inside its explicitly bounded startup block.
+            if (line === '======== X2D filament_change gcode ==========' && model === 'x2d')
+                continue;
             if (line === '========== record data ==========' && h2cStartup(index))
                 continue;
             line = line.replace(/^N\d+\s*/i, '').replace(/\*\d+\s*$/, '');
@@ -392,6 +420,33 @@ export async function inspectPrintFile(filePath, options) {
             const code = command[1].toUpperCase() + String(Number(base)) + (subcode === undefined ? '' : '.' + subcode);
             const argumentsText = line.slice(command[0].length).trim();
             commandCount++;
+            if (code === 'M9711') {
+                // Official X2D and H2D time-lapse capture (Bambu Studio and OrcaSlicer
+                // templates), emitted on every layer: M is the time-lapse mode and E the
+                // physical extruder, not a second command; T is a duration, not a heater.
+                // It sets no temperature. Positions stay inside the machine volume.
+                const invalid = () => fail('unsupported M9711 time-lapse parameters');
+                if (!['x2d', 'h2d'].includes(model))
+                    invalid();
+                let args;
+                try {
+                    args = parameters(argumentsText);
+                }
+                catch {
+                    return invalid();
+                }
+                const [width, depth, height] = MACHINE_LIMITS[model].volume;
+                const position = ['X', 'Y', 'U', 'V'].filter(key => args.has(key)).join('');
+                const limit = { X: width, U: width, Y: depth, V: depth };
+                if ([...args.keys()].some(key => !'MEXYUVZSCOT'.includes(key)) ||
+                    // X2D and H2D have two physical extruders, whatever the file declares.
+                    ![0, 1].includes(args.get('M')) || !Number.isInteger(args.get('E')) || !inRange(args, 'E', 0, Math.min(nozzleDiameters.length, 2) - 1) ||
+                    args.get('S') !== 11 || args.get('C') !== 10 || args.get('O') !== 0 || !inRange(args, 'T', 0, 600000) ||
+                    !inRange(args, 'Z', 0, height) ||
+                    !['', 'XY', 'UV'].includes(position) || [...position].some(key => !inRange(args, key, 0, limit[key])))
+                    invalid();
+                continue;
+            }
             if (!['M117', 'M118', 'M1002', 'M1006', 'M900', 'M970', 'M983.1', 'G383'].includes(code) && /[GM]\s*\d/i.test(argumentsText))
                 fail('multiple commands on one line are unsupported');
             // Coordinated extrusion closes the startup-only allowance even when the
@@ -445,9 +500,16 @@ export async function inspectPrintFile(filePath, options) {
                     continue;
                 }
                 const vendorWait = code === 'M109' && ['a1', 'a1mini'].includes(model);
+                // Bambu Studio addresses a physical nozzle on dual-nozzle machines with N<index>
+                // (X2D `M104 T1 S25 N0` multi-extruder pre-cooling and wipe-tower reheats).
+                // N selects a nozzle, never a target, so it is accepted only on those models,
+                // only for nozzle heaters, and only within the declared nozzle count.
+                const nozzleIndex = ['M104', 'M109'].includes(code) && dualNozzle;
                 for (const key of args.keys())
-                    if (!'SRTA'.includes(key) && !(key === 'H' && vendorWait))
+                    if (!'SRTA'.includes(key) && !(key === 'H' && vendorWait) && !(key === 'N' && nozzleIndex))
                         fail(`unsupported ${code} temperature parameter ${key}`);
+                if (args.has('N') && (!Number.isInteger(args.get('N')) || args.get('N') < 0 || args.get('N') >= Math.min(nozzleDiameters.length, 2)))
+                    fail(`unsupported ${code} nozzle index N`);
                 if (args.has('H') && (!Number.isFinite(args.get('H')) || args.get('H') < 0 || args.get('H') > 300))
                     fail(`unsupported ${code} wait parameter H`);
                 if (!args.has('S') && !args.has('R'))
@@ -457,13 +519,13 @@ export async function inspectPrintFile(filePath, options) {
                 // Without a verified per-filament nozzle map, apply all possible materials.
                 if (args.has('T') && (!Number.isInteger(args.get('T')) || args.get('T') < 0 || args.get('T') >= nozzleDiameters.length))
                     fail('physical heater target has no declared nozzle');
-                const position = args.has('T') ? undefined : active;
+                const position = args.has('T') || args.has('N') ? undefined : active;
                 const commonFlush = code === 'M109' && args.size === 1 && args.get('S') === 290 && model === 'x1e' && !depositionStarted && !commonFlushUsed && boundedX1ePurge(lines, index);
                 if (commonFlush)
                     commonFlushUsed = true;
                 for (const key of ['S', 'R'])
                     if (args.has(key))
-                        heat(component, args.get(key), position, args.has('T') || args.has('A'), commonFlush);
+                        heat(component, args.get(key), position, args.has('T') || args.has('N') || args.has('A'), commonFlush);
             }
             else if (code === 'M620' || code === 'M621') {
                 const args = parameters(argumentsText, model === 'x2d' ? 'MAB' : model === 'h2c' ? 'MAN' : 'MA');
@@ -578,7 +640,21 @@ export async function inspectPrintFile(filePath, options) {
                 for (const key of args.keys())
                     if (!'SLT'.includes(key))
                         fail(`unsupported M620.17 parameter ${key}`);
-                heat('nozzle', args.get('S'), requirePosition(args.get('L')));
+                if (args.get('L') === -1 && model === 'x2d') {
+                    // OrcaSlicer's X2D start G-code preheats a nozzle with no assigned
+                    // filament (L-1) for toolhead-offset calibration; Bambu Studio writes
+                    // L0 there. No project filament is selected, so check the target
+                    // against the hardware limit and every declared material, like other
+                    // heater commands without a verified filament. That is never looser
+                    // than an accepted L<position> form. Material left in the nozzle from
+                    // an earlier job is live state that no file can declare. T names one
+                    // of the two physical nozzles, whatever the file declares.
+                    if (args.get('T') > 1)
+                        fail('unsupported M620.17 nozzle/material temperature mapping');
+                    heat('nozzle', args.get('S'), undefined, true);
+                }
+                else
+                    heat('nozzle', args.get('S'), requirePosition(args.get('L')));
             }
             else if ((/^M620\./.test(code) && !['M620.3', 'M620.6', 'M620.11'].includes(code)) || /^M621\./.test(code)) {
                 fail(`unsupported thermal-affecting filament command ${code}`);
@@ -610,5 +686,5 @@ export async function inspectPrintFile(filePath, options) {
         return fail('selected G-code contains no printable commands');
     if (!used.size)
         materials.forEach((_, index) => used.add(index));
-    return { model, nozzleDiameters, materials, usedFilamentPositions: [...used].sort((a, b) => a - b), plateInternalPath, sha256, maxNozzleTemperature, maxBedTemperature, maxChamberTemperature, bedType, selectsAms, nozzleTypes, nozzleFlows };
+    return { model, nozzleDiameters, materials, usedFilamentPositions: [...used].sort((a, b) => a - b), plateInternalPath, sha256, maxNozzleTemperature, maxBedTemperature, maxChamberTemperature, bedType, selectsAms, nozzleTypes, nozzleFlows, filamentNozzleIndices };
 }

package/dist/safety/printer-state.d.ts

@@ -1,4 +1,5 @@
 import { BambuClient } from "bambu-node";
+export declare const SERIAL_MODELS: Record<string, string>;
 /** Only raw reports received after this request are evidence. Never read printer.data here. */
 export declare function readFreshPrinterStatus(printer: BambuClient, serial: string, timeoutMs?: number): Promise<any>;
 export interface PrinterStateRequirements {
@@ -6,6 +7,8 @@ export interface PrinterStateRequirements {
     nozzleDiameters: number[];
     materials?: string[];
     usedFilamentPositions?: number[];
+    /** Verified physical nozzle index for each project filament, composed from the inspected plate mappings. */
+    filamentNozzleIndices?: number[];
     amsMapping?: number[];
     useAMS?: boolean;
     requireIdle?: boolean;
@@ -36,6 +39,14 @@ export interface ValidatedPrinterState {
     reportedNozzles: ReportedNozzle[];
     filaments: ReportedFilament[];
 }
+/** The one key format for a reported entry, shared by the gate and clear_hms_errors. */
+export declare function reportedHmsKey(entry: unknown): string;
+/** Bambu's display form of a cleared-code key such as "hms:83887616:131184"; other keys unchanged. */
+export declare function describeHmsKey(key: string): string;
+/** Labels of reported entries that pass only because Bambu hides them for this printer. */
+export declare function hiddenHmsNotices(raw: unknown, serial: string, model: string): string[];
+/** Cleared-code keys of reported hidden entries; clearing never removes them, so they are not re-acknowledged. */
+export declare function hiddenHmsKeys(raw: unknown, serial: string, model: string): string[];
 /** Verifies reported configuration, not a physical nozzle/spool inspection. */
 export declare function validatePrinterState(status: any, requirements: PrinterStateRequirements): ValidatedPrinterState;
 /** Manual M104 cannot remap filament slots. Validate the material already at the nozzle. */

package/dist/safety/printer-state.js

@@ -1,11 +1,12 @@
+import { HIDDEN_HMS } from "./hidden-hms.js";
 import { GetVersionCommand, PushAllCommand } from "bambu-node";
-import { normalizeMaterial, normalizeModel } from "./limits.js";
+import { isDualNozzleModel, normalizeMaterial, normalizeModel } from "./limits.js";
 const MAX_REPORT_AGE_MS = 15000;
 const MODEL_IDS = {
     O1C: "H2C", O1C2: "H2C", O1D: "H2D", O1E: "H2D Pro", O1S: "H2S", N6: "X2D",
     N2S: "A1", A1M: "A1 Mini", C11: "P1P", C12: "P1S", C13: "X1E", "BL-P001": "X1C", "BL-P002": "X1",
 };
-const SERIAL_MODELS = {
+export const SERIAL_MODELS = {
     "093": "H2S", "094": "H2D", "31B": "H2C", "239": "H2D Pro", "20P": "X2D",
     "00M": "X1C", "00W": "X1", "03W": "X1E", "01S": "P1P", "01P": "P1S", "22E": "P2S", "039": "A1", "030": "A1 Mini",
 };
@@ -184,7 +185,77 @@ function reportedNozzles(raw) {
     }
     return output;
 }
-function validateErrors(raw, requireIdle) {
+const hiddenHmsSets = new Map(Object.entries(HIDDEN_HMS).map(([prefix, codes]) => [prefix, new Set(codes)]));
+function hmsCode(entry) {
+    const code = finiteNumber(entry?.code);
+    const attr = finiteNumber(entry?.attr);
+    const valid = (value) => value !== undefined && Number.isInteger(value) && value >= 0 && value <= 0xffffffff;
+    if (!valid(code) || !valid(attr))
+        return undefined;
+    // BambuStudio DevHMS.cpp: code >> 16; DevHMS.h: 1=fatal,2=serious,3=common,4=info.
+    return { attr, code, severity: Math.floor(code / 65536), hex: (attr.toString(16).padStart(8, "0") + code.toString(16).padStart(8, "0")).toUpperCase() };
+}
+const hmsLabel = (hex) => `HMS ${hex.slice(0, 4)}-${hex.slice(4, 8)}-${hex.slice(8, 12)}-${hex.slice(12)}`;
+const hmsKey = (entry) => `hms:${entry.attr}:${entry.code}`;
+/** The one key format for a reported entry, shared by the gate and clear_hms_errors. */
+export function reportedHmsKey(entry) {
+    const parsed = hmsCode(entry);
+    return parsed ? hmsKey(parsed) : `hms:${entry?.attr}:${entry?.code}`;
+}
+/** Bambu's display form of a cleared-code key such as "hms:83887616:131184"; other keys unchanged. */
+export function describeHmsKey(key) {
+    const match = /^hms:(\d+):(\d+)$/.exec(key);
+    const entry = match ? hmsCode({ attr: Number(match[1]), code: Number(match[2]) }) : undefined;
+    return entry ? hmsLabel(entry.hex) : key;
+}
+/**
+ * A serious or common entry that Bambu lists for this serial prefix with empty
+ * text: Bambu Studio, Bambu Handy and the printer screen never show it, and
+ * the printer keeps printing with it (an X2D raises 0500-0600-0002-0070 at
+ * every boot). Bambu Studio selects the table by serial prefix, so this does
+ * too, but only when that prefix belongs to the verified model: a sparse report
+ * without a serial must not let a misconfigured serial pick another model's
+ * table. Fatal, invalid-level and unlisted entries never qualify.
+ */
+function isHiddenNotice(serial, model, entry) {
+    if (entry.severity !== 2 && entry.severity !== 3)
+        return false;
+    const prefix = serial.trim().toUpperCase().slice(0, 3);
+    const normalized = normalizeModel(model);
+    if (!normalized || normalizeModel(SERIAL_MODELS[prefix] ?? "") !== normalized)
+        return false;
+    return hiddenHmsSets.get(prefix)?.has(entry.hex) === true;
+}
+function hiddenHmsEntries(raw, serial, model) {
+    if (!object(raw))
+        return [];
+    const identity = observedIdentity(raw, serial);
+    if (!identity.observedSerial || identity.model !== normalizeModel(model))
+        return [];
+    const entries = Array.isArray(raw.hms) ? raw.hms : [];
+    const seen = new Set();
+    return entries.map(hmsCode).filter((entry) => !!entry && isHiddenNotice(identity.observedSerial, model, entry) && !seen.has(entry.hex) && !!seen.add(entry.hex));
+}
+/** Labels of reported entries that pass only because Bambu hides them for this printer. */
+export function hiddenHmsNotices(raw, serial, model) {
+    return hiddenHmsEntries(raw, serial, model).map(entry => hmsLabel(entry.hex));
+}
+/** Cleared-code keys of reported hidden entries; clearing never removes them, so they are not re-acknowledged. */
+export function hiddenHmsKeys(raw, serial, model) {
+    return hiddenHmsEntries(raw, serial, model).map(hmsKey);
+}
+const loggedHiddenNotices = new Set();
+/** Name each hidden entry a check passed once per printer on stderr, so headless runs still record it. */
+function logHiddenNotices(raw, serial, model) {
+    for (const entry of hiddenHmsEntries(raw, serial, model)) {
+        const key = `${serial}:${entry.hex}`;
+        if (loggedHiddenNotices.has(key))
+            continue;
+        loggedHiddenNotices.add(key);
+        console.error(`Printer ${serial} reports ${hmsLabel(entry.hex)}, which Bambu lists for it without text and never shows as a fault; it does not block operations.`);
+    }
+}
+function validateErrors(raw, requireIdle, serial, model) {
     const state = typeof raw.gcode_state === "string" ? raw.gcode_state.toUpperCase() : "UNKNOWN";
     if (requireIdle && !["IDLE", "FINISH"].includes(state))
         throw new Error(`Printer state ${state} is not safely idle.`);
@@ -194,18 +265,14 @@ function validateErrors(raw, requireIdle) {
         throw new Error("Printer reports a print error or did not report its error state.");
     if (!Array.isArray(raw.hms))
         throw new Error("Printer HMS error state is missing or malformed.");
-    for (const entry of raw.hms) {
-        const code = finiteNumber(entry?.code);
-        const attr = finiteNumber(entry?.attr);
-        // BambuStudio DevHMS.cpp: code >> 16; DevHMS.h: 1=fatal,2=serious,3=common,4=info.
+    for (const reported of raw.hms) {
+        const entry = hmsCode(reported);
         // Unknown severities fail closed; attr identifies the module and is not a severity bitmask.
-        if (code === undefined || attr === undefined || !Number.isInteger(code) || !Number.isInteger(attr) || code < 0 || code > 0xffffffff || attr < 0 || attr > 0xffffffff || Math.floor(code / 65536) !== 4) {
-            const hex = (value) => value.toString(16).toUpperCase().padStart(8, "0");
-            const label = code !== undefined && attr !== undefined && Number.isInteger(code) && Number.isInteger(attr) && code >= 0 && attr >= 0
-                ? ` (HMS ${hex(attr).slice(0, 4)}-${hex(attr).slice(4)}-${hex(code).slice(0, 4)}-${hex(code).slice(4)})` : "";
-            throw new Error(`Printer reports actionable or unknown HMS errors${label}; inspect and resolve them before proceeding.`);
-        }
+        if (entry && (entry.severity === 4 || isHiddenNotice(serial, model, entry)))
+            continue;
+        throw new Error(`Printer reports actionable or unknown HMS errors${entry ? ` (${hmsLabel(entry.hex)})` : ""}; inspect and resolve them before proceeding.`);
     }
+    logHiddenNotices(raw, serial, model);
 }
 function trayRange(value, label) {
     if (value === undefined || value === null || value === "" || value === "0" || value === 0)
@@ -215,15 +282,24 @@ function trayRange(value, label) {
         throw new Error(`Reported filament ${label} temperature is malformed.`);
     return number;
 }
-function externalTray(raw) {
+/** Dual-nozzle printers report one virtual external slot per nozzle, numbered as Bambu
+ * Studio does (VIRTUAL_TRAY_MAIN_ID 255 = right/main nozzle, VIRTUAL_TRAY_DEPUTY_ID 254 =
+ * left/deputy nozzle), so the requested tray selects its slot. Single-nozzle printers keep
+ * requiring exactly one slot 254 report, then the legacy vt_tray field. */
+function externalTray(raw, trayIndex, model) {
     const slots = raw.vir_slot;
+    const dualNozzle = isDualNozzleModel(model);
     if (Array.isArray(slots)) {
-        const selected = slots.filter((slot) => Number(slot?.id) === 254);
-        if (slots.length === 1 && selected.length === 1)
+        const selected = slots.filter((slot) => Number(slot?.id) === trayIndex);
+        if (selected.length === 1 && (dualNozzle || slots.length === 1))
             return selected[0];
+        if (dualNozzle && selected.length === 0 && slots.length > 0)
+            throw new Error(`External spool ${trayIndex} is not in the fresh per-nozzle report; cannot verify the selected material.`);
         if (slots.length > 0)
             throw new Error("External spool report is ambiguous for this nozzle; cannot verify the selected material.");
     }
+    if (dualNozzle)
+        throw new Error(`Dual-nozzle external spool ${trayIndex} requires a fresh per-nozzle vir_slot report; legacy vt_tray cannot verify the selected nozzle.`);
     return object(raw.vt_tray) ? raw.vt_tray : undefined;
 }
 function mappedTray(raw, index) {
@@ -265,7 +341,7 @@ export function validatePrinterState(status, requirements) {
     const model = normalizeModel(requirements.model);
     if (!model || !identity.model || model !== identity.model)
         throw new Error(`Printer model identity mismatch: requested ${requirements.model}, observed ${identity.model ?? "unknown"}.`);
-    validateErrors(raw, requirements.requireIdle !== false);
+    validateErrors(raw, requirements.requireIdle !== false, identity.observedSerial ?? "", model);
     if (requirements.requireLoadedFilament && (raw.ams?.tray_now !== undefined || Array.isArray(raw.ams?.ams))) {
         const current = finiteNumber(raw.ams?.tray_now);
         if (current === 255)
@@ -278,7 +354,7 @@ export function validatePrinterState(status, requirements) {
         }
     }
     const nozzles = requirements.nozzleDiameters.length ? reportedNozzles(raw) : [];
-    if (requirements.nozzleDiameters.length && ["h2d", "h2dpro", "h2c", "x2d"].includes(model) &&
+    if (requirements.nozzleDiameters.length && isDualNozzleModel(model) &&
         !Array.isArray(raw.device?.nozzle?.info) && !Array.isArray(raw.nozzle_diameter)) {
         throw new Error("A scalar legacy nozzle report is ambiguous for this multi-nozzle printer; fresh per-nozzle configuration is required.");
     }
@@ -307,16 +383,33 @@ export function validatePrinterState(status, requirements) {
     if (requirements.verifyMaterials !== false && (requirements.materials !== undefined || requirements.nozzleDiameters.length)) {
         const materials = requirements.materials ?? [];
         const positions = requirements.usedFilamentPositions ?? materials.map((_, index) => index);
+        // 255 is the right/main nozzle external spool only on dual-nozzle printers.
+        const dualNozzle = isDualNozzleModel(model);
+        const maxTray = dualNozzle ? 255 : 254;
         if (!positions.length)
             throw new Error("A declared material is required for each used filament or external spool.");
         for (const position of positions) {
             const material = normalizeMaterial(materials[position]);
             if (!Number.isInteger(position) || position < 0 || !material)
                 throw new Error(`A known declared material is required for filament position ${position}.`);
-            const trayIndex = requirements.useAMS ? requirements.amsMapping?.[position] : 254;
-            if (trayIndex === undefined || !Number.isInteger(trayIndex) || trayIndex < 0 || trayIndex > 254)
+            const physicalNozzle = requirements.filamentNozzleIndices?.[position];
+            const externalForNozzle = physicalNozzle === 0 ? 255 : physicalNozzle === 1 ? 254 : undefined;
+            const trayIndex = requirements.useAMS || requirements.amsMapping !== undefined
+                ? requirements.amsMapping?.[position] : dualNozzle ? externalForNozzle : 254;
+            if (!requirements.useAMS && dualNozzle && requirements.amsMapping === undefined && externalForNozzle === undefined) {
+                throw new Error(`External spool for filament position ${position} is ambiguous; re-slice with complete filament_map and physical_extruder_map nozzle bindings or provide a verified sliced plate.`);
+            }
+            if (trayIndex === undefined || !Number.isInteger(trayIndex) || trayIndex < 0 || trayIndex > maxTray)
                 throw new Error(`Complete AMS mapping is required for filament position ${position}.`);
-            const tray = trayIndex === 254 ? externalTray(raw) : mappedTray(raw, trayIndex);
+            if (!requirements.useAMS && trayIndex < 254)
+                throw new Error("External-spool printing requires an external spool mapping; AMS trays require use_ams:true.");
+            if (dualNozzle && trayIndex >= 254) {
+                if (externalForNozzle === undefined)
+                    throw new Error(`External spool ${trayIndex} needs a verified physical nozzle binding for filament position ${position}; re-slice with complete filament_map and physical_extruder_map metadata.`);
+                if (trayIndex !== externalForNozzle)
+                    throw new Error(`External spool ${trayIndex} does not feed physical nozzle ${physicalNozzle} for filament position ${position}; use spool ${externalForNozzle}.`);
+            }
+            const tray = trayIndex >= 254 ? externalTray(raw, trayIndex, model) : mappedTray(raw, trayIndex);
             const reportedType = typeof tray?.tray_type === "string" ? tray.tray_type.trim() : "";
             if (reportedType && normalizeMaterial(reportedType) !== material)
                 throw new Error(`Reported material ${reportedType} in slot ${trayIndex} contradicts declared ${materials[position]}.`);
@@ -337,7 +430,7 @@ export function manualHeatingRequirements(status, model, nozzleDiameter, materia
     const raw = status?.raw;
     if (!object(raw))
         throw new Error("A fresh printer report is required for manual nozzle heating.");
-    if (["h2d", "h2dpro", "h2c", "x2d"].includes(normalized) || reportedNozzles(raw).some(nozzle => nozzle.index !== 0)) {
+    if (isDualNozzleModel(normalized) || reportedNozzles(raw).some(nozzle => nozzle.index !== 0)) {
         throw new Error("Manual heating cannot verify the active nozzle and loaded material on this multi-nozzle printer. Use a checked sliced print instead.");
     }
     const requirements = {

package/dist/slicer/profile-flatten.js

@@ -228,6 +228,29 @@ function enforceMatchingNozzles(arr) {
         }
     }
 }
+/**
+ * BambuStudio picks each per-variant machine, process, and filament value
+ * (e.g. filament_max_volumetric_speed) by "<extruder_type> <nozzle_volume_type>"
+ * among the variants each extruder declares in extruder_variant_list. A flow
+ * type the preset doesn't declare has no values to pick, so refuse it instead
+ * of labelling a job for a nozzle it wasn't sliced for.
+ */
+function assertNozzleVariantDeclared(flat, volumeType, machineLeaf) {
+    const strings = (key) => Array.isArray(flat[key]) ? flat[key].map(String) : [];
+    const extruderTypes = strings("extruder_type");
+    const declaredLists = strings("extruder_variant_list");
+    const count = flat["nozzle_volume_type"].length;
+    for (let i = 0; i < count; i++) {
+        const extruderType = extruderTypes[i] ?? extruderTypes[0];
+        const declared = (declaredLists[i] ?? declaredLists[0] ?? "").split(",").map((v) => v.trim()).filter(Boolean);
+        const matches = (variant) => extruderType ? variant === `${extruderType} ${volumeType}` : variant.endsWith(` ${volumeType}`);
+        // Presets without variant declarations only have Standard values.
+        if (declared.length === 0 ? volumeType === "Standard" : declared.some(matches))
+            continue;
+        throw new Error(`Slicing for a ${volumeType} nozzle is refused: "${machineLeaf}" declares no ${volumeType} variant ` +
+            `for extruder ${i + 1} (declared: ${declared.join(", ") || "none"}).`);
+    }
+}
 /** Best-effort extruder count for fallback nozzle_volume_type sizing. */
 /** BambuStudio's built-in filament_colour default. */
 export const DEFAULT_FILAMENT_COLOUR = "#00AE42";
@@ -545,6 +568,8 @@ export async function flattenForCli(opts) {
     });
     // CLI-specific post-processing on machine profile only.
     deriveNozzleVolumeType(machineFlat, opts.nozzleVolumeType);
+    if (opts.nozzleVolumeType)
+        assertNozzleVariantDeclared(machineFlat, opts.nozzleVolumeType, opts.machineLeaf);
     applyMachineModelBedMetadata(machineFlat, machineIndex);
     // A standalone custom machine can accompany process/filament profiles that
     // need BBL resolution; do not impose bundled model config on that machine.

package/dist/slicer/remote-slicer.d.ts

@@ -0,0 +1,12 @@
+import type { BambuSliceOptions } from '../stl/stl-manipulator.js';
+export declare function validateRemoteSliceOptions(options?: BambuSliceOptions): number;
+/** Upload only locally prepared profiles, then inspect the exact downloaded 3MF. */
+export declare function sliceWithOrcaApi(input: {
+    inputPath: string;
+    machinePath: string;
+    processPath: string;
+    filamentPaths: string[];
+    outputPath: string;
+    options?: BambuSliceOptions;
+    isCancelled: () => boolean;
+}): Promise<string>;