@avocadostudio-ai/orchestrator-core 0.22.0 → 0.23.0

package/dist/agents/edit-safety.js

@@ -0,0 +1,425 @@
+import { fieldText } from "../checks/field-walk.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Whether a value holds something a reader would miss.
+ *
+ * Booleans never count: `false` is a setting, not an absence. Objects count
+ * when any string or number inside them does, so an image `{ src: "" }` is
+ * empty and a rich-text document with one word is not.
+ */
+export function hasContent(value) {
+    if (value == null)
+        return false;
+    if (typeof value === "string")
+        return value.trim().length > 0;
+    if (typeof value === "number")
+        return Number.isFinite(value);
+    if (typeof value === "boolean")
+        return false;
+    if (Array.isArray(value))
+        return value.some((entry) => hasContent(entry) || isRecord(entry));
+    if (isRecord(value)) {
+        if (fieldText(value).trim().length > 0)
+            return true;
+        return Object.entries(value).some(([key, entry]) => key !== "id" && key !== "type" && hasContent(entry));
+    }
+    return false;
+}
+function shapeOf(value) {
+    if (typeof value === "string")
+        return "text";
+    if (typeof value === "number")
+        return "number";
+    if (Array.isArray(value))
+        return "list";
+    if (isRecord(value))
+        return "object";
+    return "other";
+}
+function definitionFor(manifest, type) {
+    return manifest.blocks.find((b) => b.type === type);
+}
+const BLOCK_LABEL_MAX = 48;
+/** What a reader calls a block: its first non-empty text field. Mirrors field-walk. */
+function labelFor(block, definition) {
+    const props = isRecord(block.props) ? block.props : {};
+    const keys = definition
+        ? Object.entries(definition.fields ?? {})
+            .filter(([, meta]) => meta.kind === "text")
+            .map(([key]) => key)
+        : Object.keys(props);
+    for (const key of keys) {
+        const value = props[key];
+        if (typeof value !== "string")
+            continue;
+        const trimmed = value.trim();
+        if (!trimmed || /^https?:\/\//.test(trimmed))
+            continue;
+        return trimmed.length > BLOCK_LABEL_MAX ? `${trimmed.slice(0, BLOCK_LABEL_MAX - 1)}…` : trimmed;
+    }
+    return undefined;
+}
+function itemFieldsFor(list, item) {
+    const merged = (list.itemFields ?? {});
+    if (!list.discriminator || !list.itemFieldsByType || !isRecord(item))
+        return merged;
+    const branch = item[list.discriminator];
+    if (typeof branch !== "string")
+        return merged;
+    return list.itemFieldsByType[branch] ?? merged;
+}
+/**
+ * Pair a list's items before and after the edit.
+ *
+ * By `id` when every item has one — the only pairing that survives an insert
+ * or a reorder. By position only when the list kept its length; otherwise a
+ * removed item would pair every later item with its neighbour and report
+ * fields as emptied that simply moved up.
+ */
+function pairItems(before, after) {
+    const idOf = (item) => (isRecord(item) && typeof item.id === "string" && item.id ? item.id : undefined);
+    const allHaveIds = before.every((item) => idOf(item)) && after.every((item) => idOf(item));
+    if (allHaveIds) {
+        const afterIndexById = new Map(after.map((item, index) => [idOf(item), index]));
+        const out = [];
+        for (const item of before) {
+            const id = idOf(item);
+            const index = afterIndexById.get(id);
+            if (index === undefined)
+                continue;
+            out.push({ before: item, after: after[index], afterIndex: index, itemId: id });
+        }
+        return out;
+    }
+    if (before.length !== after.length)
+        return [];
+    return before.map((item, index) => ({ before: item, after: after[index], afterIndex: index }));
+}
+function fieldChange(before, after, kind) {
+    if (!hasContent(before))
+        return null;
+    if (!hasContent(after))
+        return "emptied";
+    if (kind === "richtext")
+        return null;
+    const from = shapeOf(before);
+    const to = shapeOf(after);
+    if (from === to)
+        return null;
+    // Only a change a reader would notice: a list or an object collapsing into a
+    // scalar, or the reverse. A number stored as text is the same value.
+    const structural = (shape) => shape === "list" || shape === "object";
+    return structural(from) !== structural(to) ? "type_changed" : null;
+}
+function blockIssues(slug, before, after, manifest, ops) {
+    const definition = definitionFor(manifest, after.type) ?? definitionFor(manifest, before.type);
+    const beforeProps = isRecord(before.props) ? before.props : {};
+    const afterProps = isRecord(after.props) ? after.props : {};
+    const blockLabel = labelFor(before, definition);
+    const located = {
+        slug,
+        blockId: after.id,
+        blockType: after.type,
+        ...(blockLabel ? { blockLabel } : {})
+    };
+    const out = [];
+    const topLevel = definition
+        ? Object.entries(definition.fields ?? {}).map(([key, meta]) => [key, meta])
+        : Object.keys(beforeProps)
+            .filter((key) => key !== "id")
+            .map((key) => [key, undefined]);
+    const listKeys = new Set(Object.keys(definition?.listFields ?? {}));
+    for (const [key, meta] of topLevel) {
+        if (listKeys.has(key))
+            continue;
+        const change = fieldChange(beforeProps[key], afterProps[key], meta?.kind);
+        if (!change)
+            continue;
+        out.push({
+            kind: change,
+            ...located,
+            path: key,
+            ...(meta?.label ? { label: meta.label } : {}),
+            before: beforeProps[key],
+            after: afterProps[key] ?? null,
+            revert: { op: "update_props", pageSlug: slug, blockId: after.id, patch: { [key]: beforeProps[key] } }
+        });
+    }
+    for (const [listKey, list] of Object.entries(definition?.listFields ?? {})) {
+        const beforeItems = beforeProps[listKey];
+        const afterItems = afterProps[listKey];
+        if (!Array.isArray(beforeItems) || beforeItems.length === 0)
+            continue;
+        if (!Array.isArray(afterItems) || afterItems.length === 0) {
+            // The whole list went. One finding for it, not one per field inside it.
+            out.push({
+                kind: Array.isArray(afterItems) || afterItems == null ? "emptied" : "type_changed",
+                ...located,
+                path: listKey,
+                ...(list.label ? { label: list.label } : {}),
+                before: beforeItems,
+                after: afterItems ?? null,
+                revert: { op: "update_props", pageSlug: slug, blockId: after.id, patch: { [listKey]: beforeItems } }
+            });
+            continue;
+        }
+        out.push(...droppedItems(slug, located, listKey, list.label, beforeItems, afterItems, ops));
+        for (const pair of pairItems(beforeItems, afterItems)) {
+            if (!isRecord(pair.before))
+                continue;
+            const afterItem = isRecord(pair.after) ? pair.after : {};
+            for (const [itemKey, meta] of Object.entries(itemFieldsFor(list, pair.before))) {
+                const change = fieldChange(pair.before[itemKey], afterItem[itemKey], meta.kind);
+                if (!change)
+                    continue;
+                out.push({
+                    kind: change,
+                    ...located,
+                    path: `${listKey}[${pair.afterIndex}].${itemKey}`,
+                    ...(meta.label ? { label: meta.label } : {}),
+                    before: pair.before[itemKey],
+                    after: afterItem[itemKey] ?? null,
+                    revert: {
+                        op: "update_item",
+                        pageSlug: slug,
+                        blockId: after.id,
+                        listKey,
+                        ...(pair.itemId ? { itemId: pair.itemId } : { index: pair.afterIndex }),
+                        patch: { [itemKey]: pair.before[itemKey] }
+                    }
+                });
+            }
+        }
+    }
+    return out;
+}
+function itemIdOf(item) {
+    return isRecord(item) && typeof item.id === "string" && item.id ? item.id : undefined;
+}
+/**
+ * Entries that left a list without anyone removing them. Only reported when
+ * every entry carries an id — without ids a removal and a reorder cannot be
+ * told apart — and never for a list the batch explicitly removed from.
+ */
+function droppedItems(slug, located, listKey, listLabel, beforeItems, afterItems, ops) {
+    const removedOnPurpose = ops.some((op) => op.op === "remove_item" && op.pageSlug === slug && op.blockId === located.blockId && op.listKey === listKey);
+    if (removedOnPurpose)
+        return [];
+    if (!beforeItems.every(itemIdOf) || !afterItems.every(itemIdOf))
+        return [];
+    const surviving = new Set(afterItems.map((item) => itemIdOf(item)));
+    const out = [];
+    beforeItems.forEach((item, index) => {
+        const itemId = itemIdOf(item);
+        if (surviving.has(itemId) || !hasContent(item))
+            return;
+        const anchors = beforeItems
+            .slice(0, index)
+            .reverse()
+            .map((earlier) => itemIdOf(earlier));
+        const anchor = anchors.find((id) => surviving.has(id));
+        out.push({
+            kind: "item_dropped",
+            ...located,
+            path: `${listKey}[${index}]`,
+            ...(listLabel ? { label: listLabel } : {}),
+            listKey,
+            itemId,
+            before: item,
+            after: null,
+            anchors,
+            revert: {
+                op: "add_item",
+                pageSlug: located.slug,
+                blockId: located.blockId,
+                listKey,
+                item: structuredClone(item),
+                ...(anchor ? { afterItemId: anchor } : {})
+            }
+        });
+    });
+    return out;
+}
+const PAGE_META_FIELDS = ["title", "description", "ogImage"];
+/**
+ * Everything an edit did to one page that nobody asked for.
+ *
+ * `ops` is the batch that produced `after`: a block removed by a
+ * `remove_block` naming it was asked for and is not reported. A page created
+ * or deleted by the batch is not this agent's business — `before` or `after`
+ * is null and the answer is empty; deleting a page already goes through the
+ * destructive-action gate.
+ */
+export function detectEditDamage(args) {
+    const { slug, before, after, ops, manifest } = args;
+    if (!before || !after)
+        return [];
+    const out = [];
+    const beforeMeta = isRecord(before.meta) ? before.meta : {};
+    const afterMeta = isRecord(after.meta) ? after.meta : {};
+    for (const key of PAGE_META_FIELDS) {
+        if (!hasContent(beforeMeta[key]) || hasContent(afterMeta[key]))
+            continue;
+        out.push({
+            kind: "emptied",
+            slug,
+            path: `meta.${key}`,
+            before: beforeMeta[key],
+            after: afterMeta[key] ?? null,
+            revert: { op: "update_page_meta", pageSlug: after.slug, patch: { [key]: beforeMeta[key] } }
+        });
+    }
+    const removedOnPurpose = new Set(ops.flatMap((op) => (op.op === "remove_block" && op.pageSlug === slug ? [op.blockId] : [])));
+    const afterById = new Map(after.blocks.map((block) => [block.id, block]));
+    before.blocks.forEach((block, index) => {
+        const survivor = afterById.get(block.id);
+        if (survivor) {
+            out.push(...blockIssues(after.slug, block, survivor, manifest, ops));
+            return;
+        }
+        if (removedOnPurpose.has(block.id))
+            return;
+        // Put it back after the nearest earlier block that is still on the page,
+        // so it returns to where it was rather than to the end.
+        const anchors = before.blocks
+            .slice(0, index)
+            .reverse()
+            .map((candidate) => candidate.id);
+        const anchor = anchors.find((id) => afterById.has(id));
+        const blockLabel = labelFor(block, definitionFor(manifest, block.type));
+        out.push({
+            kind: "block_dropped",
+            slug,
+            blockId: block.id,
+            blockType: block.type,
+            ...(blockLabel ? { blockLabel } : {}),
+            before: block,
+            after: null,
+            anchors,
+            revert: {
+                op: "add_block",
+                pageSlug: after.slug,
+                ...(anchor ? { afterBlockId: anchor } : {}),
+                block: structuredClone(block)
+            }
+        });
+    });
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Reading a value back — for the stale check before a revert
+// ---------------------------------------------------------------------------
+const PATH_SEGMENT = /([^.[\]]+)|\[(\d+)\]/g;
+/** The value at an editable-target path inside `root`, or undefined. */
+export function valueAtPath(root, path) {
+    let current = root;
+    for (const match of path.matchAll(PATH_SEGMENT)) {
+        if (current == null)
+            return undefined;
+        if (match[2] !== undefined) {
+            if (!Array.isArray(current))
+                return undefined;
+            current = current[Number(match[2])];
+        }
+        else {
+            if (!isRecord(current))
+                return undefined;
+            current = current[match[1]];
+        }
+    }
+    return current;
+}
+/**
+ * What the issue's location holds on `page` now, in the same form `after` was
+ * recorded in. For a dropped block, the block if it is back; otherwise null.
+ */
+export function currentValueFor(issue, page) {
+    if (!page)
+        return undefined;
+    if (issue.kind === "block_dropped")
+        return page.blocks.find((b) => b.id === issue.blockId) ?? null;
+    if (!issue.path)
+        return undefined;
+    if (!issue.blockId)
+        return valueAtPath(page, issue.path) ?? null;
+    const block = page.blocks.find((b) => b.id === issue.blockId);
+    if (!block)
+        return undefined;
+    if (issue.kind === "item_dropped") {
+        const list = isRecord(block.props) ? block.props[issue.listKey ?? ""] : undefined;
+        if (!Array.isArray(list))
+            return undefined;
+        return list.find((item) => itemIdOf(item) === issue.itemId) ?? null;
+    }
+    return valueAtPath(block.props, issue.path) ?? null;
+}
+function stable(value) {
+    return JSON.stringify(value ?? null);
+}
+/**
+ * True while the location still holds exactly what the edit left there — the
+ * only state in which putting the old value back restores the edit's damage
+ * and nothing else.
+ */
+export function isStillAsEditLeftIt(issue, page) {
+    const current = currentValueFor(issue, page);
+    if (current === undefined)
+        return false;
+    if (issue.kind === "block_dropped" || issue.kind === "item_dropped")
+        return current === null;
+    return stable(current) === stable(issue.after);
+}
+export function countIssues(issues) {
+    return {
+        emptied: issues.filter((i) => i.kind === "emptied").length,
+        blocksDropped: issues.filter((i) => i.kind === "block_dropped").length,
+        itemsDropped: issues.filter((i) => i.kind === "item_dropped").length,
+        typeChanged: issues.filter((i) => i.kind === "type_changed").length
+    };
+}
+/** One English line for logs, the Inbox row and anything outside the editor. */
+export function describeIssues(issues) {
+    const counts = countIssues(issues);
+    const parts = [];
+    if (counts.emptied)
+        parts.push(`emptied ${counts.emptied} ${counts.emptied === 1 ? "field" : "fields"}`);
+    if (counts.blocksDropped) {
+        parts.push(`dropped ${counts.blocksDropped} ${counts.blocksDropped === 1 ? "block" : "blocks"}`);
+    }
+    if (counts.itemsDropped) {
+        parts.push(`dropped ${counts.itemsDropped} list ${counts.itemsDropped === 1 ? "entry" : "entries"}`);
+    }
+    if (counts.typeChanged) {
+        parts.push(`changed the shape of ${counts.typeChanged} ${counts.typeChanged === 1 ? "field" : "fields"}`);
+    }
+    if (parts.length <= 1)
+        return parts[0] ?? "";
+    return `${parts.slice(0, -1).join(", ")} and ${parts[parts.length - 1]}`;
+}
+/**
+ * The revert op for `issue`, re-anchored against `page` as it is now. For a
+ * dropped block or entry, the anchor is the nearest earlier neighbour that is
+ * on the page at this moment; every other revert is returned unchanged.
+ */
+export function revertFor(issue, page) {
+    const op = issue.revert;
+    if (!op || !issue.anchors || !page)
+        return op;
+    if (op.op === "add_block") {
+        const present = new Set(page.blocks.map((block) => block.id));
+        const anchor = issue.anchors.find((id) => present.has(id));
+        const { afterBlockId: _previous, ...rest } = op;
+        return anchor ? { ...rest, afterBlockId: anchor } : rest;
+    }
+    if (op.op === "add_item") {
+        const block = page.blocks.find((b) => b.id === op.blockId);
+        const list = block && isRecord(block.props) ? block.props[op.listKey] : undefined;
+        const present = new Set(Array.isArray(list) ? list.map(itemIdOf).filter(Boolean) : []);
+        const anchor = issue.anchors.find((id) => present.has(id));
+        const { afterItemId: _previous, ...rest } = op;
+        return anchor ? { ...rest, afterItemId: anchor } : rest;
+    }
+    return op;
+}

package/dist/agents/fix-writer.d.ts

@@ -0,0 +1,38 @@
+import { type Operation, type PageDoc } from "@avocadostudio-ai/shared";
+import type { FindingFix, FindingRecord } from "../durable/types.ts";
+import type { DraftClient } from "./draft-spec.ts";
+export type FixField = FindingFix["field"];
+/** The rules a fix can be written for, and which field each one fixes. */
+export declare const FIXABLE_RULES: Record<string, FixField>;
+export declare function fixFieldFor(ruleId: string): FixField | undefined;
+export type FixDeps = {
+    /** Text model for titles and descriptions. */
+    client?: DraftClient;
+    model?: string;
+    /** Vision alt text; defaults to the editor's own generator. */
+    altText?: (imageUrl: string) => Promise<string | null>;
+    /** Site facts, one per line: words to avoid, product names, tone. */
+    facts?: string[];
+};
+export type WriteFixResult = {
+    ok: true;
+    fix: FindingFix;
+} | {
+    ok: false;
+    error: string;
+};
+/** The value a fix for this finding replaces, read off the page as it is now. */
+export declare function currentValue(finding: Pick<FindingRecord, "ruleId" | "evidence">, page: PageDoc): string | undefined;
+/** The ops that put `text` in place — the same ops whether the text was written or edited. */
+export declare function fixOps(finding: Pick<FindingRecord, "ruleId" | "slug" | "evidence">, text: string): Operation[];
+/** What the page says, compactly: headings and the first sentences of its text, for the model to summarise. */
+export declare function pageDigest(page: PageDoc, maxChars?: number): string;
+/**
+ * Write a fix for one finding against the page as it is. A title or
+ * description outside its length is retried once with the count; a second
+ * miss is refused rather than stored, because the fix would reopen the very
+ * finding it was written for.
+ */
+export declare function writeFix(finding: FindingRecord, page: PageDoc, deps?: FixDeps): Promise<WriteFixResult>;
+/** "German" for "de": the model is told a language, not a code. */
+export declare function languageName(code: string): string;

package/dist/agents/fix-writer.js

@@ -0,0 +1,197 @@
+import { buildBlockManifest } from "@avocadostudio-ai/shared";
+import { fieldText, walkPageFields } from "../checks/field-walk.js";
+import { DESCRIPTION_MAX, DESCRIPTION_MIN, effectiveTitle, TITLE_MAX, TITLE_MIN } from "../checks/rules-draft.js";
+import { getAnthropicClient } from "../chat/anthropic-planner.js";
+import { defaultModelLookup } from "../chat/model-defaults.js";
+import { generateAltTextFromVision } from "../chat/vision-alt-generator.js";
+/** The rules a fix can be written for, and which field each one fixes. */
+export const FIXABLE_RULES = {
+    "seo.title-missing": "title",
+    "seo.title-length": "title",
+    "seo.description-missing": "description",
+    "seo.description-length": "description",
+    "a11y.alt-missing": "alt",
+    "i18n.untranslated": "translation"
+};
+export function fixFieldFor(ruleId) {
+    return FIXABLE_RULES[ruleId];
+}
+const LIMITS = {
+    title: [TITLE_MIN, TITLE_MAX],
+    description: [DESCRIPTION_MIN, DESCRIPTION_MAX]
+};
+/** The value a fix for this finding replaces, read off the page as it is now. */
+export function currentValue(finding, page) {
+    const field = fixFieldFor(finding.ruleId);
+    if (field === "title")
+        return effectiveTitle(page);
+    if (field === "description")
+        return (page.meta?.description ?? "").trim();
+    if (field === "alt" || field === "translation") {
+        const { blockId, path } = finding.evidence ?? {};
+        if (!blockId || !path)
+            return undefined;
+        const entry = walkPageFields(page, buildBlockManifest()).find((f) => f.blockId === blockId && f.path === path);
+        return entry ? fieldText(entry.value).trim() : undefined;
+    }
+    return undefined;
+}
+/** The ops that put `text` in place — the same ops whether the text was written or edited. */
+export function fixOps(finding, text) {
+    const field = fixFieldFor(finding.ruleId);
+    if (field === "title")
+        return [{ op: "update_page_meta", pageSlug: finding.slug, patch: { title: text } }];
+    if (field === "description")
+        return [{ op: "update_page_meta", pageSlug: finding.slug, patch: { description: text } }];
+    const { blockId, path } = finding.evidence ?? {};
+    if ((field === "alt" || field === "translation") && blockId && path) {
+        return [{ op: "update_props", pageSlug: finding.slug, blockId, patch: { [path]: text } }];
+    }
+    return [];
+}
+/** What the page says, compactly: headings and the first sentences of its text, for the model to summarise. */
+export function pageDigest(page, maxChars = 2500) {
+    const lines = [];
+    for (const entry of walkPageFields(page, buildBlockManifest())) {
+        if (entry.kind !== "text" && entry.kind !== "richtext")
+            continue;
+        const text = fieldText(entry.value).replace(/\s+/g, " ").trim();
+        if (text.length < 3 || /^https?:\/\//.test(text))
+            continue;
+        lines.push(`${entry.blockType}.${entry.path}: ${text.slice(0, 300)}`);
+    }
+    return lines.join("\n").slice(0, maxChars);
+}
+function systemPrompt(field) {
+    const [min, max] = LIMITS[field];
+    const what = field === "title"
+        ? `the page's title for search results and the browser tab`
+        : `the page's meta description for search results and link previews`;
+    return [
+        `You write ${what}.`,
+        `Length: between ${min} and ${max} characters. Count carefully; this is checked.`,
+        "Write in the language the page's content is written in.",
+        "Say what the page is about, specifically, using the page's own words and facts. Never invent a claim, a price, an offer or a date the page does not state.",
+        field === "title"
+            ? "No quotes. Put the most specific words first. You may end with the site's name after a separator if it fits."
+            : "One or two plain sentences. No quotes, no emoji, no calls to action the page does not make.",
+        "The site facts you are given are rules about the site's wording — follow them (words to avoid, product names, spelling).",
+        'Reply with JSON: {"text": "..."}.'
+    ].join("\n");
+}
+const TEXT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["text"],
+    properties: { text: { type: "string" } }
+};
+async function writeText(field, page, deps, retryNote) {
+    const client = deps.client ?? getAnthropicClient();
+    const model = deps.model ?? defaultModelLookup().anthropic.balanced;
+    const user = {
+        slug: page.slug,
+        currentTitle: effectiveTitle(page) || null,
+        currentDescription: (page.meta?.description ?? "").trim() || null,
+        siteFacts: deps.facts ?? [],
+        content: pageDigest(page),
+        ...(retryNote ? { previousAttempt: retryNote } : {})
+    };
+    const response = await client.messages.create({
+        model,
+        max_tokens: 400,
+        system: systemPrompt(field),
+        output_config: { format: { type: "json_schema", schema: TEXT_SCHEMA } },
+        messages: [{ role: "user", content: JSON.stringify(user) }]
+    }, { signal: AbortSignal.timeout(60_000) });
+    const raw = response.content.find((block) => block.type === "text")?.text ?? "";
+    const text = String(JSON.parse(raw || "{}").text ?? "");
+    return text.replace(/\s+/g, " ").trim().replace(/^["“„']+|["”']+$/g, "");
+}
+/**
+ * Write a fix for one finding against the page as it is. A title or
+ * description outside its length is retried once with the count; a second
+ * miss is refused rather than stored, because the fix would reopen the very
+ * finding it was written for.
+ */
+export async function writeFix(finding, page, deps = {}) {
+    const field = fixFieldFor(finding.ruleId);
+    if (!field)
+        return { ok: false, error: "no fix can be written for this kind of finding" };
+    const base = currentValue(finding, page);
+    if (base === undefined)
+        return { ok: false, error: "the field this finding is about is no longer on the page" };
+    if (field === "alt") {
+        const imageUrl = finding.evidence?.imageUrl;
+        if (!imageUrl)
+            return { ok: false, error: "the finding does not say which image it is about" };
+        const generate = deps.altText ?? ((url) => generateAltTextFromVision({ imageUrl: url, preferredProvider: "anthropic" }));
+        const text = (await generate(imageUrl))?.trim();
+        if (!text)
+            return { ok: false, error: "the image could not be described" };
+        return { ok: true, fix: { field, text, base, ops: fixOps(finding, text), by: "vision", at: Date.now() } };
+    }
+    if (field === "translation")
+        return writeTranslation(finding, page, base, deps);
+    const [min, max] = LIMITS[field];
+    let text = await writeText(field, page, deps);
+    if (text.length < min || text.length > max) {
+        text = await writeText(field, page, deps, `"${text}" is ${text.length} characters; it must be ${min}–${max}.`);
+    }
+    if (text.length < min || text.length > max) {
+        return { ok: false, error: `the ${field} came back ${text.length} characters, outside ${min}–${max}` };
+    }
+    return {
+        ok: true,
+        fix: { field, text, base, ops: fixOps(finding, text), by: deps.model ?? defaultModelLookup().anthropic.balanced, at: Date.now() }
+    };
+}
+/** "German" for "de": the model is told a language, not a code. */
+export function languageName(code) {
+    try {
+        return new Intl.DisplayNames(["en"], { type: "language" }).of(code) ?? code;
+    }
+    catch {
+        return code;
+    }
+}
+/**
+ * Translate a field a translated page left in the source language. Plain text
+ * only: a rich-text field would lose its formatting as a string, and is left
+ * to the chat, which translates documents block by block.
+ */
+async function writeTranslation(finding, page, base, deps) {
+    const locale = finding.evidence?.locale;
+    if (!locale)
+        return { ok: false, error: "the finding does not say which language the page is in" };
+    const raw = rawValue(finding, page);
+    if (typeof raw !== "string")
+        return { ok: false, error: "rich text is translated in the chat, where its formatting survives" };
+    const client = deps.client ?? getAnthropicClient();
+    const model = deps.model ?? defaultModelLookup().anthropic.balanced;
+    const language = languageName(locale);
+    const response = await client.messages.create({
+        model,
+        max_tokens: 1200,
+        system: [
+            `You translate website copy into ${language}.`,
+            "Keep the meaning, the tone and the length close to the original. Keep names, product names and numbers as they are.",
+            "The site facts you are given are rules about the site's wording, including its glossary — follow them.",
+            'Reply with JSON: {"text": "..."}.'
+        ].join("\n"),
+        output_config: { format: { type: "json_schema", schema: TEXT_SCHEMA } },
+        messages: [{ role: "user", content: JSON.stringify({ language, text: finding.evidence?.sourceText ?? base, siteFacts: deps.facts ?? [] }) }]
+    }, { signal: AbortSignal.timeout(60_000) });
+    const out = String(JSON.parse(response.content.find((b) => b.type === "text")?.text || "{}").text ?? "").trim();
+    if (!out)
+        return { ok: false, error: "the translation came back empty" };
+    if (out === base)
+        return { ok: false, error: "the translation came back unchanged" };
+    return { ok: true, fix: { field: "translation", text: out, base, ops: fixOps(finding, out), by: model, at: Date.now() } };
+}
+/** The field's stored value, untouched — to tell plain text from a rich-text document. */
+function rawValue(finding, page) {
+    const { blockId, path } = finding.evidence ?? {};
+    if (!blockId || !path)
+        return undefined;
+    return walkPageFields(page, buildBlockManifest()).find((f) => f.blockId === blockId && f.path === path)?.value;
+}