@zerotal/arch 1.11.1 → 1.12.0

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,175 @@ 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.12.0 — 2026-08-31
+
+One change, deliberately alone: the minor exists to carry it.
+
+A field report from an app running in production found a feature flag reading as
+enabled for every record that had it turned off. Nothing errored, nothing logged, and
+the database was doing exactly what it had been asked to.
+
+### Changed — BREAKING
+
+- **A boolean written to a column declared to hold text is refused.**
+
+  A bare `@column()` resolves to `{ type: "string" }` — the right default for the
+  common case, and the wrong one for a boolean. A text column has text affinity, so
+  `false` was stored as the string `"0"`, and `"0"` is truthy in JavaScript. Every
+  `if (model.flag)` on such a column took the wrong branch for a stored `false`, on
+  every row, silently.
+
+  There is no correct coercion. `0` becomes `"0"`; `"false"` is truthy too. The value
+  cannot survive the round trip, so the only honest options were to refuse the write or
+  to keep letting a stored `false` read back as `true`. It now raises
+  `ColumnTypeError`, naming the property and the fix:
+
+  ```
+  [Zerotal ORM] Widget.active is declared as a `string` column and was given a boolean.
+  A text column stores that as "0"/"1", and "0" is truthy in JavaScript — so a stored
+  `false` would read back as true and every `if (…)` on it would take the wrong branch.
+  Declare the column's type instead: `@column("boolean")`.
+  ```
+
+  The decorator cannot pick for you: `declare active: boolean` erases the TypeScript
+  type at runtime, so the property looks identical to a decorator whether it holds a
+  boolean or a string. Declaring the type is the only signal there is — which is why
+  the mistake is worth refusing loudly rather than guessing at.
+
+  An explicit `@column({ type: "string", cast: "boolean" })` is still honoured. That is
+  someone stating what they meant; the guard is for the column that says nothing.
+
+### Before you upgrade
+
+- **Find the boolean properties whose `@column()` declares no type.** Nothing can find
+  them for you, for the reason above — a search of your models for a bare `@column()`,
+  read against the property types beside them, is the reliable way.
+- **The rows you already wrote are still text.** This stops new bad writes; it does not
+  migrate old ones. Those rows keep reading truthy until they are converted. The
+  [upgrade guide](/docs/upgrade#1-11-to-1-12) has the statement.
+
+### Added
+
+- **`ColumnTypeError`** — exported, so an app can catch it by class.
+
+## 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.
+
+#### **BREAKING** — `countTokens` can return `null`
+
+`Ai.countTokens()` and `AiDriver.countTokens()` return `number | null` rather than
+`number`. Only Anthropic has a counting endpoint; the other drivers returned `0`, which
+is also a real count for an empty prompt, so the old value was a number you could divide
+by and budget against without ever being told it meant "unsupported".
+
+```ts
+// before
+const tokens = await Ai.countTokens(prompt);
+if (tokens > 1000) shorten();
+
+// after
+const tokens = await Ai.countTokens(prompt);
+if (tokens !== null && tokens > 1000) shorten();
+```
+
+A custom `AiDriver` implementation compiles unchanged — returning `number` still
+satisfies `Promise<number | null>`. It is callers who need the check.
+
+**This should have been a minor.** It shipped in a patch, which the versioning scheme
+says cannot carry a break; see [the note in the upgrade guide](/docs/upgrade#1-11-2).
+
+#### **INTERNAL** — four `@zerotal/ai` exports left the promised surface
+
+`toSchema`, `strippedConstraints`, `resetSpend` and `resetStats` are `@internal`. They
+are still exported and still work, so nothing breaks — they are simply no longer
+covered by the compatibility promise, which is the narrowing that had to happen before
+the package could be promoted at all. Reach for `AiFake` where a test used `resetSpend`
+or `resetStats`; it is the seam built for that.
+
+### 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/orm/index.md

@@ -227,6 +227,34 @@ so it is a **string**. TypeScript cannot catch either — the decorator does not
 constrain the property type — so an annotation that disagrees compiles fine and
 fails at the first `.diffForHumans()` or arithmetic.
 
+#### A boolean needs `@column("boolean")`
+
+A bare `@column()` resolves to `{ type: "string" }` — the right default for the common
+case, and a trap for a boolean. Writing one to a text column is **refused**:
+
+```
+[Zerotal ORM] Widget.active is declared as a `string` column and was given a boolean.
+A text column stores that as "0"/"1", and "0" is truthy in JavaScript — so a stored
+`false` would read back as true and every `if (…)` on it would take the wrong branch.
+Declare the column's type instead: `@column("boolean")`.
+```
+
+There is no correct coercion, which is why it refuses rather than converting. SQLite
+gives a text column text affinity, so an integer `0` written there is stored as the
+string `"0"`, and `"0"` is truthy in JavaScript. `"false"` is truthy too. The value
+cannot survive the round trip in either direction, so the only honest options are to
+refuse the write or to let a stored `false` read back as `true` — which is what used to
+happen, on every row, with nothing in the app or the database registering a fault.
+
+The decorator cannot infer the type for you: `declare active: boolean` erases the
+TypeScript type at runtime, so the property looks the same to a decorator whether it
+holds a boolean or a string. Declaring the type is the only signal there is.
+
+If you genuinely want the text `"true"`/`"false"`, assign a string. If you want a
+boolean stored in a text column on purpose, say so with a cast —
+`@column({ type: "string", cast: "boolean" })` is honoured, because it is someone
+stating what they meant.
+
 ### Indexes and uniqueness
 
 Declare constraints on the column and schema generation emits them, so `migrate:generate` produces a schema with the guarantees your application depends on rather than a bare set of columns:
@@ -649,6 +677,15 @@ Type helpers exported from `@zerotal/orm`:
 | `UpdatePayload<T>`    | The shape accepted by `fill()` / `update()`.                        |
 | `DatabaseConfigShape` | The `config/database.ts` configuration type.                        |
 
+### Errors
+
+| Error                    | Thrown when                                                                                            |
+| ------------------------ | ------------------------------------------------------------------------------------------------------ |
+| `ModelNotFoundError`     | `findOrFail()` / `firstOrFail()` found no row.                                                         |
+| `MassAssignmentError`    | `fill()` / `create()` received an attribute the model's rules do not allow.                            |
+| `ColumnTypeError`        | A boolean was written to a column declared to hold text — see [above](#a-boolean-needs-columnboolean). |
+| `RelationNotLoadedError` | A relation was read without being loaded, under strict relation access.                                |
+
 ### Commands
 
 `@zerotal/orm` ships the migration, model, and seeding commands. Every one runs through `bun zt`:

package/docs/support-policy.md

@@ -75,10 +75,19 @@ 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. Four have shipped so far — the
+  own section in the Upgrade Guide. Six 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, and SQLite
-  foreign-key enforcement in 1.11.0.
+  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, and the refusal to write a boolean into a text column in 1.12.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`
+  to `stable`, and the reasoning that allowed it — the package was still
+  `experimental` when the change was made, earlier in that release — is not a
+  distinction anyone installing 1.11.2 can observe. What they get is a patch that
+  breaks. It is listed here rather than argued away, because a policy that quietly
+  excuses its own exceptions is not one you can plan against.
 - **Provenance:** packages are published with npm provenance, so you can verify
   a tarball was built by this repository's release workflow rather than someone's
   laptop.
@@ -111,32 +120,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/docs/upgrade.md

@@ -289,6 +289,85 @@ 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.11 to 1.12
+
+One breaking change, and it is the intended kind: a minor, announced, with the reason.
+
+**A boolean written to a text column is refused.** A bare `@column()` resolves to
+`{ type: "string" }`, so a boolean property decorated with one was stored as text —
+and a text column has text affinity, so `false` was stored as `"0"`, which is truthy
+in JavaScript. Every `if (model.flag)` on such a column took the wrong branch for a
+stored `false`, on every row, with nothing in the app or the database registering a
+fault. An app found it when a feature flag read as enabled for every record that had
+it turned off.
+
+```ts fragment
+// in a model class body — before, and silently wrong
+@column() declare active: boolean;
+
+// after
+@column("boolean") declare active: boolean;
+```
+
+There is no correct coercion: `0` becomes `"0"` and `"false"` is truthy too, so the
+value cannot survive the round trip. The write now throws `ColumnTypeError`, naming
+the property and the fix.
+
+### What to do before upgrading
+
+**Find your boolean properties whose `@column()` declares no type.** The decorator
+cannot find them for you — `declare active: boolean` erases the TypeScript type at
+runtime, so a bare `@column()` on a boolean is indistinguishable from one on a string
+until a value arrives. A search of your models for `@column()` with no argument, read
+against the property types beside them, is the reliable way.
+
+**The rows you already wrote are still text.** This release stops new bad writes; it
+does not migrate old ones. A column that has been holding `"0"` and `"1"` needs both
+the decorator fixed and the stored values converted — on SQLite,
+`UPDATE widgets SET active = CAST(active AS INTEGER)` after the column type is
+corrected. Until then those rows keep reading truthy, which is the behaviour you are
+upgrading to escape.
+
+**If a text column really should hold a boolean**, say so explicitly and it is
+honoured: `@column({ type: "string", cast: "boolean" })`. The guard is for the column
+that says nothing, not for every string column.
+
+## 1.11.2
+
+One breaking change, and it is in a release that should not have carried one.
+
+**`countTokens` returns `number | null`.** `Ai.countTokens()` and
+`AiDriver.countTokens()` used to return `number`, with `0` standing in for "this
+provider cannot count". Only Anthropic has a counting endpoint, and `0` is also a real
+count for an empty prompt — so the old return value could not tell you which it meant,
+and a budget built on it was quietly wrong for every other provider.
+
+```ts fragment
+// before
+const tokens = await Ai.countTokens(prompt);
+if (tokens > 1000) shorten();
+
+// after
+const tokens = await Ai.countTokens(prompt);
+if (tokens !== null && tokens > 1000) shorten();
+```
+
+A custom `AiDriver` needs no change — returning `number` still satisfies
+`Promise<number | null>`. Only callers do.
+
+**Why this is in a patch.** It was made while `@zerotal/ai` was still `experimental`
+and therefore outside the compatibility promise, in the same release that then promoted
+the package to `stable`. That ordering is real and it is not a distinction anyone
+installing 1.11.2 can observe: what arrives is a patch that breaks a build. The rule
+stands as written — a patch does not break — and this release is recorded as the
+exception rather than as a reinterpretation of it. See
+[the support policy](/docs/support-policy#releases-and-versioning).
+
+Everything else in 1.11.2 is additive. `@zerotal/ai`'s other surface change — `toSchema`,
+`strippedConstraints`, `resetSpend` and `resetStats` becoming `@internal` — leaves those
+exports working; they are no longer covered by the promise, which is different from
+being gone.
+
 ## The managed zt.ts
 
 `zt.ts` is framework-managed — the header says _do not modify_. If a release

package/package.json

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