@zerotal/arch 1.9.0 → 1.11.0

package/api-surface.md

@@ -119,7 +119,7 @@ interface DoctorReport = {
 interface GuidelineOptions = {
   packages: string[]
   serverName: string
-  shape?: ProjectShape
+  shape?: ProjectShape | undefined
 }
 
 interface InstalledPackage = {
@@ -177,8 +177,8 @@ interface SchemaReport = {
 }
 
 interface SpawnProbeOptions = {
-  cwd?: string
-  timeoutMs?: number
+  cwd?: string | undefined
+  timeoutMs?: number | undefined
 }
 
 interface ToolContext = {
@@ -262,10 +262,10 @@ interface ServerIdentity = {
 }
 
 interface StdioOptions = {
-  input?: ReadableStream<Uint8Array<ArrayBufferLike>>
-  log?: (message: string) => void
+  input?: ReadableStream<Uint8Array<ArrayBufferLike>> | undefined
+  log?: ((message: string) => void) | undefined
   server: McpServer
-  write?: (frame: string) => void
+  write?: ((frame: string) => void) | undefined
 }
 
 interface ToolOutcome = {

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,298 @@ 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
+release is failures that were silent by construction — mail delivered nowhere, a page
+shared as a grey rectangle, a schedule that never fired, a rate limiter with one bucket
+for everybody. None of them logged anything.
+
+**Three things to know before upgrading.**
+
+- **React apps using SSR now need `@inertiajs/react` installed.** It is the same adapter
+  your browser entry point already uses; the server renders through its `<App>` so
+  `<Head>` works. A missing one is a named error rather than a silent omission.
+- **`scheduler.timezone` does something now.** It was documented as informational and read
+  by nothing. Its default moved from the literal `"UTC"` to **the system zone**, so an app
+  that never set the key keeps doing exactly what it did — but an app that set it now gets
+  what it asked for. If you set it to `"UTC"` on a server that is not on UTC, your
+  schedules will move. See [the upgrade guide](/docs/upgrade#1-9-to-1-10).
+- **Named rate limiters need `.trustedProxies(n)` behind a proxy.** `.byIp()`, `.byUser()`
+  and `.byApiKey()` now ignore `X-Forwarded-For` unless told how many proxies sit in
+  front, which is the same rule `ThrottleMiddleware` already followed. `zt doctor` reports
+  any that need it.
+
+### Added
+
+- **`zt assets:prune`** — removes the chunks an earlier release left behind, on the machine
+  that never ran a build. `assets:build --clean` cleans the directory it _builds into_,
+  which does nothing for the usual release shape: build here, tar the output, extract it
+  over `public/` there. Extracting merges, so every deploy adds another set of
+  content-hashed chunks and none are ever removed. One app reached 225 chunk files for the
+  49 its entry point references. Ship `.zerotal/` with the release and this removes what
+  the build record does not claim. See [Deployment](/docs/deployment#assetsprune--clearing-up-after-the-extract-instead-of-before-it).
+
+- **`zt deploy:<env> --check`** — the preflight gate on its own, for the point in a release
+  script where the new code is on disk and the service has not restarted. Exit 0 and
+  restart; exit non-zero and keep serving the previous release. Everything that can refuse
+  already runs by the end of preflight and none of it mutates, so stopping there is a
+  complete answer rather than half a deploy.
+
+- **`RateLimiter.trustedProxies(n)`** on the fluent builder, and
+  **`res.assertInertiaRedirect(url)`** in `@zerotal/testing` — the assertion that checks
+  what actually breaks on an Inertia redirect, which is the `X-Inertia` marker rather than
+  the status and `Location` a normal redirect assertion already covers.
+
+- **`@zerotal/core/runtime`** (`zerotal/runtime`) — the runtime checks as exports, so a
+  script or a test can make the same assertion `zt` makes: `runtimeBelowFloor`,
+  `declaredBunFloor`, `runtimeMismatch`, `bunBinary` and the messages that go with them.
+
+- **`definedOnly()` and `Resolved<T>`** on `@zerotal/core/helpers`, for merging an options
+  bag over defaults without an explicit `undefined` overwriting one.
+
+- **Scheduler timezone helpers** — `wallClockIn`, `isValidTimeZone`,
+  `CronExpression.matchesIn` and `CronExpression.nextRunAfterIn`, plus `SchedulerError` and
+  `UnknownTimeZoneError`.
+
+- **A boot line when a convention is skipped in this environment.** An env-restricted
+  concern is skipped by _not looking_, which is correct and completely silent: an app ran
+  for weeks in production with `app/schedules` full and no worker process, and nothing
+  logged anything because from a web process's point of view nothing existed.
+
+### Changed
+
+- **Optional properties in public option shapes are declared `?: T | undefined`.** The
+  generated `tsconfig.json` enables `exactOptionalPropertyTypes`, under which
+  `image?: string` refuses a key that is present and holds `undefined` — so
+  `{ image: candidate ?? undefined }`, the most ordinary thing there is, did not compile
+  and every conditionally-absent field had to be spelled `...(x ? { x } : {})`. 438
+  properties across 115 files. Nothing changes for a reader: an absent optional property
+  already read as `undefined`.
+
+- **`scheduler.timezone` is honoured**, and its default is the system zone rather than the
+  literal `"UTC"`. See the note above.
+
+- **`mail.driver: "log"` fails `zt doctor` in production** when `mail.from.address` has been
+  configured, and warns when it is still the placeholder. Mail written to a log file is
+  delivered to nobody and says so nowhere.
+
+### Fixed
+
+- **React SSR emitted no `<Head>` tags at all.** The React branch rendered the page
+  component directly, and `<Head>` renders nothing — it reports its children to a head
+  manager it reads from context, and rendering the component alone puts none there. So
+  every page served the template's `<head>`: no title, no description, no card. Nothing
+  failed and nothing logged, because the page is perfect in a browser, where React has run.
+  Only the readers that do not run JavaScript saw it — which is every link-preview scraper
+  and every `curl`.
+
+- **SMTP submission on port 587 sent nothing.** The STARTTLS handshake completed and then
+  the client's `EHLO` was dropped: `upgradeTLS()` returns the new socket while the
+  handshake is still in flight, and a write issued in that window is lost — not buffered,
+  not an error, gone. Port 465 was unaffected, so mail worked on the port nobody documents
+  and the 587 every provider _does_ document produced silence: no error, no bounce, no log
+  line, and password resets that never arrived.
+
+- **TLS certificates were not actually verified, on either SMTP transport.**
+  `rejectUnauthorized` is not enforced by the runtime — it reports a self-signed
+  certificate as authorized and puts the real reason beside it — so the connection was
+  encrypted and would have accepted that encryption from anyone in the network path. The
+  driver reads the handshake result itself now and fails closed.
+
+- **A scheduled task with a `timezone` took the whole scheduler down.** `Bun.cron`'s options
+  form throws, and it throws during registration, so the worker died on boot and
+  restart-looped: one task with a timezone stopped every task in the app. Zerotal evaluates
+  the zone itself now, and a task that cannot register takes only itself out.
+
+- **Named rate limiters ignored `trustedProxies`, and `zt doctor` was told not to look.**
+  `.byIp()`, `.byUser()` and `.byApiKey()` used a resolver that read the socket address and
+  fell back to the leftmost `X-Forwarded-For` entry with no proxy count. Behind a reverse
+  proxy every visitor keyed on the proxy's own address and shared one bucket, so a `login`
+  limiter of five attempts a minute was five attempts a minute for the entire user base and
+  one attacker locked everybody out. The doctor check written to catch this exempted any
+  custom `keyResolver`, which is what all three are.
+
+- **`ctx.session.intended()` could not read what `AuthMiddleware` stored.** It used the key
+  `intended` while the middleware and `redirect().intended()` used `intended_url`. Each pair
+  was internally consistent and separately tested, so every test passed — and an app that
+  mixed them, which the documentation invited, was silently sent to `/` after every sign-in.
+
+- **`MonitorStore` overwrote its own defaults with `undefined`.** It applied `?? …` defaults
+  and then spread `...opts` after them, and spread copies own properties even when they
+  hold `undefined` — so an unset config put `undefined` back over the retention window and
+  `prune()` computed a `NaN` cutoff, pruning nothing and reporting nothing.
+
+- **`engines.bun` is enforced.** Every generated app writes a floor and nothing read it.
+  `Intl` output moves between Bun releases, so a suite with currency or date assertions goes
+  red on a runtime that is otherwise fine and the failures name the code they touch rather
+  than the binary.
+
+- **The asset build record is portable.** Its filename was hashed from the output
+  directory's _absolute_ path, so a record shipped with a release matched nothing at the
+  other end and moving a checkout silently orphaned it.
+
+- **The React SSR root is marked `data-server-rendered`**, so the client hydrates the markup
+  instead of discarding it and rendering the page a second time. `POST /__ssr` returns the
+  same body shape as the Vue branch.
+
+### Documented
+
+- **["What a crawler sees"](/docs/inertia/ssr#what-a-crawler-sees)** — `inertia()` does not
+  server-render the component, which is the normal Inertia arrangement and worth saying out
+  loud: the served document is a `<title>` and a JSON blob. Which readers run JavaScript,
+  which do not, and the three ways to give the second group something to read.
+
+- **[Which Inertia redirects are covered](/docs/inertia/middleware#which-redirects-are-covered)**
+  — all of them, because `useOnce()` registers the middleware globally. Written down because
+  the opposite belief is what keeps an app's own workaround on every request forever.
+
+- **[`bun test` vs `bun zt test`](/docs/testing#bun-test-vs-bun-zt-test)** — the 30-second
+  timeout (the `bunfig.toml` key is ignored by Bun and `setDefaultTimeout()` in a preload
+  reaches only the first file, so the flag is the only mechanism that works), the runtime
+  check, and the fact that configuration resolves once per process — so a test that mutates
+  the environment in `beforeAll` is testing whichever file booted first.
+
+- **[Timezones](/docs/scheduler#timezones)** in the scheduler, **[the middleware names the
+  framework occupies](/docs/middleware#names-the-framework-already-occupies)**, and why
+  `X-Forwarded-For` is [counted from the right](/docs/rate-limiting#trustedproxies).
+
 ## 1.9.0 — 2026-08-29
 
 The gaps an app was filling in for itself: one Bun per project, a database backup that is not

package/docs/deployment.md

@@ -38,6 +38,7 @@ deliberate: systemd, your container runtime or your deploy script owns process
 lifecycle, and this gives it a gate to restart behind.
 
 ```bash
+bun zt deploy:production --check            # run the gate only — see below
 bun zt deploy:production --dry-run          # print the plan, run none of it
 bun zt deploy:production --skip-migrations  # release without touching the schema
 bun zt deploy:production --probe=https://example.com  # real handshake at the end
@@ -75,10 +76,11 @@ Omit the file entirely and you get `DEFAULT_DEPLOY_TARGETS`: `production` and
 ### Your own release gate
 
 The framework's preflight knows the things a framework can know: that this really is the
-environment you think it is, that the config validators pass, that `doctor` is happy. It
-cannot know that this workspace has no cancellation policy, that mail is still wired to the
-`log` driver so nothing is ever sent, or that the owner account is still on the password
-`admin:create` issued it. Those refusals are yours.
+environment you think it is, that the config validators pass, that `doctor` is happy —
+which now includes refusing a production release whose `mail.driver` is still `log`,
+because mail written to a log file is delivered to nobody and says so nowhere. It
+cannot know that this workspace has no cancellation policy, or that the owner account
+is still on the password `admin:create` issued it. Those refusals are yours.
 
 Write them as a command and name it `release:check` (exported as
 `CONVENTIONAL_PREFLIGHT_COMMAND`). The pipeline finds it by name — nothing to wire up:
@@ -124,6 +126,27 @@ Two things worth adding while you are there: `assets:build` and `inertia:build`
 `--clean`, which removes anything in the output directory the build did not write — see
 [Build assets](#build-assets).
 
+### `--check`: the gate on its own
+
+A release script has a moment where the new code is on disk and the service has not
+restarted yet. That is the moment to ask whether this release is fit to go live, and
+`--check` is the whole preflight and nothing else:
+
+```bash
+# on the box, after the new release is unpacked and before the restart
+APP_ENV=production bun zt deploy:production --check || exit 1
+systemctl restart app
+```
+
+It runs the environment check, the config validators with production semantics,
+`doctor`, and your own `release:check` — everything that can refuse — and builds
+nothing, migrates nothing, restarts nothing. Exit 0 and restart; exit non-zero and
+keep serving the previous release, which is the point. A workspace that has lost its
+banking details, or had its mail driver knocked back to `log`, never goes live broken.
+
+`--check` and `--dry-run` answer different questions. `--dry-run` prints the plan
+without running any of it, including the gate. `--check` runs the gate for real.
+
 > **Note** — `deploy:<env>` runs **where the app runs**, with that environment's
 > variables. It does not reach another machine over SSH. Run it on the box, or in
 > the container build, as the step before the restart.
@@ -310,6 +333,31 @@ Ordering matters if the old release is still serving traffic: clearing the direc
 its bundles away, so do it as close to the swap as you can, or stage the release in a new
 directory and move it into place.
 
+### `assets:prune` — clearing up after the extract instead of before it
+
+Clearing the directory first has a cost the ordering note above hints at: between the
+`rm -rf` and the new files landing, the release still serving traffic has no bundles.
+If you would rather extract over the top and tidy afterwards, `assets:build` records
+what it wrote and `assets:prune` removes what that record does not claim:
+
+```bash
+# on the build machine — the record is written under .zerotal/
+bun zt assets:build
+tar -czf release.tgz public .zerotal   # ship the record with the release
+
+# on the server, after extracting and before the restart
+bun zt assets:prune --dry-run          # list what would go
+bun zt assets:prune
+```
+
+**Ship `.zerotal/` with the release** — that is the part that makes it work. Without
+the record, "which files belong to this release" has no answer on a server that never
+ran a build, and `assets:prune` says so and removes nothing rather than guessing.
+
+It is conservative by design: it deletes a file only when the record does not claim it
+_and_ it is named the way the bundler names a code-split chunk. Your images and
+favicon are never candidates, because an output directory is usually `public/`.
+
 ### `--clean` for a directory the build does not own outright
 
 The cleanup above recognises the filenames `Bun.build()` produces. An app that sets its own

package/docs/helpers.md

@@ -393,6 +393,57 @@ matches how you want overrides to behave.
 > configured `driver`) are replaced by reference — they keep their prototype and are
 > never merged into.
 
+### `definedOnly` and `Resolved<T>` — merging a shallow options bag
+
+Every public option shape in the framework declares its optional properties as
+`?: T | undefined`, so that the most ordinary thing there is compiles under the
+`exactOptionalPropertyTypes` the generated `tsconfig.json` turns on:
+
+```typescript
+// in a controller
+import { Media } from "zerotal/media";
+
+await Media.store(file, { collection: request.input("collection") ?? undefined });
+```
+
+That flexibility moves a problem to the merge. **Object spread copies own properties
+even when their value is `undefined`**, so `{ ...DEFAULTS, ...options }` lets an
+explicitly-`undefined` field overwrite a default rather than leave it standing —
+which is how a `pingInterval` of `undefined` once became `setInterval(fn, 0)` and
+~830 pings a second. `definedOnly` is the fix: it drops the keys whose value is
+`undefined`, so "supplied as undefined" reads as "not supplied".
+
+```typescript fragment
+// in a class that takes options
+const merged = { ...DEFAULTS, ...definedOnly(options) };
+```
+
+`deepMerge` already does this for you — it skips `undefined` overrides at every
+depth — so `definedOnly` is for the shallow case where a spread is all you need.
+
+`Resolved<T>` is the type of what comes out. **`Required<T>` is not the same thing**,
+and that is the trap: `-?` removes the optionality a `?` introduced, but it does not
+remove an `undefined` written into the type. So `Required<MediaOptions>` still hands
+back `string | undefined` for a `collection?: string | undefined`, and a "defaults
+have been applied" type quietly stops meaning that.
+
+```typescript fragment
+// in a class that takes options
+interface Options {
+  retentionDays?: number | undefined;
+  storage?: string | undefined;
+}
+
+// Required<Pick<Options, "retentionDays">>  →  { retentionDays: number | undefined }  ✗
+// Resolved<Pick<Options, "retentionDays">>  →  { retentionDays: number }              ✓
+private readonly _opts: Resolved<Pick<Options, "retentionDays">> &
+  Omit<Options, "retentionDays">;
+```
+
+`Omit` rather than `& Options` for the rest: intersecting with the whole shape puts
+the optional declaration of each resolved field back alongside the required one, so
+the field reads as possibly `undefined` in the very code that just gave it a default.
+
 ## Fluent wrappers
 
 ### fluent

package/docs/inertia/middleware.md

@@ -50,6 +50,50 @@ would just register it twice (and `useOnce` guards against that anyway).
 > the authenticated user is always populated by the time props are built; you don't
 > need to hand-order `InertiaMiddleware` relative to auth.
 
+## Which redirects are covered
+
+**All of them.** `useOnce()` registers `InertiaMiddleware` as _global_ middleware, so it
+runs on every request the app serves — however that route declared its own middleware,
+whether as an array, a map form (`{ ALL, POST }`), a group, or nothing at all. There is
+no route that reaches a controller without passing through it, so there is no redirect
+it does not mark.
+
+This is worth stating plainly because the opposite belief is expensive. An app that
+thinks some routes miss the middleware writes its own global `InertiaRedirectMiddleware`
+to cover them, and then cannot tell whether it is still needed: removing it leaves every
+test green either way, because the tests assert a status and a `Location` and those were
+never the part that broke.
+
+Three things have to be true for the Inertia client to follow a redirect, and the
+middleware guarantees all three:
+
+|                                                                              | Set on                                                                             |
+| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| A redirect status — `303` after a non-GET, so the browser follows with `GET` | every Inertia redirect                                                             |
+| `Location`                                                                   | your handler; carried through untouched, along with `Set-Cookie`                   |
+| `X-Inertia: true`                                                            | **every** Inertia redirect, including one your handler already returned as a `303` |
+
+That last row is the one that was wrong before 1.8.0: the marker was set inside the
+302→303 conversion, so a handler doing the protocol-correct thing already —
+`http.redirect(to, 303)` — skipped the only line that marked the response as Inertia's.
+The request succeeded, the row was written, and the form sat there with its fields still
+filled in.
+
+### Pinning it from a test
+
+`assertRedirect` checks the two headers that were never the problem. `assertInertiaRedirect`
+checks all three:
+
+```typescript fragment
+// tests/Feature/OrdersTest.ts
+const res = await app.post("/orders", data, { headers: { "X-Inertia": "true" } });
+
+res.assertInertiaRedirect("/orders/1");
+```
+
+Send the request with the `X-Inertia` header, or there is nothing to assert — a redirect
+to a browser that is not running Inertia is just a redirect.
+
 ## Asset versioning
 
 The asset version is a string sent as part of every page object. When it changes, the