@avocadostudio-ai/orchestrator-core 0.3.2 → 0.3.3

package/dist/checks/rules-draft.js

@@ -0,0 +1,375 @@
+import { IMAGE_PLACEHOLDER, isKnownRoute, parseLink, toAltPath } from "@avocadostudio-ai/shared";
+import { fieldText, groupByBlock } from "./field-walk.js";
+/*
+ * The eleven-ish draft-tier rules. Each is a pure function; none does IO.
+ *
+ * Severity discipline, because findings fatigue is the failure mode and a panel
+ * with 300 warnings is a panel nobody opens:
+ *   error   — this is broken and a crawler or a screen reader sees it
+ *   warning — this is very likely wrong
+ *   info    — worth a look, and safe to ignore forever
+ */
+const TITLE_MIN = 20;
+const TITLE_MAX = 60;
+const DESCRIPTION_MIN = 70;
+const DESCRIPTION_MAX = 160;
+const THIN_CONTENT_CHARS = 120;
+function effectiveTitle(page) {
+    return (page.meta?.title ?? page.title ?? "").trim();
+}
+function nonEmpty(value) {
+    return fieldText(value).trim().length > 0;
+}
+function textFields(ctx) {
+    return ctx.fields.filter((f) => f.kind === "text" || f.kind === "richtext");
+}
+function evidenceFor(field, excerpt) {
+    return {
+        source: "draft",
+        blockId: field.blockId,
+        blockType: field.blockType,
+        ...(field.blockLabel ? { blockLabel: field.blockLabel } : {}),
+        path: field.path,
+        ...(excerpt ? { excerpt } : {})
+    };
+}
+// ---------------------------------------------------------------------------
+// Page metadata
+// ---------------------------------------------------------------------------
+const titleMissing = {
+    id: "seo.title-missing",
+    agent: "seo",
+    severity: "error",
+    run: (ctx) => effectiveTitle(ctx.page)
+        ? []
+        : [
+            {
+                title: "Page has no title",
+                detail: "Neither meta.title nor the page title is set, so the tab and the search result have nothing to show."
+            }
+        ]
+};
+const titleLength = {
+    id: "seo.title-length",
+    agent: "seo",
+    severity: "info",
+    run: (ctx) => {
+        const title = effectiveTitle(ctx.page);
+        if (!title)
+            return []; // titleMissing owns that case; two findings for one fact is noise
+        if (title.length < TITLE_MIN) {
+            return [{ title: `Title is ${title.length} characters (aim for ${TITLE_MIN}–${TITLE_MAX})` }];
+        }
+        if (title.length > TITLE_MAX) {
+            return [{ title: `Title is ${title.length} characters and will be truncated (aim for ${TITLE_MIN}–${TITLE_MAX})` }];
+        }
+        return [];
+    }
+};
+const titleDuplicate = {
+    id: "seo.title-duplicate",
+    agent: "seo",
+    severity: "warning",
+    run: (ctx) => {
+        const title = effectiveTitle(ctx.page);
+        if (!title)
+            return [];
+        const clash = ctx.site.pages.filter((p) => p.slug !== ctx.page.slug &&
+            (p.meta?.title ?? p.title ?? "").trim().toLowerCase() === title.toLowerCase());
+        if (clash.length === 0)
+            return [];
+        return [
+            {
+                title: "Another page has the same title",
+                detail: `Also used by ${clash.map((p) => p.slug).join(", ")}. Search engines pick one and drop the rest.`
+            }
+        ];
+    }
+};
+const descriptionMissing = {
+    id: "seo.description-missing",
+    agent: "seo",
+    severity: "warning",
+    run: (ctx) => (ctx.page.meta?.description ?? "").trim()
+        ? []
+        : [
+            {
+                title: "Page has no description",
+                // No proposedOps: writing a good one is a judgement-tier job. A
+                // rule that guessed here would ship copy under an approval button
+                // people have learned to click.
+                detail: "Search results and link previews will fall back to whatever text they can scrape."
+            }
+        ]
+};
+const descriptionLength = {
+    id: "seo.description-length",
+    agent: "seo",
+    severity: "info",
+    run: (ctx) => {
+        const description = (ctx.page.meta?.description ?? "").trim();
+        if (!description)
+            return [];
+        if (description.length < DESCRIPTION_MIN) {
+            return [{ title: `Description is ${description.length} characters (aim for ${DESCRIPTION_MIN}–${DESCRIPTION_MAX})` }];
+        }
+        if (description.length > DESCRIPTION_MAX) {
+            return [{ title: `Description is ${description.length} characters and will be truncated (aim for ${DESCRIPTION_MIN}–${DESCRIPTION_MAX})` }];
+        }
+        return [];
+    }
+};
+const ogImageMissing = {
+    id: "seo.og-image-missing",
+    agent: "seo",
+    severity: "info",
+    run: (ctx) => {
+        if ((ctx.page.meta?.ogImage ?? "").trim())
+            return [];
+        const hasImage = ctx.fields.some((f) => f.kind === "image" && nonEmpty(f.value) && f.value !== IMAGE_PLACEHOLDER);
+        return [
+            {
+                title: "No social preview image",
+                detail: hasImage
+                    ? "The page has images but none is set as meta.ogImage, so shares get no thumbnail."
+                    : "Shared links will render without a thumbnail."
+            }
+        ];
+    }
+};
+const slugQuality = {
+    id: "seo.slug-quality",
+    agent: "seo",
+    severity: "info",
+    run: (ctx) => {
+        const slug = ctx.page.slug;
+        const problems = [];
+        if (/[A-Z]/.test(slug))
+            problems.push("uppercase letters");
+        if (slug.includes("_"))
+            problems.push("underscores instead of hyphens");
+        if (/\s/.test(slug))
+            problems.push("spaces");
+        if (slug.split("/").filter(Boolean).length > 5)
+            problems.push("more than five segments");
+        if (problems.length === 0)
+            return [];
+        return [{ title: `Slug has ${problems.join(", ")}`, detail: slug }];
+    }
+};
+// ---------------------------------------------------------------------------
+// Structure
+// ---------------------------------------------------------------------------
+/** Heading levels in block order, from any field the manifest calls a headingLevel. */
+function headingLevels(ctx) {
+    const out = [];
+    for (const field of ctx.fields) {
+        if (field.kind !== "headingLevel")
+            continue;
+        const level = typeof field.value === "number" ? field.value : Number(field.value);
+        if (Number.isFinite(level) && level >= 1 && level <= 6)
+            out.push({ field, level });
+    }
+    return out;
+}
+const h1Count = {
+    id: "seo.h1-count",
+    agent: "seo",
+    severity: "warning",
+    run: (ctx) => {
+        const levels = headingLevels(ctx);
+        // A page whose blocks declare no heading level at all is not making a
+        // claim about its structure — most likely the site's blocks hardcode their
+        // tags. Reporting "no h1" there is a guess dressed as a fact.
+        if (levels.length === 0)
+            return [];
+        const h1s = levels.filter((l) => l.level === 1);
+        if (h1s.length === 1)
+            return [];
+        if (h1s.length === 0) {
+            return [{ title: "Page has no top-level heading", detail: "No block on the page is set to heading level 1." }];
+        }
+        // Keyed by field, not by block: a block may declare more than one heading
+        // level (a two-column with a heading each), and two findings sharing one
+        // key collapse into one — leaving the second heading with no finding and
+        // no proposed fix.
+        return h1s.slice(1).map(({ field }) => ({
+            key: `${field.blockId}:${field.path}`,
+            title: "Page has more than one top-level heading",
+            detail: `${h1s.length} blocks are set to heading level 1.`,
+            evidence: evidenceFor(field),
+            proposedOps: [
+                {
+                    op: "update_props",
+                    pageSlug: ctx.page.slug,
+                    blockId: field.blockId,
+                    patch: { [field.path]: 2 }
+                }
+            ]
+        }));
+    }
+};
+const headingOrder = {
+    id: "seo.heading-order",
+    agent: "seo",
+    severity: "info",
+    run: (ctx) => {
+        const levels = headingLevels(ctx);
+        const out = [];
+        let previous = null;
+        for (const { field, level } of levels) {
+            if (previous !== null && level > previous + 1) {
+                out.push({
+                    key: `${field.blockId}:${field.path}`,
+                    title: `Heading jumps from level ${previous} to ${level}`,
+                    detail: "Screen readers announce the gap as a missing section.",
+                    evidence: evidenceFor(field)
+                });
+            }
+            previous = level;
+        }
+        return out;
+    }
+};
+const thinContent = {
+    id: "seo.thin-content",
+    agent: "seo",
+    severity: "info",
+    run: (ctx) => {
+        const total = textFields(ctx)
+            .map((f) => fieldText(f.value).trim())
+            .join(" ")
+            .trim();
+        if (total.length >= THIN_CONTENT_CHARS)
+            return [];
+        return [
+            {
+                title: `Page has ${total.length} characters of text`,
+                detail: `Under ${THIN_CONTENT_CHARS} characters is usually too little for a page to rank for anything.`
+            }
+        ];
+    }
+};
+// ---------------------------------------------------------------------------
+// Links, images, leftovers
+// ---------------------------------------------------------------------------
+const internalLinkDead = {
+    id: "seo.internal-link-dead",
+    agent: "seo",
+    severity: "warning",
+    run: (ctx) => {
+        const known = new Set(ctx.site.slugs);
+        return ctx.fields
+            /*
+             * `link` is the kind that means "navigation target"; `url` is still
+             * accepted because a custom block's manifest may declare either, and a
+             * dead link is a dead link whichever way it was tagged. `parseLink`
+             * screens out mailto/tel/anchors/external and the default "/", so only a
+             * real route reaches `isKnownRoute` — the same matcher the editor's link
+             * field uses inline, so the panel and the field cannot disagree.
+             */
+            .filter((f) => f.kind === "link" || f.kind === "url")
+            /*
+             * Absolute routes only, as before. A bare "pricing" is a relative link
+             * and broken from any page but the root, but flagging it is a separate
+             * judgement call from this rule's, and one that would light up existing
+             * sites without warning.
+             */
+            .filter((f) => parseLink(f.value).path?.startsWith("/") === true)
+            .filter((f) => !isKnownRoute(String(f.value), known))
+            .map((field) => ({
+            key: field.path === "" ? field.blockId : `${field.blockId}:${field.path}`,
+            title: `Link points at a page that does not exist`,
+            detail: String(field.value),
+            evidence: evidenceFor(field, String(field.value))
+        }));
+    }
+};
+const altMissing = {
+    id: "a11y.alt-missing",
+    agent: "a11y",
+    severity: "warning",
+    run: (ctx) => {
+        const out = [];
+        /*
+         * One block at a time. Paths and containers are block-relative, so a
+         * page-wide index of either pairs an image in one block with the alt text
+         * of another — and two blocks of the same type on one page is the ordinary
+         * case, not the exotic one.
+         *
+         * All three ways that went wrong were silent: two heroes where the first
+         * had no alt text reported nothing at all; the mirror image reported the
+         * problem twice, both times pointing "Go to" at the wrong block.
+         */
+        for (const fields of groupByBlock(ctx.fields).values()) {
+            const alts = fields.filter((f) => f.kind === "imageAlt");
+            const altByPath = new Map(alts.map((f) => [f.path, f]));
+            const altsByContainer = new Map();
+            for (const field of alts) {
+                const list = altsByContainer.get(field.container) ?? [];
+                list.push(field);
+                altsByContainer.set(field.container, list);
+            }
+            for (const image of fields) {
+                if (image.kind !== "image" || !nonEmpty(image.value))
+                    continue;
+                // The repo's own naming convention first (`imageUrl` → `imageAlt`,
+                // `.src` → `.alt`), then the structural answer: a lone alt field in the
+                // same container. A container with two images and two alts is ambiguous
+                // and is left alone rather than guessed at.
+                const byConvention = altByPath.get(toAltPath(image.path));
+                const siblings = altsByContainer.get(image.container) ?? [];
+                const alt = byConvention ?? (siblings.length === 1 ? siblings[0] : undefined);
+                if (!alt || nonEmpty(alt.value))
+                    continue;
+                out.push({
+                    key: `${image.blockId}:${image.path}`,
+                    title: `Image has no alt text`,
+                    detail: `${image.label ?? image.path} is set but its alt text is empty.`,
+                    evidence: evidenceFor(alt)
+                });
+            }
+        }
+        return out;
+    }
+};
+const unfinished = {
+    id: "content.unfinished",
+    agent: "content",
+    severity: "warning",
+    run: (ctx) => {
+        const out = [];
+        for (const field of ctx.fields) {
+            // `defaultScalarForField` writes exactly these when a block is scaffolded,
+            // so this is an equality test, not a heuristic — the product is the only
+            // thing that could have produced the string.
+            const isScaffoldText = (field.kind === "text" || field.kind === "richtext" || field.kind === "imageAlt") &&
+                fieldText(field.value).trim() === `New ${field.label ?? field.path}`;
+            const isScaffoldImage = field.kind === "image" && field.value === IMAGE_PLACEHOLDER;
+            if (!isScaffoldText && !isScaffoldImage)
+                continue;
+            out.push({
+                key: `${field.blockId}:${field.path}`,
+                title: `${field.label ?? field.path} was never filled in`,
+                detail: "This is still the placeholder the block was created with.",
+                evidence: evidenceFor(field, fieldText(field.value) || String(field.value))
+            });
+        }
+        return out;
+    }
+};
+export const DRAFT_RULES = [
+    titleMissing,
+    titleLength,
+    titleDuplicate,
+    descriptionMissing,
+    descriptionLength,
+    ogImageMissing,
+    slugQuality,
+    h1Count,
+    headingOrder,
+    thinContent,
+    internalLinkDead,
+    altMissing,
+    unfinished
+];

package/dist/checks/run-checks.d.ts

@@ -0,0 +1,32 @@
+import type { BlockManifest, PageDoc, SiteConfig } from "@avocadostudio-ai/shared";
+import type { CheckRunRecord, CheckRunTrigger, DurableStore } from "../durable/types.ts";
+import type { CheckRule } from "./types.ts";
+/**
+ * The fingerprint: identity of a problem, not of an occurrence of it.
+ *
+ * It is computed here, from `(scopeKey, slug, ruleId, key)`, and never by a
+ * rule — because the one thing that must not leak into it is the offending
+ * *value*. Include the value and half-fixing a title produces a second finding
+ * instead of an updated one, orphaning the first and silently voiding the
+ * dismissal somebody made last week.
+ */
+export declare function fingerprintFor(scopeKey: string, slug: string, ruleId: string, key?: string): string;
+export type RunChecksArgs = {
+    scopeKey: string;
+    /** Every page in the site — not just the ones being scanned. See below. */
+    pages: PageDoc[];
+    manifest: BlockManifest;
+    siteConfig?: SiteConfig;
+    trigger?: CheckRunTrigger;
+    /**
+     * Restrict the scan to these slugs. Cross-page rules still see the whole
+     * site: an incremental run over one page must not report every *other*
+     * page's title as unique, nor every link into them as dead.
+     */
+    slugs?: string[];
+    rules?: CheckRule[];
+    store?: DurableStore;
+    runId?: string;
+    now?: () => number;
+};
+export declare function runDraftChecks(args: RunChecksArgs): Promise<CheckRunRecord>;

package/dist/checks/run-checks.js

@@ -0,0 +1,152 @@
+import { createHash, randomUUID } from "node:crypto";
+import { getDurableStore } from "../durable/durable-store-singleton.js";
+import { NEUTRAL_PAGE_WEIGHT, impactFor } from "../durable/finding-impact.js";
+import { walkPageFields } from "./field-walk.js";
+import { computePageWeights } from "./page-weight.js";
+import { DRAFT_RULES } from "./rules-draft.js";
+/**
+ * The fingerprint: identity of a problem, not of an occurrence of it.
+ *
+ * It is computed here, from `(scopeKey, slug, ruleId, key)`, and never by a
+ * rule — because the one thing that must not leak into it is the offending
+ * *value*. Include the value and half-fixing a title produces a second finding
+ * instead of an updated one, orphaning the first and silently voiding the
+ * dismissal somebody made last week.
+ */
+export function fingerprintFor(scopeKey, slug, ruleId, key = "") {
+    return createHash("sha256").update([scopeKey, slug, ruleId, key].join("\u0000")).digest("hex").slice(0, 32);
+}
+export async function runDraftChecks(args) {
+    const store = args.store ?? getDurableStore();
+    const now = args.now ?? Date.now;
+    const rules = args.rules ?? DRAFT_RULES;
+    const runId = args.runId ?? randomUUID();
+    const startedAt = now();
+    const site = {
+        slugs: args.pages.map((p) => p.slug),
+        pages: args.pages.map((p) => ({ slug: p.slug, title: p.title, ...(p.meta ? { meta: p.meta } : {}) })),
+        config: args.siteConfig ?? {}
+    };
+    const wanted = args.slugs ? new Set(args.slugs) : null;
+    const scanned = args.pages.filter((p) => (wanted ? wanted.has(p.slug) : true));
+    /*
+     * Every page is walked, not only the scanned ones.
+     *
+     * Page weight is a property of the site's link graph, so scoring it from the
+     * scanned subset would make a finding's impact depend on which run last
+     * touched it — the same finding worth 0.6 after a full sweep and 0.1 after an
+     * incremental one, with the panel resorting itself for no visible reason.
+     *
+     * The walk is pure in-memory work over data already held, and the scanned
+     * pages reuse their entry rather than being walked a second time.
+     */
+    const fieldsBySlug = new Map();
+    for (const page of args.pages)
+        fieldsBySlug.set(page.slug, walkPageFields(page, args.manifest));
+    const weights = computePageWeights({ pages: site.pages, fieldsBySlug, config: site.config });
+    await store.startCheckRun({
+        id: runId,
+        scopeKey: args.scopeKey,
+        agent: rules.length === 1 ? rules[0].agent : "checks",
+        trigger: args.trigger ?? "manual",
+        startedAt
+    });
+    const findings = [];
+    const seen = new Set();
+    let error;
+    try {
+        for (const page of scanned) {
+            const pageWeight = weights.get(page.slug)?.weight ?? NEUTRAL_PAGE_WEIGHT;
+            const ctx = {
+                scopeKey: args.scopeKey,
+                page,
+                site,
+                manifest: args.manifest,
+                fields: fieldsBySlug.get(page.slug) ?? []
+            };
+            for (const rule of rules) {
+                // One rule throwing must not cost the run every other rule's findings —
+                // a checker that goes dark because a custom block had an unexpected
+                // prop shape is worse than one that reports twelve of thirteen rules.
+                let produced;
+                try {
+                    produced = rule.run(ctx);
+                }
+                catch (err) {
+                    error ??= `${rule.id}: ${err instanceof Error ? err.message : String(err)}`;
+                    continue;
+                }
+                for (const finding of produced) {
+                    const fingerprint = fingerprintFor(args.scopeKey, page.slug, rule.id, finding.key);
+                    /*
+                     * Two findings from one rule sharing a key are one finding as far as
+                     * the store is concerned — the second upsert overwrites the first.
+                     * Collapsing them here instead keeps the ledger honest (the second
+                     * was being counted as an `updated` row) and makes which one survives
+                     * a decision rather than an accident of iteration order.
+                     */
+                    if (seen.has(fingerprint))
+                        continue;
+                    seen.add(fingerprint);
+                    const severity = finding.severity ?? rule.severity;
+                    findings.push({
+                        fingerprint,
+                        scopeKey: args.scopeKey,
+                        slug: page.slug,
+                        ruleId: rule.id,
+                        agent: rule.agent,
+                        severity,
+                        impact: impactFor(severity, pageWeight),
+                        title: finding.title,
+                        ...(finding.detail ? { detail: finding.detail } : {}),
+                        ...(finding.evidence ? { evidence: finding.evidence } : {}),
+                        ...(finding.proposedOps ? { proposedOps: finding.proposedOps } : {})
+                    });
+                }
+            }
+        }
+        const { opened } = await store.recordFindings(runId, findings);
+        // Reconcile per agent, not once for the whole run. A run of only the SEO
+        // rules that closed everything in scope would mark this morning's
+        // accessibility findings fixed without having looked at them.
+        const scannedSlugs = scanned.map((p) => p.slug);
+        let closed = 0;
+        for (const agent of new Set(rules.map((r) => r.agent))) {
+            const result = await store.reconcileFindings({
+                runId,
+                scopeKey: args.scopeKey,
+                slugs: scannedSlugs,
+                agent,
+                at: now()
+            });
+            closed += result.closed;
+        }
+        const record = {
+            id: runId,
+            scopeKey: args.scopeKey,
+            agent: rules.length === 1 ? rules[0].agent : "checks",
+            trigger: args.trigger ?? "manual",
+            startedAt,
+            finishedAt: now(),
+            pagesScanned: scanned.length,
+            findingsOpened: opened,
+            findingsClosed: closed,
+            costUsd: 0,
+            ...(error ? { error } : {})
+        };
+        await store.finishCheckRun(runId, {
+            finishedAt: record.finishedAt,
+            pagesScanned: record.pagesScanned,
+            findingsOpened: record.findingsOpened,
+            findingsClosed: record.findingsClosed,
+            costUsd: 0,
+            ...(error ? { error } : {})
+        });
+        return record;
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        await store.finishCheckRun(runId, { finishedAt: now(), pagesScanned: scanned.length, error: reason });
+        throw err;
+    }
+}

package/dist/checks/session-runner.d.ts

@@ -0,0 +1,19 @@
+import type { CheckRunRecord, CheckRunTrigger } from "../durable/types.ts";
+import type { Logger } from "../logger.ts";
+export declare function runChecksForSession(args: {
+    scopeKey: string;
+    trigger: CheckRunTrigger;
+    slugs?: string[];
+}): Promise<CheckRunRecord>;
+/**
+ * Queue a draft-tier run after an apply, coalescing a burst of edits into one.
+ *
+ * Debounced rather than throttled: the useful moment is after someone stops
+ * typing, not in the middle of a streamed multi-op plan where half the ops have
+ * landed and the page is transiently wrong.
+ */
+export declare function scheduleChecksAfterApply(scopeKey: string, log?: Logger): void;
+/** Run the draft tier after a successful publish. */
+export declare function scheduleChecksAfterPublish(scopeKey: string, log?: Logger): void;
+/** Cancel any queued run. Tests, and graceful shutdown. */
+export declare function cancelScheduledChecks(): void;

package/dist/checks/session-runner.js

@@ -0,0 +1,95 @@
+import { buildBlockManifest } from "@avocadostudio-ai/shared";
+import { getSessionDraft, getSiteConfig } from "../state/session-state.js";
+import { runDraftChecks } from "./run-checks.js";
+/*
+ * Binds the pure rules engine to session state.
+ *
+ * `run-checks.ts` deliberately takes pages and a manifest as arguments and
+ * touches no globals — it is testable against invented block types and an
+ * invented site. This is the one place that reaches for the real ones, so both
+ * the HTTP action and the triggers below run identical code.
+ */
+export async function runChecksForSession(args) {
+    return runDraftChecks({
+        scopeKey: args.scopeKey,
+        pages: [...getSessionDraft(args.scopeKey).values()],
+        // The registry of *this* process — in library mode, the host's own
+        // `registerBlocks()`. Same reason `blocksManifestAction` uses it: a rule
+        // reading our built-ins would be blind to the site's real vocabulary.
+        manifest: buildBlockManifest(),
+        siteConfig: getSiteConfig(args.scopeKey),
+        trigger: args.trigger,
+        ...(args.slugs?.length ? { slugs: args.slugs } : {})
+    });
+}
+// ---------------------------------------------------------------------------
+// Triggers
+// ---------------------------------------------------------------------------
+/*
+ * What wakes a check run, and why the defaults are what they are.
+ *
+ * `on_publish` is on by default: the draft tier is a few milliseconds of
+ * in-memory work, it costs nothing, and the moment content ships is when
+ * anybody cares whether it is broken.
+ *
+ * `on_apply` is off by default, behind `CHECKS_ON_APPLY=1`. It is the one that
+ * fires on every edit, and this repo has already paid once for a fan-out
+ * nobody intended — an ambient linter should be something an operator turns on
+ * having decided to, not something they discover in a CPU graph.
+ *
+ * Both are inert under NODE_ENV=test: the hermetic suite must not have a
+ * background task writing findings into a store its assertions are reading.
+ */
+const ON_APPLY_DEBOUNCE_MS = 2_000;
+const pending = new Map();
+function enabled(flag) {
+    if (process.env.NODE_ENV === "test")
+        return false;
+    if (flag === "apply")
+        return process.env.CHECKS_ON_APPLY === "1";
+    return process.env.CHECKS_ON_PUBLISH !== "0";
+}
+function runInBackground(scopeKey, trigger, log) {
+    void runChecksForSession({ scopeKey, trigger })
+        .then((run) => {
+        log?.info({ scopeKey, trigger, opened: run.findingsOpened, closed: run.findingsClosed }, "checks run complete");
+    })
+        .catch((err) => {
+        // A checker must never be able to fail the edit or the publish that
+        // triggered it. It reports and stops.
+        log?.error({ err: String(err), scopeKey, trigger }, "checks run failed");
+    });
+}
+/**
+ * Queue a draft-tier run after an apply, coalescing a burst of edits into one.
+ *
+ * Debounced rather than throttled: the useful moment is after someone stops
+ * typing, not in the middle of a streamed multi-op plan where half the ops have
+ * landed and the page is transiently wrong.
+ */
+export function scheduleChecksAfterApply(scopeKey, log) {
+    if (!enabled("apply"))
+        return;
+    const existing = pending.get(scopeKey);
+    if (existing)
+        clearTimeout(existing);
+    const timer = setTimeout(() => {
+        pending.delete(scopeKey);
+        runInBackground(scopeKey, "on_apply", log);
+    }, ON_APPLY_DEBOUNCE_MS);
+    // Do not hold the process open for a linter.
+    timer.unref?.();
+    pending.set(scopeKey, timer);
+}
+/** Run the draft tier after a successful publish. */
+export function scheduleChecksAfterPublish(scopeKey, log) {
+    if (!enabled("publish"))
+        return;
+    runInBackground(scopeKey, "on_publish", log);
+}
+/** Cancel any queued run. Tests, and graceful shutdown. */
+export function cancelScheduledChecks() {
+    for (const timer of pending.values())
+        clearTimeout(timer);
+    pending.clear();
+}