@zerotal/arch 1.14.2 → 1.15.0

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

@@ -84,7 +84,7 @@ bun create zerotal my-app     # choose: API, Flow, React, Vue, or Minimal
 cd my-app
 cp .env.example .env         # APP_KEY is pre-generated for you
 bun zt migrate              # create the database schema (API template)
-bun run dev                  # dev server + hot reload at http://localhost:3000
+bun zt dev                  # dev server + hot reload at http://localhost:3000
 ```
 
 The scaffolder writes a fresh `APP_KEY` into `.env.example` and installs
@@ -95,7 +95,7 @@ dependencies. Pick a template at the prompt:
 - **React** / **Vue** — Inertia SPA (see [Inertia](#inertia-react-vue-spa)).
 - **Minimal** — one page with JSX views on the bare framework.
 
-There's **no build step**: `bun run dev` starts the server, `bun test` runs the suite,
+There's **no build step**: `bun zt dev` starts the server, `bun test` runs the suite,
 `bun run typecheck` type-checks. More in [Getting Started](/docs/getting-started).
 
 ## The shape of an app
@@ -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;
@@ -631,7 +632,7 @@ bun zt migrate:rollback              # roll back last batch
 bun zt migrate:fresh                 # drop all + re-migrate
 bun zt key:generate                  # fresh APP_KEY
 bun zt queue:work                    # start the queue worker
-bun zt serve --dev                   # dev server (aliased by `bun run dev`)
+bun zt dev                           # dev server, hot reload (also `bun run dev`)
 bun zt list                          # every available command
 ```
 
@@ -658,7 +659,7 @@ The [README](../README.md) has a package-by-package table with links.
 
 - **The `zt` CLI is your control panel.** `bun zt list` shows everything —
   scaffolding, migrations, the dev server, the worker, and tests all run through it.
-- **No build, ever.** `bun run dev` / `bun test` / `bun run typecheck`. No compile
+- **No build, ever.** `bun zt dev` / `bun test` / `bun run typecheck`. No compile
   step to remember.
 - **Starters are the fastest way in.** `bun create zerotal my-app` scaffolds a working
   app from one of six starters — `api`, `admin`, `flow`, `react`, `vue`, or `minimal`.

package/docs/assets.md

@@ -12,20 +12,20 @@ View, Inertia) has its own pipeline and hot-reload behaviour; all three use
 
 Asset compilation is built into the framework — there's no package to install or
 provider to register for the pipeline itself. You only add Tailwind and wire up a
-static route, then `bun zt serve --dev` handles build-and-reload for you.
+static route, then `bun zt dev` handles build-and-reload for you.
 
 > **Note** — Projects ship a `zt.ts` entry and a `zt` package script,
-> so commands are written `bun zt <command>` (e.g. `bun zt serve --dev`).
+> so commands are written `bun zt <command>` (e.g. `bun zt dev`).
 
 ## Getting Started
 
 Asset building is part of `@zerotal/core` — nothing to install and no provider
-to register. `bun zt serve --dev` builds on change, and `bun zt css:build`
+to register. `bun zt dev` builds on change, and `bun zt css:build`
 produces a production bundle:
 
 ```bash
 # in your project root
-bun zt serve --dev     # watch and rebuild
+bun zt dev     # watch and rebuild
 bun zt css:build       # one production build
 ```
 
@@ -39,7 +39,7 @@ Pick by stack — the dev server runs the right pipeline automatically:
   production. Dev rebuilds are wired up by `FlowProvider`.
 - **Inertia** (React or Vue SPA, JS + CSS bundle): `bun zt inertia:build` for
   production. Dev rebuilds are wired up by `InertiaProvider`.
-- **Any stack, development**: `bun zt serve --dev` — initial build, file watch,
+- **Any stack, development**: `bun zt dev` — initial build, file watch,
   rebuild on save, and a browser reload over WebSocket.
 
 ## Tailwind CSS
@@ -113,7 +113,7 @@ returned HTML:
 
 ```bash
 # in your project root
-bun zt serve --dev
+bun zt dev
 ```
 
 When `resources/css/app.css` exists, `FlowProvider.onBooted()` registers a
@@ -296,7 +296,7 @@ Inertia Vue plugin so `.vue` single-file components compile.
 
 ```bash
 # in your project root
-bun zt serve --dev
+bun zt dev
 ```
 
 `InertiaProvider.onBooted()` registers Inertia's build routine under its own
@@ -409,14 +409,14 @@ stylesheet stays small and the fonts load in parallel. The other accepted values
 
 ## Hot reload
 
-Both pipelines above are driven by the same dev process. `bun zt serve --dev`
+Both pipelines above are driven by the same dev process. `bun zt dev`
 builds once, spawns the server as a child process, and watches the filesystem;
 what happens on a change depends on which directory the change landed in:
 
 ```text
-# bun zt serve --dev process model
+# bun zt dev process model
 ┌──────────────────────────────────────────────────────┐
-│  bun zt serve --dev                                 │
+│  bun zt dev                                 │
 │                                                      │
 │  Process 1: DevOrchestrator                          │
 │  ├─ Initial build (CSS or JS+CSS)                    │
@@ -699,7 +699,7 @@ test("a stale bundle is told to reload", async () => {
 | Command                             | Effect                                          |
 | ----------------------------------- | ----------------------------------------------- |
 | `bun zt serve`                      | Serve the app; assets are built once at boot    |
-| `bun zt serve --dev`                | Dev server with hot reload                      |
+| `bun zt dev`                        | Dev server with hot reload                      |
 | `bun zt css:build`                  | Production CSS build (Flow/View)                |
 | `bun zt inertia:build`              | Development JS+CSS build (Inertia)              |
 | `bun zt inertia:build --production` | Production JS+CSS build (Inertia)               |

package/docs/changelog.md

@@ -27,6 +27,148 @@ 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.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.
+
+Everything is written `bun zt <command>` now. The scaffold still adds a `dev` script, so
+`bun run dev` keeps working — the docs simply lead with the form that is the same in every
+project, including one that never ran the scaffolder.
+
+### Fixed
+
+- **Twenty pages taught a retired command.** `serve --dev` was retired in
+  [1.13.0](#1130--2026-08-31), and that release updated the runner, the codemod,
+  `docs/commands.md` and `docs/upgrade.md` — leaving the form in the getting-started guide,
+  the assets guide, two Flow pages, the logger page, and both READMEs. For three weeks the
+  front door told newcomers to run a command that exits 1.
+
+  A gate now scans every page against the upgrade codemods' own list of retired forms, so
+  what the docs teach cannot drift from what the framework accepts. Only _shipped_
+  retirements count: a codemod for 2.0 describes a rename that has not happened, and
+  flagging correct prose is how a gate becomes something people add exclusions to rather
+  than read.
+
+- **`zt upgrade` never offered the 1.13.0 migrations.** The `deprecated-aliases` codemod
+  bundled `serve --dev` and `routes:types` — retired in 1.13.0 — with the `BaseModel`
+  rename, which has not shipped and is scheduled for 2.0. A codemod carries one version, so
+  it took the later one: `zt upgrade --to 1.13.0` selected **nothing**, and the migration
+  for the release that broke `serve --dev` was unreachable by every app crossing it.
+
+  Split into `deprecated-aliases` at 1.13.0 and `base-model-rename` at 2.0.0. An app moving
+  to any 1.13+ release gets the command rewrites; one crossing to 2.0 no longer has
+  `BaseModel` renamed as a side effect of a command alias.
+
+  Found by the new gate, which flagged `extends BaseModel` in the ORM docs — correct prose,
+  and the reason it was reported was that the codemod claimed a rename that had not
+  happened.
+
 ## 1.14.2 — 2026-09-01
 
 **`bun run dev` was broken in every app scaffolded since 1.13.0.** Take this one.

package/docs/commands.md

@@ -181,7 +181,7 @@ that cannot cost you anything.
 Nothing prompts when there is no terminal to answer, which covers CI, containers,
 and anything reading `serve`'s output from a pipe. There it fails with the same
 explanation, so use `--force` or `--auto-port` to say up front which way you want
-it decided. Both flags work with a plain `serve` and with `serve --dev`.
+it decided. Both flags work with `serve` and with `dev`.
 
 The dev server is a special case worth knowing about: on every restart it waits a
 few seconds for its own previous process to let go of the socket rather than
@@ -192,8 +192,13 @@ is about to free itself anyway.
 
 `bun zt dev` starts the server, the file watcher, and every process a provider or
 your app registered — a queue worker, a type-checker, a Stripe listener — in one
-terminal, each in its own tab. It is `serve --dev` with those extra tabs and the
-keys to drive them, so anything true of one is true of the other.
+terminal, each in its own tab. It subclasses `serve`, so it is the same supervisor,
+the same port resolution and the same restart behaviour, plus the flags that only
+make sense with a deck on screen — anything true of `serve` is true of it.
+
+`serve --dev` was the old spelling and was retired in 1.13.0; it now fails with a
+message rather than starting a plain server. The scaffold's `dev` script runs this,
+so `bun run dev` and `bun zt dev` are the same thing.
 
 An app with a queue no longer needs a second terminal:
 

package/docs/flow/index.md

@@ -46,7 +46,7 @@ Registering the provider switches on the following (in lifecycle order):
 
 - `onRegister` — registers the `Router.flow()` macro and the file-route resolver so Flow pages can be declared and auto-discovered.
 - `onBooting` — builds the client runtime bundle (Alpine + the Flow bridge) and mounts the routes under `/__flow` (the WebSocket endpoint, `runtime.js`, the upload endpoint, and the session-relay endpoint).
-- `onBooted` — wires `serve --dev` rebuild hooks for `resources/css/app.css` and `resources/js/app.js` (a no-op when those entry points are absent).
+- `onBooted` — wires `zt dev` rebuild hooks for `resources/css/app.css` and `resources/js/app.js` (a no-op when those entry points are absent).
 - `onStarting` — AOT-compiles and validates every registered page's `render()` method.
 
 ### Configuration

package/docs/flow/performance.md

@@ -186,7 +186,7 @@ The cache is small (a handful of recent pages) and short-lived, same-origin only
 
 ### Fast refresh in dev
 
-When you edit a component under `serve --dev`, the server restarts (quickly) and the client **re-renders each mounted component from its held snapshot with the new code — keeping its state**, instead of a full reload that would reset everything. Because component state is a signed snapshot and your `APP_KEY` doesn't change across a restart, that snapshot still verifies against the fresh server; the browser also refetches the stylesheet, so a newly-used Tailwind class shows up too. Increment a counter, tweak its template, save — the counter keeps its value and the change appears in place.
+When you edit a component under `zt dev`, the server restarts (quickly) and the client **re-renders each mounted component from its held snapshot with the new code — keeping its state**, instead of a full reload that would reset everything. Because component state is a signed snapshot and your `APP_KEY` doesn't change across a restart, that snapshot still verifies against the fresh server; the browser also refetches the stylesheet, so a newly-used Tailwind class shows up too. Increment a counter, tweak its template, save — the counter keeps its value and the change appears in place.
 
 Two things to know:
 
@@ -199,7 +199,7 @@ Two things to know:
 
 ### Time-travel devtools
 
-Because the engine signs and delta-encodes the **full component state** on every round-trip, the client already holds an exact, verifiable history of everything each component has been. Under `serve --dev`, Flow records that stream: one frame per applied patch,
+Because the engine signs and delta-encodes the **full component state** on every round-trip, the client already holds an exact, verifiable history of everything each component has been. Under `zt dev`, Flow records that stream: one frame per applied patch,
 plus the initial mount. You can then **scrub back to any frame**.
 
 Jumping re-applies that frame's snapshot _and_ its HTML to the live component, so
@@ -225,7 +225,7 @@ use. Recording is capped to the most recent frames and runs **only** under the d
 
 ### Dev error overlay
 
-When an **unexpected** error is thrown, `serve --dev` shows a **full-screen
+When an **unexpected** error is thrown, `zt dev` shows a **full-screen
 overlay** carrying the error class, message, and stack. It covers both a server
 action and the initial `GET` render (`onMount` / `render`).
 

package/docs/getting-started.md

@@ -193,11 +193,14 @@ bun zt migrate
 
 ```bash
 # in your project root
-bun dev          # → bun zt serve --dev
+bun zt dev
 ```
 
+Every command in these docs is written `bun zt <command>`. The scaffold also adds a
+`dev` script, so `bun run dev` does the same thing — reach for whichever you prefer.
+
 Your app is now running at **http://localhost:3000** with hot reload enabled —
-`--dev` watches your files and hot-swaps routes without dropping connections. The
+`dev` watches your files and hot-swaps routes without dropping connections. The
 generated `package.json` also gives you `bun start` (production serve) and
 `bun test`.
 

package/docs/logger.md

@@ -292,7 +292,7 @@ level you can filter and in a file you can ship. Nothing writes to the terminal
 behind the logger's back, which means a `daily` channel captures the framework's
 own account of a boot, not just your application's.
 
-The one deliberate exception is the CLI itself. `serve --dev`'s banner and its
+The one deliberate exception is the CLI itself. `zt dev`'s banner and its
 `[zerotal:dev]` build/restart lines come from the supervisor process that watches
 your files, not from the application, and they are interactive terminal output
 rather than a record of anything. They stay on stdout.

package/docs/middleware.md

@@ -184,6 +184,15 @@ 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 `export default
+[AdminMiddleware]` is the natural guess 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.
+
 ## Global middleware
 
 Register middleware that runs on every request in `bootstrap/app.ts`:

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,93 @@ 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)
+
+- **`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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/arch",
-  "version": "1.14.2",
+  "version": "1.15.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -35,11 +35,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.14.2"
+    "@zerotal/core": "1.15.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "@zerotal/orm": "1.14.2"
+    "@zerotal/orm": "1.15.0"
   },
   "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": [