@avocadostudio-ai/orchestrator-core 0.3.1 → 0.3.3

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();
+}

package/dist/checks/types.d.ts

@@ -0,0 +1,65 @@
+import type { BlockManifest, FieldKind, Operation, PageDoc, SiteConfig } from "@avocadostudio-ai/shared";
+import type { FindingEvidence, FindingSeverity } from "../durable/types.ts";
+/** One field on one block, located by the manifest rather than by block type. */
+export type FieldEntry = {
+    blockId: string;
+    blockType: string;
+    /** Editable-path form: `title`, `cards[0].imageAlt`. */
+    path: string;
+    kind: FieldKind;
+    label?: string;
+    /**
+     * What a reader would call the block this field belongs to — its own heading,
+     * not the block type. A page with three Card Grids produces three findings
+     * reading `cards[0].imageAlt`, and the type name distinguishes none of them.
+     */
+    blockLabel?: string;
+    value: unknown;
+    /**
+     * The container this field sits in — `""` for a top-level prop, `cards[0]`
+     * for a list item. Pairing an image with its alt text is a question about
+     * siblings, and the container is what makes "sibling" meaningful.
+     */
+    container: string;
+};
+/** The other pages, for the rules that cannot be answered from one page. */
+export type SiteView = {
+    slugs: string[];
+    pages: Array<Pick<PageDoc, "slug" | "title"> & {
+        meta?: PageDoc["meta"];
+    }>;
+    config: SiteConfig;
+};
+export type CheckContext = {
+    scopeKey: string;
+    page: PageDoc;
+    site: SiteView;
+    manifest: BlockManifest;
+    /** Every field on the page, already flattened. Rules should not re-walk. */
+    fields: FieldEntry[];
+};
+/**
+ * What a rule returns.
+ *
+ * Deliberately *not* a `FindingInput`: the fingerprint is computed by the
+ * runner from `(scopeKey, slug, ruleId, key)`, so a rule cannot accidentally
+ * fold the offending value into it. That mistake is invisible until the day
+ * somebody half-fixes a title and gets a second finding instead of an updated
+ * one, and the dismissal they made last week stops applying.
+ */
+export type RuleFinding = {
+    /** Distinguishes several findings from one rule on one page. Stable, not a value. */
+    key?: string;
+    severity?: FindingSeverity;
+    title: string;
+    detail?: string;
+    evidence?: FindingEvidence;
+    proposedOps?: Operation[];
+};
+export type CheckRule = {
+    id: string;
+    agent: string;
+    /** Used when a finding does not override it. */
+    severity: FindingSeverity;
+    run(ctx: CheckContext): RuleFinding[];
+};

package/dist/checks/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cms/adapter.d.ts

@@ -51,6 +51,7 @@ export interface CmsPublishContext {
  */
 export type CmsPublishResult = void | {
     ok: true;
+    written?: boolean;
     unsupported?: string[];
 } | {
     ok: false;

package/dist/durable/durable-store-singleton.d.ts

@@ -0,0 +1,37 @@
+import type { DurableStore } from "./types.ts";
+export declare function getDurableStore(): DurableStore;
+/**
+ * Whether findings, memory and proposals are reaching disk, and why not.
+ *
+ * Deliberately separate from `persistenceHealth()`, which answers the same
+ * question about page state and whose warning text is about losing edits.
+ */
+export declare function durableHealth(): {
+    ok: boolean;
+    reason: string | null;
+};
+/**
+ * Record a durable-store write failure. Separate from the page-state channel:
+ * a proposal row that did not save must not tell the user their edits are gone.
+ */
+export declare function noteDurableFailure(reason: string): void;
+/**
+ * True when findings, memory and proposals are living in memory only. Callers
+ * that are about to promise durability — a scheduled run leaving a plan for the
+ * morning — should say so rather than assume.
+ */
+export declare function durableStoreIsEphemeral(): boolean;
+/** Drop the singleton. Tests and graceful shutdown; `getStore()` owns closing. */
+export declare function resetDurableStore(): void;
+/** Swap in a store — for tests, and for a host that brings its own backend. */
+export declare function setDurableStore(next: DurableStore | null, ephemeral?: boolean): void;
+export declare function isDiscardInFlight(scopeKey: string): boolean;
+/**
+ * Discard any pending proposal for a session being deleted.
+ *
+ * Without this, deleting a session leaves a `pending` row behind, and the next
+ * session with that id would rehydrate a plan the user had already thrown away.
+ */
+export declare function discardPendingProposalsForSession(scopeKey: string): void;
+/** Sweep proposals past their TTL, alongside the ephemeral-map eviction pass. */
+export declare function sweepExpiredProposals(): void;

package/dist/durable/durable-store-singleton.js

@@ -0,0 +1,179 @@
+import { getStore } from "../state/sqlite-store-singleton.js";
+import { SqliteDurableStore } from "./sqlite-durable-store.js";
+import { InMemoryDurableStore } from "./in-memory-durable-store.js";
+/*
+ * Singleton access to the durable store, mirroring `getStore()` next door.
+ *
+ * The one interesting decision here is what to do when SQLite is unavailable.
+ * `getStore()` throws: the driver could not load, and there is no page state
+ * without it. This one falls back to `InMemoryDurableStore` instead, for the
+ * same reason `createOrchestrator()` already keeps serving edits in that
+ * situation — a findings panel that 500s because a native module is missing is
+ * worse than one that works and says it is not saving anything.
+ *
+ * The failure is recorded here rather than through `notePersistenceFailure`.
+ * That channel is about *page state*: its warning tells the user "this edit was
+ * applied in memory but could not be saved", and every mutation response starts
+ * carrying `persisted: false`. Reporting a failed *proposal* row through it
+ * would tell somebody their content edits are being lost when they are not —
+ * a worse lie than the one the channel exists to prevent.
+ *
+ * Findings and proposals are capable of exactly the same lie on their own
+ * account, and an overnight run is precisely when nobody is watching the log,
+ * so they get their own flag with its own wording.
+ */
+let store = null;
+let usingFallback = false;
+let overridden = false;
+let failureReason = null;
+let lastAttemptAt = 0;
+/** How long to stay on the fallback before re-trying SQLite. */
+const RETRY_COOLDOWN_MS = 30_000;
+/*
+ * The connection `store` was built against.
+ *
+ * `resetStore()` next door closes the database and drops its singleton, and the
+ * next `getStore()` opens a fresh one — which used to leave this module holding
+ * prepared statements on a closed handle. Rather than have `resetStore()` call
+ * in here (a cycle: this module imports that one), we notice: a different `db`
+ * object means a different database, and the store is rebuilt against it.
+ */
+let boundDb = null;
+export function getDurableStore() {
+    // An explicitly-set store is sticky; the fallback is not.
+    if (store && overridden)
+        return store;
+    /*
+     * The fallback must not be permanent. `getStore()` next door leaves its own
+     * singleton null on a constructor throw and retries on the next call, so page
+     * state recovers from a transient failure — a `.data` directory not yet
+     * writable at boot, say — while this store, if it latched, would stay
+     * memory-only for the life of the process with no way back.
+     *
+     * Retrying on a cooldown rather than every call keeps a genuinely broken
+     * install from paying for a constructor on every finding. Whatever the
+     * fallback accumulated is lost on a successful retry; it was never durable,
+     * and saying so is the honest trade.
+     */
+    if (store && usingFallback && Date.now() - lastAttemptAt < RETRY_COOLDOWN_MS)
+        return store;
+    try {
+        lastAttemptAt = Date.now();
+        // Share `SqliteStore`'s connection: one WAL, one backup, one VACUUM INTO.
+        const db = getStore().db;
+        if (!store || usingFallback || boundDb !== db) {
+            store = new SqliteDurableStore(db);
+            boundDb = db;
+            usingFallback = false;
+            failureReason = null;
+        }
+    }
+    catch (err) {
+        failureReason = err instanceof Error ? err.message : String(err);
+        if (!store || !usingFallback) {
+            store = new InMemoryDurableStore();
+            boundDb = null;
+            usingFallback = true;
+        }
+    }
+    return store;
+}
+/**
+ * Whether findings, memory and proposals are reaching disk, and why not.
+ *
+ * Deliberately separate from `persistenceHealth()`, which answers the same
+ * question about page state and whose warning text is about losing edits.
+ */
+export function durableHealth() {
+    return { ok: !usingFallback, reason: usingFallback ? failureReason : null };
+}
+/**
+ * Record a durable-store write failure. Separate from the page-state channel:
+ * a proposal row that did not save must not tell the user their edits are gone.
+ */
+export function noteDurableFailure(reason) {
+    failureReason ??= reason;
+}
+/**
+ * True when findings, memory and proposals are living in memory only. Callers
+ * that are about to promise durability — a scheduled run leaving a plan for the
+ * morning — should say so rather than assume.
+ */
+export function durableStoreIsEphemeral() {
+    if (!store)
+        getDurableStore();
+    return usingFallback;
+}
+/** Drop the singleton. Tests and graceful shutdown; `getStore()` owns closing. */
+export function resetDurableStore() {
+    store = null;
+    usingFallback = false;
+    overridden = false;
+    boundDb = null;
+    failureReason = null;
+    lastAttemptAt = 0;
+}
+/** Swap in a store — for tests, and for a host that brings its own backend. */
+export function setDurableStore(next, ephemeral = false) {
+    store = next;
+    usingFallback = next ? ephemeral : false;
+    overridden = next !== null;
+    boundDb = null;
+}
+/*
+ * The two lifecycle hooks `session-state.ts` needs, living here rather than in
+ * `pending-plan-store.ts` so that session-state can call them without importing
+ * a module that imports session-state back. The cycle would probably work —
+ * neither side touches the other at module scope — but this repo has already
+ * been bitten by ESM evaluation order once, and a cleanup call is not worth
+ * finding out a second time.
+ *
+ * Both are fire-and-forget: they are called from synchronous state mutators
+ * whose signatures a durability concern has no business changing, and neither
+ * result affects what the caller returns.
+ */
+/**
+ * Sessions whose pending rows are being discarded right now.
+ *
+ * The set is added to *synchronously*, before the async discard starts, and the
+ * rehydration path consults it. `forgetSession` is a synchronous mutator, so
+ * without this a caller that forgets a session and immediately opens a new chat
+ * on the same id — ids are caller-supplied and routinely reused — races the
+ * discard and reads back the plan the delete was meant to remove.
+ *
+ * It lives here rather than in `pending-plan-store.ts` for the same reason the
+ * hooks below do: session-state must be able to reach it without importing a
+ * module that imports session-state back.
+ */
+const discardInFlight = new Set();
+export function isDiscardInFlight(scopeKey) {
+    return discardInFlight.has(scopeKey);
+}
+/**
+ * Discard any pending proposal for a session being deleted.
+ *
+ * Without this, deleting a session leaves a `pending` row behind, and the next
+ * session with that id would rehydrate a plan the user had already thrown away.
+ */
+export function discardPendingProposalsForSession(scopeKey) {
+    discardInFlight.add(scopeKey);
+    void (async () => {
+        const active = getDurableStore();
+        const rows = await active.listProposals({ scopeKey, status: "pending" });
+        for (const row of rows)
+            await active.setProposalStatus(row.id, "discarded");
+    })()
+        .catch(() => {
+        /* best-effort: an orphan row is inert until something reads it, and the
+           read path re-checks expiry and payload validity anyway. */
+    })
+        .finally(() => discardInFlight.delete(scopeKey));
+}
+/** Sweep proposals past their TTL, alongside the ephemeral-map eviction pass. */
+export function sweepExpiredProposals() {
+    void getDurableStore()
+        .expireProposals()
+        .catch(() => {
+        /* best-effort */
+    });
+}

package/dist/durable/finding-impact.d.ts

@@ -0,0 +1,30 @@
+import type { FindingSeverity } from "./types.ts";
+/**
+ * What a severity is worth before the page is taken into account.
+ *
+ * Not linear, and deliberately: `info` is defined in `rules-draft.ts` as "worth
+ * a look, and safe to ignore forever", so an info finding on the home page
+ * should sit below a warning on a secondary page, and 0.3 × 1.0 < 0.6 × 0.55
+ * is what makes that true.
+ */
+export declare const SEVERITY_WEIGHT: Record<FindingSeverity, number>;
+/**
+ * The weight given to a page nothing has scored — a row written by a build
+ * before impact existed, or by a caller that supplied no weights.
+ *
+ * Mid-scale rather than 1, so old rows interleave with scored ones instead of
+ * sorting above every finding on the site until the next run corrects them.
+ */
+export declare const NEUTRAL_PAGE_WEIGHT = 0.5;
+/** Severity × page weight, rounded to something a human can read in a log. */
+export declare function impactFor(severity: FindingSeverity, pageWeight: number): number;
+/** What an unscored finding is worth. Must match `IMPACT_FALLBACK_SQL`. */
+export declare function fallbackImpact(severity: FindingSeverity): number;
+/**
+ * The same fallback, for SQLite's ORDER BY.
+ *
+ * Generated from the constants above rather than written out, because the one
+ * failure mode here is the two drifting apart — the list would then be sorted
+ * by one rule and explained by another, and nothing would look wrong.
+ */
+export declare const IMPACT_FALLBACK_SQL: string;

package/dist/durable/finding-impact.js

@@ -0,0 +1,53 @@
+/*
+ * Impact — severity times how much the page matters.
+ *
+ * It lives beside the types rather than in `checks/` because both stores need
+ * it: a finding written before this shipped has no `impact` column, and the
+ * ORDER BY has to put it somewhere defensible rather than at one end.
+ *
+ * The two axes stay separate on the record. Severity is a claim about the
+ * problem and belongs to the rule; impact is a claim about the page and is
+ * recomputed by every run, because the link graph moves. Multiplying them into
+ * one stored number instead would make a finding's severity unrecoverable, and
+ * severity is what the icon in the panel means.
+ */
+/**
+ * What a severity is worth before the page is taken into account.
+ *
+ * Not linear, and deliberately: `info` is defined in `rules-draft.ts` as "worth
+ * a look, and safe to ignore forever", so an info finding on the home page
+ * should sit below a warning on a secondary page, and 0.3 × 1.0 < 0.6 × 0.55
+ * is what makes that true.
+ */
+export const SEVERITY_WEIGHT = {
+    error: 1,
+    warning: 0.6,
+    info: 0.3
+};
+/**
+ * The weight given to a page nothing has scored — a row written by a build
+ * before impact existed, or by a caller that supplied no weights.
+ *
+ * Mid-scale rather than 1, so old rows interleave with scored ones instead of
+ * sorting above every finding on the site until the next run corrects them.
+ */
+export const NEUTRAL_PAGE_WEIGHT = 0.5;
+/** Severity × page weight, rounded to something a human can read in a log. */
+export function impactFor(severity, pageWeight) {
+    const clamped = Math.max(0, Math.min(pageWeight, 1));
+    return Math.round(SEVERITY_WEIGHT[severity] * clamped * 1000) / 1000;
+}
+/** What an unscored finding is worth. Must match `IMPACT_FALLBACK_SQL`. */
+export function fallbackImpact(severity) {
+    return impactFor(severity, NEUTRAL_PAGE_WEIGHT);
+}
+/**
+ * The same fallback, for SQLite's ORDER BY.
+ *
+ * Generated from the constants above rather than written out, because the one
+ * failure mode here is the two drifting apart — the list would then be sorted
+ * by one rule and explained by another, and nothing would look wrong.
+ */
+export const IMPACT_FALLBACK_SQL = `COALESCE(impact, CASE severity ${Object.keys(SEVERITY_WEIGHT)
+    .map((severity) => `WHEN '${severity}' THEN ${fallbackImpact(severity)}`)
+    .join(" ")} END)`;