@zerotal/arch 1.11.1 → 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,93 @@ 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

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