079project 8.0.0 → 9.1.0

package/optimization.cjs

@@ -0,0 +1,720 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const DEFAULT_TEST = path.join(__dirname, 'test_automatic.cjs');
+const DEFAULT_MAIN_MODULE = path.join(__dirname, 'main.cjs');
+
+const nowStamp = () => {
+    const d = new Date();
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}_${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+};
+
+const ensureDir = (dir) => {
+    if (!dir) return;
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+};
+
+const parseArgs = (argv) => {
+    const out = { _: [], mainArgs: [] };
+    for (const item of argv) {
+        if (item === '-h' || item === '--help') {
+            out.help = true;
+            continue;
+        }
+        if (!item.startsWith('--')) {
+            out._.push(item);
+            continue;
+        }
+        const eq = item.indexOf('=');
+        const key = eq === -1 ? item.slice(2) : item.slice(2, eq);
+        const value = eq === -1 ? true : item.slice(eq + 1);
+
+        if (key === 'main-arg') {
+            // allow repeated --main-arg=--foo=bar
+            out.mainArgs.push(String(value));
+            continue;
+        }
+
+        if (Object.prototype.hasOwnProperty.call(out, key)) {
+            // allow repeated keys by array
+            if (Array.isArray(out[key])) out[key].push(value);
+            else out[key] = [out[key], value];
+        } else {
+            out[key] = value;
+        }
+    }
+    return out;
+};
+
+const printHelp = ({ mainDefault, testDefault } = {}) => {
+    const mainPath = mainDefault || DEFAULT_MAIN_MODULE;
+    const testPath = testDefault || DEFAULT_TEST;
+    const lines = [
+        'Usage:',
+        `  node optimization.cjs [options]`,
+        '',
+        'Quick start (recommended):',
+        `  node optimization.cjs --iters=12 --robots-limit=10000000 --params=decayK,iteration,memeNgramMin,memeNgramMax,minOverlapThreshold,maxMemeWords`,
+        '',
+        'How to choose command-line parameters:',
+        '  1) --params: choose which numeric model params to optimize.',
+        '     - Valid keys come ONLY from main.cjs exported MODEL_DEFAULTS (no invented keys).',
+        '     - Example: --params=decayK,iteration,memeNgramMin,memeNgramMax,minOverlapThreshold,maxMemeWords',
+        '  2) --init-json: set your starting point (full/partial) before optimization.',
+        '     - Example: --init-json={"decayK":1.2,"iteration":6}',
+        '  3) --cats: choose categorical params to sweep occasionally (if supported by main exports).',
+        '     - Example: --cats=activationType,transferType',
+        '  4) Keep eval comparable by default: learning is frozen unless you pass --allow-learning.',
+        '  5) Use --main-arg to forward CLI args to test_automatic/main if needed (repeatable).',
+        '  6) Deterministic control-variable search:',
+        '     - Numeric params are scanned in the exact order of --params.',
+        '     - Each numeric param is swept on a grid (float step defaults to 0.1).',
+        '     - Categorical params (e.g. activationType) are tried in order, and for each choice we run a numeric sweep.',
+        '',
+        'Options:',
+        `  -h, --help                 Show this help and exit`,
+        `  --test=FILE                Path to evaluator (default: ${testPath})`,
+        `  --main=FILE                Path to main module that exports MODEL_DEFAULTS (default: ${mainPath})`,
+        `  --robots-limit=N           Forwarded to evaluator as --robots-limit (default: 10000000)`,
+        `  --host=HOST                Evaluator target host (optional)`,
+        `  --port=PORT                Evaluator target port (optional)`,
+        `  --pass=SCORE               Pass threshold forwarded to evaluator as --pass (optional)`,
+        `  --timeout=MS               Kill eval process after timeout (default: 1200000)`,
+        `  --allow-learning=true      Allow learning during eval (default: frozen/disabled learning)`,
+        `  --main-arg=--k=v           Forward arg (repeatable). Example: --main-arg=--disable-adv=true`,
+        `  --grid=FLOAT               Grid step for float params (default: 0.1)`,
+        `  --grid-max=N               Max grid points per param (default: 200; step auto-expands if range too wide)`,
+        '',
+        'Optimization settings:',
+        `  --iters=N                  Passes over all params (default: 12)`,
+        `  --seed=N                   RNG seed (kept for logging/compat) (default: 1337)`,
+        `  --categorical-every=N      Try categorical vars on iter=1 and then every N iters (default: 2; 0 disables)`,
+        '',
+        'Logging:',
+        `  --log-dir=DIR              Output directory (default: ./optimization_logs)`,
+        `  --run=ID                   Run id (default: timestamp)`,
+        '',
+        'Notes:',
+        '  - This script evaluates by spawning the evaluator (test_automatic.cjs).',
+        '  - All model params are applied via evaluator feature (--model.* -> /api/model/params).'
+    ];
+    console.log(lines.join('\n'));
+};
+
+const coerceScalar = (value) => {
+    if (value === true) return true;
+    if (value === false) return false;
+    if (value == null) return value;
+    const s = String(value).trim();
+    if (!s) return s;
+    const low = s.toLowerCase();
+    if (low === 'true' || low === 'on' || low === 'yes') return true;
+    if (low === 'false' || low === 'off' || low === 'no') return false;
+    if (/^-?\d+(?:\.\d+)?$/.test(s)) return Number(s);
+    return s;
+};
+
+const clamp = (x, min, max) => {
+    if (!Number.isFinite(x)) return min;
+    return Math.max(min, Math.min(max, x));
+};
+
+const coerceNumber = (v, fallback) => {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : fallback;
+};
+
+// Build a deterministic grid of candidate values for one numeric param.
+// For very wide ranges, the step will auto-expand to keep total points <= maxPoints.
+const listGridValues = (spec, { step, maxPoints } = {}) => {
+    const min = Number(spec?.min);
+    const max = Number(spec?.max);
+    if (!Number.isFinite(min) || !Number.isFinite(max) || max < min) return [];
+
+    const isInt = Boolean(spec?.isInt);
+    let s = Number(step);
+    if (!Number.isFinite(s) || s <= 0) s = isInt ? 1 : 0.1;
+
+    const cap = Math.max(20, Math.floor(coerceNumber(maxPoints, 200)));
+
+    if (isInt) {
+        const stepInt = Math.max(1, Math.round(s));
+        const out = [];
+        for (let v = Math.ceil(min); v <= Math.floor(max); v += stepInt) {
+            out.push(v);
+            if (out.length >= cap) break;
+        }
+        const maxInt = Math.floor(max);
+        if (out.length && out[out.length - 1] !== maxInt && out.length < cap) out.push(maxInt);
+        return out;
+    }
+
+    // Float grid
+    const rough = Math.floor((max - min) / s) + 1;
+    if (rough > cap) {
+        s = (max - min) / (cap - 1);
+    }
+
+    const out = [];
+    let v = min;
+    for (let i = 0; i < cap; i++) {
+        const vv = Math.min(max, Math.max(min, Number(v.toFixed(10))));
+        out.push(vv);
+        if (vv >= max) break;
+        v += s;
+    }
+    if (out.length && out[out.length - 1] !== max && out.length < cap) out.push(max);
+    return out;
+};
+
+const deepClone = (obj) => JSON.parse(JSON.stringify(obj || {}));
+
+const stableStringify = (obj) => {
+    const seen = new WeakSet();
+    const sortKeys = (v) => {
+        if (!v || typeof v !== 'object') return v;
+        if (seen.has(v)) return null;
+        seen.add(v);
+        if (Array.isArray(v)) return v.map(sortKeys);
+        const keys = Object.keys(v).sort();
+        const out = {};
+        for (const k of keys) out[k] = sortKeys(v[k]);
+        return out;
+    };
+    return JSON.stringify(sortKeys(obj), null, 2);
+};
+
+const pickRandom = (arr, k, rng) => {
+    const a = arr.slice();
+    for (let i = a.length - 1; i > 0; i--) {
+        const j = Math.floor(rng() * (i + 1));
+        [a[i], a[j]] = [a[j], a[i]];
+    }
+    return a.slice(0, Math.max(0, Math.min(k, a.length)));
+};
+
+const makeRng = (seed) => {
+    // xorshift32
+    let x = (seed >>> 0) || 0x9e3779b9;
+    return () => {
+        x ^= x << 13;
+        x ^= x >>> 17;
+        x ^= x << 5;
+        return ((x >>> 0) / 0xffffffff);
+    };
+};
+
+const parseSummary = (combinedOutput) => {
+    const text = String(combinedOutput || '');
+    const mScore = text.match(/\[test_automatic\]\s+avgScore=([0-9.]+)/i);
+    const mPass = text.match(/\[test_automatic\]\s+avgScore=[0-9.]+\s+pass=(\d+)\/(\d+)/i);
+    const score = mScore ? Number(mScore[1]) : NaN;
+    const passed = mPass ? Number(mPass[1]) : NaN;
+    const total = mPass ? Number(mPass[2]) : NaN;
+    return {
+        avgScore: Number.isFinite(score) ? score : null,
+        passed: Number.isFinite(passed) ? passed : null,
+        total: Number.isFinite(total) ? total : null
+    };
+};
+
+const runEval = (testFile, {
+    robotsLimit,
+    frozen,
+    forwardMainArgs,
+    modelParams,
+    passThreshold,
+    host,
+    port,
+    timeoutMs
+}) => {
+    return new Promise((resolve) => {
+        const started = Date.now();
+
+        const args = [];
+        args.push(testFile);
+
+        if (host) args.push(`--host=${host}`);
+        if (port) args.push(`--port=${port}`);
+        if (passThreshold != null) args.push(`--pass=${passThreshold}`);
+
+        // Always maximize corpus as requested
+        if (robotsLimit != null) args.push(`--robots-limit=${robotsLimit}`);
+
+        // Freeze learning by default to keep evaluation comparable across steps
+        if (frozen) args.push('--disable-learning=true');
+
+        for (const a of (forwardMainArgs || [])) {
+            if (a && String(a).startsWith('--')) args.push(String(a));
+        }
+
+        // Model patch via test_automatic feature
+        for (const [k, v] of Object.entries(modelParams || {})) {
+            const raw = typeof v === 'string' ? v : String(v);
+            args.push(`--model.${k}=${raw}`);
+        }
+
+        const child = spawn(process.execPath, args, {
+            cwd: __dirname,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env }
+        });
+
+        let out = '';
+        let err = '';
+
+        const killTimer = timeoutMs
+            ? setTimeout(() => {
+                try {
+                    child.kill('SIGKILL');
+                } catch (_e) {
+                    // ignore
+                }
+            }, timeoutMs)
+            : null;
+
+        child.stdout.on('data', (d) => {
+            out += d.toString('utf8');
+        });
+        child.stderr.on('data', (d) => {
+            err += d.toString('utf8');
+        });
+
+        child.on('close', (code) => {
+            if (killTimer) clearTimeout(killTimer);
+            const elapsedMs = Date.now() - started;
+            const summary = parseSummary(out + '\n' + err);
+            resolve({
+                code,
+                elapsedMs,
+                stdout: out,
+                stderr: err,
+                ...summary
+            });
+        });
+    });
+};
+
+const loadMainModelSpec = (mainModulePath) => {
+    try {
+        // eslint-disable-next-line global-require, import/no-dynamic-require
+        const mod = require(mainModulePath);
+        const defaults = mod?.MODEL_DEFAULTS && typeof mod.MODEL_DEFAULTS === 'object' ? mod.MODEL_DEFAULTS : null;
+        const activations = Array.isArray(mod?.BUILTIN_ACTIVATION_TYPES) ? mod.BUILTIN_ACTIVATION_TYPES : null;
+        const transfers = Array.isArray(mod?.BUILTIN_TRANSFER_TYPES) ? mod.BUILTIN_TRANSFER_TYPES : null;
+        return { defaults, activations, transfers };
+    } catch (e) {
+        return { defaults: null, activations: null, transfers: null, error: e };
+    }
+};
+
+// 仅基于 main.cjs 真实存在的参数键生成可搜索空间（不虚构参数名）。
+// 这里的 min/max/eps/step 是优化器的超参，不属于 main 的“参数选项”。
+const buildSearchSpaceFromDefaults = (modelDefaults, { activationTypes, transferTypes } = {}) => {
+    const numeric = {};
+    const categorical = {};
+
+    if (!modelDefaults || typeof modelDefaults !== 'object') {
+        return { numeric, categorical };
+    }
+
+    const keys = Object.keys(modelDefaults);
+    for (const k of keys) {
+        const v = modelDefaults[k];
+        if (typeof v === 'number' && Number.isFinite(v)) {
+            const isInt = Number.isInteger(v);
+            // Heuristic bounds per common param family
+            let min;
+            let max;
+            let eps;
+            let step;
+
+            if (k === 'decayK') {
+                min = 0;
+                max = 12;
+                eps = 0.2;
+                step = 0.6;
+            } else if (k === 'decayFactor') {
+                min = 0.01;
+                max = 0.995;
+                eps = 0.03;
+                step = 0.08;
+            } else if (k === 'maliciousThreshold') {
+                min = 0;
+                max = 1;
+                eps = 0.05;
+                step = 0.1;
+            } else if (k === 'edgeWeight') {
+                min = 0.05;
+                max = 8;
+                eps = 0.25;
+                step = 0.6;
+            } else if (k.toLowerCase().includes('ngram')) {
+                min = 1;
+                max = 10;
+                eps = 1;
+                step = 1;
+            } else if (k.toLowerCase().includes('threshold')) {
+                min = 0;
+                max = 20;
+                eps = 1;
+                step = 1;
+            } else if (k.toLowerCase().includes('iteration')) {
+                min = 1;
+                max = 20;
+                eps = 1;
+                step = 1;
+            } else if (k.toLowerCase().includes('len')) {
+                min = 4;
+                max = 256;
+                eps = 4;
+                step = 4;
+            } else if (k.toLowerCase().includes('max')) {
+                min = 8;
+                max = 5000;
+                eps = isInt ? 8 : 0.5;
+                step = isInt ? 16 : 1;
+            } else if (k.toLowerCase().includes('decay')) {
+                min = 0;
+                max = 10;
+                eps = 0.25;
+                step = 0.5;
+            } else {
+                // default numeric range around default value
+                min = isInt ? 0 : Math.min(0, v - Math.abs(v) * 2);
+                max = isInt ? Math.max(4, v * 4 + 10) : Math.max(1, v + Math.abs(v) * 3 + 1);
+                eps = isInt ? 1 : 0.1;
+                step = isInt ? 1 : 0.25;
+            }
+
+            numeric[k] = { min, max, eps, step, isInt };
+        }
+    }
+
+    if (Array.isArray(activationTypes) && activationTypes.length) {
+        categorical.activationType = activationTypes.slice();
+    }
+    if (Array.isArray(transferTypes) && transferTypes.length) {
+        categorical.transferType = transferTypes.slice();
+    }
+
+    // Only keep categorical keys that actually exist in defaults
+    for (const k of Object.keys(categorical)) {
+        if (!(k in modelDefaults)) {
+            delete categorical[k];
+        }
+    }
+
+    return { numeric, categorical };
+};
+
+const normalizeParams = (params, space) => {
+    const out = { ...(params || {}) };
+
+    const numericSpace = space?.numeric && typeof space.numeric === 'object' ? space.numeric : {};
+    for (const [k, spec] of Object.entries(numericSpace)) {
+        if (out[k] == null) continue;
+        let v = Number(out[k]);
+        if (!Number.isFinite(v)) continue;
+        v = clamp(v, spec.min, spec.max);
+        if (spec.isInt) v = Math.round(v);
+        out[k] = v;
+    }
+
+    // dependency: memeNgramMin <= memeNgramMax
+    if (out.memeNgramMin != null && out.memeNgramMax != null) {
+        if (Number(out.memeNgramMin) > Number(out.memeNgramMax)) {
+            const tmp = out.memeNgramMin;
+            out.memeNgramMin = out.memeNgramMax;
+            out.memeNgramMax = tmp;
+        }
+    }
+
+    return out;
+};
+
+const validateNoUnknownKeys = ({ obj, allowedKeys, label }) => {
+    if (!obj || typeof obj !== 'object') return;
+    const unknown = Object.keys(obj).filter((k) => !allowedKeys.has(k));
+    if (unknown.length) {
+        const msg = `[optimization] ${label} contains unknown keys not in main.cjs modelDefaults: ${unknown.join(', ')}`;
+        throw new Error(msg);
+    }
+};
+
+const main = async () => {
+    const args = parseArgs(process.argv.slice(2));
+
+    if (args.help || args.h === true) {
+        printHelp({ mainDefault: DEFAULT_MAIN_MODULE, testDefault: DEFAULT_TEST });
+        process.exit(0);
+    }
+
+    const testFile = path.resolve(String(args.test || DEFAULT_TEST));
+    if (!fs.existsSync(testFile)) {
+        console.error('[optimization] test_automatic.cjs not found:', testFile);
+        process.exit(2);
+    }
+
+    const mainModulePath = path.resolve(String(args.main || DEFAULT_MAIN_MODULE));
+    const spec = loadMainModelSpec(mainModulePath);
+    if (!spec.defaults) {
+        console.error('[optimization] failed to load MODEL_DEFAULTS from main.cjs.');
+        console.error('[optimization] expected main.cjs to export MODEL_DEFAULTS/BUILTIN_ACTIVATION_TYPES/BUILTIN_TRANSFER_TYPES.');
+        if (spec.error) console.error('[optimization] load error:', spec.error.message);
+        process.exit(3);
+    }
+
+    const SPACE = buildSearchSpaceFromDefaults(spec.defaults, {
+        activationTypes: spec.activations,
+        transferTypes: spec.transfers
+    });
+    const allowedKeys = new Set(Object.keys(spec.defaults));
+
+    const robotsLimit = Number(args['robots-limit'] ?? 10000000);
+    const frozen = String(args['allow-learning'] || '').trim() ? false : true;
+
+    const host = args.host ? String(args.host) : undefined;
+    const port = args.port != null ? Number(args.port) : undefined;
+
+    const iterations = Math.max(1, Number(args.iters ?? 12));
+    const categoricalEvery = Math.max(0, Number(args['categorical-every'] ?? 2));
+    const pass = args.pass != null ? Number(args.pass) : undefined;
+    const timeoutMs = args.timeout != null ? Number(args.timeout) : 20 * 60 * 1000;
+
+    const seed = Number(args.seed ?? 1337);
+    // NOTE: optimizer is deterministic in coordinate/grid mode; seed kept for logging/compat.
+
+    const gridStep = coerceNumber(args.grid, 0.1);
+    const gridMax = Math.max(20, Math.floor(coerceNumber(args['grid-max'], 200)));
+
+    const logDir = path.resolve(String(args['log-dir'] || path.join(__dirname, 'optimization_logs')));
+    ensureDir(logDir);
+
+    const runId = String(args.run || nowStamp());
+    const logFile = path.join(logDir, `opt_${runId}.jsonl`);
+    const bestFile = path.join(logDir, `best_${runId}.json`);
+
+    const forwardMainArgs = Array.isArray(args.mainArgs) ? args.mainArgs : (args.mainArgs ? [args.mainArgs] : []);
+
+    let init = {};
+    if (args['init-json']) {
+        try {
+            init = JSON.parse(String(args['init-json']));
+        } catch (e) {
+            console.warn('[optimization] init-json parse failed:', e.message);
+        }
+    }
+
+    // init-json 允许设置所有真实参数（包括字符串参数），但不允许出现 main 未声明的键
+    validateNoUnknownKeys({ obj: init, allowedKeys, label: 'init-json' });
+
+    // Allow selecting subset of numeric params
+    const selectedNumeric = (() => {
+        const raw = args.params;
+        if (!raw) return Object.keys(SPACE.numeric).slice().sort();
+        const list = Array.isArray(raw) ? raw : [raw];
+        const parts = list.flatMap((x) => String(x).split(',').map((s) => s.trim()).filter(Boolean));
+        const allowed = new Set(Object.keys(SPACE.numeric));
+        const unknown = parts.filter((p) => !allowed.has(p));
+        if (unknown.length) {
+            throw new Error(`[optimization] --params contains unknown/non-numeric keys: ${unknown.join(', ')}`);
+        }
+        return parts;
+    })();
+
+    const selectedCategorical = (() => {
+        const raw = args.cats;
+        if (!raw) return Object.keys(SPACE.categorical).slice().sort();
+        const list = Array.isArray(raw) ? raw : [raw];
+        const parts = list.flatMap((x) => String(x).split(',').map((s) => s.trim()).filter(Boolean));
+        const allowed = new Set(Object.keys(SPACE.categorical));
+        const unknown = parts.filter((p) => !allowed.has(p));
+        if (unknown.length) {
+            throw new Error(`[optimization] --cats contains unknown/non-categorical keys: ${unknown.join(', ')}`);
+        }
+        return parts;
+    })();
+
+    const logLine = (obj) => {
+        fs.appendFileSync(logFile, JSON.stringify(obj) + '\n');
+    };
+
+    // current 包含所有 init-json 提供的真实键；数值键会按 SPACE 进行 clamp/round
+    let current = normalizeParams(init, SPACE);
+    let best = { params: deepClone(current), score: -Infinity, passed: null, total: null };
+
+    const evaluate = async (params, meta = {}) => {
+        // 不允许出现未知键（避免“虚构参数”）
+        validateNoUnknownKeys({ obj: params, allowedKeys, label: 'params' });
+        const normalized = normalizeParams(params, SPACE);
+        const result = await runEval(testFile, {
+            robotsLimit,
+            frozen,
+            forwardMainArgs,
+            modelParams: normalized,
+            passThreshold: pass,
+            host,
+            port,
+            timeoutMs
+        });
+
+        const entry = {
+            t: new Date().toISOString(),
+            runId,
+            seed,
+            meta,
+            robotsLimit,
+            frozen,
+            host: host || null,
+            port: port || null,
+            passThreshold: pass ?? null,
+            elapsedMs: result.elapsedMs,
+            exitCode: result.code,
+            avgScore: result.avgScore,
+            passed: result.passed,
+            total: result.total,
+            params: normalized
+        };
+        logLine(entry);
+
+        if (result.avgScore != null && result.avgScore > best.score) {
+            best = { params: deepClone(normalized), score: result.avgScore, passed: result.passed, total: result.total };
+            fs.writeFileSync(bestFile, stableStringify({
+                runId,
+                t: entry.t,
+                bestScore: best.score,
+                passed: best.passed,
+                total: best.total,
+                robotsLimit,
+                frozen,
+                host: host || null,
+                port: port || null,
+                passThreshold: pass ?? null,
+                params: best.params
+            }));
+        }
+
+        return { normalized, result };
+    };
+
+    console.log('[optimization] log:', logFile);
+    console.log('[optimization] best:', bestFile);
+    console.log('[optimization] main spec:', mainModulePath);
+    console.log('[optimization] robots-limit:', robotsLimit);
+    console.log('[optimization] frozen (disable-learning):', frozen);
+    console.log('[optimization] selected numeric params:', selectedNumeric.join(', '));
+    console.log('[optimization] selected categorical params:', selectedCategorical.join(', '));
+    console.log('[optimization] grid step (float):', gridStep);
+    console.log('[optimization] grid max points:', gridMax);
+
+    // baseline
+    const baseEval = await evaluate(current, { kind: 'baseline' });
+    let baseScore = baseEval.result.avgScore ?? -Infinity;
+    console.log(`[optimization] baseline avgScore=${baseEval.result.avgScore} pass=${baseEval.result.passed}/${baseEval.result.total}`);
+
+    const coordinateSweepNumericOnce = async ({ iter, startParams, startScore }) => {
+        let local = deepClone(startParams);
+        let localScore = startScore;
+
+        for (const key of selectedNumeric) {
+            const spec = SPACE.numeric[key];
+            if (!spec) continue;
+
+            const step = spec.isInt ? 1 : gridStep;
+            const values = listGridValues(spec, { step, maxPoints: gridMax });
+            if (!values.length) continue;
+
+            let bestVal = local[key];
+            let bestScoreLocal = localScore;
+
+            console.log(`[optimization] sweep ${key}: candidates=${values.length} (step=${spec.isInt ? 1 : step})`);
+            for (const v of values) {
+                const trial = deepClone(local);
+                trial[key] = v;
+                const ev = await evaluate(trial, { kind: 'coord', iter, key, v });
+                const s = ev.result.avgScore ?? -Infinity;
+                if (s >= bestScoreLocal) {
+                    bestScoreLocal = s;
+                    bestVal = v;
+                }
+            }
+
+            local[key] = bestVal;
+            local = normalizeParams(local, SPACE);
+            localScore = bestScoreLocal;
+            console.log(`[optimization] picked ${key}=${bestVal} score=${localScore}`);
+        }
+
+        return { params: local, score: localScore };
+    };
+
+    const sweepCategoricals = async ({ iter, startParams, startScore }) => {
+        let local = deepClone(startParams);
+        let localScore = startScore;
+
+        for (const catKey of selectedCategorical) {
+            const candidates = SPACE?.categorical?.[catKey] || [];
+            if (!Array.isArray(candidates) || candidates.length === 0) continue;
+
+            console.log(`[optimization] categorical ${catKey}: trying ${candidates.length} candidates in order`);
+
+            let bestParams = deepClone(local);
+            let bestScoreLocal = localScore;
+
+            for (const cand of candidates) {
+                const trialBase = deepClone(local);
+                trialBase[catKey] = cand;
+
+                const baseEv2 = await evaluate(trialBase, { kind: 'cat_base', iter, catKey, cand });
+                const baseS2 = baseEv2.result.avgScore ?? -Infinity;
+                const refined = await coordinateSweepNumericOnce({ iter, startParams: trialBase, startScore: baseS2 });
+
+                if (refined.score >= bestScoreLocal) {
+                    bestScoreLocal = refined.score;
+                    bestParams = refined.params;
+                    console.log(`[optimization] best so far for ${catKey}: ${cand} score=${bestScoreLocal}`);
+                }
+            }
+
+            local = deepClone(bestParams);
+            localScore = bestScoreLocal;
+            console.log(`[optimization] categorical picked ${catKey}=${local[catKey]} score=${localScore}`);
+        }
+
+        return { params: local, score: localScore };
+    };
+
+    for (let iter = 1; iter <= iterations; iter++) {
+        console.log(`\n[optimization] iter ${iter}/${iterations} (deterministic coordinate/grid)`);
+
+        // Categorical sweep: do it on iter=1, and then every N iterations if enabled.
+        if (selectedCategorical.length && (iter === 1 || (categoricalEvery > 0 && (iter % categoricalEvery === 0)))) {
+            const outCats = await sweepCategoricals({ iter, startParams: current, startScore: baseScore });
+            current = deepClone(outCats.params);
+            baseScore = outCats.score;
+        }
+
+        // Numeric sweep: one full pass in fixed order.
+        const outNum = await coordinateSweepNumericOnce({ iter, startParams: current, startScore: baseScore });
+        current = deepClone(outNum.params);
+        baseScore = outNum.score;
+
+        console.log(`[optimization] end iter ${iter}: score=${baseScore}`);
+        console.log(`[optimization] bestSoFar score=${best.score} pass=${best.passed}/${best.total}`);
+    }
+
+    console.log('\n[optimization] finished');
+    console.log('[optimization] best score:', best.score);
+    console.log('[optimization] best params written:', bestFile);
+    console.log('[optimization] full log:', logFile);
+};
+
+main().catch((err) => {
+    console.error('[optimization] fatal:', err);
+    process.exit(1);
+});