@avocadostudio-ai/orchestrator-core 0.3.2 → 0.4.0

package/dist/handler/create-orchestrator.js

@@ -30,16 +30,18 @@ import { runChatPipeline, collectMentionedSlugsFromOps } from "../chat/chat-pipe
 import { createChatTelemetryStore } from "../telemetry/chat-telemetry.js";
 import { createToolRuntime } from "../tools/runtime.js";
 import { loadStateFromDisk, scopedSessionKey, getSessionPages, getPage, getSiteConfig, setSiteConfig, pushUndo, bumpVersion, pushRecentEdit, pushVersionEntry, schedulePersistState, normalizeSiteId, publishStatusBySession, pushPublishLogEntry, persistenceHealth, persistenceWarning } from "../state/session-state.js";
-import { historyStatus, historyLog, historyUndoAction, historyRedoAction, historyRestoreAction } from "../http/history-actions.js";
+import { historyStatus, historyLog, historyUndoAction, historyRedoAction, historyRestoreAction, historyDiscardAction } from "../http/history-actions.js";
 import { whoamiAction } from "../http/session-actions.js";
 import { blocksManifestAction } from "../http/blocks-actions.js";
 import { screenshotAction } from "../http/screenshot-actions.js";
+import { runChecksAction, listFindingsAction, listCheckRunsAction, updateFindingAction } from "../http/checks-actions.js";
 import { fileImageStore, formatImageChatFrame, generateImageAction, imageChatAction, imageChatStreamAction, interpretImageAction, validateImageChatRequest } from "../http/image-generate-actions.js";
 import { transcribeAudioAction, transcriptionUnavailable, validateAudioInput } from "../http/audio-actions.js";
 import { formatVariationFrame, parseVariationRequest, scopeVariationSession, variationsAction, variationsStreamAction } from "../http/variations-actions.js";
 import { opsDryRunAction, describeAppliedOps } from "../http/ops-actions.js";
 import { describeDraft } from "../http/draft-provenance.js";
 import { buildPublishSummary, publishDiffAction, publishLogAction, publishStatusAction } from "../http/publish-actions.js";
+import { isSelectionFailure, parseSelectionSlugs, selectPagesForPublish } from "../publish/publish-selection.js";
 import { restoreSnapshotApply, restoreSnapshotDelete, restoreSnapshotsList } from "../http/restore-actions.js";
 import { unsplashSearchAction } from "../http/unsplash-actions.js";
 import { telemetryFeedbackListAction, telemetryFeedbackSubmitAction } from "../http/telemetry-feedback-actions.js";
@@ -50,6 +52,7 @@ import { resolveCapabilities } from "../cms/adapter.js";
 import { mediaSourceFromUnknown } from "../cms/media-sources.js";
 import { isAccessGateEnabled, mintAccessToken, verifyAccessPassword } from "../http/access-tokens.js";
 import { checkAuth, resolveAuth } from "./auth.js";
+import { setSiteAssetLister, invalidateSiteAssets } from "../state/site-assets.js";
 const defaultModelLookup = () => ({
     openai: {
         fast: process.env.OPENAI_MODEL_FAST ?? "gpt-4o-mini",
@@ -130,16 +133,70 @@ async function buildRuntime(config) {
      * forgotten, and `ensure()` still does its own fetch.
      */
     bootstrapCache.warm(config.adapter ?? null, log);
+    /*
+     * Tell the checker which documents this site has, if it can say.
+     *
+     * `content.file-link-unknown` is the rule that turns a hand-typed PDF path
+     * into something verifiable, and it needs the asset list. Registered here
+     * because this is the one place that holds the adapter and knows whether it
+     * implements the seam; a site with no `getMedia` registers nothing, and the
+     * rule stays silent rather than calling every document on the site missing.
+     */
+    const adapter = config.adapter ?? null;
+    if (typeof adapter?.getMedia === "function") {
+        const getMedia = adapter.getMedia.bind(adapter);
+        setSiteAssetLister(async () => {
+            const out = [];
+            /*
+             * Paged, and bounded. A media library can hold thousands of files, and a
+             * linter is not entitled to walk all of them on every publish — past the
+             * cap the rule sees a partial list, which is why it reports only links
+             * that match nothing *and* stops being useful rather than wrong: a file
+             * beyond the cap is simply not checked.
+             */
+            for (let page = 1; page <= ASSET_LIST_MAX_PAGES; page++) {
+                const result = await getMedia({ page, limit: ASSET_LIST_PAGE_SIZE, kind: "file" });
+                for (const item of result.items ?? []) {
+                    if ((item.kind ?? "image") !== "file")
+                        continue;
+                    const path = item.url ?? item.imageUrl;
+                    if (!path)
+                        continue;
+                    out.push({
+                        path,
+                        ...(item.name ? { name: item.name } : {}),
+                        ...(item.contentType ? { contentType: item.contentType } : {}),
+                        ...(item.size != null ? { size: item.size } : {})
+                    });
+                }
+                if (page >= (result.totalPages ?? 1))
+                    break;
+            }
+            return out;
+        });
+    }
+    else {
+        setSiteAssetLister(null);
+    }
     return {
         pipelineCtx,
         ready,
         resumableStore,
         log,
-        adapter: config.adapter ?? null,
+        adapter,
         capabilities,
         bootstrapCache
     };
 }
+/*
+ * A cap on one upload. Generous for a document — the largest PDF on the site
+ * that prompted this is 183KB — and small enough that a misdirected video does
+ * not sit in memory as a `Uint8Array` while the adapter decides what to do
+ * with it.
+ */
+const MEDIA_UPLOAD_MAX_BYTES = 25_000_000;
+const ASSET_LIST_PAGE_SIZE = 100;
+const ASSET_LIST_MAX_PAGES = 10;
 /*
  * Takes the *resolved* CORS map rather than the raw Origin header. It used to
  * echo the origin directly, which meant every SSE response granted a
@@ -214,11 +271,16 @@ const SUPPORTED_ROUTES = [
     "POST /draft/bootstrap",
     "GET+PUT /draft/site-config",
     "POST /ops",
+    "POST /checks/run",
+    "GET /checks/findings",
+    "GET /checks/runs",
+    "POST /checks/findings/status",
     "GET /history/status",
     "GET /history/log",
     "POST /history/undo",
     "POST /history/redo",
     "POST /history/restore",
+    "POST /history/discard",
     "GET /whoami",
     "GET /blocks/manifest",
     "GET /sites",
@@ -231,6 +293,7 @@ const SUPPORTED_ROUTES = [
     "DELETE /restore/snapshot",
     "GET /unsplash/search",
     "POST /media/cms",
+    "POST /media/upload",
     "GET+POST /telemetry/chat/feedback",
     "POST /preview/screenshot",
     "POST /audio/transcribe",
@@ -298,14 +361,31 @@ export function createOrchestrator(config = {}) {
     // up editing the bundled demo pages instead of the site's real content.
     const effectiveSiteId = config.adapter ? (config.siteId ?? "library") : config.siteId;
     /*
-     * Declared at mount, before any request can build a manifest. The registry
-     * holds this on `globalThis`, so it survives Next duplicating these modules
-     * across the RSC / SSR / route-handler layers — the declaration made here has
-     * to be visible to `/api/editor/blocks` in another copy.
+     * The registry holds this on `globalThis`, so it survives Next duplicating
+     * these modules across the RSC / SSR / route-handler layers — the declaration
+     * made here is visible to `/api/editor/blocks` in another copy.
+     *
+     * It is *not*, however, made "at mount" in any sense that covers the other
+     * route. This runs when this route's module is first evaluated, which Next
+     * does on the first request to this route — so an editor that asks
+     * `/api/editor/blocks` before anything has touched `/api/avocado/*` sees an
+     * undeclared catalogue and is offered Avocado's built-ins alongside the
+     * site's own. Pass `blockTypes` to `createEditorApiHandler` as well; it
+     * declares the same catalogue while building the manifest, which is the point
+     * that actually needs it.
      */
     if (config.blockTypes)
         declareBlockCatalogue(config.blockTypes);
     const scope = (session, bodySiteId) => scopedSessionKey(session, effectiveSiteId ?? bodySiteId);
+    /*
+     * The same resolution, for an action that scopes the session itself.
+     *
+     * `scope()` answers with a key, which is what a route needs when it holds the
+     * key. An action given `{ session, siteId }` computes its own, and every
+     * caller that forgot to fill `siteId` in silently addressed a different
+     * session than the route beside it — see `/checks/run`.
+     */
+    const withSiteId = (params) => effectiveSiteId ? { ...params, siteId: effectiveSiteId } : params;
     const imageDir = config.imageDir ?? resolve(process.cwd(), ".data/generated-images");
     /*
      * Built on first use rather than at mount: the store opens an append-only
@@ -699,7 +779,48 @@ export function createOrchestrator(config = {}) {
              * publish (LM-04).
              */
             await runtime.bootstrapCache.ensure(scopedSession, runtime.adapter, runtime.log);
-            const pages = getSessionPages(scopedSession);
+            /*
+             * Hand the adapter the baseline it needs to diff.
+             *
+             * `onPublish(pages)` alone is a snapshot contract, and a snapshot is not
+             * invertible: every CMS read is a projection, so writing the projection
+             * back replaces an asset reference with a URL and a document reference
+             * with a dead href. A publisher has to compare against what it read, and
+             * it cannot compare against nothing.
+             *
+             * This is the copy the bootstrap already took, not a fresh read — a
+             * second `getPages()` here is 45 sequential Sanity calls on the
+             * integration that motivated it. It used to be absent for the rest of a
+             * process's life after a restart that reloaded the draft from SQLite,
+             * which quietly disabled publishing for any adapter that refuses without
+             * a baseline; `ensure` now recovers it on the first request instead.
+             *
+             * It can still be undefined — the adapter read can fail, and baselines
+             * are evicted FIFO — so the contract is unchanged: treat undefined as
+             * "no baseline available" and never as "the site was empty".
+             */
+            const published = runtime.bootstrapCache.baselineFor(scopedSession) ?? undefined;
+            /*
+             * A publish of some pages is the live site with those pages replaced,
+             * never the ticked pages on their own — see `publish-selection.ts`. The
+             * baseline is doing double duty here: the adapter diffs against it, and
+             * the merge fills the unselected slots from it, so an unticked page is
+             * byte-identical to what the adapter read and produces no writes.
+             */
+            const selection = selectPagesForPublish({
+                draft: getSessionPages(scopedSession),
+                published,
+                draftSiteConfig: getSiteConfig(scopedSession),
+                publishedSiteConfig: undefined,
+                selection: {
+                    slugs: parseSelectionSlugs(body.slugs),
+                    includeSiteConfig: body.includeSiteConfig
+                }
+            });
+            if (isSelectionFailure(selection)) {
+                return jsonResponse({ ok: false, error: selection.error }, { status: 400, cors });
+            }
+            const pages = selection.pages;
             const slugs = pages.map((p) => p.slug);
             /*
              * Every exit below records what happened, because the alternative was a
@@ -759,28 +880,7 @@ export function createOrchestrator(config = {}) {
                 record(true, "Nothing written — the adapter has no onPublish");
                 return jsonResponse({ ok: true, written: false, count: pages.length, reason: "adapter has no onPublish; publish is a no-op" }, { status: 200, cors });
             }
-            const config = getSiteConfig(scopedSession);
-            /*
-             * Hand the adapter the baseline it needs to diff.
-             *
-             * `onPublish(pages)` alone is a snapshot contract, and a snapshot is not
-             * invertible: every CMS read is a projection, so writing the projection
-             * back replaces an asset reference with a URL and a document reference
-             * with a dead href. A publisher has to compare against what it read, and
-             * it cannot compare against nothing.
-             *
-             * This is the copy the bootstrap already took, not a fresh read — a
-             * second `getPages()` here is 45 sequential Sanity calls on the
-             * integration that motivated it. It used to be absent for the rest of a
-             * process's life after a restart that reloaded the draft from SQLite,
-             * which quietly disabled publishing for any adapter that refuses without
-             * a baseline; `ensure` now recovers it on the first request instead.
-             *
-             * It can still be undefined — the adapter read can fail, and baselines
-             * are evicted FIFO — so the contract is unchanged: treat undefined as
-             * "no baseline available" and never as "the site was empty".
-             */
-            const published = runtime.bootstrapCache.baselineFor(scopedSession) ?? undefined;
+            const config = selection.siteConfig;
             const context = body.assets || published
                 ? { ...(body.assets ? { assets: body.assets } : {}), ...(published ? { published } : {}) }
                 : undefined;
@@ -1164,6 +1264,67 @@ export function createOrchestrator(config = {}) {
          * The bodies are the same functions the Fastify app calls, so undo means
          * the same thing in both. See orchestrator-core/http/history-actions.ts.
          */
+        /*
+         * ---- Checks: findings, runs, and their status --------------------------
+         *
+         * Mounted here in the same commit that adds them to Fastify, rather than
+         * after somebody notices. Every route in `history-actions.ts` exists
+         * because that lesson was learned the expensive way: a UI shipped a button
+         * whose endpoint answered "not handled by createOrchestrator()".
+         */
+        if (request.method === "POST" && path === "/checks/run") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            let raw;
+            try {
+                raw = await request.json();
+            }
+            catch {
+                return jsonResponse({ error: "invalid JSON body" }, { status: 400, cors });
+            }
+            const body = (raw ?? {});
+            // The draft has to exist before it can be checked — a cold library-mode
+            // process has no pages until this runs, and an unchecked empty session
+            // would report every page as missing because there are none.
+            const scoped = scope(body.session, body.siteId);
+            await runtime.bootstrapCache.ensure(scoped, runtime.adapter, runtime.log);
+            /*
+             * `siteId` has to be the *effective* one, not whatever the caller sent.
+             *
+             * The action scopes the session itself, and it was being handed a body
+             * with no `siteId` — so a library-mode site bootstrapped the right
+             * session here and then scanned `"<session>"` instead of
+             * `"<siteId>::<session>"`. That key holds the demo seed, so the checker
+             * reported on Avocado's own sample pages: a real tri-lingual site with
+             * sixty pages got findings for `/olives` and `/blueberries`, and none of
+             * its own content was ever examined.
+             */
+            return actionResponse(await runChecksAction(withSiteId(body), runtime.log), cors);
+        }
+        if (request.method === "GET" && path === "/checks/findings") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            const query = Object.fromEntries(url.searchParams);
+            return actionResponse(await listFindingsAction(withSiteId(query), runtime.log), cors);
+        }
+        if (request.method === "GET" && path === "/checks/runs") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            const query = Object.fromEntries(url.searchParams);
+            return actionResponse(await listCheckRunsAction(withSiteId(query)), cors);
+        }
+        if (request.method === "POST" && path === "/checks/findings/status") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            let raw;
+            try {
+                raw = await request.json();
+            }
+            catch {
+                return jsonResponse({ error: "invalid JSON body" }, { status: 400, cors });
+            }
+            return actionResponse(await updateFindingAction(withSiteId((raw ?? {}))), cors);
+        }
         if (request.method === "GET" && path === "/history/status") {
             const runtime = await getRuntime();
             await runtime.ready;
@@ -1176,7 +1337,7 @@ export function createOrchestrator(config = {}) {
             const query = Object.fromEntries(url.searchParams);
             return actionResponse(historyLog(query), cors);
         }
-        if (request.method === "POST" && (path === "/history/undo" || path === "/history/redo" || path === "/history/restore")) {
+        if (request.method === "POST" && (path === "/history/undo" || path === "/history/redo" || path === "/history/restore" || path === "/history/discard")) {
             const runtime = await getRuntime();
             await runtime.ready;
             let raw;
@@ -1196,6 +1357,8 @@ export function createOrchestrator(config = {}) {
                     : null;
             if (action)
                 return actionResponse(action(body, runtime.log), cors);
+            if (path === "/history/discard")
+                return actionResponse(historyDiscardAction(body, runtime.log), cors);
             return actionResponse(historyRestoreAction(body, runtime.log), cors);
         }
         /*
@@ -1490,6 +1653,7 @@ export function createOrchestrator(config = {}) {
             const query = typeof body.query === "string" ? body.query.trim() : "";
             const page = Math.max(1, Math.trunc(Number(body.page) || 1));
             const limit = Math.min(50, Math.max(1, Math.trunc(Number(body.limit) || 20)));
+            const kind = body.kind === "file" ? "file" : "image";
             const source = typeof runtime.adapter?.getMedia === "function"
                 ? runtime.adapter.getMedia.bind(runtime.adapter)
                 : mediaSourceFromUnknown(body.config);
@@ -1499,14 +1663,101 @@ export function createOrchestrator(config = {}) {
             if (!source)
                 return jsonResponse({ error: "CMS media not configured" }, { status: 404, cors });
             try {
-                const result = await source({ query: query || undefined, page, limit });
-                return jsonResponse(result, { cors });
+                const result = await source({ query: query || undefined, page, limit, kind });
+                /*
+                 * Filter by kind on the way out as well as asking for it on the way in.
+                 *
+                 * An adapter written before documents existed ignores `kind` and
+                 * returns its images to a request for files. Trusting the response
+                 * would offer those images as PDFs. Filtering here means such an
+                 * adapter degrades to an empty document tab — which is the truth about
+                 * it — instead of to a wrong one, and costs a correct adapter nothing.
+                 */
+                const items = (result.items ?? []).filter((item) => (item.kind ?? "image") === kind);
+                /*
+                 * Whether this site takes uploads rides back on the read.
+                 *
+                 * The editor asks for the file list before it can offer a link picker,
+                 * so answering "and you may add one" here costs no round trip — and it
+                 * keeps the control's existence tied to a method that exists, rather
+                 * than to an assumption the UI made.
+                 */
+                const canUpload = typeof runtime.adapter?.uploadMedia === "function";
+                return jsonResponse({ ...result, items, canUpload }, { cors });
             }
             catch (error) {
                 runtime.log.warn?.({ err: error }, "[avocado] CMS media read failed");
                 return jsonResponse({ items: [], totalPages: 0 }, { cors });
             }
         }
+        /*
+         * Adding a document (or an image) to the site's own media library.
+         *
+         * The counterpart of `/media/cms`. The site's adapter decides where the
+         * bytes go, because only it knows: a static site writes into `public/`, a
+         * Sanity site uploads an asset and gets back a CDN URL. Deliberately NOT
+         * routed through `/image/upload`, which writes to the orchestrator's local
+         * disk — that storage loses every file on an ephemeral redeploy, and
+         * putting documents on it would spread a known defect instead of leaving it
+         * contained to the one POC route that has it.
+         *
+         * No `uploadMedia` is 404, not 500: the editor asks once and hides the
+         * control, exactly as it does for the read side.
+         */
+        if (request.method === "POST" && path === "/media/upload") {
+            const runtime = await getRuntime();
+            await runtime.ready;
+            const upload = runtime.adapter?.uploadMedia;
+            if (typeof upload !== "function") {
+                return jsonResponse({ error: "this site does not accept uploads" }, { status: 404, cors });
+            }
+            let form;
+            try {
+                form = await request.formData();
+            }
+            catch {
+                return jsonResponse({ error: "expected multipart/form-data" }, { status: 400, cors });
+            }
+            const file = form.get("file");
+            if (!(file instanceof File)) {
+                return jsonResponse({ error: "no file in the request" }, { status: 400, cors });
+            }
+            if (file.size > MEDIA_UPLOAD_MAX_BYTES) {
+                return jsonResponse({ error: `file is larger than ${Math.floor(MEDIA_UPLOAD_MAX_BYTES / 1_000_000)}MB` }, { status: 413, cors });
+            }
+            const rawKind = form.get("kind");
+            const kind = rawKind === "file" ? "file" : "image";
+            try {
+                const item = await upload.call(runtime.adapter, {
+                    // Untrusted, and passed on as such: the adapter is the only thing that
+                    // knows what a safe name is in its own store, and sanitising here
+                    // would be guessing on its behalf.
+                    filename: file.name,
+                    contentType: file.type || "",
+                    data: new Uint8Array(await file.arrayBuffer()),
+                    kind
+                });
+                /*
+                 * Drop the cached asset list, so the file somebody just added is
+                 * linkable in the same breath — by the picker, by the checker, and by
+                 * the planner's site context. Waiting out the 30-second cache would
+                 * make a fresh upload look like a broken link.
+                 */
+                invalidateSiteAssets();
+                return jsonResponse({ item }, { cors });
+            }
+            catch (error) {
+                /*
+                 * The adapter's message reaches the editor. A refusal is usually a
+                 * sentence a person needs to read — "we only accept PDFs", "a file of
+                 * that name already exists" — and swallowing it would leave the upload
+                 * control saying only that something went wrong.
+                 */
+                const reason = error instanceof Error ? error.message : String(error);
+                runtime.log.warn?.({ err: reason }, "[avocado] media upload refused");
+                return jsonResponse({ error: reason }, { status: 400, cors });
+            }
+        }
         /* The Unsplash tab of the image picker. Unconfigured answers 404, not an
          * empty result set — "no key" and "no matches" are different answers. */
         if (request.method === "GET" && path === "/unsplash/search") {

package/dist/http/audio-actions.d.ts

@@ -15,7 +15,7 @@
  * keep their own reader — Fastify streams the part (aborting mid-upload once it
  * crosses the cap), library mode reads a `File` off `request.formData()`.
  */
-import type { ActionResult } from "./history-actions.js";
+import type { ActionResult } from "./history-actions.ts";
 export type { ActionResult };
 /**
  * Formats both providers read natively.

package/dist/http/checks-actions.d.ts

@@ -0,0 +1,39 @@
+import type { CheckRunTrigger } from "../durable/types.ts";
+import type { Logger } from "../logger.ts";
+import type { ActionResult } from "./history-actions.ts";
+export type { ActionResult };
+export type ChecksScope = {
+    session?: string;
+    siteId?: string;
+};
+export type RunChecksParams = ChecksScope & {
+    /** Restrict the scan. Cross-page rules still see the whole site. */
+    slugs?: string[];
+    trigger?: CheckRunTrigger;
+};
+/** POST /checks/run — scan the session's draft and reconcile its findings. */
+export declare function runChecksAction(params: RunChecksParams, log?: Logger): Promise<ActionResult>;
+export type ListFindingsParams = ChecksScope & {
+    slug?: string;
+    agent?: string;
+    status?: string;
+    limit?: number;
+};
+/** GET /checks/findings — what is currently wrong, newest and most severe first. */
+export declare function listFindingsAction(params: ListFindingsParams, log?: Logger): Promise<ActionResult>;
+/** GET /checks/runs — the ledger, including what each run cost. */
+export declare function listCheckRunsAction(params: ChecksScope & {
+    limit?: number;
+}): Promise<ActionResult>;
+export type UpdateFindingParams = ChecksScope & {
+    id?: string;
+    status?: string;
+};
+/**
+ * POST /checks/findings/status — dismiss, snooze, or reopen one finding.
+ *
+ * `fixed` is not accepted: it is reconciliation's word, meaning "a run looked
+ * and the problem was gone". Letting a client assert it would put a finding
+ * into a state the next run immediately contradicts.
+ */
+export declare function updateFindingAction(params: UpdateFindingParams): Promise<ActionResult>;

package/dist/http/checks-actions.js

@@ -0,0 +1,122 @@
+import { scopedSessionKey } from "../state/session-state.js";
+import { getDurableStore, durableHealth } from "../durable/durable-store-singleton.js";
+import { runChecksForSession } from "../checks/session-runner.js";
+/*
+ * The checks HTTP surface, as transport-agnostic actions.
+ *
+ * Written this way from the first commit rather than as Fastify handlers,
+ * because the alternative is already documented next door: `history-actions.ts`
+ * exists because `/history/undo` was wired into Fastify only, and answered "not
+ * handled by createOrchestrator()" in a library-mode UI that shows an Undo
+ * button unconditionally. A findings panel added to one transport would be a
+ * panel that is permanently empty in the other.
+ */
+const badRequest = (error) => ({ code: 400, body: { error } });
+/**
+ * What the panel asks for when it does not say. Snoozed rows are excluded:
+ * including them is what made Snooze a button that removed a row until the next
+ * refresh put it straight back.
+ */
+const DEFAULT_STATUSES = ["open"];
+/**
+ * End any snooze whose week is up, on the way in.
+ *
+ * There is no scheduler in this process, so the wake has to hang off something
+ * that already happens; the two read paths are the only moments a snooze
+ * expiring is observable. Best-effort — a failed sweep leaves a finding hidden a
+ * little longer, which is not worth failing a request over.
+ */
+async function wakeSnoozed(scopeKey, log) {
+    try {
+        await getDurableStore().wakeSnoozedFindings(scopeKey);
+    }
+    catch (err) {
+        log?.warn({ err: String(err), scopeKey }, "waking snoozed findings failed");
+    }
+}
+/** POST /checks/run — scan the session's draft and reconcile its findings. */
+export async function runChecksAction(params, log) {
+    if (!params.session)
+        return badRequest("session is required");
+    const scopeKey = scopedSessionKey(params.session, params.siteId);
+    try {
+        await wakeSnoozed(scopeKey, log);
+        const run = await runChecksForSession({
+            scopeKey,
+            trigger: params.trigger ?? "manual",
+            ...(params.slugs?.length ? { slugs: params.slugs } : {})
+        });
+        const findings = await getDurableStore().listFindings({ scopeKey, status: DEFAULT_STATUSES });
+        // `durable` rides along on every response: findings written to the
+        // in-memory fallback look identical to durable ones until the process
+        // restarts, and a scheduled run is exactly when nobody is watching a log.
+        return { code: 200, body: { run, findings, durable: durableHealth() } };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        log?.error({ err: reason, scopeKey }, "checks run failed");
+        return { code: 500, body: { error: reason } };
+    }
+}
+const FINDING_STATUSES = ["open", "snoozed", "dismissed", "fixed"];
+function parseStatuses(raw) {
+    if (!raw)
+        return undefined;
+    const wanted = raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => FINDING_STATUSES.includes(s));
+    return wanted.length > 0 ? wanted : undefined;
+}
+/** GET /checks/findings — what is currently wrong, newest and most severe first. */
+export async function listFindingsAction(params, log) {
+    if (!params.session)
+        return badRequest("session is required");
+    const scopeKey = scopedSessionKey(params.session, params.siteId);
+    await wakeSnoozed(scopeKey, log);
+    const status = parseStatuses(params.status) ?? DEFAULT_STATUSES;
+    const limitRaw = Number(params.limit);
+    const findings = await getDurableStore().listFindings({
+        scopeKey,
+        status,
+        ...(params.slug ? { slug: params.slug } : {}),
+        ...(params.agent ? { agent: params.agent } : {}),
+        ...(Number.isFinite(limitRaw) && limitRaw > 0 ? { limit: Math.floor(limitRaw) } : {})
+    });
+    return { code: 200, body: { findings, durable: durableHealth() } };
+}
+/** GET /checks/runs — the ledger, including what each run cost. */
+export async function listCheckRunsAction(params) {
+    if (!params.session)
+        return badRequest("session is required");
+    const scopeKey = scopedSessionKey(params.session, params.siteId);
+    const limitRaw = Number(params.limit);
+    const runs = await getDurableStore().listCheckRuns(scopeKey, Number.isFinite(limitRaw) && limitRaw > 0 ? Math.floor(limitRaw) : 50);
+    return { code: 200, body: { runs } };
+}
+/**
+ * POST /checks/findings/status — dismiss, snooze, or reopen one finding.
+ *
+ * `fixed` is not accepted: it is reconciliation's word, meaning "a run looked
+ * and the problem was gone". Letting a client assert it would put a finding
+ * into a state the next run immediately contradicts.
+ */
+export async function updateFindingAction(params) {
+    if (!params.session)
+        return badRequest("session is required");
+    if (!params.id)
+        return badRequest("id is required");
+    const status = params.status;
+    if (status !== "dismissed" && status !== "snoozed" && status !== "open") {
+        return badRequest("status must be dismissed, snoozed or open");
+    }
+    const scopeKey = scopedSessionKey(params.session, params.siteId);
+    const store = getDurableStore();
+    const finding = await store.getFinding(params.id);
+    // Scope check, not politeness: findings are per-site and the id is opaque, so
+    // without this any session could dismiss any other site's finding.
+    if (!finding || finding.scopeKey !== scopeKey)
+        return { code: 404, body: { error: "finding not found" } };
+    await store.setFindingStatus(params.id, status);
+    return { code: 200, body: { finding: await store.getFinding(params.id) } };
+}

package/dist/http/history-actions.d.ts

@@ -15,7 +15,7 @@
  * status code and body to send; neither Fastify nor `Response` appears in this
  * file.
  */
-import type { Logger } from "../logger.js";
+import type { Logger } from "../logger.ts";
 /** What a caller sends. `siteId` scopes the session; both transports pass it through. */
 export type HistoryScope = {
     session?: string;
@@ -56,3 +56,46 @@ export declare function historyRestoreAction(body: {
     siteId?: string;
     targetVersion?: number;
 }, log: Logger): ActionResult;
+/** One page rolled back, and how far. */
+export type DiscardedPage = {
+    slug: string;
+    /** The earliest selected version on this page — the change being undone. */
+    fromVersion: number;
+    /** The version whose snapshot the page now holds, or null if it went away. */
+    toVersion: number | null;
+    /**
+     * Entries on this page at or after `fromVersion` that the rollback also
+     * takes out. A page has one timeline, so discarding a change in the middle
+     * of it necessarily discards what was built on top.
+     */
+    alsoDiscarded: number[];
+};
+/** A selected entry that could not be rolled back, and why. */
+export type SkippedDiscard = {
+    version: number;
+    reason: string;
+};
+/**
+ * Throw away selected changes by rolling each affected page back to the state
+ * it held immediately before the earliest change selected on it.
+ *
+ * The version log is a per-page timeline, not a stack of independent patches:
+ * an entry records the page *after* the change, so "undo this one change and
+ * keep the later ones" is not a question the stored data can answer. What it
+ * can answer is "put this page back the way it was before change N", which is
+ * what discarding means here — and it is why the response names every later
+ * entry that goes with it. The caller shows that list before asking the user
+ * to confirm; this function reports it again for whatever actually happened.
+ *
+ * Selecting several entries on one page collapses to its earliest. Selecting
+ * entries across pages rolls each page back independently — untouched pages
+ * keep their edits.
+ *
+ * Like a restore, a discard is itself an edit: the current page goes onto the
+ * undo stack first, so a discard can be undone.
+ */
+export declare function historyDiscardAction(body: {
+    session?: string;
+    siteId?: string;
+    versions?: unknown;
+}, log: Logger): ActionResult;