@michaelthielemann/kestrel 3.0.0 → 4.0.0

package/layers/core/modules/auto-discovery/scan.ts

@@ -70,9 +70,86 @@ export function collectBlockSfcs(layerRoots: string[], subdir = 'app/blocks', li
   return [...byName.values()].sort()
 }
 
+/**
+ * Each layer's OWN `server/db/manifest.ts` (ADR-0012 ownership manifest), one per layer that has one.
+ * Unlike `collectDefinitions`, this does NOT dedupe by basename: every layer's manifest is a distinct
+ * module contribution (no shadow/override semantics — `media`'s manifest and `public`'s manifest both
+ * happen to be named `manifest.ts`, and both must survive). Layer order is whatever `layerRoots` is.
+ */
+export function collectManifestFiles(layerRoots: string[], list?: Lister): string[] {
+  const files: string[] = []
+  for (const root of layerRoots) {
+    for (const file of listDefinitionFiles(join(root, 'server/db'), list)) {
+      if (basename(file) === 'manifest.ts') files.push(file)
+    }
+  }
+  return files
+}
+
 export function renderRegistry(absPaths: string[]): string {
   if (!absPaths.length) return 'export default []'
   const imports = absPaths.map((p, i) => `import _${i} from ${JSON.stringify(p)}`)
   const arr = absPaths.map((_, i) => `_${i}`).join(', ')
   return `${imports.join('\n')}\nexport default [${arr}]`
 }
+
+/**
+ * A registry combining package-provided items (each package's `kestrelDiscovery.<property>`, read via a
+ * bare specifier — no filesystem/`node_modules` guessing) with consumer/layer-scanned files, with a
+ * SAME-NAME layer item overriding a package's (via `mergeKestrelDiscovered`, evaluated at virtual-load
+ * time — package names aren't knowable at codegen time without loading the package, which this
+ * deliberately avoids doing at build time). `nameOfExpr` is a JS arrow-function source string the
+ * generated module evaluates per item (e.g. `'(x) => x.name'` for collections,
+ * `'(x) => __kestrelTableName(x)'` for schema-tables, paired with `extraImports` supplying
+ * `__kestrelTableName`).
+ */
+export function renderPackageMergedRegistry(opts: {
+  packages: string[]
+  property: 'collections' | 'schemaTables'
+  consumerFiles: string[]
+  nameOfExpr: string
+  extraImports?: string
+  preamble?: string
+}): string {
+  const pkgImports = opts.packages.map((spec, i) => `import { kestrelDiscovery as __pkg${i} } from ${JSON.stringify(spec)}`)
+  const pkgSpread = opts.packages.map((_, i) => `...(__pkg${i}.${opts.property} ?? [])`).join(', ')
+  const consumerImports = opts.consumerFiles.map((p, i) => `import _c${i} from ${JSON.stringify(p)}`)
+  const consumerArr = opts.consumerFiles.map((_, i) => `_c${i}`).join(', ')
+  return [
+    opts.preamble ?? '',
+    opts.extraImports ?? '',
+    `import { mergeKestrelDiscovered } from '@michaelthielemann/kestrel-core'`,
+    ...pkgImports,
+    ...consumerImports,
+    `export default mergeKestrelDiscovered([${pkgSpread}], [${consumerArr}], ${opts.nameOfExpr})`,
+  ].filter(Boolean).join('\n')
+}
+
+/**
+ * A registry concatenating package-provided items (`kestrelDiscovery.<property>`) with consumer/layer-
+ * scanned files — NO dedup (mirrors `collectManifestFiles`'s own "every contribution is distinct, no
+ * shadow semantics" contract; unlike collections/schema-tables, two manifests sharing a name is not a
+ * schema conflict, so there is nothing to override).
+ */
+export function renderPackageConcatRegistry(opts: {
+  packages: string[]
+  property: 'manifest'
+  consumerFiles: string[]
+  preamble?: string
+}): string {
+  const pkgImports = opts.packages.map((spec, i) => `import { kestrelDiscovery as __pkg${i} } from ${JSON.stringify(spec)}`)
+  // `opts.packages` is expected to be pre-filtered to packages that actually contribute this property (the
+  // caller's per-category list), so every `.manifest` read here SHOULD be defined — but the spread stays
+  // conditional (`...(x ? [x] : [])`, not a bare `x`) as a defense-in-depth guard: a package mis-listed in
+  // the wrong `PACKAGE_*` category contributes nothing instead of polluting the array with `undefined`.
+  const pkgItems = opts.packages.map((_, i) => `...(__pkg${i}.${opts.property} ? [__pkg${i}.${opts.property}] : [])`)
+  const consumerImports = opts.consumerFiles.map((p, i) => `import _c${i} from ${JSON.stringify(p)}`)
+  const consumerArr = opts.consumerFiles.map((_, i) => `_c${i}`)
+  const all = [...pkgItems, ...consumerArr].join(', ')
+  return [
+    opts.preamble ?? '',
+    ...pkgImports,
+    ...consumerImports,
+    `export default [${all}]`,
+  ].filter(Boolean).join('\n')
+}

package/layers/core/modules/auto-discovery/virtual.d.ts

@@ -10,6 +10,11 @@ declare module '#kestrel/schema-tables' {
   const tables: unknown[]
   export default tables
 }
+declare module '#kestrel/module-manifests' {
+  import type { OwnershipManifest } from '@michaelthielemann/kestrel-contracts'
+  const manifests: OwnershipManifest[]
+  export default manifests
+}
 declare module '#build/kestrel-layouts.mjs' {
   export const kestrelLayouts: string[]
 }

package/layers/core/modules/component-namespace/index.ts

@@ -5,6 +5,30 @@ import { KESTREL_COMPONENT_PREFIX, KESTREL_OVERRIDE_PRIORITY } from './shared'
 /** Where a consumer places a component that replaces a shipped one, relative to their `srcDir`. */
 export const KESTREL_OVERRIDE_DIR = 'Kestrel/components'
 
+/**
+ * RULING: the app-side layers (`admin`, `ui`, and the `app/` halves of `media`/`public`) stay LAYERS —
+ * they are not bridged into packages, and there is no `addComponentsDir`/`addImportsDir`
+ * module doing so. `admin` is the layer with the most at stake here: it registers by far the most
+ * components under `kestrelComponents()` (`layers/admin/nuxt.config.ts`, alongside `media`/`public`/`ui`),
+ * so it is the layer this override mechanism protects most. This module's own override mechanism (below)
+ * is WHY: it depends on Kestrel's own components being real, Nuxt-scannable `.vue` files in a real layer,
+ * resolved at a higher `addComponentsDir` priority than a consumer's override — a package's compiled
+ * `dist` output cannot participate in that priority system the same way. Bridging would cost the admin its
+ * per-component override story for no boot-order/discovery benefit these app-side files need (none of the
+ * eager-module-load or field-type-registration hazards the *server*-side package cut existed to fix apply
+ * here). Revisit only with strong evidence the cost is worth paying — see `docs/internals/layers-and-packages.md` §
+ * "The component/composable bridge".
+ *
+ * Composables are a separate question this mechanism does NOT cover: none of `admin`/`ui`'s ~30
+ * `use*`-named composables carry a `useKestrel*` prefix, and none need to — every one is internal editor
+ * state/logic (`useEditForm`, `useBlockTree`, `useCollectionOps`, …). Kestrel's own layers reuse them
+ * freely across the merged auto-import namespace (`media` uses `ui`'s `useT`/`useToast`/`useDragReorder`);
+ * what stays true is that no extension, package, or third-party consumer imports one, and none is ever
+ * documented as something a consumer reaches for — a consumer builds their own UI against collections/
+ * pipelines/field types, not by importing Kestrel's editor internals. There is consequently no override
+ * mechanism for composables (unlike components) and none is needed.
+ */
+
 export default defineNuxtModule({
   meta: { name: 'kestrel-component-namespace' },
   setup(_options, nuxt) {

package/layers/core/modules/kestrel/index.ts

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs'
 import { defineNuxtModule } from '@nuxt/kit'
-import { resolveKestrel, type KestrelConfig } from '../../server/utils/kestrel-config'
+import { resolveKestrel, type KestrelConfig } from '@michaelthielemann/kestrel-core'
 import { diagnoseAppShell } from './app-shell'
 
 /**
@@ -78,6 +78,11 @@ export default defineNuxtModule<KestrelConfig>({
     srv.aiDisclosure = c.aiDisclosure
     // Answer-engine toggles; `llmsFull` is server-only (it gates a Nitro route and what the publisher writes).
     srv.seo = c.seo
+    // Read by delivery-live's catch-all/read pipeline (see `KestrelConfig.delivery`'s own TSDoc) to
+    // decide whether to answer at all — everything else about it stays 'static'-shaped either way.
+    srv.delivery = c.delivery
+    // Extra path prefixes the live catch-all must fall through on (see `KestrelConfig.deliveryExempt`).
+    srv.deliveryExempt = c.deliveryExempt
     // Static-publish target for the runtime publisher (server-only). S3 creds are env-only; prefer the
     // output-specific creds, fall back to the shared media creds so a single S3 account "just works".
     srv.output = {

package/layers/core/modules/plugin-order/index.ts

@@ -0,0 +1,69 @@
+import { defineNuxtModule } from '@nuxt/kit'
+import { assertEffectiveOrderMatches, resolvePluginOrder, validatePluginOrder } from './plugin-order'
+
+/**
+ * Owns the execution order of the plugins Kestrel's own 6 layers ship (core/fields/media/auth/
+ * collections/public — see `plugin-order.ts`'s `PLUGIN_ORDER`), replacing Nitro's layer-then-filename
+ * sort with an explicit, declared list. A consumer's own plugins (and any extension layer's) are
+ * untouched — they keep using Nitro's default scan-and-append, landing wherever their own layer position
+ * in `extends` naturally puts them; this module only orders Kestrel's own.
+ *
+ * Mechanism: the `nitro:config` hook's config object (which becomes `nitro.options` once Nitro's own
+ * instance is built) gets `.plugins` pushed with `PLUGIN_ORDER`'s resolved absolute paths, in order — this
+ * hook runs BEFORE Nitro's own `scanPlugins` step. That step only appends a scanned file when it is not
+ * ALREADY in `nitro.options.plugins`
+ * (`nitropack/dist/core/index.mjs`: `if (!nitro.options.plugins.includes(plugin)) plugins.push(plugin)`),
+ * so every one of our explicitly-pushed paths is skipped by the scan (already present, same absolute path)
+ * and keeps our declared position — nothing needs renaming or moving on disk. `nitro:config` alone only
+ * proves what WE push, though — a separate `nitro:init` hook (which fires after every `nitro:config` hook
+ * and Nitro's own scan-and-append have both already run, against the fully-built Nitro instance) asserts
+ * the REAL, final `nitro.options.plugins` still starts with our declared order, contiguous and duplicate-
+ * free — see `assertEffectiveOrderMatches`'s own TSDoc for why this observer, not the push alone, is what
+ * actually proves "declared order ≡ effective order".
+ *
+ * The ADR-0029 eager-barrel-load guard for a future `00.*` plugin: NOT a mechanism in this module. It
+ * doesn't need to be — `@michaelthielemann/kestrel-media`/`@michaelthielemann/kestrel-collections`/`@michaelthielemann/kestrel-publishing`'s own barrels now
+ * self-guard (a used-binding `@michaelthielemann/kestrel-fields` import, first), so importing ANY of them is safe from ANY
+ * plugin position, including a hypothetical new `00.*` file. The computed rail proving this
+ * (`test/architecture/kestrel-discovery.test.ts`'s "every package whose OWN module graph reaches
+ * buildCollection()...") already re-checks every package on every test run, so a FUTURE package that
+ * starts calling `buildCollection()` without the guard fails there — independent of whatever plugin order
+ * this module declares. Plugin order literally cannot reintroduce this hazard class any more, which is the
+ * honest, verifiable version of "prevents a future 00.* plugin from eagerly loading a heavy barrel
+ * pre-seed": the guard lives at the package boundary, not the boot-order boundary.
+ */
+/** The minimal shape this module needs from `nuxt` — narrowed so a test can pass a plain mock object
+ *  instead of a real Nuxt instance (mirrors testing `defineNuxtModule`'s callback logic directly, not
+ *  through Nuxt's own module-loading machinery). */
+export interface MinimalNuxt {
+  options: { _layers: readonly { cwd: string }[] }
+  hook: {
+    (name: 'nitro:config', fn: (nitro: { plugins?: (string | undefined)[] }) => void): void
+    (name: 'nitro:init', fn: (nitro: { options: { plugins: (string | undefined)[] } }) => void): void
+  }
+}
+
+/** The module's actual logic, exported separately from `defineNuxtModule`'s wrapper so a test can call it
+ *  against a plain mock `nuxt`/`nitro` pair and assert `nitro.plugins` ends up EXACTLY
+ *  `resolvePluginOrder(roots)`, in order — the "declared order ≡ effective order" proof, at unit speed,
+ *  independent of the real-boot proof (a real `nuxt build`, inspected directly). */
+export function setupPluginOrder(nuxt: MinimalNuxt): void {
+  const roots = nuxt.options._layers.map((layer) => layer.cwd)
+  validatePluginOrder(roots) // throws — fails the build loudly on any drift, before Nitro ever scans
+
+  nuxt.hook('nitro:config', (nitro) => {
+    nitro.plugins ||= []
+    nitro.plugins.push(...resolvePluginOrder(roots))
+  })
+
+  nuxt.hook('nitro:init', (nitro) => {
+    assertEffectiveOrderMatches(nitro.options.plugins, resolvePluginOrder(roots))
+  })
+}
+
+export default defineNuxtModule({
+  meta: { name: 'kestrel-plugin-order' },
+  setup(_options, nuxt) {
+    setupPluginOrder(nuxt)
+  },
+})

package/layers/core/modules/plugin-order/plugin-order.ts

@@ -0,0 +1,273 @@
+import { existsSync, readdirSync } from 'node:fs'
+import { join, sep } from 'node:path'
+
+const PLUGIN_EXTENSIONS = ['js', 'mjs', 'cjs', 'ts', 'mts', 'cts', 'tsx', 'jsx']
+
+/** One of Kestrel's own `server/plugins/**` files, in the position it must execute at. */
+export interface PluginEntry {
+  /** The layer directory name (`layers/<layer>`). */
+  layer: string
+  /** Path relative to the layer root. */
+  file: string
+  /** Keys (`${layer}/${file}`) of OTHER entries that MUST appear at a lower index than this one — empty
+   *  when nothing's correctness depends on this entry's position. Machine-checked by `validatePluginOrder`
+   *  against `PLUGIN_ORDER`'s actual array positions, not merely asserted. */
+  after: string[]
+  /** One line: the real dependency this entry's `after` encodes (when non-empty), or the evidence it's
+   *  safe to reorder (when empty) — always named, never assumed. */
+  evidence: string
+}
+
+/** `${layer}/${file}` — the identity `after` references and `validatePluginOrder` indexes by. */
+const key = (p: Pick<PluginEntry, 'layer' | 'file'>): string => `${p.layer}/${p.file}`
+
+/**
+ * The declared execution order for every plugin Kestrel itself ships — DATA, read and pushed by
+ * `layers/core/modules/plugin-order/index.ts`, replacing Nitro's own layer-then-filename sort for these
+ * files. `validatePluginOrder` (below) makes TWO kinds of drift a loud build failure instead of a silent
+ * Nitro auto-append or an unenforced comment: (1) a plugin file on disk that isn't declared here (or a
+ * declared entry with no file behind it), and (2) an `after` dependency whose real position in this array
+ * doesn't actually satisfy it — a reshuffle that moves a dependent entry ahead of what it depends on fails
+ * the SAME way a missing/phantom file does, not silently.
+ *
+ * Audited against a real boot in both contexts (in-repo `nuxt build` and the playground's
+ * `extends: ['..', ...]` composition) via a throwaway probe module reading the resolved
+ * `nitro.options.plugins`. Confirmed identical for Kestrel's own 6 layers in both contexts:
+ * core → fields → media → auth → collections → public,
+ * filename-sort within each layer — which is exactly what this list encodes explicitly.
+ */
+export const PLUGIN_ORDER: PluginEntry[] = [
+  {
+    layer: 'core', file: 'server/plugins/00.config.ts', after: [],
+    evidence: 'Nothing depends on core/00.config.ts to come after anything else; everything downstream depends on IT (see the after: entries below).',
+  },
+  {
+    layer: 'core', file: 'server/plugins/00.migrate.ts', after: ['core/server/plugins/00.config.ts'],
+    evidence: 'Calls useDb(), which reads the config provider 00.config.ts seeds.',
+  },
+  {
+    layer: 'core', file: 'server/plugins/01.register-introspection-pipeline.ts', after: [],
+    evidence: 'registerPipeline into a Map; read lazily on first request, never at another plugin\'s init.',
+  },
+  {
+    layer: 'core', file: 'server/plugins/01.register-openapi-pipeline.ts', after: [],
+    evidence: 'registerPipeline into a Map; read lazily on first request, never at another plugin\'s init.',
+  },
+  {
+    layer: 'core', file: 'server/plugins/01.register-tooling-pipelines.ts', after: [],
+    evidence: 'registerPipeline into a Map; read lazily on first request, never at another plugin\'s init.',
+  },
+  {
+    layer: 'core', file: 'server/plugins/02.schema-sync.ts', after: ['core/server/plugins/00.migrate.ts'],
+    evidence: 'Dev-only additive auto-migration; its own header comment: "Runs after 00.migrate, so built-in collections are already migrated and this is a no-op on them".',
+  },
+  {
+    layer: 'core', file: 'server/plugins/04.outbox-worker.ts', after: [],
+    evidence: 'Starts its own setInterval poll loop against useDb(); no other plugin\'s behavior depends on when this one starts polling (the poll itself is unconditional, no readiness handshake with another plugin).',
+  },
+  {
+    layer: 'core', file: 'server/plugins/05.reindex-refs.ts', after: [],
+    evidence: 'registerReindexRefs() registers a handler on the outbox event bus; dispatched later by the outbox worker, never read at another plugin\'s init.',
+  },
+  {
+    layer: 'fields', file: 'server/plugins/01.register-blocks-pipeline.ts', after: [],
+    evidence: 'registerPipeline into a Map; read lazily on first request.',
+  },
+  {
+    layer: 'fields', file: 'server/plugins/01.register-field-populate.ts', after: [],
+    evidence: 'Registers the single global row populator; field populators (media/link/richtext/relation) are looked up at READ time, so this plugin\'s order vs. the layer plugins that register them does not matter (stated in the plugin\'s own header comment).',
+  },
+  {
+    layer: 'media', file: 'server/plugins/01.register-media-pipelines.ts', after: [],
+    evidence: 'registerPipeline into a Map; read lazily on first request.',
+  },
+  {
+    layer: 'media', file: 'server/plugins/02.register-media.ts', after: [],
+    evidence: 'registerFieldPopulator; looked up at read time, not at another plugin\'s init.',
+  },
+  {
+    layer: 'media', file: 'server/plugins/04.variant-capture.ts', after: [],
+    evidence: 'Hooks the render request context (isRendererContext) and stashes discovered variants during SSR; reconciled per-render, no dependency on another plugin having run first.',
+  },
+  {
+    layer: 'media', file: 'server/plugins/05.media-cleanup.ts', after: [],
+    evidence: 'registerMediaCleanup() registers a handler on the outbox event bus; dispatched later.',
+  },
+  {
+    layer: 'auth', file: 'server/plugins/01.register-auth-pipelines.ts', after: [],
+    evidence: 'registerPipeline into a Map; read lazily on first request.',
+  },
+  {
+    layer: 'collections', file: 'server/plugins/01.register.ts', after: [],
+    evidence: 'Reads the #kestrel/collections and #kestrel/blocks VIRTUALS directly (never allCollections()); writes the runtime registry, but no plugin in this list reads that registry at its own init — only at request time, well after every plugin has finished (documented invariant, docs/internals/architecture.md § Server plugins).',
+  },
+  {
+    layer: 'collections', file: 'server/plugins/02.register-relation-populate.ts', after: [],
+    evidence: 'registerFieldPopulator; looked up at read time.',
+  },
+  {
+    layer: 'public', file: 'server/plugins/00.ensure-snapshot-triggers.ts',
+    after: ['core/server/plugins/00.migrate.ts', 'core/server/plugins/02.schema-sync.ts'],
+    evidence: 'THE one real cross-layer dependency: needs the snapshot store\'s table to already exist, created by core\'s 00.migrate (in-repo) or 02.schema-sync (consumer). Self-tolerant even so — a boot before either has run logs a warning and returns rather than crashing (ensureSnapshotTriggers\'s own TSDoc); still placed after both so the warning path is never hit in practice.',
+  },
+  {
+    layer: 'public', file: 'server/plugins/01.register-public-pipelines.ts', after: [],
+    evidence: 'registerPipeline into a Map; read lazily on first request.',
+  },
+  {
+    layer: 'public', file: 'server/plugins/02.register-links.ts', after: [],
+    evidence: 'registerFieldPopulator; looked up at read time.',
+  },
+  {
+    layer: 'public', file: 'server/plugins/03.redirects.ts', after: [],
+    evidence: 'registerAfterStep registers a DEFERRED, when-scoped pipeline hook; invoked on a future write, not at another plugin\'s init.',
+  },
+  {
+    layer: 'public', file: 'server/plugins/05.plan-publish.ts', after: [],
+    evidence: 'Registers planPublish on the outbox bus; dispatched later by the outbox worker, after commit — never at plugin init.',
+  },
+  {
+    layer: 'public', file: 'server/plugins/zz.publish.ts', after: [],
+    evidence: 'Registers a deferred CRITICAL after-step and starts the boot publish; the boot publish\'s own registry read sits after an `await` inside publishFull, so it resumes only once the synchronous plugin loop (including collections\' 01.register) has already finished — order-free by construction (documented invariant, docs/internals/architecture.md § Server plugins).',
+  },
+]
+
+/** POSIX-normalize a path for comparison — `path.join`'s OUTPUT is OS-native (backslash on Windows), but
+ *  `PluginEntry.file` is authored with literal forward slashes (`'server/plugins/00.config.ts'`) and Nuxt's
+ *  own `_layers[].cwd` values are not guaranteed to be OS-native either (bundlers commonly normalize to
+ *  POSIX internally regardless of platform). Comparing through one canonical POSIX form — rather than two
+ *  parallel branches guessing which separator a given string happens to use — removes the asymmetry a
+ *  Windows build would otherwise hit. */
+const toPosix = (p: string): string => p.split(sep).join('/')
+
+/** Find layer `name`'s root among Nuxt's resolved `_layers` cwds. Nitro plugin paths must be absolute
+ *  filesystem paths — there is no bare-specifier equivalent for a Nitro plugin the way there is for a
+ *  package export — so this lookup (mirroring the pattern auto-discovery used for the pre-package fields
+ *  seed) is still needed. */
+function layerRoot(roots: string[], name: string): string {
+  const root = roots.find((r) => toPosix(r).endsWith(`/layers/${name}`))
+  if (!root) throw new Error(`[kestrel] plugin-order: could not locate the "${name}" layer root`)
+  return root
+}
+
+/** `PLUGIN_ORDER` (or an injected `list`, for testing drift scenarios without editing the real constant),
+ *  resolved to absolute file paths in declared order — what gets pushed into `nitro.options.plugins`. */
+export function resolvePluginOrder(roots: string[], list: PluginEntry[] = PLUGIN_ORDER): string[] {
+  return list.map((p) => join(layerRoot(roots, p.layer), p.file))
+}
+
+/** Nitro's OWN plugin file extension set (`nitropack`'s `GLOB_SCAN_PATTERN` for `plugins/`) — matched
+ *  exactly, not approximated, so this scan can never be fooled by a file Nitro would pick up that this
+ *  didn't look for. */
+const PLUGIN_FILE_RE = new RegExp(`\\.(${PLUGIN_EXTENSIONS.join('|')})$`)
+const isPluginFile = (name: string) => PLUGIN_FILE_RE.test(name) && !name.endsWith('.test.ts') && !/\.test\.(js|mjs|cjs|mts|cts|tsx|jsx)$/.test(name)
+
+/** Every file under `dir` Nitro's own scan would find — RECURSIVELY (Nitro's glob is `plugins/**\/*.{ext}`,
+ *  not a flat listing), matching Nitro's exact extension set. Mirrors Nitro's own convention for real, not
+ *  approximately. */
+function walkPluginFiles(dir: string, out: string[] = []): string[] {
+  if (!existsSync(dir)) return out
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name)
+    if (entry.isDirectory()) walkPluginFiles(full, out)
+    else if (isPluginFile(entry.name)) out.push(full)
+  }
+  return out
+}
+
+/** Every plugin file Nitro would ACTUALLY scan across the layers `list` declares — derived from `list`
+ *  itself (not a separately hardcoded layer set) so an injected test `list` governs exactly the layers it
+ *  claims to, never silently falling back to a hardcoded layer set regardless of what was actually passed
+ *  in — the shape a test injecting a fully isolated fake `list`/`roots` pair depends on. */
+function scanActualPlugins(roots: string[], list: PluginEntry[]): string[] {
+  const layers = [...new Set(list.map((p) => p.layer))]
+  const found: string[] = []
+  for (const layer of layers) found.push(...walkPluginFiles(join(layerRoot(roots, layer), 'server/plugins')))
+  return found.sort()
+}
+
+/** `PLUGIN_ORDER` entries reachable from `list`, by `key`. */
+function assertOrderConstraintsSatisfied(list: PluginEntry[]): void {
+  const indexOf = new Map(list.map((p, i) => [key(p), i]))
+  const violations: string[] = []
+  for (const p of list) {
+    for (const dep of p.after) {
+      const depIndex = indexOf.get(dep)
+      const ownIndex = indexOf.get(key(p))!
+      if (depIndex === undefined) {
+        violations.push(`${key(p)} declares after: "${dep}", but no such entry exists in PLUGIN_ORDER`)
+      } else if (depIndex >= ownIndex) {
+        violations.push(`${key(p)} must come after ${dep} (${p.evidence}), but is declared at index ${ownIndex} vs. ${dep}'s index ${depIndex}`)
+      }
+    }
+  }
+  if (violations.length) {
+    throw new Error(['[kestrel] plugin-order: PLUGIN_ORDER violates a declared after: dependency.', ...violations.map((v) => `  ${v}`)].join('\n'))
+  }
+}
+
+/**
+ * LOUD failure for BOTH kinds of drift: (1) a plugin file present on disk but missing from `PLUGIN_ORDER`
+ * (which Nitro's own scan-and-append would otherwise silently tack onto the END, in undeclared position —
+ * see nitropack's `scanPlugins`/`options.plugins.push` for exactly that fallback behavior) or a declared
+ * entry whose file no longer exists; (2) a declared `after` dependency the array's ACTUAL positions don't
+ * satisfy — a reshuffle, not just a deletion, fails just as loudly. Throws — the ONLY way a Nuxt module's
+ * `setup()` can fail the build loudly (a Nitro hook can't itself abort configuration once already running).
+ * Called from `setup()`, before the `nitro:config` hook — a build-time failure, not a Nitro-time one.
+ */
+export function validatePluginOrder(roots: string[], list: PluginEntry[] = PLUGIN_ORDER): void {
+  assertOrderConstraintsSatisfied(list)
+
+  const declared = new Set(resolvePluginOrder(roots, list))
+  const actual = new Set(scanActualPlugins(roots, list))
+  const missing = [...actual].filter((f) => !declared.has(f)) // on disk, not declared
+  const phantom = [...declared].filter((f) => !actual.has(f)) // declared, not on disk
+  if (missing.length === 0 && phantom.length === 0) return
+  const lines: string[] = ['[kestrel] plugin-order: PLUGIN_ORDER has drifted from the real server/plugins/ files.']
+  if (missing.length) lines.push(`  On disk but NOT declared (would silently land last, undeclared, via Nitro's own scan-and-append): ${missing.join(', ')}`)
+  if (phantom.length) lines.push(`  Declared but the file does not exist: ${phantom.join(', ')}`)
+  lines.push('  Fix PLUGIN_ORDER in layers/core/modules/plugin-order/plugin-order.ts.')
+  throw new Error(lines.join('\n'))
+}
+
+/**
+ * The permanent, in-process observer of the REAL merge: `validatePluginOrder`/`resolvePluginOrder` only
+ * prove what THIS module pushes — they cannot see what Nitro's own scan-and-append, another module's
+ * `nitro:config` hook, or Nitro's own internal/dev-tooling plugins do to the array afterward. Called from
+ * `index.ts`'s `nitro:init` hook (which receives the fully-built Nitro instance, after every `nitro:config`
+ * hook AND Nitro's own scan have both already run) against the REAL `nitro.options.plugins`, this asserts
+ * our declared order survived that whole pipeline intact: every `expected` path appears, in order, as ONE
+ * CONTIGUOUS RUN somewhere in the real array — NOT necessarily a prefix. A real `nuxt dev` boot pushes
+ * `@nuxt/devtools`'/`@nuxt/nitro-server`'s own internal plugins (an inline devtools runtime, dev-server
+ * request logging) ahead of everything via their own earlier-registered `nitro:config` hooks — legitimate
+ * Nuxt/Nitro tooling this module neither owns nor should reject, so "prefix" is the wrong bar; "our own
+ * declared plugins never get split apart or interleaved with anyone else's" is the real, checkable
+ * invariant, and is what this asserts. Also asserts the real array has no duplicate entries anywhere
+ * (Nitro's own `!plugins.includes(x)` scan guard is SUPPOSED to prevent one, but this checks the outcome
+ * directly rather than trusting that guard blind). Throws — a boot-time, not merely a config-time, failure.
+ */
+export function assertEffectiveOrderMatches(actualPlugins: (string | undefined)[], expected: string[]): void {
+  const cleaned = actualPlugins.filter((p): p is string => typeof p === 'string')
+  const seen = new Set<string>()
+  const duplicates = new Set<string>()
+  for (const p of cleaned) {
+    if (seen.has(p)) duplicates.add(p)
+    seen.add(p)
+  }
+  if (duplicates.size) {
+    throw new Error(`[kestrel] plugin-order: nitro.options.plugins contains duplicate entries: ${[...duplicates].join(', ')}`)
+  }
+  if (expected.length === 0) return
+  let start = -1
+  for (let i = 0; i + expected.length <= cleaned.length; i++) {
+    if (expected.every((e, j) => cleaned[i + j] === e)) { start = i; break }
+  }
+  if (start === -1) {
+    throw new Error(
+      '[kestrel] plugin-order: the REAL nitro.options.plugins does not contain PLUGIN_ORDER as one unbroken, '
+      + "in-order run — something split our declared block apart or interleaved into it.\n"
+      + `  Expected (contiguous, any position): ${expected.join(', ')}\n`
+      + `  Actual full list:                    ${cleaned.join(', ')}`,
+    )
+  }
+}

package/layers/core/nuxt.config.ts

@@ -5,5 +5,6 @@ export default defineNuxtConfig({
     fileURLToPath(new URL('./modules/component-namespace/index.ts', import.meta.url)),
     fileURLToPath(new URL('./modules/auto-discovery/index.ts', import.meta.url)),
     fileURLToPath(new URL('./modules/kestrel/index.ts', import.meta.url)),
+    fileURLToPath(new URL('./modules/plugin-order/index.ts', import.meta.url)),
   ],
 })

package/layers/core/server/api/[...path].ts

@@ -0,0 +1,98 @@
+import { getRequestHeader } from 'h3'
+import {
+  MAX_JSON_BODY, assertBodyLimit, isRoutablePipeline, toHttpError, tryResolveDefaultPipeline,
+  parseFilter, parsePipelineRoute, getCollectionOr404, useDb, readIfUnmodifiedSince,
+} from '@michaelthielemann/kestrel-core'
+import type { PipelineContext, PipelineTrace } from '@michaelthielemann/kestrel-core'
+import { runPipelineForEventAuto, resolveEventPrincipal } from '@michaelthielemann/kestrel-access'
+// The one handler behind the whole pipeline URL scheme:
+//
+//   GET  /api/<collection>/<readPipeline>[/<id>]
+//   POST /api/<collection>/<writePipeline>[/<id>]
+//   POST /api/<pipeline>                            (collection-less: login, publish, createPreview)
+//
+// It is the ONLY route file under server/api: every endpoint is a pipeline, and this is where each one is
+// resolved, verb-checked and run.
+
+/** Reads take their whole input from the query string, in the shape the read steps expect. One builder for
+ *  every read pipeline — the generic list/detail reads and the editor's tooling reads pick the keys they
+ *  need out of the same object. */
+function readInput(query: Record<string, unknown>): Record<string, unknown> {
+  return {
+    ...query,
+    locale: query.locale as string | undefined,
+    sort: query.sort as string | undefined,
+    page: query.page ? Number(query.page) : undefined,
+    perPage: query.perPage ? Number(query.perPage) : undefined,
+    filter: parseFilter(query),
+    depth: query.depth ? Number(query.depth) : 0,
+  }
+}
+
+function assertMethod(method: string, read: boolean, pipeline: string): void {
+  const allowed = read ? method === 'GET' || method === 'HEAD' : method === 'POST'
+  if (!allowed) {
+    throw createError({ statusCode: 405, statusMessage: `${pipeline} is a ${read ? 'read' : 'write'} pipeline — use ${read ? 'GET' : 'POST'}` })
+  }
+}
+
+/** Embed the trace as a `$`-prefixed sidecar, matching the `$media`/`$translations` convention on rows. A
+ *  batch/array result (createMany, duplicate) or a bare value (a not-found singleton's `null`) has no
+ *  object to spread into, so it is wrapped under `data` instead. */
+function embedTrace(result: unknown, trace: PipelineTrace): unknown {
+  if (result === null || typeof result !== 'object' || Array.isArray(result)) return { data: result, $pipeline: trace }
+  return { ...(result as Record<string, unknown>), $pipeline: trace }
+}
+
+function logPipelineRun(trace: PipelineTrace): void {
+  const steps = trace.steps.map((s) => `${s.name}${s.status === 'ok' ? '' : `:${s.status}`}=${s.ms}ms`).join(' ')
+  const pipeline = trace.collection ? `${trace.collection}/${trace.pipeline}` : trace.pipeline
+  console.log(`[kestrel] pipeline ${pipeline} ${steps} total=${trace.ms}ms`)
+}
+
+export default defineEventHandler(async (event) => {
+  const route = parsePipelineRoute(event.path)
+  const collection = route.collection === null ? null : getCollectionOr404(route.collection)
+  const resolved = tryResolveDefaultPipeline(route.collection, route.pipeline)
+  if (!isRoutablePipeline(resolved)) {
+    throw createError({ statusCode: 404, statusMessage: `Unknown pipeline: ${route.pipeline}` })
+  }
+  assertMethod(getMethod(event), resolved.read, route.pipeline)
+
+  const query = getQuery(event) as Record<string, unknown>
+  // The body is buffered HERE, before the pipeline's gates run — so it must be bounded, or an anonymous /
+  // cross-site / IP-blocked caller could stream an unbounded body into memory before being refused.
+  if (!resolved.read && !resolved.rawBody) assertBodyLimit(getRequestHeader(event, 'content-length'), MAX_JSON_BODY)
+  let ctx: PipelineContext | undefined
+  let result: unknown
+  try {
+    result = await runPipelineForEventAuto(event, {
+      op: route.pipeline,
+      collection,
+      db: collection ? useDb() : null,
+      id: route.id,
+      locale: query.locale as string | undefined,
+      // A `rawBody` pipeline owns its own body read (multipart, ciphertext, a size-capped stream), so the
+      // router must not consume the stream first.
+      input: resolved.read ? readInput(query) : resolved.rawBody ? undefined : await readBody(event),
+      // Optimistic concurrency: the editor sends the baseline it loaded, and a stale save is refused with
+      // 409. Only `updateOne` has a step that reads it.
+      work: resolved.read ? {} : { expectedUpdatedAt: readIfUnmodifiedSince(event) },
+      onContext: (c) => { ctx = c },
+    })
+  } catch (error) {
+    // The ONE call site that turns a step-raised KestrelError into an HTTP response (see
+    // utils/kestrel-error-map.ts); everything else (the runner, the drivers) passes it through untouched.
+    // Gate denials (401/403) never reach here as a KestrelError — they're already createError-shaped by
+    // the time they leave the runner (see runner.ts's denied/refused) and pass through unchanged.
+    throw toHttpError(error)
+  } finally {
+    if (import.meta.dev && ctx) logPipelineRun(ctx.trace.toJSON())
+  }
+  if (route.pipeline === 'createOne' || route.pipeline === 'createMany') setResponseStatus(event, 201)
+
+  if (ctx && query.debug === 'pipeline' && resolveEventPrincipal(event).role === 'admin') {
+    return embedTrace(result, ctx.trace.toJSON())
+  }
+  return result
+})

package/layers/core/server/plugins/00.config.ts

@@ -0,0 +1,12 @@
+import { setResolvedKestrelConfig } from '@michaelthielemann/kestrel-core'
+import { resolveServerKestrelConfig } from '../utils/server-config'
+
+// Runs before every other core plugin (00.migrate.ts included — it calls useDb(), which now reads the
+// provider) and before media/auth/collections/public's own plugins (docs/internals/architecture.md § Server
+// plugins: core → media → auth → collections → public). Resolves the config ONCE with the app's own
+// runtimeConfig-preferred, file/env-fallback precedence and pushes it into the config provider — the seam
+// package code (locale.ts, revision-retention.ts, db.ts today; the future package-side movers of the
+// same files) reads from instead of touching `useRuntimeConfig()` directly.
+export default defineNitroPlugin(() => {
+  setResolvedKestrelConfig(resolveServerKestrelConfig())
+})

package/layers/core/server/plugins/00.migrate.ts

@@ -1,6 +1,7 @@
 import { resolve } from 'node:path'
 import { existsSync } from 'node:fs'
 import { migrate } from 'drizzle-orm/better-sqlite3/migrator'
+import { useDb } from '@michaelthielemann/kestrel-core'
 
 export default defineNitroPlugin(() => {
   // The committed drizzle-kit migrations only exist in Kestrel's own repo. When Kestrel is consumed as

package/layers/core/server/plugins/01.register-introspection-pipeline.ts

@@ -0,0 +1,5 @@
+import { buildIntrospectionPipelines, registerPipeline } from '@michaelthielemann/kestrel-core'
+// Registration only — nothing resolves a pipeline here; the registry is read on the first request.
+export default defineNitroPlugin(() => {
+  for (const def of buildIntrospectionPipelines()) registerPipeline(def)
+})

package/layers/core/server/plugins/01.register-openapi-pipeline.ts

@@ -0,0 +1,5 @@
+import { buildOpenApiPipelines, registerPipeline } from '@michaelthielemann/kestrel-core'
+// Registration only — nothing resolves a pipeline here; the registry is read on the first request.
+export default defineNitroPlugin(() => {
+  for (const def of buildOpenApiPipelines()) registerPipeline(def)
+})

package/layers/core/server/plugins/01.register-tooling-pipelines.ts

@@ -0,0 +1,5 @@
+import { buildToolingPipelines, registerPipeline } from '@michaelthielemann/kestrel-core'
+// Registration only — nothing resolves a pipeline here; the registry is read on the first request.
+export default defineNitroPlugin(() => {
+  for (const def of buildToolingPipelines()) registerPipeline(def)
+})