@michaelthielemann/kestrel 1.2.1

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

@@ -0,0 +1,86 @@
+import { asc, eq, getTableColumns } from 'drizzle-orm'
+import { list } from '../../../core/server/utils/crud'
+import { captureRead } from '../../../core/server/utils/read-capture'
+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 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
+ * (a draft URL must never be advertised to crawlers), `seo.noindex` variants EXCLUDED (advertising an
+ * 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.
+ */
+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 []
+  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')
+  const proj: Record<string, unknown> = { id: cols.id, locale: cols.locale, path: cols.path }
+  if (hasStatus) proj.status = cols.status
+  if (c.def.seo) proj.seo = cols.seo
+  // Read the WHOLE group and filter in JS: a row excluded by SQL is never captured, so a draft sibling
+  // would carry no dependency edge for the publish tag `<coll>:<id>` to match, and this page would keep a
+  // baked hreflang set missing the newly-published sibling until the next full generate.
+  const rows = db.select(proj as never)
+    .from(c.table)
+    .where(eq(cols.translationGroup, group))
+    .orderBy(asc(cols.locale))
+    .all() as Array<{ id: number; locale: string; path: unknown; status?: string; seo?: { noindex?: boolean } | null }>
+  const alternates: PageAlternate[] = []
+  let selfAdvertisable = false
+  for (const r of rows) {
+    // Capture the sibling as a publish dependency even if it is filtered out below — a draft/noindexed/
+    // null-path sibling that later becomes advertisable must still re-render this page's hreflang set.
+    captureRead(c.def.name, r.id)
+    if (hasStatus && r.status !== 'published') continue // a draft URL must never be advertised
+    if (typeof r.path !== 'string' || !r.path) continue // null/empty path — no advertisable URL
+    if (r.seo?.noindex) continue // noindexed — never advertise it via hreflang (matches the sitemap)
+    if (r.id === page.id) selfAdvertisable = true
+    alternates.push({ locale: r.locale, path: r.path })
+  }
+  // A hreflang set with no self-reference is a signal search engines ignore wholesale — if the page
+  // being rendered didn't itself survive the filters above, advertise nothing rather than an orphan set.
+  if (!selfAdvertisable) return []
+  return alternates.length >= 2 ? alternates : []
+}
+
+/**
+ * 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.
+ */
+export function resolvePage(db: BetterSQLite3Database, collections: BuiltCollection[], path: string, locale?: string, publishedOnly = true): ResolvedPage | null {
+  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
+    // collection here (the self-lookup is by path); instead tag the found record below, so this page
+    // depends on its OWN record, not on every sibling in the collection (precise invalidation).
+    let result: ReturnType<typeof list>
+    try {
+      result = list(db, c, { filter: [{ field: 'path', op: 'eq', value: path }], locale, depth: 1, perPage: 1, withTotal: false, capture: false }, publishedOnly)
+    } catch (error) {
+      // 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.
+      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 null
+}

package/layers/public/server/utils/populate-links.ts

@@ -0,0 +1,66 @@
+import type { FieldPopulator } from '../../../core/server/utils/populate'
+import { memoDuringPrerender } from '../../../core/server/utils/prerender-memo'
+import { memoResolver } from '../../../core/server/utils/resolve-scope'
+import { captureRead } from '../../../core/server/utils/read-capture'
+import { collectRichtextRefs, resolveRichtextLinks } from '../../../fields/app/utils/richtext-links'
+
+// The localized-href-for-a-page-row rule lives once in core (`pageRowHref`); the link populator/resolver
+// use it as the target-row href. The resolver (link-resolve) STATUS-GATES: a missing OR draft target
+// renders `'#'` (no draft-slug leak); only a published target gets its real path.
+
+// Resolves an internal link `{collection, id}` to the target's localized path, or null when it has no
+// public path (target missing, not page-like, or no path). The locale is the TARGET row's own, so the
+// resolver takes no locale argument — mirroring how the media populator injects its by-id resolver.
+export type ResolveHref = (collection: string, id: number) => string | null
+
+interface InternalLink { type: 'internal'; collection: string; id: number; href?: string }
+
+function isInternal(value: unknown): value is InternalLink {
+  if (!value || typeof value !== 'object') return false
+  const v = value as Record<string, unknown>
+  return v.type === 'internal' && typeof v.collection === 'string' && typeof v.id === 'number'
+}
+
+// Replace an internal link value in place with a cloned `{...value, href}` (KestrelLink reads value.href).
+// external / email / tel and unresolvable internals pass through untouched (the latter render '#').
+function resolveLink(value: unknown, resolveHref: ResolveHref): unknown {
+  if (!isInternal(value)) return value
+  const href = resolveHref(value.collection, value.id)
+  return href == null ? value : { ...value, href }
+}
+
+/**
+ * The `link` + `richtext` field populators. `link` replaces an internal link value with `{...value, href}`;
+ * `richtext` rewrites `kestrel:` internal-link markers in the HTML to resolved localized paths. Both are
+ * bare-keyed in every key-mode (link/richtext are not single-ref columns), so `keyMode` is irrelevant.
+ * Registered per-type via `registerFieldPopulator`; the shared field-tree walker drives them over
+ * top-level fields, block props, and (now) repeater entries. Both share one prerender memo so a target is
+ * resolved once per generate across links and richtext alike.
+ */
+export function buildLinkFieldPopulators(resolveHref: ResolveHref): { link: FieldPopulator; richtext: FieldPopulator } {
+  // Same composition as the relation/media populators: build-wide memo during generate, request-/publish-
+  // run-wide via the resolve scope (budgeted per live request, read-tags replayed on hits).
+  // memoResolver OUTERMOST so a per-scope budget-skip null is never cached build-wide by the prerender memo.
+  const key = (collection: string, id: number) => `link:${collection}:${id}`
+  const resolve = memoResolver(memoDuringPrerender(resolveHref, key), key)
+  return {
+    // captureRead runs even on a memo hit (each embedding page must record the dep), so it sits here, not
+    // inside `resolve`: it durably ties this render's route to `<collection>:<id>`, so renaming the target
+    // re-renders the referrer instead of leaving a baked href pointing at the pruned old path. A DRAFT
+    // target is tagged for the same reason: resolution is status-gated, so the referrer baked '#', and this
+    // edge is what lets the availability tag `<collection>:<id>` (planInvalidation's publish/unpublish/
+    // delete branches) re-render it into the real path. A dangling target's tag is simply inert — no write
+    // ever emits it.
+    link: (bag, key) => {
+      const value = bag[key]
+      if (isInternal(value)) captureRead(value.collection, value.id)
+      bag[key] = resolveLink(value, resolve)
+    },
+    richtext: (bag, key) => {
+      const html = bag[key]
+      if (typeof html !== 'string') return
+      for (const ref of collectRichtextRefs(html)) captureRead(ref.collection, ref.id)
+      bag[key] = resolveRichtextLinks(html, resolve)
+    },
+  }
+}

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

@@ -0,0 +1,22 @@
+import type { Invalidation } from './invalidation'
+
+/**
+ * Merge a burst of invalidations collected during a debounce window into one: any `full` wins (a
+ * full rebuild subsumes everything); otherwise union the `tags`/`render`/`prune` sets (dedup, stable
+ * insertion order); all-`noop` (or empty) collapses to `noop`.
+ */
+export function coalesce(items: Invalidation[]): Invalidation {
+  if (items.some((i) => i.type === 'full')) return { type: 'full' }
+  const tags = new Set<string>()
+  const render = new Set<string>()
+  const prune = new Set<string>()
+  let any = false
+  for (const i of items) {
+    if (i.type !== 'tags') continue
+    any = true
+    for (const t of i.tags) tags.add(t)
+    for (const r of i.render) render.add(r)
+    for (const p of i.prune) prune.add(p)
+  }
+  return any ? { type: 'tags', tags: [...tags], render: [...render], prune: [...prune] } : { type: 'noop' }
+}

package/layers/public/server/utils/publish/deps-persistence.ts

@@ -0,0 +1,43 @@
+import { eq } from 'drizzle-orm'
+import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'
+import { publishDeps } from '../../database/publish-deps'
+import type { DepsPersistence } from './deps'
+
+/** No-op persistence: a `DepsStore` backed by it runs purely in-memory. */
+const inMemoryOnly: DepsPersistence = { load: () => [], save: () => {}, remove: () => {}, clearAll: () => {} }
+
+/**
+ * SQLite-backed durable persistence for the publish deps index. Takes the drizzle db as an argument (the
+ * caller passes `useDb()`) so this stays a pure function of an injected db — fully unit-testable against an
+ * in-memory database, no auto-import in the module. Tags are stored JSON-encoded (a small bounded set per
+ * route).
+ *
+ * Probes the `publish_deps` table once on creation: if it is absent (a not-yet-migrated deploy — prod never
+ * auto-DDLs, so an operator must run `db:migrate`) it warns and returns an in-memory-only no-op rather than
+ * crashing the boot publish + every write. Full durability (cross-restart pruning) returns once the table
+ * exists. Probing once (not per-op) keeps ALL of load/save/remove/clearAll consistent — the boot publish
+ * calls `save()` per route, so a resilient `load()` alone was not enough.
+ */
+export function createSqlitePersistence(db: BetterSQLite3Database): DepsPersistence {
+  try {
+    db.select().from(publishDeps).limit(1).all()
+  } catch {
+    console.warn('[kestrel] publish_deps table is missing — run the `db:migrate` task. Falling back to in-memory deps (no cross-restart prune until migrated).')
+    return inMemoryOnly
+  }
+  return {
+    load() {
+      return db.select().from(publishDeps).all().map((r) => [r.route, JSON.parse(r.tags) as string[]] as const)
+    },
+    save(route, tags) {
+      const json = JSON.stringify([...tags])
+      db.insert(publishDeps).values({ route, tags: json }).onConflictDoUpdate({ target: publishDeps.route, set: { tags: json } }).run()
+    },
+    remove(route) {
+      db.delete(publishDeps).where(eq(publishDeps.route, route)).run()
+    },
+    clearAll() {
+      db.delete(publishDeps).run()
+    },
+  }
+}

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

@@ -0,0 +1,87 @@
+/**
+ * Routes whose captured dependency tags intersect `changed`. The publisher captures, per published
+ * route, the set of data tags it read while rendering (`<coll>` for a `list`, `<coll>:<id>` for a
+ * `getOne`, `<coll>` for a singleton). On a write, the changed tags `{coll, coll:id}` map back to
+ * exactly the routes that embed that data — so editing one speaker re-renders its detail page + the
+ * overview that lists speakers, and nothing else. Pure.
+ */
+export function routesForTags(changed: Iterable<string>, index: Map<string, Set<string>>): string[] {
+  const want = new Set(changed)
+  const out: string[] = []
+  for (const [route, tags] of index) {
+    for (const t of tags) {
+      if (want.has(t)) { out.push(route); break }
+    }
+  }
+  return out
+}
+
+/**
+ * Routes the publisher previously wrote (tracked in the deps index) that are no longer in the published
+ * set — a page that was unpublished, deleted, or whose slug changed. Their static files must be removed
+ * on the next full publish. Pure; the diff drives a targeted prune (it only ever deletes files this
+ * publisher created — output ≡ DB, no opt-in toggle).
+ */
+export function staleRoutes(tracked: Iterable<string>, publishedNow: Iterable<string>): string[] {
+  const live = new Set(publishedNow)
+  return [...tracked].filter((route) => !live.has(route))
+}
+
+/**
+ * Durable backing for the deps index: a write-through `route → tags` store that survives a restart.
+ * The in-memory index is the (synchronous) query layer; this port persists every mutation and is read
+ * back once on construction to rehydrate. Kept abstract so `DepsStore` stays pure-unit-testable (a fake
+ * port in node tests) while production injects the SQLite-backed adapter (`createSqlitePersistence`).
+ */
+export interface DepsPersistence {
+  /** Every persisted `route → tags` pair (read once on DepsStore construction to rehydrate). */
+  load(): Iterable<readonly [string, Iterable<string>]>
+  /** Persist (upsert) a route's tag set. */
+  save(route: string, tags: Iterable<string>): void
+  /** Remove a route. */
+  remove(route: string): void
+  /** Drop every route. */
+  clearAll(): void
+}
+
+/**
+ * In-memory `route → tags` index, populated as routes are published and queried on each write — the fast
+ * synchronous query layer. When constructed with a `DepsPersistence`, the index is rehydrated from it on
+ * boot and every mutation is written through, so the store survives a restart: a boot full-publish's
+ * `staleRoutes` can then prune pages that were unpublished/deleted while the server was down.
+ */
+export class DepsStore {
+  private index = new Map<string, Set<string>>()
+
+  constructor(private persistence?: DepsPersistence) {
+    if (persistence) for (const [route, tags] of persistence.load()) this.index.set(route, new Set(tags))
+  }
+
+  /** Replace the tag set captured for `route`. */
+  record(route: string, tags: Iterable<string>): void {
+    const set = new Set(tags)
+    this.index.set(route, set)
+    this.persistence?.save(route, set)
+  }
+
+  /** Routes whose tags intersect `changed`. */
+  routesForTags(changed: Iterable<string>): string[] {
+    return routesForTags(changed, this.index)
+  }
+
+  /** Every route with a captured tag set. */
+  routes(): string[] {
+    return [...this.index.keys()]
+  }
+
+  /** Drop `route` from the index (on prune/unpublish). */
+  forget(route: string): void {
+    this.index.delete(route)
+    this.persistence?.remove(route)
+  }
+
+  clear(): void {
+    this.index.clear()
+    this.persistence?.clearAll()
+  }
+}

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

@@ -0,0 +1,141 @@
+import { pageRowHref } from '../../../../core/server/utils/page-route'
+
+/** The shape of the collection a write targets (the subset invalidation needs). */
+export interface WriteCollection {
+  name: string
+  pageLike?: boolean
+  /** Whether the collection has a draft/published `status` column. */
+  status?: boolean
+}
+
+type Row = Record<string, unknown> | null
+
+/** A content write reduced to what invalidation needs (computed by `classifyWrite`). */
+export interface WriteClassification {
+  collection: string
+  pageLike: boolean
+  status: 'created' | 'updated' | 'deleted'
+  id: number | null
+  /** pageLike `path` changed (the old static file must be pruned, the new one written). */
+  pathChanged: boolean
+  /** published-ness changed (publish or unpublish — adds/removes the page + sitemap entry). */
+  statusChanged: boolean
+  isPublished: boolean
+  wasPublished: boolean
+  /** The page's own public route from the NEW row (pageLike + has a path), else null. */
+  selfRoute: string | null
+  /** 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
+}
+
+/** What to republish for a write. Routes are resolved from `tags` against the captured deps index. */
+export type Invalidation =
+  | { type: 'full' }
+  | { type: 'tags'; tags: string[]; render: string[]; prune: string[] }
+  | { type: 'noop' }
+
+/**
+ * The routes to actually delete from a coalesced invalidation: `prune` minus anything we just wrote live.
+ * A render and a prune for the SAME route can coalesce into one window (e.g. a new page created at /x while
+ * another page vacates /x) — pruning a freshly-rendered route would delete the live page, so render wins.
+ * Filtered against the ACTUALLY-rendered set (not the render candidates), so a route whose record is now a
+ * draft — skipped by the renderer — is still pruned.
+ */
+export function routesToPrune(prune: string[], rendered: string[]): string[] {
+  const live = new Set(rendered)
+  return prune.filter((r) => !live.has(r))
+}
+
+/** A collection with no `status` column is always public; otherwise public ⇔ status === 'published'. */
+function isPublic(def: WriteCollection, row: Row): boolean {
+  if (!def.status) return true
+  return !!row && row.status === 'published'
+}
+
+/** Reduce a before/after row pair (either may be null) to a `WriteClassification`. Pure (routes via the shared `pageRowHref`). */
+export function classifyWrite(def: WriteCollection, before: Row, after: Row, primaryLocale: string, prefixPrimary = false): WriteClassification {
+  const status: WriteClassification['status'] = before === null ? 'created' : after === null ? 'deleted' : 'updated'
+  const row = after ?? before
+  const id = typeof row?.id === 'number' ? row.id : null
+  const pageLike = !!def.pageLike
+
+  const isPublished = isPublic(def, after)
+  const wasPublished = isPublic(def, before)
+  const statusChanged = status === 'updated' && !!def.status && isPublished !== wasPublished
+
+  const routeFrom = (r: Row): string | null => (pageLike ? pageRowHref(r, primaryLocale, prefixPrimary) : null)
+  const selfRoute = routeFrom(after)
+  const oldRoute = routeFrom(before)
+  // Compare the RESOLVED routes, not raw `path`: the route is localePath(path, locale), so a locale-only
+  // 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 }
+}
+
+/**
+ * Decide what a write invalidates, per the maintainer-agreed model. Two 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>`.
+ *
+ * Two principles drive the split:
+ *  1. FRESHENING (content or path changed) re-renders BOTH listings and explicit referrers (`[coll, coll:id]`)
+ *     so their output stays fresh.
+ *  2. AVAILABILITY (publish / unpublish / delete) re-renders listings (membership changed) AND the explicit
+ *     referrers (`[coll, coll:id]`), because a referrer's BAKED output encodes the target's availability:
+ *     link resolution is status-gated (a draft target bakes `href="#"`) and a page's hreflang set lists only
+ *     its published translation siblings — both go dead/stale the moment availability flips, and only a
+ *     re-render can fix them. A record's OWN artifact always matches its DB state (render on publish, prune
+ *     on unpublish/delete). A draft that stays a draft is a no-op.
+ *
+ * `full` is reserved for the boot publish + the reconciler (enqueued directly), never produced here.
+ */
+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]
+  const selfRender = ev.pageLike && ev.selfRoute ? [ev.selfRoute] : []
+
+  // DELETE — leaves the collection. Listings re-render, referrers too (their baked link/hreflang now points
+  // at a route that is about to disappear); the own (pageLike) route is pruned.
+  if (ev.status === 'deleted') {
+    const prune = ev.pageLike && ev.oldRoute ? [ev.oldRoute] : []
+    return { type: 'tags', tags, render: [], prune }
+  }
+
+  // CREATE — joins the collection. A created draft produces no public output (noop); a created published
+  // 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: [] }
+  }
+
+  // UNPUBLISH — leaves the published set. Listings re-render; referrers re-render so their link falls back to
+  // '#' and their hreflang drops this sibling; the own route is pruned (the live file sits at the OLD path if
+  // this save also renamed).
+  if (ev.statusChanged && !ev.isPublished) {
+    const route = ev.oldRoute ?? ev.selfRoute
+    const prune = ev.pageLike && route ? [route] : []
+    return { type: 'tags', tags, render: [], prune }
+  }
+
+  // PUBLISH — joins the published set. Listings re-render; referrers re-render because a link to a draft
+  // resolves to '#' — their baked href only becomes the real path on a re-render; the own route renders.
+  if (ev.statusChanged && ev.isPublished) {
+    return { type: 'tags', tags, render: selfRender, prune: [] }
+  }
+
+  // Below: a plain update, no availability change. A draft that stays a draft touches no public output.
+  if (!ev.isPublished) return { type: 'noop' }
+
+  // SLUG / PATH CHANGE — path freshening: listings + referrers re-render (their link path updates); the new
+  // route renders, the old route is pruned.
+  if (ev.pathChanged) {
+    const prune = ev.oldRoute ? [ev.oldRoute] : []
+    return { type: 'tags', tags, render: selfRender, prune }
+  }
+
+  // CONTENT EDIT — content freshening: listings + explicit referrers re-render; the own route re-renders.
+  return { type: 'tags', tags, render: selfRender, prune: [] }
+}

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

@@ -0,0 +1,54 @@
+import { eq } from 'drizzle-orm'
+import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'
+import { publishStatus } from '../../database/publish-status'
+
+export interface PublishOutcome {
+  status: 'success' | 'error'
+  /** The failure message (render / write / S3) on an 'error' outcome; omitted/null on success. */
+  error?: string | null
+  /** Which output the attempt wrote to — `outputConfig().driver` ('local' | 's3'). */
+  target: string
+}
+
+/**
+ * Upsert the LATEST publish outcome for a route — one row per route (latest-state, not a history). Called
+ * by the runtime publisher after each render+put (success) or when one throws (error). Resilient by design:
+ * a missing `publish_status` table (a not-yet-migrated deploy — prod never auto-DDLs) degrades to a warn
+ * rather than breaking the publish loop or masking the real render/write error in the caller's catch. The
+ * timestamp is an explicit `new Date()` so the conflict-update branch (which does not fire `$defaultFn`)
+ * also refreshes it; drizzle maps it to UNIX seconds (mode:'timestamp'), never raw milliseconds.
+ */
+export function recordPublishStatus(db: BetterSQLite3Database, route: string, outcome: PublishOutcome): void {
+  try {
+    const set = { status: outcome.status, error: outcome.error ?? null, target: outcome.target, updatedAt: new Date() }
+    db.insert(publishStatus).values({ route, ...set }).onConflictDoUpdate({ target: publishStatus.route, set }).run()
+  } catch (error) {
+    console.warn('[kestrel] could not record publish status (is `publish_status` migrated? run `db:migrate`):', (error as Error).message)
+  }
+}
+
+/**
+ * Classify a route's render result into a publish outcome:
+ *  - `success` — a 200 with a rendered body (write it + record success).
+ *  - `error`   — a 5xx: the page itself rendered to a server error (a bad block / relation / template).
+ *                Crucially this surfaces as a non-200 RESPONSE, not a thrown exception, so without this
+ *                branch it would be a silent skip leaving a stale `success` row — the failure mode the
+ *                editor ampel most needs to show.
+ *  - `skip`    — any other non-200 (a draft / unpublish race resolving to a 404 / redirect): not an error,
+ *                leave the route's status untouched (the prune path handles a real unpublish).
+ */
+export function renderOutcome(status: number, hasBody: boolean): 'success' | 'error' | 'skip' {
+  if (status === 200 && hasBody) return 'success'
+  if (status >= 500) return 'error'
+  return 'skip'
+}
+
+/** 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 {
+  try {
+    db.delete(publishStatus).where(eq(publishStatus.route, route)).run()
+  } catch (error) {
+    console.warn('[kestrel] could not clear publish status:', (error as Error).message)
+  }
+}