champollion 0.4.0 → 0.5.1

package/lib/docusaurus-sync.js

@@ -74,7 +74,7 @@ import {
 import { walkFiles } from './locale-layout.js';
 import {
   readRefusals, contentHolds, nextRefusals, storeRefusals, blockUnit, fieldUnit, describeHeld, describeNewHold,
-  describeFallenBack, previewHeld, PAGE_UNIT, PAGE_NAME,
+  describeFallenBack, previewHeld, PAGE_UNIT, PAGE_NAME, pendingLockValue, isPendingLock,
 } from './content-refusals.js';
 import { applyNamedKeyRule, reportUnmatchedKeys, unmatchedKeysSummary, reportNamedFromCache } from './named-keys.js';
 
@@ -248,7 +248,9 @@ function scanDocusaurusContentWork(contentSources, pairEntries, config, manifest
               action = 'changed';
             }
           } else {
-            // No stored hash — check for [EN] fallback markers. This runs
+            // No stored hash — check for legacy [EN] fallback markers (pages
+            // written before 2026-10-05; now such a page has a pending:<hash>
+            // lock entry instead). This runs
             // even under --force-content: a target with no lock entry and
             // no [EN] markers is a genuine hand-translated file, and force
             // must never overwrite human work with machine output.
@@ -1372,6 +1374,9 @@ async function runDocusaurusSync(options, config, cwd, resolveRuntime) {
           // Each field is cached on its own source text (exactly like a
           // key-value sync key): a title edit re-pays only the title.
           const translatedFields = {};
+          // A field left in the source language (refused, or held from an
+          // earlier refusal): the page is written, its lock marked pending.
+          let fieldsLeftInSource = false;
           if (hasFrontMatter && Object.keys(fieldsToTranslate).length > 0) {
             const { hits: fmHits, misses: fmMisses } = partitionByTM(
               tm, fieldsToTranslate, Object.keys(fieldsToTranslate), code, tmKey
@@ -1393,14 +1398,16 @@ async function runDocusaurusSync(options, config, cwd, resolveRuntime) {
             if (Object.keys(fbCache.hits).length > 0) notePage(pairKey, label);
             const fieldsToSend = fbCache.misses;
             for (const f of Object.keys(translatedFields)) refusal.filled.add(fieldUnit(f));
-            // Refused before: a held field fails its page as a refused one
-            // does — nothing of it is sent, nothing written, lock not advanced.
+            // Refused before: a held field is not sent again; it keeps its
+            // source text and the page is written (its lock marked pending).
             const heldFields = fieldsToSend.filter(f => holds.field(f, fieldsToTranslate[f]) === 'held');
             const fallbackOnlyFields = new Set(fieldsToSend.filter(f => holds.field(f, fieldsToTranslate[f]) === 'fallback-only'));
             if (heldFields.length > 0) {
-              const err = new Error('held');
-              err.heldNames = heldFields.map(f => `front matter "${f}"`);
-              throw err;
+              fieldsLeftInSource = true;
+              const names = heldFields.map(f => `front matter "${f}"`);
+              refusal.held.push(...names);
+              output.warn(describeHeld({ file: label, code, pairKey, pairConfig, names }));
+              for (const f of heldFields) fieldsToSend.splice(fieldsToSend.indexOf(f), 1);
             }
 
             if (fieldsToSend.length > 0) {
@@ -1420,9 +1427,9 @@ async function runDocusaurusSync(options, config, cwd, resolveRuntime) {
                 budget: fallbackBudget,
                 sharedOutputs: sharedOutputsFor(code),
                 label: `${docLabel} front matter`,
-                translate: (keys, cfg) => translateBatch(
+                translate: (keys, cfg, extra = {}) => translateBatch(
                   keys, fieldsToTranslate, cfg,
-                  { apiKey, model: cfg.model, batchSize: cfg.batchSize || 30 },
+                  { apiKey, model: cfg.model, batchSize: cfg.batchSize || 30, ...extra },
                 ),
                 fallbackOnly: fallbackOnlyFields,
               });
@@ -1432,18 +1439,16 @@ async function runDocusaurusSync(options, config, cwd, resolveRuntime) {
                 refusal.refused.push({ unit: fieldUnit(field), source: fieldsToTranslate[field], methods });
               }
               if (fm.hollowed.length > 0) {
-                const h = fm.hollowed[0];
-                const err = new Error(
-                  `Docusaurus content sync for ${code}: front matter "${h.field}" — ${h.reason}.\n` +
-                  `  source: ${JSON.stringify(fieldsToTranslate[h.field])}\n` +
-                  `  got:    ${JSON.stringify(h.value)}\n` +
-                  (h.fallbackReason ? `  the fallback (${pairConfig.fallback.method}) failed it too: ${h.fallbackReason}\n` : '') +
-                  '  Nothing was written or cached. If this is a low-coverage target\n' +
-                  '  language, the model has no vocabulary for this string.\n' +
-                  `  ${describeNewHold({ file: label, pairKey, pairConfig, count: fm.hollowed.length })}`
-                );
-                err.heldNext = true;
-                throw err;
+                // Refused, and refused again when asked with the reason: the
+                // field keeps its source text; the page is still written.
+                fieldsLeftInSource = true;
+                for (const h of fm.hollowed) {
+                  output.warn(
+                    `${label} → ${code}: front matter "${h.field}" kept in the source language — ${h.reason}`
+                    + `${h.fallbackReason ? `; the fallback (${pairConfig.fallback.method}): ${h.fallbackReason}` : ''}.`
+                  );
+                }
+                output.warn(describeNewHold({ file: label, pairKey, pairConfig, count: fm.hollowed.length }));
               }
               if (fm.noResults) {
                 // Front matter translation failed — loud error
@@ -1461,9 +1466,10 @@ async function runDocusaurusSync(options, config, cwd, resolveRuntime) {
               // by the pair's method — the page is held, as with no fallback.
               const unfilled = [...fallbackOnlyFields].filter(f => !(f in fm.translated));
               if (unfilled.length > 0) {
-                const err = new Error('held');
-                err.heldNames = unfilled.map(f => `front matter "${f}"`);
-                throw err;
+                fieldsLeftInSource = true;
+                const names = unfilled.map(f => `front matter "${f}"`);
+                refusal.held.push(...names);
+                output.warn(describeHeld({ file: label, code, pairKey, pairConfig, names }));
               }
               Object.assign(translatedFields, fm.translated);
               for (const f of Object.keys(fm.translated)) refusal.filled.add(fieldUnit(f));
@@ -1583,7 +1589,7 @@ async function runDocusaurusSync(options, config, cwd, resolveRuntime) {
                 }));
 
                 const missed = [];
-                const heldBlocks = []; // refused before: not sent, '[EN] ' kept
+                const heldBlocks = []; // refused before: not sent, the source text kept
                 let position = 0; // place among the translatable blocks
                 for (const r of rendered) {
                   if (r.seg.type !== 'translatable') {
@@ -1603,8 +1609,8 @@ async function runDocusaurusSync(options, config, cwd, resolveRuntime) {
                   const hold = holds.block(r.source);
                   if (hold === 'held') {
                     // Refused before by this method (and its fallback): the
-                    // honest last resort stays, nothing is sent or billed.
-                    r.out = restoreBlocks(config.fallbackPrefix + r.seg.text, blocks);
+                    // source text stays, nothing is sent or billed.
+                    r.out = r.source;
                     heldBlocks.push(r);
                     continue;
                   }
@@ -1615,7 +1621,7 @@ async function runDocusaurusSync(options, config, cwd, resolveRuntime) {
                   bodyUsedFallback = true;
                   const names = heldBlocks.map(r => `paragraph ${r.pos + 1}`);
                   refusal.held.push(...names);
-                  output.warn(describeHeld({ file: label, code, pairKey, pairConfig, names, fallbackPrefix: config.fallbackPrefix }));
+                  output.warn(describeHeld({ file: label, code, pairKey, pairConfig, names }));
                 }
 
                 if (missed.length > 0) {
@@ -1624,14 +1630,13 @@ async function runDocusaurusSync(options, config, cwd, resolveRuntime) {
                   // batch → one missing-segments-only retry → (with a
                   // fallback method: one batch through it for every block the
                   // primary dropped or damaged — lib/fallback.js) → honest
-                  // '[EN] '-prefixed source for anything still missing. A
+                  // the source text, unmarked, for anything still missing. A
                   // duplicate/unknown marker or an empty first response
                   // still fails the file whole when no fallback rescues it.
                   const outcome = await translateBlocksWithFallback({
                     missed,
                     blocks,
                     pairConfig,
-                    fallbackPrefix: config.fallbackPrefix,
                     budget: fallbackBudget,
                     sharedOutputs: sharedOutputsFor(code),
                     label: docLabel,
@@ -1639,7 +1644,6 @@ async function runDocusaurusSync(options, config, cwd, resolveRuntime) {
                       texts,
                       buildPrompt: (t) => buildBlockBatchPrompt(t, cfg, { ...promptOptions, pageTitle }),
                       callModel: (prompt) => translateRawContent(prompt, { apiKey, pairConfig: cfg }),
-                      fallbackPrefix: config.fallbackPrefix,
                     }),
                     fallbackOnly: new Set(missed.flatMap((r, i) => (r.fallbackOnly ? [i] : []))),
                   });
@@ -1664,7 +1668,7 @@ async function runDocusaurusSync(options, config, cwd, resolveRuntime) {
                   }
                   if ((outcome.refused || []).length > 0) {
                     output.warn(
-                      `Docusaurus body for ${code}: ${outcome.refused.length} block(s) of ${dirName}/${relPath} refused by the quality gate — `
+                      `Docusaurus body for ${code}: ${outcome.refused.length} block(s) of ${dirName}/${relPath} refused by the quality gate, also when asked again with the reason — `
                       + outcome.refused.slice(0, 3).map(r => `paragraph ${r.block}: ${r.reason}`).join('; ')
                       + `${outcome.refused.length > 3 ? '; …' : ''}.`
                     );
@@ -1680,8 +1684,7 @@ async function runDocusaurusSync(options, config, cwd, resolveRuntime) {
                           : 'missing from the model response after a retry';
                     output.warn(
                       `Docusaurus body for ${code}: ${fellBack.length} of ${missed.length} ` +
-                      `block(s) ${why} — written as ` +
-                      `'${config.fallbackPrefix}'-prefixed source. ` +
+                      `block(s) ${why} — left in the source language, unmarked (\`champollion status\` lists them). ` +
                       describeFallenBack({
                         file: label, pairKey, pairConfig, fellBack: fellBack.length, newlyHeld, refusedBy: outcome.refusedBy,
                       })
@@ -1721,7 +1724,7 @@ async function runDocusaurusSync(options, config, cwd, resolveRuntime) {
 
               // Content-preservation check on the REASSEMBLED body — same
               // lane, same reasoning as the front matter above. Skipped for a
-              // fallback body: it deliberately carries '[EN] '-prefixed
+              // fallback body: it deliberately carries untranslated
               // source text and is neither cached nor lock-advanced already.
               const bodyHollowed = !bodyUsedFallback && checkContentPreservation(body, translatedBody);
               if (bodyHollowed) {
@@ -1736,7 +1739,7 @@ async function runDocusaurusSync(options, config, cwd, resolveRuntime) {
               // Store per-block AND whole-body entries only after the check
               // passes (whole-body makes reverts/lock-loss re-runs free). A
               // fallback body is NEVER stored whole — it contains
-              // untranslated '[EN] ' text.
+              // untranslated source text.
               for (const s of pendingBlockStores) {
                 storeTM(tm, s.source, code, s.tmKey, s.translation);
               }
@@ -1759,10 +1762,9 @@ async function runDocusaurusSync(options, config, cwd, resolveRuntime) {
           // keeps its old entry (or none), so it re-fires next sync — as
           // does a fallback body (its re-fire is TM-cheap: only the
           // fallen-back segment re-bills).
-          if (!bodyUsedFallback) {
-            updatedDocuManifest[manifestKey] = sourceHash;
-            manifestDirty = true;
-          }
+          updatedDocuManifest[manifestKey] = !bodyUsedFallback && !fieldsLeftInSource
+            ? sourceHash : pendingLockValue(sourceHash);
+          manifestDirty = true;
 
         } catch (contentErr) {
           if (contentErr.heldNames) {
@@ -1774,7 +1776,6 @@ async function runDocusaurusSync(options, config, cwd, resolveRuntime) {
             settleRefusals();
             output.warn(describeHeld({
               file: `${dirName}/${relPath}`, code, pairKey, pairConfig, names: contentErr.heldNames, pageHeld: true,
-              fallbackPrefix: config.fallbackPrefix,
             }));
             completed++;
             output.raw(`    [${completed}/${totalWork}] ${dirName}/${relPath} → ${code} [HELD]`);

package/lib/fallback.js

@@ -27,9 +27,9 @@ import { estimateCost } from './pairs.js';
 import { lookupTM, lookupTMValidated, tmMethodKey } from './tm.js';
 import { createTMEvictor } from './tm-evict.js';
 import { translatableBlockSources } from './content-estimate.js';
-import { checkContentPreservation, contentGateFault, sharedOutputReason } from './validate.js';
+import { checkContentPreservation, contentGateFault, sharedOutputReason, isKeepAsWrittenFault } from './validate.js';
 import { restoreBlocks, hasOrphanedPlaceholders, PLACEHOLDER_PREFIX, PLACEHOLDER_SUFFIX } from './content.js';
-import { EST_CHARS_PER_KEY } from './config.js';
+import { contentKeyUnits } from './config.js';
 import { output } from './output.js';
 import { refusalCategory, notePrimaryReason } from './refusal-category.js';
 
@@ -125,8 +125,8 @@ export function createFallbackBudget({ maxCost = null, committed = 0, cwd = null
  * @param {number} chars
  * @returns {number}
  */
-export function charsToKeyUnits(chars) {
-  return Math.ceil(chars / EST_CHARS_PER_KEY);
+export function charsToKeyUnits(chars, pairConfig = {}) {
+  return contentKeyUnits(chars, pairConfig);
 }
 
 // ── Reporting ────────────────────────────────────────────────────────
@@ -546,6 +546,45 @@ export async function translateFieldsWithFallback({
       stores.push({ text: fields[field], value, tmKey: primaryKey });
     }
     remember(passing.filter(([field]) => !shared.has(field)));
+
+    // Refused: asked once more, with the reason (the key-value lane's
+    // feedback retry, and retryRefusedBlocks for blocks). A keep-as-written
+    // refusal answered the same way twice is taken at its word.
+    const refusedFields = [...failed].filter(([, f]) => f.reason && !f.fallbackOnly).map(([field]) => field);
+    if (refusedFields.length > 0) {
+      const descriptions = {};
+      for (const field of refusedFields) {
+        const f = failed.get(field);
+        descriptions[field] = `RETRY: a previous translation ("${String(f.value ?? '').slice(0, 60)}") was refused by an automatic quality check: ${f.reason}. `
+          + `Translate this ${field} into ${pairConfig.name || pairConfig.target}. If it is correct exactly as written — a name, title, acronym or code — return it unchanged.`;
+      }
+      const chars = refusedFields.reduce((n, f) => n + fields[f].length, 0);
+      const deaf = pairConfig.acceptsInstructions === false;
+      const verdict = deaf ? { ok: false } : budget ? await budget.approve(charsToKeyUnits(chars, pairConfig), pairConfig) : { ok: true };
+      // Declared deaf: not asked again; its first answer is judged as a second one.
+      let again = deaf ? Object.fromEntries(refusedFields.map(f => [f, failed.get(f).value])) : null;
+      if (verdict.ok) {
+        try { again = await translate(refusedFields, pairConfig, { descriptions }); } catch { again = null; }
+      }
+      const againPassing = [];
+      for (const field of refusedFields) {
+        const value = again?.[field];
+        if (typeof value !== 'string') continue;
+        const f = failed.get(field);
+        const fault = contentGateFault(fields[field], value, pairConfig);
+        const insisted = isKeepAsWrittenFault(fault) && isKeepAsWrittenFault(f.reason) && value === f.value;
+        if (!fault || insisted) againPassing.push([field, value]);
+        else f.reason = `${f.reason}; asked again with that reason: ${fault}`;
+      }
+      const againShared = sharedCheck(againPassing);
+      for (const [field, value] of againPassing) {
+        if (againShared.has(field)) continue;
+        translated[field] = value;
+        stores.push({ text: fields[field], value, tmKey: primaryKey });
+        failed.delete(field);
+      }
+      remember(againPassing.filter(([field]) => !againShared.has(field)));
+    }
   } else if (fb) {
     for (const field of primaryAsked) failed.set(field, { reason: null });
   }
@@ -563,7 +602,7 @@ export async function translateFieldsWithFallback({
       notePrimaryReason(report, refusalCategory(f.reason, { sharedOutput: !!f.sharedOutput, heldBefore: !!f.fallbackOnly, noAnswer: !f.reason }));
     }
     const chars = asked.reduce((n, f) => n + fields[f].length, 0);
-    const verdict = budget ? await budget.approve(charsToKeyUnits(chars), fb) : { ok: true };
+    const verdict = budget ? await budget.approve(charsToKeyUnits(chars, fb), fb) : { ok: true };
     if (!verdict.ok) {
       report.skipped = { reason: verdict.reason, items: asked.map(f => `front matter "${f}"`) };
     } else {
@@ -659,12 +698,73 @@ export function blockFault(protectedSource, protectedOut, restoredOut, restoredS
   return contentGateFault(restoredSource, restoredOut, pairConfig);
 }
 
+/**
+ * Ask the pair's method once more for the blocks the gate refused, telling it
+ * why. WHY: a refusal used to be final for the run, and the block was left in
+ * the source language — while a good share of refusals are the model keeping
+ * text that is correct as written (a name heading, a citation, a table of
+ * codes), which no fixed rule can tell from a missed translation (dogfood
+ * 2026-10-05: 0.5% of 40,352 accepted blocks of champollion.dev). Told the
+ * 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).
+ *
+ * @param {object} p
+ * @param {number[]} p.idx - Indices (into `missed`) the gate refused
+ * @param {string[]} p.texts - The protected block texts
+ * @param {Array<{source: string}>} p.missed
+ * @param {Map<string,string>} p.blocks - protectBlocks() map
+ * @param {object} p.pairConfig
+ * @param {Function} p.runBatch
+ * @param {Map<number,string>} p.firstOut - The refused (restored) answers
+ * @param {Map<number,string>} p.reasons - Why each was refused; a block asked
+ *   again and refused again gets the second reason appended
+ * @param {object|null} [p.budget]
+ * @returns {Promise<Map<number,string>>} index → accepted (restored) answer
+ */
+async function retryRefusedBlocks({ idx, texts, missed, blocks, pairConfig, runBatch, firstOut, reasons, budget = null }) {
+  const accepted = new Map();
+  if (idx.length === 0) return accepted;
+  // An endpoint that declares it follows no instructions (a trained NMT
+  // model) would answer the same: not asked again — its first answers are
+  // judged as second answers are (the key-value lane's rule).
+  if (pairConfig.acceptsInstructions === false) {
+    for (const i of idx) if (isKeepAsWrittenFault(reasons.get(i))) accepted.set(i, firstOut.get(i));
+    return accepted;
+  }
+  if (budget) {
+    const chars = idx.reduce((n, i) => n + missed[i].source.length, 0);
+    const verdict = await budget.approve(charsToKeyUnits(chars, pairConfig), pairConfig);
+    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);
+    const insisted = isKeepAsWrittenFault(fault) && isKeepAsWrittenFault(reasons.get(i)) && restored === firstOut.get(i);
+    if (!fault || insisted) accepted.set(i, restored);
+    else reasons.set(i, `${reasons.get(i)}; asked again with that reason: ${fault}`);
+  });
+  return accepted;
+}
+
 /**
  * Translate the Markdown blocks the TM ladder did not hold: one batch through
  * the pair's method, then one batch through its fallback for every block the
  * primary dropped or damaged. A block both fail is written as
- * `fallbackPrefix` + its source — the honest '[EN] ' last resort (never
- * cached; the caller does not advance the file's lock).
+ * its source text, unmarked (never cached; the caller records the refusal,
+ * does not advance the file's lock, and reports it). A refused block is first
+ * asked again once, with the reason (retryRefusedBlocks).
  *
  * Without a fallback this is exactly the lanes' old block path: the primary's
  * output stands, its dropped blocks carry the prefix, and a structural
@@ -686,16 +786,16 @@ export function blockFault(protectedSource, protectedOut, restoredOut, restoredS
  * @param {import('./validate.js').SharedOutputIndex|null} [p.sharedOutputs] - The
  *   locale's different-inputs-same-output index: a block answered with the
  *   text the model gave for other source strings is refused like a damaged
- *   one (the fallback gets it; without one, the honest '[EN] ' last resort)
+ *   one (the fallback gets it; without one, the source text stands)
  * @param {string} [p.label] - Names the blocks in that index ("posts/a.md")
  * @param {Set<number>} [p.fallbackOnly] - Indices (into `missed`) of blocks the
  *   pair's method refused before (lib/content-refusals.js): not sent to it,
- *   only to the fallback ('[EN] ' when the fallback does not translate them)
+ *   only to the fallback (the source text stands when the fallback does not translate them)
  * @returns {Promise<{ outs: string[], stores: Array<{source: string, translation: string, tmKey: string}>,
  *   fellBack: number[], fromFallback: number, report: FallbackReport|null, sharedOutput: number[],
  *   refused: Array<{ i: number, block: number, reason: string }>, refusedBy: string[][] }>} refused: blocks written as the
- *   '[EN] ' last resort because the gate refused them (block = place among the page's blocks, from 1);
- *   refusedBy[i]: the method keys whose answer for block i the gate refused, for blocks left as '[EN] '
+ *   source text because the gate refused them (block = place among the page's blocks, from 1);
+ *   refusedBy[i]: the method keys whose answer for block i the gate refused, for blocks left in the source language
  *   (empty for the rest) — the lane remembers them
  */
 export async function translateBlocksWithFallback({
@@ -728,7 +828,7 @@ export async function translateBlocksWithFallback({
   };
   // Why the gate refused a block (index → reason), for the lane's warning.
   const refusedReason = new Map();
-  /** Blocks written as the '[EN] ' last resort because the gate refused them. */
+  /** Blocks left as their source text because the gate refused them. */
   const refusedList = (fellBack) => fellBack.filter(i => refusedReason.has(i))
     .map(i => ({ i, block: (Number.isInteger(missed[i].pos) ? missed[i].pos : i) + 1, reason: refusedReason.get(i) }));
 
@@ -744,12 +844,27 @@ export async function translateBlocksWithFallback({
       if (fault) refusedReason.set(i, fault);
     }
     const shared = sharedFault(outs.map((out, i) => ({ i, out })).filter(({ i }) => !fellSet.has(i) && !refusedReason.has(i)));
+    for (const i of shared) refusedReason.set(i, 'the same text the model gave for other, different source strings');
+    // Refused: asked once more, with the reason.
+    const again = await retryRefusedBlocks({
+      idx: [...refusedReason.keys()], texts, missed, blocks, pairConfig, runBatch,
+      firstOut: new Map([...refusedReason.keys()].map(i => [i, outs[i]])), reasons: refusedReason, budget,
+    });
+    const againShared = sharedFault([...again].map(([i, out]) => ({ i, out })));
+    for (const [i, out] of again) {
+      if (againShared.has(i)) continue;
+      outs[i] = out;
+      refusedReason.delete(i);
+      shared.delete(i);
+    }
+    // A memorized answer is reported as one (sharedOutput), not as a refusal.
+    for (const i of shared) refusedReason.delete(i);
     const stores = [];
     const accepted = [];
     outs.forEach((out, i) => {
       if (shared.has(i) || refusedReason.has(i)) {
-        // Refused: the honest last resort, never cached.
-        outs[i] = restoreBlocks(fallbackPrefix + texts[i], blocks);
+        // Refused twice: the source text stands, never cached.
+        outs[i] = missed[i].source;
         fellBack.push(i);
         primaryRefused.add(i);
         return;
@@ -812,6 +927,29 @@ export async function translateBlocksWithFallback({
       stores.push({ source: missed[i].source, translation: out, tmKey: primaryKey });
     }
     remember(good.filter(({ i }) => !shared.has(i)));
+    // Refused (not dropped, not held before): asked once more, with the reason.
+    const firstOut = new Map();
+    for (const i of failed) {
+      if (sharedIdx.has(i)) refusedReason.set(i, 'the same text the model gave for other, different source strings');
+      if (refusedReason.has(i)) firstOut.set(i, restoreBlocks(primary.blocks[i], blocks));
+    }
+    const again = await retryRefusedBlocks({
+      idx: [...firstOut.keys()], texts, missed, blocks, pairConfig, runBatch, firstOut, reasons: refusedReason, budget,
+    });
+    const againShared = sharedFault([...again].map(([i, out]) => ({ i, out })));
+    const recovered = new Set();
+    for (const [i, out] of again) {
+      if (againShared.has(i)) continue;
+      outs[i] = out;
+      stores.push({ source: missed[i].source, translation: out, tmKey: primaryKey });
+      refusedReason.delete(i);
+      sharedIdx.delete(i);
+      primaryRefused.delete(i);
+      recovered.add(i);
+    }
+    remember([...again].filter(([i]) => recovered.has(i)).map(([i, out]) => ({ i, out })));
+    if (recovered.size > 0) failed.splice(0, failed.length, ...failed.filter(i => !recovered.has(i)));
+    for (const i of sharedIdx) refusedReason.delete(i);
   } else {
     for (let i = 0; i < texts.length; i++) failed.push(i);
   }
@@ -831,7 +969,7 @@ export async function translateBlocksWithFallback({
   if (failed.length === 0) return { outs, stores, fellBack, fromFallback: 0, report, sharedOutput: [], refused: [], refusedBy: refusedByOf([]) };
 
   const chars = failed.reduce((n, i) => n + missed[i].source.length, 0);
-  const verdict = budget ? await budget.approve(charsToKeyUnits(chars), fb) : { ok: true };
+  const verdict = budget ? await budget.approve(charsToKeyUnits(chars, fb), fb) : { ok: true };
   if (!verdict.ok) {
     report.skipped = { reason: verdict.reason, items: failed.map(i => `block ${i + 1} of ${texts.length}`) };
     if (primaryError) throw primaryError;
@@ -841,7 +979,7 @@ export async function translateBlocksWithFallback({
     for (const i of failed) {
       if (sharedIdx.has(i) || primaryFell.has(i) || refusedReason.has(i) || fallbackOnly.has(i)) {
         outs[i] = sharedIdx.has(i) || refusedReason.has(i) || fallbackOnly.has(i)
-          ? restoreBlocks(fallbackPrefix + texts[i], blocks) : restoreBlocks(primary.blocks[i], blocks);
+          ? missed[i].source : restoreBlocks(primary.blocks[i], blocks);
         fellBack.push(i);
         continue;
       }
@@ -893,8 +1031,8 @@ export async function translateBlocksWithFallback({
       fromFallback++;
       continue;
     }
-    // Both methods failed this block: the honest last resort.
-    outs[i] = restoreBlocks(fallbackPrefix + texts[i], blocks);
+    // Both methods failed this block: the source text stands.
+    outs[i] = missed[i].source;
     fellBack.push(i);
   }
   return {
@@ -947,7 +1085,7 @@ export async function translatePageWithFallback({ body, blocks, pairConfig, runP
     ? refusalCategory(null, { heldBefore: true })
     : refusalCategory(primaryBody === null ? null : 'content lost or changed', { noAnswer: primaryBody === null }));
 
-  const verdict = budget ? await budget.approve(charsToKeyUnits(body.length), fb) : { ok: true };
+  const verdict = budget ? await budget.approve(charsToKeyUnits(body.length, fb), fb) : { ok: true };
   if (!verdict.ok) {
     report.skipped = { reason: verdict.reason, items: ['the page body'] };
     return { body: null, primaryBody, tmKey: null, report, refusedBy };

package/lib/locale-state.js

@@ -65,6 +65,7 @@ import path from 'node:path';
 import { hashValue } from './hash.js';
 import { tmTranslationsOf, tmTranslationSet, tmMethodKey } from './tm.js';
 import { tmProofTextsFor } from './tm-evict.js';
+import { GATE_VERSION } from './validate.js';
 
 /** Where replaced hand edits are recorded: the project root, tracked in git. */
 export const REPLACED_EDITS_FILENAME = '.champollion-replaced-edits.jsonl';
@@ -269,6 +270,8 @@ export function refusedBy(record, sourceValue, methodKey) {
  * @returns {'send'|'fallback-only'|'held'}
  */
 export function holdState(record, sourceValue, pairConfig) {
+  // A refusal by an earlier gate lifts by itself (validate.js GATE_VERSION).
+  if (!record || record.gate !== GATE_VERSION) return 'send';
   if (typeof sourceValue !== 'string' || !refusedBy(record, sourceValue, tmMethodKey(pairConfig))) return 'send';
   if (pairConfig.fallback && !refusedBy(record, sourceValue, tmMethodKey(pairConfig.fallback))) return 'fallback-only';
   return 'held';
@@ -294,6 +297,7 @@ export function recordRefusal(localeState, lockKey, sourceValue, methods, { redo
     source: src,
     methods: [...new Set([...known, ...methods])],
     on: new Date().toISOString().slice(0, 10),
+    gate: GATE_VERSION,
     ...(redo && { redo: true }),
   };
 }

package/lib/methods/direct-llm.js

@@ -27,7 +27,7 @@
  *   set of abstract methods to provide provider-specific HTTP details.
  *
  * RUNTIME MODEL VALIDATION:
- *   An OpenRouter-style id ("openai/gpt-5.5", or an alias for one) becomes
+ *   An OpenRouter-style id ("openai/gpt-5.5") becomes
  *   the provider's own name, or is refused when the provider has none
  *   (resolveModelId — pairs.js applies it when the pair graph is built).
  *   On first translate() call, the base class fetches the provider's available
@@ -46,7 +46,7 @@ import path from 'node:path';
 import { LLMMethod, buildSystemMessage, buildUserMessage, promptSettingsFor, isUnsafeKey } from './llm.js';
 import { captureRequest, isCapturing, PREVIEW_KEY } from './request-capture.js';
 import { projectGlossary } from './coaching-data.js';
-import { resolveModel } from '../models.js';
+import { requireExactModelId } from '../models.js';
 import { getEnvOrFileVar, findEnvOrFileVar } from '../api-key.js';
 import {
   MAX_RETRIES,
@@ -330,8 +330,10 @@ class DirectLLMMethod extends LLMMethod {
 
   /**
    * The model id this provider is sent, for a configured model:
-   *   - an alias from shared/model-aliases.json resolves first
-   *     ("gpt" → "openai/gpt-5.5");
+   *   - a retired alias ("gpt") or a floating id ("…-latest", "~vendor/…")
+   *     is REFUSED first, on every transport (gateway and local included),
+   *     naming the exact slug to write — founder ruling 2026-10-05: exact
+   *     slugs only, no aliasing (lib/models.js requireExactModelId);
    *   - an OpenRouter-style id of THIS provider's vendor becomes its own
    *     name ("openai/gpt-5.5" → "gpt-5.5", "anthropic/claude-haiku-4.5" →
    *     "claude-haiku-4-5") — mirroring the harness's direct providers;
@@ -345,12 +347,15 @@ class DirectLLMMethod extends LLMMethod {
    *   ("from --model", "from the top-level \"model\""); cwd: the project
    *   directory (its .env may point the method at a gateway)
    * @returns {string|null}
-   * @throws {Error} code CHAMPOLLION_MODEL_ROUTE when there is no such model here
+   * @throws {Error} code CHAMPOLLION_MODEL_ROUTE when there is no such model here,
+   *   code CHAMPOLLION_MODEL_ID for a retired alias or a floating id
    */
   resolveModelId(model, { from = null, cwd = null } = {}) {
-    if (!model || typeof model !== 'string' || !this._callsOwnApi(cwd)) return model;
+    if (!model || typeof model !== 'string') return model;
+    requireExactModelId(model, { from });
+    if (!this._callsOwnApi(cwd)) return model;
     const vendor = this._getModelVendor();
-    const resolved = resolveModel(model);
+    const resolved = model;
     const slash = resolved.indexOf('/');
     if (slash < 0) return this._nativeModelName(resolved);
     const idVendor = resolved.slice(0, slash);
@@ -358,7 +363,7 @@ class DirectLLMMethod extends LLMMethod {
     const plainName = /^[A-Za-z0-9._-]+$/.test(name);
     if (idVendor === vendor && plainName) return this._nativeModelName(name);
 
-    const notes = [resolved === model ? null : `alias of ${resolved}`, from].filter(Boolean);
+    const notes = [from].filter(Boolean);
     const what = `"${model}"${notes.length > 0 ? ` (${notes.join(', ')})` : ''}`;
     const servedBy = Object.entries(DIRECT_MODEL_VENDORS).find(([, v]) => v === idVendor)?.[0] || null;
     const label = this._getProviderLabel();

package/lib/methods/gemini.js

@@ -18,7 +18,7 @@ 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-2.5-flash';
+const DEFAULT_MODEL = 'gemini-3.8-flash';
 
 class GeminiMethod extends DirectLLMMethod {
   constructor(options = {}) {

package/lib/methods/llm-coached.js

@@ -66,6 +66,7 @@ import { LLMMethod, inferKeyTypes, isUnsafeKey, buildSystemMessage, buildUserMes
 import { DEFAULT_COACHING_DIR, loadCoachingData, findDictionaryMatches, projectGlossary } from './coaching-data.js';
 import { DEFAULT_OPENROUTER_MODEL, DEFAULT_BATCH_SIZE, DEFAULT_COACHED_TEMPERATURE, DEFAULT_MAX_RETRIES, DEFAULT_METHOD_CONCURRENCY } from '../config.js';
 import { pMap } from '../concurrent.js';
+import { requireExactModelId } from '../models.js';
 import { output } from '../output.js';
 
 /**
@@ -256,7 +257,8 @@ class LLMCoachedMethod extends TranslationMethod {
         output.warn('LLM-Coached translate: no API key provided — skipping batch.');
         return null;
       }
-      const model = pairConfig.model || options.model || DEFAULT_OPENROUTER_MODEL;
+      // Exact slugs only (founder ruling 2026-10-05): refused before anything is sent.
+      const model = requireExactModelId(pairConfig.model || options.model || DEFAULT_OPENROUTER_MODEL);
       const llm = new LLMMethod();
       const batchFn = (batch, opts) => this._callCoachedBatch(batch, glossary, opts, pairConfig);
       return this._runCoachedBatches(llm, keys, sourceFlat, langConfig, {

package/lib/methods/llm.js

@@ -44,6 +44,7 @@ import { isUnsafeKey } from '../security.js';
 import { pMap } from '../concurrent.js';
 import { output } from '../output.js';
 import { getEnvOrFileVar } from '../api-key.js';
+import { requireExactModelId } from '../models.js';
 import { nameRules } from '../name-rules.js';
 import { isCapturing, PREVIEW_KEY } from './request-capture.js';
 import { projectGlossary, terminologyBlock } from './coaching-data.js';
@@ -97,7 +98,9 @@ class LLMMethod extends TranslationMethod {
     // A request preview needs no key: it is shown, never sent.
     const apiKey = options.apiKey || (isCapturing() ? PREVIEW_KEY : null);
     const batchSize = pairConfig.batchSize || options.batchSize || DEFAULT_BATCH_SIZE;
-    const model = pairConfig.model || options.model || DEFAULT_OPENROUTER_MODEL;
+    // Exact slugs only (founder ruling 2026-10-05) — checked here too, since
+    // callers outside the pair graph (the MCP translate tool) reach this directly.
+    const model = requireExactModelId(pairConfig.model || options.model || DEFAULT_OPENROUTER_MODEL);
     const maxRetries = pairConfig.maxRetries ?? DEFAULT_MAX_RETRIES;
     if (!apiKey) {
       output.warn('LLM translate: no API key provided — skipping batch.');
@@ -181,7 +184,9 @@ class LLMMethod extends TranslationMethod {
    */
   async translateContent(prompt, pairConfig, options) {
     const { apiKey } = options;
-    const model = pairConfig.model || options.model || DEFAULT_OPENROUTER_MODEL;
+    // Exact slugs only (founder ruling 2026-10-05) — checked here too, since
+    // callers outside the pair graph (the MCP translate tool) reach this directly.
+    const model = requireExactModelId(pairConfig.model || options.model || DEFAULT_OPENROUTER_MODEL);
     if (!apiKey) {
       output.warn('LLM translateContent: no API key provided — skipping.');
       return null;