@michaelthielemann/kestrel 3.0.1 → 4.0.0

package/layers/media/server/utils/ai-signal-detect.ts

@@ -1,155 +0,0 @@
-/**
- * Upload-time scan for signals that a file was AI-generated or -manipulated (EU AI Act Art. 50).
- *
- * **This produces EVIDENCE, never a classification.** Everything it finds is quoted into the free-text
- * `aiNote`; the legal `aiSourceType` stays a deliberate human decision, because a signal is neither proof
- * nor its absence a disproof: metadata survives no re-save, screenshot or re-encode, and an upstream file
- * can be mislabeled or forged. In particular a C2PA manifest is reported as PRESENT only — verifying its
- * signature needs the full C2PA SDK plus a trust list, which Kestrel deliberately does not ship.
- *
- * Pure (no DB, no Nitro) so it stays unit-testable, and never throws: an unreadable file is simply no
- * evidence, which must not fail the upload it came with.
- */
-
-/** Tools that name themselves in EXIF `Software`. Matched case-insensitively as whole phrases, so an
- *  ordinary "Adobe Photoshop" is not caught by the "Adobe Firefly" entry. */
-const KNOWN_GENERATORS = [
-  'midjourney', 'dall-e', 'dall·e', 'adobe firefly', 'stable diffusion', 'leonardo.ai',
-  'nightcafe', 'bing image creator', 'google imagefx', 'imagen', 'flux.1', 'ideogram',
-]
-
-/** PNG text-chunk keywords the Stable-Diffusion / ComfyUI families write their generation graph under. */
-const GENERATION_KEYWORDS = ['parameters', 'prompt', 'workflow']
-
-export interface AiSignal {
-  /** One human-readable line per signal found, in a stable order. Never empty (the result is null instead). */
-  evidence: string[]
-}
-
-/** Walk PNG chunks after the 8-byte signature, yielding `[type, data]`. Bails out on any malformed length. */
-function* pngChunks(bytes: Buffer): Generator<[string, Buffer]> {
-  if (bytes.length < 8 || bytes.readUInt32BE(0) !== 0x89504E47) return
-  let at = 8
-  while (at + 8 <= bytes.length) {
-    const len = bytes.readUInt32BE(at)
-    const end = at + 8 + len
-    if (len > bytes.length || end + 4 > bytes.length) return
-    yield [bytes.toString('latin1', at + 4, at + 8), bytes.subarray(at + 8, end)]
-    at = end + 4 // skip the trailing CRC
-  }
-}
-
-/** Walk JPEG marker segments after SOI, yielding `[marker, payload]`. Stops at SOS (entropy-coded data). */
-function* jpegSegments(bytes: Buffer): Generator<[number, Buffer]> {
-  if (bytes.length < 4 || bytes[0] !== 0xFF || bytes[1] !== 0xD8) return
-  let at = 2
-  while (at + 4 <= bytes.length) {
-    if (bytes[at] !== 0xFF) return
-    const marker = bytes[at + 1]!
-    if (marker === 0xDA || marker === 0xD9) return
-    const len = bytes.readUInt16BE(at + 2)
-    if (len < 2 || at + 2 + len > bytes.length) return
-    yield [marker, bytes.subarray(at + 4, at + 2 + len)]
-    at += 2 + len
-  }
-}
-
-/** Walk RIFF/WebP chunks, yielding `[fourcc, data]`. Chunks are padded to an even length. */
-function* riffChunks(bytes: Buffer): Generator<[string, Buffer]> {
-  if (bytes.length < 12 || bytes.toString('latin1', 0, 4) !== 'RIFF') return
-  let at = 12
-  while (at + 8 <= bytes.length) {
-    const len = bytes.readUInt32LE(at + 4)
-    const end = at + 8 + len
-    if (len > bytes.length || end > bytes.length) return
-    yield [bytes.toString('latin1', at, at + 4), bytes.subarray(at + 8, end)]
-    at = end + (len % 2)
-  }
-}
-
-/**
- * The IPTC Digital Source Type a generator self-declared, read straight out of the embedded XMP packet.
- * Deliberately a byte-level scan rather than a metadata library: XMP is the same XML in every container,
- * so this also covers the ones exifr cannot open (WebP), and it costs one `indexOf` when absent.
- */
-function findDigitalSourceType(bytes: Buffer): string | null {
-  const at = bytes.indexOf('DigitalSourceType', 0, 'latin1')
-  if (at < 0) return null
-  const window = bytes.toString('latin1', at, Math.min(at + 512, bytes.length))
-  // Both XMP serializations: as an rdf:Description attribute, or as its own element.
-  const value = /^DigitalSourceType\s*=\s*"([^"]*)"/.exec(window)?.[1]
-    ?? /^DigitalSourceType[^>]*>([^<]*)</.exec(window)?.[1]
-  const trimmed = value?.trim()
-  return trimmed ? trimmed : null
-}
-
-/** True when the file structurally carries a C2PA/JUMBF manifest store. Presence only — never verified. */
-function hasC2paManifest(bytes: Buffer): boolean {
-  for (const [type] of pngChunks(bytes)) if (type === 'caBX') return true
-  // C2PA-in-JPEG lives in APP11 segments whose payload starts with the JUMBF "JP" identifier.
-  for (const [marker, payload] of jpegSegments(bytes)) {
-    if (marker === 0xEB && payload.length >= 2 && payload.toString('latin1', 0, 2) === 'JP') return true
-  }
-  for (const [fourcc] of riffChunks(bytes)) if (fourcc === 'C2PA') return true
-  return false
-}
-
-/** The generation-parameter keyword a PNG text chunk is stored under, or null. Covers tEXt/zTXt/iTXt —
- *  in all three the keyword is the leading null-terminated string, so a compressed payload needs no
- *  inflating to be recognised (exifr only decodes the uncompressed tEXt form). */
-function findPngGenerationChunk(bytes: Buffer): string | null {
-  for (const [type, data] of pngChunks(bytes)) {
-    if (type !== 'tEXt' && type !== 'zTXt' && type !== 'iTXt') continue
-    const nul = data.indexOf(0)
-    const keyword = data.toString('latin1', 0, nul < 0 ? data.length : nul).toLowerCase()
-    if (GENERATION_KEYWORDS.includes(keyword)) return keyword
-  }
-  return null
-}
-
-/** The EXIF `Software`/`ProcessingSoftware` value, when it names a tool on the known-generator list. */
-async function findGeneratorSoftware(bytes: Buffer): Promise<string | null> {
-  let tags: Record<string, unknown> | undefined
-  try {
-    // Loaded lazily: consumers who never turn the feature on never pay the module's parse cost.
-    const exifr = (await import('exifr')).default
-    tags = await exifr.parse(bytes, { tiff: true, exif: true, mergeOutput: true }) as Record<string, unknown> | undefined
-  } catch {
-    return null // an unsupported container or a corrupt header is simply no evidence
-  }
-  for (const key of ['Software', 'ProcessingSoftware']) {
-    const value = tags?.[key]
-    if (typeof value !== 'string' || !value.trim()) continue
-    const haystack = value.toLowerCase()
-    if (KNOWN_GENERATORS.some((g) => haystack.includes(g))) return value.trim()
-  }
-  return null
-}
-
-/**
- * Scan an uploaded file for AI-origin signals. Returns null when nothing matched — which is NOT evidence
- * of non-AI origin, only the absence of a declaration.
- */
-export async function detectAiSignal(bytes: Buffer, _mime: string): Promise<AiSignal | null> {
-  const evidence: string[] = []
-
-  const sourceType = findDigitalSourceType(bytes)
-  if (sourceType) evidence.push(`IPTC/XMP Digital Source Type: ${sourceType}`)
-
-  const software = await findGeneratorSoftware(bytes)
-  if (software) evidence.push(`EXIF Software: ${software}`)
-
-  if (hasC2paManifest(bytes)) {
-    evidence.push('C2PA content-credentials manifest present (unverified — presence only, no signature check)')
-  }
-
-  const keyword = findPngGenerationChunk(bytes)
-  if (keyword) evidence.push(`PNG text chunk "${keyword}" present (Stable-Diffusion-style generation parameters)`)
-
-  return evidence.length ? { evidence } : null
-}
-
-/** How the scan's findings are worded into `aiNote`. Kept here so the wording has one home. */
-export function aiSignalNote(signal: AiSignal): string {
-  return `Detected at upload: ${signal.evidence.join('; ')}`
-}

package/layers/media/server/utils/backfill.ts

@@ -1,144 +0,0 @@
-import { eq, getTableColumns } from 'drizzle-orm'
-import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'
-import type { ResolvedImagePolicy, ResolvedVariant, VariantFormat } from '../../../core/server/utils/kestrel-config'
-import type { StorageDriver } from '../../../core/server/utils/storage'
-import { media } from '../collections/media'
-import { deriveImage, RASTER } from './derive'
-import { derivativeKey, type DerivativeManifest } from './record'
-import { readVariantRegistry, resolveActiveVariants } from './variants'
-import { withLock, mediaLockKey } from '../../../core/server/utils/key-lock'
-import { emitMediaWrite } from './media-write'
-
-// Mirrors index.post.ts: a long-lived (non-immutable, so a replace isn't pinned) cache for originals +
-// derivatives. Backfilled objects MUST carry the same header or the CDN caches them differently.
-const MEDIA_CACHE_CONTROL = 'public, max-age=31536000'
-
-export interface BackfillPlan {
-  /** Specs, each carrying ONLY its missing formats, to derive + add. */
-  missing: ResolvedVariant[]
-  /** Object keys of manifest entries no longer in the active set (deregistered) — to prune. Always empty
-   *  when the caller passes `prune: false`, i.e. the active set is a fallback rather than the registry. */
-  orphanKeys: string[]
-}
-
-/**
- * Pure diff of a media row's derivative manifest against the active variant set: what to generate, what to
- * prune. A proportional spec wider than the source is never "missing" (deriveImage would skip it, so it can
- * never be satisfied). Orphans are keyed per `<name>.<format>`, so a deregistered FORMAT of a still-active
- * name is pruned too.
- */
-export function planBackfill(
-  row: { width: number | null; derivatives: DerivativeManifest | null }, specs: ResolvedVariant[], prune = true,
-): BackfillPlan {
-  const manifest = row.derivatives ?? {}
-  const activeKeys = new Set<string>()
-  const missing: ResolvedVariant[] = []
-  for (const spec of specs) {
-    const applicable = spec.height != null || !row.width || spec.width <= row.width
-    const missingFormats: VariantFormat[] = []
-    for (const f of spec.formats) {
-      activeKeys.add(`${spec.name}.${f}`)
-      if (applicable && !(`${spec.name}.${f}` in manifest)) missingFormats.push(f)
-    }
-    if (missingFormats.length) missing.push({ ...spec, formats: missingFormats })
-  }
-  const orphanKeys: string[] = []
-  if (prune) for (const [k, entry] of Object.entries(manifest)) if (!activeKeys.has(k) && entry.key) orphanKeys.push(entry.key)
-  return { missing, orphanKeys }
-}
-
-interface BackfillRow { id: number; storageKey: string; mime: string; width: number | null; derivatives: DerivativeManifest | null }
-
-/**
- * Reconcile ONE media row to the active set: derive its missing variants from the original (put-first),
- * write the updated manifest, then prune orphan objects LAST (a crash never dangles the manifest). The pruned
- * objects are this row's OWN deregistered derivatives — self-owned, so no cross-row ownership guard is needed
- * (that is Slice 9's published-media GC, a different concern).
- */
-export async function backfillRow(
-  db: BetterSQLite3Database, driver: StorageDriver, row: BackfillRow, specs: ResolvedVariant[], policy: ResolvedImagePolicy, prune = true,
-): Promise<{ generated: number; pruned: number }> {
-  const plan = planBackfill(row, specs, prune)
-  if (!plan.missing.length && !plan.orphanKeys.length) return { generated: 0, pruned: 0 }
-
-  const orphaned = new Set(plan.orphanKeys)
-  const manifest: DerivativeManifest = {}
-  for (const [k, e] of Object.entries(row.derivatives ?? {})) if (!orphaned.has(e.key)) manifest[k] = e
-
-  let generated = 0
-  if (plan.missing.length) {
-    if (typeof driver.get !== 'function') throw new Error('storage driver cannot read originals back (no get()) — backfill needs it')
-    const derived = await deriveImage(await driver.get(row.storageKey), { ...policy, variants: plan.missing })
-    for (const v of derived.variants) {
-      const key = derivativeKey(row.storageKey, v.name, v.format)
-      await driver.put(key, v.bytes, v.mime, { cacheControl: MEDIA_CACHE_CONTROL })
-      manifest[`${v.name}.${v.format}`] = { key, width: v.width, height: v.height, mime: v.mime }
-      generated++
-    }
-  }
-
-  const cols = getTableColumns(media) as Record<string, never>
-  db.update(media).set({ derivatives: manifest, updatedAt: new Date() } as never).where(eq(cols.id, row.id)).run()
-  // Published pages hold this row's srcset candidates, so a rewritten manifest — especially a pruned
-  // key, which now 404s — has to re-render them. Emitted before the prune: a delete that throws must
-  // not leave the already-written manifest un-republished.
-  emitMediaWrite({ id: row.id }, { id: row.id })
-  for (const key of plan.orphanKeys) await driver.delete(key)
-  return { generated, pruned: plan.orphanKeys.length }
-}
-
-export interface BackfillReport {
-  rows: number; rowsChanged: number; generated: number; pruned: number; check: boolean
-  /** The run declined to prune because the active set is the config fallback, not the registry — so a
-   *  `pruned: 0` here means "could not tell what is registered", not "nothing was deregistered". */
-  pruneWithheld: boolean
-}
-
-/**
- * Iterate every raster media row, reconciling each to the active variant set. Sequential (sharp CPU + a
- * full-original GET per row) and best-effort per row — a corrupt original is logged and skipped, never
- * aborting the whole run. `check` reports the plan (rows / would-generate / would-prune) without writing.
- */
-export async function runBackfill(
-  db: BetterSQLite3Database, driver: StorageDriver, policy: ResolvedImagePolicy, opts: { check?: boolean } = {},
-): Promise<BackfillReport> {
-  // Deriving a superset is harmless, deleting against one is not, so the prune follows the resolver's own
-  // verdict: an unmigrated, unreadable, empty or wholly-rejected registry resolves to the CONFIG fallback,
-  // under which every registered variant of every row looks deregistered.
-  const { specs, fromRegistry: prune } = resolveActiveVariants(readVariantRegistry(db), policy.variants, policy.presets)
-  if (!prune) console.warn('[kestrel] backfill: no usable variant registry — generating against the config fallback and withholding the prune. Run a full publish so the prerender scan populates media_settings.')
-  const rows = db.select().from(media).all() as BackfillRow[]
-  const report: BackfillReport = { rows: rows.length, rowsChanged: 0, generated: 0, pruned: 0, check: !!opts.check, pruneWithheld: !prune }
-  for (const snapshot of rows) {
-    if (!RASTER.has(snapshot.mime)) continue
-    if (opts.check) {
-      // Dry-run reads only (against the snapshot) — no mutation, so no lock.
-      const plan = planBackfill(snapshot, specs, prune)
-      const toGenerate = plan.missing.reduce((n, s) => n + s.formats.length, 0)
-      if (!toGenerate && !plan.orphanKeys.length) continue
-      report.rowsChanged++
-      report.generated += toGenerate
-      report.pruned += plan.orphanKeys.length
-      continue
-    }
-    // Serialize per storageKey with the upload path, and re-read the row FRESH inside the lock: a concurrent
-    // overwrite may have replaced the bytes/dims/manifest since the up-front snapshot, and reconciling the
-    // stale snapshot against the new object would write a manifest whose dims describe the OLD image.
-    await withLock(mediaLockKey(snapshot.storageKey), async () => {
-      const cols = getTableColumns(media) as Record<string, never>
-      const row = db.select().from(media).where(eq(cols.id, snapshot.id)).get() as BackfillRow | undefined
-      if (!row || !RASTER.has(row.mime)) return
-      const plan = planBackfill(row, specs, prune)
-      if (!plan.missing.length && !plan.orphanKeys.length) return
-      report.rowsChanged++
-      try {
-        const r = await backfillRow(db, driver, row, specs, policy, prune)
-        report.generated += r.generated
-        report.pruned += r.pruned
-      } catch (error) {
-        console.error(`[kestrel] backfill failed for media ${row.id} (${row.storageKey}):`, (error as Error)?.message ?? error)
-      }
-    })
-  }
-  return report
-}

package/layers/media/server/utils/derive.ts

@@ -1,59 +0,0 @@
-import sharp from 'sharp'
-import { rgbaToThumbHash } from 'thumbhash'
-import type { ResolvedImagePolicy } from '../../../core/server/utils/kestrel-config'
-
-// The derivation policy is resolved once from kestrel config (KESTREL_MEDIA_IMAGE_* env → config → default)
-// and threaded in by the upload handler. `DEFAULT_IMAGE_POLICY` is auto-imported from kestrel-config
-// (the single export site); re-exporting it here would register a duplicate auto-import.
-export type ImagePolicy = ResolvedImagePolicy
-
-// Raster mimes that receive a derivative ladder. GIF is intentionally excluded: deriving WebP flattens it
-// to a static first frame. Shared by the upload handler and the backfill task so they never disagree.
-export const RASTER = new Set(['image/png', 'image/jpeg', 'image/webp', 'image/avif'])
-
-export interface DerivedImage {
-  width: number
-  height: number
-  thumbhash: string
-  variants: { name: string; width: number; height: number; format: 'webp' | 'jpeg'; mime: string; bytes: Buffer }[]
-}
-
-export async function deriveImage(input: Buffer, policy: ImagePolicy): Promise<DerivedImage> {
-  const meta = await sharp(input, { limitInputPixels: 268402689 }).metadata()
-  // sharp's metadata reports the stored (pre-EXIF-rotation) dimensions; .rotate() only affects
-  // the pixel pipeline. For EXIF orientation 5-8 (90°/270°, e.g. phone portrait photos) the
-  // displayed image — and every variant below, which applies .rotate() — has width/height swapped.
-  const swap = (meta.orientation ?? 0) >= 5
-  const width = (swap ? meta.height : meta.width) ?? 0
-  const height = (swap ? meta.width : meta.height) ?? 0
-
-  const small = await sharp(input).rotate().resize(100, 100, { fit: 'inside' }).ensureAlpha().raw().toBuffer({ resolveWithObject: true })
-  const thumbhash = Buffer.from(rgbaToThumbHash(small.info.width, small.info.height, small.data)).toString('base64')
-
-  // Derive exactly the active variant set (name × format). A proportional spec wider than the source is
-  // skipped (never upscale); a crop clamps via withoutEnlargement. The stored width/height are the REAL
-  // pipeline-output dims (correct for crops and for clamped proportionals — not an aspect-ratio guess).
-  const variants: DerivedImage['variants'] = []
-  for (const spec of policy.variants) {
-    // sharp throws on a non-positive-integer dimension — coerce so a malformed spec (e.g. a stale
-    // `height: ''`) degrades to a proportional resize instead of 500ing the upload.
-    const specWidth = toPosInt(spec.width)
-    if (specWidth == null) continue
-    const cropHeight = toPosInt(spec.height)
-    if (cropHeight == null && width > 0 && specWidth > width) continue
-    for (const format of spec.formats) {
-      const resized = cropHeight == null
-        ? sharp(input).rotate().resize({ width: specWidth, withoutEnlargement: true })
-        : sharp(input).rotate().resize(specWidth, cropHeight, { fit: spec.fit, position: spec.position, withoutEnlargement: true })
-      const encoded = format === 'jpeg' ? resized.jpeg({ quality: policy.jpegQuality }) : resized.webp({ quality: policy.webpQuality })
-      const { data, info } = await encoded.toBuffer({ resolveWithObject: true })
-      variants.push({ name: spec.name, width: info.width, height: info.height, format, mime: format === 'jpeg' ? 'image/jpeg' : 'image/webp', bytes: data })
-    }
-  }
-  return { width, height, thumbhash, variants }
-}
-
-function toPosInt(value: unknown): number | null {
-  const n = Math.floor(Number(value))
-  return Number.isFinite(n) && n >= 1 ? n : null
-}

package/layers/media/server/utils/folder-paths.ts

@@ -1,42 +0,0 @@
-/** Parent folder path; '' for a top-level folder; null for the root itself. */
-export function parentOf(path: string): string | null {
-  if (path === '') return null
-  const i = path.lastIndexOf('/')
-  return i === -1 ? '' : path.slice(0, i)
-}
-
-/** Every ancestor folder (excluding the path itself and the root ''), root-first. */
-export function ancestorsOf(path: string): string[] {
-  const out: string[] = []
-  const segs = path.split('/').filter(Boolean)
-  for (let i = 1; i < segs.length; i++) out.push(segs.slice(0, i).join('/'))
-  return out
-}
-
-/** The path plus all its ancestors (excluding root ''), root-first. */
-export function selfAndAncestors(path: string): string[] {
-  return path === '' ? [] : [...ancestorsOf(path), path]
-}
-
-/** True when `path` is exactly one level below `parent`. */
-export function isImmediateChild(parent: string, path: string): boolean {
-  return parentOf(path) === parent
-}
-
-/** Last path segment. */
-export function childName(path: string): string {
-  const i = path.lastIndexOf('/')
-  return i === -1 ? path : path.slice(i + 1)
-}
-
-/** True when `path` is `prefix` itself or a descendant of it (anchored on a '/' boundary). */
-export function isUnder(prefix: string, path: string): boolean {
-  return path === prefix || path.startsWith(`${prefix}/`)
-}
-
-/** Re-base `path` from the `from` subtree onto `to` (path unchanged if not under `from`). */
-export function rewritePrefix(path: string, from: string, to: string): string {
-  if (path === from) return to
-  if (path.startsWith(`${from}/`)) return to + path.slice(from.length)
-  return path
-}

package/layers/media/server/utils/folders.ts

@@ -1,12 +0,0 @@
-import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'
-import { folders } from '../database/folders'
-import { sanitizeFolder } from './naming'
-import { selfAndAncestors } from './folder-paths'
-
-/** Ensure a folder row exists for `path` and every ancestor (after sanitizing). Idempotent. */
-export function ensureFolder(db: BetterSQLite3Database, path: string): void {
-  const clean = sanitizeFolder(path)
-  for (const p of selfAndAncestors(clean)) {
-    db.insert(folders).values({ path: p }).onConflictDoNothing().run()
-  }
-}

package/layers/media/server/utils/library.ts

@@ -1,91 +0,0 @@
-import { and, eq, like, count, getTableColumns, sql, isNull, or, asc, desc } from 'drizzle-orm'
-import type { BetterSQLite3Database } from 'drizzle-orm/better-sqlite3'
-import type { AnySQLiteTable } from 'drizzle-orm/sqlite-core'
-import { media } from '../collections/media'
-import { folders as foldersTable } from '../database/folders'
-import { resolveMedia } from './resolve'
-import { childName, isImmediateChild } from './folder-paths'
-import { primaryLocale } from '../../../core/server/utils/locale'
-import { escapeLike } from '../../../core/server/utils/sql'
-
-export interface LibraryQuery { folder?: string; search?: string; type?: 'image' | 'all'; page?: number; perPage?: number; sort?: string }
-export interface LibraryFolder { path: string; name: string; size: number }
-
-// Sortable table columns → media column. `sort` is `field` (asc) or `-field` (desc); unknown → name.
-const SORT_FIELDS = ['name', 'size', 'type'] as const
-function parseSort(sort: string | undefined): { field: (typeof SORT_FIELDS)[number]; desc: boolean } {
-  const isDesc = (sort ?? '').startsWith('-')
-  const field = (sort ?? '').replace(/^-/, '') as (typeof SORT_FIELDS)[number]
-  return { field: SORT_FIELDS.includes(field) ? field : 'name', desc: isDesc }
-}
-
-export function listLibrary(db: BetterSQLite3Database, q: LibraryQuery, publicUrl: (key: string) => string) {
-  const folder = q.folder ?? ''
-  const cols = getTableColumns(media) as Record<string, never>
-  const t = media as AnySQLiteTable
-
-  // root files are stored with folder NULL (the uploader maps '' → null), so match both at root
-  const conds = [folder === '' ? or(isNull(cols.folder), eq(cols.folder, '')) : eq(cols.folder, folder)]
-  if (q.search) conds.push(sql`${cols.filename} like ${`%${escapeLike(q.search)}%`} escape '\\'`)
-  if (q.type === 'image') conds.push(like(cols.mime, 'image/%'))
-  const where = and(...conds)
-
-  // `?? default` catches only null/undefined, NOT NaN (`?perPage=abc` → Number('abc') === NaN), and
-  // .limit(NaN) binds LIMIT NULL / 500s in SQLite — guard with Number.isFinite (mirrors crud.list).
-  const num = (v: number | undefined, fallback: number) => (Number.isFinite(v) ? (v as number) : fallback)
-  const page = Math.max(1, Math.floor(num(q.page, 1)))
-  const perPage = Math.min(200, Math.max(1, Math.floor(num(q.perPage, 60))))
-
-  // Files are paginated, so sorting must happen in SQL. Tie-break by filename for a stable order.
-  const sort = parseSort(q.sort)
-  const sortCol = sort.field === 'size' ? cols.size : sort.field === 'type' ? cols.mime : cols.filename
-  const dir = sort.desc ? desc : asc
-  const rows = db.select().from(t).where(where).orderBy(dir(sortCol), asc(cols.filename))
-    .limit(perPage).offset((page - 1) * perPage).all() as Record<string, unknown>[]
-  const totalRow = db.select({ value: count() }).from(t).where(where).get() as { value: number } | undefined
-
-  // Resolve in the configured PRIMARY locale — the same locale the viewer edits alt in (and the locale
-  // resolveMedia itself falls back to), so an alt edit round-trips into the list for any primary, not
-  // just 'en'. A literal 'en' here would let an 'en' translation mask a non-en primary's alt.
-  const locale = primaryLocale()
-  const files = rows.map((r) => {
-    const m = resolveMedia(r as never, locale, publicUrl)
-    // serialize the webp ladder to an <img srcset> string; non-derivable files (pdf/svg) → undefined
-    // so the grid renders its ext badge instead of a broken <img> (an empty array is truthy)
-    const srcset = m.srcset.length ? m.srcset.map((s) => `${s.url} ${s.width}w`).join(', ') : undefined
-    return {
-      id: m.id, filename: r.filename as string, mime: m.mime, folder: r.folder as string,
-      size: r.size as number, width: m.width, height: m.height, thumbhash: m.thumbhash,
-      src: m.src, srcset, alt: m.alt, aiDisclosure: m.aiDisclosure,
-      createdAt: r.createdAt as Date, updatedAt: r.updatedAt as Date,
-    }
-  })
-
-  const allFolders = db.select({ path: foldersTable.path }).from(foldersTable).all()
-
-  // Recursive folder sizes: one grouped query sums bytes per exact folder across the current subtree,
-  // then each immediate child's whole subtree is rolled up in JS (cheap: one row per distinct folder).
-  const sizeBase = db.select({ folder: cols.folder, total: sql<number>`coalesce(sum(${cols.size}), 0)` }).from(t).groupBy(cols.folder)
-  const sizeRows = (folder === ''
-    ? sizeBase
-    : sizeBase.where(or(eq(cols.folder, folder), sql`${cols.folder} like ${`${escapeLike(folder)}/%`} escape '\\'`))
-  ).all() as { folder: string | null; total: number }[]
-  const sizeOf = (prefix: string): number =>
-    sizeRows.reduce((sum, r) => (((r.folder ?? '') === prefix || (r.folder ?? '').startsWith(`${prefix}/`)) ? sum + Number(r.total ?? 0) : sum), 0)
-
-  // Folders always render before files; within the group they follow the same sort (by name, or by
-  // recursive size; type is uniform for folders so it falls back to name).
-  const folderList: LibraryFolder[] = allFolders
-    .filter((f) => isImmediateChild(folder, f.path))
-    .map((f) => ({ path: f.path, name: childName(f.path), size: sizeOf(f.path) }))
-    .sort((a, b) => {
-      const c = sort.field === 'size' ? a.size - b.size : a.name.localeCompare(b.name)
-      return sort.desc ? -c : c
-    })
-
-  // The root always exists; any other folder must have a row in the registry. Lets the client tell a
-  // genuinely-empty folder apart from a path that does not exist (→ error instead of a blank listing).
-  const exists = folder === '' || allFolders.some((f) => f.path === folder)
-
-  return { folder, exists, folders: folderList, files, total: Number(totalRow?.value ?? 0), page, perPage }
-}

package/layers/media/server/utils/media-cleanup.ts

@@ -1,27 +0,0 @@
-import type { WriteEvent } from '../../../core/server/utils/write-events'
-import type { DerivativeManifest } from './record'
-
-/** Every storage key a media row owns — the original plus each generated derivative (the webp ladder). */
-export function mediaStorageKeys(row: Record<string, unknown>): string[] {
-  const keys: string[] = []
-  if (typeof row.storageKey === 'string' && row.storageKey) keys.push(row.storageKey)
-  const derivatives = row.derivatives as DerivativeManifest | null | undefined
-  if (derivatives && typeof derivatives === 'object') {
-    for (const d of Object.values(derivatives)) {
-      if (d && typeof d.key === 'string' && d.key) keys.push(d.key)
-    }
-  }
-  return keys
-}
-
-/**
- * Storage keys to delete when a write event is a media-record DELETE — the original + ALL derivatives;
- * `[]` for anything else. This makes deleting a media record remove its files on EVERY delete path:
- * the generic CRUD `remove()` emits a delete event handled here, complementing the media library's own
- * `deleteAffected` (which deletes storage inline). So a media record can never be removed while leaving
- * orphaned objects in storage — principle 4 (output ≡ DB) for media. Pure → unit-testable.
- */
-export function planMediaDeletion(event: WriteEvent): string[] {
-  if (event.def.name !== 'media' || event.after !== null || !event.before) return []
-  return mediaStorageKeys(event.before)
-}

package/layers/media/server/utils/media-enabled.ts

@@ -1,23 +0,0 @@
-import { createError } from 'h3'
-import { collectionEnabled } from '../../../core/server/schema/bootstrap'
-import { resolveServerKestrel, serverRuntimeConfig } from '../../../core/server/utils/server-config'
-import mediaCollection from '../collections/media'
-
-/**
- * Whether the `media` built-in is active for this consumer. The media routes are static files rather than
- * registry-driven, so they have to ask the SAME predicate the registry plugin and the schema engine use.
- * Without it a consumer who turned the built-in off keeps serving endpoints that query a table the schema
- * engine deliberately never created.
- */
-export function mediaCollectionEnabled(): boolean {
-  const toggles = (serverRuntimeConfig()?.kestrel?.collections ?? resolveServerKestrel().collections) as
-    | Record<string, boolean>
-    | undefined
-  return collectionEnabled(mediaCollection.def, toggles)
-}
-
-/** Route guard: with the built-in disabled the endpoint genuinely does not exist, so 404 — not a 500 from
- *  the missing table. */
-export function requireMediaCollection(): void {
-  if (!mediaCollectionEnabled()) throw createError({ statusCode: 404, statusMessage: 'Media collection is disabled' })
-}