@zerotal/arch 1.11.2 → 1.13.0

package/docs/changelog.md

@@ -27,6 +27,122 @@ 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.13.0 — 2026-08-31
+
+Three retirements, taken together on purpose. Each is a small migration, and three minors
+each asking an app to move costs more than one that asks properly — so this is one crossing
+and one `zt upgrade` run.
+
+```bash
+bun zt upgrade --to 1.13.0
+```
+
+### Removed — BREAKING
+
+- **Flow's `Component.client(…)`.** Use the `` this.$`…` `` tagged template.
+
+  This is a security fix wearing an ergonomics change's clothes, which is why it did not wait
+  for 2.0. `client()` took a **string** and queued it to be evaluated in the browser, so the
+  caller owned the escaping — and its own docblock had to warn _never interpolate unescaped
+  user input_. A method whose documentation has to tell you not to hold it that way is a
+  footgun with a label on. `$` is a tagged template, so every `${…}` is encoded as a JS
+  literal before it reaches the page.
+
+  ```ts
+  // before — escaping was yours to remember
+  this.client(`toast(${JSON.stringify(this.search)})`);
+
+  // after — encoded for you
+  this.$`toast(${this.search})`;
+  ```
+
+  The codemod rewrites a call whose argument is a single literal. **One whose argument is a
+  variable or a concatenation is reported rather than rewritten**: those are precisely the
+  ones the warning was about, and wrapping a finished string as `` $`${expr}` `` would encode
+  it as a string literal and stop running it as code. A codemod that quietly did that would
+  leave an app compiling, running, and no longer doing anything where it used to run a script.
+
+  Removing it also frees `client` as a property name on a component — the same benefit
+  removing `title` gave in 1.7.3.
+
+### Changed — BREAKING
+
+- **`LockDriver.extend()` is required.** Only affects a custom lock driver; all three
+  built-in drivers already implement it.
+
+  It shipped optional in 1.5.0 with `acquire(key, owner, ttl)` as the fallback, and that
+  fallback was correct only by coincidence. `acquire` happens to be an owner-guarded refresh
+  on every built-in driver, and nothing in the interface ever said it had to be — so a
+  third-party driver whose `acquire` takes a _free_ lock, which is the ordinary reading of
+  the word, would have had `refresh()` silently take a lock another holder owned. That is the
+  one thing a lock exists to prevent. Requiring the method turns an assumption the contract
+  never stated into something a driver has to answer.
+
+- **`routes:types` and `serve --dev` are retired**, in favour of `route:types` and `dev`.
+  Both are rewritten by the codemod.
+
+  `serve --dev` **fails with a message** rather than being ignored, and the flag is still
+  declared for that reason alone. Flag parsing runs non-strict, so simply deleting it would
+  have left `serve --dev` starting a plain server — no watcher, no rebuild, no explanation. A
+  retired flag that silently changes what a command does is worse than one that is still
+  there.
+
+### Added
+
+- **The `client-tagged-template` codemod**, which is what makes the first item above a
+  migration rather than a search.
+
+## 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 +217,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/flow/index.md

@@ -198,7 +198,7 @@ The names in use:
 | Rendering         | `render` `layout` `placeholder` `slot` `hasSlot` `child` `isInteractive`                                              |
 | Actions & state   | `bind` `validate` `resetValidation` `errors` `addError` `refresh` `$refresh` `$set` `cancelled` `signal`              |
 | Navigation        | `redirect` `redirectRoute` `redirectIntended` `currentUrl` `navigateCurrent`                                          |
-| Events & realtime | `dispatch` `dispatchSelf` `dispatchTo` `stream` `client` `$`                                                          |
+| Events & realtime | `dispatch` `dispatchSelf` `dispatchTo` `stream` `$`                                                                   |
 | Misc              | `flash` `download` `clearDurable`                                                                                     |
 
 Anything beginning with `_` is also framework-internal, as are the statics `durable`

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,20 @@ 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. Seven 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, the refusal to write a boolean into a text column in 1.12.0, and the removal of
+  Flow's `Component.client(…)` alongside two retired aliases in 1.13.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,143 @@ 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.12 to 1.13
+
+Three retirements in one crossing, deliberately together: each is a small migration, and
+three minors each asking an app to move costs more than one that asks properly. `zt upgrade`
+does the mechanical half.
+
+```bash fragment
+bun zt upgrade --to 1.13.0
+```
+
+### `Component.client(…)` is removed — use the `$` tagged template
+
+The reason this did not wait: `client()` took a **string** and queued it to be evaluated in
+the browser, so the caller owned the escaping. Its own docblock had to say _never interpolate
+unescaped user input_, which is a warning about a footgun rather than a design. `$` is a
+tagged template, so every `${…}` is encoded as a JS literal before it reaches the page.
+
+```ts fragment
+// in a component class body — before
+this.client(`$refs.titleInput.focus()`);
+this.client(`toast(${JSON.stringify(this.search)})`); // escaping was yours to remember
+
+// after
+this.$`$refs.titleInput.focus()`;
+this.$`toast(${this.search})`; // encoded for you
+```
+
+The codemod rewrites a call whose argument is a single literal. **A call whose argument is a
+variable or a concatenation is reported rather than rewritten**, because those are exactly the
+ones the security note was about — and wrapping the finished string as `` $`${expr}` `` would
+encode it as a string literal and stop running it as code. Read those and interpolate through
+`$` instead.
+
+Removing it also frees `client` as a property name on your components, the way removing
+`title` did in 1.7.3.
+
+### `LockDriver.extend()` is required
+
+Only affects a **custom lock driver**; the three built-in ones already implement it.
+
+It shipped optional in 1.5.0 with `acquire(key, owner, ttl)` as the fallback, and the fallback
+was correct only by coincidence: `acquire` happens to be an owner-guarded refresh on every
+built-in driver, and nothing in the interface said it had to be. A driver whose `acquire` takes
+a _free_ lock — the ordinary reading of the word — would have had `refresh()` silently take a
+lock another holder owned, which is the one thing a lock exists to prevent.
+
+Implement `extend(key, owner, ttlSeconds)`: push the deadline out, return `false` when the key
+is free or held by someone else.
+
+### `routes:types` and `serve --dev` are retired
+
+`route:types` and `dev` are the real names. The codemod rewrites both in scripts and CI config.
+
+`serve --dev` **fails loudly** rather than being ignored. The flag is still declared for exactly
+that reason: flag parsing is non-strict, so deleting it would have left `serve --dev` starting a
+plain server with no watcher and no message — a retired flag that silently changes what a
+command does.
+
+## 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.13.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -35,11 +35,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.11.2"
+    "@zerotal/core": "1.13.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "@zerotal/orm": "1.11.2"
+    "@zerotal/orm": "1.13.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": [