caracms 0.0.0-stage → 0.2.0

package/src/live/git.ts

@@ -0,0 +1,1021 @@
+/**
+ * The git layer of live mode (M4 Phase 1): the in-memory `drafts` copy, draft
+ * commits, keeping `drafts` up to date with `main`, Publish, what's waiting, publish
+ * status, history and Try again. No UI and no routes; Phase 2's live drafts store,
+ * sweep and status route sit on top of it.
+ *
+ * **The copy** (Spec → How it maps to git). The server holds `drafts`' site files in
+ * memory: downloaded once at startup as an archive, keeping only the files under
+ * the declared collection folders plus Site Settings (Decision 3), then kept current
+ * by the server's own commits and merges. When `drafts` moved under it (another
+ * server, during a deploy), it's refreshed before anything retries.
+ *
+ * **Two servers at once.** Railway runs the old and new servers side by side during
+ * a deploy. Nothing here assumes it's alone: every ref move is compare-and-swap
+ * (`expectedHeadOid`, `beforeOid`), a lost race re-reads and refreshes the copy and
+ * goes round again, Publish takes a Redis lock, and the newest publish is kept in
+ * Redis, so a status read on the new server knows about a publish the old one made.
+ *
+ * **Rate limits** (M1 → G4: 80 content-creating requests a minute, 500 an hour).
+ * One commit per batch; `drafts`' head comes from the copy, so a draft commit is
+ * one request; status reads ask GitHub at most once a minute (Decision 8) and the
+ * deployments at most every 10 seconds while a publish is in flight (Decision 13).
+ *
+ * **Deletions** (M5a Decisions 12): a draft entry with `text` null removes the file
+ * (`commitDrafts`), merged like any change with the draft winning (a file the editor
+ * deleted that `main` changed stays deleted, with `Draft-kept:`). A deleted document
+ * is named "Contact (deleted)" in the draft and publish headlines, its title from
+ * `main`'s copy, else `drafts`' copy before the removal, else its path. What's
+ * waiting knows which files `main` lacks (`SinceMain.absent`), so each waiting file is
+ * new, deleted or changed (`changeOf`), and a file made and removed again since the
+ * last Publish isn't waiting at all.
+ *
+ * In-process state here is caches of git and GitHub, and throttles; none of it is
+ * the only record of anything.
+ */
+import { randomBytes } from 'node:crypto';
+import { relative, sep } from 'node:path';
+import { repoPrefix, SITE_SETTINGS_FILE, type ResolvedSite } from '../config.ts';
+import { documentUrl, filesSource, type ContentSource } from '../content.ts';
+import { confinePath } from '../editor/server/write.ts';
+import { movesKey } from './autosaves.ts';
+import type { WaitingChange } from '../editor/types.ts';
+import { MissingBranchError, StaleHeadError, type Branch, type CommitSummary, type Comparison, type GitBackend, type Head, type Heads, type TreeChange } from './backend.ts';
+import { HttpError } from './github.ts';
+import { mergeFile } from './merge.ts';
+import { draftMessage, mergeMessage, parseMessage, publishMessage, type Person } from './messages.ts';
+import type { RedisClient } from './redis.ts';
+import { DEFAULT_TIMINGS, type LiveTimings } from './timings.ts';
+import { publishState, waitingFromCommits, type DeploymentFact, type PublishRecord, type PublishState, type WaitingFile } from './status.ts';
+
+/** One autosave to commit (Decision 6): `text` is `applyEdits(base, document)`. */
+export interface DraftEntry {
+	/** Site-relative path, `content/pages/index.json`. */
+	file: string;
+	/** The text the edits were made against: the merge's ancestor. Null for a file that didn't exist. */
+	base: string | null;
+	/** The autosave as text: the merge's draft side, which wins conflicts. Null: the editor deleted the file (M5a). */
+	text: string | null;
+	editor: Person;
+}
+
+export interface DraftCommitResult {
+	/** Null when nothing changed (every entry already matched `drafts`). */
+	commit: string | null;
+	/** Site-relative files the commit changed. */
+	files: string[];
+	/** Files where a key or the whole file was decided for the autosave (the notice). */
+	keptDraft: string[];
+	/** Each entry's file as committed, by file (null: removed). */
+	texts: Map<string, string | null>;
+	attempts: number;
+}
+
+export type CheckResult =
+	| { kind: 'current' }
+	| { kind: 'fast-forward'; to: string; fromMain: string[] }
+	| { kind: 'merged'; commit: string; fromMain: string[]; keptDraft: string[] };
+
+export type PublishResult =
+	| { kind: 'nothing-waiting' }
+	/** `fileTitles`: each of `record.files`' own title, in that order (`record.titles` is the headline's items). */
+	| { kind: 'published'; record: PublishRecord; attempts: number; fileTitles: string[] }
+	/** A Publish was already running; this press joined it. */
+	| { kind: 'joined'; record: PublishRecord | null };
+
+export interface PublishStatus {
+	/** `none`: nothing has been published since the record began. */
+	state: PublishState | 'none';
+	record: PublishRecord | null;
+	/** Live only because there's no deploy pipeline to ask (Decision 12; logged). */
+	assumed: boolean;
+	/** Try again is possible (a Railway token is set and the publish failed). */
+	canTryAgain: boolean;
+}
+
+export interface HistoryEntry {
+	commit: string;
+	by: Person | null;
+	/** ISO; the editor shows it in the site's time zone (Decision 16). */
+	at: string;
+	titles: string[];
+	files: string[];
+	state: PublishState;
+}
+
+export interface RailwayConfig {
+	/** CARACMS_RAILWAY_TOKEN: a project token (Decision 12). */
+	token: string;
+	serviceId: string;
+	environmentId: string;
+	/** For tests. Default: global fetch. */
+	fetch?: typeof fetch;
+}
+
+export interface LiveGitOptions {
+	backend: GitBackend;
+	site: Pick<ResolvedSite, 'root' | 'collections' | 'repoPath'>;
+	redis: RedisClient;
+	now?: () => number;
+	sleep?: (ms: number) => Promise<void>;
+	log?: (line: string) => void;
+	/** The running server's commit, read on every status (tests move it). Default: CARACMS_RUNNING_COMMIT or RAILWAY_GIT_COMMIT_SHA. */
+	runningCommit?: () => string | null;
+	timings?: Partial<LiveTimings>;
+	railway?: RailwayConfig | null;
+	/** Redis key prefix. Default `caracms:`. */
+	keyPrefix?: string;
+}
+
+/** The site file that holds Site Settings, relative to the site (Decision 15). Defined in config.ts (M5a: the reserved `settings` collection). */
+export { SITE_SETTINGS_FILE };
+
+const MAX_ATTEMPTS = 4;
+/** archiveDiff's mark for "changed, sha not known". */
+const CHANGED = '(changed)';
+const RAILWAY_API = 'https://backboard.railway.com/graphql/v2';
+
+const posix = (p: string) => p.split(sep).join('/');
+
+/** What `drafts` holds beyond `main`: from one compare, extended by this server's own commits. */
+interface SinceMain {
+	main: string;
+	drafts: string;
+	commits: CommitSummary[];
+	/** Repo paths that differ (a superset: a file changed and changed back stays listed). */
+	files: Set<string>;
+	/** M5a: those of `files` that `main` doesn't have (new on `drafts`, or made and removed again). */
+	absent: Set<string>;
+}
+
+export class LiveGit {
+	readonly backend: GitBackend;
+	readonly redis: RedisClient;
+	readonly timings: LiveTimings;
+	readonly now: () => number;
+	/** Phase 2 fills this: commit every pending autosave (Decision 10 step 1; Decision 8 before a merge). */
+	commitPending: () => Promise<void> = async () => {};
+	/**
+	 * Told the site files (and their new text) a fast-forward or merge from `main` just
+	 * changed in the copy. Phase 2's editor records "only merges" for any file with no
+	 * record of who changed it yet (Decision 11). Its failure never fails the check.
+	 */
+	tookIn: (files: { file: string; text: string }[]) => Promise<void> = async () => {};
+
+	private readonly site: LiveGitOptions['site'];
+	private readonly prefix: string;
+	private readonly folders: string[];
+	private readonly sleep: (ms: number) => Promise<void>;
+	private readonly log: (line: string) => void;
+	private readonly runningCommit: () => string | null;
+	private readonly railway: RailwayConfig | null;
+	private readonly keyPrefix: string;
+
+	private copyHead: Head | null = null;
+	private copyFiles = new Map<string, string>();
+	private since: SinceMain | null = null;
+	private lastCheck = -Infinity;
+	private checking: Promise<CheckResult> | null = null;
+	private queue: Promise<unknown> = Promise.resolve();
+	private assumedLogged = false;
+	private deploymentsCache: { key: string; at: number; facts: DeploymentFact[]; later: Set<string> } | null = null;
+	private includesCache = new Map<string, boolean>();
+	private laterCache: { key: string; later: Set<string> } | null = null;
+	private historyCache: { at: number; entries: HistoryEntry[] } | null = null;
+	private deploymentsDenied = false;
+	/** A deleted file's title (M5a): the waiting list's name for it once `drafts` has no copy. Learned when this process deleted it, else from `main`'s copy at a check (`learnDeletedTitles`), so a restart keeps it. */
+	private deletedTitles = new Map<string, string>();
+
+	constructor(options: LiveGitOptions) {
+		this.backend = options.backend;
+		this.redis = options.redis;
+		this.site = options.site;
+		this.timings = { ...DEFAULT_TIMINGS, ...options.timings };
+		this.now = options.now ?? Date.now;
+		this.sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+		this.log = options.log ?? ((line) => console.log(`[caracms] ${line}`));
+		this.runningCommit = options.runningCommit ?? (() => process.env.CARACMS_RUNNING_COMMIT || process.env.RAILWAY_GIT_COMMIT_SHA || null);
+		this.railway = options.railway ?? null;
+		this.keyPrefix = options.keyPrefix ?? 'caracms:';
+		this.prefix = repoPrefix(options.site);
+		// Every collection's folder, shared blocks' included (M5a Decision 8); Site Settings is its one file (inScope).
+		this.folders = Object.values(options.site.collections)
+			.filter((c) => c.kind !== 'settings')
+			.map((c) => posix(relative(options.site.root, c.dir)));
+	}
+
+	// ── Paths and the copy ──────────────────────────────────────────────────────
+
+	/** Is this repo path one the copy keeps? Collection folders' `.json` files (shared blocks' too), and Site Settings (Decision 3). */
+	inScope(repoPath: string): boolean {
+		if (!repoPath.startsWith(this.prefix)) return false;
+		const rel = repoPath.slice(this.prefix.length);
+		if (rel === SITE_SETTINGS_FILE) return true;
+		return rel.endsWith('.json') && this.folders.some((f) => rel.startsWith(`${f}/`));
+	}
+	toSite = (repoPath: string) => repoPath.slice(this.prefix.length);
+	toRepo = (sitePath: string) => `${this.prefix}${sitePath}`;
+
+	/** The copy's files, by site-relative path. Phase 3 reads `content/site-settings.json` here. */
+	files(): ReadonlyMap<string, string> {
+		return this.copyFiles;
+	}
+
+	/** One file from the copy, or null. */
+	read(sitePath: string): string | null {
+		return this.copyFiles.get(sitePath) ?? null;
+	}
+
+	/** The copy as a content.ts source: the reader's rules over `drafts` (Current state). */
+	contentSource(): ContentSource {
+		return filesSource(this.site.root, () => this.copyFiles);
+	}
+
+	/** `drafts`' head as the copy has it. */
+	head(): Head {
+		if (!this.copyHead) throw new Error('caracms: the drafts copy isn\'t loaded yet (call start()).');
+		return this.copyHead;
+	}
+
+	private key(name: string) {
+		return `${this.keyPrefix}${name}`;
+	}
+
+	/** Run `fn` alone among this server's git operations, so the copy is never changed by two at once. */
+	private exclusive<T>(fn: () => Promise<T>): Promise<T> {
+		const run = this.queue.then(fn, fn);
+		this.queue = run.catch(() => {});
+		return run;
+	}
+
+	// ── Startup ─────────────────────────────────────────────────────────────────
+
+	/**
+	 * Create `drafts` from `main` if it's missing, download the copy, and check `main` once
+	 * (`check: false` leaves the check to the caller: the runtime does, so the live editor
+	 * can run it once `commitPending` is in place, Decision 8).
+	 */
+	async start(options: { check?: boolean } = {}): Promise<void> {
+		await this.backend.tracker.within('start', () =>
+			this.exclusive(async () => {
+				let heads: Heads;
+				try {
+					heads = await this.backend.readHeads();
+				} catch (error) {
+					if (!(error instanceof MissingBranchError) || error.branch !== 'drafts') throw error;
+					const main = await this.mainOnly();
+					this.log(`no drafts branch yet: creating it from main (${main.slice(0, 7)})`);
+					await this.backend.createBranch('drafts', main).catch((e: unknown) => {
+						if (!(e instanceof HttpError && e.status === 422)) throw e; // another server made it first
+					});
+					heads = await this.backend.readHeads();
+				}
+				await this.download(heads.drafts);
+			}),
+		);
+		if (options.check !== false) await this.check({ force: true });
+	}
+
+	/** `main`'s head when `drafts` is missing (readHeads throws then). */
+	private async mainOnly(): Promise<string> {
+		// listCommits reads main alone; its first entry is the head.
+		const [head] = await this.backend.listCommits('main', 1);
+		if (!head) throw new MissingBranchError('main');
+		return head.sha;
+	}
+
+	private async download(head: Head) {
+		const files = await this.backend.readArchive(head.commit, (p) => this.inScope(p));
+		this.copyFiles = new Map([...files].map(([p, t]) => [this.toSite(p), t]));
+		this.copyHead = head;
+		this.since = null;
+	}
+
+	/** Bring the copy up to `drafts` as GitHub has it: the commits since, or a fresh download. */
+	private async refresh(heads: Heads) {
+		const copy = this.head();
+		if (heads.drafts.commit === copy.commit) return;
+		const cmp = await this.backend.compare(copy.commit, heads.drafts.commit);
+		if (cmp.status !== 'ahead' || cmp.files === null) {
+			this.log(`drafts moved to ${heads.drafts.commit.slice(0, 7)} (not on from the copy): downloading it again`);
+			await this.download(heads.drafts);
+			return;
+		}
+		// A file new to the waiting list was the same on main as in the copy, so main has it if the copy did.
+		const hadIt = new Map(cmp.files.map((f) => [f.path, this.copyFiles.has(this.toSite(f.path))]));
+		await this.applyChanges(heads.drafts, cmp);
+		if (this.since && this.since.main === heads.main.commit) {
+			this.since.drafts = heads.drafts.commit;
+			this.since.commits.push(...cmp.commits);
+			for (const f of cmp.files) {
+				if (!this.since.files.has(f.path) && !hadIt.get(f.path)) this.since.absent.add(f.path);
+				this.since.files.add(f.path);
+			}
+		} else this.since = null;
+	}
+
+	/** Lay a comparison's in-scope files (at `to`) onto the copy. */
+	private async applyChanges(to: Head, cmp: Comparison) {
+		const changed = (cmp.files ?? []).filter((f) => this.inScope(f.path));
+		const reads = changed.filter((f) => f.sha !== null);
+		const texts = reads.length ? await this.backend.readFiles(reads.map((f) => ({ commit: to.commit, path: f.path }))) : [];
+		reads.forEach((f, i) => {
+			const text = texts[i];
+			if (text === null || text === undefined) this.copyFiles.delete(this.toSite(f.path));
+			else this.copyFiles.set(this.toSite(f.path), text);
+		});
+		for (const f of changed) if (f.sha === null) this.copyFiles.delete(this.toSite(f.path));
+		this.copyHead = to;
+	}
+
+	/** Re-read both heads and refresh the copy: after any failed ref move (M1 → G6 (a)). */
+	private async reread(): Promise<Heads> {
+		const heads = await this.backend.readHeads();
+		await this.refresh(heads);
+		return heads;
+	}
+
+	// ── Draft commits (Decisions 5 and 6) ───────────────────────────────────────
+
+	/**
+	 * Commit a batch of autosaves to `drafts` in **one** commit, each merged with the
+	 * file in `drafts` now (Decision 6), with who changed what in the message
+	 * (Decision 5). Entries for one file apply in order. A lost race refreshes the copy
+	 * and merges again.
+	 */
+	async commitDrafts(entries: DraftEntry[]): Promise<DraftCommitResult> {
+		return this.backend.tracker.within('draft', () =>
+			this.exclusive(async () => {
+				for (let attempt = 1; ; attempt++) {
+					const head = this.head();
+					const texts = new Map<string, string | null>();
+					const kept = new Set<string>();
+					const edits: { file: string; title: string; editor: Person }[] = [];
+					for (const entry of entries) {
+						const perKey = entry.file.endsWith('.json');
+						const current = texts.has(entry.file) ? texts.get(entry.file)! : this.read(entry.file);
+						const merged = mergeFile({ base: entry.base, draft: entry.text, other: current, perKey });
+						// The notice is for changes made outside this batch: a later entry for the same file is checked against drafts.
+						const outside = texts.has(entry.file) ? mergeFile({ base: entry.base, draft: entry.text, other: this.read(entry.file), perKey }) : merged;
+						if (outside.keptDraft) kept.add(entry.file);
+						// An editor's autosave never deletes: a null here means "deleted on the other side", and the draft
+						// wins it. A deletion (M5a: `text` null) merges like any change, so a removal the draft wins removes it.
+						texts.set(entry.file, entry.text === null ? merged.text : (merged.text ?? entry.text));
+						edits.push({ file: entry.file, title: '', editor: entry.editor });
+					}
+					const changed = [...texts].filter(([file, text]) => this.read(file) !== text);
+					if (changed.length === 0) return { commit: null, files: [], keptDraft: [], texts, attempts: attempt };
+					const changedFiles = new Set(changed.map(([f]) => f));
+					const removed = changed.filter(([, text]) => text === null).map(([f]) => f);
+					const deletedTitles = await this.titlesBeforeRemoval(removed);
+					const titled = edits
+						.filter((e) => changedFiles.has(e.file))
+						.map((e) => ({ ...e, title: texts.get(e.file) === null ? `${deletedTitles.get(e.file)!} (deleted)` : titleOf(e.file, texts.get(e.file)!) }));
+					const { headline, body } = draftMessage(titled, [...kept].filter((f) => changedFiles.has(f)));
+					try {
+						const next = await this.backend.commitOnBranch(
+							'drafts',
+							head.commit,
+							changed.filter(([, text]) => text !== null).map(([file, contents]) => ({ path: this.toRepo(file), contents: contents! })),
+							removed.map(this.toRepo),
+							headline,
+							body,
+						);
+						// Before the copy changes: a file new to the waiting list is on main exactly when drafts had it.
+						const absentOnMain = changed.filter(([file]) => this.read(file) === null).map(([file]) => this.toRepo(file));
+						for (const [file, text] of changed) {
+							if (text === null) this.copyFiles.delete(file);
+							else this.copyFiles.set(file, text);
+						}
+						for (const [file, title] of deletedTitles) this.deletedTitles.set(file, title);
+						this.copyHead = next;
+						if (this.since?.drafts === head.commit) {
+							this.since.drafts = next.commit;
+							this.since.commits.push({ sha: next.commit, parents: [head.commit], message: `${headline}\n\n${body}`, date: new Date(this.now()).toISOString() });
+							for (const [file] of changed) {
+								const repo = this.toRepo(file);
+								if (!this.since.files.has(repo) && absentOnMain.includes(repo)) this.since.absent.add(repo);
+								this.since.files.add(repo);
+							}
+						}
+						this.log(`draft ${next.commit.slice(0, 7)}: ${[...changedFiles].join(', ')}`);
+						return { commit: next.commit, files: [...changedFiles], keptDraft: [...kept].filter((f) => changedFiles.has(f)), texts, attempts: attempt };
+					} catch (error) {
+						const heads = await this.backend.readHeads().catch(() => null);
+						const moved = heads !== null && heads.drafts.commit !== head.commit;
+						if (!(error instanceof StaleHeadError) && !moved) throw error;
+						if (attempt >= MAX_ATTEMPTS) throw new Error(`caracms: drafts kept moving; gave up committing after ${attempt} tries.`);
+						this.log(`draft: drafts moved under us; refreshing the copy and merging again`);
+						await this.refresh(heads ?? (await this.backend.readHeads()));
+					}
+				}
+			}),
+		);
+	}
+
+	// ── Keeping drafts up to date with main (Decision 8) ────────────────────────
+
+	/**
+	 * Is `main` in `drafts`? If `drafts` is only behind, fast-forward it; if they've
+	 * diverged, commit every pending autosave and merge per key. Throttled to once a
+	 * minute unless `force` (startup, the webhook, Publish). Concurrent calls share one run.
+	 */
+	async check(options: { force?: boolean } = {}): Promise<CheckResult> {
+		// Not throttled while the cached compare is missing (after a refresh), so waiting() comes back soon.
+		if (!options.force && this.since && this.now() - this.lastCheck < this.timings.mainCheckMs) return { kind: 'current' };
+		if (this.checking) return this.checking;
+		this.lastCheck = this.now();
+		this.checking = this.backend.tracker
+			.within('check', async () => {
+				let pendingCommitted = false;
+				for (let attempt = 1; attempt <= MAX_ATTEMPTS + 1; attempt++) {
+					const r = await this.exclusive(() => this.checkOnce(pendingCommitted));
+					if (r !== 'needs-pending') {
+						await this.exclusive(() => this.learnDeletedTitles());
+						return r;
+					}
+					await this.commitPending();
+					pendingCommitted = true;
+				}
+				throw new Error('caracms: main and drafts kept moving; gave up keeping drafts up to date.');
+			})
+			.finally(() => {
+				this.checking = null;
+			});
+		return this.checking;
+	}
+
+	private async checkOnce(pendingCommitted: boolean): Promise<CheckResult | 'needs-pending'> {
+		for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+			const heads = await this.reread();
+			if (this.since && this.since.main === heads.main.commit && this.since.drafts === heads.drafts.commit) return { kind: 'current' };
+			const cmp = await this.backend.compare(heads.drafts.commit, heads.main.commit); // main relative to drafts
+			if (cmp.status === 'identical' || cmp.status === 'behind') {
+				// main is in drafts: just learn what's waiting.
+				await this.learnSince(heads);
+				return { kind: 'current' };
+			}
+			if (cmp.status === 'ahead') {
+				const done = await this.fastForward(heads, cmp);
+				if (done) return done;
+				continue;
+			}
+			if (!pendingCommitted) return 'needs-pending';
+			const merged = await this.merge(heads, cmp);
+			if (merged) return merged;
+		}
+		throw new Error('caracms: drafts kept moving; gave up merging main into it.');
+	}
+
+	/** What `drafts` holds beyond `main` (Decision 8's cached compare). */
+	private async learnSince(heads: Heads) {
+		if (heads.main.commit === heads.drafts.commit) {
+			this.since = { main: heads.main.commit, drafts: heads.drafts.commit, commits: [], files: new Set(), absent: new Set() };
+			return;
+		}
+		const cmp = await this.backend.compare(heads.main.commit, heads.drafts.commit);
+		this.since = {
+			main: heads.main.commit,
+			drafts: heads.drafts.commit,
+			commits: cmp.commits,
+			files: new Set((cmp.files ?? this.diffCopyFallback()).map((f) => (typeof f === 'string' ? f : f.path))),
+			// Added on drafts: main doesn't have it. (With too many files to list, none is known to be missing.)
+			absent: new Set((cmp.files ?? []).filter((f) => f.status === 'added').map((f) => f.path)),
+		};
+	}
+
+	/** With too many files for GitHub's compare: every in-scope file counts as possibly waiting. */
+	private diffCopyFallback(): string[] {
+		this.log('compare listed too many files: treating every content file as possibly waiting');
+		return [...this.copyFiles.keys()].map(this.toRepo);
+	}
+
+	/** `drafts` only behind `main`: move it up, no merge commit (Decision 8). Null when it lost a race. */
+	private async fastForward(heads: Heads, cmp: Comparison): Promise<CheckResult | null> {
+		if (!(await this.moveRefs([{ branch: 'drafts', before: heads.drafts.commit, after: heads.main.commit, force: false }]))) return null;
+		if (cmp.files === null) await this.download(heads.main);
+		else await this.applyChanges(heads.main, cmp);
+		this.since = { main: heads.main.commit, drafts: heads.main.commit, commits: [], files: new Set(), absent: new Set() };
+		const fromMain = (cmp.files ?? []).filter((f) => this.inScope(f.path)).map((f) => this.toSite(f.path));
+		this.log(`drafts fast-forwarded to main (${heads.main.commit.slice(0, 7)})`);
+		await this.told(fromMain);
+		return { kind: 'fast-forward', to: heads.main.commit, fromMain };
+	}
+
+	/**
+	 * `main` and `drafts` diverged: a merge commit (parents drafts, main) whose tree is
+	 * `main`'s with `drafts`' changes laid over it, and per-key merges (merge.ts) for
+	 * content files changed on both sides. Null when it lost a race.
+	 */
+	private async merge(heads: Heads, mainSide: Comparison): Promise<CheckResult | null> {
+		const draftsSide = await this.backend.compare(heads.main.commit, heads.drafts.commit);
+		const base = mainSide.mergeBase.commit;
+
+		// Main's in-scope changes since the merge base. Out-of-scope ones come with main's tree.
+		let mainChanged: Map<string, string | null>;
+		if (mainSide.files) mainChanged = new Map(mainSide.files.filter((f) => this.inScope(f.path)).map((f) => [f.path, f.sha]));
+		else mainChanged = await this.archiveDiff(base, heads.main.commit);
+		let draftsChanged: Map<string, string | null>;
+		if (draftsSide.files) draftsChanged = new Map(draftsSide.files.map((f) => [f.path, f.sha]));
+		else {
+			this.log('merge: too many drafts-side files to list; only content files are carried over');
+			draftsChanged = await this.archiveDiff(base, heads.drafts.commit);
+		}
+		// archiveDiff knows texts, not blob shas: drafts' side is then written from the copy.
+		const fromCopy = (path: string) => draftsChanged.get(path) === CHANGED;
+
+		const both = [...draftsChanged.keys()].filter((p) => mainChanged.has(p));
+		const both3 = both.filter((p) => this.inScope(p));
+		const mainOnly = [...mainChanged].filter(([p, sha]) => !draftsChanged.has(p) && sha !== null).map(([p]) => p);
+		const reads = [
+			...both3.flatMap((p) => [
+				{ commit: base, path: p },
+				{ commit: heads.main.commit, path: p },
+			]),
+			...mainOnly.map((p) => ({ commit: heads.main.commit, path: p })),
+		];
+		const texts = reads.length ? await this.backend.readFiles(reads) : [];
+
+		const changes: TreeChange[] = [];
+		const writes: { path: string; contents: string }[] = [];
+		const copyAfter = new Map<string, string | null>();
+		const keptDraft: string[] = [];
+		// Changed only on drafts' side: drafts' version over main's tree. (Content files are plain files.)
+		for (const [path, sha] of draftsChanged) {
+			if (mainChanged.has(path)) continue;
+			if (fromCopy(path)) writes.push({ path, contents: this.read(this.toSite(path))! });
+			else changes.push({ path, mode: '100644', sha });
+		}
+		both3.forEach((path, i) => {
+			const site = this.toSite(path);
+			const result = mergeFile({ base: texts[i * 2] ?? null, other: texts[i * 2 + 1] ?? null, draft: this.read(site), perKey: path.endsWith('.json') });
+			if (result.keptDraft) keptDraft.push(site);
+			if (result.text === null) changes.push({ path, mode: '100644', sha: null });
+			else writes.push({ path, contents: result.text });
+			copyAfter.set(site, result.text);
+		});
+		// Changed on both sides outside the copy (code pushed to drafts): the draft's version, whole.
+		for (const path of both.filter((p) => !this.inScope(p))) changes.push({ path, mode: '100644', sha: draftsChanged.get(path)! });
+		mainOnly.forEach((path, i) => copyAfter.set(this.toSite(path), texts[both3.length * 2 + i] ?? null));
+		for (const [path, sha] of mainChanged) if (sha === null && !draftsChanged.has(path)) copyAfter.set(this.toSite(path), null);
+
+		const tree = changes.length || writes.length ? await this.backend.createTree(heads.main.tree, changes, writes) : heads.main.tree;
+		const fromMain = [...mainChanged.keys()].filter((p) => !draftsChanged.has(p)).map(this.toSite);
+		const message = mergeMessage(fromMain, keptDraft);
+		const commit = await this.backend.createCommit(tree, [heads.drafts.commit, heads.main.commit], message);
+		if (!(await this.moveRefs([{ branch: 'drafts', before: heads.drafts.commit, after: commit, force: false }]))) return null;
+
+		for (const [site, text] of copyAfter) {
+			if (text === null) this.copyFiles.delete(site);
+			else this.copyFiles.set(site, text);
+		}
+		this.copyHead = { commit, tree };
+		// Which of drafts' files main lacks now: one main deleted (the draft kept it), or one drafts added that main didn't.
+		const addedOnDrafts = new Set((draftsSide.files ?? []).filter((f) => f.status === 'added').map((f) => f.path));
+		const absent = [...draftsChanged.keys()].filter((p) => (mainChanged.has(p) ? mainChanged.get(p) === null : addedOnDrafts.has(p)));
+		this.since = {
+			main: heads.main.commit,
+			drafts: commit,
+			commits: [...draftsSide.commits, { sha: commit, parents: [heads.drafts.commit, heads.main.commit], message, date: new Date(this.now()).toISOString() }],
+			files: new Set(draftsChanged.keys()),
+			absent: new Set(absent),
+		};
+		this.log(`merged main into drafts (${commit.slice(0, 7)}): from main [${fromMain.join(', ')}], draft kept [${keptDraft.join(', ')}]`);
+		await this.told([...copyAfter.keys()]);
+		return { kind: 'merged', commit, fromMain, keptDraft };
+	}
+
+	/** Hand `tookIn` the files a check just changed in the copy (deleted ones left out). */
+	private async told(files: string[]) {
+		const changed = [...new Set(files)].flatMap((file) => {
+			const text = this.read(file);
+			return text === null ? [] : [{ file, text }];
+		});
+		if (!changed.length) return;
+		await this.tookIn(changed).catch((error: unknown) => this.log(`recording what main changed: ${error instanceof Error ? error.message : String(error)}`));
+	}
+
+	/** In-scope files that differ between two commits, from their archives (when compare can't list them). */
+	private async archiveDiff(from: string, to: string): Promise<Map<string, string | null>> {
+		const [a, b] = await Promise.all([this.backend.readArchive(from, (p) => this.inScope(p)), this.backend.readArchive(to, (p) => this.inScope(p))]);
+		const out = new Map<string, string | null>();
+		for (const p of new Set([...a.keys(), ...b.keys()])) {
+			if (a.get(p) === b.get(p)) continue;
+			out.set(p, b.has(p) ? CHANGED : null);
+		}
+		return out;
+	}
+
+	/**
+	 * Move refs, compare-and-swap. **After any error, re-read both heads** (M1 → G6 (a):
+	 * GitHub's error for a stale `beforeOid` is generic): if a head moved, it lost a race,
+	 * and the copy is refreshed; returns false. Anything else is thrown. **If every ref
+	 * already points where this call moved it**, the move landed and only its answer was
+	 * lost: that's a success.
+	 */
+	private async moveRefs(updates: { branch: Branch; before: string; after: string; force: boolean }[]): Promise<boolean> {
+		try {
+			await this.backend.updateRefs(updates);
+			return true;
+		} catch (error) {
+			const heads = await this.backend.readHeads();
+			if (updates.every((u) => heads[u.branch].commit === u.after)) {
+				this.log(`the ref move's answer was lost, but ${updates.map((u) => u.branch).join(' and ')} point where it moved them: it landed`);
+				return true;
+			}
+			const moved = updates.some((u) => heads[u.branch].commit !== u.before);
+			if (!moved && !(error instanceof StaleHeadError)) throw error;
+			this.log(`a ref moved under us (${updates.map((u) => u.branch).join(', ')}); re-reading and trying again`);
+			await this.refresh(heads);
+			this.since = null;
+			return false;
+		}
+	}
+
+	// ── Publish (Decision 10) ───────────────────────────────────────────────────
+
+	/**
+	 * Publish: commit every pending autosave; refuse to go on unless `main` is in
+	 * `drafts` (merging inside the retry loop); one squashed commit with `drafts`' tree on
+	 * `main`'s head; both refs moved in one `updateRefs`; after any error, re-read and
+	 * start again. Nothing waiting: nothing happens. One Publish at a time per site (a
+	 * Redis lock); a second press while one runs joins it.
+	 */
+	async publish(by: Person): Promise<PublishResult> {
+		const lock = this.key('publish:lock');
+		const token = randomBytes(12).toString('base64url');
+		if (!(await this.redis.set(lock, token, { nx: true, px: this.timings.publishLockMs }))) {
+			const until = this.now() + this.timings.publishLockMs;
+			while (this.now() < until && (await this.redis.get(lock)) !== null) await this.sleep(500);
+			return { kind: 'joined', record: await this.lastPublish() };
+		}
+		try {
+			return await this.backend.tracker.within('publish', async () => {
+				for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+					await this.commitPending();
+					const r = await this.exclusive(() => this.publishOnce(by, attempt));
+					if (r) return r;
+				}
+				throw new Error(`caracms: publish gave up after ${MAX_ATTEMPTS} tries (main or drafts kept moving).`);
+			});
+		} finally {
+			await this.redis.compareAndDelete(lock, token).catch(() => {});
+		}
+	}
+
+	private async publishOnce(by: Person, attempt: number): Promise<PublishResult | null> {
+		const heads = await this.reread();
+		if (heads.main.tree === heads.drafts.tree) {
+			this.log('publish: nothing waiting');
+			return { kind: 'nothing-waiting' };
+		}
+		const cmp = await this.backend.compare(heads.main.commit, heads.drafts.commit);
+		if (cmp.status !== 'ahead' && cmp.status !== 'identical') {
+			// A push landed on main (M1 → G6 (e)): merge it in (pending autosaves were just committed), then go round.
+			this.log(`publish: main isn't in drafts (${cmp.status}); merging it in first`);
+			const mainSide = await this.backend.compare(heads.drafts.commit, heads.main.commit);
+			await this.merge(heads, mainSide);
+			return null;
+		}
+		const repoFiles = (cmp.files ?? this.diffCopyFallback().map((path) => ({ path }))).map((f) => f.path);
+		const files = repoFiles.filter((p) => p.startsWith(this.prefix)).map(this.toSite);
+		// A file drafts no longer has is deleted: "Contact (deleted)", its title from main's copy first (M5a Decision 12).
+		const gone = files.filter((f) => this.read(f) === null);
+		const goneTitles = await this.titlesBeforeRemoval(gone, heads.main.commit);
+		const records = await this.moveRecords();
+		const moves = this.movesIn(files, records);
+		// Each file's own title (a "stood" notice names the document by it), then the headline's items.
+		const fileTitles = files.map((f) => {
+			const text = this.read(f);
+			return text === null ? goneTitles.get(f)! : titleOf(f, text);
+		});
+		const items = files.map((f, i) => {
+			if (this.read(f) === null) return `${fileTitles[i]!} (deleted)`;
+			return moves.from.has(f) ? `${fileTitles[i]!} (moved from ${moves.from.get(f)})` : fileTitles[i]!;
+		});
+		// Pre-M7 item 8: a moved document is one item in the headline, "Visit (moved from /studio/visit)",
+		// listed first; its old file is part of that item, not one of its own.
+		const titles = [...items.filter((_, i) => moves.from.has(files[i]!)), ...items.filter((_, i) => !moves.from.has(files[i]!) && !moves.to.has(files[i]!))];
+		const commit = await this.backend.createCommit(heads.drafts.tree, [heads.main.commit], publishMessage(titles, files, by));
+		const moved = await this.moveRefs([
+			// main: a fast-forward onto the squash commit. drafts: not a fast-forward, so
+			// `force`, but still compare-and-swap on `before` (M1 → G2).
+			{ branch: 'main', before: heads.main.commit, after: commit, force: false },
+			{ branch: 'drafts', before: heads.drafts.commit, after: commit, force: true },
+		]);
+		if (!moved) return null; // the squash commit is left orphaned; nothing points at it
+		this.copyHead = { commit, tree: heads.drafts.tree };
+		this.since = { main: commit, drafts: commit, commits: [], files: new Set(), absent: new Set() };
+		this.deletedTitles.clear();
+		this.historyCache = null;
+		// The moves this publish took live are done with (a move made since stays waiting).
+		const published = [...records].filter(([old]) => files.includes(old)).map(([old]) => old);
+		if (published.length) await this.redis.hdel(movesKey(this.keyPrefix), ...published).catch(() => 0);
+		const record: PublishRecord = { commit, by, at: new Date(this.now()).toISOString(), files, titles, tryAgainAt: null };
+		await this.redis.set(this.key('publish:last'), JSON.stringify(record));
+		this.log(`published ${commit.slice(0, 7)} (attempt ${attempt}): ${titles.join(', ')}`);
+		return { kind: 'published', record, attempts: attempt, fileTitles };
+	}
+
+	/** The newest publish, from Redis. */
+	async lastPublish(): Promise<PublishRecord | null> {
+		const raw = await this.redis.get(this.key('publish:last'));
+		if (!raw) return null;
+		try {
+			return JSON.parse(raw) as PublishRecord;
+		} catch {
+			return null;
+		}
+	}
+
+	// ── What's waiting (Decision 8) ─────────────────────────────────────────────
+
+	/**
+	 * Files that differ between `main` and `drafts`, with who changed them and when,
+	 * from git (the cached compare plus this server's own commits since). **Never asks
+	 * GitHub.** Phase 2 lays Redis's uncommitted autosaves on top.
+	 */
+	waiting(): (WaitingFile & { title: string; change: WaitingChange })[] {
+		if (!this.since) return [];
+		const files = [...this.since.files].filter((p) => this.inScope(p)).map(this.toSite);
+		return waitingFromCommits(files, this.since.commits).flatMap((w) => {
+			const change = this.changeOf(w.file, this.read(w.file));
+			return change ? [{ ...w, change, title: this.titleFor(w.file) }] : [];
+		});
+	}
+
+	/**
+	 * M5a: does `main` have this file? From the cached compare when the file is waiting
+	 * (`absent`), else as `drafts` has it (the two are the same there). Never asks GitHub.
+	 */
+	mainHas(sitePath: string): boolean {
+		const repo = this.toRepo(sitePath);
+		if (this.since?.files.has(repo)) return !this.since.absent.has(repo);
+		return this.read(sitePath) !== null;
+	}
+
+	/**
+	 * M5a: what a document whose text is now `text` (null: deleted) is to `main`: `new`,
+	 * `deleted` or `changed`; null when it's neither on `main` nor here (made and
+	 * deleted again since the last Publish: nothing to publish, so not waiting).
+	 */
+	changeOf(sitePath: string, text: string | null): WaitingChange | null {
+		const onMain = this.mainHas(sitePath);
+		if (text === null) return onMain ? 'deleted' : null;
+		return onMain ? 'changed' : 'new';
+	}
+
+	/** Pre-M7 item 8: the documents a publish moves (`movesIn`), over `drafts`' copy. */
+	private movesIn(files: string[], records: ReadonlyMap<string, string>): Moves {
+		return movesIn(this.site, files, (f) => this.read(f), records);
+	}
+
+	/** Pre-M7 item 8: the moves recorded as they were made (autosaves.ts → `moves`), old file → new file. */
+	private async moveRecords(): Promise<Map<string, string>> {
+		return new Map(Object.entries(await this.redis.hgetall(movesKey(this.keyPrefix))));
+	}
+
+	/** A file's title for the waiting list and notices: the copy's, else the title it had when it was deleted, else its name. */
+	titleFor(sitePath: string): string {
+		const text = this.read(sitePath);
+		if (text !== null) return titleOf(sitePath, text);
+		return this.deletedTitles.get(sitePath) ?? titleOf(sitePath, null);
+	}
+
+	/**
+	 * M5a: the title of each deletion waiting to publish that this process hasn't heard of
+	 * (a restart, another server's commit), from `main`'s copy of the file, which exists for
+	 * any deletion still waiting. So the waiting list names it as the document, not its file.
+	 * A failed read leaves the file's name (the same fallback as the commit messages) unsaved, so the next check tries again.
+	 */
+	private async learnDeletedTitles() {
+		if (!this.since) return;
+		const missing = [...this.since.files]
+			.filter((p) => this.inScope(p))
+			.map(this.toSite)
+			.filter((f) => this.read(f) === null && this.mainHas(f) && !this.deletedTitles.has(f));
+		if (missing.length === 0) return;
+		const titles = await this.titlesBeforeRemoval(missing, this.since.main);
+		for (const [file, title] of titles) if (title !== titleOf(file, null)) this.deletedTitles.set(file, title);
+	}
+
+	/**
+	 * Deleted files' titles for the commit messages (M5a Decision 12): `main`'s copy
+	 * (one read, only for files `main` has), else `drafts`' copy before the removal,
+	 * else the file's name. A failed read falls back the same way.
+	 */
+	private async titlesBeforeRemoval(files: string[], mainCommit?: string): Promise<Map<string, string>> {
+		const out = new Map<string, string>();
+		if (files.length === 0) return out;
+		const onMain = files.filter((f) => this.mainHas(f));
+		let mainTexts: (string | null)[] = [];
+		if (onMain.length) {
+			try {
+				const main = mainCommit ?? this.since?.main ?? (await this.backend.readHeads()).main.commit;
+				mainTexts = await this.backend.readFiles(onMain.map((f) => ({ commit: main, path: this.toRepo(f) })));
+			} catch (error) {
+				this.log(`reading main's copy of deleted files for their titles: ${error instanceof Error ? error.message : String(error)}`);
+			}
+		}
+		for (const file of files) {
+			const fromMain = mainTexts[onMain.indexOf(file)] ?? null;
+			const before = this.read(file);
+			const title = fromMain !== null ? titleOf(file, fromMain) : before !== null ? titleOf(file, before) : (this.deletedTitles.get(file) ?? titleOf(file, null));
+			out.set(file, title);
+		}
+		return out;
+	}
+
+	/**
+	 * Phase 2: each waiting file the merge decided for the draft, with the newest commit
+	 * that said so (`Draft-kept:`), so a dismissed notice comes back only for a new
+	 * conflict. From the cached compare; never asks GitHub.
+	 */
+	keptDraftNotices(): { file: string; commit: string }[] {
+		if (!this.since) return [];
+		const waiting = new Set([...this.since.files].filter((p) => this.inScope(p)).map(this.toSite));
+		const out = new Map<string, string>();
+		for (const c of this.since.commits) for (const file of parseMessage(c.message).keptDraft) if (waiting.has(file)) out.set(file, c.sha);
+		return [...out].map(([file, commit]) => ({ file, commit }));
+	}
+
+	// ── Publish status (Decision 12) ────────────────────────────────────────────
+
+	/** The newest publish's state. Asks GitHub at most every `deploymentReadMs`, and only while it isn't live. */
+	async publishStatus(): Promise<PublishStatus> {
+		const record = await this.lastPublish();
+		if (!record) return { state: 'none', record: null, assumed: false, canTryAgain: false };
+		const running = this.runningCommit();
+		if (running === null) {
+			if (!this.assumedLogged) {
+				this.assumedLogged = true;
+				this.log('no RAILWAY_GIT_COMMIT_SHA or CARACMS_RUNNING_COMMIT: no deploy pipeline, so a publish reads as live once its refs moved');
+			}
+			return { state: 'live', record, assumed: true, canTryAgain: false };
+		}
+		return this.backend.tracker.within('status', async () => {
+			const includes = running === record.commit ? true : await this.includes(record.commit, running);
+			let facts: DeploymentFact[] = [];
+			let later = new Set<string>();
+			if (!includes) ({ facts, later } = await this.deploymentFacts(record));
+			const { state } = publishState({ record, running, runningIncludesPublish: includes, laterOnMain: later, deployments: facts });
+			return { state, record, assumed: false, canTryAgain: state === 'failed' && this.railway !== null };
+		});
+	}
+
+	/** Is `commit` in `running` (the same, or an ancestor)? One compare per pair, per server. */
+	private async includes(commit: string, running: string): Promise<boolean> {
+		const key = `${commit}:${running}`;
+		const known = this.includesCache.get(key);
+		if (known !== undefined) return known;
+		let yes = false;
+		try {
+			const cmp = await this.backend.compare(commit, running);
+			yes = cmp.status === 'ahead' || cmp.status === 'identical';
+		} catch (error) {
+			if (!(error instanceof HttpError && error.status === 404)) throw error; // the running commit isn't in this repo
+		}
+		this.includesCache.set(key, yes); // ancestry never changes: one compare per pair
+		return yes;
+	}
+
+	private async deploymentFacts(record: PublishRecord): Promise<{ facts: DeploymentFact[]; later: Set<string> }> {
+		const key = `${record.commit}:${record.tryAgainAt ?? ''}`;
+		const cached = this.deploymentsCache;
+		if (cached && cached.key === key && this.now() - cached.at < this.timings.deploymentReadMs) return cached;
+		if (this.deploymentsDenied) return { facts: [], later: new Set() };
+		let facts: DeploymentFact[] = [];
+		let later = new Set<string>();
+		try {
+			// main's head from the cached compare when there is one (Decision 8 keeps it fresh), else one ref read.
+			const main = this.since?.main ?? (await this.backend.readHeads()).main.commit;
+			if (main !== record.commit) {
+				if (this.laterCache?.key !== `${record.commit}:${main}`) {
+					const cmp = await this.backend.compare(record.commit, main);
+					this.laterCache = { key: `${record.commit}:${main}`, later: new Set(cmp.commits.map((c) => c.sha)) };
+				}
+				later = this.laterCache.later;
+			}
+			const deployments = (await this.backend.listDeployments(30)).filter((d) => d.sha === record.commit || later.has(d.sha));
+			for (const d of deployments.slice(0, 5)) {
+				const s = await this.backend.deploymentStatus(d.id);
+				facts.push({ sha: d.sha, createdAt: d.createdAt, state: s?.state ?? null });
+			}
+		} catch (error) {
+			if (error instanceof HttpError && (error.status === 403 || error.status === 404)) {
+				this.deploymentsDenied = true;
+				this.log(`can't read GitHub Deployments (${error.status}): the App needs "Deployments: read". A publish will show as publishing until the server runs it.`);
+				return { facts: [], later: new Set() };
+			}
+			throw error;
+		}
+		this.deploymentsCache = { key, at: this.now(), facts, later };
+		return this.deploymentsCache;
+	}
+
+	// ── History (Decision 12) ───────────────────────────────────────────────────
+
+	/** The newest 20 publishes from `main`'s commits, cached; `refresh` asks again at most once a minute. */
+	async history(options: { refresh?: boolean } = {}): Promise<HistoryEntry[]> {
+		const cached = this.historyCache;
+		if (cached && (!options.refresh || this.now() - cached.at < this.timings.historyMs)) return cached.entries;
+		return this.backend.tracker.within('history', async () => {
+			const commits = await this.backend.listCommits('main', 100);
+			const status = await this.publishStatus();
+			const running = this.runningCommit();
+			const runningAt = running === null ? -1 : commits.findIndex((c) => c.sha === running);
+			const entries: HistoryEntry[] = [];
+			commits.forEach((c, i) => {
+				if (entries.length >= 20) return;
+				const parsed = parseMessage(c.message);
+				if (parsed.kind !== 'publish') return;
+				const live = running === null || (runningAt !== -1 && i >= runningAt) || (status.record?.commit === c.sha && status.state === 'live');
+				const pending: PublishState = status.state === 'failed' ? 'failed' : 'publishing';
+				entries.push({ commit: c.sha, by: parsed.publishedBy, at: c.date, titles: parsed.titles, files: parsed.publishedFiles, state: live ? 'live' : pending });
+			});
+			this.historyCache = { at: this.now(), entries };
+			return entries;
+		});
+	}
+
+	// ── Try again (Decision 12) ─────────────────────────────────────────────────
+
+	/** Redeploy through Railway's API with the project token. Never publishes again. */
+	async tryAgain(): Promise<{ ok: true } | { ok: false; reason: string }> {
+		if (!this.railway) return { ok: false, reason: 'No CARACMS_RAILWAY_TOKEN: a developer can redeploy from Railway.' };
+		const record = await this.lastPublish();
+		if (!record) return { ok: false, reason: 'Nothing has been published.' };
+		const { token, serviceId, environmentId } = this.railway;
+		const res = await (this.railway.fetch ?? fetch)(RAILWAY_API, {
+			method: 'POST',
+			headers: { 'content-type': 'application/json', 'project-access-token': token },
+			body: JSON.stringify({
+				query: 'mutation($serviceId: String!, $environmentId: String!) { serviceInstanceRedeploy(serviceId: $serviceId, environmentId: $environmentId) }',
+				variables: { serviceId, environmentId },
+			}),
+		});
+		const body = (await res.json().catch(() => ({}))) as { data?: { serviceInstanceRedeploy?: boolean }; errors?: { message: string }[] };
+		if (!res.ok || body.errors?.length || !body.data?.serviceInstanceRedeploy) {
+			const reason = body.errors?.map((e) => e.message).join('; ') || `Railway answered ${res.status}`;
+			this.log(`try again: Railway refused the redeploy (${reason})`);
+			return { ok: false, reason };
+		}
+		await this.redis.set(this.key('publish:last'), JSON.stringify({ ...record, tryAgainAt: new Date(this.now()).toISOString() }));
+		this.deploymentsCache = null;
+		this.log(`try again: Railway is redeploying (publish ${record.commit.slice(0, 7)})`);
+		return { ok: true };
+	}
+}
+
+export interface Moves {
+	/** The new file → its old address. */
+	from: Map<string, string>;
+	/** The old file → its new address. */
+	to: Map<string, string>;
+}
+
+/**
+ * Pre-M7 item 8: which of these changed files are documents moved, from the moves
+ * recorded as they were made (`records`, old file → new file: autosaves.ts → `moves`),
+ * never from Site Settings' redirects, so a move stays a move whether or not the
+ * editor keeps its redirect. A record counts while both files are among `files`, the
+ * old one gone (`read` null) and the new one there. Publish's headline and the waiting
+ * list read it ("Visit (moved from /studio/visit)").
+ */
+export function movesIn(site: Pick<ResolvedSite, 'root' | 'collections'>, files: readonly string[], read: (file: string) => string | null, records: ReadonlyMap<string, string>): Moves {
+	const from = new Map<string, string>();
+	const to = new Map<string, string>();
+	const urlOf = (file: string) => {
+		try {
+			const c = confinePath(site as ResolvedSite, file);
+			return documentUrl(site.collections[c.collection]!, c.path);
+		} catch {
+			return null;
+		}
+	};
+	const changed = new Set(files);
+	for (const [old, moved] of records) {
+		if (old === moved || !changed.has(old) || !changed.has(moved) || from.has(moved) || to.has(old)) continue;
+		if (read(old) !== null || read(moved) === null) continue;
+		const fromUrl = urlOf(old);
+		const toUrl = urlOf(moved);
+		if (!fromUrl || !toUrl) continue;
+		from.set(moved, fromUrl);
+		to.set(old, toUrl);
+	}
+	return { from, to };
+}
+
+/** A file's title for messages: the document's `title`, else its name title-cased. */
+export function titleOf(file: string, text: string | null): string {
+	if (text !== null) {
+		try {
+			const t = (JSON.parse(text) as { title?: unknown } | null)?.title;
+			if (typeof t === 'string' && t.trim()) return t.trim();
+		} catch {
+			/* not JSON: use the name */
+		}
+	}
+	const name = file.split('/').pop()!.replace(/\.json$/, '');
+	return name.replace(/[-_]+/g, ' ').replace(/^./, (c) => c.toUpperCase());
+}