@zerotal/arch 1.10.0 → 1.11.0

package/docs/ai.md

@@ -333,6 +333,88 @@ the part that can be wrong. Whether the model's prose is good is not a unit test
 `ai.refuse()` makes the next call decline, which is worth exercising deliberately: a
 refusal is an HTTP 200, so that handling path is the one most likely never to have run.
 
+### An empty string is an answer
+
+`required` treats `""` as absent, which is right for a form — an empty text input
+submits `""`, and a user who typed nothing supplied nothing. It is **not** how
+structured output works. There, `""` is the conventional way to say _"this field does
+not apply"_, and it is what a prompt naturally asks for:
+
+> A month must be YYYY-MM. Use an empty string when the question names no month.
+
+So `rule.string()` accepts `""` on the AI path, and only there. Absence is still a
+failure — the field has to be present — and every other constraint still applies:
+
+```typescript fragment
+// in a service
+await Ai.object(prompt, (rule) => ({
+  month: rule.string(), //          "" is an answer; missing is not
+  category: rule.string().min(3), // "" fails min(3), because that is your rule
+  score: rule.number(), //           "" is a malformed answer, not a convention
+}));
+```
+
+That difference is worth knowing because the failure it caused was silent: an app's
+questions mostly named no month, the model returned `""` in three seconds every time,
+the answer was rejected as malformed, and the page said _"either no model is
+configured, or it was not about your money"_ — while a model was configured and had
+answered.
+
+### `AiFake` checks what you script it with
+
+Pass the same schema to the fake that production passes, and a canned object that the
+real driver would reject fails the test instead:
+
+```typescript fragment
+// in a test
+const ai = AiFake.install();
+ai.respondWithObject({ month: "" });
+
+// Validated against this schema, exactly as a driver would validate a real answer.
+await service.answer("what did I spend");
+```
+
+This matters more than it sounds. A fake that returns whatever it is handed makes a
+suite _less_ informative than no suite: eleven tests passed on a `{ month: "" }` the
+live path rejected every time, so the feature shipped green and answered nothing. The
+permissive fake is what made the schema bug invisible; they were the same defect from
+both ends.
+
+Omit the schema and nothing is checked, because there is nothing to check against.
+
+### Deciding whether to give up: `transient`
+
+Every `AiError` carries `transient` — `true` for _this call failed_, `false` for _this
+machine cannot do this_:
+
+```typescript fragment
+// in a service
+try {
+  return await Ai.object(prompt, schema);
+} catch (error) {
+  if (error instanceof AiError && !error.transient) this.disabled = true;
+  return null;
+}
+```
+
+A service calling a model per row needs that latch, or a machine with no API key pays
+the driver's timeout per row, per merchant, per page load — eight seconds times twelve
+merchants is ninety seconds of blank page.
+
+| Permanent — stop asking                     | Transient — try again                   |
+| ------------------------------------------- | --------------------------------------- |
+| `AiConfigError`, `AiDriverUnavailableError` | `AiRateLimitError`, `AiSpendLimitError` |
+| `UnknownAiDriverError`                      | `AiSchemaError`, `AiRefusedError`       |
+| `AiRequestError` with a 4xx                 | `AiRequestError` with 5xx, 408 or 429   |
+|                                             | `AiAgentLimitError`, `AiCancelledError` |
+
+**`AiSchemaError` is transient**, and that is the one worth checking your own code
+against. Sampling is not deterministic, so a model that shaped one answer badly may
+shape the next correctly — an app classified it as permanent and would have disabled
+two features on their first imperfect reply. The permissive mistake in this direction
+is unrecoverable, because every call site already treats "no answer" as normal, so a
+feature that switches itself off never says so.
+
 ## Observability
 
 Every generation emits `AiGenerated` on the framework event bus, and a decline also

package/docs/changelog.md

@@ -27,6 +27,142 @@ 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.11.0 — 2026-08-30
+
+Two production reports, from teams taking apps live on 1.9.0 — one shipping a
+household-finance app to a VPS, one migrating a webmail platform from Flow to Inertia
+and cutting it over to live traffic. Between them, nineteen findings.
+
+The character of the list is the thing worth naming. Almost none of it is a crash.
+Most of it fails silently or fails open: a release gate that always passes, a
+`cascadeOnDelete` that deletes nothing, an `.env.example` carrying the key the project
+actually runs with, a fake that agrees with whatever it is handed. Building an app
+finds loud bugs quickly because somebody is watching. Deploying one finds the quiet
+ones, months later, when nobody is.
+
+**This is the first release under the versioning scheme in
+[the upgrade guide](/docs/upgrade#versioning): a minor carries breaking changes, a
+patch never does, and majors are annual.** So a `^1.10.0` range will pull this in.
+Read the two items below before you take it.
+
+### Two things to do before upgrading
+
+- **SQLite now enforces foreign keys.** Run `bun zt db:check-foreign-keys` first. It
+  lists any row whose parent is missing — legal before, a constraint violation now —
+  and exits non-zero, so a release script can gate on it.
+- **If you have ever renamed a migration file**, `migrate` will now stop rather than
+  re-run it. That is the intended behaviour and the message says what to do; see
+  [the upgrade guide](/docs/upgrade#1-10-to-1-11).
+
+### Changed — BREAKING
+
+- **SQLite enforces foreign keys.** `database.sqlite.foreignKeys` defaults to `true`.
+  SQLite ignores foreign keys unless the connection asks it not to, and it is the only
+  supported dialect that does — so `constrained()` and `cascadeOnDelete()` in a
+  migration described behaviour the database would not perform. Deleting a parent left
+  its children, silently, and every child had to be removed by hand in the right order
+  by application code that remembered to. An app's data-erasure path swept fifteen
+  tables and missed three, two of them holding uploaded files, so an account erasure
+  left the paperwork on disk. `zt db:check-foreign-keys` and `zt doctor` both report
+  the rows that enforcement would now reject; `sqlite: { foreignKeys: false }` takes
+  the old behaviour back while you fix them.
+
+- **A renumbered migration is refused rather than re-run.** A migration is recorded
+  under its filename, so renaming one made an applied migration look pending — the
+  runner tried it again and failed on `table already exists`, a failed boot whose
+  error named a table rather than the rename. An app renumbered `001_` to `0001_` to
+  match this framework's own scaffold convention and would have made all nine of its
+  production migrations look unrun. `migrate` now recognises that shape, refuses, and
+  prints both spellings and the fix.
+
+### Fixed
+
+- **`.env.example` no longer ships the key the project runs with.** Both files got the
+  same rendered content, so every scaffolded project committed a live, working
+  `APP_KEY` — `.gitignore` covers `.env` and not `.env.example`. And
+  `cp .env.example .env` is the first line of every deployment guide, so the published
+  key went on to sign production sessions. No strength check can catch it: as a string
+  the value is perfectly strong.
+
+- **`.gitignore` covers the SQLite sidecars.** `*.sqlite` does not match
+  `db.sqlite-wal` or `db.sqlite-shm`, and WAL mode is on by default, so both exist in
+  every project and the write-ahead log holds rows not yet checkpointed. An app found
+  both in its first commit on a public host.
+
+- **A command can fail without throwing.** `CommandRunner` ran `process.exit(0)` the
+  moment `run()` returned and never read `process.exitCode` — the idiomatic way to
+  fail a CLI without an exception. A release gate printed six blockers, set the code,
+  and exited `0`. `zt deploy` gates on the same value, so its own preflight had the
+  hole too: a gate that could not fail, failing open.
+
+- **A Bun the project never asked for is a warning, not a refusal.**
+  `bun-plugin-tailwind` declares `bun` as a required peer, so `bun install` fetches a
+  second runtime and the guard refused to boot. An app took two outages on it. The
+  guard now asks whether the project _declared_ `bun`; if not, it warns and names both
+  the fix that works and the one that cannot.
+
+- **SMTP submission and TLS verification.** STARTTLS on 587 completed its handshake
+  and sent nothing — a write issued before the handshake finishes is dropped. And
+  `rejectUnauthorized` is not enforced by the runtime on either transport, so TLS was
+  encrypted and would have accepted that encryption from anyone in the path.
+
+- **Migration names no longer carry the platform that recorded them.** `Bun.Glob`
+  yields native separators, so on Windows the whole joined path went into the
+  `migrations` table. A database moved between platforms re-ran every migration.
+
+- **React SSR emits the page's `<Head>` tags**, and `ctx.session.intended()` reads the
+  URL `AuthMiddleware` stored — the two APIs used different session keys, so an app
+  that mixed them was silently sent to `/` after every sign-in.
+
+- **An empty string is an answer.** `required` treats `""` as absent, which is right
+  for a form and wrong for structured model output, where `""` is how a prompt asks a
+  model to say "this does not apply". A whole feature returned nothing because of it —
+  and shipped green, because `AiFake` never checked its canned object against the
+  schema. One half made the mistake; the other made it invisible.
+
+- **`MonitorStore` no longer overwrites its own defaults with `undefined`**, and
+  `zt inertia:build` fails when it produces no files rather than serving a page with
+  no script.
+
+### Added
+
+- **`zt db:check-foreign-keys`** — the rows enforcement would reject, by table and
+  rowid, exiting non-zero.
+- **`Migration.id`** — a declared identity, so renaming a migration file is free.
+- **`@zerotal/inertia/testing`'s `renderPage()`**, and a page-render test in the React
+  scaffold. An app shipped a blank page with 614 passing tests: every one asserted a
+  value or a status code, so a page could throw on its first paint and the suite
+  stayed green.
+- **`AiError.transient`** — `true` for _this call failed_, `false` for _this machine
+  cannot do this_, so a service can latch itself off without classifying eleven error
+  classes by hand.
+- **`assertRedirectContains()`**, and **`assertRedirect()` now compares paths
+  exactly** — it used `includes()`, so `assertRedirect("/login")` passed on
+  `/login-as-someone-else`.
+- **`database.sqlite.foreignKeys`**, a doctor check for a `notifications` table that
+  is not the framework's, and a doctor check for a production `mail.driver` of `log`.
+
+### Changed
+
+- **`config/session.ts` is scaffolded environment-aware**, so the first production
+  deploy no longer fails on the config validator's (correct) refusal.
+- **Tailwind and its plugin move to `dependencies`** and the plugin is pinned — a
+  `--production` install that then builds on the server had neither.
+- **The notification database channel is built on first use**, so an app that never
+  routes there never touches the table.
+- **`@column({ type: "integer" })` compiles.** The object form took six type names
+  while the string form took twelve.
+- **`--success` meets WCAG AA** at the contrast it is actually drawn at.
+
+### Documented
+
+- [Persistent layouts](/docs/inertia/rendering#persistent-layouts), which failed only
+  in a browser and were documented nowhere;
+  [which Inertia redirects are covered](/docs/inertia/middleware#which-redirects-are-covered);
+  [pages render](/docs/testing#pages-render); the middleware names the framework
+  occupies; why `X-Forwarded-For` is counted from the right; and how to authenticate a
+  test when identity is not a row.
+
 ## 1.10.0 — 2026-08-30
 
 A second report from the team building on Zerotal, and the things it found. Most of this

package/docs/inertia/rendering.md

@@ -112,6 +112,73 @@ models with unloaded relations** — eager-load what the page needs (`.with("aut
 or map to a plain shape. Shared props (`auth.user`) are already reduced to scalars
 for you; see [Shared Props](/docs/inertia/props).
 
+## Persistent layouts
+
+A page can name a layout that survives navigation — the shell is not unmounted and
+remounted between visits, so its state, scroll position and any open panel stay put:
+
+```tsx fragment
+// resources/js/pages/mail.tsx
+import MailLayout from "../Layouts/MailLayout";
+
+export default function Mail({ messages }) {
+  return <MessageList messages={messages} />;
+}
+
+Mail.layout = (page) => <MailLayout>{page}</MailLayout>;
+```
+
+### The callback is handed the page element, not the page props
+
+This is the one thing to get right, because getting it wrong fails in a way nothing
+on the server can see:
+
+```tsx fragment
+// WRONG — `page.props` is undefined. Compiles, 200s, blank screen.
+Mail.layout = (page) => <MailLayout search={page.props.search}>{page}</MailLayout>;
+```
+
+The argument is the rendered page **element**. It has no `props.search`, so this
+throws `Cannot read properties of undefined` on the first paint — in the browser,
+after the response has been sent. The route still answers `200`, the Inertia payload
+is still correct, and a server-side test still passes. The user gets a white page.
+
+Read props with `usePage()` inside a layout component instead:
+
+```tsx fragment
+// resources/js/pages/mail.tsx
+import { usePage } from "@inertiajs/react";
+import type { SharedProps } from "../types";
+
+function MailLayout({ children }) {
+  const { props } = usePage<SharedProps & { search?: string }>();
+  return <SuiteLayout search={props.search}>{children}</SuiteLayout>;
+}
+
+Mail.layout = (page) => <MailLayout>{page}</MailLayout>;
+```
+
+`usePage()` reads the same page object the server sent, from context, and works at
+any depth — so a layout five components down needs nothing threaded to it.
+
+> **Why the wrong form typechecks.** `@inertiajs/react` types the callback's argument
+> loosely enough that reaching for `.props` is not a compile error, and a cast to get
+> past a complaint makes it worse. The check that catches it is
+> [rendering the page in a test](/docs/testing#pages-render) — the scaffold ships one,
+> and it is the only thing in a normal suite that builds the component tree at all.
+
+### One layout for several pages
+
+Assign the same callback, or export it from the layout module and reuse it:
+
+```tsx fragment
+// resources/js/Layouts/MailLayout.tsx
+export const withMailLayout = (page: ReactNode) => <MailLayout>{page}</MailLayout>;
+
+// resources/js/pages/mail.tsx
+Mail.layout = withMailLayout;
+```
+
 ## First load vs. navigation
 
 `inertia()` branches on the `X-Inertia` request header:

package/docs/migrations.md

@@ -397,6 +397,16 @@ The `onDelete` / `onUpdate` actions are `"CASCADE"`, `"SET NULL"`, `"RESTRICT"`,
 `"NO ACTION"`. Shorthands `cascadeOnDelete()`, `nullOnDelete()`, and `restrictOnDelete()`
 read more fluently.
 
+> **SQLite only enforces these when asked**, and it is the only supported dialect that
+> behaves that way — `database.sqlite.foreignKeys` defaults to `true` and sets
+> `PRAGMA foreign_keys = ON` on every connection. Turn it off and the declarations
+> above become comments: deleting a parent leaves its children, silently, and every
+> child has to be removed by hand in the right order. An app's data-erasure path
+> missed three tables that way, two of them holding uploaded files.
+>
+> On a database that ran without enforcement, `bun zt db:check-foreign-keys` lists any
+> rows that would now be rejected. Postgres and MySQL always enforce.
+
 ## Soft deletes
 
 ```typescript fragment

package/docs/orm/index.md

@@ -202,12 +202,21 @@ import { column } from "@zerotal/orm";
 
 Shorthands map to: `string`, `text`, `integer`, `number`, `float`, `boolean`, `datetime`, `date`, `json`, `array`, `encrypted`, `encrypted:json`. See [Casts & Mutators](/docs/orm/casts) for the full cast reference.
 
-A shorthand is not the same as `type`. `type` is only the storage type —
-`string`, `text`, `number`, `boolean`, `datetime`, `json` — so `{ type: "integer" }`
-and `{ type: "encrypted" }` are both errors. The shorthands that look like types
-(`integer`, `float`, `encrypted`) are type-and-cast pairs: `@column("integer")` is
-`{ type: "number", cast: "integer" }`, and `@column("encrypted")` is
-`{ type: "text", cast: "encrypted" }`.
+**`type` takes either vocabulary.** The _storage_ types are `string`, `text`,
+`number`, `boolean`, `datetime` and `json` — what schema generation emits. The
+shorthands that look like types (`integer`, `float`, `date`, `encrypted`) are
+type-and-cast pairs, and writing one as a `type` resolves it the same way the string
+form does:
+
+```typescript fragment
+// in a model class body
+@column({ type: "integer", default: 0 }) retries!: number; // → { type: "number", cast: "integer" }
+@column({ type: "encrypted", nullable: true }) idNumber?: string; // → { type: "text", cast: "encrypted" }
+```
+
+`{ type: "integer" }` used to be an error while `@column("integer")` compiled, so the
+vocabulary halved exactly when a column needed `default`, `nullable` or `unique` —
+which is most real columns. An explicit `cast` alongside a shorthand still wins.
 
 `string` is a bounded VARCHAR and `text` is the unbounded TEXT type — a distinction that matters on Postgres and MySQL, where a long body in a `VARCHAR(255)` is an error rather than a slow column.
 

package/docs/support-policy.md

@@ -64,17 +64,21 @@ All `@zerotal/*` packages and `create-zerotal` share **one version line and
 publish lockstep** — a release publishes every package at the same version, in
 dependency order, from CI. Never mix versions across packages.
 
-- **Semantic versioning:** patch for fixes, minor for compatible features, major
-  for breaking changes. The [Upgrade Guide](/docs/upgrade) describes the upgrade
-  procedure; the [Release Notes](/docs/changelog) list what changed.
-- **One exception, while the 1.x line is young:** a breaking change may land in a
-  minor or a patch when leaving it in place would cost more than the migration
-  does. It is called out in the release notes as **BREAKING**, with the reason and
-  the migration steps, and it is never silent. Three have shipped so far — the
+- **What the numbers mean:** a **patch** is anything that does not break —
+  a fix, and a feature too. A **minor** carries a breaking change. A **major** is
+  an annual consolidation, cut each July. The
+  [Upgrade Guide](/docs/upgrade#versioning) explains why the framework is versioned
+  this way and describes the upgrade procedure; the
+  [Release Notes](/docs/changelog) list what changed.
+- **What that costs you:** a caret range crosses a minor, so a project on
+  `^1.10.0` takes 1.11.0 and its breaking change without being asked. Pin with a
+  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. Four have shipped so far — the
   `ComponentWith` / `BaseModelWith` removal in 1.3.0, Flow's `socket:` listener
-  prefix in 1.7.2, and the removal of Flow's `this.title(…)` in 1.7.3. This carve-out is a consequence of the project's age, not a
-  standing policy; it will be withdrawn, with a version named here, once adoption
-  makes the cost of a break real.
+  prefix in 1.7.2, the removal of Flow's `this.title(…)` in 1.7.3, and SQLite
+  foreign-key enforcement in 1.11.0.
 - **Provenance:** packages are published with npm provenance, so you can verify
   a tarball was built by this repository's release workflow rather than someone's
   laptop.

package/docs/testing/http.md

@@ -171,6 +171,21 @@ await testApp.withSession({ locale: "fr", flash: "saved" }).get("/profile");
 `session.secret` and `session.cookie` from your config. `withSession()` preserves
 any `user_id` already set by `actingAs()`.
 
+> **No users table?** `withSession()` is the whole answer, and it is the one to reach
+> for when identity is not a row — an app whose login _is_ an IMAP login has no user
+> to hand `actingAs()`. Seed whatever your app reads from the session and the request
+> is authenticated:
+>
+> ```typescript fragment
+> // in a test
+> await testApp.withSession({ mail_wallet: { primary: "a@example.test" } }).get("/mail");
+> ```
+>
+> Reaching past this to the session driver is the wrong layer and does not work —
+> `driver.write()` is not a method, and `saveSession()` wants an id and a `Response`
+> you do not have yet. Both of these encode through the app's _own_ driver, so the
+> cookie always matches the format the app will read.
+
 ### Headers and redirects
 
 ```typescript fragment
@@ -396,42 +411,43 @@ expect(ctx.response?.status).toBe(200);
 
 ### TestResponse
 
-| Member                                                                              | Signature                                 | Description                                          |
-| ----------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------- |
-| `assertStatus`                                                                      | `assertStatus(expected: number): this`    | Assert the status code.                              |
-| `assertOk` / `assertCreated` / `assertNoContent`                                    | `(): this`                                | Assert `200` / `201` / `204`.                        |
-| `assertSuccessful`                                                                  | `(): this`                                | Assert any `2xx`.                                    |
-| `assertMovedPermanently`                                                            | `(): this`                                | Assert `301`.                                        |
-| `assertUnauthorized` / `assertForbidden` / `assertNotFound` / `assertUnprocessable` | `(): this`                                | Assert `401` / `403` / `404` / `422`.                |
-| `assertServerError`                                                                 | `(): this`                                | Assert `500`.                                        |
-| `assertRedirect`                                                                    | `assertRedirect(url: string): this`       | Assert a `3xx` whose `Location` contains `url`.      |
-| `assertHeader`                                                                      | `assertHeader(name, value?): this`        | Assert a header is present (and contains `value`).   |
-| `assertHeaderMissing`                                                               | `assertHeaderMissing(name): this`         | Assert a header is absent.                           |
-| `assertJson`                                                                        | `assertJson(expected): this`              | Assert each key in `expected` matches the JSON body. |
-| `assertJsonPath`                                                                    | `assertJsonPath(path, expected): this`    | Assert a dot-notation path in the JSON body.         |
-| `assertJsonCount`                                                                   | `assertJsonCount(count, key?): this`      | Assert an array length at the body or `key`.         |
-| `assertSee` / `assertBodyContains`                                                  | `(needle): this`                          | Assert the body contains `needle`.                   |
-| `assertDontSee`                                                                     | `assertDontSee(needle): this`             | Assert the body does not contain `needle`.           |
-| `assertSeeText` / `assertDontSeeText`                                               | `(needle): this`                          | The same, against the body with its tags stripped.   |
-| `assertInvalid`                                                                     | `assertInvalid(fields?): this`            | Assert validation failed, optionally on `fields`.    |
-| `assertValid`                                                                       | `assertValid(fields?): this`              | Assert validation did not fail.                      |
-| `validationErrors`                                                                  | `(): Record<string, string[]> \| null`    | The errors, from the body or the session.            |
-| `assertAuthenticated`                                                               | `(): this`                                | Assert the session holds a `user_id`.                |
-| `assertAuthenticatedAs`                                                             | `assertAuthenticatedAs(user \| id): this` | Assert that specific user is signed in.              |
-| `assertGuest`                                                                       | `(): this`                                | Assert nobody is signed in.                          |
-| `assertCookie`                                                                      | `assertCookie(name, value?): this`        | Assert a `Set-Cookie` (and optional value).          |
-| `assertCookieMissing`                                                               | `assertCookieMissing(name): this`         | Assert no such cookie is set.                        |
-| `assertSessionHas`                                                                  | `assertSessionHas(key, value?): this`     | Assert the session contains `key`.                   |
-| `assertSessionMissing`                                                              | `assertSessionMissing(key): this`         | Assert the session lacks `key`.                      |
-| `assertSessionHasErrors` / `assertSessionHasNoErrors`                               | `(fields?): this`                         | Assert flashed validation errors.                    |
-| `session`                                                                           | `(): Record<string, unknown> \| null`     | The decoded session.                                 |
-| `assertInertia`                                                                     | `assertInertia(component?, props?): this` | Assert the Inertia page and a partial prop match.    |
-| `assertInertiaProp`                                                                 | `assertInertiaProp(key, value?): this`    | Assert a single Inertia prop.                        |
-| `inertia`                                                                           | `(): InertiaPage \| null`                 | The Inertia page object, from either wire shape.     |
-| `exception`                                                                         | `(): unknown`                             | The exception the request raised, if any.            |
-| `json`                                                                              | `json<T>(): T`                            | Parse and return the full JSON body.                 |
-| `text`                                                                              | `text(): string`                          | Return the body as text.                             |
-| `status` / `ok` / `headers`                                                         | getters                                   | The underlying `Response` status, `ok`, and headers. |
+| Member                                                                              | Signature                                        | Description                                                                    |
+| ----------------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------ |
+| `assertStatus`                                                                      | `assertStatus(expected: number): this`           | Assert the status code.                                                        |
+| `assertOk` / `assertCreated` / `assertNoContent`                                    | `(): this`                                       | Assert `200` / `201` / `204`.                                                  |
+| `assertSuccessful`                                                                  | `(): this`                                       | Assert any `2xx`.                                                              |
+| `assertMovedPermanently`                                                            | `(): this`                                       | Assert `301`.                                                                  |
+| `assertUnauthorized` / `assertForbidden` / `assertNotFound` / `assertUnprocessable` | `(): this`                                       | Assert `401` / `403` / `404` / `422`.                                          |
+| `assertServerError`                                                                 | `(): this`                                       | Assert `500`.                                                                  |
+| `assertRedirect`                                                                    | `assertRedirect(url: string): this`              | Assert a `3xx` whose `Location` path equals `url`.                             |
+| `assertRedirectContains`                                                            | `assertRedirectContains(fragment: string): this` | Assert a `3xx` whose `Location` merely contains `fragment` — for a signed URL. |
+| `assertHeader`                                                                      | `assertHeader(name, value?): this`               | Assert a header is present (and contains `value`).                             |
+| `assertHeaderMissing`                                                               | `assertHeaderMissing(name): this`                | Assert a header is absent.                                                     |
+| `assertJson`                                                                        | `assertJson(expected): this`                     | Assert each key in `expected` matches the JSON body.                           |
+| `assertJsonPath`                                                                    | `assertJsonPath(path, expected): this`           | Assert a dot-notation path in the JSON body.                                   |
+| `assertJsonCount`                                                                   | `assertJsonCount(count, key?): this`             | Assert an array length at the body or `key`.                                   |
+| `assertSee` / `assertBodyContains`                                                  | `(needle): this`                                 | Assert the body contains `needle`.                                             |
+| `assertDontSee`                                                                     | `assertDontSee(needle): this`                    | Assert the body does not contain `needle`.                                     |
+| `assertSeeText` / `assertDontSeeText`                                               | `(needle): this`                                 | The same, against the body with its tags stripped.                             |
+| `assertInvalid`                                                                     | `assertInvalid(fields?): this`                   | Assert validation failed, optionally on `fields`.                              |
+| `assertValid`                                                                       | `assertValid(fields?): this`                     | Assert validation did not fail.                                                |
+| `validationErrors`                                                                  | `(): Record<string, string[]> \| null`           | The errors, from the body or the session.                                      |
+| `assertAuthenticated`                                                               | `(): this`                                       | Assert the session holds a `user_id`.                                          |
+| `assertAuthenticatedAs`                                                             | `assertAuthenticatedAs(user \| id): this`        | Assert that specific user is signed in.                                        |
+| `assertGuest`                                                                       | `(): this`                                       | Assert nobody is signed in.                                                    |
+| `assertCookie`                                                                      | `assertCookie(name, value?): this`               | Assert a `Set-Cookie` (and optional value).                                    |
+| `assertCookieMissing`                                                               | `assertCookieMissing(name): this`                | Assert no such cookie is set.                                                  |
+| `assertSessionHas`                                                                  | `assertSessionHas(key, value?): this`            | Assert the session contains `key`.                                             |
+| `assertSessionMissing`                                                              | `assertSessionMissing(key): this`                | Assert the session lacks `key`.                                                |
+| `assertSessionHasErrors` / `assertSessionHasNoErrors`                               | `(fields?): this`                                | Assert flashed validation errors.                                              |
+| `session`                                                                           | `(): Record<string, unknown> \| null`            | The decoded session.                                                           |
+| `assertInertia`                                                                     | `assertInertia(component?, props?): this`        | Assert the Inertia page and a partial prop match.                              |
+| `assertInertiaProp`                                                                 | `assertInertiaProp(key, value?): this`           | Assert a single Inertia prop.                                                  |
+| `inertia`                                                                           | `(): InertiaPage \| null`                        | The Inertia page object, from either wire shape.                               |
+| `exception`                                                                         | `(): unknown`                                    | The exception the request raised, if any.                                      |
+| `json`                                                                              | `json<T>(): T`                                   | Parse and return the full JSON body.                                           |
+| `text`                                                                              | `text(): string`                                 | Return the body as text.                                                       |
+| `status` / `ok` / `headers`                                                         | getters                                          | The underlying `Response` status, `ok`, and headers.                           |
 
 ## Next steps
 

package/docs/testing/index.md

@@ -209,6 +209,46 @@ observers, global scopes, and state-machine callbacks, plus framework event
 subscriptions. `createTestApp()` and `testApp.close()` call it for you, so suites
 using those helpers don't need the explicit `afterEach`.
 
+## Pages render
+
+A test that asserts a status code or an Inertia payload proves the _server_ did its
+job. It proves nothing about the component, and a page can throw on its first paint
+while every such test passes — the route answers `200`, the payload is correct, and
+the failure happens in a browser the suite never opened.
+
+An app shipped a blank page to production with **614 passing tests** exactly that way:
+a [layout callback](/docs/inertia/rendering#persistent-layouts) read `page.props`,
+which the callback is not given.
+
+`renderPage()` builds the component tree and lets whatever it throws escape:
+
+```typescript fragment
+// tests/pages.test.ts
+import { renderPage } from "@zerotal/inertia/testing";
+import Profile from "../resources/js/pages/profile";
+
+test("profile builds", async () => {
+  await renderPage(Profile, { title: "Profile" }, { shared: SHARED });
+});
+```
+
+It renders through Inertia's own `<App>`, so `usePage()`, `<Head>` and a persistent
+layout all behave as they do in the browser — the layout is resolved and rendered
+too, which is the case worth catching.
+
+Two things to know:
+
+- **Seed the shared props.** A component that destructures `auth` or `flash` throws
+  without them. That is a real failure and rarely the one you are testing for, so
+  pass the shape your `Inertia.share()` actually sends.
+- **It is not a DOM.** `useEffect` does not run and nothing clicks; this is
+  `renderToString`. For behaviour after paint, use
+  [the browser harness](/docs/testing/browser).
+
+The React scaffold ships one of these covering every page it generates. Add a line
+when you add a page — the cost is one line and the bug it catches is a white screen
+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
@@ -271,6 +311,7 @@ preload runs the floor check as a warning.
 | `runtimeBelowFloor`        | `runtimeBelowFloor(cwd?): RuntimeFloor \| null`           | Is this process below that floor? `null` when it is met or none is declared.                |
 | `runtimeBelowFloorMessage` | `runtimeBelowFloorMessage(floor): string`                 | The explanation to print — both versions, the manifest, and the way out.                    |
 | `installedBunVersion`      | `installedBunVersion(cwd): { version, manifest } \| null` | The Bun in `node_modules`, if the project installs one as a package.                        |
+| `declaresBunDependency`    | `declaresBunDependency(cwd): boolean`                     | Whether the project _asked_ for that package, or acquired it as a transitive peer.          |
 | `runtimeMismatch`          | `runtimeMismatch(cwd?): RuntimeMismatch \| null`          | Does the running Bun differ from the installed one? Compared exactly — a patch is a binary. |
 | `runtimeMismatchMessage`   | `runtimeMismatchMessage(mismatch): string`                | The explanation for that one.                                                               |
 | `runtimeMismatchAllowed`   | `runtimeMismatchAllowed(): boolean`                       | Whether `ZT_ALLOW_RUNTIME_MISMATCH` is set.                                                 |

package/docs/upgrade.md

@@ -10,15 +10,28 @@ what changed in each version, see the [Release Notes](/docs/changelog).
 
 ## Versioning
 
-Zerotal follows semantic versioning across its `@zerotal/*` packages, which share a
-version line:
-
-- **Patch** (`x.y.Z`) — bug fixes, safe to take anytime.
-- **Minor** (`x.Y.z`) — new features, backward compatible.
-- **Major** (`X.y.z`) — breaking changes; read the version's section in the
-  [Release Notes](/docs/changelog) before upgrading.
-
-> **Warning** — while the 1.x line is young, a breaking change may also land in a minor or a patch. It is always labelled **BREAKING** in the [Release Notes](/docs/changelog) with migration steps. Read the notes for every version you cross, not only the majors. See [Releases and versioning](/docs/support-policy#releases-and-versioning) for which ones have shipped and when this carve-out ends.
+Zerotal's `@zerotal/*` packages share one version line, and what each number means
+is set by how much the framework still moves in a year rather than by the letter of
+semver:
+
+- **Patch** (`x.y.Z`) — anything that does not break. Fixes, and features too.
+  Safe to take at any time.
+- **Minor** (`x.Y.z`) — a breaking change. Always labelled **BREAKING** in the
+  [Release Notes](/docs/changelog), with the reason and the migration steps, and
+  given its own section on this page.
+- **Major** (`X.y.z`) — an annual consolidation, cut each July. The next is 2.0, in
+  July 2027.
+
+Why not strict semver: a framework this young corrects itself often, and under
+strict semver every correction is a major. A version line that reaches 9.0 in its
+first year tells a reader nothing about how much has changed — only that the
+project is willing to break things, which the release notes already say far more
+precisely. Keeping the major for a yearly line in the sand leaves it meaning
+something, and puts the work where it is useful: reading the notes for each minor.
+
+> **Warning** — **a caret range crosses a minor.** `"zerotal": "^1.10.0"` will
+> install 1.11.0, and its breaking change, without asking. Read the notes for every
+> minor you cross, or pin with a tilde (`~1.10.0`) and cross them deliberately.
 
 > **Warning** — always upgrade the `@zerotal/*` packages together. Mixing versions across core, ORM, and feature packages leads to type and runtime mismatches.
 
@@ -217,6 +230,65 @@ worth thirty seconds of checking if it does.
    Nothing to change if you already have it as a dependency, which every React Inertia app
    does.
 
+## 1.10 to 1.11
+
+Two changes to how the database is treated. Both are **BREAKING** in the narrow sense
+that a working app can stop working on upgrade, and both refuse loudly rather than
+doing something quiet.
+
+1. **SQLite enforces foreign keys.** `database.sqlite.foreignKeys` defaults to `true`,
+   so `PRAGMA foreign_keys = ON` is set on every connection. Until now SQLite ignored
+   them, which meant `constrained()` and `cascadeOnDelete()` in your migrations
+   described behaviour the database would not perform — deleting a parent left its
+   children, silently.
+
+   The risk is data you already have. A child row whose parent is missing was legal
+   without enforcement and is a constraint violation with it, so a write touching one
+   now fails. Find them before deploying:
+
+   ```bash fragment
+   bun zt db:check-foreign-keys
+   ```
+
+   It lists every offending row by table and rowid and exits non-zero, so a release
+   script can gate on it. `zt doctor` reports the same thing. Delete them or repoint
+   them at a parent that exists.
+
+   To take the release without dealing with it yet:
+
+   ```ts fragment
+   // config/database.ts
+   export default DatabaseConfig({ sqlite: { foreignKeys: false } });
+   ```
+
+   Take that override back off afterwards. With it in place `cascadeOnDelete()` is a
+   comment.
+
+2. **A renumbered migration is refused rather than re-run.** A migration is recorded
+   under its filename, so renaming one makes an applied migration look pending — the
+   runner tries it again and fails on `table already exists`. Renumbering `001_` to
+   `0001_` to match the scaffold's convention is exactly the kind of tidying that
+   causes it, and it takes every migration with it.
+
+   `migrate` now recognises that shape and stops:
+
+   ```
+   "0001_create_users" looks like "001_create_users", which has already run — the
+   same migration renumbered rather than a new one.
+   ```
+
+   If you meant to rename, pin the identity to what the database already holds and the
+   filename is then free:
+
+   ```ts fragment
+   export default class CreateUsers extends Migration {
+     static override id = "001_create_users";
+   }
+   ```
+
+   If it really is a new migration, give it a name that does not collide once the
+   leading digits are removed.
+
 ## The managed zt.ts
 
 `zt.ts` is framework-managed — the header says _do not modify_. If a release

package/package.json

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