@zerotal/arch 1.14.0 → 1.14.2

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,105 @@ 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.2 — 2026-09-01
+
+**`bun run dev` was broken in every app scaffolded since 1.13.0.** Take this one.
+
+Found by starting the adoption release the obvious way — scaffolding a fresh app and
+walking the first-run path as a newcomer would, rather than reasoning about it.
+
+### Fixed
+
+- **The scaffold templates shipped a retired command.** Every template's `package.json`
+  carried `"dev": "bun zt.ts serve --dev"`, and `serve --dev` was retired in
+  [1.13.0](#1130--2026-08-31) — deliberately failing loudly rather than silently starting a
+  plain server with no watcher. So the first command a new user runs exited 1 and told them
+  to use something else.
+
+  Retiring an alias meant updating the runner, the documentation and the `zt upgrade`
+  codemod. It did not occur to me to update the thing that _writes new apps_, which is the
+  one place a retired form is guaranteed to keep appearing.
+
+  A test now checks the scaffolder against the codemod's own list of retired forms, so what
+  generates apps cannot fall behind what migrates them. It is driven by the codemod rather
+  than a second list, because two lists disagree.
+
+- **`zt upgrade` did not rewrite `zt.ts serve --dev` either.** The codemod anchored on `zt`
+  followed by whitespace, matching `zt serve --dev` and missing `bun zt.ts serve --dev` —
+  the form in every scaffolded `package.json`. So an app running `zt upgrade` to migrate off
+  the alias was told there was nothing to do, on the file that needed it most.
+
+  Worth naming as its own failure: the first version of the new scaffolder test passed with
+  the bug deliberately planted, because it was driven by that same pattern. A gate is only
+  worth what it catches, and the way to know is to break the thing on purpose and watch it
+  fail.
+
+## 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

package/package.json

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