@michaelthielemann/kestrel 1.7.0 → 2.0.0

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/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'
 
 /**
@@ -19,7 +20,7 @@ import { registerWriteListener } from '../../../core/server/utils/write-events'
  */
 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/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/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

@@ -84,6 +84,30 @@ export function classifyWrite(def: WriteCollection, before: Row, after: Row, pri
   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. Three notions of "dependent":
  *  - LISTINGS — pages that QUERY the collection (overviews) → captured as the `<coll>` tag.

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

@@ -0,0 +1,74 @@
+/**
+ * "Saved but not published": the state a deferred-publish model needs to name. Saving writes the DB,
+ * publishing writes the static file, so the two stamps drift apart on purpose — a record edited after its
+ * page was last published keeps serving the published version until someone publishes again.
+ *
+ * The tolerance is not cosmetic: `publish_status.updated_at` is stored in whole seconds while a record's
+ * `updatedAt` is milliseconds, so the publish that directly followed a save can carry a stamp up to a
+ * second BEHIND it. Without the slack every freshly published page would report unpublished changes.
+ */
+const TOLERANCE_MS = 1000
+
+export function hasPendingChanges(savedAtMs: number | null | undefined, publishedAtMs: number | null | undefined, toleranceMs = TOLERANCE_MS): boolean {
+  // Never published (no status row) → nothing to protect: there is no older artifact this edit could
+  // overtake, so the route is a normal render candidate, not a pending change.
+  if (savedAtMs == null || publishedAtMs == null) return false
+  return savedAtMs > publishedAtMs + toleranceMs
+}
+
+/** The subset of `savedAt` routes whose record moved on after the route's last publish. Pure. */
+export function pendingRoutes(savedAt: Map<string, number>, publishedAt: Map<string, number>): string[] {
+  const out: string[] = []
+  for (const [route, saved] of savedAt) {
+    if (hasPendingChanges(saved, publishedAt.get(route) ?? null)) out.push(route)
+  }
+  return out
+}
+
+export interface HeldRoutes {
+  /** Routes to leave un-rendered: their record is serving an older published version somewhere. */
+  hold: Set<string>
+  /** Previously-published routes that are still the live artifact of a held record — never prune these. */
+  keep: Set<string>
+}
+
+/**
+ * Withholding by RECORD rather than by route string, which is what a rename needs. `pendingRoutes` compares
+ * a route against its own publish stamp, so a renamed record — whose new route has no stamp at all — falls
+ * through the "never published, nothing to protect" carve-out: the unpublished rename gets rendered and the
+ * old route, still the live one, is left looking abandoned to the prune. The carve-out is about a FIRST
+ * deploy having no older version; a rename has one, at the previous route.
+ *
+ * So a record's prior published routes are consulted too: if the record has moved on since the newest of
+ * them, the new route is held back and those prior routes are protected from the prune. A record with no
+ * prior published route keeps the carve-out — otherwise a first deploy would produce an empty site.
+ *
+ * Pure: `routesForTag` is the deps index's lookup, passed in.
+ */
+export function heldRoutes(
+  savedAt: Map<string, number>,
+  publishedAt: Map<string, number>,
+  recordTag: Map<string, string>,
+  routesForTag: (tag: string) => Iterable<string>,
+  toleranceMs = TOLERANCE_MS,
+): HeldRoutes {
+  const hold = new Set<string>()
+  const keep = new Set<string>()
+  for (const [route, saved] of savedAt) {
+    const own = publishedAt.get(route) ?? null
+    if (own != null) {
+      if (hasPendingChanges(saved, own, toleranceMs)) hold.add(route)
+      continue
+    }
+    // No stamp of its own: either genuinely never published, or published under a previous route.
+    const tag = recordTag.get(route)
+    if (!tag) continue
+    const priors = [...routesForTag(tag)].filter((r) => r !== route && publishedAt.has(r))
+    if (!priors.length) continue // first publish of this record — nothing to protect
+    const newest = Math.max(...priors.map((r) => publishedAt.get(r)!))
+    if (!hasPendingChanges(saved, newest, toleranceMs)) continue
+    hold.add(route)
+    for (const prior of priors) keep.add(prior)
+  }
+  return { hold, keep }
+}

package/layers/public/server/utils/publish/publish-runtime.ts

@@ -0,0 +1,28 @@
+import type { PublishQueue } from './queue'
+import type { DepsStore } from './deps'
+
+/**
+ * The process-wide handle on the running publish machinery. The `zz.publish` Nitro plugin owns the queue
+ * and the deps index (it builds the output driver and does the logging), but the explicit publish action —
+ * `POST /api/publish` — has to reach both from inside a request: the queue to enqueue the run, the deps
+ * index to find the routes this record was baked into. Mirrors core's `write-events` registry: module
+ * state, set once at boot.
+ *
+ * `null` wherever the runtime publisher does not run at all (dev, or `output.auto` off). That is not an
+ * error — it is what the endpoint reports back so the editor can say "nothing is generated here" instead
+ * of pretending a publish happened.
+ */
+export interface PublishRuntime {
+  queue: PublishQueue
+  deps: DepsStore
+}
+
+let runtime: PublishRuntime | null = null
+
+export function setPublishRuntime(next: PublishRuntime | null): void {
+  runtime = next
+}
+
+export function usePublishRuntime(): PublishRuntime | null {
+  return runtime
+}

package/layers/public/server/utils/publish/publish-status.ts

@@ -43,6 +43,24 @@ export function renderOutcome(status: number, hasBody: boolean): 'success' | 'er
   return 'skip'
 }
 
+/**
+ * Every route's last successful-or-failed publish time, in ms — the "last published" half of the
+ * saved-vs-published comparison a deferred publish needs. Same missing-table resilience as the writers:
+ * an unmigrated deploy yields an empty map, which reads as "nothing was ever published here" and so
+ * holds nothing back.
+ */
+export function lastPublishedAt(db: BetterSQLite3Database): Map<string, number> {
+  const out = new Map<string, number>()
+  try {
+    for (const row of db.select({ route: publishStatus.route, updatedAt: publishStatus.updatedAt }).from(publishStatus).all()) {
+      if (row.updatedAt instanceof Date) out.set(row.route, row.updatedAt.getTime())
+    }
+  } catch (error) {
+    console.warn('[kestrel] could not read publish status:', (error as Error).message)
+  }
+  return out
+}
+
 /** Clear a route's status row — its static file was pruned (unpublish / delete / slug change), so it is no
  *  longer live. Idempotent; same missing-table resilience as `recordPublishStatus`. */
 export function clearPublishStatus(db: BetterSQLite3Database, route: string): void {

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

@@ -12,8 +12,9 @@ import { withResolveScope } from '../../../../core/server/utils/resolve-scope'
 import { runAsRenderer } from '../../../../access/server/utils/render-context'
 import { htmlKeyForRoute } from './route-keys'
 import { staleRoutes, type DepsStore } from './deps'
-import { recordPublishStatus, clearPublishStatus, renderOutcome } from './publish-status'
+import { recordPublishStatus, clearPublishStatus, renderOutcome, lastPublishedAt } from './publish-status'
 import { routesToPrune, type Invalidation } from './invalidation'
+import { pendingRoutes, heldRoutes } from './pending'
 
 /**
  * The runtime static publisher: renders public routes from the LIVE server (`localFetch`, the same
@@ -28,6 +29,7 @@ interface OutputRc {
   dir: string
   publicDir: string
   auto: boolean
+  publishOnSave: boolean
   reconcileMinutes: number
   verbose: boolean
   s3: { bucket: string; region: string; endpoint: string; prefix: string; accessKeyId: string; secretAccessKey: string; sessionToken: string }
@@ -69,6 +71,11 @@ export async function renderRoute(route: string): Promise<{ body: Buffer | null;
  *  route set is INCOMPLETE, so it must never be used as the authority for what to delete. */
 export interface PublishedRoutes {
   routes: string[]
+  /** Each route's record `updatedAt` in ms — the "last saved" half of the saved-vs-published comparison. */
+  savedAt: Map<string, number>
+  /** Each route's owning record as its deps tag (`<coll>:<id>`) — route strings move on a rename, records
+   *  do not, so withholding a renamed page needs the identity behind the route. */
+  recordTag: Map<string, string>
   /** Names of collections whose route query threw (drifted schema, locked DB) — routes are missing. */
   failed: string[]
 }
@@ -82,6 +89,8 @@ export function allPublishedRoutes(): PublishedRoutes {
   const prefixPrimary = prefixPrimaryLocale()
   const pub = publicReadableResources()
   const routes = new Set<string>([localePath('/', primary, primary, prefixPrimary)]) // `/` or `/<primary>`
+  const savedAt = new Map<string, number>()
+  const recordTag = new Map<string, string>()
   const failed: string[] = []
   for (const c of allCollections()) {
     if (!c.def.pageLike || !isPubliclyReadable(c.def.name, pub)) continue
@@ -94,6 +103,10 @@ export function allPublishedRoutes(): PublishedRoutes {
     const proj: Record<string, unknown> = { path: cols.path }
     if (c.def.translatable) proj.locale = cols.locale
     if (c.def.status) proj.status = cols.status
+    // `updatedAt` is a system column on every built collection, but this projection also runs against
+    // hand-rolled tables in tests — guard it exactly like `locale`, or its absence throws the select.
+    if (Object.hasOwn(cols, 'updatedAt')) proj.updatedAt = cols.updatedAt
+    if (Object.hasOwn(cols, 'id')) proj.id = cols.id
     let rows: Record<string, unknown>[]
     try { rows = db.select(proj as never).from(c.table).all() as Record<string, unknown>[] }
     catch (error) {
@@ -106,10 +119,17 @@ export function allPublishedRoutes(): PublishedRoutes {
     for (const row of rows) {
       if (c.def.status && row.status !== 'published') continue
       const route = pageRowHref(row, primary, prefixPrimary) // the shared (path, locale) → route rule
-      if (route) routes.add(route)
+      if (!route) continue
+      routes.add(route)
+      const saved = row.updatedAt
+      if (saved instanceof Date) savedAt.set(route, saved.getTime())
+      else if (typeof saved === 'number') savedAt.set(route, saved)
+      // The same tag the publisher records against a rendered route, so a route can be traced back to its
+      // record even after a rename moved the route string.
+      if (typeof row.id === 'number') recordTag.set(route, `${c.def.name}:${row.id}`)
     }
   }
-  return { routes: [...routes], failed }
+  return { routes: [...routes], savedAt, recordTag, failed }
 }
 
 /** Render + write the given routes (skips non-200). When `deps` is given, each render is wrapped in a
@@ -226,7 +246,7 @@ export async function publishFull(driver: StorageDriver = outputDriver(), deps?:
   // runs late (layer-then-filename order) — finish populating the registry first. Moving the read before
   // an await would silently render an empty registry. See docs/architecture.md → "Server plugins".
   await syncStaticAssets(driver, cfg.publicDir)
-  const { routes, failed } = allPublishedRoutes()
+  const { routes, savedAt, recordTag, failed } = allPublishedRoutes()
   if (failed.length) {
     // Keep on doubt: with a collection missing from the enumeration, every one of its live pages looks
     // stale, so a prune would wipe it from the output. Rendering still proceeds — a stale extra file is
@@ -234,12 +254,27 @@ export async function publishFull(driver: StorageDriver = outputDriver(), deps?:
     console.error(`[kestrel] publish: prune skipped — routes of ${failed.join(', ')} could not be enumerated; existing files kept`)
   }
 
+  // A full run resynchronizes the output with the DB, so without this it would push every saved-but-
+  // unpublished edit live — exactly what deferring the publish exists to prevent. Those routes keep the
+  // file their last publish wrote.
+  // …unless the consumer opted out of the split (`output.publishOnSave`): there, a save IS a publish, so
+  // "saved after the last publish" means a republish is merely in flight, not deliberately withheld.
+  // Computed BEFORE the prune, because a held record's live file may sit at a route the DB no longer names
+  // (an unpublished rename), and that file is what the site is still serving. Without `deps` there is no
+  // way to find those prior routes, so only same-route withholding applies — the pre-rename behaviour.
+  const { hold, keep } = cfg.publishOnSave
+    ? { hold: new Set<string>(), keep: new Set<string>() }
+    : heldRoutes(savedAt, lastPublishedAt(useDb()), recordTag, (tag) => deps?.routesForTags([tag]) ?? [])
+  if (hold.size) {
+    console.info(`[kestrel] publish: ${hold.size} route(s) held at their published version (unpublished changes): ${[...hold].join(', ')}`)
+  }
+
   // Targeted prune: a route we previously published that is no longer in the published set — a page
   // unpublished, deleted, or whose slug changed — must lose its static file. Safe because it only deletes
   // files this publisher wrote (tracked in deps, durable across restarts). Output ≡ DB; no opt-in toggle.
   let pruned = 0
   if (deps && !failed.length) {
-    const stale = staleRoutes(deps.routes(), routes)
+    const stale = staleRoutes(deps.routes(), routes).filter((route) => !keep.has(route))
     if (stale.length) {
       await prunePages(stale, driver)
       for (const route of stale) deps.forget(route)
@@ -247,11 +282,13 @@ export async function publishFull(driver: StorageDriver = outputDriver(), deps?:
     }
   }
 
+  const renderRoutes = routes.filter((route) => !hold.has(route))
+
   // Reset the discovery accumulator so this full run reconciles ONLY what it actually renders — an earlier
   // incremental (tag) publish also feeds the accumulator, and a variant it recorded whose usage was later
   // removed would otherwise survive and be re-registered here (defeating usage-driven narrowing).
   clearVariants()
-  const written = await publishRoutes(routes, driver, deps)
+  const written = await publishRoutes(renderRoutes, driver, deps)
   const rendered = written.length
   await publishMeta(driver)
   // Auto-discovery: a FULL render just visited every published route, so the capture accumulator now holds
@@ -260,8 +297,10 @@ export async function publishFull(driver: StorageDriver = outputDriver(), deps?:
   // by the un-rendered routes. ONLY narrow when EVERY route rendered: a partial failure leaves the accumulator
   // incomplete, so reconciling would deregister variants still referenced by the stale (kept) published HTML,
   // which a later backfill would then delete out from under the live page. An un-enumerated collection is
-  // the same partial-coverage case: its pages were never visited, so their variants are missing too.
-  if (!failed.length && rendered === routes.length) saveDiscoveredVariants(useDb())
+  // the same partial-coverage case: its pages were never visited, so their variants are missing too — and
+  // so is a route held back at its published version: its live file still references the variants this run
+  // never saw.
+  if (!failed.length && !hold.size && rendered === renderRoutes.length) saveDiscoveredVariants(useDb())
   return { rendered, pruned }
 }
 
@@ -270,13 +309,39 @@ export async function publishFull(driver: StorageDriver = outputDriver(), deps?:
  *  (their `<lastmod>` may have changed). */
 export interface PublishResult { rendered: string[]; pruned: string[]; counts: { rendered: number; pruned: number } }
 
+/**
+ * Drop the routes a tag match dragged in that are holding their published version back. Withholding is a
+ * property of the ROUTE, not of the full publish: a route whose record was saved after its last publish
+ * serves that published file until someone publishes it. Without this, publishing one record re-renders
+ * every route tagged with the collection — and every route reads the `site` singleton — from the live DB,
+ * so a routine Publish writes an unrelated record's withheld body to the live site.
+ *
+ * A route named in `render` is exempt: it IS what the publish was for, and pressing Publish is what clears
+ * the withholding. The prune set is untouched — removal has no publish intent left to protect, so an
+ * unpublished or deleted record's page still goes at once (ADR-0008).
+ *
+ * The cost, deliberately accepted: a withheld route keeps the baked links and hreflang of its last
+ * publish, so a link to a record that has since been unpublished stays stale until the referrer itself is
+ * published. That is the same staleness its body already carries — a frozen route is one publish
+ * generation throughout, rather than a mix of two. Rendering a referrer from its published state while
+ * resolving fresh links needs a published snapshot per record, which is ADR-0008's "Future".
+ */
+function withheldRemoved(inv: Extract<Invalidation, { type: 'tags' }>, routes: string[]): string[] {
+  if (outputConfig().publishOnSave) return routes // that mode never defers a publish in the first place
+  // An un-enumerable collection contributes no `savedAt` entry, so its routes are simply not withheld —
+  // the same direction publishFull takes, and the non-destructive one (a stale re-render, never a delete).
+  const held = new Set(pendingRoutes(allPublishedRoutes().savedAt, lastPublishedAt(useDb())))
+  const explicit = new Set(inv.render)
+  return routes.filter((route) => explicit.has(route) || !held.has(route))
+}
+
 export async function publishInvalidation(inv: Invalidation, driver: StorageDriver = outputDriver(), deps?: DepsStore): Promise<PublishResult> {
   if (inv.type === 'noop') return { rendered: [], pruned: [], counts: { rendered: 0, pruned: 0 } }
   if (inv.type === 'full') {
     const r = await publishFull(driver, deps) // full: counts only (don't list every route)
     return { rendered: [], pruned: [], counts: { rendered: r.rendered, pruned: r.pruned } }
   }
-  const routes = [...new Set([...(deps?.routesForTags(inv.tags) ?? []), ...inv.render])]
+  const routes = withheldRemoved(inv, [...new Set([...(deps?.routesForTags(inv.tags) ?? []), ...inv.render])])
   const rendered = await publishRoutes(routes, driver, deps)
   let pruned: string[] = []
   // Never prune a route we just wrote live — render wins a coalesced render+prune collision (see routesToPrune).

package/layers/ui/app/components/field/Datetime.vue

@@ -59,10 +59,12 @@ const rangeEnd = computed<string | null>({
   <UiFieldset v-else :id="id" :label="name" :error="error" :required="required">
     <template #default="f">
       <template v-if="isTime">
+        <!-- eslint-disable-next-line vuejs-accessibility/label-has-for -- native wrapping label around a custom UiTimeInput; no `for`/`id` pair needed, invisible to static analysis -->
         <label class="field-datetime__sub">
           <span class="field-datetime__sublabel">{{ t('field.datetime.range_start') }}</span>
           <UiTimeInput v-model="rangeStart" :disabled="disabled" v-bind="f" />
         </label>
+        <!-- eslint-disable-next-line vuejs-accessibility/label-has-for -- native wrapping label around a custom UiTimeInput; no `for`/`id` pair needed, invisible to static analysis -->
         <label class="field-datetime__sub">
           <span class="field-datetime__sublabel">{{ t('field.datetime.range_end') }}</span>
           <UiTimeInput v-model="rangeEnd" :disabled="disabled" v-bind="f" />

package/layers/ui/app/components/field/Repeater.vue

@@ -126,6 +126,7 @@ function insertRowAt(at: number) {
       {{ name }}<span v-if="required" aria-hidden="true">*</span>
     </legend>
 
+    <!-- eslint-disable-next-line vuejs-accessibility/no-static-element-interactions -- @dragleave is a mouse-only progressive enhancement; the move-up/move-down buttons below give the same reorder fully keyboard access -->
     <div ref="rowsEl" class="ui-repeater__rows" @dragleave="onDragLeave">
       <template v-for="(row, i) in rows" :key="keys[i]">
         <div class="ui-repeater__insert-zone">
@@ -140,6 +141,7 @@ function insertRowAt(at: number) {
           </button>
         </div>
 
+        <!-- eslint-disable-next-line vuejs-accessibility/no-static-element-interactions -- drag handlers are a mouse-only progressive enhancement; the move-up/move-down buttons below give the same reorder fully keyboard access -->
         <div
           class="ui-repeater__row-wrap"
           :class="{ 'ui-repeater__row-wrap--over': overIndex === i && dragIndex !== i }"

package/layers/ui/app/components/ui/Checkbox.vue

@@ -25,6 +25,7 @@ watch(() => props.indeterminate, syncIndeterminate)
 </script>
 
 <template>
+  <!-- eslint-disable-next-line vuejs-accessibility/form-control-has-label -- id/label land via UiField's attrs fallthrough (single root element), invisible to static analysis -->
   <input
     ref="input"
     v-model="model"

package/layers/ui/app/components/ui/CheckboxGroup.vue

@@ -23,6 +23,7 @@ function toggle(value: string, checked: boolean) {
 
 <template>
   <div class="ui-checkbox-group" role="group">
+    <!-- eslint-disable-next-line vuejs-accessibility/label-has-for -- native wrapping label around a custom UiCheckbox; no `for`/`id` pair needed, invisible to static analysis -->
     <label v-for="o in options" :key="o.value" class="ui-checkbox-group__item">
       <UiCheckbox
         :model-value="selected.includes(o.value)"

package/layers/ui/app/components/ui/Combobox.vue

@@ -117,7 +117,9 @@ function moveChip(from: number, to: number) {
     class="ui-combobox"
   >
     <ComboboxAnchor class="ui-combobox__anchor" :data-multiple="multiple || undefined" :aria-invalid="invalid || undefined">
+      <!-- eslint-disable-next-line vuejs-accessibility/no-static-element-interactions, vuejs-accessibility/no-redundant-roles -- @dragleave is a mouse-only progressive enhancement (the chip-move buttons below give the same reorder fully keyboard access); role="list" is NOT redundant here, `list-style: none` below strips the implicit list semantics in WebKit, see the "WebKit list-semantics fix" test -->
       <ul v-if="multiple && selected.length" ref="chips" class="ui-combobox__chips" role="list" @dragleave="onDragLeave">
+        <!-- eslint-disable-next-line vuejs-accessibility/no-static-element-interactions -- drag handlers are a mouse-only progressive enhancement; the chip-move buttons below give the same reorder fully keyboard access -->
         <li
           v-for="(s, i) in selected"
           :key="s.value"