@elytracms/studio 0.0.101 → 0.0.103

package/dist/lib/ai/translate-document.d.ts

@@ -6,7 +6,10 @@ export declare const DEFAULT_TRANSLATE_BATCH_SIZE = 12;
 export declare const DEFAULT_TRANSLATE_CONCURRENCY = 6;
 /** The schema name the batch call carries — how a FakeProvider recognises a translate call. */
 export declare const TRANSLATE_SCHEMA_NAME = "translate_units";
-/** Fill only still-connected locale values (default), or re-translate every localized field. */
+/**
+ * Fill only still-connected locale values (default), or re-translate every localized field
+ * — replacing a value with its own translation, rebuilt from the base (EC-752).
+ */
 export type TranslateMode = 'fill-empty' | 'retranslate-all';
 export interface TranslateDocumentInput {
     provider: AiProvider;
@@ -18,7 +21,12 @@ export interface TranslateDocumentInput {
     targetLocales?: readonly Locale[];
     /** Assembled project knowledge (glossary / voice) sent as context with every batch. */
     knowledge?: ResolvedKnowledge;
-    /** `fill-empty` (default) or `retranslate-all` (overwrites diverged values — gated in UI). */
+    /**
+     * `fill-empty` (default) or `retranslate-all` — which REPLACES a value with its own
+     * translation, whole or not at all, never a slug the editor set (EC-752). The studio runs
+     * it only behind a confirm listing {@link planTranslation}'s replacements, after a version
+     * snapshot of the draft.
+     */
     mode?: TranslateMode;
     batchSize?: number;
     concurrency?: number;
@@ -52,12 +60,28 @@ export interface TranslateProgress {
 }
 /** Why a text position was not translated. */
 export type TranslateSkipReason = 
-/** The stored value at the position is not readable as its type (e.g. a pre-convergence rich text). */
+/**
+ * The stored value at the position is not readable as its type (e.g. a pre-convergence rich
+ * text) — or (EC-752) it is a value the traversal cannot read at all (`OpaquePosition`: a
+ * holder stored in a shape its declaration no longer reads) that may hold text.
+ */
 'unreadable'
 /** The provider returned no (or empty) text for the unit. */
  | 'not-returned'
-/** The translation did not keep the formatting / link / embed tokens; the original was kept. */
- | 'structure-changed';
+/**
+ * The translation did not keep the formatting / link / embed tokens: `fill-empty` keeps
+ * the source's block in the fill; `retranslate-all` leaves the whole target value as it was.
+ */
+ | 'structure-changed'
+/**
+ * EC-738: the bucket's locked content (`form.readOnly` / `ai.exclude`) differs in shape
+ * from the source's — writing the translation would lose a locked value the target holds or
+ * add one it does not (a repeater with more or fewer items, a composition with other
+ * nodes) — or (EC-748) either side stores it in a shape the declaration no longer reads.
+ * The whole bucket was left as it is: only code, a seed, an import or a save in the editor
+ * changes it.
+ */
+ | 'locked';
 /**
  * One text position the run could NOT translate (EC-593, ratified 4e): reported in the
  * result and shown in the dialog — never a silent skip.
@@ -75,9 +99,71 @@ export interface TranslateSkip {
     };
     reason: TranslateSkipReason;
 }
+/** One `(field, locale)` value — the unit a translation writes, plans and reports (EC-752). */
+export interface TranslateBucket {
+    readonly field: string;
+    readonly locale: Locale;
+}
+/**
+ * What a planned bucket is (EC-752): `fill` — the target FOLLOWS the base (EC-318 connected)
+ * and gets its own translation; `replace` — the target holds its own value (an earlier
+ * translation, an editor's edit), which a re-translation rebuilds from the base — its text
+ * translated, every other value (a number, an image, a select) the base's, its locked
+ * positions kept (EC-738). `replace` exists only in `retranslate-all`.
+ */
+export type TranslateBucketKind = 'fill' | 'replace';
+export interface TranslatePlanBucket extends TranslateBucket {
+    readonly kind: TranslateBucketKind;
+}
+/**
+ * EC-752 — what a run will do, judged BEFORE any provider call: the eligibility, the locked
+ * judgement (EC-738), the units and the unreadable positions. ONE judge
+ * ({@link planTranslation}) gives both the studio's confirm and the run's input, so the list
+ * an editor confirms is the list the run works from.
+ *
+ * It is an UPPER bound ("up to"): what is known only after the provider answered — a unit
+ * not returned, a block whose tokens did not survive, a cancel, the introduced-errors gate
+ * refusing the run, a colleague's write refused at its revision — can only take a bucket
+ * away. {@link TranslateDocumentResult.writes} says what was written.
+ */
+export interface TranslatePlan {
+    readonly mode: TranslateMode;
+    readonly base: Locale;
+    /** Every configured locale but the base (or the caller's `targetLocales`). */
+    readonly targets: readonly Locale[];
+    /** The buckets the run writes when every unit lands — walk order (field, then locale). */
+    readonly buckets: readonly TranslatePlanBucket[];
+    /**
+     * What the run will NOT translate, known now: a bucket left as it is for its locked
+     * content (`locked`), an unreadable position (`unreadable` — in `retranslate-all` its whole
+     * bucket is left as it was, so it is not in {@link buckets}).
+     */
+    readonly skipped: readonly TranslateSkip[];
+    /** Translatable units — the run's {@link TranslateDocumentResult.total}. */
+    readonly total: number;
+}
+/** What {@link planTranslation} reads — the run's own inputs, minus the provider. */
+export type TranslatePlanInput = Pick<TranslateDocumentInput, 'collection' | 'document' | 'localeConfig' | 'targetLocales' | 'mode' | 'validateOptions'>;
+/**
+ * One bucket this run WROTE (EC-752): a planned `fill` / `replace` whose every unit landed
+ * (`fill-empty`: at least one), or a `slug` derived from the translated source (only where
+ * the target's slug followed the base). `patch` is the one the caller persists
+ * ({@link TranslateDocumentResult.patches}, same order).
+ */
+export interface TranslateWrite extends TranslateBucket {
+    readonly kind: TranslateBucketKind | 'slug';
+    readonly patch: DocumentPatch;
+}
 export interface TranslateDocumentResult {
-    /** The new draft with the translations filled in (base + connected locale values). */
+    /** The new draft with the translations in. */
     document: CmsDocument;
+    /** EC-752 — the pre-provider plan this run executed ({@link planTranslation} on its input). */
+    plan: TranslatePlan;
+    /**
+     * EC-752 — what this run wrote, one entry per bucket, in {@link patches}' order: compare
+     * with {@link plan} for what was planned but not written.
+     */
+    writes: readonly TranslateWrite[];
     /**
      * EC-595 A2 — the positions this run wrote, as patches (one per `(field, locale)`
      * bucket it filled — "localized fields patch per bucket"): what the caller persists,
@@ -94,7 +180,7 @@ export interface TranslateDocumentResult {
     changed: boolean;
     /** Translatable units filled per target locale. */
     perLocale: Record<Locale, number>;
-    /** Slug fields derived per target locale (not model-translated). */
+    /** Slug fields derived (not model-translated) — the `slug` entries of {@link writes}. */
     slugsDerived: number;
     /** Every text position the run could not translate (EC-593) — empty when all landed. */
     skipped: readonly TranslateSkip[];
@@ -118,4 +204,12 @@ export interface TranslateDocumentResult {
     /** Surviving non-error findings on the produced draft — carried onto a proposal. */
     issues: readonly CmsValidationIssue[];
 }
+/**
+ * EC-752 — THE pre-provider judge: which field × locale values a translation of `input`
+ * writes when every unit lands (`fill` / `replace`), and what it already knows it will not
+ * translate (`locked`, `unreadable`). Pure: no provider, no store, no clock. The studio's
+ * confirm lists it; {@link translateDocument} runs exactly it — one judge, never a second
+ * count. See {@link TranslatePlan} for why it is an upper bound.
+ */
+export declare function planTranslation(input: TranslatePlanInput): TranslatePlan;
 export declare function translateDocument(input: TranslateDocumentInput): Promise<TranslateDocumentResult>;

package/dist/lib/ai/translate-document.js

@@ -2,21 +2,28 @@
  * `translateDocument` — the full-document AI translation engine (EC-332).
  *
  * ONE implementation behind two surfaces (the detail-editor "Translate document" header
- * action + the chat tool). It walks a document's LOCALIZED fields, computes the units
- * still **connected to base** (EC-318 — never overwriting a manually diverged value),
- * translates them with bounded client-side concurrency over the EC-331 provider, and
- * returns a NEW draft with the translations filled in. The caller writes that draft
- * through the operations layer with the user's session (provenance-tagged) — the engine
- * itself has no data access, so the deterministic FakeProvider drives the whole flow.
+ * action + the chat tool). It walks a document's LOCALIZED fields, plans the field ×
+ * locale values to write ({@link planTranslation} — the ONE pre-provider judge, EC-752),
+ * translates their units with bounded client-side concurrency over the EC-331 provider,
+ * and returns a NEW draft with the translations in. In the default mode (`fill-empty`)
+ * only values still **connected to base** are filled (EC-318 — a value with its own
+ * translation is never overwritten); `retranslate-all` (EC-752, the dialog's "Re-translate
+ * everything", behind a confirm that lists what it replaces) also REPLACES a value with its
+ * own translation, rebuilt from the base. The caller writes that draft through the
+ * operations layer with the user's session (provenance-tagged) — the engine itself has no
+ * data access, so the deterministic FakeProvider drives the whole flow.
  *
- * Unit-walk semantics (fill-empty-only, the default):
+ * Unit-walk semantics:
  *  - target locales = configured locales minus the document's base locale;
  *  - only LOCALIZED, writer-unlocked fields participate (a non-localized field is shared
  *    across locales — there is nothing per-locale to fill; EC-716: an `ai.exclude` or
  *    `form.readOnly` position, at any depth, is no unit — and no derived slug either);
- *  - a field/locale is translated only when it is CONNECTED (no per-locale key yet) and
- *    the base value is non-empty — so writing the translation DIVERGES it, which is
- *    exactly what makes a re-run an idempotent no-op;
+ *  - `fill-empty`: a field/locale is translated only when it is CONNECTED (no per-locale
+ *    key yet) and the base value is non-empty — so writing the translation DIVERGES it,
+ *    which is exactly what makes a re-run an idempotent no-op. `retranslate-all`: also when
+ *    it holds its own value — and then a field/locale is written only WHOLE, when every unit
+ *    of it landed (a dropped unit, a rejected block, a cancel or an unreadable position
+ *    leaves the target's value as it was, reported); its locked content is kept (EC-738);
  *  - EVERY text position of the base value is a unit (EC-593, ratified 4e): the walk is
  *    core's ONE value-position traversal, so a `text` position is one unit and a
  *    `richText` / `blocks` sequence one unit per translatable block (structure preserved
@@ -28,10 +35,14 @@
  *  - the target bucket is the BASE value with its text translated — every other value
  *    (an image, a select, a number) carried from it, the displayed-value rule (2c);
  *  - whatever cannot be translated is REPORTED (`skipped`), never silently left: a
- *    position whose value is unreadable, a unit the provider did not return, a rich-text
- *    block whose translation did not decode token-faithfully (its original is kept);
- *  - SLUG fields are never model-translated: after the text fills land, each empty
- *    per-locale slug is derived (EC-315 `autoDeriveSlug`) from the translated source.
+ *    position whose value is unreadable (EC-752: text inside a value the traversal cannot
+ *    read too), a unit the provider did not return, a rich-text block whose translation did
+ *    not decode token-faithfully (fill-empty keeps the source's block in the fill;
+ *    retranslate-all leaves the whole target value as it was);
+ *  - SLUG fields are never model-translated: after the text fills land, each per-locale
+ *    slug that still FOLLOWS the base is derived (EC-315 `autoDeriveSlug`) from the
+ *    translated source — in both modes: a slug the editor set is never touched (EC-752 — a
+ *    changed slug moves the page's address, and nothing redirects it).
  *
  * Batching (improves on the Sanity precedent's context-blind per-block calls): units are
  * grouped per target locale and chunked into batches; each batch is ONE `generate` call
@@ -39,14 +50,14 @@
  * translates with cross-block context. Bounded concurrency (default 6) keeps a realistic
  * document well under the route's per-minute rate limit.
  */
-import { autoDeriveSlug, createCollectionRegistry, fieldValuePosition, isFieldLocalized, isWriterLocked, slugFieldOf, validateDocument, valuesInLocale, writeField, } from '@elytracms/core/cms-core';
+import { autoDeriveSlug, childPositions, createCollectionRegistry, declarationMayHold, fieldValuePosition, isFieldLocalized, isOpaquePosition, isWriterLocked, resolveField, slugFieldOf, validateDocument, valuesInLocale, writeField, } from '@elytracms/core/cms-core';
 import { introducedErrors, warningsOf } from './proposal-validation.js';
 import { fieldWritePatch } from '../cms/field-patch.js';
 import { fieldConnection, hasLocaleVariant } from '../locale/index.js';
 import { assembleKnowledgeBlock } from './knowledge.js';
 import { aiProvenance } from './provenance.js';
 import { extractRichTextUnits, rebuildRichTextReport } from './rich-text-translate.js';
-import { rebuildTextPositions, textPositionsOf } from './writer-form.js';
+import { lockedChanges, rebuildTextPositions, textPositionsOf, withLockedFrom } from './writer-form.js';
 /** Default translatable units per `generate` call. */
 export const DEFAULT_TRANSLATE_BATCH_SIZE = 12;
 /** Default number of `generate` calls in flight at once (mirrors the precedent's limiter of 6). */
@@ -88,6 +99,34 @@ function positionId(locale, field, position) {
     const key = positionKey(position);
     return key === '' ? `${locale}|${field}` : `${locale}|${field}|${key}`;
 }
+/** A declaration whose value is text a writer may translate (a unit, or a sequence of them). */
+function isTranslatableDeclaration(field) {
+    return (field.type === 'text' || field.type === 'richText' || field.type === 'blocks') && !isWriterLocked(field);
+}
+/**
+ * EC-752 (the EC-748 traversal contract, read by translate): every value at or below
+ * `root` the traversal cannot read (an {@link OpaquePosition} — a holder stored in a shape
+ * its declaration no longer reads) whose declaration may hold translatable text. Its text
+ * is no unit — it cannot be found — so the caller REPORTS it (`unreadable`), never leaves
+ * it untranslated with no word. A writer-locked position is not descended (no unit, never
+ * a skip — EC-716), exactly as {@link textPositionsOf} does.
+ */
+function unreadableTextUnder(root, ctx) {
+    const out = [];
+    const visit = (position) => {
+        if (isWriterLocked(position.field) || position.field.type === 'text')
+            return;
+        for (const child of childPositions(position, ctx)) {
+            if (!isOpaquePosition(child))
+                visit(child);
+            else if (!isWriterLocked(child.declaration) && declarationMayHold(child.declaration, isTranslatableDeclaration)) {
+                out.push(child);
+            }
+        }
+    };
+    visit(root);
+    return out;
+}
 /** A minimal bounded-concurrency limiter (the precedent's `createLimiter`). */
 function createLimiter(max) {
     let active = 0;
@@ -196,31 +235,39 @@ function chunk(items, size) {
         out.push(items.slice(i, i + size));
     return out;
 }
-export async function translateDocument(input) {
-    const { provider, collection, document, localeConfig } = input;
+/** A skip entry — the component it sits in, when it does. */
+function skipOf(field, locale, site, reason, at = site.at) {
+    return { field, locale, at, ...(site.component ? { component: { ...site.component } } : {}), reason };
+}
+/**
+ * EC-752 — THE pre-provider judge: which field × locale values a translation of `input`
+ * writes when every unit lands (`fill` / `replace`), and what it already knows it will not
+ * translate (`locked`, `unreadable`). Pure: no provider, no store, no clock. The studio's
+ * confirm lists it; {@link translateDocument} runs exactly it — one judge, never a second
+ * count. See {@link TranslatePlan} for why it is an upper bound.
+ */
+export function planTranslation(input) {
+    return planRun(input).plan;
+}
+function planRun(input) {
+    const { collection, document, localeConfig } = input;
     const mode = input.mode ?? 'fill-empty';
+    // EC-752 rule 2: a re-translation writes a field × locale WHOLE or not at all — it
+    // replaces a value someone made, so a part of it must never become the base's text.
+    const whole = mode === 'retranslate-all';
     // EC-580: the base is the project's default locale — the only default there is,
     // and the one the translate dialog names (MODE #12: the engine used to translate
     // FROM a per-document default while the dialog said "from EN").
     const base = localeConfig.default;
     const targets = (input.targetLocales ?? localeConfig.locales).filter((l) => l !== base);
-    const provenance = aiProvenance(provider, input.now ?? new Date().toISOString());
     // EC-593: the traversal reaches component props through the validator's own lookup.
     const lookupManifest = input.validateOptions?.lookupManifest;
     const positionCtx = lookupManifest ? { lookupManifest } : {};
-    // 1. Walk every text position of each connected bucket's base value → units + plans.
+    // Walk every text position of each eligible bucket's base value → units + plans.
     const units = [];
-    const plans = new Map();
+    const richPlans = new Map();
     const pending = [];
     const skipped = [];
-    const slugFields = collection.fields.filter((f) => isSlugField(f, collection) && !isWriterLocked(f) && isFieldLocalized(collection, f.name));
-    const skip = (field, locale, position, reason, at = position.at) => skipped.push({
-        field,
-        locale,
-        at,
-        ...(position.component ? { component: { ...position.component } } : {}),
-        reason,
-    });
     for (const field of collection.fields) {
         if (isWriterLocked(field))
             continue;
@@ -235,32 +282,49 @@ export async function translateDocument(input) {
             const eligible = mode === 'retranslate-all' ? conn.canFillFromBase : conn.connected && conn.canFillFromBase;
             if (!eligible)
                 continue;
-            const before = units.length;
+            // EC-738: the target keeps its locked content. The translation is the base value with
+            // its text replaced, and every locked position then taken from the target's DISPLAYED
+            // value by key; a bucket where that still loses or creates a locked value (the two
+            // differ in shape around it) is not written. Judged here, before any unit is sent:
+            // the text replacement changes neither the locked positions nor the shape around them.
+            // Fill-empty is unchanged by construction — a connected bucket displays the base.
+            const current = resolveField(collection, document, field.name, locale, localeConfig).value;
+            const root = fieldValuePosition(field, conn.baseValue, { locale: base });
+            const kept = withLockedFrom(root, current, positionCtx);
+            const changes = lockedChanges(fieldValuePosition(field, current, { locale }), kept, positionCtx);
+            if (changes.lost.length > 0 || changes.created.length > 0) {
+                skipped.push(skipOf(field.name, locale, root, 'locked'));
+                continue;
+            }
+            const bucketUnits = [];
+            const bucketPlans = new Map();
+            const bucketSkips = [];
+            const unreadable = (site) => bucketSkips.push(skipOf(field.name, locale, site, 'unreadable'));
             // EC-593: every text position of the base value — the converter module's fold
             // over core's ONE value-position traversal.
-            for (const position of textPositionsOf(fieldValuePosition(field, conn.baseValue, { locale: base }), positionCtx)) {
+            for (const position of textPositionsOf(root, positionCtx)) {
                 const { value } = position;
                 if (value === undefined || value === null)
                     continue;
                 if (position.field.type === 'text') {
                     if (typeof value !== 'string')
-                        skip(field.name, locale, position, 'unreadable');
+                        unreadable(position);
                     else if (value.trim().length > 0) {
-                        units.push({ kind: 'text', id: positionId(locale, field.name, position), locale, field: field.name, text: value });
+                        bucketUnits.push({ kind: 'text', id: positionId(locale, field.name, position), locale, field: field.name, text: value });
                     }
                     continue;
                 }
                 const extracted = extractRichTextUnits(value);
                 if (!extracted.readable) {
-                    skip(field.name, locale, position, 'unreadable');
+                    unreadable(position);
                     continue;
                 }
                 if (extracted.units.length === 0)
                     continue;
                 const planId = positionId(locale, field.name, position);
-                plans.set(planId, extracted.plan);
+                bucketPlans.set(planId, extracted.plan);
                 for (const block of extracted.units) {
-                    units.push({
+                    bucketUnits.push({
                         kind: 'richText',
                         id: `${planId}|${block.id}`,
                         locale,
@@ -271,10 +335,53 @@ export async function translateDocument(input) {
                     });
                 }
             }
-            if (units.length > before)
-                pending.push({ field, locale, base: conn.baseValue });
+            // EC-752 (8b): text inside a value the traversal cannot read is no unit — reported, not
+            // silent (once per location: an unreadable sequence was named by the walk above).
+            for (const opaque of unreadableTextUnder(root, positionCtx)) {
+                const at = JSON.stringify(opaque.at);
+                if (!bucketSkips.some((entry) => JSON.stringify(entry.at) === at))
+                    unreadable(opaque);
+            }
+            skipped.push(...bucketSkips);
+            // Rule 2, known before the provider: a value with text that cannot be translated is
+            // never re-translated in part — its whole bucket stays as it was (and spends no call).
+            if (whole && bucketSkips.length > 0)
+                continue;
+            if (bucketUnits.length === 0)
+                continue;
+            units.push(...bucketUnits);
+            for (const [id, plan] of bucketPlans)
+                richPlans.set(id, plan);
+            pending.push({ field, locale, base: conn.baseValue, current, kind: conn.connected ? 'fill' : 'replace' });
         }
     }
+    return {
+        plan: {
+            mode,
+            base,
+            targets,
+            buckets: pending.map(({ field, locale, kind }) => ({ field: field.name, locale, kind })),
+            skipped,
+            total: units.length,
+        },
+        units,
+        richPlans,
+        pending,
+        positionCtx,
+    };
+}
+export async function translateDocument(input) {
+    const { provider, collection, document, localeConfig } = input;
+    // EC-752 (rule 4): the run executes the ONE pre-provider plan — the list the studio's
+    // confirm showed is the list the units come from.
+    const { plan, units, richPlans: plans, pending, positionCtx } = planRun(input);
+    const { mode, base, targets } = plan;
+    const whole = mode === 'retranslate-all';
+    const provenance = aiProvenance(provider, input.now ?? new Date().toISOString());
+    const lookupManifest = input.validateOptions?.lookupManifest;
+    const skipped = [...plan.skipped];
+    const skip = (field, locale, position, reason, at = position.at) => skipped.push(skipOf(field, locale, position, reason, at));
+    const slugFields = collection.fields.filter((f) => isSlugField(f, collection) && !isWriterLocked(f) && isFieldLocalized(collection, f.name));
     const total = units.length;
     // 2. Batch per locale, translate with bounded concurrency, honour the abort signal.
     const batchSize = Math.max(1, input.batchSize ?? DEFAULT_TRANSLATE_BATCH_SIZE);
@@ -317,11 +424,12 @@ export async function translateDocument(input) {
     //    text position replaced (the traversal's writing fold), then slug derivation.
     //    `translated` / `perLocale` count applied UNITS (comparable to `total`).
     let next = document;
-    // EC-595 A2: every bucket this run writes, emitted as its patch at the end.
+    // EC-595 A2: every bucket this run writes, emitted as its patch at the end (EC-752:
+    // with what the write was — the outcome the studio reports).
     const written = new Map();
-    const write = (field, locale, value) => {
+    const write = (field, locale, value, kind) => {
         next = writeField(collection, next, field, locale, value, lookupManifest ? { lookupManifest } : {});
-        written.set(`${locale}|${field}`, { field, locale });
+        written.set(`${locale}|${field}`, { field, locale, kind });
     };
     const perLocale = {};
     let translated = 0;
@@ -343,18 +451,24 @@ export async function translateDocument(input) {
         'content',
         ...blockId.split('.').map(Number),
     ];
-    for (const { field, locale, base: baseValue } of pending) {
+    for (const { field, locale, base: baseValue, current, kind } of pending) {
         let applied = 0;
+        // EC-752 rule 2: whether every unit of the bucket landed — a unit never sent (a cancel),
+        // not returned, or a block whose tokens did not survive makes it incomplete.
+        let complete = true;
         // EC-593: the base value with each translated text position replaced — the
         // converter module's writing fold; every other value is carried from the base.
         const value = rebuildTextPositions(fieldValuePosition(field, baseValue, { locale: base }), positionCtx, (position) => {
             const id = positionId(locale, field.name, position);
             if (position.field.type === 'text') {
-                if (!attempted.has(id))
+                if (!attempted.has(id)) {
+                    complete = false;
                     return position.value;
+                }
                 const text = returned(id);
                 if (text === undefined) {
                     skip(field.name, locale, position, 'not-returned');
+                    complete = false;
                     return position.value;
                 }
                 applied += 1;
@@ -365,11 +479,15 @@ export async function translateDocument(input) {
                 return position.value;
             const blockTranslations = new Map();
             for (const [blockId, unit] of blocksOf.get(id) ?? []) {
-                if (!attempted.has(unit.id))
+                if (!attempted.has(unit.id)) {
+                    complete = false;
                     continue;
+                }
                 const text = returned(unit.id);
-                if (text === undefined)
+                if (text === undefined) {
                     skip(field.name, locale, position, 'not-returned', blockAt(position, blockId));
+                    complete = false;
+                }
                 else
                     blockTranslations.set(blockId, text);
             }
@@ -378,6 +496,7 @@ export async function translateDocument(input) {
             const rebuilt = rebuildRichTextReport(plan, blockTranslations);
             for (const blockId of rebuilt.rejected) {
                 skip(field.name, locale, position, 'structure-changed', blockAt(position, blockId));
+                complete = false;
             }
             if (rebuilt.applied.length === 0)
                 return position.value;
@@ -385,14 +504,22 @@ export async function translateDocument(input) {
             return rebuilt.value;
         });
         if (applied === 0)
-            continue; // nothing landed — the bucket stays connected to base
-        write(field.name, locale, value);
+            continue; // nothing landed — the bucket stays as it was
+        // EC-752 rule 2: a re-translation writes a field × locale only WHOLE. A part of it is
+        // never replaced by the base's text: the target keeps its value, the skips say why.
+        if (whole && !complete)
+            continue;
+        // EC-738: the target's locked positions, by key (judged in the plan).
+        write(field.name, locale, withLockedFrom(fieldValuePosition(field, value, { locale }), current, positionCtx), kind);
         bump(locale, applied);
     }
-    // 4. Slugs: derive each empty per-locale slug from the (now translated) source. Never
-    //    model-translated; only for a still-connected slug whose SOURCE field this run
-    //    actually translated (so the derived slug differs from the base — no pointless
-    //    divergence, and an aborted run with no translations derives nothing).
+    // 4. Slugs: derive each per-locale slug that still follows the base from the (now
+    //    translated) source. Never model-translated; only for a still-connected slug whose
+    //    SOURCE field holds its own value in that locale (so the derived slug differs from the
+    //    base — no pointless divergence, and an aborted run with no translations derives
+    //    nothing). EC-752 rule 1 — in BOTH modes: a slug the editor set is never touched. A
+    //    changed slug moves the page's address and nothing redirects the old one, so a
+    //    re-translation silently changing the URL was the measured ship-stopper.
     let slugsDerived = 0;
     for (const field of slugFields) {
         const sourceField = slugSourceField(field, collection);
@@ -400,7 +527,7 @@ export async function translateDocument(input) {
             const conn = fieldConnection(collection, next, field.name, locale, localeConfig);
             if (!conn)
                 continue;
-            if (mode !== 'retranslate-all' && !conn.connected)
+            if (!conn.connected)
                 continue;
             const sourceTranslated = sourceField
                 ? hasLocaleVariant(next, sourceField, locale)
@@ -411,7 +538,7 @@ export async function translateDocument(input) {
             const derived = autoDeriveSlug(field.slug, collection, valuesInLocale(collection, next, locale, localeConfig));
             if (!derived || derived === conn.baseValue)
                 continue;
-            write(field.name, locale, derived);
+            write(field.name, locale, derived, 'slug');
             slugsDerived += 1;
         }
     }
@@ -427,9 +554,17 @@ export async function translateDocument(input) {
         ...(input.validateOptions ?? {}),
     };
     const producedIssues = validateDocument(registry, next, validateOptions);
+    const writes = [...written.values()].map(({ field, locale, kind }) => ({
+        field,
+        locale,
+        kind,
+        patch: fieldWritePatch(collection, next, field, locale),
+    }));
     return {
         document: next,
-        patches: [...written.values()].map(({ field, locale }) => fieldWritePatch(collection, next, field, locale)),
+        plan,
+        writes,
+        patches: writes.map((entry) => entry.patch),
         total,
         translated,
         cancelled,