@zerotal/arch 1.14.3 → 1.15.1

package/api-surface.md

@@ -3,6 +3,9 @@
 <!-- AUTO-GENERATED by scripts/api-surface.ts. Do not edit by hand.
      Run `bun run api:surface` to regenerate after an intentional API change. -->
 
+> Not a guide — this is a flat, alphabetical snapshot used to detect unintended
+> API changes. For how to use these, read the [documentation](https://zerotal.dev/docs).
+
 ## .  `(./src/index.ts)`
 
 class ArchError = {

package/docs/about.md

@@ -236,6 +236,7 @@ decorators; the table name is derived by convention (so `@table` is optional):
 ```ts fragment
 // app/models/Post.ts
 import { Model, table, column, hasMany, belongsTo } from "@zerotal/orm";
+import type { Carbon } from "@zerotal/core/carbon";
 
 @table("posts")
 export default class Post extends Model {
@@ -243,7 +244,7 @@ export default class Post extends Model {
   @column() declare title: string;
   @column("text") declare body: string;
   @column("boolean") declare published: boolean;
-  @column("datetime") declare createdAt: Date;
+  @column("datetime") declare createdAt: Carbon;
 
   @hasMany(() => Comment) declare comments: Comment[];
   @belongsTo(() => User) declare author: User;

package/docs/changelog.md

@@ -27,6 +27,184 @@ the section for every version you cross and apply its migration notes, not only
 majors. [Releases and versioning](/docs/support-policy#releases-and-versioning) explains
 when that carve-out ends.
 
+## 1.15.1 — 2026-09-13
+
+A patch, and its headline is an ORM bug as old as the option it breaks: a model keyed on
+anything but `id` could not be updated, deleted or reloaded, and said nothing about it.
+
+Nothing here breaks. Safe to take directly.
+
+### Added
+
+- **`registerViewFileRouteResolver` is public** (`@zerotal/core`). It is what turns on
+  server-rendered file-route pages — a route file's default export rendered to HTML and
+  wrapped in the nearest `_layout`. Both halves were implemented, tested, and described in
+  [View](/docs/view) as automatic, while the call that enables them carried an internal
+  marker and could not be reached from an app. It stays opt-in, because it claims every
+  `.tsx` route file's default export; the docs now say so and document the `_layout`
+  convention beside it.
+
+### Fixed
+
+- **A model with a primary key other than `id` could not be updated, deleted or reloaded**
+  (`@zerotal/orm`). `static primaryKey = "uuid"` configured the column name everywhere the
+  key was written into SQL, while the value bound against it came from `this.id` — a
+  property such a model never has. So every statement went out as `WHERE uuid = NULL`:
+  `save()` on a loaded instance and `delete()` each matched zero rows and returned as
+  though they had written, `refresh()` and `fresh()` raised `ModelNotFoundError` for a row
+  sitting in the table, and `increment()`, `loadCount()` and the relation aggregates
+  no-opped or reported zero.
+
+  The insert was worse than silent. It wrote the row, then read it back by
+  `last_insert_rowid()`, which answers with a rowid no `TEXT` key ever equals — so the
+  instance came back with no timestamps and not marked as resident, and the next `save()`
+  on it was a second INSERT and a duplicate-key error rather than an UPDATE.
+
+  Every one of those paths now reads the key by its declared name. A write against an
+  instance whose key is genuinely absent, such as a row hydrated by `select("title")`,
+  raises `E_NO_PRIMARY_KEY` instead of binding NULL and looking like a success.
+  [The ORM guide](/docs/orm) now has a section on keying a model on something other than
+  `id`, including the part that bit: `localKey` on a relation defaults to `"id"`, so a
+  named key has to be named there too.
+
+- **A primary key the app mints was stripped from the INSERT** (`@zerotal/orm`). `id` was
+  treated as database-generated unconditionally, so a table whose key is a `TEXT id` the
+  application supplies took the value off the instance, dropped it from the statement, and
+  stored NULL — while the in-memory model went on holding the value it thought it had
+  written. The key is now omitted only when it has no value, which is what leaves
+  AUTOINCREMENT to the database.
+
+- **A `_layout` file that could not apply rendered its pages without one**
+  (`@zerotal/core`). The same fail-open the `_middleware` loader had in
+  [1.15.0](#1150--2026-09-04), one function up in the same file: an import error was
+  swallowed together with the not-found case. A `_layout.tsx` with a typo rendered every
+  page beneath it stripped of its chrome, with no error and no log. Absence stays silent;
+  a file that exists and threw now stops the boot with its path and the original error.
+
+- **A test file that booted the app with a `setup` callback left every later file without a
+  database** (`@zerotal/testing`). `createTestApp(bootstrap, setup)` opts out of sharing,
+  which was implemented as opting out of the cache — so nothing knew that app was in use,
+  its `close()` ran the full provider teardown, and `DatabaseProvider.onStopping` cleared
+  the process-global connection resolver for everyone after it. Suites that had done
+  nothing wrong failed with `No database connection. Is DatabaseProvider registered?`. It
+  read as a CI-only flake for months, because whether it bites depends on test-file order.
+
+- **`zt doctor` says when its outside-in probes did not run** (`@zerotal/core`). The
+  response-header and WebSocket-transport checks need `--url`, and they are the two that
+  see what no in-process check can. Skipping them silently meant the people who most needed
+  them had no way to learn they existed.
+
+Three more are internal, and in the notes for each package: a MySQL adapter that offers
+connection reservation may still refuse it, a dialect-coverage test left the ORM in MySQL
+mode for the rest of the process, and four test suites left their fixture trees on disk
+because a recursive `rm()` of a `"./"`-prefixed path silently deletes nothing on Windows.
+
+## 1.15.0 — 2026-09-04
+
+A working developer building a training-provider platform on 1.14.3 sent eight findings
+from doing it. All eight are here. Two of them were the same bug twice, and it was the
+worst kind: a routing convention that failed open.
+
+### Changed — BREAKING
+
+- **`createdAt`, `updatedAt` and `deletedAt` are `Carbon`, not `Date`** (`@zerotal/orm`,
+  `@zerotal/audit`).
+
+  They were declared `Date` and never held one. Every `datetime` column hydrates as
+  `Carbon`, these three included, so the declaration was wrong on any freshly loaded row —
+  and `order.createdAt.getTime()` type-checked and threw, because `Carbon` has
+  `toISOString()` and `valueOf()` but no `getTime()`.
+
+  Worse, the runtime class depended on how you reached the property: `Carbon` after a load,
+  a raw `Date` after `save()`, `touch()` or a soft `delete()` wrote one straight back onto
+  the instance. The same property on the same model, matching its declared type in neither
+  case, and with no `@column` declaration to check the truth against — which is exactly why
+  the declaration had to be the thing that is right.
+
+  ```ts fragment
+  order.createdAt.getTime(); // compiled, threw at runtime
+  order.createdAt.valueOf(); // epoch milliseconds
+  order.createdAt.toISOString(); // "2026-09-04T09:12:33.000Z"
+  order.createdAt.toDate(); // a native Date, when something needs one
+  ```
+
+  **Compile and follow the errors.** Every one is a line that would have thrown against a
+  loaded row, so the break is the fix arriving early. See the
+  [Upgrade Guide](/docs/upgrade#114-to-115).
+
+### Fixed
+
+- **A `_middleware.ts` that could not apply left its subtree serving, unguarded**
+  (`@zerotal/core`). Two ways in, both silent.
+
+  `export default [Mw]` was ignored: the loader read only the named export. It is the
+  natural guess — every route file in the same directory default-exports its handler — and
+  getting it wrong produced no warning, no boot error, and nothing in `route:list`. This was
+  found on a host-employer portal scoped to one company's learners, where shipping it
+  unguarded would have been a data breach rather than a bug report.
+
+  The second was one `catch {}` covering both "there is no middleware here" and "the
+  middleware threw on import". A typo, a bad import path, a circular import or a
+  `SyntaxError` all read as absence — and on a hot-reload, that is a guard which was there
+  a second earlier.
+
+  Absence stays silent, because that is the convention working. Everything else is loud: a
+  file that throws stops the boot with its path and the original error; a file that exports
+  nothing appliable names the mistake and the line to write instead. Nothing rejected here
+  has ever applied, so no working app changes behaviour.
+
+- **`zt doctor`'s secure-headers check false-positived behind a reverse proxy**
+  (`@zerotal/core`). It read `app.secureHeaders.secure` and inferred the response from it,
+  so an app where Caddy or nginx terminates TLS and sets HSTS — the most common production
+  topology for a Bun app — was reported as downgradeable while `curl -I` showed the header
+  present.
+
+  The cost is not the wrong answer. `doctor` is reliable enough that people run it after
+  every deploy, and one line they have to remember to ignore is a line nobody reads on the
+  day it is right. It now makes one request to `app.url` on a deployment and reports what
+  came back. When it cannot reach the site it says so, rather than reporting a header as
+  missing.
+
+- **A test that stubbed `globalThis.fetch` also answered the test client's own requests**
+  (`@zerotal/testing`). Faking a third-party integration — the ordinary way to test one —
+  made unrelated route tests fail with `connection refused`. The failure presents as "my
+  test client cannot reach my app", which sends you looking at the server. `TestApp` now
+  binds `fetch` at module load, before any test can replace it.
+
+### Added
+
+- **`bun zt route:types` generates every type file, not only the routes** (`@zerotal/core`,
+  `@zerotal/inertia`). Adding a page and rendering it failed with `TS2345: … not assignable
+to 'PageName'` — accurate and unhelpful, since it reads as a mistyped page name when the
+  registry simply had not been rebuilt. The command whose name says it generates types
+  regenerated half of them.
+
+  `registerTypeGenerator` lets a view package add its codegen without core importing it.
+  One command refreshes both, and `--check` gates on both in CI.
+
+- **`bun zt test` no longer inherits `.env`'s outbound drivers** (`@zerotal/core`). Bun
+  loads `.env` into every process, so a developer with `MAIL_DRIVER=smtp` pointed at a
+  local Postfix got a suite where every path that sends mail opened a real SMTP connection
+  — one test going from milliseconds to a five-second timeout, failing only when run with
+  its siblings, and invisible to anyone without a mail server configured.
+
+  Mail, queue, session and cache now get their in-process defaults, which is what the app's
+  own config already defaults to. A value set in the shell still wins, `.env.test` is read
+  and merged last, and `--keep-env` turns it off.
+
+### Documented
+
+- **The query builder is findable.** A team wrote whole-table loads with JavaScript
+  filtering throughout an app because they never found `whereIn`. The page documenting it
+  exists and is thorough; the README's Data table sent anyone looking for `Post.query()` to
+  the `DB.table()` page, and `api-surface.md` is a flat alphabetical snapshot where
+  `whereIn` sits among two hundred siblings. Both now point where they should, and
+  [Queries](/docs/orm/queries) warns against the shape that degrades in proportion to the
+  table rather than the result.
+
+- **`_middleware.ts` takes a named export**, and stubbing `globalThis.fetch` in a test has
+  a documented pattern next to `Http.fake()`.
+
 ## 1.14.3 — 2026-09-01
 
 Consistency pass on the documentation, and two bugs it uncovered.

package/docs/contributing.md

@@ -114,6 +114,41 @@ bun test src/db/QueryBuilder.test.ts   # a single file
 5. **Update the docs.** If you change or add public API, update the relevant page
    under `docs/` (and the nav in `apps/docs/app/routes/_layout.ts` if you add a page).
 
+### Tests restore anything process-global
+
+Bun runs a package's test files in **one process**, and the preload is evaluated
+once per worker, not once per file. So a global a test writes is still there for
+every file that runs after it: `Bun.env` keys, `globalThis.fetch` or
+`globalThis.document`, and framework module state set through the `_set*` helpers.
+
+Put it back. `beforeEach` captures, `afterEach` restores — and restore in a
+`finally` or an `afterEach`, never at the end of the test body, or a failing
+assertion skips the restore and takes the rest of the suite with it.
+
+```ts fragment
+let saved: string | undefined;
+beforeEach(() => {
+  saved = Bun.env["APP_ENV"];
+  Bun.env["APP_ENV"] = "production";
+});
+afterEach(() => {
+  if (saved === undefined) delete Bun.env["APP_ENV"];
+  else Bun.env["APP_ENV"] = saved;
+});
+```
+
+This is worth its own rule because **the damage never lands where the mistake is**.
+The file that fails is whichever ran next, and which file that is depends on
+directory order — alphabetical on Windows, arbitrary readdir order on Linux. So a
+leak passes locally for months and reddens CI on an unrelated commit. Five of
+these were found in one week, each written by someone who had tested their own
+file in isolation and seen it pass.
+
+If a CI-only failure lands in a package your change did not touch, suspect a
+leaked global before suspecting your diff. To reproduce the order locally, rename
+the file you think runs second so it sorts last — passing paths to `bun test`
+explicitly does not work, because Bun re-sorts them.
+
 ## Documentation changes
 
 The docs are markdown files in `docs/`, served by the docs app in `apps/docs`. A page's

package/docs/middleware.md

@@ -184,6 +184,19 @@ export const middleware = [AuthMiddleware, AdminMiddleware];
 Middleware stacks from outer directories are prepended automatically —
 you get `root/_middleware → admin/_middleware → route handler` in one pipeline.
 
+> **It is `export const middleware`, an array — not `export default`.** Route
+> files in the same directory default-export their handler, so a default export is
+> the natural guess here and it is the wrong one. The app refuses to boot and tells
+> you which file, rather than serving the subtree unguarded and looking exactly
+> like a guarded one. The same applies to a `_middleware.ts` that
+> fails to import: a typo or a bad import path is a boot error, not a subtree that
+> quietly loses its guard. A directory with no `_middleware` file at all is the
+> convention working, and stays silent.
+>
+> Note the asymmetry with its sibling: a `_layout` file is read by its **default**
+> export, a `_middleware` file by a **named** one. Both now refuse to boot on the
+> other's spelling rather than applying nothing.
+
 ## Global middleware
 
 Register middleware that runs on every request in `bootstrap/app.ts`:

package/docs/orm/index.md

@@ -171,6 +171,45 @@ export class LedgerEntry extends Model {
 > `forceDelete()`, `trashed()`, and the `withTrashed()` / `onlyTrashed()` scopes. See
 > [Lifecycle & Events](/docs/orm/lifecycle).
 
+#### A primary key that isn't `id`
+
+Name the key column and every read and write keys on it — `find()`, `save()`, `delete()`,
+`refresh()`, `increment()`, relation counts. Declare it like any other column and set the
+value yourself, because a `TEXT` key has no auto-increment to fall back on:
+
+```typescript fragment
+@(table("documents").primaryKey("uuid"))
+export class Document extends Model {
+  @column("string") uuid!: string;
+  @column("string") title!: string;
+
+  // `localKey` defaults to "id" on every relation, so a named key has to be named here too
+  @hasMany(() => Revision, { foreignKey: "documentUuid", localKey: "uuid" })
+  revisions!: HasMany<Revision>;
+}
+
+const doc = new Document();
+doc.uuid = crypto.randomUUID(); // nothing fills this in for you
+doc.title = "Roadmap";
+await doc.save();
+
+doc.createdAt; // the insert writes your key, then reads the row back by it
+```
+
+Three consequences worth holding onto:
+
+- **Set the key before the first `save()`.** With no value to write, the insert hands the
+  column to the database, which for a `TEXT` key means whatever its schema says — a `NOT
+NULL` violation, or a silent `NULL`.
+- **`localKey` on every relation.** It defaults to `"id"`, so a relation left at the
+  default reads a property the model does not have and quietly matches nothing.
+- **A string key wants its own name.** `Model` types the inherited `id` as a `number`, so
+  `primaryKey("uuid")` (or `"ticket_ref"`, or whatever it is) type-checks where a `TEXT`
+  column called `id` does not.
+
+Keep the key out of `fillable` unless request data really is allowed to choose it —
+[mass assignment](#mass-assignment) is what decides that, the same as any other column.
+
 ### @column decorator
 
 Declare typed columns. Accepts a shorthand cast string or a full options object:

package/docs/orm/queries.md

@@ -159,6 +159,14 @@ const user = await User.findOrNew(1);
 `Model.query()` returns a `ModelQueryBuilder`. Most methods are also available on
 `DB.table()` for unmodelled raw queries — see [Query builder](/docs/query-builder).
 
+> **Filter in SQL, not in JavaScript.** If you find yourself writing
+> `(await Placement.all()).filter((p) => p.employerId === id)`, the builder has
+> what you want — `.where("employerId", id)`. That shape works fine on a table
+> with hundreds of rows and gets slower in proportion to the table, not to the
+> result, so it fails long after it was written and nowhere near the code that
+> caused it. The next four sections are the whole filtering surface; skimming
+> them once is the cheapest thing on this page.
+
 ### Filtering
 
 ```typescript fragment

package/docs/support-policy.md

@@ -75,14 +75,16 @@ dependency order, from CI. Never mix versions across packages.
   tilde if you would rather cross a minor deliberately.
 - **A break is never silent.** Every one is called out in the release notes as
   **BREAKING**, with the reason and the migration steps, and the version gets its
-  own section in the Upgrade Guide. Eight have shipped so far — the
+  own section in the Upgrade Guide. Nine have shipped so far — the
   `ComponentWith` / `BaseModelWith` removal in 1.3.0, Flow's `socket:` listener
   prefix in 1.7.2, the removal of Flow's `this.title(…)` in 1.7.3, SQLite
   foreign-key enforcement in 1.11.0, `countTokens` returning `number | null` in
   1.11.2, the refusal to write a boolean into a text column in 1.12.0, and the removal of
   Flow's `Component.client(…)` alongside two retired aliases in 1.13.0, and
-  `inertia.ssr` no longer registering `POST /__ssr` in 1.14.0.
-- **One of those five is in the wrong place, and it stays on the record.** 1.11.2
+  `inertia.ssr` no longer registering `POST /__ssr` in 1.14.0, and the model
+  timestamps `createdAt` / `updatedAt` / `deletedAt` being typed `Carbon` rather
+  than `Date` in 1.15.0.
+- **One of those nine is in the wrong place, and it stays on the record.** 1.11.2
   is a patch, and by the rule above a patch cannot carry a break. It did: the
   `countTokens` signature changed in the same release that promoted `@zerotal/ai`
   to `stable`, and the reasoning that allowed it — the package was still

package/docs/testing/index.md

@@ -251,14 +251,45 @@ your users find first.
 
 ## `bun test` vs `bun zt test`
 
-Both run the same files. `bun zt test` is a wrapper that sets up three things Bun's
+Both run the same files. `bun zt test` is a wrapper that sets up four things Bun's
 runner does not, and each of them has cost somebody a day:
 
-|                  | `bun test`            | `bun zt test`                                              |
-| ---------------- | --------------------- | ---------------------------------------------------------- |
-| Per-test timeout | Bun's default, 5000ms | 30000ms (`--timeout`, override with `--timeout=`)          |
-| Runtime check    | none                  | refuses a Bun below the project's `engines.bun`            |
-| DB wiring        | none                  | preloads `@zerotal/testing/preload` and passes `ZT_DB_URL` |
+|                  | `bun test`            | `bun zt test`                                                      |
+| ---------------- | --------------------- | ------------------------------------------------------------------ |
+| Per-test timeout | Bun's default, 5000ms | 30000ms (`--timeout`, override with `--timeout=`)                  |
+| Runtime check    | none                  | refuses a Bun below the project's `engines.bun`                    |
+| DB wiring        | none                  | preloads `@zerotal/testing/preload` and passes `ZT_DB_URL`         |
+| Drivers          | inherits `.env`       | resets mail, queue, session and cache to their in-process defaults |
+
+### The drivers
+
+Bun loads `.env` into every process it starts, so a test run inherits your local
+setup — including the keys that decide whether a code path talks to something
+real. A developer with `MAIL_DRIVER=smtp` pointed at a local Postfix gets a suite
+where every path that sends mail opens an SMTP connection: one test that confirms
+a payment and issues an invitation goes from milliseconds to a five-second
+timeout, and fails only when run alongside its siblings. A teammate with no mail
+server configured never sees it.
+
+So `bun zt test` resets these for the child process:
+
+| Key              | Test value |
+| ---------------- | ---------- |
+| `MAIL_DRIVER`    | `log`      |
+| `QUEUE_DRIVER`   | `sync`     |
+| `SESSION_DRIVER` | `cookie`   |
+| `CACHE_DRIVER`   | `memory`   |
+
+Each is already the app config's default; only `.env` was overriding it. Two
+things still win, and the command prints a line saying what it changed:
+
+- **A value set in the shell** — `MAIL_DRIVER=smtp bun zt test` is someone
+  testing that path deliberately, and is left alone.
+- **`.env.test`** — read by `bun zt test` and merged last, for anything a test
+  run should configure for itself. (Bun only loads that file when `NODE_ENV=test`,
+  so `bun test` on its own does not see it.)
+
+`--keep-env` skips the reset entirely and inherits `.env` as-is.
 
 ### The timeout
 

package/docs/testing/mocking.md

@@ -225,6 +225,34 @@ it("charges the card and records the reference", async () => {
 A catch-all stub at the end is worth adding: without it an unstubbed URL falls
 through, and a test can quietly start depending on a service being reachable.
 
+### Stubbing `globalThis.fetch` directly
+
+`Http.fake()` only sees requests made through the `Http` client. An integration
+written against `fetch` directly — a third-party SDK, or a client you wrote
+before reaching for `Http` — needs the global replaced:
+
+```typescript fragment
+// src/tests/MoodleTest.ts
+const originalFetch = globalThis.fetch;
+
+beforeEach(() => {
+  globalThis.fetch = (async (input, init) => {
+    const url = String(typeof input === "string" ? input : (input as Request).url);
+    if (!url.startsWith("https://learn.example.test")) return originalFetch(input, init);
+    return Response.json({ courses: [] });
+  }) as typeof fetch;
+});
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+```
+
+The passthrough is there for **everything else your code fetches**, not for the
+test client: `TestApp` holds the real `fetch` from before any test ran, so a stub
+installed here can never answer `app.get('/orders')`. Restoring in `afterEach` is
+what matters — a stub left installed makes the next file's outbound calls return
+the previous file's fixture.
+
 ## Time
 
 Behaviour that depends on the passage of time — a token that expires in seven

package/docs/upgrade.md

@@ -296,6 +296,99 @@ doing something quiet.
    If it really is a new migration, give it a name that does not collide once the
    leading digits are removed.
 
+## 1.14 to 1.15
+
+Two breaking changes. Both replace something that was quietly wrong with something that
+says so.
+
+### `createdAt`, `updatedAt` and `deletedAt` are `Carbon`, not `Date`
+
+They always hydrated as `Carbon` — every `datetime` column does — but were declared `Date`,
+so the type was wrong on any row loaded from the database. Worse, the runtime class
+depended on how you got there: a `Carbon` after a load, a raw `Date` after a `save()`, a
+`touch()` or a soft `delete()`. The same property on the same model, matching its declared
+type in neither case.
+
+```ts fragment
+// before — compiled, and threw at runtime on a loaded row
+const ms = order.createdAt.getTime();
+
+// after
+const ms = order.createdAt?.valueOf(); // epoch milliseconds
+const iso = order.createdAt?.toISOString(); // "2026-09-04T08:15:00.000Z"
+const native = order.createdAt?.toDate(); // a real Date, if something needs one
+```
+
+**What to change.** Compile and follow the errors: every one is code that would have thrown
+if that line had run against a loaded row. `Carbon` has `toISOString()`, `valueOf()`,
+`toJSON()` and `toDate()`, plus its own comparison and arithmetic — it does not have
+`getTime()`, `getFullYear()` or the rest of the `Date` accessors.
+
+If you were working around the old inconsistency, the workaround can go:
+
+```ts fragment
+// before — needed because the class varied by path
+const ms = ((value as any).toDate?.() ?? value).getTime();
+
+// after
+const ms = value.valueOf();
+```
+
+A cast that hid the mismatch (`order.createdAt as unknown as string`) now hides a different
+one — `.slice(0, 10)` on a `Carbon` still throws. Use `.toISOString().slice(0, 10)`.
+
+### A broken `_middleware.ts` stops the boot
+
+Two ways a `_middleware.ts` could fail to apply used to be silent, leaving the routes it
+was written to guard live and unguarded:
+
+- **`export default [Middleware]`** — the loader only ever read `export const middleware`.
+  `export default` is the natural guess, because every route file in the same directory
+  default-exports its handler.
+- **A file that fails to import** — a typo, a bad import path, a circular import, a
+  `SyntaxError`. All shared a `catch` with the missing-file case, so all read as "this
+  directory has no middleware".
+
+Both now fail the boot, naming the file and the fix. A directory with no `_middleware` file
+is unchanged: absence is the convention working, and stays silent.
+
+```ts fragment
+// app/routes/employer/_middleware.ts
+
+// before — silently ignored, subtree served unguarded
+export default [EmployerMiddleware];
+
+// after
+export const middleware = [EmployerMiddleware];
+```
+
+**What to change.** Boot the app once — `bun zt route:list` is enough. If nothing changes,
+you had none of this. If a `_middleware.ts` file was never applying, you will be told which
+one, and the routes under it were open until now.
+
+Under `zt dev` a reload that hits this aborts and keeps serving the previously compiled
+routes, so a guard never drops mid-session.
+
+### Also worth knowing (not breaking)
+
+- **A save or delete on a model with no primary-key value now raises an error** (1.15.1).
+  It used to bind NULL, match no row, and resolve as though it had written. The one way to
+  reach it is a partially hydrated instance — `Post.query().select("title").get()`, then
+  `save()` on a result — and in that state the write was already being thrown away. What
+  changes is that you hear about it: `E_NO_PRIMARY_KEY`, naming the model and the key.
+  Select the key column alongside whatever else you need, and the write works as intended.
+- **`bun zt route:types` regenerates the Inertia page registry too.** Adding a page and
+  getting `TS2345: … not assignable to parameter of type 'PageName'` is now fixed by the
+  command whose name says it generates types. `--check` gates on both files.
+- **`bun zt test` no longer inherits `.env`'s mail, queue, session and cache drivers.**
+  They get their in-process defaults (`log`, `sync`, `cookie`, `memory`) so a suite cannot
+  open a real SMTP or Redis connection because of how one machine is configured. A value
+  set in the shell still wins, `.env.test` is read and merged last, and `--keep-env` turns
+  it off. See [Testing](/docs/testing#bun-test-vs-bun-zt-test).
+- **`zt doctor`'s secure-headers check probes the deployed URL** instead of inferring HSTS
+  from config, so an app behind a TLS-terminating proxy is no longer reported as
+  downgradeable when the header is being sent.
+
 ## 1.13 to 1.14
 
 One breaking change, and it is small in practice.

package/docs/view.md

@@ -272,9 +272,27 @@ Router.view("/terms", TermsPage)
 
 ## File-based pages
 
-Under [file-based routing](/docs/routing), a page file's **default export**
-becomes a `GET` route automatically. The page is a function of `(http, params)`
-and may be async:
+Server-rendered file-route pages are **opt-in**. Register the resolver before
+your routes are scanned — in `bootstrap/app.ts`, or a provider's `onRegister()`:
+
+```ts
+// bootstrap/app.ts
+import { registerViewFileRouteResolver } from "@zerotal/core/view";
+
+registerViewFileRouteResolver();
+```
+
+That is what makes the two conventions below work: a page's default export is
+rendered to HTML rather than treated as a plain handler, and `_layout` files are
+discovered. Without it neither applies — the default export is registered as an
+ordinary file handler and `_layout` discovery is switched off.
+
+It is opt-in because it claims every `.tsx` route file's default export, which an
+app using file routes for plain handlers has not asked for, and because `_layout`
+discovery walks the directory tree for every scanned route.
+
+With it registered, a page file's **default export** becomes a `GET` route. The
+page is a function of `(http, params)` and may be async:
 
 ```tsx fragment
 // app/views/posts/[slug].tsx  →  GET /posts/:slug
@@ -306,6 +324,41 @@ import { definePage } from "zerotal/view";
 export default definePage((http, params) => `<h1>Hello ${params.name}</h1>`);
 ```
 
+### Directory layouts — `_layout.tsx`
+
+With the resolver registered, a `_layout.tsx` beside your pages wraps every page
+in that directory and below. The nearest one wins, so a section can override the
+root:
+
+```tsx fragment
+// app/views/_layout.tsx  →  wraps every page under app/views
+export default (http: HttpContext, { children }: { children?: unknown }) => (
+  <html>
+    <body>
+      <nav>…</nav>
+      {children}
+    </body>
+  </html>
+);
+```
+
+```
+app/views/
+  _layout.tsx          ← wraps everything below
+  index.tsx
+  admin/
+    _layout.tsx        ← wraps only the admin pages
+    users.tsx
+```
+
+It is read by its **default export** — the opposite of `_middleware.ts`, which is
+read by a named `middleware` export. Both refuse to boot on the other's spelling
+rather than silently applying nothing, so a mistake here is a startup error
+naming the file, not a page that quietly renders without its chrome.
+
+A page can opt out with `export const layout = null`, or override with
+`export { SomeLayout as layout }`.
+
 ## Embedding raw HTML
 
 When you have pre-rendered markup (e.g. from a Markdown renderer) use `safe()` or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/arch",
-  "version": "1.14.3",
+  "version": "1.15.1",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -35,11 +35,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.14.3"
+    "@zerotal/core": "1.15.1"
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "@zerotal/orm": "1.14.3"
+    "@zerotal/orm": "1.15.1"
   },
   "description": "The Zerotal agent surface — an MCP server that hands coding agents the framework's machine-readable truth: exact API signatures, live routes and schema, version-matched docs, and `zt doctor`.",
   "keywords": [