caracms 0.2.0 → 0.3.0

package/src/live/locks.ts

@@ -28,11 +28,16 @@
  *
  * **Presence** (`caracms:presence`, a hash by tab): each poll records the person and the
  * document their tab has open; someone is "on" a document while a tab of theirs
- * polled with it in the last `presenceMs`.
+ * polled with it within that record's hold: twice the tab's poll interval plus 3 s
+ * (Redis diet Decision 9), so a slow tab stays on and a closed fast one goes quickly.
+ *
+ * **The status cache** (status-cache.ts, Redis diet Decision 2): every write here tells
+ * it what landed, so the status poll can read locks and presence from memory.
  */
 import type { LockState, LockView, PresenceView } from '../editor/types.ts';
 import type { Person } from './messages.ts';
 import type { RedisClient } from './redis.ts';
+import { landed, type StatusCache } from './status-cache.ts';
 import type { LiveTimings } from './timings.ts';
 
 export interface LockRecord {
@@ -48,7 +53,7 @@ export interface LockRecord {
 	deleted?: true;
 }
 
-interface ReadLock {
+export interface ReadLock {
 	raw: string;
 	lock: LockRecord;
 }
@@ -57,11 +62,16 @@ interface PresenceRecord {
 	person: Person;
 	file: string | null;
 	at: number;
+	/** ms the record holds after `at` (Redis diet Decision 9). Absent (written before it was added): `presenceMs`. */
+	hold?: number;
 }
 
 /** How long a releasing lock with no autosave yet waits for the tab's last write. */
 export const RELEASE_GRACE_MS = 5_000;
 
+/** Redis diet Decision 9: a presence record holds for twice the tab's poll interval plus this. */
+export const PRESENCE_SLACK_MS = 3_000;
+
 const sameEmail = (a: Person, b: Person) => a.email.toLowerCase() === b.email.toLowerCase();
 
 export type AcquireResult = { ok: true; lock: LockRecord } | { ok: false; lock: LockRecord };
@@ -73,17 +83,38 @@ export class Locks {
 	readonly prefix: string;
 	/** Whether the document has an autosave not yet committed. */
 	private readonly pending: (file: string) => Promise<boolean>;
+	private readonly cache: StatusCache | null;
 
-	constructor(redis: RedisClient, timings: LiveTimings, now: () => number, pending: (file: string) => Promise<boolean>, prefix = 'caracms:') {
+	constructor(
+		redis: RedisClient,
+		timings: LiveTimings,
+		now: () => number,
+		pending: (file: string) => Promise<boolean>,
+		prefix = 'caracms:',
+		cache: StatusCache | null = null,
+	) {
 		this.redis = redis;
 		this.timings = timings;
 		this.now = now;
 		this.pending = pending;
 		this.prefix = prefix;
+		this.cache = cache;
 	}
 
 	key = (file: string) => `${this.prefix}lock:${file}`;
-	private presenceKey = () => `${this.prefix}presence`;
+	/** What every lock key starts with (the status cache scans it). */
+	get keyPrefix(): string {
+		return this.key('');
+	}
+	readonly presenceKey = () => `${this.prefix}presence`;
+
+	/** A compare-and-swap on a lock key, and the status cache told what came of it. */
+	private async swap(file: string, expected: string | null, raw: string): Promise<boolean> {
+		const ok = await landed(this.cache, this.key(file), () => this.redis.compareAndSet(this.key(file), expected, raw, { px: this.timings.autosaveTtlMs }));
+		if (ok) this.cache?.string(this.key(file), raw);
+		else this.cache?.drop(this.key(file));
+		return ok;
+	}
 
 	private parse(raw: string | null): ReadLock | null {
 		if (raw === null) return null;
@@ -101,14 +132,19 @@ export class Locks {
 
 	/** Every lock key: one SCAN and one MGET. */
 	async all(): Promise<Map<string, ReadLock>> {
-		const keys = await this.redis.scan(`${this.prefix}lock:*`);
-		const out = new Map<string, ReadLock>();
-		if (keys.length === 0) return out;
+		const keys = await this.redis.scan(`${this.keyPrefix}*`);
+		if (keys.length === 0) return new Map();
 		const raws = await this.redis.mget(keys);
-		keys.forEach((k, i) => {
-			const read = this.parse(raws[i] ?? null);
-			if (read) out.set(k.slice(this.key('').length), read);
-		});
+		return this.allFrom(keys.map((k, i) => [k, raws[i] ?? null]));
+	}
+
+	/** The locks among these keys and values (a scan of `keyPrefix`), by file. */
+	allFrom(entries: Iterable<readonly [string, string | null]>): Map<string, ReadLock> {
+		const out = new Map<string, ReadLock>();
+		for (const [k, raw] of entries) {
+			const read = this.parse(raw);
+			if (read) out.set(k.slice(this.keyPrefix.length), read);
+		}
 		return out;
 	}
 
@@ -125,7 +161,7 @@ export class Locks {
 	}
 
 	private put(file: string, expected: string | null, lock: LockRecord): Promise<boolean> {
-		return this.redis.compareAndSet(this.key(file), expected, JSON.stringify(lock), { px: this.timings.autosaveTtlMs });
+		return this.swap(file, expected, JSON.stringify(lock));
 	}
 
 	private static mine(lock: LockRecord, tab: string, person: Person) {
@@ -161,18 +197,32 @@ export class Locks {
 	 * is still here), except for a lock the tab's own delete released. A lapsed lock that still names this tab is re-taken (a tab back
 	 * from hidden). Nothing is taken that the tab never held.
 	 */
-	async beat(file: string, tab: string, person: Person): Promise<ReadLock | null> {
+	async beat(file: string, tab: string, person: Person, known?: ReadLock | null): Promise<ReadLock | null> {
 		for (let attempt = 0; attempt < 3; attempt++) {
-			const cur = await this.read(file);
+			// `known`: the lock as the status cache has it, the first try's expected value (Redis diet Decision 6).
+			const cur = attempt === 0 && known !== undefined ? known : await this.read(file);
 			if (!cur || !Locks.mine(cur.lock, tab, person)) return cur;
 			// A poll in flight when the tab deleted the document must not un-release its lock (M5a).
 			const next = { ...cur.lock, beat: this.now(), releasing: cur.lock.deleted ? cur.lock.releasing : null };
 			const raw = JSON.stringify(next);
-			if (await this.redis.compareAndSet(this.key(file), cur.raw, raw, { px: this.timings.autosaveTtlMs })) return { raw, lock: next };
+			if (await this.swap(file, cur.raw, raw)) return { raw, lock: next };
 		}
 		return this.read(file);
 	}
 
+	/**
+	 * Redis diet Decision 6: does the status poll need to beat for this tab? Only when the
+	 * lock (as the cache has it) is the tab's own and its last beat is `beatEveryMs` old
+	 * (a lapsed one is older still: it's taken back), or it's marked releasing and not
+	 * deleted (a tab back from `pagehide`: the beat clears it). A lock that isn't the
+	 * tab's, or none, needs no beat: the beat takes nothing the tab never held.
+	 */
+	needsBeat(cached: ReadLock | null, tab: string, person: Person): boolean {
+		if (!cached || !Locks.mine(cached.lock, tab, person)) return false;
+		if (cached.lock.releasing !== null && !cached.lock.deleted) return true;
+		return this.now() - cached.lock.beat >= this.timings.beatEveryMs;
+	}
+
 	/** Edit here: move your own lock to this tab at once, or take a free one. Someone else's refuses. */
 	async take(file: string, tab: string, person: Person): Promise<AcquireResult> {
 		for (let attempt = 0; attempt < 5; attempt++) {
@@ -218,7 +268,10 @@ export class Locks {
 	/** Delete a lock that no longer holds (the sweep, after a commit). */
 	async dropIfFree(file: string): Promise<void> {
 		const cur = await this.read(file);
-		if (cur && !(await this.live(cur, file))) await this.redis.compareAndDelete(this.key(file), cur.raw);
+		if (cur && !(await this.live(cur, file))) {
+			if (await landed(this.cache, this.key(file), () => this.redis.compareAndDelete(this.key(file), cur.raw))) this.cache?.string(this.key(file), null);
+			else this.cache?.drop(this.key(file));
+		}
 	}
 
 	view(file: string, lock: LockRecord, tab: string | null, person: Person): LockView {
@@ -238,19 +291,28 @@ export class Locks {
 
 	// ── Presence ────────────────────────────────────────────────────────────────
 
-	/** Record a poll: this tab, this person, this document (or none). */
-	async present(tab: string, person: Person, file: string | null): Promise<void> {
-		const record: PresenceRecord = { person, file, at: this.now() };
-		await this.redis.hset(this.presenceKey(), { [tab]: JSON.stringify(record) });
+	/**
+	 * Record a poll: this tab, this person, this document (or none). `intervalMs`: how long
+	 * until the tab's next poll; the record holds for twice that plus 3 s (Decision 9).
+	 */
+	async present(tab: string, person: Person, file: string | null, intervalMs = this.timings.pollMs): Promise<void> {
+		const record: PresenceRecord = { person, file, at: this.now(), hold: 2 * intervalMs + PRESENCE_SLACK_MS };
+		const fields = { [tab]: JSON.stringify(record) };
+		await landed(this.cache, this.presenceKey(), () => this.redis.hset(this.presenceKey(), fields));
+		this.cache?.hash(this.presenceKey(), fields);
 	}
 
-	/** Who is on which document now (polled with it in the last `presenceMs`). Long-gone tabs are pruned. */
+	/** Who is on which document now (polled with it within the record's hold). Long-gone tabs are pruned. */
 	async presence(): Promise<PresenceView[]> {
-		const all = await this.redis.hgetall(this.presenceKey());
+		return this.presenceFrom(Object.entries(await this.redis.hgetall(this.presenceKey())));
+	}
+
+	/** `presence()` over the hash's fields as read (the status cache's, on a poll). */
+	async presenceFrom(fields: Iterable<readonly [string, string]>): Promise<PresenceView[]> {
 		const now = this.now();
 		const byFile = new Map<string, Person[]>();
 		const gone: string[] = [];
-		for (const [tab, raw] of Object.entries(all)) {
+		for (const [tab, raw] of fields) {
 			let r: PresenceRecord;
 			try {
 				r = JSON.parse(raw) as PresenceRecord;
@@ -258,8 +320,9 @@ export class Locks {
 				gone.push(tab);
 				continue;
 			}
-			if (now - r.at > this.timings.presenceMs) {
-				if (now - r.at > this.timings.lockLapseMs) gone.push(tab);
+			const hold = typeof r.hold === 'number' ? r.hold : this.timings.presenceMs;
+			if (now - r.at > hold) {
+				if (now - r.at > Math.max(hold, this.timings.lockLapseMs)) gone.push(tab);
 				continue;
 			}
 			if (!r.file) continue;
@@ -267,7 +330,10 @@ export class Locks {
 			if (!people.some((p) => sameEmail(p, r.person))) people.push(r.person);
 			byFile.set(r.file, people);
 		}
-		if (gone.length) await this.redis.hdel(this.presenceKey(), ...gone);
+		if (gone.length) {
+			await landed(this.cache, this.presenceKey(), () => this.redis.hdel(this.presenceKey(), ...gone));
+			this.cache?.hash(this.presenceKey(), {}, gone);
+		}
 		return [...byFile].map(([file, people]) => ({ file, people }));
 	}
 }

package/src/live/mode.ts

@@ -1,13 +1,16 @@
 /**
  * Which mode the editor runs in, read from the environment (M4 Decision 1).
  *
- * - **Local mode**: `astro dev` with no `GITHUB_APP_ID`. M3's editor, files on disk.
- * - **Live mode**: whenever the App is configured, and **always on a production
- *   server**. It needs `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`, the repo
- *   (`RAILWAY_GIT_REPO_OWNER` and `RAILWAY_GIT_REPO_NAME`, or `GITHUB_REPO=owner/name`;
- *   Decision 3), `CARACMS_SECRET`, and `REDIS_URL` in production (dev may use the
- *   stand-in). A production server missing any of them still serves the public site;
- *   `/admin` answers 503 naming them (Phase 2 builds that from `missing`).
+ * - **Local mode**: `astro dev` with no GitHub credentials (`GITHUB_APP_ID` or
+ *   `CARACMS_GITHUB_TOKEN`). M3's editor, files on disk.
+ * - **Live mode**: whenever a credential is configured, and **always on a production
+ *   server**. It needs one GitHub credential (a fine-grained token, or the App's
+ *   `GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY`; runs-anywhere Decisions 3–4), the repo
+ *   (`GITHUB_REPO=owner/name`, or Railway's `RAILWAY_GIT_REPO_OWNER` and
+ *   `RAILWAY_GIT_REPO_NAME`; Decision 6), `CARACMS_SECRET`, `REDIS_URL` and the site's
+ *   `https://` address in production (dev may use the stand-in Redis). A production
+ *   server missing any of them still serves the public site; `/admin` answers 503
+ *   naming them (Phase 2 builds that from `missing`).
  * - **The in-memory GitHub** (Decision 2): `CARACMS_GITHUB=memory`, for tests and local
  *   browser runs, never against the site's own repo. It's live mode with no App and
  *   no repo, and it's **refused in production**.
@@ -19,9 +22,10 @@ import { DEFAULT_BRANCHES, type BranchNames } from './branches.ts';
 import { DEFAULT_TIMINGS, type LiveTimings } from './timings.ts';
 
 export interface LiveSettings {
-	/** `memory`: the in-memory GitHub backend (Decision 2). */
+	/** `memory`: the in-memory GitHub backend (Decision 2). `token`: CARACMS_GITHUB_TOKEN (runs-anywhere Decision 3). */
 	github:
 		| { kind: 'app'; appId: string; privateKey: string; owner: string; repo: string }
+		| { kind: 'token'; token: string; owner: string; repo: string }
 		| { kind: 'memory' };
 	/** Null in dev without REDIS_URL: the in-memory stand-in. */
 	redisUrl: string | null;
@@ -31,12 +35,22 @@ export interface LiveSettings {
 	allow: string[];
 	/** GITHUB_WEBHOOK_SECRET; null means the webhook route answers 404 (Decision 14). */
 	webhookSecret: string | null;
-	/** Try again (Decision 12): all three, or null. */
+	/** Try again through Railway's API (Decision 12): all three, or null. */
 	railway: { token: string; serviceId: string; environmentId: string } | null;
+	/** Try again through a deploy hook (runs-anywhere Decision 11): CARACMS_DEPLOY_HOOK_URL. A secret: never logged or sent to the browser. */
+	deployHook?: string | null;
+	/**
+	 * The site's public origin (runs-anywhere Decision 7): Astro's `site` (baked at build,
+	 * SITE_URL at build included), then SITE_URL, then RAILWAY_PUBLIC_DOMAIN. Never null
+	 * in production live mode; missing (a test's settings) means unknown.
+	 */
+	address?: string | null;
 	/** CARACMS_BACKUP_USER and CARACMS_BACKUP_PASSWORD, both or neither (Phase 3 checks the length). */
 	backup: { user: string; password: string } | null;
-	/** CARACMS_RUNNING_COMMIT, else RAILWAY_GIT_COMMIT_SHA; null with no deploy pipeline (Decision 12). */
+	/** The running commit at start (runs-anywhere Decision 9, `runningCommitFrom`); null with none known. */
 	runningCommit: string | null;
+	/** The commit baked in at build (`Baked.commit`); status reads the running commit afresh from it and the environment. */
+	bakedCommit?: string | null;
 	/** Dev only: CARACMS_TIMINGS, a JSON object of LiveTimings to shorten (Decision 2). */
 	timings: LiveTimings;
 	/**
@@ -56,17 +70,90 @@ export type Mode =
 
 type Env = Record<string, string | undefined>;
 
+/** What the build baked in (the integration's defines; editor/server/mode.ts passes them). */
+export interface Baked {
+	/** Astro's `site` at build: the config's, or SITE_URL's (M6 Decision 3). */
+	site?: string | null;
+	/** The commit the build was made from (runs-anywhere Decision 9). */
+	commit?: string | null;
+}
+
+// The sentences the configuration problems print, kept here so the docs can quote them.
+export const BOTH_CREDENTIALS_PROBLEM =
+	'Both a GitHub App (GITHUB_APP_ID) and a token (CARACMS_GITHUB_TOKEN) are set: set one of them, not both.';
+export const CLASSIC_TOKEN_PROBLEM =
+	'CARACMS_GITHUB_TOKEN is a classic token, which reaches every repo its owner can: use a fine-grained token (it starts with github_pat_) with access to this site\'s repo only.';
+export const NOT_FINE_GRAINED_PROBLEM = 'CARACMS_GITHUB_TOKEN must be a fine-grained token: it starts with github_pat_.';
+export const NO_ADDRESS_PROBLEM =
+	"The site's public address isn't known: set SITE_URL to it, like https://fernhill.ie, both when the site is built and when it runs. Without it, sign-in links can't be sent and the editor's saves are refused.";
+export const HTTP_ADDRESS_PROBLEM = (address: string) =>
+	`The site's address (${address}) is http://, but signing in needs https://: the session cookie is only ever sent over https. Set SITE_URL to the https:// address (http:// works for localhost only).`;
+export const BOTH_REDEPLOYERS_PROBLEM =
+	'Both CARACMS_DEPLOY_HOOK_URL and CARACMS_RAILWAY_TOKEN are set: Try again redeploys through one of them, so set only one.';
+
+/** The prefixes of GitHub's classic tokens (`ghp_` and the OAuth, user-to-server, server-to-server and refresh ones). */
+const CLASSIC_TOKEN = /^(ghp|gho|ghu|ghs|ghr)_/;
+
+/** On Railway: it sets these on every service (the gate detects the host the same way). */
+const onRailway = (env: Env) => Boolean(env.RAILWAY_ENVIRONMENT_ID?.trim() || env.RAILWAY_GIT_REPO_OWNER?.trim() || env.RAILWAY_GIT_REPO_NAME?.trim());
+
+/**
+ * The hosts' commit variables, in order (runs-anywhere Decision 9): Railway's, Render's,
+ * Coolify's. The build bakes the first one set (or `git rev-parse HEAD`).
+ */
+export const HOST_COMMIT_VARIABLES = ['RAILWAY_GIT_COMMIT_SHA', 'RENDER_GIT_COMMIT', 'SOURCE_COMMIT'] as const;
+
+/**
+ * The running commit (runs-anywhere Decision 9): CARACMS_RUNNING_COMMIT, then a host's
+ * variable, then the commit baked in at build. A value at run time wins over the baked
+ * one; the in-memory GitHub ignores the baked one (it's this repo's, which the in-memory
+ * repo never has). Null with none known.
+ */
+export function runningCommitFrom(env: Env, baked: string | null | undefined): string | null {
+	for (const name of ['CARACMS_RUNNING_COMMIT', ...HOST_COMMIT_VARIABLES]) {
+		const v = env[name]?.trim();
+		if (v) return v;
+	}
+	if (env.CARACMS_GITHUB?.trim() === 'memory') return null;
+	return baked?.trim() || null;
+}
+
+/**
+ * The site's public origin (runs-anywhere Decision 7): Astro's `site` as built, then
+ * SITE_URL, then Railway's public domain. Null when none is set or SITE_URL doesn't parse
+ * (the build already warned).
+ */
+export function addressFrom(env: Env, bakedSite: string | null | undefined): string | null {
+	for (const raw of [bakedSite, env.SITE_URL]) {
+		const v = raw?.trim();
+		if (!v) continue;
+		try {
+			const url = new URL(v);
+			if (url.protocol === 'https:' || url.protocol === 'http:') return url.origin;
+		} catch {
+			/* the next one */
+		}
+	}
+	const railway = env.RAILWAY_PUBLIC_DOMAIN?.trim();
+	return railway ? `https://${railway}` : null;
+}
+
+const isLocalhost = (host: string) => host === 'localhost' || host.endsWith('.localhost') || host === '127.0.0.1' || host === '[::1]';
+
 /**
  * Read the mode. `production` is whether this is a production server (the
  * integration knows: not `astro dev`); it defaults to `NODE_ENV === 'production'`.
+ * `baked` is what the build baked in (the address and the commit).
  */
-export function readMode(env: Env = process.env, production = env.NODE_ENV === 'production'): Mode {
+export function readMode(env: Env = process.env, production = env.NODE_ENV === 'production', baked: Baked = {}): Mode {
 	const get = (name: string) => {
 		const v = env[name]?.trim();
 		return v ? v : null;
 	};
 	const memory = get('CARACMS_GITHUB') === 'memory';
-	if (!production && !memory && !get('GITHUB_APP_ID')) return { kind: 'local' };
+	// Never GITHUB_TOKEN (Decision 4): the gh CLI and GitHub Actions export it.
+	const ghToken = get('CARACMS_GITHUB_TOKEN');
+	if (!production && !memory && !get('GITHUB_APP_ID') && !ghToken) return { kind: 'local' };
 
 	const missing: string[] = [];
 	const problems: string[] = [];
@@ -82,15 +169,38 @@ export function readMode(env: Env = process.env, production = env.NODE_ENV === '
 
 	let github: LiveSettings['github'] = { kind: 'memory' };
 	if (!memory || production) {
-		const appId = need('GITHUB_APP_ID');
-		const privateKey = need('GITHUB_APP_PRIVATE_KEY');
+		const appId = get('GITHUB_APP_ID');
 		const repo = readRepo(env, problems);
-		if (!repo) missing.push('RAILWAY_GIT_REPO_OWNER and RAILWAY_GIT_REPO_NAME (or GITHUB_REPO)');
-		github = { kind: 'app', appId, privateKey, owner: repo?.owner ?? '', repo: repo?.repo ?? '' };
+		const owner = repo?.owner ?? '';
+		const name = repo?.repo ?? '';
+		if (appId && ghToken) problems.push(BOTH_CREDENTIALS_PROBLEM);
+		if (ghToken) {
+			if (CLASSIC_TOKEN.test(ghToken)) problems.push(CLASSIC_TOKEN_PROBLEM);
+			else if (!ghToken.startsWith('github_pat_')) problems.push(NOT_FINE_GRAINED_PROBLEM);
+			github = { kind: 'token', token: ghToken, owner, repo: name };
+		} else if (appId) {
+			github = { kind: 'app', appId, privateKey: need('GITHUB_APP_PRIVATE_KEY'), owner, repo: name };
+		} else {
+			missing.push('CARACMS_GITHUB_TOKEN (or GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY)');
+		}
+		if (!repo && !problems.some((p) => p.startsWith('GITHUB_REPO'))) {
+			missing.push(onRailway(env) ? 'RAILWAY_GIT_REPO_OWNER and RAILWAY_GIT_REPO_NAME (or GITHUB_REPO)' : 'GITHUB_REPO');
+		}
 	}
 	const secret = need('CARACMS_SECRET');
 	const redisUrl = production ? need('REDIS_URL') : get('REDIS_URL');
 
+	// The address (Decision 7): known, and https:// (but for localhost), in production.
+	const address = addressFrom(env, baked.site);
+	if (production && !address) problems.push(NO_ADDRESS_PROBLEM);
+	if (production && address && address.startsWith('http:') && !isLocalhost(new URL(address).hostname)) problems.push(HTTP_ADDRESS_PROBLEM(address));
+
+	const deployHook = get('CARACMS_DEPLOY_HOOK_URL');
+	if (deployHook) {
+		if (get('CARACMS_RAILWAY_TOKEN')) problems.push(BOTH_REDEPLOYERS_PROBLEM);
+		if (!/^https?:\/\//i.test(deployHook)) problems.push('CARACMS_DEPLOY_HOOK_URL must be the hook\'s https:// address.');
+	}
+
 	const token = get('CARACMS_RAILWAY_TOKEN');
 	const serviceId = get('RAILWAY_SERVICE_ID');
 	const environmentId = get('RAILWAY_ENVIRONMENT_ID');
@@ -119,8 +229,11 @@ export function readMode(env: Env = process.env, production = env.NODE_ENV === '
 				.filter(Boolean),
 			webhookSecret: get('GITHUB_WEBHOOK_SECRET'),
 			railway: token && serviceId && environmentId ? { token, serviceId, environmentId } : null,
+			deployHook,
+			address,
 			backup: user && password ? { user, password } : null,
-			runningCommit: get('CARACMS_RUNNING_COMMIT') ?? get('RAILWAY_GIT_COMMIT_SHA'),
+			runningCommit: runningCommitFrom(env, baked.commit),
+			bakedCommit: baked.commit ?? null,
 			timings,
 			branches,
 			production,
@@ -164,7 +277,7 @@ function isBranchName(name: string): boolean {
 	);
 }
 
-/** The repo: GITHUB_REPO overrides Railway's own variables (Decision 3). */
+/** The repo: GITHUB_REPO overrides Railway's own variables (M4 Decision 3; runs-anywhere Decision 6). */
 function readRepo(env: Env, problems: string[]): { owner: string; repo: string } | null {
 	const override = env.GITHUB_REPO?.trim();
 	if (override) {

package/src/live/notices.ts

@@ -0,0 +1,100 @@
+/**
+ * The editor's notices in Redis (M4 Decision 7 and 10 step 1), in one place so the
+ * status cache hears of every write (Redis diet Decision 2).
+ *
+ * - **"Published as it stood"** (`caracms:notices`, a hash by notice id): Publish leaves
+ *   one for each person who had a published document open; dismissing it deletes it.
+ * - **Dismissed "draft kept" notices** (`caracms:dismissed`, a set of ids): those are
+ *   shared, worked out from git (`git.keptDraftNotices()`), so a dismissal is remembered
+ *   here; a new conflict has a new id and shows again.
+ *
+ * Both expire a week after their last write (`autosaveTtlMs`), as a backstop.
+ */
+import type { NoticeView } from '../editor/types.ts';
+import type { Person } from './messages.ts';
+import type { RedisClient } from './redis.ts';
+import { landed, type StatusCache } from './status-cache.ts';
+import type { LiveTimings } from './timings.ts';
+
+/** "Aoife published Home as it stood at 14:20", for one person. */
+export interface StoodNotice {
+	id: string;
+	/** The person it's for, lower-cased. */
+	for: string;
+	file: string;
+	title: string;
+	by: Person;
+	at: string;
+}
+
+export class Notices {
+	readonly redis: RedisClient;
+	readonly timings: LiveTimings;
+	private readonly cache: StatusCache | null;
+	readonly noticesKey: string;
+	readonly dismissedKey: string;
+
+	constructor(redis: RedisClient, timings: LiveTimings, prefix = 'caracms:', cache: StatusCache | null = null) {
+		this.redis = redis;
+		this.timings = timings;
+		this.cache = cache;
+		this.noticesKey = `${prefix}notices`;
+		this.dismissedKey = `${prefix}dismissed`;
+	}
+
+	/** Leave these "published as it stood" notices. */
+	async addStood(notices: readonly StoodNotice[]): Promise<void> {
+		if (notices.length === 0) return;
+		const fields = Object.fromEntries(notices.map((n) => [n.id, JSON.stringify(n)]));
+		await landed(this.cache, this.noticesKey, () => this.redis.hset(this.noticesKey, fields));
+		this.cache?.hash(this.noticesKey, fields);
+		await this.redis.pexpire(this.noticesKey, this.timings.autosaveTtlMs);
+	}
+
+	/** A "published as it stood" notice is done with. */
+	async remove(id: string): Promise<void> {
+		await landed(this.cache, this.noticesKey, () => this.redis.hdel(this.noticesKey, id));
+		this.cache?.hash(this.noticesKey, {}, [id]);
+	}
+
+	/** A shared "draft kept" notice was dismissed. */
+	async dismiss(id: string): Promise<void> {
+		await landed(this.cache, this.dismissedKey, () => this.redis.sadd(this.dismissedKey, id));
+		this.cache?.add(this.dismissedKey, id);
+		await this.redis.pexpire(this.dismissedKey, this.timings.autosaveTtlMs);
+	}
+
+	/** This person's notices, read from Redis now. `kept` and `titleFor` are git's (`keptDraftNotices`, `titleFor`). */
+	async of(person: Person, kept: readonly { file: string; commit: string }[], titleFor: (file: string) => string): Promise<NoticeView[]> {
+		const [dismissed, stood] = await this.redis.batch([
+			['smembers', this.dismissedKey],
+			['hgetall', this.noticesKey],
+		] as const);
+		return Notices.forPerson(person, kept, titleFor, new Set(dismissed), Object.values(stood));
+	}
+
+	/** This person's notices from what was read: the dismissed ids, and the stood notices' values. */
+	static forPerson(
+		person: Person,
+		kept: readonly { file: string; commit: string }[],
+		titleFor: (file: string) => string,
+		dismissed: ReadonlySet<string>,
+		stood: Iterable<string>,
+	): NoticeView[] {
+		const out: NoticeView[] = [];
+		for (const n of kept) {
+			const id = `kept:${n.file}:${n.commit}`;
+			if (!dismissed.has(id)) out.push({ id, kind: 'draft-kept', file: n.file, title: titleFor(n.file) });
+		}
+		const email = person.email.toLowerCase();
+		for (const raw of stood) {
+			try {
+				const n = JSON.parse(raw) as StoodNotice;
+				if (n.for === email) out.push({ id: n.id, kind: 'published-as-it-stood', file: n.file, title: n.title, by: n.by, at: n.at });
+			} catch {
+				/* skip */
+			}
+		}
+		return out;
+	}
+}