@purposeinplay/payload-ai-translate 0.1.0

package/dist/lib/error-messages.js

@@ -0,0 +1,626 @@
+/**
+ * Editor-facing error catalogue.
+ *
+ * Single source of truth for every error / soft-skip / alert / endpoint
+ * failure that surfaces to a content editor in the admin UI. Plugin
+ * internals throw / log machine codes; this file maps each code to
+ * plain-English copy keyed by `{ title, body, action?, explanation? }`.
+ *
+ * Why this exists: editors hit the Translation Hub, AlertBanner, doc-view
+ * Translate modal, etc. and used to see raw `err.message` text like
+ * "NoObjectGeneratedError: Response was not valid JSON" or internal codes
+ * like "Code: permanent.config". Engineers can debug those; editors can't.
+ * Every render site now routes through `editorMessageFor(code, ctx)` and
+ * shows the raw text only behind a "Show technical details" disclosure.
+ *
+ * Adding a new code: add the literal to `EditorErrorCode`, register a
+ * formatter in `MESSAGES`, set `isPermanentFailure` if applicable. Tests
+ * in `error-messages.test.ts` enforce that every code has a formatter.
+ */ // ---------------------------------------------------------------------------
+// Code taxonomy
+// ---------------------------------------------------------------------------
+/**
+ * Every code an editor can encounter in the UI. Grouped by source:
+ *
+ * - `bulk.*` — `FailureCode` from `tasks/bulk-translate-doc-task.ts`
+ *   classifyError(). Persisted on `bulk_translate_units.failureCode`.
+ * - `soft-skip.*` — Validation outcome from `lib/output-validation.ts`
+ *   when an LLM response is rejected without erroring. Persisted on
+ *   `translation-usage.targetLocales[].softSkippedFields[].reasonCode`.
+ * - `cost-guard.*` — Throws from `lib/cost-guards.ts`. Persisted on
+ *   `translation-alerts.metadata.code` when alert is `cost-guard-abort`.
+ * - `alert.*` — `translation-alerts.alertType`. The collection itself
+ *   already enums these.
+ * - `endpoint.*` — Response.error.code from `endpoints/translation-hub/*`.
+ * - `marker.*` — Special-case `failureMessage` values written by admin
+ *   actions (cancel / force-reset) that aren't real failures.
+ */ // ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+const USD_FORMATTER = new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: 'USD',
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2
+});
+const NUMBER_FORMATTER = new Intl.NumberFormat('en-US');
+function formatUsd(value) {
+    if (value == null || !Number.isFinite(value)) return '$0.00';
+    return USD_FORMATTER.format(value);
+}
+function formatNumber(value) {
+    if (value == null || !Number.isFinite(value)) return '0';
+    return NUMBER_FORMATTER.format(value);
+}
+/**
+ * Best-effort mapping from locale code to a human label. The plugin
+ * doesn't ship an exhaustive locale name table — for unknown codes
+ * we render the code wrapped (e.g. "the 'es-419' locale") so the
+ * meaning is still inferable.
+ */ function localeLabel(locale) {
+    if (!locale) return 'a target language';
+    const lower = locale.toLowerCase();
+    const known = {
+        en: 'English',
+        es: 'Spanish',
+        fr: 'French',
+        de: 'German',
+        it: 'Italian',
+        pt: 'Portuguese',
+        ru: 'Russian',
+        ja: 'Japanese',
+        zh: 'Chinese',
+        ko: 'Korean',
+        ar: 'Arabic',
+        nl: 'Dutch',
+        pl: 'Polish',
+        sv: 'Swedish',
+        tr: 'Turkish',
+        uk: 'Ukrainian',
+        cs: 'Czech',
+        ro: 'Romanian',
+        hu: 'Hungarian',
+        da: 'Danish',
+        fi: 'Finnish',
+        no: 'Norwegian'
+    };
+    return known[lower] ?? known[lower.split(/[-_]/)[0] ?? ''] ?? `the '${locale}' locale`;
+}
+const MESSAGES = {
+    // -------------------------------------------------------------------------
+    // Bulk worker failures — surface on bulk_translate_units rows
+    // -------------------------------------------------------------------------
+    'bulk.transient.rate_limited': ()=>({
+            title: 'Translation service is busy',
+            body: "The translation service is handling too many requests right now. We're retrying automatically.",
+            action: 'Wait a few minutes, or contact engineering if it keeps failing.'
+        }),
+    'bulk.transient.provider': ()=>({
+            title: 'Translation service temporarily down',
+            body: 'The translation service returned an error. This is usually temporary.',
+            action: "We're retrying automatically. If it keeps failing, contact engineering."
+        }),
+    'bulk.transient.crashed': ()=>({
+            title: 'Translation stopped mid-run',
+            body: 'The translation worker stopped before finishing this document — usually because of a server restart.',
+            action: 'Click Retry to translate it again.'
+        }),
+    'bulk.permanent.schema': ()=>({
+            // 2026-06-05: copy revised. Old copy ("AI response was unreadable /
+            // Contact engineering — this needs a configuration fix") pointed
+            // editors at the wrong remedy. This bucket actually catches two
+            // distinct LLM-output-quality outcomes: (1) the response wasn't
+            // valid structured output (parser couldn't read it), or (2) the
+            // validator rejected the translation per-field (e.g. ratio too
+            // short for dense target locales like zh/ja/ko on long English
+            // sources). Neither is a "configuration fix" — both benefit from
+            // a retry on a more capable model, OR are legitimate edge cases
+            // the editor needs to translate manually.
+            title: 'Some fields couldn’t be auto-translated',
+            body: 'The AI’s response for these fields didn’t meet our quality checks — usually the output was cut off, much shorter than the source, or returned in an unexpected format. The fields are listed below.',
+            action: 'Open the document on this locale to translate the listed fields manually, or click Retry to try again (often works on the second pass, especially with a different model).',
+            explanation: 'This usually happens when the AI hits its output limit or returns content too short to match the source. Common for very dense target languages (Chinese, Japanese, Korean) on long English passages. Retrying often works; if it persistently fails on the same fields, edit them manually.'
+        }),
+    'bulk.permanent.too_large': ()=>({
+            title: 'Document exceeds size limit',
+            body: 'This document is too large to translate in one pass.',
+            action: 'Split it into shorter sections, or ask engineering to raise the limit.',
+            explanation: "Translation requests are capped at a per-document character limit to keep costs predictable. Documents above the cap won't fit in a single AI call. Splitting into smaller sections is the quickest fix; engineering can also raise the cap if needed."
+        }),
+    'bulk.permanent.config': ()=>({
+            title: 'Translation system is not set up',
+            body: 'The translation system rejected this document due to a configuration issue — missing authentication, invalid AI model, or unsupported content type.',
+            action: 'Contact engineering to fix the settings.',
+            explanation: "Configuration problems won't resolve on retry. Engineering needs to check the authentication keys, allowed content types, and AI model settings."
+        }),
+    'bulk.permanent.deleted': ()=>({
+            title: 'Document was deleted',
+            body: 'This document no longer exists — it was deleted after the run started.',
+            action: 'The run continues with remaining documents.',
+            explanation: "The document was removed between the time we started the run and when we tried to translate it. There's nothing left to translate."
+        }),
+    'bulk.unknown': ()=>({
+            title: 'Translation failed unexpectedly',
+            body: "Something went wrong, but we couldn't identify what.",
+            action: 'Try again. If it persists, contact engineering with the document ID.'
+        }),
+    // -------------------------------------------------------------------------
+    // Soft-skips — surfaced in the UsageTable expanded row
+    // -------------------------------------------------------------------------
+    'soft-skip.echoed': (ctx)=>({
+            title: "AI didn't translate this field",
+            body: `The AI returned the source text unchanged for ${localeLabel(ctx.locale)} — it may be a brand name, URL, or term that shouldn't be translated.`,
+            action: 'Open the document and edit the field manually if needed.'
+        }),
+    'soft-skip.too-short': (ctx)=>({
+            title: 'Translation was too short',
+            body: 'The translation is much shorter than the source — usually because the AI cut off its output. We kept the source text instead of saving a partial translation.',
+            action: 'Open the document and translate the field manually, or try again.'
+        }),
+    'soft-skip.too-long': ()=>({
+            title: 'Translation was too long',
+            body: 'The translation is much longer than the source — usually because the AI repeated itself or added extra content. We kept the source text instead.',
+            action: 'Open the document and translate the field manually, or try again.'
+        }),
+    'soft-skip.placeholders': (ctx)=>{
+        const missing = ctx.missingPlaceholders?.length ?? 0;
+        const extra = ctx.extraPlaceholders?.length ?? 0;
+        const issues = [];
+        if (missing) issues.push(`lost ${missing} formatting tag${missing === 1 ? '' : 's'}`);
+        if (extra) issues.push(`added ${extra} extra tag${extra === 1 ? '' : 's'}`);
+        const detail = issues.join(' and ');
+        return {
+            title: 'Translation broke formatting',
+            body: `The translation ${detail || 'changed formatting tags'} (bold, links, italics, etc.). We kept the source text to protect the formatting.`,
+            action: 'Open the document and translate the field manually, or try again.'
+        };
+    },
+    'soft-skip.refusal': ()=>({
+            title: 'AI refused to translate',
+            body: 'The AI returned a refusal instead of a translation. We kept the source text.',
+            action: 'Try a different model, or translate the field manually.'
+        }),
+    'soft-skip.injection': ()=>({
+            title: 'Translation contained suspicious code',
+            body: "The AI's response included tags that looked like code or system instructions. We kept the source text as a safety precaution.",
+            action: 'Try again, or contact engineering if it persists.'
+        }),
+    'soft-skip.control-chars': ()=>({
+            title: 'Translation had invalid characters',
+            body: "The AI's response included characters we can't store safely. We kept the source text.",
+            action: 'Try again.'
+        }),
+    // -------------------------------------------------------------------------
+    // Cost guards — surface in AlertBanner + Preflight modal
+    // -------------------------------------------------------------------------
+    'cost-guard.per-call': (ctx)=>({
+            title: 'Section is too large to translate',
+            body: `This section is ${formatNumber(ctx.chars)} characters, above the per-translation limit of ${formatNumber(ctx.limit)}.`,
+            action: 'Split it into smaller sections, or ask engineering to raise the limit.',
+            explanation: "Translation requests are limited to keep AI costs predictable. Sections above the limit can't be sent in one piece. Splitting the content is the quickest fix; engineering can also raise the limit if needed."
+        }),
+    'cost-guard.per-doc': (ctx)=>({
+            title: 'Document exceeds the size limit',
+            body: `This document is ${formatNumber(ctx.chars)} characters, above the limit of ${formatNumber(ctx.limit)}.`,
+            action: 'Split it into shorter sections, or ask engineering to raise the limit.',
+            explanation: "Documents are capped at a maximum size to keep translation costs predictable. Documents above the cap can't be translated as a whole. Engineering can raise the cap if needed."
+        }),
+    'cost-guard.daily-cap': (ctx)=>({
+            title: 'Daily budget reached',
+            body: `You've spent ${formatUsd(ctx.spent)} of the ${formatUsd(ctx.cap)} daily limit.`,
+            action: 'The budget resets at midnight UTC. Ask engineering to raise the limit if you need to translate sooner.',
+            explanation: 'Translation is capped at a daily budget to prevent runaway costs. New translations are blocked once the cap is reached until the next UTC day. Engineering can increase the cap if needed.'
+        }),
+    // -------------------------------------------------------------------------
+    // Alert types — surface in AlertBanner
+    // -------------------------------------------------------------------------
+    'alert.persistent-failure': (ctx)=>{
+        // HUB-2 / NEW-13 (v1.2.6): standardised on "attempts" — matches the
+        // recorded `attempts` column on `bulk_translate_units` and the
+        // BucketRow "Attempts" label. `ctx.maxAttempts` is sourced from
+        // `retryConfig.attempts` (DEFAULT_RETRY.attempts in defaults.ts), so
+        // the number reflects the real configured retry budget instead of a
+        // hard-coded "3" fallback that drifted from the default of 2.
+        const attempts = ctx.maxAttempts ?? 2;
+        return {
+            title: 'Translation failed repeatedly',
+            body: `${formatNumber(ctx.count)} field${ctx.count === 1 ? '' : 's'} couldn't be translated to ${localeLabel(ctx.locale)} after ${formatNumber(attempts)} attempt${attempts === 1 ? '' : 's'}.`,
+            action: 'Open the document and review the failed fields. Contact engineering if the problem persists.'
+        };
+    },
+    'alert.cost-guard-abort': ()=>({
+            title: 'Translation stopped — document too large',
+            body: 'We stopped the translation because the document exceeded the size limit. No partial translation was saved.',
+            action: 'See the alert details for the specific document. Split it into shorter pieces or ask engineering to raise the limit.'
+        }),
+    'alert.provider-outage': ()=>({
+            title: 'Translation service is down',
+            body: 'The translation service has been experiencing errors. New translations may fail until it recovers.',
+            action: 'Try again later. Engineering is aware.'
+        }),
+    // -------------------------------------------------------------------------
+    // Hub endpoint error codes
+    // -------------------------------------------------------------------------
+    'endpoint.invalid_state': (ctx)=>{
+        const status = ctx.status ?? 'unknown';
+        if (status === 'running' || status === 'pending') {
+            return {
+                title: 'Run is still in progress',
+                body: "You can't do this while the translation run is in progress.",
+                action: 'Wait for it to finish, or cancel it first.'
+            };
+        }
+        if (status === 'cancelling') {
+            return {
+                title: 'Run is already being cancelled',
+                body: 'A cancellation is in progress — no need to cancel again.',
+                action: "Refresh the page if the status doesn't update in a few seconds."
+            };
+        }
+        return {
+            title: 'Run has already ended',
+            body: 'This run is finished.',
+            action: 'Refresh the page to see the latest status.'
+        };
+    },
+    'endpoint.not_found': ()=>({
+            title: "Run doesn't exist",
+            body: "This translation run can't be found.",
+            action: 'Refresh the page.'
+        }),
+    'endpoint.totp_invalid': ()=>({
+            title: 'Authentication code was incorrect',
+            body: "The 6-digit code from your authenticator app didn't match.",
+            action: 'Check your authenticator app and try again.'
+        }),
+    'endpoint.totp_missing': ()=>({
+            title: 'Authentication code required',
+            body: 'This action needs a 6-digit code from your authenticator app.',
+            action: 'Enter the code shown in your authenticator app.'
+        }),
+    'endpoint.totp_plugin_unavailable': ()=>({
+            title: 'Two-factor authentication not set up',
+            body: "This action requires two-factor authentication, but it hasn't been enabled on your account.",
+            action: 'Go to Account → Security and enrol your authenticator app first.'
+        }),
+    'endpoint.daily_cap_exceeded': (ctx)=>({
+            title: 'Daily budget exceeded',
+            body: `You've spent ${formatUsd(ctx.spent)} of the ${formatUsd(ctx.cap)} daily limit${ctx.delta != null ? `. This would add about ${formatUsd(ctx.delta)}` : ''}.`,
+            action: 'The budget resets at midnight UTC. Ask engineering to raise the limit if you need to translate sooner.'
+        }),
+    'endpoint.concurrent_batch': ()=>({
+            title: 'A translation run is already in progress',
+            body: 'Only one translation run can be active at a time.',
+            action: 'Cancel the current run before starting a new one.'
+        }),
+    'endpoint.not_configured': ()=>({
+            title: 'Translation is not set up',
+            body: "Translation hasn't been configured for this site.",
+            action: 'Contact engineering to enable it.'
+        }),
+    'endpoint.window_expired': (ctx)=>{
+        const elapsed = ctx.hoursElapsed != null ? `${formatNumber(ctx.hoursElapsed)}h` : 'too long';
+        const window = ctx.hoursWindow != null ? `${formatNumber(ctx.hoursWindow)}h` : 'the undo window';
+        return {
+            title: 'Undo window expired',
+            body: `The ${window} undo window closed (this run was ${elapsed} ago).`,
+            action: 'Contact engineering if you need to restore the previous version.'
+        };
+    },
+    'endpoint.cost_unavailable': ()=>({
+            title: 'Cost estimate unavailable',
+            body: "We couldn't estimate the cost for this translation. For safety, the run is blocked.",
+            action: "Contact engineering — the AI model's pricing may need to be configured."
+        }),
+    'endpoint.invalid_batch_id': ()=>({
+            title: 'Run ID is invalid',
+            body: 'The run ID in the link is malformed.',
+            action: 'Refresh the page or go back to the Translation Hub.'
+        }),
+    'endpoint.invalid_json': ()=>({
+            title: 'Request failed',
+            body: 'The data for this action was malformed.',
+            action: 'Refresh the page and try again. Contact engineering if it persists.'
+        }),
+    'endpoint.forbidden': ()=>({
+            title: "You don't have permission",
+            body: "Your account can't perform this action.",
+            action: 'Contact an admin if this is incorrect.'
+        }),
+    'endpoint.unauthorized': ()=>({
+            title: 'Please sign in again',
+            body: 'Your session expired.',
+            action: 'Sign in and try again.'
+        }),
+    // -------------------------------------------------------------------------
+    // Admin action markers — written to failureMessage when an admin
+    // cancelled or force-reset a unit. Not real failures.
+    // -------------------------------------------------------------------------
+    'marker.cancelled-by-admin': ()=>({
+            title: 'Cancelled by an admin',
+            body: 'This translation was stopped before it could run.'
+        }),
+    'marker.force-reset-by-admin': ()=>({
+            title: 'Reset by admin',
+            body: 'This translation was manually reset after it stalled.'
+        }),
+    'marker.cancelled-mid-flight': ()=>({
+            title: 'Stopped mid-run',
+            body: "This document was being translated when the run was cancelled — it didn't finish in time.",
+            action: 'Start a new run to translate the remaining documents.'
+        })
+};
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Returns the editor-facing message for a given code. When the code is
+ * unknown (e.g. legacy data with a code we no longer ship), returns a
+ * safe fallback rather than rendering `undefined` in the UI.
+ */ export function editorMessageFor(code, ctx = {}) {
+    if (code && code in MESSAGES) {
+        return MESSAGES[code](ctx);
+    }
+    return {
+        title: 'Something went wrong',
+        body: "The system reported an error we don't have a friendly description for.",
+        action: 'Try again. If it keeps happening, contact engineering with the run details.'
+    };
+}
+/**
+ * `true` when the code names a failure that won't fix itself on retry
+ * — used to disable the Retry button in the UI and show the inline
+ * "Why won't this work?" explanation. Conservative by design: when
+ * we're not sure, allow retry.
+ */ export function isPermanentFailure(code) {
+    if (!code) return false;
+    return code === 'bulk.permanent.schema' || code === 'bulk.permanent.too_large' || code === 'bulk.permanent.config' || code === 'bulk.permanent.deleted' || code === 'cost-guard.per-call' || code === 'cost-guard.per-doc';
+}
+/**
+ * Adapter from the bulk worker's `FailureCode` (machine enum on the
+ * `bulk_translate_units.failureCode` column) to an `EditorErrorCode`.
+ * Keeps the persistence enum unchanged while letting the UI key off
+ * the catalogue.
+ */ export function editorCodeFromFailureCode(failureCode) {
+    switch(failureCode){
+        case 'transient.rate_limited':
+            return 'bulk.transient.rate_limited';
+        case 'transient.provider':
+            return 'bulk.transient.provider';
+        case 'transient.crashed':
+            return 'bulk.transient.crashed';
+        case 'permanent.schema':
+            return 'bulk.permanent.schema';
+        case 'permanent.too_large':
+            return 'bulk.permanent.too_large';
+        case 'permanent.config':
+            return 'bulk.permanent.config';
+        case 'permanent.deleted':
+            return 'bulk.permanent.deleted';
+        default:
+            return 'bulk.unknown';
+    }
+}
+/**
+ * Adapter from the alerts collection's `alertType` enum to an
+ * `EditorErrorCode`. Used by AlertBanner to render the friendly
+ * message via the catalogue.
+ */ export function editorCodeFromAlertType(alertType) {
+    switch(alertType){
+        case 'persistent-failure':
+            return 'alert.persistent-failure';
+        case 'cost-guard-abort':
+            return 'alert.cost-guard-abort';
+        case 'provider-outage':
+            return 'alert.provider-outage';
+        default:
+            return 'alert.persistent-failure';
+    }
+}
+/**
+ * Adapter from the cost-guard throw's `code` property to an
+ * `EditorErrorCode`. Used in API catch blocks that emitAlert.
+ */ export function editorCodeFromCostGuardCode(costGuardCode) {
+    switch(costGuardCode){
+        case 'PER_CALL_LIMIT':
+            return 'cost-guard.per-call';
+        case 'PER_DOC_CEILING':
+            return 'cost-guard.per-doc';
+        default:
+            return 'cost-guard.per-doc';
+    }
+}
+/**
+ * Adapter from a `failureMessage` enum marker (admin action) to an
+ * `EditorErrorCode`. Returns `null` when the message is a real error
+ * (not an admin marker) so callers can fall back to `failureCode`.
+ */ export function editorCodeFromFailureMessageMarker(failureMessage) {
+    if (!failureMessage) return null;
+    if (failureMessage === 'cancelled_by_admin') return 'marker.cancelled-by-admin';
+    if (failureMessage === 'force-reset by admin') return 'marker.force-reset-by-admin';
+    return null;
+}
+const CONFIG_ERROR_FAILURE_CODES = new Set([
+    'permanent.config'
+]);
+const TRANSIENT_PROVIDER_FAILURE_CODES = new Set([
+    'transient.provider',
+    'transient.rate_limited',
+    'transient.crashed'
+]);
+const OUTPUT_VALIDATION_FAILURE_CODES = new Set([
+    'permanent.schema'
+]);
+const CATEGORY_LABEL = {
+    'config-error': 'Configuration error',
+    'transient-provider-error': 'Provider hiccup',
+    'cancelled-mid-flight': 'Stopped mid-run',
+    'output-validation-error': 'Invalid AI output',
+    'unknown-error': 'Unknown error'
+};
+const CATEGORY_EDITOR_CODE = {
+    'config-error': 'bulk.permanent.config',
+    'transient-provider-error': 'bulk.transient.provider',
+    'cancelled-mid-flight': 'marker.cancelled-mid-flight',
+    'output-validation-error': 'bulk.permanent.schema',
+    'unknown-error': 'bulk.unknown'
+};
+// Hints inside the raw error message that override what `failureCode`
+// claims. The persisted `failureCode` is best-effort from
+// `classifyError`; when the underlying message clearly says something
+// else, trust the message.
+const MESSAGE_HINTS = [
+    // Output validation — Vercel AI SDK throws this when structured output
+    // doesn't match the schema.
+    {
+        category: 'output-validation-error',
+        pattern: /noobjectgeneratederror|invalid json|schema rejected/i
+    },
+    // Auth / config — 401 / 403, missing key, missing model
+    {
+        category: 'config-error',
+        pattern: /\b401\b|\b403\b|unauthorized|forbidden|api[_-]?key|no model (configured|registered)|no provider/i
+    },
+    // Transient provider — 5xx, timeout, network, rate limit, undefined cost
+    {
+        category: 'transient-provider-error',
+        pattern: /\b5\d\d\b|\b429\b|timeout|timed out|fetch failed|econnreset|enotfound|network|rate[_-]?limit|provider returned undefined|cost instrumentation broken/i
+    }
+];
+function rawErrorMessage(input) {
+    if (input.failureMessage) return input.failureMessage;
+    if (input.err instanceof Error) return input.err.message;
+    if (typeof input.err === 'string') return input.err;
+    return '';
+}
+/**
+ * Coarse-grained failure categorizer used by `bulk_translate_units` UI
+ * surfaces (BatchRow expanded row, BucketRow locale detail, Failure
+ * drawer chip). Pure function over the persisted row + parent batch
+ * status. Server-side callers (worker) can also pass the raw thrown
+ * error before persistence.
+ *
+ * Decision order:
+ *  1. Admin markers (failureMessage = 'cancelled_by_admin' /
+ *     'force-reset by admin') short-circuit to the existing marker
+ *     codes — those aren't real failures.
+ *  2. If the parent batch is `cancelled` or `cancelling` AND the unit
+ *     has a real failure (failureCode present, not just the admin
+ *     marker), classify as `cancelled-mid-flight`. The user's mental
+ *     model is "I cancelled, so this stopped" — not "my config is
+ *     broken."
+ *  3. Message-hint patterns override the persisted `failureCode` when
+ *     they clearly point at a different bucket (defends against
+ *     `classifyError` drift in legacy data — e.g. pre-v1.2.6 the
+ *     COST_UNDEFINED case persisted as `permanent.config`).
+ *  4. Map `failureCode` to a category via the static tables.
+ *  5. Fallback: `unknown-error`.
+ */ export function categorizeFailure(input) {
+    const failureMessage = input.failureMessage ?? null;
+    const failureCode = input.failureCode ?? null;
+    const batchStatus = input.batchStatus ?? null;
+    const message = rawErrorMessage(input);
+    // 1. Admin markers — the unit is not a real failure.
+    if (failureMessage === 'cancelled_by_admin') {
+        return {
+            category: 'cancelled-mid-flight',
+            label: 'Cancelled',
+            editorCode: 'marker.cancelled-by-admin',
+            userMessage: editorMessageFor('marker.cancelled-by-admin').title
+        };
+    }
+    if (failureMessage === 'force-reset by admin') {
+        return {
+            category: 'cancelled-mid-flight',
+            label: 'Reset',
+            editorCode: 'marker.force-reset-by-admin',
+            userMessage: editorMessageFor('marker.force-reset-by-admin').title
+        };
+    }
+    // 2. Cancelled-mid-flight: parent batch was cancelled/cancelling AND
+    //    the unit has a real (non-marker) failure. The cancel context
+    //    overrides whatever the categorizer would otherwise pick — the
+    //    editor just clicked Cancel and shouldn't be told "config broken".
+    const cancelInProgress = batchStatus === 'cancelled' || batchStatus === 'cancelling';
+    if (cancelInProgress && (failureCode || failureMessage)) {
+        return {
+            category: 'cancelled-mid-flight',
+            label: CATEGORY_LABEL['cancelled-mid-flight'],
+            editorCode: CATEGORY_EDITOR_CODE['cancelled-mid-flight'],
+            userMessage: editorMessageFor(CATEGORY_EDITOR_CODE['cancelled-mid-flight']).title,
+            // Engineers can still see the original error in the disclosure.
+            details: message || undefined
+        };
+    }
+    // 3. Message-hint override — when the raw text clearly says one
+    //    thing but `failureCode` says another, the message wins.
+    for (const hint of MESSAGE_HINTS){
+        if (message && hint.pattern.test(message)) {
+            const editorCode = CATEGORY_EDITOR_CODE[hint.category];
+            return {
+                category: hint.category,
+                label: CATEGORY_LABEL[hint.category],
+                editorCode,
+                userMessage: editorMessageFor(editorCode).title,
+                details: message
+            };
+        }
+    }
+    // 4. failureCode → category.
+    if (failureCode) {
+        if (CONFIG_ERROR_FAILURE_CODES.has(failureCode)) {
+            return {
+                category: 'config-error',
+                label: CATEGORY_LABEL['config-error'],
+                editorCode: 'bulk.permanent.config',
+                userMessage: editorMessageFor('bulk.permanent.config').title,
+                details: message || undefined
+            };
+        }
+        if (TRANSIENT_PROVIDER_FAILURE_CODES.has(failureCode)) {
+            const editorCode = editorCodeFromFailureCode(failureCode);
+            return {
+                category: 'transient-provider-error',
+                label: CATEGORY_LABEL['transient-provider-error'],
+                editorCode,
+                userMessage: editorMessageFor(editorCode).title,
+                details: message || undefined
+            };
+        }
+        if (OUTPUT_VALIDATION_FAILURE_CODES.has(failureCode)) {
+            return {
+                category: 'output-validation-error',
+                label: CATEGORY_LABEL['output-validation-error'],
+                editorCode: 'bulk.permanent.schema',
+                userMessage: editorMessageFor('bulk.permanent.schema').title,
+                details: message || undefined
+            };
+        }
+        // Recognised but uncategorised codes (e.g. `permanent.too_large`,
+        // `permanent.deleted`) fall through to their editor code without
+        // being squashed into `unknown` — the catalogue already covers
+        // their copy.
+        if (failureCode === 'permanent.too_large' || failureCode === 'permanent.deleted') {
+            const editorCode = editorCodeFromFailureCode(failureCode);
+            return {
+                // These two are config-adjacent permanent failures; mapping
+                // them to `config-error` keeps the UI tone consistent (red,
+                // explanation block, disabled retry) without inventing two
+                // more category buckets for what's still "won't retry past".
+                category: 'config-error',
+                label: editorMessageFor(editorCode).title,
+                editorCode,
+                userMessage: editorMessageFor(editorCode).title,
+                details: message || undefined
+            };
+        }
+    }
+    // 5. Fallback.
+    return {
+        category: 'unknown-error',
+        label: CATEGORY_LABEL['unknown-error'],
+        editorCode: 'bulk.unknown',
+        userMessage: editorMessageFor('bulk.unknown').title,
+        details: message || undefined
+    };
+}

package/dist/lib/events.d.ts

@@ -0,0 +1,39 @@
+import type { AITranslatePluginConfig, TranslationAlert, TranslationEvent } from '../types.js';
+/**
+ * Module-scoped payload reference for alert persistence. Set via
+ * `setAlertsContext` from the plugin's `onInit` (post-config-build,
+ * when `payload` is live). When null, `emitAlert` skips DB persistence
+ * but still fires the consumer's `onAlert` callback.
+ *
+ * `payload` carries an optional `logger` (pino) so we can emit
+ * structured "alerts about alerts failing" — without it, persistence
+ * failures swallow silently (Grafana blindness).
+ */
+declare let alertsContext: {
+    payload: {
+        create: (args: unknown) => Promise<unknown>;
+        logger?: {
+            debug?: (...args: unknown[]) => void;
+            info?: (...args: unknown[]) => void;
+            warn?: (...args: unknown[]) => void;
+            error?: (...args: unknown[]) => void;
+        };
+    };
+    collectionSlug: string;
+} | null;
+export declare function setAlertsContext(ctx: typeof alertsContext): void;
+export declare function emitEvent(config: AITranslatePluginConfig, event: TranslationEvent): void;
+/**
+ * Best-effort alert persistence + consumer callback. Two outputs:
+ *
+ *   1. Persists a row to `translation-alerts` collection when the
+ *      plugin's alertsContext is set (auto-registered when
+ *      `usageTracking.enabled`). Lets the Hub surface alerts in-app.
+ *   2. Calls the consumer's `onAlert` callback if set (back-compat —
+ *      pre-1.1.15 consumers wired this to Slack/email).
+ *
+ * Neither path can break the main translation flow — both are wrapped
+ * in best-effort try/catch with no propagation.
+ */
+export declare function emitAlert(config: AITranslatePluginConfig, alert: TranslationAlert): void;
+export {};