@michaelthielemann/kestrel 1.6.0 → 2.0.0

package/layers/public/server/api/publish-status.get.ts

@@ -2,6 +2,7 @@ import { eq, getTableColumns } from 'drizzle-orm'
 import type { AnySQLiteTable } from 'drizzle-orm/sqlite-core'
 import { publishStatus } from '../database/publish-status'
 import { routeForRecord } from '../utils/publish/route-for-record'
+import { hasPendingChanges } from '../utils/publish/pending'
 
 /**
  * Admin-only read of the LIVE publish state of a record's static page (`?collection=&id=`). Admin-only by
@@ -17,28 +18,41 @@ export default defineEventHandler((event) => {
   // (`driver`) and whether the runtime publisher actually produces files HERE (prod + `output.auto`). In dev
   // (or with auto off) nothing is ever generated, so the lamp shows a calm "Not built" instead of a stuck
   // "Generating". Read straight from runtimeConfig — no need to pull in the whole publisher module.
-  const output = (useRuntimeConfig().kestrel as { output?: { driver?: 'local' | 's3'; auto?: boolean } }).output
-  const env = { driver: (output?.driver ?? 'local') as 'local' | 's3', generates: !import.meta.dev && !!output?.auto }
+  const output = (useRuntimeConfig().kestrel as { output?: { driver?: 'local' | 's3'; auto?: boolean; publishOnSave?: boolean } }).output
+  // `publishOnSave` also tells the editor whether to offer a Publish button at all: with the split turned
+  // off there is nothing left for it to do.
+  const publishOnSave = !!output?.publishOnSave
+  const env = { driver: (output?.driver ?? 'local') as 'local' | 's3', generates: !import.meta.dev && !!output?.auto, publishOnSave }
 
   const q = getQuery(event)
   const name = typeof q.collection === 'string' ? q.collection : ''
   const id = Number(typeof q.id === 'string' ? q.id : NaN)
   const c = getCollection(name)
-  if (!c || !c.def.pageLike || !Number.isInteger(id) || id <= 0) return { route: null, status: null, ...env }
+  if (!c || !c.def.pageLike || !Number.isInteger(id) || id <= 0) return { route: null, status: null, pending: false, neverPublished: false, ...env }
 
   const db = useDb()
   const table = c.table as AnySQLiteTable
   const cols = getTableColumns(table) as Record<string, never>
-  const row = db.select().from(table).where(eq(cols.id, id)).get() as { path?: unknown; locale?: unknown } | undefined
+  const row = db.select().from(table).where(eq(cols.id, id)).get() as { path?: unknown; locale?: unknown; updatedAt?: unknown } | undefined
   const route = routeForRecord(row, true, primaryLocale(), prefixPrimaryLocale())
-  if (!route) return { route: null, status: null, ...env }
+  if (!route) return { route: null, status: null, pending: false, neverPublished: false, ...env }
 
+  // Saved after it was last published: with publishing deferred to an explicit action, that is the normal
+  // working state of a page being edited — the live file is the previous version until someone publishes.
+  const savedAt = row?.updatedAt instanceof Date ? row.updatedAt.getTime() : null
   try {
     const st = db.select().from(publishStatus).where(eq(publishStatus.route, route)).get()
-    if (!st) return { route, status: null, ...env }
-    return { route, status: st.status, error: st.error, updatedAt: st.updatedAt, target: st.target, ...env }
+    // A routable page with no row was never published. Before the split that was indistinguishable from
+    // "a publish is running" — a save always enqueued one — but now nothing is in flight and nothing will be
+    // until someone presses Publish, so the lamp must not claim progress that is not happening.
+    if (!st) return { route, status: null, pending: false, neverPublished: true, ...env }
+    // With the split off, a save republishes on its own, so a newer save means a republish is in flight —
+    // reporting that as "unpublished changes" would ask the user to act on something already happening.
+    const pending = !publishOnSave && hasPendingChanges(savedAt, st.updatedAt instanceof Date ? st.updatedAt.getTime() : null)
+    return { route, status: st.status, error: st.error, updatedAt: st.updatedAt, target: st.target, pending, neverPublished: false, ...env }
   } catch {
-    // publish_status not migrated yet → treat as "no status" rather than a 500.
-    return { route, status: null, ...env }
+    // publish_status not migrated yet → treat as "no status" rather than a 500. Not "never published"
+    // either: the table is unreadable, so the page's real state is unknown, not known to be absent.
+    return { route, status: null, pending: false, neverPublished: false, ...env }
   }
 })

package/layers/public/server/api/publish.post.ts

@@ -0,0 +1,84 @@
+import { inArray, getTableColumns } from 'drizzle-orm'
+import type { AnySQLiteTable } from 'drizzle-orm/sqlite-core'
+import { MAX_BULK_IDS } from '../../../core/app/utils/list-limits'
+import { classifyWrite, planInvalidation } from '../utils/publish/invalidation'
+import { staleRoutes } from '../utils/publish/deps'
+import { usePublishRuntime } from '../utils/publish/publish-runtime'
+import { allPublishedRoutes } from '../utils/publish/publisher'
+
+/**
+ * Publish records: write their static files (and everything whose baked output embeds them) to the
+ * configured output — the deliberate second half of the split ADR-0008 introduced. Saving persists to the
+ * DB and leaves the live site alone; THIS is what changes what visitors see.
+ *
+ *   body: { collection: string, ids?: number[], id?: number }
+ *   200:  { queued, generates, routes, pruned, drafts }
+ *
+ * The record's publish INTENT (`status`) is not touched here — that is a field the editor saves like any
+ * other, so a page goes live by being published while published. A draft is therefore reported back
+ * (`drafts`) rather than silently promoted: it has no public output to write.
+ *
+ * All-or-nothing on lookup (an unknown id 404s before anything is enqueued), like the bulk write actions.
+ */
+export default defineEventHandler(async (event) => {
+  requireAdmin(event) // write-authorization backstop (defense-in-depth; see require-admin.ts)
+  const body = await readBody(event)
+  const name = typeof (body as { collection?: unknown })?.collection === 'string' ? (body as { collection: string }).collection : ''
+  const c = getCollection(name)
+  if (!c) throw createError({ statusCode: 404, statusMessage: `Unknown collection: ${name}` })
+
+  const raw = (body as { ids?: unknown; id?: unknown })?.ids ?? [(body as { id?: unknown })?.id]
+  const ids = parseIdList(raw, MAX_BULK_IDS)
+
+  const db = useDb()
+  const table = c.table as AnySQLiteTable
+  const cols = getTableColumns(table) as Record<string, never>
+  const rows = db.select().from(table).where(inArray(cols.id, ids)).all() as Record<string, unknown>[]
+  const found = new Set(rows.map((r) => r.id as number))
+  const missing = ids.filter((id) => !found.has(id))
+  if (missing.length) throw createError({ statusCode: 404, statusMessage: `${c.def.name} not found: ${missing.join(', ')}` })
+
+  // Where the next publish would go, and whether one happens here at all: in dev (or with `output.auto`
+  // off) there is no runtime publisher, and saying so is more useful than a queued run that never runs.
+  const output = (useRuntimeConfig().kestrel as { output?: { auto?: boolean } }).output
+  const runtime = usePublishRuntime()
+  const generates = !import.meta.dev && !!output?.auto && !!runtime
+
+  // The live route set answers "is this tracked route still somebody's page?" — the question a rename
+  // leaves open. `failed` means the enumeration was incomplete, and an incomplete read must never drive a
+  // delete (the standing rule from the 2026-07-25 audit), so the prune is skipped wholesale.
+  const liveNow = runtime ? allPublishedRoutes() : { routes: [], failed: ['*'] }
+  const prunable = liveNow.failed.length === 0
+
+  const primary = primaryLocale()
+  const prefixPrimary = prefixPrimaryLocale()
+  const routes: string[] = []
+  const pruned: string[] = []
+  const drafts: number[] = []
+  let queued = false
+
+  for (const row of rows) {
+    // before === after: nothing about the record is changing, this is a re-render of its current state.
+    // A draft classifies as not-published, so `planInvalidation` returns a noop for it — reported below.
+    const ev = classifyWrite(c.def, row, row, primary, prefixPrimary)
+    const inv = planInvalidation(ev)
+    if (inv.type !== 'tags') {
+      drafts.push(row.id as number)
+      continue
+    }
+    // Abandoned URLs: routes the publisher baked FROM this record (tagged with its id) that no live page
+    // claims any more — in practice the old file a published rename left behind. Same rule a full publish
+    // applies globally, scoped to this record's tag; a referrer or listing carrying the tag is a live route
+    // and therefore never in this set.
+    const tagged = ev.id != null ? (runtime?.deps.routesForTags([`${c.def.name}:${ev.id}`]) ?? []) : []
+    const stale = prunable ? staleRoutes(tagged, liveNow.routes) : []
+    routes.push(...inv.render)
+    pruned.push(...stale)
+    if (runtime) {
+      runtime.queue.enqueue({ ...inv, prune: [...inv.prune, ...stale] })
+      queued = true
+    }
+  }
+
+  return { queued, generates, routes, pruned, drafts }
+})

package/layers/public/server/api/route.get.ts

@@ -14,13 +14,33 @@ export default defineEventHandler((event) => {
   const isStaticRender = import.meta.prerender === true || isRendererContext()
   const publishedOnly = isStaticRender || event.context.readScope !== 'all'
   const db = useDb()
-  const resolved = resolvePage(db, allCollections(), path, locale, publishedOnly)
+  const { page: resolved, failed } = resolvePage(db, allCollections(), path, locale, publishedOnly)
   // The site-wide head tier rides along on the fetch the page already awaits, so it reaches SSR and the
-  // prerender on a path that is known to work. Looked up through the registry, not imported, so a consumer
-  // that disables the collection gets `null` instead of a query against a table the schema never created.
-  // `depth: 1` resolves the sharing image into `$media`; `getSingleton` captures the read, so an edit
-  // re-publishes every route that embedded it.
+  // prerender on a path that is known to work. Looked up through the registry, not imported, so an
+  // installation whose registry never received the built-in simply has the tier off (`null`) instead of
+  // querying a table the schema never created. `depth: 1` resolves the sharing image into `$media`;
+  // `getSingleton` captures the read, so an edit re-publishes every route that embedded it.
   const siteCollection = getCollection('site')
-  const site = siteCollection ? getSingleton(db, siteCollection, locale, false, 1) : null
+  let site: ReturnType<typeof getSingleton> = null
+  let siteUnreadable = false
+  if (siteCollection) {
+    try { site = getSingleton(db, siteCollection, locale, false, 1) }
+    catch (error) {
+      // Registered but unreadable (its migration hasn't been run) — indistinguishable in the response from
+      // the off state above, so it joins the incomplete-read channel rather than degrading silently.
+      siteUnreadable = true
+      console.error('[kestrel] route: the site singleton could not be read:', (error as Error)?.message ?? error)
+    }
+  }
+  // One rule for every incomplete read: never answer 200. The publisher classifies a 200-with-body as a
+  // successful render, writes it over the live file and records success — so an unreadable page collection
+  // would bake the catch-all's empty document over a real page (the record may well live in the collection
+  // that failed, which is why this is not a 404), and an unreadable head tier would strip the composed
+  // title, default description and sharing image from every route it touches. Both are unrecoverable
+  // without a full re-publish and neither leaves a mark. A 5xx keeps the existing artifact and turns the
+  // editor's status red. The head tier is site-wide, so it fails the request even when a page did resolve.
+  if (siteUnreadable || (failed.length && !resolved)) {
+    throw createError({ statusCode: 503, statusMessage: 'Route lookup incomplete' })
+  }
   return { collection: resolved?.collection ?? null, page: resolved?.page ?? null, alternates: resolved?.alternates ?? [], site }
 })

package/layers/public/server/plugins/02.register-links.ts

@@ -3,10 +3,10 @@ import { buildLinkFieldPopulators } from '../utils/populate-links'
 import { resolveInternalHref } from '../utils/link-resolve'
 
 // Resolve internal links to the target record's localized public path at read time (page-like targets;
-// external/email/tel pass through). NOTE: the resolver does NOT status-gate the target — a link to a DRAFT
-// emits the draft's real (not-yet-generated) path, disclosing its slug and shipping a 404 until publish. This
-// is deliberate: it keeps links stable without re-rendering every referrer when a target's status flips, and
-// the editor warns about draft/dead links instead. (See link-resolve.ts for the rationale.)
+// external/email/tel pass through). The resolver IS status-gated: a link to a DRAFT resolves to nothing and
+// bakes `'#'`, so an unpublished slug never reaches published HTML. The href therefore encodes availability,
+// which is why flipping a target's status re-renders its referrers; the editor warns about the resulting
+// draft/dead links separately. (See link-resolve.ts.)
 //
 // Registered as `link` + `richtext` per-type populators; the shared field-tree walker dispatches them over
 // top-level fields, block props, slots, and repeater entries.

package/layers/public/server/plugins/zz.publish.ts

@@ -1,8 +1,9 @@
 import { createPublishQueue } from '../utils/publish/queue'
+import { setPublishRuntime } from '../utils/publish/publish-runtime'
 import { DepsStore } from '../utils/publish/deps'
 import { createSqlitePersistence } from '../utils/publish/deps-persistence'
 import { outputDriver, publishInvalidation } from '../utils/publish/publisher'
-import { classifyWrite, planInvalidation } from '../utils/publish/invalidation'
+import { classifyWrite, planWrite } from '../utils/publish/invalidation'
 import { registerWriteListener } from '../../../core/server/utils/write-events'
 
 /**
@@ -15,11 +16,11 @@ import { registerWriteListener } from '../../../core/server/utils/write-events'
  *     DETACHED (`runNitroPlugins` is synchronous + unawaited; `localFetch` is already wired before plugins
  *     run + before the server listens), so it never blocks boot.
  *  3. RECONCILER — an optional periodic full publish (`output.reconcileMinutes`) self-heals any missed
- *     invalidation and picks up time-based `publishDate` publishing that no write event would trigger.
+ *     invalidation.
  */
 export default defineNitroPlugin(() => {
   if (import.meta.dev) return
-  const output = (useRuntimeConfig().kestrel as { output?: { auto?: boolean; reconcileMinutes?: number; verbose?: boolean } }).output
+  const output = (useRuntimeConfig().kestrel as { output?: { auto?: boolean; publishOnSave?: boolean; reconcileMinutes?: number; verbose?: boolean } }).output
   if (!output?.auto) return
 
   // `output.verbose`: on top of the one-line summary, itemise each incremental republish with a
@@ -48,8 +49,16 @@ export default defineNitroPlugin(() => {
     onError: (error) => console.error('[kestrel] publish run failed:', error),
   })
 
+  // The explicit publish action (`POST /api/publish`) enqueues through this same queue, so a publish and
+  // a write-driven prune are serialized by one single-flight run rather than racing each other.
+  setPublishRuntime({ queue, deps })
+
+  // A save writes the DB, not the site: by default only what a save must still REMOVE from the output (an
+  // unpublished or deleted record's page) passes through, and everything renderable waits for an explicit
+  // publish — see ADR-0008. `output.publishOnSave` restores the pre-2.0 model, where every write republished.
+  const publishOnSave = output.publishOnSave ?? false
   registerWriteListener(({ def, before, after }) => {
-    queue.enqueue(planInvalidation(classifyWrite(def, before, after, primaryLocale(), prefixPrimaryLocale())))
+    queue.enqueue(planWrite(classifyWrite(def, before, after, primaryLocale(), prefixPrimaryLocale()), publishOnSave))
   })
 
   // Boot publish goes THROUGH the queue (not a direct publishFull) so it shares the single-flight guard:

package/layers/public/server/routes/llms.txt.get.ts

@@ -44,8 +44,11 @@ export default defineEventHandler((event) => {
     let rows: Record<string, unknown>[]
     try {
       rows = db.select(proj as never).from(c.table).all() as Record<string, unknown>[]
-    } catch {
-      continue // table not migrated yet (e.g. a bare prerender DB)
+    } catch (error) {
+      // Skipping keeps a bare prerender DB publishable, but a drifted table drops the whole section — a
+      // silent gap the publisher would write straight over the live artifact.
+      console.error(`[kestrel] llms.txt: skipped collection ${c.def.name}:`, (error as Error)?.message ?? error)
+      continue
     }
     const entries: LlmsEntry[] = []
     for (const row of rows) {

package/layers/public/server/routes/sitemap.xml.get.ts

@@ -39,8 +39,11 @@ export default defineEventHandler((event) => {
     let rows: Record<string, unknown>[]
     try {
       rows = db.select(proj as never).from(c.table).all() as Record<string, unknown>[]
-    } catch {
-      continue // table not migrated yet (e.g. a bare prerender DB)
+    } catch (error) {
+      // Skipping keeps a bare prerender DB publishable, but a drifted table de-indexes every page of the
+      // collection — a silent gap the publisher would write straight over the live sitemap.
+      console.error(`[kestrel] sitemap.xml: skipped collection ${c.def.name}:`, (error as Error)?.message ?? error)
+      continue
     }
     for (const row of rows) {
       if (c.def.status && row.status !== 'published') continue

package/layers/public/server/tasks/publish/run.ts

@@ -5,7 +5,8 @@ import { createSqlitePersistence } from '../../utils/publish/deps-persistence'
 /**
  * The shared publish engine, exposed as a Nitro task. Renders every published page (+ sitemap/robots)
  * via the live server, mirrors `_nuxt`/assets, and always prunes the routes that left the published set
- * (output ≡ DB).
+ * (output ≡ DB). Like every full publish it HOLDS BACK routes with unpublished changes (ADR-0008) — a
+ * resync must not push work in progress live; those pages go out when they are published.
  *
  * Triggering (Nuxt 4.4 / Nitro 2.13 — there is NO `nuxi task run`):
  *   - dev:  GET http://localhost:3000/_nitro/tasks/publish:run   (the dev-only task route; plumbing smoke test)

package/layers/public/server/utils/link-resolve.ts

@@ -27,8 +27,11 @@ export function resolveInternalHref(collection: string, id: number, db = useDb()
   let row: Record<string, unknown> | undefined
   try {
     row = db.select().from(c.table).where(eq(cols.id, id)).get() as Record<string, unknown> | undefined
-  } catch {
-    return null // table not migrated yet (e.g. a bare prerender DB)
+  } catch (error) {
+    // Still null (a throw would 500 every page holding an internal link on a bare prerender DB), but the
+    // memo caches that null run-wide as "not linkable", so the dead link needs a trace to be diagnosable.
+    console.error(`[kestrel] resolveInternalHref: ${collection}:${id} unreadable:`, (error as Error)?.message ?? error)
+    return null
   }
   if (!isPubliclyLinkable(row, Object.hasOwn(cols, 'status'))) return null
   return pageRowHref(row, primaryLocale(), prefixPrimaryLocale())

package/layers/public/server/utils/page-resolve.ts

@@ -1,12 +1,20 @@
 import { asc, eq, getTableColumns } from 'drizzle-orm'
 import { list } from '../../../core/server/utils/crud'
 import { captureRead } from '../../../core/server/utils/read-capture'
+import { translationGroupTag } from './publish/invalidation'
 import type { BuiltCollection } from '../../../core/server/utils/collection-types'
 import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'
 
 export interface PageAlternate { locale: string; path: string }
 export interface ResolvedPage { collection: string; page: Record<string, unknown>; alternates: PageAlternate[] }
 
+/** The matched page (or null) plus the collections whose lookup threw. `failed` is non-empty ⇒ the scan
+ *  was INCOMPLETE, so `page: null` must never be treated as an authoritative "no such page". */
+export interface PageResolution {
+  page: ResolvedPage | null
+  failed: string[]
+}
+
 /**
  * The page's published, INDEXABLE translation siblings (self included) as locale→path pairs — the hreflang
  * set the public head emits. Mirrors the sitemap's rules exactly so the two never disagree: published-only
@@ -14,12 +22,15 @@ export interface ResolvedPage { collection: string; page: Record<string, unknown
  * hreflang to a noindexed page is a conflicting signal), null-path rows skipped, and a single-member group
  * returns [] (hreflang is meaningless for a lone page). EVERY sibling in the group is `captureRead`-tagged,
  * filtered-out ones included, so an incremental publish re-renders every group member when a sibling is
- * renamed/published/unpublished — otherwise a baked page would keep a stale/dead hreflang href.
+ * renamed/published/unpublished — otherwise a baked page would keep a stale/dead hreflang href. The GROUP
+ * itself is tagged too: a sibling that does not exist yet has no id to have been captured, so the group tag
+ * is the only edge a later CREATE can match.
  */
 function publishedAlternates(db: BetterSQLite3Database, c: BuiltCollection, page: Record<string, unknown>): PageAlternate[] {
   if (c.def.mode !== 'multi' || !c.def.translatable) return []
   const group = page.translationGroup
   if (typeof group !== 'string' || !group) return []
+  captureRead(translationGroupTag(c.def.name, group))
   const cols = getTableColumns(c.table) as Record<string, never>
   // A status-less pageLike collection has no draft state — every sibling is "published".
   const hasStatus = Object.hasOwn(cols, 'status')
@@ -54,13 +65,15 @@ function publishedAlternates(db: BetterSQLite3Database, c: BuiltCollection, page
 
 /**
  * The first page-like record (across all collections, in registration order) whose `path` matches,
- * populated at depth 1 — or null. Reuses the access-scoped `list()` so media/links populate exactly as
- * a direct collection read would. `publishedOnly` defaults true: a static render (prerender / runtime
- * publisher) and an anonymous live request must never see drafts. The authenticated-admin live preview
- * passes false to surface a draft at its real URL. Registration order is the precedence rule when two
- * page-like collections happen to share a path.
+ * populated at depth 1 — or null, alongside the collections that could not be read at all. Reuses the
+ * access-scoped `list()` so media/links populate exactly as a direct collection read would.
+ * `publishedOnly` defaults true: a static render (prerender / runtime publisher) and an anonymous live
+ * request must never see drafts. The authenticated-admin live preview passes false to surface a draft at
+ * its real URL. Registration order is the precedence rule when two page-like collections happen to share
+ * a path.
  */
-export function resolvePage(db: BetterSQLite3Database, collections: BuiltCollection[], path: string, locale?: string, publishedOnly = true): ResolvedPage | null {
+export function resolvePage(db: BetterSQLite3Database, collections: BuiltCollection[], path: string, locale?: string, publishedOnly = true): PageResolution {
+  const failed: string[] = []
   for (const c of collections) {
     if (!c.def.pageLike) continue
     // withTotal:false — read only the first row, skip count(). capture:false — don't tag the whole
@@ -73,14 +86,15 @@ export function resolvePage(db: BetterSQLite3Database, collections: BuiltCollect
       // Table not migrated yet (e.g. a bare prerender DB) — isolate this collection's drift from the rest,
       // but never silently: an unread collection is indistinguishable from one with no matching page, and
       // the publisher would write a 404 over every one of its routes.
+      failed.push(c.def.name)
       console.error(`[kestrel] resolvePage: skipped collection ${c.def.name}:`, (error as Error)?.message ?? error)
       continue
     }
     const { data } = result
     if (data.length) {
       captureRead(c.def.name, (data[0] as { id?: number }).id ?? null)
-      return { collection: c.def.name, page: data[0]!, alternates: publishedAlternates(db, c, data[0]!) }
+      return { page: { collection: c.def.name, page: data[0]!, alternates: publishedAlternates(db, c, data[0]!) }, failed }
     }
   }
-  return null
+  return { page: null, failed }
 }

package/layers/public/server/utils/preview-token.ts

@@ -0,0 +1,109 @@
+import { randomBytes } from 'node:crypto'
+import type { H3Event } from 'h3'
+
+/**
+ * Short-lived tickets carrying the editor's UNSAVED form state to a real page render. The editor's own
+ * iframe gets unsaved content over postMessage, but an external tab has no parent window to talk to — so
+ * instead of saving (which would publish intent the user never expressed) it mints a ticket and opens
+ * `<url>?kestrel-preview-token=…`. Nothing is written to the DB; the ticket lives in this process only.
+ *
+ * The admin session is the actual gate (both endpoints are admin-only under the default-deny API guard).
+ * The owner binding on top is NOT per-session isolation today: Kestrel has one shared admin credential and
+ * `derivePrincipal` (access layer) never mints more than one admin identity, so every caller that reaches
+ * this store has already been narrowed by `requireAdmin` to the same principal, and `previewOwner()`
+ * resolves to the literal string `'admin'` every time — `t.owner === owner` cannot currently be false for
+ * an admin caller. The binding is kept because it is the seam that makes the check meaningful the moment
+ * (if ever) a per-user identity is added upstream; until then it costs nothing and documents the intent.
+ * Tickets stay readable until they expire — a preview tab may be reloaded — and the store bounds itself in
+ * both directions: a sweep on every mint, and a hard cap that evicts the oldest ticket.
+ *
+ * In-memory by design: previewing is a per-editor, per-minute affair, and a second server instance would
+ * simply re-mint. Nothing durable depends on it.
+ */
+export interface PreviewPayload {
+  collection: string
+  /** The record being previewed, or null for one that has never been saved. */
+  id: number | null
+  locale?: string
+  /** The editor's populated values — the same tree the live-preview bridge posts into the iframe. */
+  values: Record<string, unknown>
+}
+
+export interface PreviewTicket {
+  token: string
+  expiresAt: number
+}
+
+export interface PreviewStore {
+  mint: (owner: string, payload: PreviewPayload) => PreviewTicket
+  read: (token: string, owner: string) => PreviewPayload | null
+  size: () => number
+}
+
+export interface PreviewStoreOptions {
+  ttlMs?: number
+  max?: number
+  now?: () => number
+  randomToken?: () => string
+}
+
+const TTL_MS = 10 * 60 * 1000
+const MAX_TICKETS = 32
+
+export function createPreviewStore(opts: PreviewStoreOptions = {}): PreviewStore {
+  const ttlMs = opts.ttlMs ?? TTL_MS
+  const max = opts.max ?? MAX_TICKETS
+  const now = opts.now ?? Date.now
+  const randomToken = opts.randomToken ?? (() => randomBytes(24).toString('base64url'))
+  // Insertion-ordered, which is what makes "evict the oldest" a single `keys().next()`.
+  const tickets = new Map<string, { owner: string; payload: PreviewPayload; expiresAt: number }>()
+
+  function sweep(at: number): void {
+    for (const [token, t] of tickets) if (t.expiresAt <= at) tickets.delete(token)
+  }
+
+  return {
+    mint(owner, payload) {
+      const at = now()
+      sweep(at)
+      while (tickets.size >= max) tickets.delete(tickets.keys().next().value as string)
+      const token = randomToken()
+      const expiresAt = at + ttlMs
+      tickets.set(token, { owner, payload, expiresAt })
+      return { token, expiresAt }
+    },
+    read(token, owner) {
+      const t = tickets.get(token)
+      if (!t) return null
+      if (t.expiresAt <= now()) {
+        tickets.delete(token)
+        return null
+      }
+      // Bound to the minting owner rather than trusted on token possession alone — inert while every admin
+      // caller resolves to the same owner (see the module docstring), but the check a future per-user
+      // identity would need is already the one being run, not one that would need to be added later.
+      return t.owner === owner ? t.payload : null
+    },
+    size: () => tickets.size,
+  }
+}
+
+/**
+ * Who a ticket belongs to. In production this only ever runs after `requireAdmin(event)` has already
+ * thrown for anyone but the admin principal, and `derivePrincipal` (access layer) always gives that
+ * principal a fixed `userId: 'admin'` — so the first branch always wins and this always returns the
+ * literal `'admin'`. The `role` / `'anonymous'` fallbacks are unreached by any principal shape
+ * `derivePrincipal` produces today; kept as a defensive default rather than a non-null assertion, since
+ * this function has no way to enforce that invariant itself.
+ */
+export function previewOwner(event: H3Event): string {
+  const principal = event.context.principal as { userId?: string | null; role?: string } | undefined
+  return principal?.userId ?? principal?.role ?? 'anonymous'
+}
+
+/** The process-wide store the two `/api/preview` handlers share. */
+let shared: PreviewStore | null = null
+export function usePreviewStore(): PreviewStore {
+  shared ??= createPreviewStore()
+  return shared
+}

package/layers/public/server/utils/publish/invalidation.ts

@@ -27,6 +27,12 @@ export interface WriteClassification {
   /** The page's own public route from the OLD row (pageLike + had a path), else null — the route whose
    *  static file must be pruned on a slug change / unpublish / delete (symmetric to `selfRoute`). */
   oldRoute: string | null
+  groupTag: string | null
+}
+
+/** The data tag naming a translation group. `#` keeps it clear of the `<coll>:<id>` record namespace. */
+export function translationGroupTag(coll: string, group: string): string {
+  return `${coll}#group:${group}`
 }
 
 /** What to republish for a write. Routes are resolved from `tags` against the captured deps index. */
@@ -71,13 +77,43 @@ export function classifyWrite(def: WriteCollection, before: Row, after: Row, pri
   // change (path unchanged) still moves the route — the old-locale file must be pruned.
   const pathChanged = pageLike && status === 'updated' && oldRoute !== selfRoute
 
-  return { collection: def.name, pageLike, status, id, pathChanged, statusChanged, isPublished, wasPublished, selfRoute, oldRoute }
+  // `update` refuses to move a row between groups, so the surviving row's group is the group either way.
+  const group = row?.translationGroup
+  const groupTag = typeof group === 'string' && group ? translationGroupTag(def.name, group) : null
+
+  return { collection: def.name, pageLike, status, id, pathChanged, statusChanged, isPublished, wasPublished, selfRoute, oldRoute, groupTag }
+}
+
+/**
+ * What the write listener enqueues for a content write. `publishOnSave` (`output.publishOnSave`) is the
+ * documented way back to the pre-2.0 model where a save WAS a publish: with it on, a write plans exactly
+ * what it always did. Off (the default), only removals pass — see `planSaveInvalidation`.
+ */
+export function planWrite(ev: WriteClassification, publishOnSave: boolean): Invalidation {
+  return publishOnSave ? planInvalidation(ev) : planSaveInvalidation(ev)
+}
+
+/**
+ * What a plain SAVE may do to the static output. Saving persists to the DB; writing a page's file is the
+ * explicit publish action's job (`planInvalidation`, driven by `POST /api/publish`), so a save renders
+ * nothing — the live site keeps serving the last published version while the editor works on the next one.
+ *
+ * REMOVAL is the asymmetry, and it is deliberate: an unpublished or deleted record must not keep a live
+ * page, so those two branches act immediately. Their referrer/listing re-renders come along, because a
+ * baked link to a page that just went offline is stale the moment it goes — the same "availability" rule
+ * `planInvalidation` documents, minus everything that would put NEW content on the live site.
+ */
+export function planSaveInvalidation(ev: WriteClassification): Invalidation {
+  const removal = ev.status === 'deleted' || (ev.statusChanged && !ev.isPublished)
+  return removal ? planInvalidation(ev) : { type: 'noop' }
 }
 
 /**
- * Decide what a write invalidates, per the maintainer-agreed model. Two notions of "dependent":
+ * Decide what a write invalidates, per the maintainer-agreed model. Three notions of "dependent":
  *  - LISTINGS — pages that QUERY the collection (overviews) → captured as the `<coll>` tag.
  *  - EXPLICIT REFERRERS — pages that LINK/EMBED/relate-to a specific record → captured as `<coll>:<id>`.
+ *  - TRANSLATION SIBLINGS — every member of a group bakes the group's hreflang set → captured as the
+ *    group tag, the only edge that reaches members which rendered before this row existed.
  *
  * Two principles drive the split:
  *  1. FRESHENING (content or path changed) re-renders BOTH listings and explicit referrers (`[coll, coll:id]`)
@@ -94,7 +130,10 @@ export function classifyWrite(def: WriteCollection, before: Row, after: Row, pri
 export function planInvalidation(ev: WriteClassification): Invalidation {
   const coll = ev.collection
   const recordTag = ev.id != null ? `${coll}:${ev.id}` : null
-  const tags = recordTag ? [coll, recordTag] : [coll]
+  // Unlike recordTag (dropped on create — no referrer can target a brand-new id), groupTag is included even
+  // there: a new sibling still changes every existing member's hreflang set.
+  const groupTags = ev.groupTag ? [ev.groupTag] : []
+  const tags = recordTag ? [coll, recordTag, ...groupTags] : [coll, ...groupTags]
   const selfRender = ev.pageLike && ev.selfRoute ? [ev.selfRoute] : []
 
   // DELETE — leaves the collection. Listings re-render, referrers too (their baked link/hreflang now points
@@ -108,7 +147,7 @@ export function planInvalidation(ev: WriteClassification): Invalidation {
   // record re-renders listings + its own route. No referrer can point at a brand-new id, so no `coll:id`.
   if (ev.status === 'created') {
     if (!ev.isPublished) return { type: 'noop' }
-    return { type: 'tags', tags: [coll], render: selfRender, prune: [] }
+    return { type: 'tags', tags: [coll, ...groupTags], render: selfRender, prune: [] }
   }
 
   // UNPUBLISH — leaves the published set. Listings re-render; referrers re-render so their link falls back to