caracms 0.8.0 → 0.8.2

package/src/editor/types.ts

@@ -26,6 +26,16 @@ export interface DocRef {
 /** `pages/services/branding`: a document's id, for keys, storage and the Recent list. */
 export const docId = (ref: DocRef): string => `${ref.collection}/${ref.path}`;
 
+/**
+ * Whether the editor opens a listed document. One whose only trouble is a missing title
+ * does (caracms-cloud adversarial review, finding 15): it's kept off the site and marked,
+ * and opening it is how the title goes back. Invalid JSON and a nested index.json don't.
+ */
+export const opensInEditor = (doc: Pick<DocumentEntry, 'warning'>): boolean => !doc.warning || doc.warning.code === 'no-title';
+
+/** The screen reader's words for a listed document's warning mark. */
+export const warnedWords = (doc: Pick<DocumentEntry, 'warning'>): string => (doc.warning?.code === 'no-title' ? ', needs a title' : ", can't be opened");
+
 export const sameDoc = (a: DocRef | null | undefined, b: DocRef | null | undefined): boolean =>
 	!!a && !!b && a.collection === b.collection && a.path === b.path;
 
@@ -297,6 +307,8 @@ export const ENDPOINTS = {
 	history: '/_caracms/history',
 	tryAgain: '/_caracms/try-again',
 	notice: '/_caracms/notice',
+	// Discard changes (live mode only): one document back to what's live.
+	discard: '/_caracms/discard',
 	// M6 Decision 9: the inbox, both modes (forms/inbox.ts has each route).
 	submissions: '/_caracms/submissions',
 } as const;
@@ -342,6 +354,42 @@ export interface LastChange {
 	version: string | null;
 	/** ISO. */
 	at: string | null;
+	/**
+	 * Discard changes: someone put the document back to what's live (within the last week),
+	 * and when. Edits held in a browser from before then are dropped, not re-sent (keeper.ts → verdict).
+	 */
+	discarded?: { by: Person; at: string } | null;
+}
+
+/**
+ * POST /_caracms/discard `{ file }` (live mode only): put one waiting document back to what's
+ * live. A changed one reads as `main` has it, a new one is removed, a deleted one comes back,
+ * a moved one goes back to its old address (its file `movedBack`). `{ file, seen: true }`: this
+ * tab has let go of its copy of a document someone discarded (`open.discarded`).
+ */
+export interface DiscardRequest {
+	file: string;
+	seen?: true;
+}
+
+export interface DiscardResponse {
+	ok: true;
+	file: string;
+	/** What it was: `changed`, `new` (now removed) or `deleted` (now back). */
+	change: WaitingChange;
+	/** Every file put back as `main` has it. */
+	files: string[];
+	/** A moved document: where it is again (its collection and path), else null. */
+	movedBack: { collection: string; path: string; file: string } | null;
+}
+
+/**
+ * Discard's refusals: `not-waiting` (404: nothing to discard), `locked` (409: someone is
+ * editing it now), `publishing` (409), `busy` (409: the sweep is busy on another server),
+ * `held-move` (409: it moved with the page that holds it), `bad-request`/`bad-path` (400).
+ */
+export interface DiscardRefusal extends ApiError {
+	code: 'not-waiting' | 'locked' | 'publishing' | 'busy' | 'held-move' | 'swap' | 'bad-request' | 'bad-path' | 'no-tab' | 'signed-out' | 'unavailable';
 }
 
 /** 401 from any editor API in live mode with no session (Phase 3's guard, Decision 11). */
@@ -414,6 +462,11 @@ export interface WaitingView {
 	movedFrom?: string;
 	/** With `movedFrom`: Site Settings' redirects send visitors from the old address here (the editor may have taken it out). */
 	movedRedirect?: boolean;
+	/**
+	 * caracms-cloud adversarial review, finding 15: why Publish will leave it waiting ("its title
+	 * is empty"), read from the document as it will publish; absent when it will go out.
+	 */
+	heldBack?: string;
 }
 
 /**
@@ -444,7 +497,9 @@ export type NoticeView =
 	/** "Home was also changed outside the editor. Your draft was kept; check it before publishing" (Decision 7). */
 	| { id: string; kind: 'draft-kept'; file: string; title: string }
 	/** "Aoife published Home as it stood at 14:20" (Decision 10), for the people who had it open. */
-	| { id: string; kind: 'published-as-it-stood'; file: string; title: string; by: Person; at: string };
+	| { id: string; kind: 'published-as-it-stood'; file: string; title: string; by: Person; at: string }
+	/** "Aoife discarded the unpublished changes to About" (Discard changes), for the people who had edits in it or had it open. */
+	| { id: string; kind: 'discarded'; file: string; title: string; by: Person; at: string };
 
 export interface PublishRecordView {
 	commit: string;
@@ -493,6 +548,12 @@ export interface StatusResponse {
 		 * who deleted it and when, when that's known (`by` null: not known). Null while it exists.
 		 */
 		deleted: { by: Person | null; at: string | null } | null;
+		/**
+		 * Discard changes: someone put the document back to what's live while this tab had it
+		 * (open, or edits in it), so this tab's copy is stale: it lets go (`POST discard { file,
+		 * seen }`) and reads it again. Its writes are refused (409 `discarded`) until then.
+		 */
+		discarded?: { by: Person; at: string } | null;
 	} | null;
 	waiting: WaitingView[];
 	locks: LockView[];
@@ -505,9 +566,33 @@ export interface StatusResponse {
 	 * missing permission, or a token expiring within 14 days. `message` names the fix,
 	 * for the developer it's forwarded to. Null when nothing is wrong. `cloud` (caracms-cloud
 	 * M2 Decision 14): CaraCMS Cloud refused a token; `message` is the cloud's sentence and
-	 * `link` the install link it names, if any, which the note shows as a link.
+	 * `link` the install link it names, if any, which the note shows as a link. `renamed`
+	 * (caracms-cloud adversarial review, finding 7) is information, not a problem: the repo
+	 * was renamed or transferred on GitHub and work carries on under the new name, shown
+	 * until the server restarts.
+	 */
+	githubAccess: { kind: 'refused' | 'permission' | 'expiring' | 'cloud' | 'renamed'; title: string; message: string; link?: string | null } | null;
+	/**
+	 * caracms-cloud adversarial review, finding 4: edits are waiting in Redis and the draft
+	 * commits that should carry them to GitHub have failed several times in a row (git.ts →
+	 * `COMMIT_TROUBLE_AFTER`). The save bar stops saying Kept and says so; `message` is the
+	 * whole sentence. Null otherwise, and again once a commit goes through. (Absent from an
+	 * older server: read it as null.)
+	 */
+	commitTrouble?: { since: string; failures: number; message: string } | null;
+	/**
+	 * Finding 5: a start found the `drafts` branch gone and could only make it again from
+	 * `main`, so what it held since the last Publish is gone. `commit` is its last recorded
+	 * head (null: none was recorded). Shown to everyone for a week, or until the next Publish.
+	 */
+	draftsLost?: { title: string; message: string; commit: string | null; at: string } | null;
+	/**
+	 * caracms-cloud adversarial review, force-push note: `main` no longer has the last
+	 * Publish's commit (`publish`), so its history was rewritten, and what was rolled back is
+	 * waiting again. Shown to everyone until the next Publish, or once nothing is waiting.
+	 * (Absent from an older server: read it as null.)
 	 */
-	githubAccess: { kind: 'refused' | 'permission' | 'expiring' | 'cloud'; title: string; message: string; link?: string | null } | null;
+	mainRolledBack?: { title: string; message: string; publish: string; main: string; at: string } | null;
 	/**
 	 * The brand as committed in Site Settings (M5a Decision 10: read from `drafts`, never
 	 * an autosave), so the chrome picks up a change on the next poll with no reload.
@@ -534,8 +619,11 @@ export interface LockResponse {
 
 /** POST /_caracms/publish. */
 export interface PublishResponse {
-	result: 'published' | 'nothing-waiting' | 'joined';
+	/** `held-back` (finding 15): everything waiting would break the reader, so nothing was published. */
+	result: 'published' | 'nothing-waiting' | 'joined' | 'held-back';
 	publish: PublishView;
+	/** Finding 15: what was left waiting, and why ("its title is empty"); absent or empty when nothing was. */
+	held?: { file: string; title: string; reason: string }[];
 }
 
 export interface HistoryEntryView {

package/src/forms/cloud-store.ts

@@ -39,7 +39,10 @@ function submissionOf(value: unknown, what: string): StoredSubmission {
 	if (!s || typeof s !== 'object' || !isSubmissionId(s.id) || typeof s.form !== 'string' || typeof s.receivedAt !== 'string' || !s.fields || typeof s.fields !== 'object') {
 		throw malformed(what);
 	}
-	return { ...s, v: 1, readAt: typeof s.readAt === 'string' ? s.readAt : null };
+	const { filesNote, ...rest } = s;
+	// The attachments-not-kept sentence (caracms-cloud's attachment limit): kept only as a non-empty string.
+	const note = typeof filesNote === 'string' && filesNote.trim() ? { filesNote: filesNote.trim() } : {};
+	return { ...rest, v: 1, readAt: typeof s.readAt === 'string' ? s.readAt : null, ...note };
 }
 
 export function cloudStore(connection: CloudConnection): SubmissionStore {

package/src/forms/inbox.ts

@@ -24,7 +24,8 @@
 import type { ResolvedSite } from '../config.ts';
 import { checkOrigin, WriteRefused } from '../editor/server/write.ts';
 import { FILE_TYPES, isSubmissionId, senderName, shownFileName, submissionSnippet, type ResolvedFormField } from './rules.ts';
-import { fileExtension, readSubmissionsConfig, submissionStore, type StoredSubmission, type SubmissionStore } from './store.ts';
+import { fileExtension, readSubmissionsConfig, submissionStore, type EmailOutcome, type StoredSubmission, type SubmissionStore } from './store.ts';
+import { readCappedText } from '../body.ts';
 
 type Env = Record<string, string | undefined>;
 
@@ -48,8 +49,10 @@ export interface SubmissionRow {
 	readAt: string | null;
 	/** How many files came with it. */
 	files: number;
-	/** The email's outcome, or null when it's unknown (the server died between storing and recording). */
-	emailStatus: 'sent' | 'failed' | 'skipped' | null;
+	/** The email's outcome (`held`: the cloud's, behind the site's daily limit), or null when it's unknown (the server died between storing and recording). */
+	emailStatus: EmailOutcome['status'] | null;
+	/** True when the cloud didn't keep its attachments (`StoredSubmission.filesNote`); absent otherwise. */
+	filesNotKept?: true;
 }
 
 export interface SubmissionsListResponse {
@@ -103,6 +106,7 @@ export function rowOf(site: Pick<ResolvedSite, 'forms'>, s: StoredSubmission): S
 		readAt: s.readAt ?? null,
 		files: s.files?.length ?? 0,
 		emailStatus: s.email?.status ?? null,
+		...(s.filesNote ? { filesNotKept: true as const } : {}),
 	};
 }
 
@@ -125,8 +129,9 @@ export function attachmentHeader(name: string): string {
 export const downloadType = (key: string): string => FILE_TYPES[fileExtension(key)]?.[0] ?? 'application/octet-stream';
 
 async function readJsonBody(request: Request): Promise<Record<string, unknown>> {
-	const text = await request.text().catch(() => '');
-	if (text.length > 4096) return {};
+	// caracms-cloud adversarial review, finding 10: 4 KB counted as it's read, never the whole body first.
+	const text = await readCappedText(request, 4096).catch(() => '');
+	if (text === null) return {};
 	try {
 		const value = JSON.parse(text || '{}') as unknown;
 		return value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : {};

package/src/forms/store.ts

@@ -53,10 +53,16 @@ export interface StoredFile {
 }
 
 export interface EmailOutcome {
-	status: 'sent' | 'failed' | 'skipped';
+	/**
+	 * `held` is only ever the cloud's answer (caracms-cloud adversarial review, finding 20): the
+	 * email waits behind the site's daily limit and goes out when it's raised or the next UTC day.
+	 * It's never stored by the package's own stores.
+	 */
+	status: 'sent' | 'failed' | 'skipped' | 'held';
+	/** When it was sent, failed or was skipped; for `held`, when it was held. */
 	at: string;
 	to: string[];
-	/** Resend's message on failure, or why it was skipped. */
+	/** Resend's message on failure, why it was skipped, or the cloud's sentence for a held one. */
 	error?: string;
 }
 
@@ -76,6 +82,12 @@ export interface StoredSubmission {
 	readAt: string | null;
 	/** Absent: not attempted yet, or the server died mid-way (the inbox says "unknown"). */
 	email?: EmailOutcome;
+	/**
+	 * Only ever the cloud's: why the attachments that came with it weren't kept (the site
+	 * reached its daily attachment limit in CaraCMS Cloud), as a sentence the inbox shows in
+	 * place of "No files". Absent otherwise.
+	 */
+	filesNote?: string;
 }
 
 export interface NewFile {

package/src/index.ts

@@ -139,6 +139,7 @@ export const EDITOR_ROUTES = [
 	{ pattern: '/_caracms/history', entrypoint: 'editor/routes/history.ts' },
 	{ pattern: '/_caracms/try-again', entrypoint: 'editor/routes/try-again.ts' },
 	{ pattern: '/_caracms/notice', entrypoint: 'editor/routes/notice.ts' },
+	{ pattern: '/_caracms/discard', entrypoint: 'editor/routes/discard.ts' },
 	// M6 Decision 9: the inbox, both modes (the guard's prefix rule covers it in live mode).
 	{ pattern: '/_caracms/submissions/[...path]', entrypoint: 'editor/routes/submissions.ts' },
 ] as const;
@@ -281,18 +282,27 @@ export function trustedDomains(
 	return domains;
 }
 
-/**
- * The browser side of the editor imports React and idiomorph from the package.
- * Pre-bundled up front (dev only), so Vite doesn't discover them on the first
- * visit to /admin and reload the page to optimise them (a flicker, M2 Decision 9).
- */
 /** Vite's cache for every command but `astro dev`, apart from dev's `node_modules/.vite` (see its use). Relative to the site's root. */
 export const BUILD_VITE_CACHE = 'node_modules/.vite-caracms-build';
 
+/**
+ * Every bare import the package's browser code makes (the editor, and the site's own
+ * components such as the video player), pre-bundled up front in dev. Two reasons:
+ * - Vite doesn't discover them on the first visit to /admin and reload the page to
+ *   optimise them (a flicker, M2 Decision 9).
+ * - Installed from the registry (npm or pnpm), the package sits in the site's node_modules,
+ *   and Vite serves a bare import from it that isn't listed here as the dependency's raw
+ *   file. For a CommonJS one (react-dom) the browser refuses the module and the editor never
+ *   starts (caracms-cloud adversarial review, finding 12). The workspace's linked copy hides
+ *   this, so any new bare import in browser code goes here; test/pack-install.release.test.ts
+ *   checks it in a real browser.
+ */
 export const EDITOR_CLIENT_DEPS = [
 	'caracms > react',
 	'caracms > react/jsx-runtime',
 	'caracms > react/jsx-dev-runtime',
+	// Arrange pages' createPortal (arrange/ArrangeStage.tsx). react-dom's root is CommonJS.
+	'caracms > react-dom',
 	'caracms > react-dom/client',
 	'caracms > idiomorph',
 	// M5a: the rich-text field's editor (Tiptap on ProseMirror), browser only.
@@ -306,16 +316,21 @@ export const EDITOR_CLIENT_DEPS = [
 	'caracms > @tiptap/pm/view',
 	// M5b: a clip's upload straight to Mux, imported on the first one (client/media/store.ts).
 	'caracms > @mux/upchunk',
+	// The site's video player, imported on the first click on Play (components/media-player.ts).
+	// ESM, so served raw it still loaded, but unbundled, and one CommonJS file in its tree would break it.
+	'caracms > @mux/mux-player',
 	// The date field's calendar (pre-M7 polish).
 	'caracms > react-day-picker',
 ];
 
 /**
- * The variables M5b Decision 5 names: the media pipeline's and Mux's. Only these are
- * taken from the site's env files (copyMediaEnv); everything else in `.env` (the
- * GitHub App, live mode) is left to the process's own environment, as before.
+ * The variables M5b Decision 5 names: the media pipeline's and Mux's, and the cloud key,
+ * which is both on a cloud site. Only these are taken from the site's env files
+ * (copyMediaEnv); everything else in `.env` (the GitHub App, live mode) is left to the
+ * process's own environment, as before.
  */
 export const MEDIA_ENV_NAMES = [
+	'CARACMS_CLOUD_KEY',
 	'CARACMS_MEDIA',
 	'CARACMS_MEDIA_URL',
 	'IMGPROXY_KEY',

package/src/live/auth/login.ts

@@ -54,6 +54,7 @@ import {
 	type PageAssets,
 	type SafeHtml,
 } from './views.ts';
+import { readCappedText } from '../../body.ts';
 
 export const CONFIRM_PATH = `${LOGIN_PATH}/confirm`;
 export const SIGNOUT_PATH = `${LOGIN_PATH}/signout`;
@@ -80,9 +81,9 @@ const BASE_HEADERS = {
 class BodyTooLarge extends Error {}
 
 async function readBody(request: Request): Promise<string> {
-	if (Number(request.headers.get('content-length') ?? 0) > MAX_BODY_BYTES) throw new BodyTooLarge();
-	const text = await request.text();
-	if (Buffer.byteLength(text) > MAX_BODY_BYTES) throw new BodyTooLarge();
+	// caracms-cloud adversarial review, finding 10: counted as it's read, so a chunked body stops at the cap too.
+	const text = await readCappedText(request, MAX_BODY_BYTES);
+	if (text === null) throw new BodyTooLarge();
 	return text;
 }
 

package/src/live/auth/views.ts

@@ -313,8 +313,15 @@ export function emailView(input: { next: string; value?: string; invalid?: strin
  * rate-limited, send failed). It repeats the address typed, which the person already
  * knows, and says nothing about it.
  */
+/**
+ * caracms-cloud adversarial review, editor wording note (B3): the same answer for every
+ * address, so it never says whether one has access; this line tells someone who mistyped
+ * theirs, or wasn't invited, why nothing may come.
+ */
+export const SENT_BY_INVITATION = 'Sign-in is by invitation. If nothing arrives in a few minutes, check the address or ask whoever invited you.';
+
 export function sentView(input: { email: string; next: string; again: boolean; backupEnabled: boolean }): SafeHtml {
-	return html`<section class="si-card">${input.again ? html`<p class="notice ok" role="status">${ic('check', 'i-sm')}Sent again.</p>` : ''}<h1>Check your email</h1><p>If <strong>${input.email}</strong> can sign in, a link is on its way. It expires in 15 minutes.</p><p class="fine">Not there? Check spam, or send again.</p><div class="row-acts"><form method="post" action="${LOGIN_PATH}"><input type="hidden" name="email" value="${input.email}"><input type="hidden" name="next" value="${input.next}"><input type="hidden" name="again" value="1"><button class="btn" type="submit">Send again</button></form><a class="linkbtn" href="${loginHref({}, input.next)}">Use a different address</a></div></section>${input.backupEnabled ? backupLink(input.next) : ''}`;
+	return html`<section class="si-card">${input.again ? html`<p class="notice ok" role="status">${ic('check', 'i-sm')}Sent again.</p>` : ''}<h1>Check your email</h1><p>If <strong>${input.email}</strong> can sign in, a link is on its way. It expires in 15 minutes.</p><p class="fine">${SENT_BY_INVITATION}</p><p class="fine">Not there? Check spam, or send again.</p><div class="row-acts"><form method="post" action="${LOGIN_PATH}"><input type="hidden" name="email" value="${input.email}"><input type="hidden" name="next" value="${input.next}"><input type="hidden" name="again" value="1"><button class="btn" type="submit">Send again</button></form><a class="linkbtn" href="${loginHref({}, input.next)}">Use a different address</a></div></section>${input.backupEnabled ? backupLink(input.next) : ''}`;
 }
 
 /** Runs-anywhere Decision 7: the site was opened at an address that isn't its own (request.ts → `addressNotice`). */

package/src/live/autosaves.ts

@@ -4,8 +4,11 @@
  * - **`caracms:autosave:<file>`**: the whole document as the tab last sent it, with the
  *   base it was edited from, its text (`applyEdits(base, document)`), its editor and
  *   tab, and two times for the sweep: the first write since the last commit (the
- *   five-minute cap) and the newest write (the idle time). Expires after a week, as a
- *   backstop (`autosaveTtlMs`).
+ *   five-minute cap) and the newest write (the idle time). **It never expires**: it's an
+ *   edit that hasn't reached GitHub, so while commits fail (a lost token, an uninstalled
+ *   App) it waits for the sweep however long that takes (caracms-cloud adversarial review,
+ *   finding 4). Once committed it's deleted, and what's left of it, the committed record
+ *   below, expires a week later as before.
  * - **`caracms:committed:<file>`**: what the sweep last committed from a tab's editing
  *   session (its tab, its base, and the text it committed). The next commit from the
  *   same session merges against that text, not the session's first base, so the
@@ -40,6 +43,13 @@
  * moving it back to where it was drops the record, as does deleting it. A record only
  * counts while its old file is gone and its new file is there (`movesIn`, git.ts).
  *
+ * **Discards** (Discard changes) ride on **`caracms:changed:<file>`** (`ChangeRecord.discard`),
+ * which every poll on the document and every write to it already read, so a discard costs
+ * them no command of their own: who put the document back to what's live, when, and the tabs
+ * that had it open or were editing it then. Those tabs' writes are refused until each says it
+ * has let go of its copy (`ackDiscard`), so a tab that hasn't heard yet can't bring the
+ * discarded edits back. A write carries the discard forward for a week (`carryDiscard`).
+ *
  * Paths are site-relative (`content/pages/index.json`). Values are JSON text.
  *
  * **The status cache** (status-cache.ts, Redis diet Decision 2): every write here of a
@@ -110,6 +120,16 @@ export interface ChangeRecord {
 	at: string;
 	/** M5a: this change deleted the document (`by` deleted it). */
 	gone?: boolean;
+	/** Discard changes: the last time someone put the document back to what's live (see the header). */
+	discard?: DiscardRecord;
+}
+
+/** A document put back to what's live (Discard changes): `tabs` are the tabs whose copies are stale until they let go. */
+export interface DiscardRecord {
+	by: Person;
+	/** ISO. */
+	at: string;
+	tabs: string[];
 }
 
 /** A value with the raw text it was read as, for compare-and-swap. */
@@ -169,11 +189,9 @@ export class Autosaves {
 	readonly changedKey = (file: string) => `${this.prefix}changed:${file}`;
 	readonly movesKey = () => movesKey(this.prefix);
 
-	/** A compare-and-swap (or delete) on an autosave key, and the status cache told what came of it. */
+	/** A compare-and-swap (or delete) on an autosave key, and the status cache told what came of it. No expiry: a SET without PX also clears one an older version left. */
 	private async swap(key: string, expected: string | null, raw: string | null): Promise<boolean> {
-		const ok = await landed(this.cache, key, () =>
-			raw === null ? this.redis.compareAndDelete(key, expected!) : this.redis.compareAndSet(key, expected, raw, { px: this.timings.autosaveTtlMs }),
-		);
+		const ok = await landed(this.cache, key, () => (raw === null ? this.redis.compareAndDelete(key, expected!) : this.redis.compareAndSet(key, expected, raw)));
 		if (ok) this.cache?.string(key, raw);
 		else this.cache?.drop(key);
 		return ok;
@@ -212,11 +230,81 @@ export class Autosaves {
 		return this.swap(this.key(read.value.file), read.raw, null);
 	}
 
+	/**
+	 * An autosave written by caracms 0.8.0 or before, with the week's expiry it set: written
+	 * again as it is, with none (the sweep's startup check). Only if it's still what was read.
+	 */
+	async keepForever(read: Read<Autosave>): Promise<boolean> {
+		if ((await this.redis.pttl(this.key(read.value.file))) < 0) return false;
+		return this.swap(this.key(read.value.file), read.raw, read.raw);
+	}
+
 	/** Replace it only if it's still what was read. */
 	replaceIf(read: Read<Autosave>, next: Autosave): Promise<boolean> {
 		return this.swap(this.key(next.file), read.raw, JSON.stringify(next));
 	}
 
+	/**
+	 * Discard changes: delete the autosave whatever it holds (a newer write is deleted too),
+	 * returning each one deleted, so the caller knows whose tabs had it.
+	 */
+	async removeAll(file: string): Promise<Autosave[]> {
+		const gone: Autosave[] = [];
+		for (let attempt = 0; attempt < 8; attempt++) {
+			const read = await this.get(file);
+			if (!read) return gone;
+			if (await this.removeIf(read)) gone.push(read.value);
+		}
+		throw new Error(`caracms: the autosave for ${file} kept changing under the discard.`);
+	}
+
+	/** Discard changes: the session's committed record goes with the edit it recorded. */
+	async forgetCommitted(file: string): Promise<void> {
+		await this.redis.del(this.committedKey(file));
+	}
+
+	/** Discard changes: every move record from or to these files, and their live addresses, go. */
+	async forgetMovesOf(files: readonly string[]): Promise<void> {
+		const key = movesKey(this.prefix);
+		const all = Object.entries(await this.redis.hgetall(key));
+		const drop = all
+			.filter(([k, v]) => (k.startsWith(ADDRESS_FIELD) ? files.includes(k.slice(ADDRESS_FIELD.length)) : files.includes(k) || files.includes(v)))
+			.map(([k]) => k);
+		if (drop.length === 0) return;
+		await landed(this.cache, key, () => this.redis.hdel(key, ...drop));
+		this.cache?.hash(key, {}, drop);
+	}
+
+	/** The autosave and the change record in one MGET (the write route reads both: Discard changes costs it no command). */
+	async getWithChange(file: string): Promise<[Read<Autosave> | null, ChangeRecord | null]> {
+		const [raw, changed] = await this.redis.mget([this.key(file), this.changedKey(file)]);
+		const value = parse<Autosave>(raw ?? null);
+		return [raw !== null && raw !== undefined && value ? { raw, value } : null, Autosaves.changedFrom(changed ?? null)];
+	}
+
+	/** The discard a write should keep on the change record it makes: the one there, while under a week old. */
+	carryDiscard(record: ChangeRecord | null): Pick<ChangeRecord, 'discard'> {
+		const d = record?.discard;
+		return d && this.now() - Date.parse(d.at) < this.timings.autosaveTtlMs ? { discard: d } : {};
+	}
+
+	/** A tab has let go of its copy of a discarded document: its writes are taken again. */
+	async ackDiscard(file: string, tab: string): Promise<void> {
+		const key = this.changedKey(file);
+		for (let attempt = 0; attempt < 5; attempt++) {
+			const raw = await this.redis.get(key);
+			const record = Autosaves.changedFrom(raw);
+			if (!record?.discard || !record.discard.tabs.includes(tab)) return;
+			const next = JSON.stringify({ ...record, discard: { ...record.discard, tabs: record.discard.tabs.filter((t) => t !== tab) } });
+			const ok = await landed(this.cache, key, () => this.redis.compareAndSet(key, raw, next));
+			if (ok) {
+				this.cache?.string(key, next);
+				return;
+			}
+			this.cache?.drop(key);
+		}
+	}
+
 	async committed(file: string): Promise<Committed | null> {
 		return parse<Committed>(await this.redis.get(this.committedKey(file)));
 	}