@prenta/core 5.5.0 → 5.7.0

package/dist/seo/autopilot.js

@@ -0,0 +1,1060 @@
+import { updateDocumentSeoFields } from '../actions.js';
+import { getAIConfig } from '../ai/config-store.js';
+import { getActiveBrandVoice } from '../ai/brand-voice.js';
+import { ensureBrandVoiceDocument } from '../ai/brand-voice-document.js';
+import { parseStructuredProfile } from '../ai/brand-voice-structured.js';
+import { getFeatureGovernance } from '../ai/governance.js';
+import { ADMIN_ROLES } from '../api/route-helpers.js';
+import { getPrentaConfig } from '../config/runtime.js';
+import { assertPlanFeature } from '../plan/features.js';
+import { acceptRedirectSuggestion, } from '../redirects/suggestion-accept.js';
+import { logEvent } from '../security/audit.js';
+import { AUTOPILOT_METADATA_TYPES, isAutopilotIssueType, } from './autopilot-policy.js';
+import { buildDuplicateIndex, evaluateAutopilotGate, featureKeyFor, } from './autopilot-gate.js';
+import { countAutoAppliesToday, loadCooldownKeys, recordAutoApply, } from './autopilot-ledger.js';
+import { runOutcomeWatch } from './autopilot-outcome.js';
+import { applySeoOverrides, getSeoOverrides, patchAutopilotPolicy, patchSeoModuleSettings, resolveSeoModuleSettings, } from './config-store.js';
+import { deepEqualUnordered } from './deep-equal.js';
+import { applyIssueFix, loadIssueFixContext } from './issue-fix-apply.js';
+import { buildFixFingerprint, suggestDeterministicFix } from './issue-fix.js';
+import { pendingFixFromMetadata, stickyFingerprintsFromMetadata } from './issue-fix-ai.js';
+import { generateSeoProposals } from './proposals-generate.js';
+import { ISSUE_FIX_FEATURE_KEY, REDIRECT_FEATURE_KEY, listSeoProposals, liveFingerprintFor, loadOpenFixableIssuesWithDocs, } from './proposals.js';
+import { resolveRenderedMetaTitle } from './title-templates.js';
+/** Whole-tick wall clock, inside the 30 s function ceiling. */
+export const AUTOPILOT_BUDGET_MS = 20_000;
+/**
+ * Grace added to the run budget before a held run lease is considered abandoned
+ * (a tick that died without reaching its `finally`). Below this age a second
+ * tick halts `already_running`; at or above it the lease is taken over.
+ */
+export const AUTOPILOT_LEASE_STALE_MARGIN_MS = 10_000;
+/** Cap on the AI generate phase. */
+export const AUTOPILOT_GENERATE_BUDGET_MS = 10_000;
+/** Wall clock that must remain for the apply phase after generate. */
+export const AUTOPILOT_APPLY_RESERVE_MS = 5_000;
+/**
+ * Budget for the outcome watch, passed to `runOutcomeWatch` as its `deadline`:
+ * it stops judging rows once reached (the rest stay `pending` for the next
+ * tick). The in-flight row may still overrun slightly — that is logged and
+ * shrinks the generate window; the apply reserve holds.
+ */
+export const AUTOPILOT_OUTCOME_BUDGET_MS = 3_000;
+/** Max issue contexts loaded per tick while scanning for deterministic-tier fixes. */
+export const AUTOPILOT_DETERMINISTIC_SCAN_MAX = 50;
+/**
+ * The deterministic scan stops loading issue contexts this long before the
+ * run deadline so the gate context build and at least one apply still fit.
+ */
+export const AUTOPILOT_SCAN_DEADLINE_MARGIN_MS = 1_000;
+/** Look-back for the `Version` row an apply produced (best effort). */
+const VERSION_LOOKBACK_MS = 60_000;
+const PUBLISHED_INDEX_MAX = 5_000;
+const REDIRECT_INDEX_MAX = 10_000;
+/**
+ * Patch keys `updateDocumentSeoFields` is known to transform on write
+ * (`syncSchemaTypeFields` mirrors `structuredDataType` ↔ `schemaType`;
+ * `applyStructuredDataFieldsToData` stamps them). The written-equals-gated
+ * check skips these; every other key must land byte-for-byte. Deliberately
+ * NOT exempt: `focusKeyphrase` — `normalizeSeoFieldAliases` folds it into
+ * `focusKeyword`, so a patch carrying it fails closed (`gate_mismatch`) rather
+ * than skipping the check; a fix type that needs the alias must map it to
+ * `focusKeyword` in both the `before` snapshot and the comparison.
+ */
+const GATE_MISMATCH_EXEMPT_KEYS = new Set([
+    'structuredData',
+    'structuredDataType',
+    'schemaType',
+]);
+function asRecord(v) {
+    return v && typeof v === 'object' && !Array.isArray(v) ? v : {};
+}
+function sameValue(a, b) {
+    if (a === b)
+        return true;
+    if (a == null && b == null)
+        return true;
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+function bump(map, key) {
+    map[key] = (map[key] ?? 0) + 1;
+}
+function bumpGate(gated, reason) {
+    gated[reason] = (gated[reason] ?? 0) + 1;
+}
+/** Ledger `path`: pathname only, no origin / query / hash, no trailing slash, root kept. */
+export function normalizeAutopilotPath(url) {
+    if (!url)
+        return null;
+    let pathname;
+    try {
+        pathname = new URL(url, 'https://placeholder.invalid').pathname;
+    }
+    catch {
+        return null;
+    }
+    let path = pathname.replace(/\/+$/, '') || '/';
+    // `new URL` percent-encodes; the GSC sync (`normalizeGscPageUrl`) stores the
+    // decoded form, and the outcome watch joins on it. Keep the encoded form only
+    // when decoding fails (malformed escape).
+    try {
+        path = decodeURIComponent(path);
+    }
+    catch {
+        /* keep encoded */
+    }
+    return path;
+}
+const defaultRestoreFields = (db, collection, entityId, fields, actor) => {
+    const ctx = { userId: actor.userId, role: actor.role, db };
+    return updateDocumentSeoFields(collection, entityId, fields, ctx);
+};
+/**
+ * Deterministic-tier candidates: open fixable issues of the opted-in metadata
+ * types with no LIVE cache whose deterministic suggestion is auto-fixable.
+ * These never appear in the inbox (the generator skips them), so the run
+ * discovers them directly. A stale cache counts as none — the inbox row it
+ * backs is gated `stale`, so without this the issue would be fixed by neither
+ * tier. Bounded by AUTOPILOT_DETERMINISTIC_SCAN_MAX loads and by the run
+ * deadline (minus AUTOPILOT_SCAN_DEADLINE_MARGIN_MS).
+ */
+async function defaultDeterministicCandidates(db, types, opts) {
+    const { issues, docsById } = await loadOpenFixableIssuesWithDocs(db);
+    const out = [];
+    const scanDeadline = opts.deadline - AUTOPILOT_SCAN_DEADLINE_MARGIN_MS;
+    let scanned = 0;
+    for (const issue of issues) {
+        if (scanned >= AUTOPILOT_DETERMINISTIC_SCAN_MAX)
+            break;
+        if (opts.now() >= scanDeadline)
+            break;
+        if (issue.fixable !== true || !types.has(String(issue.type)))
+            continue;
+        if (typeof issue.entityId !== 'string' || !docsById.has(issue.entityId))
+            continue;
+        const cache = pendingFixFromMetadata(issue.metadata);
+        if (cache && liveFingerprintFor(issue, cache, docsById) === cache.fingerprint)
+            continue;
+        scanned++;
+        const loaded = await loadIssueFixContext(db, issue, { overrides: opts.overrides });
+        if (!loaded.ok)
+            continue;
+        const suggestion = suggestDeterministicFix({
+            type: String(issue.type),
+            title: String(issue.title ?? issue.type),
+            recommendation: typeof issue.recommendation === 'string' ? issue.recommendation : null,
+            entityType: typeof issue.entityType === 'string' ? issue.entityType : null,
+            entityId: issue.entityId,
+        }, {
+            entity: loaded.ctx.entity,
+            siteSeo: loaded.ctx.siteSeo,
+            updatedAt: loaded.ctx.updatedAt,
+            metadata: asRecord(issue.metadata),
+        });
+        if (!suggestion.autoFixable || Object.keys(suggestion.patch).length === 0)
+            continue;
+        out.push({
+            id: `issue:${String(issue.id)}`,
+            kind: 'issue-fix',
+            title: String(issue.title ?? issue.type),
+            entity: {
+                type: typeof issue.entityType === 'string' ? issue.entityType : null,
+                id: issue.entityId,
+                title: docsById.get(issue.entityId)?.title ?? null,
+                url: typeof issue.url === 'string' ? issue.url : null,
+            },
+            changes: suggestion.changes,
+            justification: suggestion.justification,
+            source: 'deterministic',
+            confidence: null,
+            brandAlignment: null,
+            generatedAt: null,
+            fingerprint: buildFixFingerprint(issue.entityId, String(issue.type), loaded.ctx.updatedAt),
+            stale: false,
+            issueType: String(issue.type),
+            severity: issue.severity === 'critical' || issue.severity === 'warning' || issue.severity === 'info'
+                ? issue.severity
+                : null,
+            issueId: String(issue.id),
+            suggestionId: null,
+            patch: suggestion.patch,
+            dismissedFingerprint: stickyFingerprintsFromMetadata(issue.metadata).dismissed,
+        });
+    }
+    return out;
+}
+function toCandidate(p) {
+    const typeKey = p.kind === 'redirect' ? 'redirect' : p.issueType;
+    if (!isAutopilotIssueType(typeKey))
+        return null;
+    return {
+        ...p,
+        featureKey: featureKeyFor(p.kind),
+        issueTypeKey: typeKey,
+        patch: 'patch' in p ? p.patch : null,
+        dismissedFingerprint: 'dismissedFingerprint' in p ? p.dismissedFingerprint : undefined,
+    };
+}
+/**
+ * Inbox proposals do not carry the issue's sticky dismissal marker (the
+ * proposal shape is the public inbox contract), so it is read once here for
+ * every issue-fix candidate that does not already have it. A lookup failure
+ * propagates: an unverifiable "not dismissed" is not a green light.
+ */
+async function attachDismissalMarkers(db, candidates) {
+    const pending = candidates.filter((c) => c.kind === 'issue-fix' && c.issueId && c.dismissedFingerprint === undefined);
+    if (pending.length === 0)
+        return;
+    const ids = [...new Set(pending.map((c) => c.issueId))];
+    const rows = await db.seoIssue.findMany({
+        where: { id: { in: ids } },
+        select: { id: true, metadata: true },
+    });
+    const byId = new Map(rows.map((r) => [String(r.id), r.metadata]));
+    for (const c of pending) {
+        c.dismissedFingerprint = byId.has(c.issueId)
+            ? stickyFingerprintsFromMetadata(byId.get(c.issueId)).dismissed
+            : null;
+    }
+}
+/** Deterministic first, then AI fixes by brand alignment (nulls last), then redirects by confidence. */
+function orderCandidates(list) {
+    const tier = (c) => c.source === 'deterministic' ? 0 : c.kind === 'issue-fix' ? 1 : 2;
+    return [...list].sort((a, b) => {
+        const t = tier(a) - tier(b);
+        if (t !== 0)
+            return t;
+        if (a.kind === 'issue-fix' && b.kind === 'issue-fix') {
+            return (b.brandAlignment ?? -1) - (a.brandAlignment ?? -1);
+        }
+        return (b.confidence ?? 0) - (a.confidence ?? 0);
+    });
+}
+function dedupeById(list) {
+    const seen = new Set();
+    return list.filter((c) => {
+        if (seen.has(c.id))
+            return false;
+        seen.add(c.id);
+        return true;
+    });
+}
+async function buildGateContext(db, policy, candidates, now, overrides) {
+    const governance = {};
+    for (const key of [ISSUE_FIX_FEATURE_KEY, REDIRECT_FEATURE_KEY]) {
+        governance[key] = await getFeatureGovernance(db, key);
+    }
+    const featureCandidates = {};
+    for (const c of candidates) {
+        if (policy.types[c.issueTypeKey] === true)
+            bump(featureCandidates, c.featureKey);
+    }
+    const [appliedToday, cooldown] = await Promise.all([
+        countAutoAppliesToday(db, now),
+        loadCooldownKeys(db, now),
+    ]);
+    let brandProfile = null;
+    try {
+        const active = getActiveBrandVoice(await getAIConfig(db));
+        if (active)
+            brandProfile = parseStructuredProfile(ensureBrandVoiceDocument(active));
+    }
+    catch (err) {
+        console.warn('[seo/autopilot] brand profile unavailable; brand gate skipped', err);
+    }
+    // The gate compares `changes[].after` — the RENDERED title (page title through the site
+    // template) — so every published document is indexed the same way, falling back to the
+    // document title when no meta title is stored (those pages collide too).
+    const siteSeo = applySeoOverrides(getPrentaConfig(), overrides)?.seo;
+    const published = await db.document.findMany({
+        where: { status: 'PUBLISHED', deletedAt: null },
+        select: { id: true, title: true, data: true },
+        take: PUBLISHED_INDEX_MAX,
+    });
+    const duplicates = buildDuplicateIndex(published.map((d) => {
+        const data = asRecord(d.data);
+        return {
+            entityId: d.id,
+            metaTitle: resolveRenderedMetaTitle({
+                metaTitlePage: typeof data.metaTitle === 'string' ? data.metaTitle : null,
+                documentTitle: d.title,
+                site: siteSeo,
+            }),
+            metaDescription: data.metaDescription,
+        };
+    }));
+    const redirects = await db.redirect.findMany({
+        select: { source: true },
+        take: REDIRECT_INDEX_MAX,
+    });
+    return {
+        policy,
+        governance,
+        featureCandidates,
+        featureApplied: {},
+        appliedThisRun: 0,
+        appliedToday,
+        cooldownIssueIds: cooldown.issueIds,
+        cooldownEntityKeys: cooldown.entityKeys,
+        brandProfile,
+        duplicates,
+        existingRedirectSources: new Set(redirects.map((r) => r.source)),
+        planDenied: assertPlanFeature('seo.inlineApply') !== null,
+    };
+}
+/**
+ * The data-layer patch an issue-fix candidate will write. Deterministic
+ * candidates carry it; inbox (AI) candidates keep it in the issue's cache,
+ * which must still be the proposal the gate scored: same fingerprint AND the
+ * same `changes` / `brandAlignment`. The fingerprint alone is not enough —
+ * `suggest-fix` regenerates the cache under an unchanged fingerprint, so a
+ * regeneration between listing and apply would otherwise write text the
+ * brand / banned-term / duplicate / validator gates never saw. Any mismatch
+ * is `stale` (nothing written); the proposal is re-listed on the next tick.
+ */
+async function resolvePatch(db, c) {
+    if (c.patch)
+        return c.patch;
+    const issue = await db.seoIssue.findUnique({ where: { id: c.issueId } });
+    const cache = pendingFixFromMetadata(issue?.metadata);
+    if (!cache || (c.fingerprint && cache.fingerprint !== c.fingerprint))
+        return null;
+    if (!deepEqualUnordered(cache.changes, c.changes))
+        return null;
+    if (cache.brandAlignment !== c.brandAlignment)
+        return null;
+    return cache.patch;
+}
+async function readDocument(db, id) {
+    const doc = await db.document.findFirst({
+        where: { id, deletedAt: null },
+        select: { id: true, collection: true, data: true },
+    });
+    return doc ? { id: doc.id, collection: doc.collection, data: asRecord(doc.data) } : null;
+}
+async function findApplyVersionId(db, documentId, actorId, nowMs) {
+    try {
+        const version = await db.version.findFirst({
+            where: {
+                documentId,
+                changedById: actorId,
+                createdAt: { gte: new Date(nowMs - VERSION_LOOKBACK_MS) },
+            },
+            orderBy: { createdAt: 'desc' },
+            select: { id: true },
+        });
+        return version?.id ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+async function audit(event, userId, details) {
+    try {
+        await logEvent({ event, userId, details });
+    }
+    catch {
+        /* audit-log failures never block */
+    }
+}
+function countApplied(state, c) {
+    state.ctx.appliedThisRun++;
+    state.ctx.appliedToday++;
+    bump(state.ctx.featureApplied, c.featureKey);
+}
+/**
+ * Hard `maxPerDay`: the gate's `appliedToday` was read once when the context was
+ * built, so a tick overlapping this one (the run lease closes most of that
+ * window, not all of it) could push the day past the cap. Re-count the ledger
+ * immediately before every write; when the day is already full, gate the
+ * candidate `cap_per_day` and tell the loop nothing later can pass. Returns
+ * whether the write may proceed. A count that throws propagates — an
+ * unverifiable cap is not a green light.
+ */
+async function dayCapAllowsWrite(state) {
+    const fresh = await countAutoAppliesToday(state.db, state.startedAt);
+    // Adopt the fresher figure so the gate's own cap check stays honest too.
+    if (fresh > state.ctx.appliedToday)
+        state.ctx.appliedToday = fresh;
+    if (fresh < state.policy.maxPerDay)
+        return true;
+    bumpGate(state.summary.gated, 'cap_per_day');
+    state.dayCapReached = true;
+    return false;
+}
+/**
+ * Ledger a write that has already landed. The ledger is the only audit and
+ * undo path for an unattended write, so a failed insert is not tolerated: the
+ * write is undone (best effort), the failure is audited as
+ * `seo_autopilot_ledger_failed` so it is attributable to the issue / redirect,
+ * and the run halts with `ledger_write_failed` so nothing else is written
+ * under a broken ledger. Returns whether the row was recorded.
+ */
+async function recordOrHalt(state, input, undo) {
+    try {
+        await recordAutoApply(state.db, input);
+        return true;
+    }
+    catch (err) {
+        const ref = { kind: input.kind, issueId: input.issueId, redirectId: input.redirectId };
+        console.warn('[seo/autopilot] ledger write failed after apply; undoing and halting', ref, err);
+        await audit('seo_autopilot_ledger_failed', state.actor.userId, ref);
+        if (undo) {
+            try {
+                await undo();
+            }
+            catch (undoErr) {
+                console.warn('[seo/autopilot] undo after ledger failure failed', undoErr);
+            }
+        }
+        state.summary.halted = true;
+        state.summary.haltedReason = 'ledger_write_failed';
+        return false;
+    }
+}
+async function applyRedirect(state, c, gate) {
+    const { db, actor, summary } = state;
+    if (!(await dayCapAllowsWrite(state)))
+        return;
+    let res;
+    try {
+        res = await state.deps.acceptRedirect(db, {
+            suggestionId: c.suggestionId,
+            actor: { userId: actor.userId },
+        });
+    }
+    catch (err) {
+        // Includes a unique violation on `Redirect.source` and probe/network errors: one bad
+        // suggestion must not take the phase down.
+        console.warn('[seo/autopilot] acceptRedirectSuggestion threw', { suggestionId: c.suggestionId }, err);
+        bump(summary.applyOutcomes, 'error');
+        return;
+    }
+    switch (res.status) {
+        case 'accepted': {
+            const recorded = await recordOrHalt(state, {
+                kind: 'redirect',
+                issueId: null,
+                issueType: 'redirect',
+                entityId: null,
+                collection: null,
+                path: null,
+                redirectId: res.redirectId,
+                before: null,
+                after: {
+                    source: c.entity.url,
+                    destination: c.changes[0]?.after ?? null,
+                    suggestionId: c.suggestionId,
+                },
+                gate,
+                status: 'applied',
+                appliedById: actor.userId,
+            }, async () => {
+                await db.redirect.delete({ where: { id: res.redirectId } });
+                await db.redirectSuggestion.update({
+                    where: { id: c.suggestionId },
+                    data: { status: 'open' },
+                });
+            });
+            if (!recorded)
+                return;
+            // Same-run containment: a second suggestion for this source must now gate
+            // `redirect_manual_exists` instead of hitting the unique index.
+            if (c.entity.url)
+                state.ctx.existingRedirectSources.add(c.entity.url);
+            summary.applied++;
+            countApplied(state, c);
+            return;
+        }
+        case 'not-found':
+        case 'invalid':
+        case 'still-live':
+            bump(summary.applyOutcomes, res.status);
+            return;
+        default: {
+            const exhaustive = res;
+            return exhaustive;
+        }
+    }
+}
+/**
+ * Put an issue back to `open` after its fix was undone. `applyIssueFix` marks
+ * the issue resolved as part of a successful write, so every path that restores
+ * `before` afterwards (gate mismatch, unreadable re-read, ledger failure, throw
+ * after write) must reopen it or the audit shows a resolved issue whose problem
+ * is live again. Idempotent for issues that were never resolved. Best effort —
+ * the audit may have removed the row since.
+ */
+async function reopenIssue(db, issueId, cause) {
+    try {
+        await db.seoIssue.update({
+            where: { id: issueId },
+            data: { status: 'open', resolvedAt: null, resolvedById: null },
+        });
+    }
+    catch (err) {
+        console.warn(`[seo/autopilot] issue reopen after ${cause} failed`, { issueId }, err);
+    }
+}
+/**
+ * Verify failed (or the apply threw after writing, or the landed value is not
+ * the gated one): put `before` back, reopen the issue, and ledger the attempt as
+ * `verify_failed`. A restore that throws is logged and recorded with
+ * `revertReason: null` — the row says what was written, the revert did not
+ * happen — and never aborts the run. The restore has already run, so a failed
+ * ledger insert here has nothing to undo; it still halts the run (`recordOrHalt`).
+ */
+async function restoreAndRecord(state, c, doc, base, before) {
+    const { db, actor, summary } = state;
+    let restored = false;
+    try {
+        await state.deps.restoreFields(db, doc.collection, doc.id, before, actor);
+        restored = true;
+        if (c.issueId)
+            await reopenIssue(db, c.issueId, 'restore');
+    }
+    catch (err) {
+        console.warn('[seo/autopilot] restore after verify failure failed', { issueId: c.issueId, fields: Object.keys(before) }, err);
+    }
+    await recordOrHalt(state, {
+        ...base,
+        status: 'verify_failed',
+        revertReason: restored ? 'verify_failed' : null,
+        revertedAt: restored ? new Date(state.now()) : null,
+        revertedById: restored ? actor.userId : null,
+    }, null);
+    summary.verifyFailed++;
+    countApplied(state, c);
+    state.verifyFailures++;
+    if (!summary.halted && state.verifyFailures >= state.policy.verifyFailuresPerRun) {
+        summary.halted = true;
+        summary.haltedReason = 'verify_failures';
+    }
+}
+async function applyIssueFixCandidate(state, c, gate) {
+    const { db, actor, summary } = state;
+    if (!c.entity.id) {
+        bump(summary.applyOutcomes, 'not-found');
+        return;
+    }
+    const doc = await readDocument(db, c.entity.id);
+    if (!doc) {
+        bump(summary.applyOutcomes, 'not-found');
+        return;
+    }
+    const patch = await resolvePatch(db, c);
+    if (!patch) {
+        bump(summary.applyOutcomes, 'stale');
+        return;
+    }
+    const keys = Object.keys(patch);
+    if (keys.length === 0) {
+        bump(summary.applyOutcomes, 'not-fixable');
+        return;
+    }
+    // Snapshot BEFORE the write — applyIssueFix does not return the diff on verify-failed.
+    const before = {};
+    for (const key of keys)
+        before[key] = doc.data[key] ?? null;
+    const afterFromPatch = {};
+    for (const key of keys)
+        afterFromPatch[key] = patch[key] ?? null;
+    const base = {
+        kind: 'issue-fix',
+        issueId: c.issueId,
+        issueType: c.issueTypeKey,
+        entityId: doc.id,
+        collection: doc.collection,
+        path: normalizeAutopilotPath(c.entity.url),
+        redirectId: null,
+        before,
+        after: afterFromPatch,
+        gate,
+        appliedById: actor.userId,
+    };
+    /** Live values for the patch keys after the apply; `null` when unreadable. */
+    const liveAfter = async () => {
+        const fresh = await readDocument(db, doc.id).catch(() => null);
+        if (!fresh)
+            return null;
+        const out = {};
+        for (const key of keys)
+            out[key] = fresh.data[key] ?? null;
+        return out;
+    };
+    if (!(await dayCapAllowsWrite(state)))
+        return;
+    let res;
+    try {
+        res = await state.deps.applyFix(db, {
+            issueId: c.issueId,
+            fingerprint: c.fingerprint ?? undefined,
+            actor,
+            // The gate evaluated the cached text for AI-tier candidates; make applyIssueFix write
+            // that rather than a recomputed deterministic value. Deterministic-tier candidates
+            // were gated on their own recompute, so they keep the default order.
+            preferCached: c.source === 'ai',
+        });
+    }
+    catch (err) {
+        console.warn('[seo/autopilot] applyIssueFix threw', { issueId: c.issueId }, err);
+        // Unknown failure: find out whether the document was written before treating it as a no-op.
+        const live = await liveAfter();
+        const wrote = live !== null && keys.some((key) => !sameValue(live[key], before[key]));
+        if (wrote) {
+            await restoreAndRecord(state, c, doc, { ...base, after: live }, before);
+        }
+        else {
+            bump(summary.applyOutcomes, 'error');
+        }
+        return;
+    }
+    switch (res.status) {
+        case 'applied': {
+            const live = await liveAfter();
+            // Written value must equal gated value. `applyIssueFix` verified against ITS suggestion;
+            // this verifies against the patch the gate saw. Any drift is a verify failure — and so
+            // is not being able to read the document back: an unverifiable write is not kept.
+            if (!live) {
+                console.warn('[seo/autopilot] document unreadable after apply; restoring', {
+                    issueId: c.issueId,
+                    entityId: doc.id,
+                });
+                bump(summary.applyOutcomes, 'after_unreadable');
+                await restoreAndRecord(state, c, doc, base, before);
+                return;
+            }
+            const drifted = keys.filter((key) => !GATE_MISMATCH_EXEMPT_KEYS.has(key) && !sameValue(live[key], afterFromPatch[key]));
+            if (drifted.length > 0) {
+                console.warn('[seo/autopilot] written value differs from gated patch; restoring', {
+                    issueId: c.issueId,
+                    fields: drifted,
+                });
+                bump(summary.applyOutcomes, 'gate_mismatch');
+                await restoreAndRecord(state, c, doc, { ...base, after: live }, before);
+                return;
+            }
+            const recorded = await recordOrHalt(state, {
+                ...base,
+                after: live,
+                status: 'applied',
+                versionId: await findApplyVersionId(db, doc.id, actor.userId, state.now()),
+            }, async () => {
+                await state.deps.restoreFields(db, doc.collection, doc.id, before, actor);
+                await reopenIssue(db, c.issueId, 'ledger failure');
+            });
+            if (!recorded)
+                return;
+            summary.applied++;
+            countApplied(state, c);
+            return;
+        }
+        case 'verify-failed':
+            await restoreAndRecord(state, c, doc, base, before);
+            return;
+        case 'stale':
+        case 'plan-required':
+        case 'not-found':
+        case 'not-allowed':
+        case 'not-fixable':
+            bump(summary.applyOutcomes, res.status);
+            return;
+        default: {
+            const exhaustive = res;
+            return exhaustive;
+        }
+    }
+}
+async function applyCandidate(state, c) {
+    const verdict = evaluateAutopilotGate(c, state.ctx);
+    if (!verdict.pass) {
+        bumpGate(state.summary.gated, verdict.reason);
+        return;
+    }
+    const gate = {
+        source: c.source,
+        brandAlignment: c.brandAlignment,
+        confidence: c.confidence,
+        checks: verdict.checks,
+    };
+    switch (c.kind) {
+        case 'redirect':
+            if (!c.suggestionId) {
+                bump(state.summary.applyOutcomes, 'not-found');
+                return;
+            }
+            await applyRedirect(state, { ...c, suggestionId: c.suggestionId }, gate);
+            return;
+        case 'issue-fix':
+            if (!c.issueId) {
+                bump(state.summary.applyOutcomes, 'not-found');
+                return;
+            }
+            await applyIssueFixCandidate(state, { ...c, issueId: c.issueId }, gate);
+            return;
+        default: {
+            const exhaustive = c.kind;
+            return exhaustive;
+        }
+    }
+}
+function isActiveAdmin(owner) {
+    return owner !== null && owner.isActive === true && ADMIN_ROLES.has(owner.role);
+}
+/**
+ * The resolved owner came from the legacy 404 lever's `updatedBy` (or there was
+ * none) rather than from a stored `autopilot.enabledById`. Such an owner is
+ * advisory: crons rewrite `updatedBy` with `'system'`, and the admin who flipped
+ * the lever may have left since. Only true while the lever is on and nothing
+ * explicit has been stored — one PUT/resume stores a real owner and ends it.
+ */
+function isLegacyOwnerAdvisory(overrides, moduleSettings) {
+    const stored = asRecord(asRecord(overrides?.module).autopilot);
+    return typeof stored.enabledById !== 'string' && moduleSettings.redirectRecoveryAutoApply === true;
+}
+/**
+ * Pick the most recently active (then newest) active admin, persist it as the
+ * explicit `enabledById` (sparse write — nothing else materialises), and audit
+ * `seo_autopilot_owner_migrated`. Returns `null` — leaving the caller on the
+ * `owner_unavailable` path — when no admin exists or the write fails; an owner
+ * that could not be recorded must not run the tick.
+ */
+async function migrateLegacyOwner(db, previous) {
+    let admin;
+    try {
+        admin = await db.user.findFirst({
+            where: { isActive: true, role: { in: [...ADMIN_ROLES] } },
+            orderBy: [{ lastActiveAt: { sort: 'desc', nulls: 'last' } }, { createdAt: 'desc' }],
+            select: { id: true, role: true, isActive: true },
+        });
+    }
+    catch (err) {
+        console.warn('[seo/autopilot] legacy owner migration: admin lookup failed', err);
+        return null;
+    }
+    if (!isActiveAdmin(admin))
+        return null;
+    try {
+        await patchAutopilotPolicy(db, { enabledById: admin.id }, admin.id);
+    }
+    catch (err) {
+        console.warn('[seo/autopilot] legacy owner migration: failed to persist owner', err);
+        return null;
+    }
+    await audit('seo_autopilot_owner_migrated', admin.id, {
+        enabledById: admin.id,
+        previous,
+        source: 'legacy_redirect_recovery_lever',
+    });
+    return admin;
+}
+/**
+ * The user the pause is written as. The owner row (even inactive / demoted)
+ * is preferred; otherwise any active admin — the settings document's
+ * `updatedById` is a foreign key, so an unverified id would fail the write.
+ */
+async function resolvePauseWriter(db, owner) {
+    if (owner)
+        return owner.id;
+    try {
+        const admin = await db.user.findFirst({
+            where: { isActive: true, role: { in: [...ADMIN_ROLES] } },
+            select: { id: true },
+        });
+        return admin?.id ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function runSeoAutopilot(db, opts = {}) {
+    const now = opts.now ?? Date.now;
+    const startedMs = now();
+    const startedAt = new Date(startedMs);
+    const budgetMs = opts.budgetMs ?? AUTOPILOT_BUDGET_MS;
+    const deps = opts.deps ?? {};
+    const generate = deps.generate ?? generateSeoProposals;
+    const listProposals = deps.listProposals ?? listSeoProposals;
+    const deterministicCandidates = deps.deterministicCandidates ?? defaultDeterministicCandidates;
+    const outcomeWatch = deps.outcomeWatch ?? runOutcomeWatch;
+    const applyDeps = {
+        applyFix: deps.applyFix ?? applyIssueFix,
+        acceptRedirect: deps.acceptRedirect ?? acceptRedirectSuggestion,
+        restoreFields: deps.restoreFields ?? defaultRestoreFields,
+    };
+    const elapsed = () => now() - startedMs;
+    const summary = {
+        startedAt: startedAt.toISOString(),
+        durationMs: 0,
+        applied: 0,
+        verifyFailed: 0,
+        reverted: 0,
+        gated: {},
+        applyOutcomes: {},
+        generated: { generated: 0, skipped: 0, failed: 0, haltedReason: null },
+        halted: false,
+        haltedReason: null,
+    };
+    // 1. Preflight
+    const overrides = await getSeoOverrides(db);
+    const moduleSettings = resolveSeoModuleSettings(overrides);
+    const policy = moduleSettings.autopilot;
+    if (!policy.enabled) {
+        summary.halted = true;
+        summary.haltedReason = 'disabled';
+        summary.durationMs = elapsed();
+        return summary;
+    }
+    if (policy.pausedAt) {
+        summary.halted = true;
+        summary.haltedReason = 'paused';
+        summary.durationMs = elapsed();
+        return summary;
+    }
+    let owner = policy.enabledById
+        ? await db.user.findUnique({
+            where: { id: policy.enabledById },
+            select: { id: true, role: true, isActive: true },
+        })
+        : null;
+    if (!isActiveAdmin(owner) && isLegacyOwnerAdvisory(overrides, moduleSettings)) {
+        // Compatibility: the tenant enabled the old 404 lever and never stored an
+        // owner. Adopt an active admin instead of pausing on the first tick.
+        owner = (await migrateLegacyOwner(db, policy.enabledById)) ?? owner;
+    }
+    if (!isActiveAdmin(owner)) {
+        summary.halted = true;
+        summary.haltedReason = 'owner_unavailable';
+        const writer = await resolvePauseWriter(db, owner);
+        if (writer) {
+            try {
+                summary.durationMs = elapsed();
+                // Sparse policy write: only the pause keys, merged onto the stored block.
+                await patchAutopilotPolicy(db, { pausedAt: startedAt.toISOString(), pausedReason: 'owner_unavailable' }, writer);
+                await patchSeoModuleSettings(db, { autopilotLastRunAt: startedAt.toISOString(), autopilotLastRun: summary }, writer);
+            }
+            catch (err) {
+                console.warn('[seo/autopilot] failed to persist owner_unavailable pause', err);
+            }
+            await audit('seo_autopilot_paused', writer, {
+                reason: 'owner_unavailable',
+                enabledById: policy.enabledById,
+            });
+        }
+        else {
+            console.warn('[seo/autopilot] owner unavailable and no active admin to write the pause');
+        }
+        summary.durationMs = elapsed();
+        return summary;
+    }
+    const actor = { userId: owner.id, role: owner.role };
+    // Run lease. Not atomic (read-then-write on the settings document), but it
+    // closes the realistic overlap — admin "Run now" landing on the cron tick, or
+    // two admins clicking within the budget — to a window of milliseconds, and the
+    // per-write day-count check bounds whatever slips through. A lease older than
+    // budget + margin belongs to a tick that died before its `finally`; take it over.
+    if (isLeaseHeld(moduleSettings.autopilotRunStartedAt, startedMs, budgetMs)) {
+        summary.halted = true;
+        summary.haltedReason = 'already_running';
+        summary.durationMs = elapsed();
+        return summary;
+    }
+    await patchSeoModuleSettings(db, { autopilotRunStartedAt: summary.startedAt }, actor.userId);
+    try {
+        await runPhases(db, { policy, actor, summary, overrides, startedMs, startedAt, budgetMs, now }, { generate, listProposals, deterministicCandidates, outcomeWatch, applyDeps });
+    }
+    catch (err) {
+        // Nothing in the phases is expected to throw (each contains its own failures);
+        // an escape is a bug, but the lease and last-run record must still be correct.
+        // The record carries a code only: the summary is served to every authenticated
+        // role and provider / Prisma messages can name hosts and tables.
+        console.warn('[seo/autopilot] run failed', err);
+        summary.halted = true;
+        summary.haltedReason = summary.haltedReason ?? 'run_failed';
+        throw err;
+    }
+    finally {
+        // 5. Summary + release the lease in the same write. Nothing here may throw:
+        // a stuck lease would block every tick until the stale margin expires.
+        try {
+            summary.durationMs = elapsed();
+        }
+        catch {
+            /* keep the last measured duration */
+        }
+        try {
+            await patchSeoModuleSettings(db, {
+                autopilotLastRunAt: startedAt.toISOString(),
+                autopilotLastRun: summary,
+                autopilotRunStartedAt: null,
+            }, actor.userId);
+        }
+        catch (err) {
+            console.warn('[seo/autopilot] failed to persist run summary', err);
+        }
+    }
+    await audit('seo_autopilot_run', actor.userId, { ...summary });
+    return summary;
+}
+/** A lease younger than this run's budget plus the stale margin belongs to a live tick. */
+function isLeaseHeld(lease, nowMs, budgetMs) {
+    if (!lease)
+        return false;
+    const startedMs = Date.parse(lease);
+    if (!Number.isFinite(startedMs))
+        return false;
+    return nowMs - startedMs < budgetMs + AUTOPILOT_LEASE_STALE_MARGIN_MS;
+}
+/** Phases 2–4 (outcome watch, generate, apply). Runs under the lease; mutates `summary`. */
+async function runPhases(db, input, deps) {
+    const { policy, actor, summary, overrides, startedMs, startedAt, budgetMs, now } = input;
+    const { generate, listProposals, deterministicCandidates, outcomeWatch, applyDeps } = deps;
+    const elapsed = () => now() - startedMs;
+    let workingPolicy = policy;
+    // 2. Outcome watch + breakers (bounded by AUTOPILOT_OUTCOME_BUDGET_MS)
+    const watchStartedMs = now();
+    // Pauses are persisted the moment the watch decides them (sparse write that
+    // merges onto the stored map), so a revert that throws, a watch that escapes,
+    // or a killed process cannot lose a breaker. `persisted` lets the post-watch
+    // sweep below write only what the callback failed to.
+    const decidedPauses = {};
+    const persisted = new Set();
+    const onPause = async (type, reason) => {
+        decidedPauses[type] = reason;
+        await patchAutopilotPolicy(db, { pausedTypes: { [type]: reason } }, actor.userId);
+        persisted.add(type);
+    };
+    try {
+        const watch = await outcomeWatch(db, workingPolicy, {
+            now: startedAt,
+            actor,
+            clock: now,
+            deadline: watchStartedMs + AUTOPILOT_OUTCOME_BUDGET_MS,
+            onPause,
+        });
+        summary.reverted = watch.reverted;
+        if (watch.revertErrors > 0) {
+            summary.applyOutcomes.outcome_revert_error =
+                (summary.applyOutcomes.outcome_revert_error ?? 0) + watch.revertErrors;
+        }
+        Object.assign(decidedPauses, watch.pausedTypes);
+    }
+    catch (err) {
+        console.warn('[seo/autopilot] outcome watch failed', err);
+        bump(summary.applyOutcomes, 'outcome_watch_error');
+    }
+    if (Object.keys(decidedPauses).length > 0) {
+        workingPolicy = {
+            ...workingPolicy,
+            pausedTypes: { ...workingPolicy.pausedTypes, ...decidedPauses },
+        };
+        const unpersisted = Object.fromEntries(Object.entries(decidedPauses).filter(([t]) => !persisted.has(t)));
+        if (Object.keys(unpersisted).length > 0) {
+            try {
+                await patchAutopilotPolicy(db, { pausedTypes: unpersisted }, actor.userId);
+            }
+            catch (err) {
+                console.warn('[seo/autopilot] failed to persist outcome pauses', err);
+                bump(summary.applyOutcomes, 'outcome_watch_error');
+            }
+        }
+    }
+    const watchMs = now() - watchStartedMs;
+    if (watchMs > AUTOPILOT_OUTCOME_BUDGET_MS) {
+        console.warn('[seo/autopilot] outcome watch exceeded its budget', {
+            ms: watchMs,
+            budgetMs: AUTOPILOT_OUTCOME_BUDGET_MS,
+        });
+    }
+    // 3. Generate (AI) — only for opted-in, unpaused metadata types
+    const enabledMetadata = new Set(AUTOPILOT_METADATA_TYPES.filter((t) => workingPolicy.types[t] === true && !(t in workingPolicy.pausedTypes)));
+    if (enabledMetadata.size > 0) {
+        const generateBudget = Math.min(AUTOPILOT_GENERATE_BUDGET_MS, budgetMs - elapsed() - AUTOPILOT_APPLY_RESERVE_MS);
+        if (generateBudget > 0) {
+            try {
+                const g = await generate(db, { userId: actor.userId }, { concurrency: 2, budgetMs: generateBudget, onlyTypes: enabledMetadata, now });
+                summary.generated = {
+                    generated: g.generated,
+                    skipped: g.skipped,
+                    failed: g.failed,
+                    haltedReason: g.haltedReason,
+                };
+            }
+            catch (err) {
+                console.warn('[seo/autopilot] generation failed', err);
+                summary.generated.haltedReason = 'generate_failed';
+            }
+        }
+        else {
+            summary.generated.haltedReason = 'budget_exhausted';
+        }
+    }
+    // 4. Apply
+    if (elapsed() >= budgetMs) {
+        summary.halted = true;
+        summary.haltedReason = 'budget_exhausted';
+    }
+    else {
+        try {
+            const payload = await listProposals(db);
+            let deterministic = [];
+            if (enabledMetadata.size > 0) {
+                try {
+                    deterministic = await deterministicCandidates(db, enabledMetadata, {
+                        now,
+                        deadline: startedMs + budgetMs,
+                        overrides,
+                    });
+                }
+                catch (err) {
+                    console.warn('[seo/autopilot] deterministic scan failed; inbox proposals only', err);
+                }
+            }
+            const candidates = orderCandidates(dedupeById([...deterministic, ...payload.proposals]
+                .map(toCandidate)
+                .filter((c) => c !== null)));
+            await attachDismissalMarkers(db, candidates);
+            // Discovery (inbox + scan) and the gate context (published-document index, redirect
+            // index, caps) are the expensive preamble. If the scan already consumed the reserve,
+            // do not pay for the gate context; if the gate context consumed it, say so rather than
+            // entering the loop only to exit on its first check.
+            const ctx = elapsed() < budgetMs
+                ? await buildGateContext(db, workingPolicy, candidates, startedAt, overrides)
+                : null;
+            if (!ctx || elapsed() >= budgetMs) {
+                summary.halted = true;
+                summary.haltedReason = 'budget_exhausted';
+            }
+            else {
+                const state = {
+                    db,
+                    policy: workingPolicy,
+                    actor,
+                    summary,
+                    ctx,
+                    verifyFailures: 0,
+                    now,
+                    startedAt,
+                    dayCapReached: false,
+                    deps: applyDeps,
+                };
+                for (const c of candidates) {
+                    if (summary.halted || state.dayCapReached)
+                        break;
+                    if (elapsed() >= budgetMs) {
+                        summary.halted = true;
+                        summary.haltedReason = 'budget_exhausted';
+                        break;
+                    }
+                    await applyCandidate(state, c);
+                }
+            }
+        }
+        catch (err) {
+            console.warn('[seo/autopilot] apply phase failed', err);
+            summary.halted = true;
+            summary.haltedReason = summary.haltedReason ?? 'apply_failed';
+        }
+    }
+}
+//# sourceMappingURL=autopilot.js.map