champollion 0.5.2 → 0.5.3

package/lib/command-help.js

@@ -711,7 +711,7 @@ const COMMAND_HELP = {
   },
 
   models: {
-    usage: 'champollion models --method <provider>',
+    usage: 'champollion models --method <provider> | champollion models check',
     description: [
       'Lists available models from a translation provider\'s API.',
       'Queries the provider\'s live model endpoint and displays all',
@@ -719,6 +719,7 @@ const COMMAND_HELP = {
     ],
     options: [
       ['--method <name>', 'Provider to query: gemini, openai, or anthropic (required)'],
+      ['check',           'Check every default model (shared/model-defaults.json) against the providers\' live lists; exit 1 if one is gone. Free (list endpoints are not billed)'],
       ['--json',          'Machine-readable JSON output (single document)'],
     ],
     examples: [

package/lib/commands/models.js

@@ -21,6 +21,8 @@ import { resolveConfig } from '../config.js';
 import { fetchAvailableModels, resolveProviderApiKey, getProviderLabel, getProviderEnvVar, isListableProvider, getListableProviders } from '../models.js';
 import { missingKeyAdvice } from '../missing-key.js';
 import { output } from '../output.js';
+import { checkModelDefaults } from '../model-defaults.js';
+import { fetchModelPricing } from '../methods/openrouter-pricing.js';
 
 /**
  * @param {import('../types.js').CLIArgs} args - Parsed CLI arguments
@@ -38,6 +40,8 @@ async function run(args, cwd) {
     return 0;
   }
 
+  if (args._[1] === 'check') return runCheck(args, cwd, json);
+
   const method = args.method;
   if (!method) {
     if (json) {
@@ -182,3 +186,49 @@ function showHelp() {
 }
 
 export { run };
+
+/**
+ * `champollion models check` — every default model (shared/model-defaults.json)
+ * against the providers' live lists. Read-only and free: list endpoints are
+ * not billed. Exit 1 when a pinned default is no longer listed (a run would
+ * fail on it); a newer model matching a role's rule is reported, not a
+ * failure — moving a default is a reviewed change, never automatic.
+ *
+ * @param {object} args
+ * @param {string} cwd
+ * @param {boolean} json
+ * @returns {Promise<number>}
+ */
+async function runCheck(args, cwd, json) {
+  const lists = { openrouter: null, openai: null, gemini: null, anthropic: null };
+  try {
+    const pricing = await fetchModelPricing();
+    if (pricing && pricing.size > 0) lists.openrouter = [...pricing.keys()];
+  } catch { /* unchecked */ }
+  for (const provider of ['openai', 'gemini', 'anthropic']) {
+    const key = resolveProviderApiKey(provider, cwd);
+    if (key) lists[provider] = await fetchAvailableModels(provider, key);
+  }
+  const rows = checkModelDefaults(lists);
+  const gone = rows.filter(r => r.status === 'gone');
+  if (json) {
+    console.log(JSON.stringify({ command: 'models check', ok: gone.length === 0, roles: rows }, null, 2));
+    return gone.length > 0 ? 1 : 0;
+  }
+  output.raw('\n  Default models (shared/model-defaults.json) against the providers\' live lists:\n');
+  for (const r of rows) {
+    const mark = { ok: '[OK]  ', newer: '[NEW] ', gone: '[GONE]', unchecked: '[--]  ' }[r.status];
+    output.raw(`  ${mark} ${r.role.padEnd(10)} ${r.model.padEnd(34)} ${r.note}`);
+  }
+  const unchecked = rows.filter(r => r.status === 'unchecked').map(r => r.provider);
+  if (unchecked.length > 0) {
+    output.raw(`\n  Not checked (no key for ${[...new Set(unchecked)].map(p => getProviderEnvVar(p) || p).join(', ')}): set it to check that provider's list.`);
+  }
+  output.raw('');
+  if (gone.length > 0) {
+    output.error(`${gone.length} default model(s) are no longer listed by their provider — a run on them would fail. `
+      + 'Update shared/model-defaults.json (in the repo: node cli/scripts/check-model-defaults.mjs --update) and release.');
+    return 1;
+  }
+  return 0;
+}

package/lib/config.js

@@ -11,6 +11,7 @@
  * complex setups with custom registers, models, and batch sizes.
  */
 
+import { defaultModel } from './model-defaults.js';
 import fs from 'node:fs';
 import path from 'node:path';
 import { DEFAULT_REGISTERS, getLanguageCard, getRegister, resolveCode } from './registers.js';
@@ -25,7 +26,8 @@ const CONFIG_FILENAMES = ['champollion.config.json'];
 
 // Canonical defaults — import these in any module that needs a fallback
 // instead of hardcoding the string/number inline.
-const DEFAULT_OPENROUTER_MODEL = 'google/gemini-3.8-flash';
+// shared/model-defaults.json, role "translate" — never written here (lib/model-defaults.js).
+const DEFAULT_OPENROUTER_MODEL = defaultModel('translate');
 const DEFAULT_BATCH_SIZE = 80;
 // Max parallel API calls for JSON key-value translation. 50 is kind to
 // free/low-tier keys on a zero-config first run (200 would hammer 429s).

package/lib/fallback.js

@@ -720,8 +720,9 @@ function sameAnswer(a, b) {
  * reason, the model either translates it or returns it unchanged again — and
  * a keep-as-written refusal (isKeepAsWrittenFault) answered the same way
  * twice is taken at its word, as the key-value lane takes a name. Every other
- * fault must clear the gate outright. One ask, never a loop; under --max-cost
- * it is billed like any other call (budget.approve).
+ * fault must clear the gate outright. One ask per block, alone (not in the
+ * page's batch), never a loop; under --max-cost it is billed like any other
+ * call (budget.approve).
  *
  * @param {object} p
  * @param {number[]} p.idx - Indices (into `missed`) the gate refused
@@ -752,17 +753,26 @@ async function retryRefusedBlocks({ idx, texts, missed, blocks, pairConfig, runB
     if (!verdict.ok) return accepted;
   }
   const retryNotes = new Map(idx.map(i => [texts[i], reasons.get(i)]));
-  let res = null;
-  try {
-    res = await runBatch(idx.map(i => texts[i]), { ...pairConfig, retryNotes });
-  } catch {
-    return accepted;
-  }
-  const fell = new Set(res?.fellBack || []);
-  idx.forEach((i, j) => {
-    if (!res || fell.has(j) || typeof res.blocks[j] !== 'string') return;
-    const restored = restoreBlocks(res.blocks[j], blocks);
-    const fault = blockFault(texts[i], res.blocks[j], restored, missed[i].source, pairConfig);
+  // Each block alone: away from the page's other segments, the model has one
+  // thing to do (and one reason to read). Refusals are rare, so the extra
+  // requests cost next to nothing; at most 4 at a time.
+  const answers1 = new Map();
+  let next = 0;
+  const worker = async () => {
+    while (next < idx.length) {
+      const i = idx[next++];
+      try {
+        const res = await runBatch([texts[i]], { ...pairConfig, retryNotes });
+        if (res && !(res.fellBack || []).includes(0) && typeof res.blocks[0] === 'string') answers1.set(i, res.blocks[0]);
+      } catch { /* no second answer for this block */ }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(4, idx.length) }, worker));
+  idx.forEach((i) => {
+    if (!answers1.has(i)) return;
+    const protectedOut = answers1.get(i);
+    const restored = restoreBlocks(protectedOut, blocks);
+    const fault = blockFault(texts[i], protectedOut, restored, missed[i].source, pairConfig);
     const insisted = isKeepAsWrittenFault(fault) && isKeepAsWrittenFault(reasons.get(i))
       && [firstOut.get(i), missed[i].source].some(v => sameAnswer(v, restored));
     if (!fault || insisted) accepted.set(i, restored);

package/lib/methods/anthropic.js

@@ -13,6 +13,7 @@
  * lives in DirectLLMMethod.
  */
 
+import { defaultModel } from '../model-defaults.js';
 import { DirectLLMMethod } from './direct-llm.js';
 import { fetchAvailableModels } from '../models.js';
 import { estimateLlmCost } from './provider-pricing.js';
@@ -21,7 +22,7 @@ import { estimateLlmCost } from './provider-pricing.js';
 // _getDefaultModel() and again as an inline `pairConfig.model || '...'`
 // fallback in estimateCost() — so the two could drift and price a run
 // against a model it did not use.
-const DEFAULT_MODEL = 'claude-sonnet-4-6';
+const DEFAULT_MODEL = defaultModel('anthropic'); // shared/model-defaults.json
 
 class AnthropicMethod extends DirectLLMMethod {
   constructor(options = {}) {

package/lib/methods/gemini.js

@@ -12,13 +12,14 @@
  * lives in DirectLLMMethod.
  */
 
+import { defaultModel } from '../model-defaults.js';
 import { DirectLLMMethod } from './direct-llm.js';
 import { fetchAvailableModels } from '../models.js';
 import { estimateLlmCost } from './provider-pricing.js';
 
 // The default model, named ONCE — it was previously written twice (here and
 // as an inline fallback in estimateCost()) and the two could drift.
-const DEFAULT_MODEL = 'gemini-3.8-flash';
+const DEFAULT_MODEL = defaultModel('gemini'); // shared/model-defaults.json
 
 class GeminiMethod extends DirectLLMMethod {
   constructor(options = {}) {

package/lib/methods/openai.js

@@ -13,15 +13,16 @@
  * lives in DirectLLMMethod.
  */
 
+import { defaultModel } from '../model-defaults.js';
 import { DirectLLMMethod } from './direct-llm.js';
 import { fetchAvailableModels } from '../models.js';
 import { estimateLlmCost } from './provider-pricing.js';
 
 // The default model, named ONCE — it was previously written twice (here and
 // as an inline fallback in estimateCost()) and the two could drift.
-// A dated snapshot: plain 'gpt-4o' was an alias OpenAI repoints (founder
-// ruling 2026-10-05: exact model ids only, nothing floating).
-const DEFAULT_MODEL = 'gpt-5.4-mini-2026-03-17';
+// shared/model-defaults.json: a dated snapshot (plain 'gpt-4o' was an alias
+// OpenAI repoints — founder ruling 2026-10-05: exact model ids only).
+const DEFAULT_MODEL = defaultModel('openai');
 
 class OpenAIMethod extends DirectLLMMethod {
   constructor(options = {}) {

package/lib/model-defaults.js

@@ -0,0 +1,113 @@
+/**
+ * model-defaults.js — the ONE place a default model comes from.
+ *
+ * WHY: the toolset's defaults were ten hand-written ids in seven files across
+ * five components (CLI, its three direct providers, the harness, forge, the
+ * MCP server, the site docent). Nothing kept them in step, so they drifted —
+ * the docent still named an undated `claude-haiku-4-5` after every other
+ * default had been made exact (founder, 2026-10-07: "we're gonna be getting
+ * our wires crossed no matter what doing it that way"). Every default now
+ * reads shared/model-defaults.json (bundled here as shared/model-defaults.json).
+ *
+ * A default is an exact id, fixed in that file — never resolved at run time:
+ * a run must say which model translated, and the translation memory is keyed
+ * by model, so a default that moved by itself would re-bill every cached
+ * string. What IS live is the check: `champollion models check` reads each
+ * provider's current list, fails when a pinned id is gone, and names the
+ * newest model each role's rule matches today.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FILE = path.join(__dirname, '..', 'shared', 'model-defaults.json');
+
+let _data = null;
+
+/** The parsed file. Missing or malformed is a broken install: fail loud. */
+export function modelDefaultsData() {
+  if (_data) return _data;
+  let raw;
+  try {
+    raw = fs.readFileSync(FILE, 'utf-8');
+  } catch (err) {
+    throw new Error(`${FILE} is missing (${err.code || err.message}): it names every default model. Reinstall champollion.`);
+  }
+  const data = JSON.parse(raw);
+  if (!data || typeof data.roles !== 'object') throw new Error(`${FILE} has no "roles" — it is not a model-defaults file.`);
+  _data = data;
+  return data;
+}
+
+/**
+ * The exact default model id for a role ("translate", "openai", "gemini",
+ * "anthropic", "harness", "docent"). Unknown role: a programming error.
+ *
+ * @param {string} role
+ * @returns {string}
+ */
+export function defaultModel(role) {
+  const r = modelDefaultsData().roles[role];
+  if (!r || typeof r.model !== 'string' || !r.model) throw new Error(`model-defaults.json has no "${role}" role.`);
+  return r.model;
+}
+
+/** Version string → comparable number array ("4-6" / "4.6" → [4, 6]). */
+function versionKey(v) {
+  return String(v || '0').split(/[.-]/).map((n) => Number(n) || 0);
+}
+
+function compareIds(a, b) {
+  const [va, vb] = [versionKey(a.v), versionKey(b.v)];
+  for (let i = 0; i < Math.max(va.length, vb.length); i++) {
+    if ((va[i] || 0) !== (vb[i] || 0)) return (va[i] || 0) - (vb[i] || 0);
+  }
+  return String(a.date || '').localeCompare(String(b.date || ''));
+}
+
+/**
+ * The newest id in a provider's live list that a role's rule matches, or null.
+ *
+ * @param {object} role - A roles[] entry ({ rule: { match } })
+ * @param {string[]} ids - The provider's live model ids
+ * @returns {string|null}
+ */
+export function ruleCandidate(role, ids) {
+  const re = new RegExp(role.rule.match);
+  const hits = [];
+  for (const id of ids || []) {
+    const m = re.exec(id);
+    if (m) hits.push({ id, v: m.groups?.v, date: m.groups?.date });
+  }
+  if (hits.length === 0) return null;
+  hits.sort(compareIds);
+  return hits[hits.length - 1].id;
+}
+
+/**
+ * Check every role against live lists.
+ *
+ * @param {Record<string, string[]|null>} lists - provider → live ids (null = could not be read)
+ * @returns {Array<{ role: string, provider: string, model: string, status: 'ok'|'newer'|'gone'|'unchecked', candidate: string|null, note: string }>}
+ */
+export function checkModelDefaults(lists) {
+  const out = [];
+  for (const [name, role] of Object.entries(modelDefaultsData().roles)) {
+    const ids = lists[role.provider];
+    if (!ids) {
+      out.push({ role: name, provider: role.provider, model: role.model, status: 'unchecked', candidate: null, note: `${role.provider}'s model list could not be read` });
+      continue;
+    }
+    const candidate = ruleCandidate(role, ids);
+    if (!ids.includes(role.model)) {
+      out.push({ role: name, provider: role.provider, model: role.model, status: 'gone', candidate, note: `${role.model} is no longer in ${role.provider}'s list${candidate ? ` — the rule's model today: ${candidate}` : ''}` });
+    } else if (candidate && candidate !== role.model) {
+      out.push({ role: name, provider: role.provider, model: role.model, status: 'newer', candidate, note: `a newer model matches the rule: ${candidate}` });
+    } else {
+      out.push({ role: name, provider: role.provider, model: role.model, status: 'ok', candidate, note: 'listed' });
+    }
+  }
+  return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "champollion",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Research-grade translation engine for i18n projects. Pluggable methods, per-pair quality tiers, and deterministic script converters. Supports JSON (next-intl, i18next), TOML, and YAML (Hugo).",
   "type": "module",
   "bin": {