@zerotal/arch 1.11.0 → 1.11.2

package/docs/ai.md

@@ -138,9 +138,28 @@ response.stopReason; // "end_turn" | "max_tokens" | "tool_use" | …
 
 Current Claude models **reject** `temperature`, `top_p`, and `top_k` with a 400 — a
 generic sampling parameter forwarded blindly fails every request. The Anthropic
-driver therefore drops `temperature` and warns once.
+driver drops `temperature` on those models and warns once.
 
-Reach for `effort` instead. It trades thoroughness against cost and latency:
+**On models that accept it, it is sent.** The 4.6 and 4.5 generations take sampling
+parameters perfectly well, and there the configured or per-request `temperature`
+reaches the API. Ask `modelCapabilities(model)` if you want to know which you are on:
+
+```ts
+import { modelCapabilities } from "@zerotal/ai";
+
+const caps = modelCapabilities("claude-haiku-4-5");
+// { sampling: true, effort: false, thinking: "budget" }
+```
+
+That table is also what keeps the driver from sending a model something it rejects.
+`effort` is a 400 on the 4.5 generation, and those models want an explicit thinking
+budget rather than the adaptive form — so the driver builds a different request for
+them rather than one request for everything. Models it does not recognise are treated
+as current generation, because the ones that differ are a closed set that ages out
+while new models keep arriving.
+
+Reach for `effort` where the model has it. It trades thoroughness against cost and
+latency:
 
 | Effort   | Use it for                                               |
 | -------- | -------------------------------------------------------- |
@@ -150,6 +169,18 @@ Reach for `effort` instead. It trades thoroughness against cost and latency:
 | `xhigh`  | Hard coding and agentic tasks                            |
 | `max`    | When correctness matters more than the bill              |
 
+### The thinking stream
+
+A streamed `thinking` chunk carries the model's reasoning as it happens. The API
+**omits that text by default** on the current generation, so the driver asks for it:
+`drivers.anthropic.thinkingDisplay` defaults to `"summarized"`.
+
+Set it to `"omitted"` to get the API's own default back. The thinking happens — and is
+billed — either way; the setting only decides whether you are shown it. Before 1.11.2
+the driver never asked, so the documented `thinking` chunk fired forever with
+`text: ""` and no error, and a "thinking…" view built against the 4.6 models stopped
+working when their users moved to 5 without anything saying so.
+
 ### Streaming
 
 ```ts fragment
@@ -531,6 +562,8 @@ sections above; this is the index.
 | `modelPrice`             | The price for a model, or `undefined` when we have none.                     |
 | `estimateCost`           | Estimated USD for one request's usage. Returns 0 for an unpriced model.      |
 | `modelRejectsSampling`   | Whether a Claude model rejects `temperature` / `top_p` / `top_k` with a 400. |
+| `modelCapabilities`      | What a model accepts: sampling, `effort`, and which thinking shape.          |
+| `ModelCapabilities`      | The three answers `modelCapabilities` returns.                               |
 
 ### Spend and statistics
 

package/docs/changelog.md

@@ -27,6 +27,166 @@ 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.2 — 2026-08-31
+
+`@zerotal/ai` is `stable`, and the release that promotes it is the one that fixes five
+bugs its first production users found. That ordering is the point: a `stable` promise
+about an API nothing has pushed against is a promise nobody has tested.
+
+Also here: two gates that were not doing their job, one of which had let two releases
+publish over a red build.
+
+A patch. Nothing here breaks — `@zerotal/ai`'s surface was narrowed _before_ the label,
+while narrowing was still free.
+
+### `@zerotal/ai` — the review, answered
+
+The package shipped `experimental` with a stated precondition — _it graduates in the
+release after its first real users_ — and a review date of 1.11.0 enforced by the
+package linter rather than by a promise. Its first production users, running it against
+Anthropic, sent a field review of the driver. So the precondition was met rather than
+waived, and the answer is **promote**.
+
+**Fixed, all from that review:**
+
+- **Sonnet 5 was priced as Sonnet 4.6** — 3/15 rather than 2/10, 50% high. The same
+  table feeds `limits.perRequestUsd` and `perDayUsd`, so an app on that model was
+  refused requests comfortably inside its budget by an error that said "spend limit"
+  and sent it to its config rather than to the row. `AiSpendLimitError` now quotes the
+  rate it priced with and names `registerModelPrice()`, so a wrong table is legible
+  from the refusal and correctable without waiting for a release.
+
+- **`effort` and `thinking` are model-aware.** Both went on every call. `effort` is a
+  400 on the 4.5 generation and those models want an explicit thinking budget rather
+  than the adaptive form — so the package listed `claude-haiku-4-5` in its pricing
+  table while the driver could not successfully call it. `modelCapabilities()` answers
+  what a model takes, and the driver builds the request that model accepts.
+
+- **`temperature` never reached the API, on any model.** Not in the review — it turned
+  up while testing the item below. The driver warned about dropping `temperature` and
+  had no branch that set it, so the configured default and `AiRequest.temperature` were
+  both inert everywhere, including on the models that accept them. The old predicate
+  warned for almost every model, which is exactly what made the silence look deliberate
+  on the few it did not.
+
+- **The streamed `thinking` chunk was always empty.** The API omits thinking text by
+  default on the current generation, so a documented chunk type fired forever with
+  `text: ""` and no error — and a "thinking…" view built against the 4.6 models, where
+  it defaulted on, stopped working when users moved to 5 with nothing to say so.
+  `drivers.anthropic.thinkingDisplay` defaults to `"summarized"`.
+
+- **An app with no AI configured now boots.** `AiConfig` threw when no driver was
+  declared and threw again on an empty `apiKey`, so a deployment with no key could not
+  express itself either way. One app declared an Ollama server it did not run purely to
+  satisfy the validator, with a comment explaining that the config was lying. "AI is
+  off" is a coherent deployment and is now expressible; the first call raises
+  `AiDriverUnavailableError`, whose `transient` is already `false`.
+
+- **`countTokens` returns `null` where a provider cannot count**, rather than `0`. Only
+  Anthropic has a counting endpoint, and `0` is also a real count for an empty prompt.
+
+**How it was promoted**, because the order is the part that matters:
+
+The surface was narrowed **first** — narrowing after `stable` is itself a breaking
+change. `toSchema`, `strippedConstraints`, `resetSpend` and `resetStats` are `@internal`
+now: still exported, so nothing breaks at runtime, but no longer promised.
+`translateSchema` stayed public despite having no caller outside the package, for the
+same reason `AiDriver` is public — the point of a driver contract is that someone else
+implements it, and implementing structured output means translating a schema.
+`AiDelivery` stayed too, being the element type of `recentGenerations()`.
+
+Then the two modules it would have been embarrassing to freeze untested: the SSE
+parser, which reads a remote provider's framing off the network, and prompt redaction,
+which is the only thing between a user's prompt and a log that outlives the request.
+Both hold up — the parser reassembles a frame whose terminator is split across chunks
+and a UTF-8 sequence cut mid-character.
+
+### Fixed — the gates
+
+- **The release workflow ran three checks; the pull-request workflow ran fifteen.** So
+  every convention, surface and documentation gate guarded the cheap, reversible action
+  and not the permanent one. 1.11.0 and 1.11.1 both published over a CI that had been
+  red since the first of them, and nothing in the release objected, because nothing in
+  the release looked. `release.yml` now runs the same set.
+
+- **One failing check hid eleven others.** When the `@zerotal/ai` review fell due, the
+  package-conventions step failed and every later step in that job was skipped —
+  reported as "skipped", which reads like "not applicable" rather than "never ran".
+  Each check is now guarded so it reports its own result.
+
+## 1.11.1 — 2026-08-31
+
+Two things the framework could not do, both reported by teams who had already
+worked around them.
+
+A patch, not a minor: nothing here breaks. Under
+[the versioning scheme](/docs/upgrade#versioning) a minor is reserved for a
+breaking change and a patch carries everything else, features included — so this
+is safe to take from any 1.11.x.
+
+### Added
+
+- **`zt version`** — which Zerotal, which Bun, which app.
+
+  ```
+  Zerotal  1.11.1
+  Bun      1.3.14
+  App      my-app 0.1.0
+  ```
+
+  It was an unknown command, so the version had to be dug out of `package.json` or
+  `node_modules` — both of which report what is _installed_ rather than what is
+  _running_, and those differ for any process that has been up since before an
+  upgrade. It reports the running one.
+
+  `--version` and `-v` answer earlier still, ahead of the runtime check, the config
+  load and the app import, because those are the things someone is asking the version
+  _about_: a config that no longer validates and an app that will not boot are the two
+  moments the question stops being idle. A version flag that only works when
+  everything else already works answers a question nobody has.
+
+  Add `--json` for a script, and prefer `zt --version --json` over
+  `zt version --json` there — the application's boot log is written to stdout, so the
+  second form puts a log line ahead of the JSON while the first never boots at all.
+  The output carries no colour, unlike every other command's, because it gets pasted
+  into bug reports and piped into parsers more than it is read on a terminal.
+
+- **`MailMessage.header()` and `MailPayload.headers`** — set a header the mail driver
+  does not build itself.
+
+  ```ts
+  new MailMessage()
+    .subject("Your weekly digest")
+    .header("List-Unsubscribe", `<https://app.test/unsubscribe/${token}>`)
+    .header("List-Unsubscribe-Post", "List-Unsubscribe=One-Click");
+  ```
+
+  `MailPayload` had `to`, `from`, `subject`, `text`, `html`, `cc`, `bcc`, `replyTo`
+  and `attachments`, and no way to add anything else — so a team that wanted
+  `List-Unsubscribe` had to patch a vendored copy of the package, and shipped a footer
+  link instead.
+
+  Those are not substitutes for one another. Gmail and Yahoo draw their native
+  unsubscribe control from the header, and a recipient who cannot find a control marks
+  the message as spam instead — a judgement that attaches to the sending domain and
+  degrades delivery of everything else it sends, including the mail people asked for.
+  Send `List-Unsubscribe-Post` alongside it: alone, the first leaves a link to follow,
+  and only the pair produces the one-click control both providers now expect.
+
+  Wired through all three drivers. SMTP writes them into the message, Resend sends
+  them as the API's `headers` object, and the log driver prints them — that last one
+  deliberately, because the reason to set a header is that a mail client does
+  something with it, and the log driver is where that gets checked before anything is
+  sent for real.
+
+  Names the drivers build themselves are refused rather than sent twice: a second
+  `Subject` is an ambiguous message, not an override, and which copy a client believes
+  is its own business. The list is exported as `RESERVED_MAIL_HEADERS`, with
+  `resolveHeaders()` beside it for anyone writing a custom transport. CR and LF in a
+  value are folded to a space — left raw they end the header and let the remainder be
+  read as further headers, which is how a `Bcc` arrives courtesy of whoever supplied a
+  tracking ID.
+
 ## 1.11.0 — 2026-08-30
 
 Two production reports, from teams taking apps live on 1.9.0 — one shipping a

package/docs/commands.md

@@ -310,6 +310,7 @@ Packages register their own — see
 
 | Command                | Description                                            |
 | ---------------------- | ------------------------------------------------------ |
+| `bun zt version`       | Show the Zerotal, Bun and app versions                 |
 | `bun zt route:list`    | List all registered routes with methods and middleware |
 | `bun zt route:types`   | Write `types/routes.generated.ts` (`--check` in CI)    |
 | `bun zt doctor`        | Check the app for silent misconfigurations             |
@@ -317,6 +318,36 @@ Packages register their own — see
 | `bun zt lint:packages` | Check every workspace package against convention rules |
 | `bun zt upgrade`       | Apply the codemods for a version upgrade               |
 
+#### Which version am I on?
+
+`bun zt version` prints the framework, the runtime and the app:
+
+```
+Zerotal  1.11.0
+Bun      1.3.14
+App      my-app 0.1.0
+```
+
+It reports the version that is **running**, which is not always the version that is
+installed — a long-running server holds the code it booted with, so an upgrade lands
+on disk without reaching it.
+
+`--version` and `-v` answer the same question without booting the application:
+
+```bash
+bun zt --version
+bun zt --version --json     # for a script
+```
+
+Prefer the flag form in scripts, for two reasons. It still answers when the app does
+not boot — a config that no longer validates is exactly when you want to know which
+version you are on. And it is the form whose output can be piped: the application's
+boot log is written to stdout, so `bun zt version --json` carries a log line ahead of
+the JSON, while `bun zt --version --json` never boots and emits nothing else.
+
+If `node_modules` contains a second Bun, the report names it. Nothing executes that
+copy — it arrives as a peer dependency — but it is the one an install would use.
+
 ### Upgrading between versions
 
 `bun zt upgrade --to <version>` applies the codemods a version gap calls for —

package/docs/notifications.md

@@ -390,6 +390,47 @@ async toMail(_n: Notifiable): Promise<MailMessage> {
 }
 ```
 
+#### Custom headers, and the unsubscribe button
+
+`header(name, value)` sets a header the driver does not build itself. The one this
+exists for is `List-Unsubscribe`:
+
+```ts fragment
+// in a Notification
+toMail(n: Notifiable): MailMessage {
+  return new MailMessage()
+    .subject("Your weekly digest")
+    .line("Here is what happened this week.")
+    .header("List-Unsubscribe", `<https://app.test/unsubscribe/${n.unsubscribeToken}>`)
+    .header("List-Unsubscribe-Post", "List-Unsubscribe=One-Click");
+}
+```
+
+Gmail and Yahoo draw their native unsubscribe control — the one beside the sender's
+name, not the one in your footer — from that header, and there is no other way to ask
+for it. Send both headers, not just the first: alone, `List-Unsubscribe` leaves the
+recipient a link to follow, and only the pair produces a control that resolves in one
+press. The URL must accept a `POST` with no body and unsubscribe on the spot, with no
+confirmation page.
+
+It is worth more than the footer link it duplicates. A recipient who cannot find the
+control marks the message as spam instead, and that judgement attaches to the sending
+domain and affects delivery of everything else it sends — including the mail people do
+want. The two paths out of a mailing list are not equivalent for the sender.
+
+Header names the drivers build themselves are refused rather than sent twice, because
+a second `Subject` is an ambiguous message rather than an override. Those names are
+`RESERVED_MAIL_HEADERS`, and the error names the `MailMessage` method to use instead
+where there is one. The check runs when you set the header, so the throw carries the
+stack of the code that wrote it rather than of a queue worker three hops away — and
+again in the driver, since a `MailPayload` can be built without ever passing through
+`MailMessage`.
+
+Values are folded to a single line: a CR or LF in a header value ends the header and
+lets the rest be read as further headers, which is how a `Bcc` gets added by someone
+who was only supposed to be supplying a tracking ID. Writing a custom transport?
+Call `resolveHeaders()` on the payload's headers and it does both checks for you.
+
 ### database
 
 Implement `toDatabase(notifiable)` returning a plain object. The notification is

package/docs/support-policy.md

@@ -111,32 +111,39 @@ has worn the label for a year is not being cautious, it is unowned. So each one
 below `stable` names the release by which it is reviewed, and the review has three
 outcomes — promote, keep with a new date and the reason, or withdraw.
 
-| Package       | Now            | Reviewed by |
-| ------------- | -------------- | ----------- |
-| `@zerotal/ai` | `experimental` | **1.11.0**  |
-
-`@zerotal/ai`'s date moved once, from 1.9.0, and the reason is the same one that made it
-experimental in the first place: **it graduates in the release after its first real users, and
-it has not had them yet.** Promoting on a date rather than on evidence is how a label becomes
-decoration — a `stable` promise is only worth making about an API that something has pushed
-against.
-
-The date is a forcing function, not a prediction. It moved once; a second move needs a better
-reason than the first, or the honest answer is to withdraw the package rather than keep
-re-dating it. Its surface triage and the tests for its SSE parser and prompt redaction are worth
-doing meanwhile, and are tracked separately — they improve the package whichever way the review
-goes, and they are what would otherwise turn the deadline into a scramble.
+Nothing is below `stable` today. The table that lived here is empty, which is the
+outcome the mechanism is for rather than the absence of one — it is how the review
+looks when every date has been answered.
+
+`@zerotal/ai` was the last entry, `experimental` and due by 1.11.0. It was promoted in
+1.11.2, and the precondition it carried was met rather than waived: it graduates in the
+release after its first real users, and its first production users sent a field review
+of the driver against Anthropic. That review is why the promotion is worth anything —
+five bugs came back with it, and a `stable` promise about an API nothing has pushed
+against is a promise nobody has tested.
+
+The order was deliberate. Its surface was narrowed **before** the label, because
+narrowing after `stable` is itself a breaking change: `toSchema`, `strippedConstraints`,
+`resetSpend` and `resetStats` are `@internal` now. `translateSchema` stayed public
+despite having no caller outside the package, for the same reason `AiDriver` did — the
+whole point of a driver contract is that someone else implements it, and implementing
+structured output requires translating a schema. Then its two riskiest modules were
+tested: the SSE parser, which reads a remote provider's framing off the network, and
+prompt redaction, which is the only thing between a user's prompt and a log that
+outlives the request.
 
 `@zerotal/arch` held `beta` with the same date, was reviewed ahead of it, and is
 `stable` — the release that carried the promotion is the one its
-[changelog](/docs/changelog) names. Its surface was narrowed first — the writers behind
-`arch:install` are `@internal` now, because they had no caller outside the package
+[changelog](/docs/changelog) names. Its surface was narrowed first too: the writers
+behind `arch:install` are `@internal`, because they had no caller outside the package
 and freezing them would have promised the shape of `.mcp.json` writing to nobody.
 
-`@zerotal/ai` is not in the `zerotal` meta-package and nothing `stable` depends on
-it, so the cost of its label falling due is ours and not yours. Neither is `arch`,
-still: `arch:install` writes configuration and instruction files into a project,
-which is an opinion about someone's toolchain and stays their choice to invite.
+Neither `ai` nor `arch` is in the `zerotal` meta-package. `arch` stays out because
+`arch:install` writes configuration and instruction files into a project, which is an
+opinion about someone's toolchain and stays their choice to invite. `ai` stays out for
+its own reason rather than by omission: it is the only package with an optional peer
+on a vendor SDK, and pulling it into the meta-package would put a provider dependency
+in front of every app that installs `zerotal`, including the ones with no AI in them.
 
 That table used to be the whole of the commitment, which meant the version could
 sail past it and the only consequence would be this paragraph quietly becoming

package/package.json

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