champollion 0.3.4 → 0.4.0

package/lib/content-refusals.js

@@ -0,0 +1,270 @@
+/**
+ * content-refusals.js — Markdown blocks and front-matter fields the quality
+ * gate refused, remembered so a plain sync does not send them to the same
+ * model again. The key-value rule (lib/locale-state.js, Round 4) for the two
+ * content lanes (lib/content-sync.js, lib/docusaurus-sync.js).
+ *
+ * WHY: a block the gate refused (lib/validate.js contentGateFault) was
+ * written as the '[EN] ' last resort, never cached, and its file's lock was
+ * not advanced — so EVERY sync sent it to the same paid model again, which
+ * answered the same way and was refused again. A refused front-matter field
+ * failed its page, and every sync re-sent the page's fields. With a paid
+ * model and no fallback that repeated the charge on each run, unlike keys,
+ * which are held back.
+ *
+ * THE RECORD — in .champollion-content.lock (committed, beside the lane's
+ * own entries), one entry per (page × locale) that has refusals:
+ *
+ *   "refused:<manifestKey>": {
+ *     "block:<hash12>": { "source": "<hash12>", "methods": ["<method key>"], "on": "2026-10-04" },
+ *     "field:title":    { "source": "<hash12>", "methods": ["<method key>"], "on": "2026-10-04" },
+ *     "page":           { "source": "<hash12>", "methods": ["<method key>"], "on": "2026-10-04" }
+ *   }
+ *
+ * <manifestKey> is the lane's own key for the translation ("posts/a.md:fr",
+ * "docusaurus:docs/intro.md:fr"). A block is named by the hash of its source
+ * text, so an edited paragraph is a new block (the hold lifts); `source` is
+ * the 12-hex SHA-256 the key-value record uses, `methods` the TM method keys
+ * (method|model|register|coaching) whose answers the gate refused.
+ *
+ * "page" is the whole body of a page translated in one prompt
+ * (contentSegmentation: "page"): refused when the answer damages a protected
+ * placeholder or hollows the page (the whole-body checks), its `source` the
+ * hash of the body text. Editing the body — or switching to block
+ * segmentation — lifts it. A held page is not written, as a held field's
+ * page is not: there is no '[EN] ' text for a page translated whole.
+ *
+ * PRECEDENCE — the key-value rule, unit by unit:
+ *   1. Named for a redo — `--redo files:<page>`, `--redo content`
+ *      (= --force-content), `--retranslate`, or anything under `--fresh`:
+ *      always sent.
+ *   2. Refused before by the pair's method, for the unit's current source
+ *      text: held back — not sent to that method again. A fallback method
+ *      that has not refused it still gets it. A held block keeps its
+ *      '[EN] ' text until it is filled; a page whose front-matter field is
+ *      held is not written (the field gate fails a page whole, as it always
+ *      did) — and nothing of it is sent.
+ *   3. A model or method change lifts the hold (the refusal was that method
+ *      key's), as does a new source text.
+ *   The cache is always consulted first (free): holding back only stops a
+ *   paid call. A unit filled any other way — a fallback, the cache, a
+ *   paragraph written by hand — drops its record.
+ */
+
+import { tmMethodKey, lookupTM } from './tm.js';
+import { holdState, shortSourceHash } from './locale-state.js';
+import { contentRedoCommand } from './verify.js';
+import { translatableBlockSources } from './content-estimate.js';
+
+/** The content-lock key of one page × locale's refusals. */
+export function refusalRecordKey(manifestKey) {
+  return `refused:${manifestKey}`;
+}
+
+/** A block's unit id: the hash of its (restored) source text. */
+export const blockUnit = (source) => `block:${shortSourceHash(source)}`;
+
+/** A front-matter field's unit id. */
+export const fieldUnit = (field) => `field:${field}`;
+
+/** The unit id of a page body translated whole (contentSegmentation: "page"). */
+export const PAGE_UNIT = 'page';
+
+/** How a held page body is named in messages and summaries. */
+export const PAGE_NAME = 'the whole page body';
+
+/**
+ * One page × locale's refusal record (entries that do not parse are dropped).
+ *
+ * @param {object} manifest - The content lock
+ * @param {string} manifestKey
+ * @returns {Record<string, { source: string, methods: string[], on?: string }>}
+ */
+export function readRefusals(manifest, manifestKey) {
+  const rec = manifest?.[refusalRecordKey(manifestKey)];
+  if (!rec || typeof rec !== 'object' || Array.isArray(rec)) return {};
+  const out = {};
+  for (const [id, r] of Object.entries(rec)) {
+    if (r && typeof r === 'object' && typeof r.source === 'string' && Array.isArray(r.methods)) out[id] = r;
+  }
+  return out;
+}
+
+/**
+ * What a run may do with each unit of one page: 'send' (ask the pair's
+ * method), 'fallback-only' (the pair's method refused it; its fallback has
+ * not), 'held' (not sent at all).
+ *
+ * @param {object} units - readRefusals()
+ * @param {object} pairConfig
+ * @param {{ redo?: boolean }} [opts] - redo: the page was named for a redo (always sent)
+ * @returns {{ block: (source: string) => 'send'|'fallback-only'|'held',
+ *   field: (field: string, source: string) => 'send'|'fallback-only'|'held',
+ *   page: (body: string) => 'send'|'fallback-only'|'held' }}
+ */
+export function contentHolds(units, pairConfig, { redo = false } = {}) {
+  // The key-value rule (lib/locale-state.js holdState), unit by unit.
+  const stateOf = (id, source) => (redo ? 'send' : holdState(units[id], source, pairConfig));
+  return {
+    block: (source) => stateOf(blockUnit(source), source),
+    field: (field, source) => stateOf(fieldUnit(field), source),
+    page: (body) => stateOf(PAGE_UNIT, body),
+  };
+}
+
+/**
+ * One page's record after a run processed it: earlier refusals that still
+ * apply (same source text, not filled this run), plus this run's.
+ *
+ * @param {object} prior - readRefusals()
+ * @param {object} p
+ * @param {string[]} p.blockSources - The page's current translatable block sources ([] in page mode)
+ * @param {string|null} [p.pageSource] - Its body, in page mode (null in block mode)
+ * @param {Record<string, string>} p.fields - Its current translatable front-matter fields
+ * @param {Array<{ unit: string, source: string, methods: string[] }>} p.refused - Refused this run, left unfilled
+ * @param {Set<string>} p.filled - Units filled this run (any method, the cache, a person)
+ * @returns {object|null} The record, or null when nothing is left to hold
+ */
+export function nextRefusals(prior, { blockSources = [], pageSource = null, fields = {}, refused = [], filled = new Set() }) {
+  const live = new Map();
+  for (const s of blockSources) live.set(blockUnit(s), shortSourceHash(s));
+  if (typeof pageSource === 'string' && pageSource.trim()) live.set(PAGE_UNIT, shortSourceHash(pageSource));
+  for (const [f, v] of Object.entries(fields)) if (typeof v === 'string') live.set(fieldUnit(f), shortSourceHash(v));
+  const out = {};
+  for (const [id, r] of Object.entries(prior)) {
+    if (filled.has(id) || live.get(id) !== r.source) continue;
+    out[id] = r;
+  }
+  const on = new Date().toISOString().slice(0, 10);
+  for (const { unit, source, methods } of refused) {
+    if (!methods || methods.length === 0 || filled.has(unit)) continue;
+    const src = shortSourceHash(source);
+    const known = out[unit] && out[unit].source === src ? out[unit].methods : [];
+    out[unit] = { source: src, methods: [...new Set([...known, ...methods])], on };
+  }
+  return Object.keys(out).length > 0 ? out : null;
+}
+
+/** Write (or remove) one page's record in the content lock object. */
+export function storeRefusals(manifest, manifestKey, record) {
+  const key = refusalRecordKey(manifestKey);
+  if (record) manifest[key] = record;
+  else delete manifest[key];
+}
+
+/**
+ * The warning for one page's held units — both lanes say it the same way.
+ *
+ * @param {object} p
+ * @param {string} p.file - The page as sync names it (what `--redo files:` matches)
+ * @param {string} p.code
+ * @param {string} p.pairKey
+ * @param {object} p.pairConfig
+ * @param {string[]} p.names - "paragraph 2", 'front matter "title"'
+ * @param {boolean} [p.pageHeld] - A front-matter field (or the page body, in
+ *   page mode) is held: the page is not written
+ * @param {boolean} [p.handWritten] - The lane keeps a paragraph written by hand (contentDir)
+ * @param {string} [p.fallbackPrefix]
+ * @returns {string}
+ */
+export function describeHeld({ file, code, pairKey, pairConfig, names, pageHeld = false, handWritten = false, fallbackPrefix = '[EN] ' }) {
+  const shown = names.slice(0, 5).join(', ') + (names.length > 5 ? `, +${names.length - 5} more` : '');
+  const fb = pairConfig.fallback;
+  const who = fb ? `${pairConfig.method}'s and its fallback's (${fb.method})` : `${pairConfig.method}'s`;
+  const left = !pageHeld
+    ? `The '${fallbackPrefix.trim()}' text stays until they are filled.`
+    : names.includes(PAGE_NAME)
+      ? 'A page translated whole has no \'[EN]\' text to keep, so it is not written (and nothing of it is sent) until it is filled.'
+      : 'A front-matter field the gate refuses fails its page, so the page is not written (and nothing of it is sent) until it is filled.';
+  const other = fb
+    ? 'another "fallback" method on the pair'
+    : `a "fallback" method on the pair (it is asked for what ${pairConfig.method} refused)`;
+  const hand = handWritten && !pageHeld ? ', or write those paragraphs by hand (a hand-written paragraph is kept)' : '';
+  return `${file} → ${code}: ${names.length} block(s)/field(s) held back (${shown}) — the quality gate refused ${who} translation of their `
+    + `current text before; not sent, not billed. ${left} Ask again: \`${contentRedoCommand(file, { pair: pairKey })}\`; `
+    + `or fill them another way — ${other}${hand}.`;
+}
+
+/**
+ * Said with a refusal this run recorded: what the next sync does with it.
+ *
+ * @param {object} p
+ * @param {string} p.file
+ * @param {string} p.pairKey
+ * @param {object} p.pairConfig
+ * @param {number} p.count - Units refused (and left unfilled) this run
+ * @param {boolean} [p.fallbackAsked] - Some of them still go to the fallback
+ *   (it has not refused them — skipped by --max-cost, or no answer)
+ * @returns {string}
+ */
+export function describeNewHold({ file, pairKey, pairConfig, count, fallbackAsked = false, lead = 'Remembered:' }) {
+  const them = count === 1 ? 'it' : `these ${count}`;
+  const fb = pairConfig.fallback;
+  const where = fb && fallbackAsked
+    ? `${pairConfig.method} again (its fallback, ${fb.method}, is asked for what it has not refused)`
+    : `${pairConfig.method}${fb ? ` or its fallback (${fb.method})` : ''} again`;
+  return `${lead} the next sync does not send ${them} to ${where} — not billed again; `
+    + `\`${contentRedoCommand(file, { pair: pairKey })}\` asks again.`;
+}
+
+/**
+ * The end of a lane's "N block(s) … written as '[EN] '-prefixed source" line:
+ * what the next sync does with them — asks again for a block that got no
+ * usable answer, holds back one the gate refused.
+ *
+ * @param {object} p
+ * @param {string} p.file
+ * @param {string} p.pairKey
+ * @param {object} p.pairConfig
+ * @param {number} p.fellBack - Blocks written as '[EN] ' this run
+ * @param {number[]} p.newlyHeld - Of those (indices into the batch), the ones the gate refused
+ * @param {string[][]} [p.refusedBy] - translateBlocksWithFallback().refusedBy
+ * @returns {string}
+ */
+export function describeFallenBack({ file, pairKey, pairConfig, fellBack, newlyHeld, refusedBy = [] }) {
+  if (newlyHeld.length === 0) return 'Not cached, lock not advanced: the next sync retries just those block(s).';
+  const retry = fellBack - newlyHeld.length;
+  const fbKey = pairConfig.fallback ? tmMethodKey(pairConfig.fallback) : null;
+  const fallbackAsked = !!fbKey && newlyHeld.some(i => !(refusedBy[i] || []).includes(fbKey));
+  const n = newlyHeld.length;
+  return 'Not cached, lock not advanced. '
+    + (retry > 0 ? `The next sync asks again for the ${retry} that got no usable answer. ` : '')
+    + describeNewHold({
+      file, pairKey, pairConfig, count: n, fallbackAsked,
+      lead: `The ${n === 1 ? 'one' : n} the quality gate refused ${n === 1 ? 'is' : 'are'} remembered:`,
+    });
+}
+
+/**
+ * What a real run would hold back for one page — a dry run says so instead
+ * of "would create". The cache is consulted as the sync consults it (pure
+ * lookups: a preview changes nothing): only what it does not hold is held.
+ *
+ * @param {object} p
+ * @param {object} p.tm
+ * @param {string} p.code
+ * @param {object} p.pairConfig
+ * @param {Record<string, string>} p.fields - Translatable front-matter fields
+ * @param {string} p.body
+ * @param {'block'|'page'} p.segMode
+ * @param {ReturnType<typeof contentHolds>} p.holds
+ * @returns {{ names: string[], pageHeld: boolean }}
+ */
+export function previewHeld({ tm, code, pairConfig, fields, body, segMode, holds }) {
+  const keys = [tmMethodKey(pairConfig), ...(pairConfig.fallback ? [tmMethodKey(pairConfig.fallback)] : [])];
+  const cached = (text) => keys.some(k => lookupTM(tm, text, code, k) !== null);
+  const names = [];
+  for (const [field, text] of Object.entries(fields || {})) {
+    if (typeof text === 'string' && !cached(text) && holds.field(field, text) === 'held') names.push(`front matter "${field}"`);
+  }
+  if (names.length > 0) return { names, pageHeld: true };
+  if (segMode === 'page' && typeof body === 'string' && body.trim() && !cached(body) && holds.page(body) === 'held') {
+    return { names: [PAGE_NAME], pageHeld: true };
+  }
+  if (segMode === 'block' && typeof body === 'string' && body.trim() && !cached(body)) {
+    translatableBlockSources(body).forEach((source, i) => {
+      if (!cached(source) && holds.block(source) === 'held') names.push(`paragraph ${i + 1}`);
+    });
+  }
+  return { names, pageHeld: false };
+}

package/lib/content-review.js

@@ -0,0 +1,372 @@
+/**
+ * content-review.js — keep the edits a person makes to translated Markdown.
+ *
+ * THE BUG THIS CLOSES (persona finding, 2026-10-03): a reviewer corrects a
+ * sentence in newsletters/2026-10.crk.md; the author then edits a DIFFERENT
+ * paragraph of newsletters/2026-10.md; the next sync re-translates the file
+ * and the Translation Memory serves the OLD machine translation for every
+ * unchanged paragraph, so the reviewer's correction was overwritten with
+ * nothing said but "source updated, re-translating". The content lock held
+ * only the SOURCE hash, so nothing could tell a reviewed file from the file
+ * sync wrote.
+ *
+ * THE RECORD. Whenever the content lane writes (or adopts) a translated file
+ * it also records what it left on disk, in the same .champollion-content.lock,
+ * under "written:<relPath>:<locale>":
+ *
+ *   {
+ *     "file":   16 hex of SHA-256 over the whole file as sync left it,
+ *     "blocks": "s:t s:t:r …"  one entry per translatable body block, in
+ *               order. s = 8 hex of the SOURCE block it translates, t = 8 hex
+ *               of the block as written, ":r" = a person's text (kept on
+ *               every later sync). null when the written body does not split
+ *               into as many blocks as the source (no safe positional map).
+ *     "fields": { "<name>": "s:t[:r]" }  translatable front-matter fields.
+ *     "owned":  true  the whole file is a person's (hand-translated, or
+ *               brought up to date by hand) and has no block map.
+ *     "held":   16 hex of the file when a sync last left it as is because
+ *               its edits could not be merged with a source change.
+ *   }
+ *
+ * The block unit is exactly the TM's (segment.js via translatableBlockSources:
+ * protect → split → restore, translatable segments only), and the record is
+ * computed by re-splitting the file AS WRITTEN — the same function the next
+ * sync runs on the file on disk — so "differs from the record" can only mean
+ * that a person changed it.
+ *
+ * WHAT A SYNC DOES WITH EDITS (lib/content-sync.js):
+ *   - source unchanged → the file is not touched (as before);
+ *   - source changed → edited paragraphs whose source paragraph is unchanged
+ *     are kept word for word, everything else is updated; an edited paragraph
+ *     whose source paragraph itself changed is re-translated and the run
+ *     prints the edited wording so it can be re-applied;
+ *   - edits that cannot be matched paragraph by paragraph (paragraphs added,
+ *     removed or merged; 'page' segmentation) → the file is left as is and
+ *     the run says so every time until the file is brought up to date by hand
+ *     (the next sync then takes it as current) or re-translated by name.
+ */
+
+import crypto from 'node:crypto';
+import { parseContentFile } from './content.js';
+import { translatableBlockSources } from './content-estimate.js';
+
+const WRITTEN_PREFIX = 'written:';
+
+function sha256(text) {
+  return crypto.createHash('sha256').update(text, 'utf-8').digest('hex');
+}
+
+/** 8-hex fingerprint of one block or field value (collisions only matter within one file). */
+function blockHash(text) {
+  return sha256(text).slice(0, 8);
+}
+
+/** 16-hex fingerprint of a whole translated file. */
+function fileHash(text) {
+  return sha256(text).slice(0, 16);
+}
+
+/** The lock key of the written-record for a content manifest key ("relPath:locale"). */
+function writtenRecordKey(manifestKey) {
+  return `${WRITTEN_PREFIX}${manifestKey}`;
+}
+
+function encodePair(s, t, owned) {
+  return `${s}:${t}${owned ? ':r' : ''}`;
+}
+
+function decodePair(enc) {
+  if (typeof enc !== 'string') return null;
+  const [s, t, flag, extra] = enc.split(':');
+  if (!/^[0-9a-f]{8}$/.test(s || '') || !/^[0-9a-f]{8}$/.test(t || '')) return null;
+  if (extra !== undefined || (flag !== undefined && flag !== 'r')) return null;
+  return { s, t, owned: flag === 'r' };
+}
+
+/**
+ * Parse a stored written-record. Returns null when there is none; throws
+ * (with a plain message) when one is present but malformed — the caller
+ * must say so rather than silently treat the file as unedited.
+ *
+ * @param {*} value - The lock value under writtenRecordKey(...)
+ * @returns {{ file: string, blocks: Array<{s:string,t:string,owned:boolean}>|null,
+ *   fields: Object<string,{s:string,t:string,owned:boolean}>, owned: boolean,
+ *   held: string|null }|null}
+ */
+function parseWrittenRecord(value) {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== 'object' || Array.isArray(value) || typeof value.file !== 'string') {
+    throw new Error('not a written-record object');
+  }
+  let blocks = null;
+  if (typeof value.blocks === 'string') {
+    blocks = value.blocks === '' ? [] : value.blocks.split(' ').map(decodePair);
+    if (blocks.some(b => b === null)) throw new Error('malformed "blocks"');
+  } else if (value.blocks !== null && value.blocks !== undefined) {
+    throw new Error('malformed "blocks"');
+  }
+  const fields = {};
+  if (value.fields !== undefined) {
+    if (typeof value.fields !== 'object' || value.fields === null || Array.isArray(value.fields)) {
+      throw new Error('malformed "fields"');
+    }
+    for (const [name, enc] of Object.entries(value.fields)) {
+      const pair = decodePair(enc);
+      if (!pair) throw new Error(`malformed field "${name}"`);
+      fields[name] = pair;
+    }
+  }
+  return {
+    file: value.file,
+    blocks,
+    fields,
+    owned: value.owned === true,
+    held: typeof value.held === 'string' ? value.held : null,
+  };
+}
+
+/**
+ * Build the record of a file sync is leaving on disk.
+ *
+ * @param {object} args
+ * @param {string} args.sourceBody - Source Markdown body (front matter stripped)
+ * @param {Object<string,string>} args.sourceFields - Translatable source front-matter values
+ * @param {string} args.written - The complete target file as written
+ * @param {Set<number>} [args.ownedBlocks] - Source block positions holding a person's text
+ * @param {Set<string>} [args.ownedFields] - Field names holding a person's text
+ * @returns {object} JSON-ready record (see header)
+ */
+function buildWrittenRecord({ sourceBody, sourceFields, written, ownedBlocks = new Set(), ownedFields = new Set() }) {
+  const target = parseContentFile(written);
+  const src = translatableBlockSources(sourceBody);
+  const out = translatableBlockSources(target.body);
+  const record = { file: fileHash(written), blocks: null };
+  if (src.length === out.length) {
+    record.blocks = src.map((s, j) => encodePair(blockHash(s), blockHash(out[j]), ownedBlocks.has(j))).join(' ');
+  } else if (ownedBlocks.size > 0) {
+    // A person's paragraphs with no block map: the whole file is theirs.
+    record.owned = true;
+  }
+  const fields = {};
+  for (const name of Object.keys(sourceFields).sort()) {
+    const value = sourceFields[name];
+    const tv = target.frontMatter[name];
+    if (typeof value === 'string' && typeof tv === 'string') {
+      fields[name] = encodePair(blockHash(value), blockHash(tv), ownedFields.has(name));
+    }
+  }
+  if (Object.keys(fields).length > 0) record.fields = fields;
+  return record;
+}
+
+/**
+ * Record a file a person wrote (hand-translated, or brought up to date by
+ * hand after a sync held it): every paragraph and field is theirs.
+ */
+function buildAdoptedRecord({ sourceBody, sourceFields, written }) {
+  const blockCount = translatableBlockSources(sourceBody).length;
+  const ownedBlocks = new Set(Array.from({ length: blockCount }, (_, j) => j));
+  const record = buildWrittenRecord({
+    sourceBody, sourceFields, written, ownedBlocks, ownedFields: new Set(Object.keys(sourceFields)),
+  });
+  // A hand-written file with no translatable blocks is still a person's file.
+  if (record.blocks === null) record.owned = true;
+  return record;
+}
+
+/**
+ * First record of a file this version never recorded (written by an older
+ * version, source unchanged since). A block or field is marked as a person's
+ * when the TM holds a machine translation for its source and the file does
+ * NOT carry it — that is an edit made before the record existed. With no TM
+ * entry there is no evidence either way, and the text is taken as written.
+ *
+ * @param {object} args
+ * @param {(sourceText: string) => string[]} args.machineFor - Cached machine
+ *   translations of a source text (exact entries; no side effects)
+ */
+function buildBootstrapRecord({ sourceBody, sourceFields, written, machineFor }) {
+  const target = parseContentFile(written);
+  const src = translatableBlockSources(sourceBody);
+  const out = translatableBlockSources(target.body);
+  const differs = (sourceText, targetText) => {
+    const known = machineFor(sourceText);
+    return known.length > 0 && !known.includes(targetText);
+  };
+  const ownedBlocks = new Set();
+  if (src.length === out.length) {
+    src.forEach((s, j) => { if (differs(s, out[j])) ownedBlocks.add(j); });
+  }
+  const ownedFields = new Set();
+  for (const [name, value] of Object.entries(sourceFields)) {
+    const tv = target.frontMatter[name];
+    if (typeof value === 'string' && typeof tv === 'string' && differs(value, tv)) ownedFields.add(name);
+  }
+  return buildWrittenRecord({ sourceBody, sourceFields, written, ownedBlocks, ownedFields });
+}
+
+/**
+ * What a person changed in a translated file since sync last recorded it.
+ *
+ * @param {string} targetRaw - The translated file as it is on disk now
+ * @param {ReturnType<typeof parseWrittenRecord>} record
+ * @returns {{ state: 'clean' } |
+ *   { state: 'unmappable', reason: string } |
+ *   { state: 'edited', blocks: Array<{src:string,text:string,owned:boolean}>,
+ *     fields: Object<string,{src:string,text:string,owned:boolean}>,
+ *     ownedBlocks: number, ownedFields: number }}
+ */
+function readReviewerEdits(targetRaw, record) {
+  const edited = fileHash(targetRaw) !== record.file;
+  const anyOwned = record.owned
+    || (record.blocks || []).some(b => b.owned)
+    || Object.values(record.fields).some(f => f.owned);
+  if (!edited && !anyOwned) return { state: 'clean' };
+
+  const target = parseContentFile(targetRaw);
+  const fields = {};
+  for (const [name, f] of Object.entries(record.fields)) {
+    const current = target.frontMatter[name];
+    if (typeof current !== 'string') continue; // removed from the file: nothing to keep
+    fields[name] = { src: f.s, text: current, owned: f.owned || blockHash(current) !== f.t };
+  }
+  const ownedFields = Object.values(fields).filter(f => f.owned).length;
+
+  if (record.blocks === null) {
+    if (!edited && !record.owned) {
+      // Only field flags: the body is as written.
+      return ownedFields > 0 ? { state: 'edited', blocks: null, fields, ownedBlocks: 0, ownedFields } : { state: 'clean' };
+    }
+    return {
+      state: 'unmappable',
+      reason: record.owned
+        ? 'it is maintained by hand'
+        : 'its paragraphs did not line up one to one with the source when sync wrote it',
+    };
+  }
+
+  const current = translatableBlockSources(target.body);
+  if (current.length !== record.blocks.length) {
+    return {
+      state: 'unmappable',
+      reason: `it now has ${current.length} paragraph(s) where sync wrote ${record.blocks.length} — paragraphs were added, removed or merged`,
+    };
+  }
+  const blocks = record.blocks.map((b, i) => ({
+    src: b.s, text: current[i], owned: b.owned || blockHash(current[i]) !== b.t,
+  }));
+  const ownedBlocks = blocks.filter(b => b.owned).length;
+  // Edits only to separators, passthrough blocks (code) or untranslated
+  // front matter: those parts are copied from the source by design.
+  if (ownedBlocks === 0 && ownedFields === 0) return { state: 'clean' };
+  return { state: 'edited', blocks, fields, ownedBlocks, ownedFields };
+}
+
+/**
+ * Match a person's paragraphs to the CURRENT source's blocks by the source
+ * text they translate. Every previously written block is queued under its
+ * source hash, so the k-th copy of a repeated paragraph maps to the k-th copy.
+ *
+ * @param {Array<{src:string,text:string,owned:boolean}>} editBlocks - From readReviewerEdits
+ * @param {string[]} sourceBlocks - Current source's translatable block texts, in order
+ * @returns {{ keep: Map<number,string>, superseded: Array<{ paragraph: number, text: string }> }}
+ *   keep: source block position → the person's text. superseded: edited
+ *   paragraphs (1-based, as they were in the file) whose source paragraph
+ *   is gone or changed.
+ */
+function matchEditedBlocks(editBlocks, sourceBlocks) {
+  const queues = new Map();
+  editBlocks.forEach((b, i) => {
+    if (!queues.has(b.src)) queues.set(b.src, []);
+    queues.get(b.src).push({ ...b, paragraph: i + 1 });
+  });
+  const keep = new Map();
+  sourceBlocks.forEach((text, j) => {
+    const entry = queues.get(blockHash(text))?.shift();
+    if (entry && entry.owned) keep.set(j, entry.text);
+  });
+  const superseded = [...queues.values()].flat()
+    .filter(e => e.owned)
+    .sort((a, b) => a.paragraph - b.paragraph)
+    .map(e => ({ paragraph: e.paragraph, text: e.text }));
+  return { keep, superseded };
+}
+
+/**
+ * Match a person's front-matter values to the current source fields.
+ *
+ * @returns {{ keep: Object<string,string>, superseded: Array<{ field: string, text: string }> }}
+ */
+function matchEditedFields(editFields, sourceFields) {
+  const keep = {};
+  const superseded = [];
+  for (const [name, f] of Object.entries(editFields)) {
+    if (!f.owned) continue;
+    const source = sourceFields[name];
+    if (typeof source === 'string' && blockHash(source) === f.src) keep[name] = f.text;
+    else superseded.push({ field: name, text: f.text });
+  }
+  return { keep, superseded };
+}
+
+/**
+ * Decide what a sync does with an existing translated file before it
+ * translates anything. Pure (no I/O): runContentSync and the cost estimator
+ * (countPendingContentTranslations) both call it, so the estimate can never
+ * count a file the sync would leave as is.
+ *
+ * @param {object} args
+ * @param {string} args.targetRaw - The translated file on disk
+ * @param {ReturnType<typeof parseWrittenRecord>} args.record - null = no record (older version)
+ * @param {'block'|'page'} args.segMode - The pair's content segmentation
+ * @param {boolean} args.replaceEdits - The operator named this file for a redo
+ *   (--retranslate, or --redo files: / --files with --force-content)
+ * @param {boolean} args.sourceCurrent - The lock says the source is unchanged
+ *   (we are here only because of --force-content)
+ * @returns {{ action: 'proceed', edits: object|null, replaced?: object } |
+ *   { action: 'keep', reason: string } | { action: 'accept' } |
+ *   { action: 'hold', reason: string, heldHash: string }}
+ *   proceed: translate; `edits` (state 'edited') are the person's paragraphs
+ *   and fields to keep. keep: an up-to-date file with edits that cannot be
+ *   merged — leave it. accept: a held file was edited since — take it as
+ *   current. hold: leave the file as is and say so (lock not advanced).
+ */
+function assessExistingTarget({ targetRaw, record, segMode, replaceEdits, sourceCurrent }) {
+  if (!record) return { action: 'proceed', edits: null };
+  const edits = readReviewerEdits(targetRaw, record);
+  if (edits.state === 'clean') return { action: 'proceed', edits: null };
+  if (replaceEdits) return { action: 'proceed', edits: null, replaced: edits };
+  const cannotMerge = edits.state === 'unmappable' || (segMode === 'page' && edits.ownedBlocks > 0);
+  if (!cannotMerge) return { action: 'proceed', edits };
+  const reason = edits.state === 'unmappable'
+    ? edits.reason
+    : "its pair uses 'page' segmentation, which translates the body as one piece";
+  if (sourceCurrent) return { action: 'keep', reason };
+  const current = fileHash(targetRaw);
+  if (record.held && record.held !== current) return { action: 'accept' };
+  return { action: 'hold', reason, heldHash: current };
+}
+
+/** "3 paragraph(s) and the title" — for kept/replaced messages. */
+function describeEdits({ paragraphs = 0, fields = [] }) {
+  const parts = [];
+  if (paragraphs > 0) parts.push(`${paragraphs} paragraph(s)`);
+  if (fields.length > 0) parts.push(`front matter ${fields.map(f => `"${f}"`).join(', ')}`);
+  return parts.join(' and ') || 'the file';
+}
+
+export {
+  assessExistingTarget,
+  describeEdits,
+  WRITTEN_PREFIX,
+  blockHash,
+  fileHash,
+  writtenRecordKey,
+  parseWrittenRecord,
+  buildWrittenRecord,
+  buildAdoptedRecord,
+  buildBootstrapRecord,
+  readReviewerEdits,
+  matchEditedBlocks,
+  matchEditedFields,
+};