@zerotal/arch 1.11.2 → 1.12.0

package/docs/changelog.md

@@ -27,6 +27,57 @@ 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
@@ -101,6 +152,37 @@ which is the only thing between a user's prompt and a log that outlives the requ
 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

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.

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