@zerotal/arch 1.13.0 → 1.13.2

package/docs/changelog.md

@@ -27,6 +27,83 @@ 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.13.2 — 2026-08-31
+
+From a production field report at 1.12.0 — an Inertia + React app on SQLite, 117 routes,
+1256 tests, live behind Caddy. Six items, of which one was still open. The other five had
+been closed between 1.10.0 and 1.13.0 and are listed at the end, because a report that
+carries items forward is worth answering precisely rather than generally.
+
+### Fixed
+
+- **`Inertia.stream()` honours `X-Inertia`.** It answered every request with `text/html`,
+  including the XHR a running Inertia client sends. So the obvious way to adopt server
+  rendering — point a route at `stream` — broke client-side navigation _to_ that route.
+
+  The shape of the failure is the reason it survived: the first load looks perfect, which
+  is what a person checks. The second click does nothing. It fails only for somebody
+  already in the app, silently, and only once the route otherwise works.
+
+  `render` and `stream` now share the branch that writes the page object rather than one
+  of them having it, which is precisely how they came apart. An app that wrote a header
+  check in front of the call can delete it; it does no harm either way.
+
+### Verified, not changed
+
+Five of the six items were already closed. Each was re-checked against this release rather
+than taken on trust, because the report carried them forward from 1.9.0:
+
+- **STARTTLS on port 587** — fixed in 1.11.0, with `SmtpStartTls.test.ts` covering it. The
+  cause was that a write issued before the handshake completes is dropped.
+- **`intended_url` across `Auth.attempt()`** — fixed in 1.11.0. `attempt` delegates to
+  `login`, `regenerate()` deliberately carries the data bag, and only privilege markers are
+  swept. `intendedFlow.test.ts` runs the three steps in order against a real session,
+  including the ID rotation.
+- **`bun install --ignore-scripts`** — documented in the
+  [deployment guide](/docs/deployment).
+- **A default test timeout** — `zt test` has passed `--timeout=30000` for some time, and
+  [the testing guide](/docs/testing#bun-test-vs-bun-zt-test) already names the two
+  alternatives that do not work: `bunfig.toml`'s `[test] timeout`, and
+  `setDefaultTimeout()` in a preload.
+- **`postForm` refusing a `File`** — it has thrown, naming `multipart()`, since 1.0.2.
+
+The report's other upload concern — that `http.file()` consumes the multipart stream, so a
+later `body()` reads empty — **does not reproduce**: `_parseFormData()` caches, and reading
+the file first is safe. A test now pins that, since nothing had covered that order.
+
+## 1.13.1 — 2026-08-31
+
+One addition, found by sizing a job rather than doing it.
+
+The 2.0 ledger carries an entry to prefix every `@internal` export with `_` — 270 symbols,
+filed as mechanical. Three of them are `Job` classes, and a job class name is not a source
+symbol: `JobRegistry` keys on it and that string is written into the persisted queue payload,
+so a job enqueued yesterday is resolved by today's process. Renaming one invalidates every job
+already in the queue, at deploy time rather than at change time, and no test sees it because a
+test enqueues and runs in the same process.
+
+The rename is re-scoped. The hazard it exposed is fixed here.
+
+### Added
+
+- **`Job.jobName`** — a declared name for the queue payload, so renaming a job class is free:
+
+  ```ts
+  export class SendWelcomeEmail extends Job {
+    static override jobName = "SendWelcomeEmail"; // survives a class rename
+    async handle(): Promise<void> {}
+  }
+  ```
+
+  It defaults to the class name, so a job that declares nothing behaves exactly as before.
+  This is the same tool [`Migration.id`](/docs/upgrade#1-10-to-1-11) is for a migration's
+  filename, shipped in 1.11.0 for the same reason: an identity the framework derived from a
+  name someone was free to change, with no way to say otherwise.
+
+  It also decouples the queue from a build that mangles names. `zt compile` does not minify
+  today, so that is not a live hazard — but nothing in the registry said it depended on that,
+  and an assumption worth relying on is worth writing down.
+
 ## 1.13.0 — 2026-08-31
 
 Three retirements, taken together on purpose. Each is a small migration, and three minors

package/docs/inertia/ssr.md

@@ -89,12 +89,23 @@ export class PostController {
 | Response body  | Fully buffered string    | Streaming `ReadableStream`         |
 | TTFB           | Immediate                | After the shell is ready           |
 | Page `<Head>`  | Client only              | Collected into the served `<head>` |
-| XHR navigation | JSON (the normal path)   | N/A — only the first-page document |
+| XHR navigation | JSON (the normal path)   | JSON — the same page object        |
 
-For XHR navigations (`X-Inertia: true`), keep using `inertia()` — streaming only
-benefits the initial HTML document load.
+**Both implement the whole protocol.** An `X-Inertia: true` request gets the page
+object as JSON from either one; the streaming half applies to the first arrival,
+which is the only load that renders a document.
+
+That means a route can be moved to `inertiaStream()` for its cold load without
+anything else changing. Until 1.13.2 it could not: `inertiaStream()` answered every
+request with `text/html`, including the XHR, so pointing a route at it broke
+client-side navigation _to_ that route. The first load looked perfect — which is what
+a person checks — and the second click did nothing, for somebody already in the app.
+Apps that hit this wrote a header check in front of the call; that workaround still
+works and is no longer needed.
 
 > **Tip** — Stream the heaviest landing pages and leave everything else on `inertia()`.
+> Streaming costs TTFB on a page that is mostly shell, so it is a choice per route
+> rather than a global default.
 
 ## Page metadata: `<Head>` on the server
 

package/docs/queue.md

@@ -141,6 +141,37 @@ export class PruneDeletedContentJob extends Job {
 JobRegistry.register(PruneDeletedContentJob as never);
 ```
 
+### Renaming a job class
+
+A queued job is a **persisted reference to a class**. The payload in the database or in Redis
+carries a string, and the worker resolves the class by it — so a job enqueued yesterday is
+looked up by today's process. That makes the class name a compatibility surface, and renaming
+the class a silent data migration: jobs already in the queue under the old name stop resolving
+at the moment you deploy.
+
+It is invisible to a test suite, because a test enqueues and runs in the same process.
+
+Declare the stored name and the class is free to move:
+
+```ts
+import { Job } from "@zerotal/queue";
+
+export class SendWelcomeEmail extends Job {
+  // The name in the queue payload. Keep it when the class is renamed.
+  static override jobName = "SendWelcomeEmail";
+
+  async handle(): Promise<void> {}
+}
+```
+
+It defaults to the class name, so a job that says nothing behaves exactly as before. Declare it
+when you rename a job class, or ahead of time on jobs you expect to rename — it is the same
+tool `Migration.id` is for a migration's filename, and the same reason.
+
+**Drain before you rename, if you have not declared one.** A rename with jobs in flight and no
+`jobName` leaves rows the worker reports as an unknown job class; `zt queue:failed` lists them
+and `zt queue:retry` can replay them once the name matches again.
+
 ## Auto-registration
 
 You don't import or wire up your jobs anywhere. Any job class placed under

package/package.json

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