@zerotal/arch 1.14.3 → 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

@@ -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,112 @@ 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.

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