@avocadostudio-ai/orchestrator-core 0.3.3 → 0.5.0

package/dist/handler/create-orchestrator.js

@@ -30,7 +30,7 @@ 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";
@@ -41,6 +41,7 @@ import { formatVariationFrame, parseVariationRequest, scopeVariationSession, var
 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,7 +51,9 @@ import { createCmsBootstrapCache } from "../cms/bootstrap.js";
 import { resolveCapabilities } from "../cms/adapter.js";
 import { mediaSourceFromUnknown } from "../cms/media-sources.js";
 import { isAccessGateEnabled, mintAccessToken, verifyAccessPassword } from "../http/access-tokens.js";
+import { declareLibraryMount, observeLibraryMount } from "./library-mount.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",
@@ -131,16 +134,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
@@ -224,6 +281,7 @@ const SUPPORTED_ROUTES = [
     "POST /history/undo",
     "POST /history/redo",
     "POST /history/restore",
+    "POST /history/discard",
     "GET /whoami",
     "GET /blocks/manifest",
     "GET /sites",
@@ -236,6 +294,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",
@@ -319,6 +378,15 @@ export function createOrchestrator(config = {}) {
     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
@@ -349,16 +417,40 @@ export function createOrchestrator(config = {}) {
     const gateLogger = config.logger ?? consoleLogger();
     {
         const resolved = resolveAuth(config.auth);
-        const line = `[auth] library mode: ${resolved.mode} — ${resolved.reason}`;
+        /*
+         * `next build` evaluates this route module to collect its exports, with
+         * `NODE_ENV=production` and none of the deployment's environment. With no
+         * credential configured the gate resolves to `closed` and this printed a
+         * red `[error]` in the middle of an otherwise clean, *successful* build —
+         * about a request that is not being served, on a machine that is not the
+         * deployment.
+         *
+         * It is still the only notice anyone gets of a real problem, so it is not
+         * silenced: during a build it is a warning that says which state it is
+         * describing. At runtime it stays an error, because then it means every
+         * request is actually being refused.
+         */
+        const building = process.env.NEXT_PHASE === "phase-production-build";
+        const line = building
+            ? `[auth] library mode: ${resolved.mode} — ${resolved.reason} ` +
+                `(evaluated during the build; set ACCESS_PASSWORD_HASH or ` +
+                `ORCHESTRATOR_ACCESS_TOKEN in the deployment's environment, not here)`
+            : `[auth] library mode: ${resolved.mode} — ${resolved.reason}`;
         if (resolved.mode === "closed")
-            gateLogger.error(line);
+            building ? gateLogger.warn(line) : gateLogger.error(line);
         else if (resolved.mode === "open-dev")
             gateLogger.warn(line);
         else
             gateLogger.info(line);
     }
+    // Tell the SDK's draft fetch where we are, so it stops defaulting to the
+    // standalone orchestrator on :4200 that a library-mode site does not run.
+    // See `library-mount.ts` for why this is not simply a config value.
+    if (config.previewUrl)
+        declareLibraryMount(`${config.previewUrl.replace(/\/+$/, "")}${basePath}`);
     const handler = async function handler(request) {
         const url = new URL(request.url);
+        observeLibraryMount(`${url.origin}${basePath}`);
         const path = stripBasePath(url.pathname, basePath);
         const cors = corsHeadersFor(request, config);
         if (request.method === "OPTIONS") {
@@ -712,7 +804,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
@@ -772,28 +905,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;
@@ -1201,19 +1313,30 @@ export function createOrchestrator(config = {}) {
             // 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);
-            return actionResponse(await runChecksAction(body, runtime.log), cors);
+            /*
+             * `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(query, runtime.log), cors);
+            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(query), cors);
+            return actionResponse(await listCheckRunsAction(withSiteId(query)), cors);
         }
         if (request.method === "POST" && path === "/checks/findings/status") {
             const runtime = await getRuntime();
@@ -1225,7 +1348,7 @@ export function createOrchestrator(config = {}) {
             catch {
                 return jsonResponse({ error: "invalid JSON body" }, { status: 400, cors });
             }
-            return actionResponse(await updateFindingAction((raw ?? {})), cors);
+            return actionResponse(await updateFindingAction(withSiteId((raw ?? {}))), cors);
         }
         if (request.method === "GET" && path === "/history/status") {
             const runtime = await getRuntime();
@@ -1239,7 +1362,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;
@@ -1259,6 +1382,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);
         }
         /*
@@ -1553,6 +1678,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);
@@ -1562,14 +1688,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/handler/library-mount.d.ts

@@ -0,0 +1,6 @@
+export declare const LIBRARY_MOUNT_KEY = "__avocado_library_mount__";
+/** Called at construction, from `previewUrl` + `basePath`. */
+export declare function declareLibraryMount(url: string): void;
+/** Called on each request, from the URL the runtime actually received. */
+export declare function observeLibraryMount(url: string): void;
+export declare function getLibraryMount(): string | null;

package/dist/handler/library-mount.js

@@ -0,0 +1,45 @@
+/*
+ * Where this process's own orchestrator is mounted, if it has one.
+ *
+ * In library mode the orchestrator is a route inside the site's own Next app,
+ * and the SDK's draft fetch had no way to know that: with `ORCHESTRATOR_URL`
+ * unset it fell back to `http://127.0.0.1:4200`, the *standalone* orchestrator,
+ * which a library-mode site by definition does not run. The failure is silent
+ * when nothing is listening there (the draft fetch fails, the preview falls back
+ * to published content, and every edit appears to do nothing) and worse when
+ * something is — the fetch succeeds against a foreign process and the preview
+ * renders another project's pages. Anyone integrating is likely to have a :4200
+ * up, because that is what the standalone stack runs on.
+ *
+ * So the handler records its own address, and `getOrchestratorUrl()` in the SDK
+ * reads it through the same `globalThis` key. The key is a string on both sides
+ * rather than an import because `@avocadostudio-ai/orchestrator-core` is an
+ * *optional* peer of the SDK — a site that is not in library mode does not have
+ * it installed, and neither package may require the other.
+ *
+ * Two sources, in order of trust:
+ *   - the origin of a real request this handler served, which cannot be wrong;
+ *   - `config.previewUrl + basePath` at construction time, which is available
+ *     before any request and is what covers a preview page that renders before
+ *     the orchestrator route module has ever been evaluated.
+ */
+export const LIBRARY_MOUNT_KEY = "__avocado_library_mount__";
+function slot() {
+    const g = globalThis;
+    return g[LIBRARY_MOUNT_KEY] ?? (g[LIBRARY_MOUNT_KEY] = {});
+}
+/** Called at construction, from `previewUrl` + `basePath`. */
+export function declareLibraryMount(url) {
+    slot().declared = url.replace(/\/+$/, "");
+}
+/** Called on each request, from the URL the runtime actually received. */
+export function observeLibraryMount(url) {
+    const s = slot();
+    const next = url.replace(/\/+$/, "");
+    if (s.observed !== next)
+        s.observed = next;
+}
+export function getLibraryMount() {
+    const s = slot();
+    return s.observed ?? s.declared ?? null;
+}

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

@@ -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;

package/dist/http/history-actions.js

@@ -167,3 +167,125 @@ export function historyRestoreAction(body, log) {
         }
     };
 }
+/**
+ * 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 function historyDiscardAction(body, log) {
+    if (!body.session)
+        return badRequest("session is required");
+    const requested = Array.isArray(body.versions)
+        ? Array.from(new Set(body.versions.filter((v) => typeof v === "number" && Number.isFinite(v))))
+        : [];
+    if (requested.length === 0)
+        return badRequest("versions must be a non-empty array of version numbers");
+    const session = scopedSessionKey(body.session, body.siteId);
+    const entries = versionLog.get(session) ?? [];
+    const byVersion = new Map(entries.map((entry) => [entry.version, entry]));
+    const skipped = [];
+    /*
+     * Collapse to one rollback per page. A selection of three entries on the
+     * same page is one rollback to before the earliest of them; running three
+     * would have the second and third restore snapshots the first already
+     * invalidated.
+     */
+    const earliestBySlug = new Map();
+    for (const version of requested) {
+        const entry = byVersion.get(version);
+        if (!entry) {
+            skipped.push({ version, reason: "not in this session's version log" });
+            continue;
+        }
+        const current = earliestBySlug.get(entry.slug);
+        if (current === undefined || version < current)
+            earliestBySlug.set(entry.slug, version);
+    }
+    const discarded = [];
+    let previewVersion = versions.get(session) ?? 0;
+    let navigateToSlug;
+    for (const [slug, fromVersion] of earliestBySlug) {
+        /*
+         * The state before `fromVersion` is the snapshot of the newest earlier
+         * entry on the same page. An entry with no snapshot is a legacy row that
+         * cannot restore anything, so it does not count as the prior state.
+         */
+        const prior = entries
+            .filter((entry) => entry.slug === slug && entry.version < fromVersion && entry.snapshot !== undefined)
+            .at(-1);
+        if (!prior) {
+            /*
+             * Nothing recorded before this change — the log was capped, or this is
+             * the page's first entry. Guessing would mean inventing a state the
+             * page never had, so the entry stays and the caller is told why.
+             */
+            skipped.push({
+                version: fromVersion,
+                reason: "no recorded page state before this change"
+            });
+            continue;
+        }
+        const alsoDiscarded = entries
+            .filter((entry) => entry.slug === slug && entry.version >= fromVersion)
+            .map((entry) => entry.version)
+            .filter((version) => version !== fromVersion);
+        // Filtered above, so this only maps the impossible `undefined` onto the
+        // `null` that means "the page did not exist at this version".
+        const snapshot = prior.snapshot ?? null;
+        // pushUndo also clears redo, which is right: a discard starts a new branch.
+        pushUndo(session, slug, getPage(session, slug));
+        if (snapshot === null)
+            removePage(session, slug);
+        else
+            setPage(session, structuredClone(snapshot));
+        previewVersion = bumpVersion(session);
+        const count = alsoDiscarded.length + 1;
+        pushVersionEntry(session, {
+            version: previewVersion,
+            slug,
+            summary: `Discarded ${count} change${count === 1 ? "" : "s"} — back to v${prior.version}`,
+            opTypes: [],
+            opCount: 0,
+            source: "restore",
+            snapshot: snapshot === null ? null : structuredClone(snapshot)
+        });
+        discarded.push({ slug, fromVersion, toVersion: snapshot === null ? null : prior.version, alsoDiscarded });
+        navigateToSlug = slug;
+    }
+    if (discarded.length === 0) {
+        return {
+            code: 400,
+            body: { error: "nothing could be discarded", skipped }
+        };
+    }
+    schedulePersistState(log);
+    const touched = discarded[discarded.length - 1].slug;
+    const undoList = getHistoryMap(historyUndo, session).get(touched) ?? [];
+    const redoList = getHistoryMap(historyRedo, session).get(touched) ?? [];
+    return {
+        code: 200,
+        body: {
+            status: "applied",
+            previewVersion,
+            discarded,
+            skipped,
+            ...(navigateToSlug ? { navigateToSlug } : {}),
+            canUndo: undoList.length > 0,
+            canRedo: redoList.length > 0
+        }
+    };
+}