@nextsparkjs/core 0.1.0-beta.191 → 0.1.0-beta.192

package/scripts/build/registry/host/README.md

@@ -0,0 +1,296 @@
+# Generated host: route facades
+
+`facade-emitter.mjs` writes one thin `src/app` route file per route (#203). A facade imports only
+from a fixed specifier (a package subpath such as `@nextsparkjs/core/...` or a project alias such as
+`@/templates/...`), re-exports what Next.js reads at runtime, and re-declares as literals the segment
+config Next.js reads statically:
+
+```ts
+// Generated by NextSpark from @/templates/blog/[slug]/page. Do not edit: regenerated on every build.
+export { default } from "@/templates/blog/[slug]/page"
+export { generateMetadata, generateStaticParams } from "@/templates/blog/[slug]/page"
+export const revalidate = 60
+```
+
+```js
+import { emitFacade, FacadeEmitError } from './facade-emitter.mjs'
+
+const { target, content } = await emitFacade({
+  kind: 'page',                           // a row of the table below
+  target: 'blog/[slug]/page.tsx',         // relative to src/app
+  specifier: '@/templates/blog/[slug]/page',
+  file: '/abs/project/templates/blog/[slug]/page.tsx',
+  projectRoot: '/abs/project',
+  cacheComponents: false,                 // the host's next.config value (checked when given)
+})
+```
+
+Every problem is a `FacadeEmitError` carrying all diagnostics (`code`, `file`, `line`, `exportName`,
+`message`); nothing is dropped silently.
+
+## Export table (Next.js 16.3.5)
+
+Source of truth: `next-route-exports.json`. The tests fail when the installed Next.js version differs,
+when Next's `AppSegmentConfigSchemaKeys` or `HTTP_METHODS` change, and when this rendering is stale.
+
+| Kind | File | Default | Re-exported | Literal segment config | Facade directive |
+| --- | --- | --- | --- | --- | --- |
+| page | `page` | required | `generateMetadata`, `metadata`, `generateViewport`, `viewport`, `generateStaticParams` | `revalidate`, `dynamicParams`, `dynamic`, `fetchCache`, `instant`, `prefetch`, `unstable_dynamicStaleTime`, `preferredRegion`, `runtime`, `maxDuration`, `config` | - |
+| layout | `layout` | required | `generateMetadata`, `metadata`, `generateViewport`, `viewport`, `generateStaticParams` | `revalidate`, `dynamicParams`, `dynamic`, `fetchCache`, `instant`, `prefetch`, `preferredRegion`, `runtime`, `maxDuration` | - |
+| template | `template` | required | - | - | - |
+| loading | `loading` | required | - | - | - |
+| error | `error` | required | - | - | 'use client' (source must be client) |
+| global-error | `global-error` | required | - | - | 'use client' (source must be client) |
+| not-found | `not-found` | required | - | - | - |
+| global-not-found | `global-not-found` | required | `metadata`, `generateMetadata` | - | - |
+| forbidden | `forbidden` | required | - | - | - |
+| unauthorized | `unauthorized` | required | - | - | - |
+| default | `default` | required | - | - | - |
+| route | `route` | forbidden | `GET`, `HEAD`, `OPTIONS`, `POST`, `PUT`, `DELETE`, `PATCH`, `generateStaticParams` | `revalidate`, `dynamicParams`, `dynamic`, `fetchCache`, `preferredRegion`, `runtime`, `maxDuration`, `config` | - |
+| sitemap | `sitemap` | required | `generateSitemaps` | `revalidate`, `dynamic`, `fetchCache`, `preferredRegion`, `runtime`, `maxDuration` | - |
+| robots | `robots` | required | - | `revalidate`, `dynamic`, `fetchCache`, `preferredRegion`, `runtime`, `maxDuration` | - |
+| manifest | `manifest` | required | - | `revalidate`, `dynamic`, `fetchCache`, `preferredRegion`, `runtime`, `maxDuration` | - |
+| icon | `icon`, `icon0`-`icon9` | required | `generateImageMetadata`, `size`, `contentType` | `revalidate`, `dynamic`, `fetchCache`, `preferredRegion`, `runtime`, `maxDuration` | - |
+| apple-icon | `apple-icon`, `apple-icon0`-`apple-icon9` | required | `generateImageMetadata`, `size`, `contentType` | `revalidate`, `dynamic`, `fetchCache`, `preferredRegion`, `runtime`, `maxDuration` | - |
+| opengraph-image | `opengraph-image`, `opengraph-image0`-`opengraph-image9` | required | `generateImageMetadata`, `size`, `contentType`, `alt` | `revalidate`, `dynamic`, `fetchCache`, `preferredRegion`, `runtime`, `maxDuration` | - |
+| twitter-image | `twitter-image`, `twitter-image0`-`twitter-image9` | required | `generateImageMetadata`, `size`, `contentType`, `alt` | `revalidate`, `dynamic`, `fetchCache`, `preferredRegion`, `runtime`, `maxDuration` | - |
+
+Emitted forms: **default** `export { default } from '<source>'`; **re-exported** `export { name } from
+'<source>'` (never through `export *`, which Next does not see); **literal** `export const name = <literal>`
+copied from the source.
+
+Next detects `generateStaticParams`, `generateSitemaps` and `generateImageMetadata` statically through
+`specifier.orig`, so a source that exports one under an alias (`export { listSlugs as generateStaticParams }`,
+which Next does *not* detect statically) is forwarded keeping that local name, and the facade reads the same:
+
+```ts
+import { generateStaticParams as listSlugs } from "@/templates/x/[slug]/page"
+export { listSlugs as generateStaticParams }
+```
+
+Metadata image kinds accept Next's one-digit variants (`icon1`, `apple-icon9`, `opengraph-image2`,
+`twitter-image3`), mapped to the base kind.
+
+The emitter resolves `next/package.json` once (project first, then core) and accepts only `~16.3.5`: the table's
+`next` is the verified baseline, and any stable 16.3.x patch at or above it is accepted, while other minors/majors,
+lower patches and prereleases are refused (`NS_HOST_UNSUPPORTED_NEXT_VERSION`). It loads Next's segment config
+schema from that same package root.
+Every emitted facade is also validated by `static-imports.mjs` against an allowed grammar: a `'use client'`
+prologue, static imports, `export { … } from '<string>'`, `export { … }` of imported names, and
+`export const name = <literal Next reads>`. Nothing else - no expression, call, member access, function, class or
+`export *` - so no runtime selection of a module can be written in a facade at all. Generated registries use the
+`registry` grammar: static imports plus `export const X = <object/array literal>` whose leaves are literals or imported
+identifiers (no computed keys, spreads, methods, getters or calls).
+
+Segment config and `cacheComponents` (verified by probe builds with `next build --webpack` and
+`--turbopack`, Next.js 16.3.5):
+
+- invalid with `cacheComponents: true` (build error "Route segment config "X" is not compatible with
+  `nextConfig.cacheComponents`"): `dynamic`, `dynamicParams`, `fetchCache`, `revalidate`, **`runtime`**
+  (not listed in Next's docs, but even `runtime = 'nodejs'` fails);
+- require `cacheComponents: true`: `instant`, `prefetch`;
+- `unstable_dynamicStaleTime` is page-only (a layout fails the build).
+
+Literal values are accepted exactly as `next/dist/build/analysis/extract-const-value.js` reads them
+(no negative numbers, no parentheses, no identifiers) and then validated with Next's own
+`parseAppSegmentConfig`.
+
+## Diagnostics
+
+| Code | When |
+| --- | --- |
+| `NS_HOST_NON_LITERAL_SEGMENT_CONFIG` | segment config exported as anything but `export const x = <literal>` |
+| `NS_HOST_INVALID_SEGMENT_CONFIG_VALUE` | a literal Next's schema rejects |
+| `NS_HOST_CACHE_COMPONENTS_CONFLICT` | a key the host's `cacheComponents` setting makes Next reject |
+| `NS_HOST_CLIENT_SERVER_ONLY_EXPORT` | metadata family, `generateStaticParams` or segment config from a `'use client'` module; a route/metadata route source marked `'use client'` |
+| `NS_HOST_CLIENT_REQUIRED` | `error` / `global-error` source without `'use client'` |
+| `NS_HOST_ROUTE_DEFAULT_EXPORT` | a Route Handler source with a default export |
+| `NS_HOST_ROUTE_NO_METHODS` | a Route Handler source without HTTP methods |
+| `NS_HOST_MISSING_DEFAULT` | a component or metadata file source without a default export |
+| `NS_HOST_UNSUPPORTED_EXPORT` | any export the table does not list for the kind |
+| `NS_HOST_UNCLASSIFIABLE_EXPORT` | `export *`, destructuring exports, `enum`, `namespace`, `export =` |
+| `NS_HOST_SERVER_ACTIONS_MODULE` | a `'use server'` module used as a route file |
+| `NS_HOST_PARSE_ERROR` | the source does not parse |
+| `NS_HOST_UNSUPPORTED_NEXT_VERSION` | the project resolves a Next.js outside `~<table next>` (other minor/major, lower patch, prerelease), or it lacks the segment config schema |
+| `NS_HOST_VARIABLE_LOOKUP` | an emitted facade leaves the allowed facade grammar (internal guard, `static-imports.mjs`) |
+| `NS_HOST_TARGET_MISMATCH` / `NS_HOST_INVALID_SPECIFIER` / `NS_HOST_UNKNOWN_KIND` | bad emitter input |
+
+## `nextspark prepare`: the whole generated host
+
+The emitter writes one file; `prepare.mjs` generates the complete `src/app` and the registries of a project and
+publishes them safely. The CLI runs `prepare-cli.mjs` from the installed core (`prepare`, `prepare --check`,
+`build`, `dev`).
+
+| Module | Role |
+| --- | --- |
+| `core-routes.mjs` | `loadCoreRouteManifest()`: the one loader of core's route manifest, resolved through the core package's `exports` (`@nextsparkjs/core/routes/manifest.json` -> `dist/routes/manifest.json` in the npm package; in a source checkout `src/routes/manifest.json` wins, since dist is its build output); `[{ kind, target, specifier, protected? }]`. Route modules resolve the same way (`./routes/*`). `routes/variants.json` (`{ "cacheComponents": [...] }`) replaces entries by target when the host's `cacheComponents` is on (read from a literal in `next.config.*`; unknown keeps the manifest entries). No manifest: the core cannot generate the host and prepare fails saying so. Protected targets: `protected: true` or core's `PROTECTED_PATHS` (any level: a whole-file override cannot keep part of a route protected). |
+| `mode.mjs` | `resolveHostMode()`: `host` when the core ships the manifest and `src/app` is absent, holds only empty directories and placeholders (`.gitkeep`, `README.md`, OS files - never touched), or is described by a valid generation record (parses, schema version, NextSpark paths only); `legacy-app` when `src/app` holds files and there is no valid record (a committed app tree): `prepare`, `build` and `dev` fail with `LEGACY_APP_MESSAGE`, pointing to `nextspark migrate`, which detects the tree with this same decision and converts it; `no-manifest` otherwise. Read-only. |
+| `plan.mjs` | `planHost()`: core < plugin (`plugins/<name>/templates/**`, `plugins/<name>/api/**` at `api/plugins/<name>/**`) < project (`templates/**`, `api/**` at `api/**`). A higher layer replaces a lower one at the same directory + file stem (+ cache-mode suffix); two files of one layer, two plugins, anything over a protected core route, and a page with a Route Handler in one directory are diagnostics naming both sources. Sorted by code unit, so deterministic. |
+| `render.mjs` | One facade per planned route through `emitFacade` (every cache mode the host builds is checked; a problem all modes share is reported once). Facade cache for the watcher. |
+| `generation.mjs` | Ownership, validation, publication, lock and check (below). |
+| `prepare.mjs` | `prepareHost()` / `checkHost()` / `watchHost()` for any host config; `predictHost(config)` resolves to `{ ok, routes, notices, diagnostics, checks }` without writing or throwing on a diagnostic (dry runs such as `migrate --dry-run`): it runs the plan, the emission, the grammar gate, the ownership preflight of `src/app` and the contracts plan with its preflight, read-only, and says which ran in `checks` (`passed` / `failed` / `skipped` / `none`); the registry build is never run there (it writes a staging directory), so `checks.registries` is `skipped`; `projectHostConfig()` for a real project (the registry build runs into a staging directory: `NEXTSPARK_REGISTRIES_OUT`, `NEXTSPARK_GENERATED_HOST=1`, and its wall-clock timestamps are normalized so the same sources give the same bytes). |
+
+Publication (`generation.mjs`):
+
+- everything is planned, emitted, staged and validated (facade grammar for `src/app`, registry grammar where the producer
+  declares it, paths only under `src/app` and `.nextspark/registries`) before the first write; a failure leaves the previous
+  generation untouched;
+- changed files are written to a temporary file beside them and renamed; unchanged files are not touched;
+- `.nextspark/generation.json` records schema version, mode, core/cli/next versions, the hash of every input and every
+  emitted file. It is written ahead (previous + new files, `pending: true`) and then final, so an interrupted run never leaves
+  a file no record owns;
+- ownership is proven against the disk: a `src/app` file is NextSpark's only when the previous record lists it **and** its
+  bytes still have the recorded hash (for an interrupted publication, also the hash it had before). A listed file edited
+  since, or a leftover record next to a tree that replaced the generated one, is foreign: never overwritten or deleted;
+- only files of the previous record are deleted; nothing is written, replaced or deleted through a symlink (a symlink in or
+  on the way to `src/app` or the registries stops the run; safe-fs refuses it too);
+- `src/app` files that are not provably NextSpark's stop the run before it writes, naming them; an unowned file
+  byte-identical to its generated content is adopted; placeholders (`.gitkeep`, `README.md`, OS files) are ignored;
+- a file already in place of a generated registry that the previous record does not own is taken over only when a
+  NextSpark registry build wrote it (byte-identical, or stamped `Generated at: <ISO time>` / `// Generated by NextSpark` in
+  its first 30 lines, which every legacy registry carries); anything else stops the run (`NS_HOST_FOREIGN_REGISTRY`) and is
+  left untouched;
+- one writer at a time: `.nextspark/generation.lock`, only ever created with O_EXCL. A stale lock (its process gone on
+  this machine; from another machine, older than 10 minutes; unreadable for more than 30 seconds) is never deleted and
+  re-created: the one process that creates `generation.lock.takeover-<inode-mtime>` with O_EXCL re-checks the lock is
+  still that instance and renames its own claim over it atomically. A live holder on this machine is never taken over.
+
+`prepare --check` writes nothing and targets the production host (what `prepare` and `build` write): a `nextspark dev`
+generation is reported as such; `--check --dev` checks it instead. `src/app` is re-rendered in memory and compared byte for
+byte (missing / stale / foreign); a publication that did not finish (`pending`) is not fresh;
+registries are compared with their recorded hashes and inputs with their recorded hashes (the registry build is not
+side-effect free, so it is not re-run); no `src/app` and no record: "run nextspark prepare".
+
+`nextspark dev`: the first generation must succeed before Next starts; `watchHost` then regenerates on changes under
+`templates/`, `api/`, `plugins/`, `entities/`, `config/`, `blocks/`, `messages/`, `nextspark.config.ts`, core's route manifest
+and packaged plugin manifests. A failed regeneration keeps the last valid host published **and served** (routes keep answering 200), prints the
+diagnostic, and shows it in the browser without pretending the change was applied. What stays is `src/app`: the route
+files, the names they forward and the segment config copied as literals. Edits inside modules the existing facades import
+still reach Next directly (a facade re-exports the module, it does not copy it), so the message says exactly that:
+
+- a dev generation adds three fixed files under `src/app/_nextspark/` (a private folder, never routes):
+  `generation-diagnostic.ts` (`export const generationDiagnostic = ""`), `generation-status-reporter.tsx` (a `'use client'`
+  component that, while the diagnostic is non-empty, shows it in a fixed dev panel and calls `console.error` once, which Next's
+  dev indicator lists as an issue; the panel is what stays reliable, since Next clears its issue list on every Fast Refresh
+  rebuild) and `generation-status.tsx`
+  (`withGenerationStatus(Layout)`, the root layout with the reporter rendered before its children);
+- the dev root layout facade is `export default withGenerationStatus(<the layout>)` (`dev-facade` grammar; `<the layout>` is the
+  root layout's default import, or its composition with a project layout, see below);
+- on failure the watcher rewrites only `generation-diagnostic.ts`; Next's HMR re-renders and the reporter shows the
+  diagnostic. The next successful regeneration empties it and the panel goes away, with no reload.
+  **Not while a source does not parse** (`NS_HOST_PARSE_ERROR`, an entity config that does not parse, or any TypeScript or
+  JavaScript source changed in this or an earlier batch that still does not parse; `nextspark.config.*`, `next.config.*`, tests and
+  specs aside: the app does not import them, so the panel is where their errors show): Next already shows
+  that error, and rewriting a module of the graph while one of them does not parse makes Turbopack drop the fix that
+  follows (it kept serving the code from before the error). Nothing is written until the sources parse again.
+  The regression guard is the unit test with its negative control (`host-robustness.test.mjs`); `scripts/performance/dev-recovery-e2e.mjs`
+  checks recovery and the panel over HTTP (`--project <dir>` on an installed project is where the Turbopack failure reproduced; the
+  fixture target does not reproduce it).
+
+A production preparation never emits these files or the composition: zero bytes and zero code in production builds.
+
+## Composition, per-entity routes, API namespaces (stage 4)
+
+A facade forwards one module. Five things are not that, and the host writes them as **composed facades**
+(`composed-facade` grammar, `static-imports.mjs`): the facade grammar plus a fixed `.css` import and at most one
+`export default wrapper(...)` / any number of `export const NAME = wrapper(...)`, where the callee is one of an explicit
+allowlist of core composition wrappers (`CORE_COMPOSITION_WRAPPERS`: each imported from the exact `@nextsparkjs/core/routes/_internal/...`
+module that exports it) and each argument is an imported name or a nested allowed call. The one literal is the array of child entity
+names that is `createEntityDetailRoute`'s second argument. A runtime resolver (a template lookup by key, a registry accessor,
+a wrapper name imported from anywhere else) is never a callee, however it is spelled; there is no member access, no other call, no
+spread and no expression. A host with another core (the conformance fixture) passes its own wrappers (`compositionWrappers`).
+
+- **The root layout** always imports the project stylesheet (`import "@/styles/globals.css"`, when `styles/globals.css`
+  exists). A project `templates/layout.tsx` is composed, never a replacement:
+  `export default withRootLayout(NextSparkTemplate)`, core's providers and protections around the project's layout. The
+  project's `metadata` is forwarded (the root layout is protected at the render level, which allows it); without one, core's.
+- **Group layouts** `(auth)`, `(public)`, `superadmin`, `devtools`: a project override is composed with core's
+  `with<Group>Messages` wrapper, so it cannot drop the group's message provider; **core's protection is always the outer layer**:
+  the role-guarded groups (`superadmin`, `devtools`) are composed with `withSuperadminGuard` / `withDevtoolsGuard`, which put the
+  messages, the dashboard providers and the role guard around the project's layout (and `with...Messages` alone is not callable from a
+  facade). A core layout declares the wrapper as `compose: { wrapper, specifier }` in the core route manifest
+  (`routes-manifest.mjs`, `COMPOSED_ROUTES`); a route protected at `protected_all` is never composed. An override without
+  `metadata` keeps core's, forwarded from the wrapper's module when it exports it (the `(auth)` and `(public)` modules
+  `_internal/{auth,public}-layout` and their `.cc` variants do), else from core's layout. Those modules import no component:
+  every client component a route's server graph reaches ships to the browser even if never rendered, so forwarding from
+  core's layout would put its default navbar on every page of an override (core's default layouts live in
+  `_internal/default-{auth,public}-layout`).
+- **Role-gated areas** `/superadmin`, `/devtools`: every page, layout, template and default served under the area's URL (core's,
+  a plugin's or the project's, in any route group) is composed with `withSuperadminAccess` / `withDevtoolsAccess`
+  (`routes/_internal/area-access`), which checks the session's role on the server before the segment renders, and its
+  `generateMetadata` with `withSuperadminMetadata` / `withDevtoolsMetadata` (metadata resolves apart too); a Route Handler's
+  methods but `OPTIONS` with `withSuperadminRouteAccess` / `withDevtoolsRouteAccess` (401 / 403 JSON; `OPTIONS` is forwarded
+  unchecked, so it must not return data). An intercepting route
+  counts by the URL it intercepts (`(.)`, `(..)`, `(...)` resolved). A metadata file there (`icon`, `opengraph-image`, `sitemap`, ...)
+  cannot be guarded: it stays a plain facade and is a warning notice (`NS_HOST_AREA_FILE_UNGUARDED`). The area's own
+  layout is left out: its message wrapper checks. A layout cannot protect its pages on its own (Next renders every segment of a
+  route separately), so the check does not depend on the project's proxy. The area layout declares it as `access: { wrapper, metadata, handler, specifier }`
+  in the core route manifest (`ACCESS_ROUTES`); a Cache Components variant keeps the access of the entry it replaces.
+- **One route per entity** (`entity-routes.mjs`). For every entity of the project and of enabled plugins, the host writes
+  `dashboard/(main)/<entity>/{layout,error,loading,page,create/page,[id]/page,[id]/edit/page}` and, for builder entities with
+  `access.basePath`, the public item route (`(public)<basePath>/[...slug]`, `[slug]` at `/`) and archive route; a public
+  entity with an archive page and no basePath gets `(public)/<entity>/[[...rest]]`. Each is a facade over the entity's config and
+  one factory of its own core module (`routes/_internal/entity-*-route`, `public-*-route`): a route's module graph holds one
+  entity config and only the client components its page renders, and nothing looks an entity or a template up by a key.
+  A project template for an entity page (`templates/dashboard/(main)/<entity>/{page,create/page,[id]/page,[id]/edit/page}.tsx`; a public
+  item's `templates/(public)<basePath>/[slug]/page.tsx`) is composed into that route as its `Template` argument, and runs only after
+  core's checks (the entity is enabled and shown in the dashboard): the generated factory is never discarded. The client code these
+  routes carry does not depend on how many entities the project has: the create/edit views and the shared client modules read the
+  dashboard's own registry (hydrated from server props), never the generated client registry that imports every entity's config. Core has no `[entity]/**` or `(public)/[...slug]` route: `metadata`, `error` and `loading` of the per-entity routes come from `routes/_internal/entity-{list,detail}-metadata`, `entity-error` and `entity-loading`.
+  What decides the routes is read from the config's source as literals (`enabled`, `ui.dashboard.showInMenu`,
+  `access.basePath`, `access.allowNestedSlugs`, `access.public`, `builder.enabled`, `ui.public.hasArchivePage`; the config
+  object must be an object literal): a flag that cannot be read keeps the dashboard route (core's checks answer notFound()),
+  and one that decides a public route is a diagnostic. An entity's `slug` must equal its directory name.
+  **The template replaces** (`NS_HOST_ENTITY_ROUTES_REPLACED`, a notice, not an error): a project page or Route Handler under
+  `templates/`, in a directory other than `dashboard/(main)/<entity>/` (another route group, `templates/dashboard/(staff)/<entity>/...`),
+  that **collides** with the entity's generated dashboard routes takes their URL over, as its static segment took core's `[entity]`
+  route in 0.x. It collides when it serves a URL a generated page serves (`/dashboard/<entity>`, `/create`, `/[id]`, `/[id]/edit`,
+  whatever the dynamic segment's name) or names their dynamic segment differently (`[cohortId]` where they have `[id]`): Next refuses
+  both. A template that only adds a URL (`(staff)/<entity>/export`, `(staff)/<entity>/[id]/members`) does not collide: the generated
+  routes stay and both are served. On a collision the whole generated dashboard subtree of that entity is dropped (layout, error,
+  loading, list, create, `[id]`, `[id]/edit`, and the metadata they forward), so the entity is not served from two route groups
+  under two layouts. The entity's permission layout (`createEntityLayoutRoute`) is a security boundary and stays: it is written at the
+  top directory of every project tree serving the URL (`dashboard/(staff)/<entity>/layout.tsx`, protected, so a project layout at that
+  exact file is refused). Templates inside `dashboard/(main)/<entity>/` keep the composition above. `prepare` prints the replacement
+  as `Info:`; `planHost` returns it in `notices`.
+  An optional catch-all also serves its parent's URL (`(staff)/<entity>/[[...slug]]` collides with `/dashboard/<entity>`). An intercepting
+  route (`(.)[id]`, `@modal/(.)[id]`) is a segment of its own, never a collision: nothing is replaced, and it renders only in its
+  own layout tree, not under the generated `[id]` route's layout.
+- **Billing webhooks** (`webhooks.mjs`): `nextspark.config.ts` `billing.webhookExtensions: { stripe: './lib/...', polar: './lib/...' }`
+  replaces core's webhook route with `export const POST = createStripeWebhookRoute(stripeWebhookExtensions)`, the module
+  imported statically (it must export `stripeWebhookExtensions` / `polarWebhookExtensions`).
+
+**API namespaces** are enforced by the plan (`plan.mjs`): core owns `/api/v1/**`, the project's `api/` is served at `/api/<path>`,
+each plugin's `api/` at `/api/plugins/<plugin>/**`. Stops generation (`NS_HOST_API_NAMESPACE`): a project `api/` route in `/api/v1/**` or
+`/api/plugins/**`; a project `templates/api/v1/...` route that replaces no route core has, or `templates/api/plugins/<plugin>/...` route that
+replaces no route that plugin serves (a project may override an existing route there, never create one); a plugin route (from `api/` or
+`templates/`) outside `/api/plugins/<its-name>/**`. There are no dispatchers: `/api/v1/theme/**` and `/api/v1/plugin/**` do not exist, and the
+route-handlers registry imports no handler (API route metadata only).
+
+**Per-entity API override.** One exception to "a project never creates a route under `/api/v1`": `templates/api/v1/<entity>/<rest>` is allowed
+when `<entity>` is an entity of the project or of an enabled plugin (`planEntityRoutes(...).entities`, passed to `planHost` as `entityNames`) and
+`<rest>` mirrors a route core serves under `api/v1/[entity]` (`route.ts`, `[id]/route.ts`, `[id]/child/[childType]/route.ts`,
+`[id]/child/[childType]/[childId]/route.ts`, the same segment names): the planner checks the slot of `api/v1/[entity]/<rest>`, so it follows
+whatever core ships. The generated route is the static `/api/v1/<entity>/<rest>`, which Next resolves before `[entity]`; other URLs of the
+entity stay on the generic handler. `planHost` returns an Info notice per entity (`NS_HOST_ENTITY_API_OVERRIDDEN`, with the URLs and the
+files; `prepare` prints it): the override **replaces** the generic handler for those URLs, so authentication, permissions, rate limits and the
+entity's hooks are the project's responsibility there (business rules belong in entity hooks, which every path keeps). `prepare` prints it as `Warning:`. Core's own API namespaces (every first segment core serves under `api/v1/`: `users`, `teams`, `auth`, `billing`, `cron`, `api-keys`, `devtools`, `media`, `media-tags`, `blocks`, `patterns`, `post-categories`, `team-invitations`) are never an entity's: the override is refused there with a hint naming the collision, and an entity named like one is `NS_HOST_ENTITY_CORE_API_NAMESPACE` (checked in `planEntityRoutes`, before any route is planned). A route core serves, replaced at its exact path (`templates/api/v1/users/route.ts`), is allowed as before and now also reports `NS_HOST_CORE_API_REPLACED` (`Warning:`), so no core API is replaced silently. Any other file under
+`templates/api/v1/` that replaces no core route, an unknown entity or a shape core does not serve stays `NS_HOST_API_NAMESPACE`.
+
+The plan also refuses what Next.js would fail on later, with the routes named: two pages for one URL in different route
+groups (`NS_HOST_URL_CONFLICT`) and dynamic segments it cannot tell apart at one level (`[slug]` and `[entity]`, `[...a]`
+and `[[...a]]`: `NS_HOST_DYNAMIC_SEGMENT_CONFLICT`).
+
+**Cache Components** variants (`routes/variants.json`, used when the project's next.config says `cacheComponents: true`, like the PPR
+root layout) are of three kinds: the `page.cc.tsx` files of the routes whose segment config Next.js rejects with it (login, signup and both
+docs pages: `dynamic`, `dynamicParams`); the `layout.cc.tsx` files of the five layouts that load messages (`(auth)`, `(public)`, `devtools`,
+`superadmin`, `dashboard`), because `await getMessages()` reads the request and Next.js refuses that outside Suspense while prerendering
+(`_internal/group-layouts.cc`: `(auth)`, `(public)` and `devtools` provide the build-time `STATIC_MESSAGES` of the default locale and put
+their pages behind Suspense; `dashboard` and `superadmin` load request messages inside a Suspense boundary and declare their area
+request-time; an override composes through `_internal/{auth,public,superadmin,devtools}-layout.cc`, one module per group, so the
+guards, dashboard providers and sidebars of the protected groups never reach a public or auth route); and the root layout (`layout.ppr`, whose `main` puts the page behind Suspense as the net for a page that reads `params`,
+cookies or headers below no other boundary). The public item routes omit `revalidate` in that mode; a host that builds in Cache Components
+mode only imports `_internal/public-item-route.cc`, whose reads of the published item and of the patterns it references are `'use cache'`
+functions (`cacheLife` of an hour for an item, tags `entity:<slug>` and `public-item:<slug>:<item slug>`).
+
+Tests: `node --test packages/core/scripts/build/registry/host/__tests__/*.test.mjs`.

package/scripts/build/registry/host/__tests__/diag-write-child.mjs

@@ -0,0 +1,6 @@
+// Child of the writeOwnedFile crash test: rewrites the dev diagnostic module, to be SIGKILLed
+// after the file is replaced and before the record is finalized.
+import { writeOwnedFile } from '../generation.mjs'
+import { DEV_DIAGNOSTIC_FILE } from '../render.mjs'
+
+writeOwnedFile(process.argv[2], DEV_DIAGNOSTIC_FILE, process.argv[3])