@zerotal/arch 1.13.5 → 1.14.1

package/docs/ai.md

@@ -287,6 +287,48 @@ after a crash before another worker may take over". If the lock is ever lost the
 loop's signal aborts, because at that point somebody else may be doing the same work.
 See [Locking](/docs/lock) for the mechanism.
 
+## Prompt caching
+
+A long, stable prefix is worth caching: a cached read costs a tenth of an ordinary input
+token. A _write_ costs more than one, so caching something that changes every request is
+strictly more expensive than not caching it.
+
+**The system prompt is cached for you** when `cacheSystem` is on (the default) and it is
+long enough to be worth a breakpoint.
+
+**Anything else you mark yourself.** Put `cache: true` on the last message of the stable
+prefix — a retrieved document, a fixed few-shot block — and everything up to and including
+it is cached:
+
+```ts fragment
+await Ai.generate({
+  messages: [
+    { role: "user", content: policyDocument, cache: true },
+    { role: "user", content: question },
+  ],
+});
+```
+
+The marker goes on the **last** message of the prefix, not on every message in it: a
+breakpoint caches everything before it, so marking each one spends four breakpoints to
+describe one boundary. Anthropic allows four per request and the framework refuses a fifth
+by name rather than letting the provider return a 400 about a field you did not write.
+
+Before 1.14.1 only the system prompt could be cached, so a long document in the message
+history could not be — which is the case caching is most worth having for.
+
+### What it costs
+
+`estimateCost` prices a cache read at 0.1× input and a **5-minute** write at 1.25×. A
+**1-hour** write costs 2×, and the two are tracked separately in `AiUsage`
+(`cacheWrite1hTokens`, counted inside `cacheWriteTokens`) because one number cannot be
+priced two ways.
+
+Zerotal never requests a 1-hour cache, so that figure is `0` unless you reach past the
+driver with `providerOptions`. It used to be priced at 1.25× regardless, which
+underestimated by 37.5% — in the unsafe direction for a spend ceiling, since a limit that
+under-counts lets spend through rather than blocking it.
+
 ## Refusals
 
 A provider's safety classifiers can decline a request. That arrives as a **successful

package/docs/changelog.md

@@ -27,6 +27,119 @@ 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.14.1 — 2026-09-01
+
+Clearing the deferred list. Three of the four are fixed; the other two were sized and moved
+to 2.0 with the reasoning recorded, because deciding is also addressing.
+
+### Added
+
+- **Prompt-cache breakpoints on messages.** Caching reached exactly one place — the system
+  prompt — so a long stable document in the message history could not be cached, which is
+  the case caching is most worth having for.
+
+  ```ts
+  await Ai.generate({
+    messages: [
+      { role: "user", content: policyDocument, cache: true },
+      { role: "user", content: question },
+    ],
+  });
+  ```
+
+  The marker goes on the **last** message of the prefix, because a breakpoint caches
+  everything before it — marking each message spends four breakpoints describing one
+  boundary. Anthropic allows four, and a fifth is refused by name rather than surfacing as
+  a provider 400 about a field you never wrote.
+
+### Fixed
+
+- **A 1-hour cache write is priced at 2×, not 1.25×.** Every write was multiplied by the
+  5-minute rate, underestimating a 1-hour write by 37.5% — in the unsafe direction for a
+  ceiling, since a limit that under-counts lets spend through rather than blocking it.
+  `AiUsage.cacheWrite1hTokens` carries the split, read from the `cache_creation` breakdown
+  Anthropic returns when a 1-hour cache was used. Optional on the type, because a custom
+  driver constructs `AiUsage` and making it required would break every one for an
+  accounting detail their provider probably does not report.
+
+- **A command that declares `needsApp = false` no longer boots the application.**
+  `zt version`, `key:generate`, every `make:*` scaffolder and the gate commands paid for
+  providers, a database connection and a schedule registry they never touch — and could not
+  run when booting was the thing that was broken. A CLI you cannot reach when the app is
+  down is missing exactly when it is wanted.
+
+  Config is still bound, through the new `Application.bindConfig()`. "Does not need the
+  app" and "does not need config" are different claims, and only the first is true of a
+  scaffolder writing to a configured path.
+
+  It also makes `zt version --json` pipeable, which previously needed the `--version` form
+  to dodge the boot log on stdout.
+
+### Decided, not done
+
+Two entries on the 2.0 ledger were filed as alias retirements and are mass renames:
+
+- **`BaseModel` → `Model`** is **617 references across `api-surface.md` files and 354 in
+  non-test source.** `BaseModel` is the class's declared name, so TypeScript prints it into
+  every signature mentioning a model — retiring it means renaming the class and
+  regenerating every snapshot, which the breaking-change gate reads as hundreds of removals.
+  The "trivial" codemod in the ledger is the app-side rewrite, which is genuinely trivial
+  and already written; the framework side was never sized.
+- **Prefixing the 269 `@internal` exports with `_`** is the same shape, minus the classes
+  that [cannot be renamed at all](#1131--2026-08-31).
+
+Both move to 2.0 on the ledger's own rule — a break worth taking once, wanting one
+migration and one `zt upgrade` run rather than hundreds of app-visible type positions
+churned so there is one name instead of two. They should cross together, so an app pays for
+one rename pass rather than two.
+
+## 1.14.0 — 2026-09-01
+
+Rendering and the SSR endpoint become separate decisions. Small in practice — most apps
+change nothing — but it is a change to what a config flag does, so it takes a minor and
+says so.
+
+### Changed — BREAKING
+
+- **`inertia.ssr: true` no longer registers `POST /__ssr`.**
+
+  ```ts
+  // config/inertia.ts
+  export default InertiaConfig({
+    ssr: true, // server-render every first page load. Renders nothing else.
+    ssrEndpoint: true, // expose POST /__ssr, for a renderer outside this process
+  });
+  ```
+
+  **If you set `ssr: true` for server rendering, you need no change.** You keep exactly
+  that and stop exposing a route you were not using. Add `ssrEndpoint: true` only when
+  something outside the web process calls `/__ssr` — a separate renderer, a second host.
+
+  The endpoint exists because upstream Inertia runs on hosts with no JavaScript runtime:
+  PHP cannot import a `.tsx`, so it posts `{ component, props, url }` to a Node process and
+  gets `{ body, head }` back. That hop is forced by the host language, not chosen. Bun _is_
+  a JavaScript runtime, so [1.13.5](#1135--2026-09-01) made `ssr` import the component and
+  render it inline — no serialisation, no second process, no network.
+
+  So the endpoint solves a problem this framework does not have, and it stays only for the
+  case that is still real: deliberately moving render CPU off the web process. That is a
+  deployment choice, and it now has to be made rather than inherited.
+
+  Turning rendering on should not open a route that renders arbitrary components from POST
+  input, however well guarded. One switch, one thing — the same reasoning that separated
+  `secureHeaders: false` from the site gate in 1.13.3.
+
+### A note on what this costs
+
+Worth stating plainly, because it is easy to expect the opposite: **turning `ssr` on adds
+CPU to the web process.** Before 1.13.5 the flag rendered nothing, so there was no round
+trip to remove — a page load did no rendering at all. Now it renders every first load.
+
+The comparison where in-process rendering _is_ cheaper is against the way other frameworks
+do SSR: no HTTP hop, no JSON round trip of the whole page object, no second process to run
+and supervise. Against the framework's own previous behaviour, it is new work in exchange
+for HTML a crawler and a link preview can read.
+
 ## 1.13.5 — 2026-09-01
 
 **`inertia.ssr: true` server-renders now.** One config line, every page, no controller

package/docs/inertia/ssr.md

@@ -56,15 +56,30 @@ server renderer for the framework your app uses.
 client-rendered document is served instead, because taking a route down because an
 _optimisation_ failed would make `ssr: true` a liability rather than an improvement.
 
-## What `POST /__ssr` is for
+## What `POST /__ssr` is for, and why you probably do not want it
 
-`ssr: true` also registers it. It accepts `{ component, props, url }` and returns
-`{ body, head }` — the same contract as the Inertia Node SSR server — and it exists for
-an **external** caller: a separate renderer process, or a deployment that renders
-somewhere other than the web process.
+Set `ssrEndpoint: true` and the app exposes `POST /__ssr`, which accepts
+`{ component, props, url }` and returns `{ body, head }`.
 
-You do not need it for the switch above, which renders in-process. It is throttled and
-loopback-gated; see `ssrSecret` for reaching it from another host.
+That is the contract upstream Inertia uses, and it exists there for a reason that does not
+apply here: **PHP and Ruby have no JavaScript runtime**, so the web framework cannot import
+a `.tsx` and must hand rendering to a separate Node process. The HTTP hop is forced by the
+host language.
+
+Bun _is_ a JavaScript runtime. `ssr: true` imports the component and renders it inline, in
+the same process, with no serialisation and no network. So the endpoint solves a problem
+this framework does not have.
+
+What it is still good for is the one case that remains real: **deliberately moving render
+CPU off the web process**, onto another process or another host, on an app where rendering
+competes with request handling. Then the hop is the point rather than the cost.
+
+It is throttled, answers a 404 to anything that is not loopback, and takes `ssrSecret` for
+a renderer on another host.
+
+> **`ssr: true` does not register it, since 1.14.0.** It used to, which meant turning
+> rendering on opened a route the app never asked for. See
+> [the upgrade note](/docs/upgrade#1-13-to-1-14).
 
 ## Streaming SSR — a different question
 

package/docs/support-policy.md

@@ -75,12 +75,13 @@ 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. Seven have shipped so far — the
+  own section in the Upgrade Guide. Eight 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.
+  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
   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`

package/docs/upgrade.md

@@ -296,6 +296,34 @@ 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.13 to 1.14
+
+One breaking change, and it is small in practice.
+
+**`inertia.ssr: true` no longer registers `POST /__ssr`.** Rendering and the endpoint are
+separate decisions now:
+
+```ts fragment
+// config/inertia.ts — before
+export default InertiaConfig({ ssr: true }); // rendered, and opened the route
+
+// after
+export default InertiaConfig({ ssr: true }); // renders, and opens nothing
+export default InertiaConfig({ ssrEndpoint: true }); // opens the route, for an
+// external renderer
+```
+
+**Most apps need no change.** If you set `ssr: true` for server rendering — which is what
+the option is for — you keep exactly that, and you stop exposing a route you were not
+using. The endpoint had no in-process caller before 1.13.5, so an app that set the flag was
+getting the route and nothing else.
+
+**Add `ssrEndpoint: true` only if something outside the web process calls `/__ssr`** — a
+separate renderer, a second host. If you are not running one, you were not using it.
+
+Why split them: turning rendering on should not open a route that renders arbitrary
+components from POST input, however well guarded. One switch, one thing.
+
 ## 1.12 to 1.13
 
 Three retirements in one crossing, deliberately together: each is a small migration, and

package/package.json

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