@zerotal/arch 1.7.2 → 1.7.3

package/docs/about.md

@@ -43,7 +43,7 @@ a theme.
 
 ### 1. Bun-native, source-only
 
-Zerotal runs **only on Bun** (≥ 1.1) and leans on Bun's APIs throughout — `Bun.sql`
+Zerotal runs **only on Bun** (≥ 1.3.14) and leans on Bun's APIs throughout — `Bun.sql`
 for the database, `Bun.CryptoHasher` for hashing, `Bun.build` for bundling. Because
 Bun runs and type-strips TypeScript natively, packages ship as **`.ts` source with no
 compiled `dist/`**. You always read real source and get accurate types; there's
@@ -660,9 +660,9 @@ The [README](../README.md) has a package-by-package table with links.
   scaffolding, migrations, the dev server, the worker, and tests all run through it.
 - **No build, ever.** `bun run dev` / `bun test` / `bun run typecheck`. No compile
   step to remember.
-- **Reference apps are the best teacher.** Full working apps under `apps/` exercise the
-  framework end-to-end — a Flow-based finance app and a Flow + Auth + ORM starter
-  are the most complete real-world examples. Read them alongside the docs.
+- **Starters are the fastest way in.** `bun create zerotal my-app` scaffolds a working
+  app from one of six starters — `api`, `admin`, `flow`, `react`, `vue`, or `minimal`.
+  Read the generated code alongside the docs.
 - **Conventions are documented, not magic.** When something "just works" (a model you
   never registered, a policy suddenly enforced), [Conventions](/docs/conventions)
   explains exactly what the framework discovered and why.

package/docs/changelog.md

@@ -17,12 +17,68 @@ summary across the suite.
 Each version lists changes under three headings:
 
 - **Added** — new features and APIs (safe to adopt incrementally).
-- **Changed** — behavior changes; **breaking** ones are called out explicitly and
-  appear only in major releases.
+- **Changed** — behavior changes; **breaking** ones are called out explicitly, in
+  bold, as **BREAKING**.
 - **Fixed** — bug fixes.
 
-Patch and minor releases are backward compatible. Before taking a **major** release,
-read its section here and apply each migration note.
+Breaking changes belong in major releases, and while the 1.x line is young they may
+also land in a minor or a patch — always labelled, always with migration steps. Read
+the section for every version you cross and apply its migration notes, not only the
+majors. [Releases and versioning](/docs/support-policy#releases-and-versioning) explains
+when that carve-out ends.
+
+## 1.7.3 — 2026-08-20
+
+Two fields that accepted input and threw it away, and a CI job that was testing nothing.
+
+### Fixed
+
+- **A boolean column could not hold a boolean on PostgreSQL.** `table.boolean()` compiled to
+  `INTEGER` on every engine — right for SQLite, which has no boolean type, and rejected by
+  PostgreSQL, which has a real one:
+
+  ```text
+  column "active" is of type integer but expression is of type boolean   (42804)
+  ```
+
+  Every insert of `true` failed, and so did every `where("active", true)`. The storage type
+  now comes from the dialect, as the auto-increment column already did. SQLite and MySQL are
+  unchanged — MySQL's `BOOLEAN` is a synonym for `TINYINT(1)` and `INTEGER` takes 0/1 either
+  way, so there was nothing broken there to fix.
+
+  **Existing PostgreSQL tables keep their integer columns.** New tables get `BOOLEAN`; a table
+  already created needs an `ALTER` if you want the column converted:
+
+  ```sql
+  ALTER TABLE posts ALTER COLUMN active TYPE boolean USING active <> 0;
+  ```
+
+- **A bound password field discarded every keystroke.** Flow's client-writable set was
+  `fillable` minus `hidden`, which conflates two allow-lists answering different questions:
+  `fillable` governs what may be _written_, `hidden` governs what may be _shown_. A password
+  is in both, so subtracting made it unwritable — `<input type="password"
+value={this.user.password} blur />` accepted typing and dropped it on arrival.
+
+  `hidden` is no longer subtracted. It is still never sent: the stored hash does not leave the
+  server and the field arrives empty. A hidden value **the client supplied** survives until
+  save; one **the server produced** is never echoed back, and a half-typed one is stripped
+  from the durable snapshot before it is persisted.
+
+### Changed
+
+- **The PostgreSQL CI job blocks merges.** It had been running the ORM suite beside a Postgres
+  container without connecting to it, so it reported success without testing anything. A smoke
+  suite now exercises schema DDL, identity columns, CRUD, type round-trips, row locks and
+  transaction rollback against a real PostgreSQL 16, and a failure fails the build. The
+  boolean defect above is what it found on its first real run.
+
+### Documented
+
+- **Flow pages take their model from the route, not from a query.** The docs opened every
+  model example by fetching the record in `onMount()`, which predates a route being able to
+  hand a component the record. `models.md` leads with the bound form; `lifecycle.md` no longer
+  presents the old id-plus-`onHydrate`-re-query as the correct pattern. The old shape still
+  works — it is simply two fields and a query doing what one field now does.
 
 ## 1.7.2 — 2026-08-18
 
@@ -50,7 +106,7 @@ saying so.
 - **Flow bundles the socket client into its runtime.** A page that declares a `socket:`
   listener is live with no script of your own. Flow apps own no bundle entry, so the contract
   used to be "publish `window.Socket` yourself" — and when you didn't, the listeners were
-  *silently inert*: no error, no warning, no subscription, so a live feature with no script
+  _silently inert_: no error, no warning, no subscription, so a live feature with no script
   looked exactly like a live feature that was never written. An app that needs a configured
   client still assigns `window.Socket` before the runtime loads and that one is used as-is; a
   page with no listeners opens no connection at all.
@@ -60,7 +116,7 @@ saying so.
 - **A patch no longer writes back into a file input.** A file input's `value` belongs to the
   user agent, and assigning anything but `""` throws `InvalidStateError`. The write was legal
   while the bound property was empty and threw on the very patch carrying an upload's result
-  — and the throw escaped the frame handler, so the DOM never updated *and* the action's ack
+  — and the throw escaped the frame handler, so the DOM never updated _and_ the action's ack
   never resolved. Since frames are chained per component, every later action queued behind a
   promise that would never settle: the page rendered correctly and ignored every click for
   the rest of its life.

package/docs/contributing.md

@@ -8,7 +8,7 @@ description: Get the Zerotal monorepo running locally and pass the checks your c
 Zerotal is a Bun-native monorepo of composable packages. This guide covers getting the
 repo running locally, the project layout, and the checks your change needs to pass.
 
-> **Warning** — Bun ≥ 1.1 is required. Node.js is not supported; Zerotal uses `Bun.sql`, `Bun.CryptoHasher`, `Bun.build`, and other Bun-native APIs throughout.
+> **Warning** — Bun ≥ 1.3.14 is required. Node.js is not supported; Zerotal uses `Bun.sql`, `Bun.CryptoHasher`, `Bun.build`, and other Bun-native APIs throughout.
 
 ## Getting set up
 
@@ -32,7 +32,7 @@ packages/        # the framework — one directory per @zerotal/* package
   auth/  cache/  queue/  …  # feature packages
   testing/       #   factories, fakes, test app harness
   create-zerotal/ #   the `bun create zerotal` scaffolder
-apps/            # example apps used for end-to-end testing and the docs site
+apps/            # applications in this workspace
   docs/          #   this documentation site
 docs/            # the markdown documentation (what you're reading)
 ```

package/docs/errors.md

@@ -77,6 +77,28 @@ The full set exported from `zerotal`:
 > and `ServiceUnavailableError(reason, retryAfter)` populate the `Allow` and
 > `Retry-After` response headers for you when you pass those arguments.
 
+## Errors the framework raises
+
+The errors above are the ones you throw. These the framework throws at you, and
+each is written to name the fix rather than only the symptom. Most surface at
+boot, before a request is ever served:
+
+| Class                        | `code`                       | Raised when                                                                                                                              |
+| ---------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `BootCheckError`             | `E_BOOT_CHECK_FAILED`        | The boot-time doctor found one or more wiring problems.                                                                                  |
+| `ConfigValidationError`      | `E_CONFIG_VALIDATION_FAILED` | Config validation refused a production boot, listing every fatal issue by namespace.                                                     |
+| `FacadeBindingMissingError`  | `E_FACADE_BEFORE_BOOT`       | A facade was used after boot but nothing provides its binding — almost always a `ServiceProvider` missing from `bootstrap/providers.ts`. |
+| `ContextOutsideRequestError` | `E_CONTEXT_OUTSIDE_REQUEST`  | `RequestContext` was read with no request in scope, such as from module-level code or a background task. Renders as a 500.               |
+
+`BootCheckError` carries the whole list rather than the first failure it hit. Its
+`failures` array holds one `BootCheckFailure` per culprit — the `token`, the
+`provider` that declared it in `static provides`, and the `reason` — so a single
+restart tells you everything there is to fix.
+
+These four are not re-exported from `zerotal`, because throwing them yourself is
+not the point. Catch one by class from `@zerotal/core/errors`, or match on `code`
+the way you would any other framework error.
+
 ## Custom exception classes
 
 Extend `ZerotalError` for domain errors, or `HttpError` for HTTP errors. The

package/docs/flow/components.md

@@ -489,25 +489,21 @@ A dropzone bound to an `@expose` property. Choosing a file POSTs the bytes to `/
 import { Component, expose, FileUpload, FileUploads, TemporaryUploadedFile } from "@zerotal/flow";
 
 export class AvatarPage extends Component.using(FileUploads) {
+  @locked user!: User; // /users/:user/avatar — the record, already found
   @expose photo: TemporaryUploadedFile | null = null;
-  @locked photoUrl: string = "";
-
-  override async onMount() {
-    const user = await User.find(this.userId);
-    this.photoUrl = user?.avatarUrl ?? "";
-  }
 
   @expose async save(): Promise<void> {
     if (!this.photo) return;
     const path = await this.photo.store("avatars"); // moves to permanent storage
-    await User.query().where("id", this.userId).update({ avatarUrl: path });
+    this.user.avatarUrl = path;
+    await this.user.save();
     this.flash("Avatar updated.", "success");
   }
 
   override async render() {
     return (
       <div class="space-y-4">
-        {this.photoUrl && <img src={this.photoUrl} class="h-24 w-24 rounded-full" />}
+        {this.user.avatarUrl && <img src={this.user.avatarUrl} class="h-24 w-24 rounded-full" />}
 
         <FileUpload bind={this.photo} accept="image/*" maxSize="5mb" />
 

package/docs/flow/decorators.md

@@ -42,18 +42,19 @@ Only `@expose` properties are two-way: the client can push updates back to the s
 
 Sent to the client for display, but the client cannot mutate it. Included in the snapshot so it survives WebSocket round-trips without re-loading from the database.
 
+An ORM model is the exception: only its id travels in the snapshot and the row is re-read on every round-trip, so what the page shows is always current. See [Models in Components](/docs/flow/models).
+
 A `value={this.x}` binding on a `@locked` property renders as a read-only display — not an editable field.
 
-Use `@locked` for data loaded in `onMount()` that the server controls: model results, user info, computed totals, child props from the parent:
+Use `@locked` for anything the server owns: a record the route resolved, results loaded in `onMount()`, computed totals, child props from the parent:
 
 ```tsx
 export class PostsPage extends Component {
+  @locked user!: User; // /users/:user — the record, already found
   @locked posts: Post[] = [];
-  @locked user: User | null = null;
   @locked total: number = 0;
 
   override async onMount() {
-    this.user = await User.findOrFail(this.userId);
     this.posts = await Post.query()
       .where("user_id", this.user.id)
       .where("status", "published")
@@ -65,7 +66,7 @@ export class PostsPage extends Component {
   override async render() {
     return (
       <div>
-        <h1>Posts by {this.user?.name}</h1>
+        <h1>Posts by {this.user.name}</h1>
         <p>{this.total} posts</p>
         <ul>
           {this.posts.map((p) => (
@@ -269,7 +270,8 @@ An `@expose`d method that runs on the server but **skips the re-render cycle**.
 }
 
 @expose @renderless async archivePost(): Promise<void> {
-  await Post.where("id", this.postId).update({ status: "archived" });
+  this.post.status = "archived"; // this.post came from the route
+  await this.post.save();
   this.redirect("/posts");
 }
 ```
@@ -307,6 +309,8 @@ async onOrderCancelled(payload: { id: number }): Promise<void> {
 }
 ```
 
+Both forms are a `ListenerName`: the event string itself, or a resolver handed the component instance that returns one.
+
 See [Events & Broadcasting](/docs/flow/events) for dispatch methods, targeting, broadcasting, and native event integration.
 
 ## The @reactive decorator
@@ -396,8 +400,8 @@ See [Layouts & Composition](/docs/flow/layouts#two-way-props) for the full `@mod
 | `@expose method`                                | Callable from the browser via WebSocket                               |
 | `@expose @renderless method`                    | Callable from browser; skips re-render cycle                          |
 | `@on("event") method`                           | Listens for cross-component events (auto-exposed)                     |
-| `@on("socket:channel,Event") method`              | Listens for real-time server broadcasts                               |
-| `@on((self) => "socket:…") method`                | Same, with the channel resolved per instance (record ids)             |
+| `@on("socket:channel,Event") method`            | Listens for real-time server broadcasts                               |
+| `@on((self) => "socket:…") method`              | Same, with the channel resolved per instance (record ids)             |
 | `@reactive prop`                                | Child prop; parent re-pushes on change, child re-renders              |
 | `@modelable prop`                               | Two-way child prop; writes from child flow back to parent             |
 
@@ -421,13 +425,13 @@ this.redirectIntended("/dashboard"); // back to where AuthMiddleware intercepted
 // Force onMount() to re-run this round-trip (useful for reloading stale data)
 this.refresh();
 
-// Update the document title in the browser tab
-this.title("Edit post — My App");
+// The document title is `static title` on the class, not an action — see Routing.
 
-// Run raw JavaScript in the browser after the DOM patch is applied
-this.client("$refs.titleInput.focus()");
-this.client("window.scrollTo({ top: 0, behavior: 'smooth' })");
-this.client(`$dispatch('toast', { message: 'Done!' })`);
+// Run JavaScript in the browser after the DOM patch is applied. `$` is a tagged
+// template, so interpolated values are encoded for you.
+this.$`$refs.titleInput.focus()`;
+this.$`window.scrollTo({ top: 0, behavior: 'smooth' })`;
+this.$`$dispatch('toast', { message: ${this.message} })`;
 
 // Trigger a file download in the browser
 this.download("report.csv", csvContent, "text/csv;charset=utf-8");

package/docs/flow/events.md

@@ -276,8 +276,8 @@ export class OrderDashboard extends Component {
 
 ### Channel name formats
 
-| Format                             | Channel type                            |
-| ---------------------------------- | --------------------------------------- |
+| Format                               | Channel type                            |
+| ------------------------------------ | --------------------------------------- |
 | `socket:channel,Event`               | Public channel                          |
 | `socket-private:channel,Event`       | Private channel (requires auth)         |
 | `socket-presence:room,joining`       | Presence channel — member joined        |
@@ -315,7 +315,7 @@ The resolver runs once per render, after `onMount()`, so it can read anything th
 loaded. If it throws — a field it reads is still null, say — that one listener is dropped and the
 page renders without it, rather than the render failing.
 
-Resolve the *narrowest* channel the reader is entitled to. A static `issues` channel with an
+Resolve the _narrowest_ channel the reader is entitled to. A static `issues` channel with an
 `if (payload.issueId !== this.issue.id) return` in the handler looks equivalent and is not: the
 broadcast still reaches every subscriber's browser, so every reader receives every issue's
 comment bodies and discards them after the fact.

package/docs/flow/index.md

@@ -139,7 +139,7 @@ component in the project is covered — the Flow scaffold already writes this:
 > is a type error rather than a wrong render. The two JSX runtimes produce different element
 > types: a view `FC` returns `SafeHtml` (`{ value }`) and Flow's JSX expects `HtmlNode`
 > (`{ html }`), so using one inside the other is `TS2786: 'Box' cannot be used as a JSX
-> component`. A shared component library has to target one runtime; share class-name constants
+component`. A shared component library has to target one runtime; share class-name constants
 > or plain strings across the two instead of components.
 
 ### Your first component
@@ -183,22 +183,26 @@ Router.flow("/counter", CounterPage);
 ### Reserved member names
 
 `Component` brings its own members, and a property of yours that collides with one is a
-type error. It is caught at compile time and the message is specific, but the name that
-trips people is `title` — an obvious field for a row representing a media item, a guide or
-a review, and taken by the page-title accessor.
+type error. It is caught at compile time and the message is specific, so the cost is the
+surprise rather than the failure — which is why the list is here.
+
+`title` used to be on it, and was the name that caught people most: an obvious field for a
+row representing a media item, a guide or a review. The document title is
+[`static title`](#the-page-title) now, so the instance name is yours.
 
 The names in use:
 
 | Group             | Names                                                                                                                 |
 | ----------------- | --------------------------------------------------------------------------------------------------------------------- |
 | Lifecycle         | `onBoot` `onMount` `onHydrate` `onDehydrate` `onRendering` `onRendered` `onUpdate` `onUpdating` `onUpdated` `onError` |
-| Rendering         | `render` `layout` `placeholder` `slot` `hasSlot` `child` `title`                                                      |
+| Rendering         | `render` `layout` `placeholder` `slot` `hasSlot` `child`                                                              |
 | 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` `client` `$`                                                          |
 | Misc              | `flash` `download` `clearDurable`                                                                                     |
 
-Anything beginning with `_` is also framework-internal, as is the static `durable`.
+Anything beginning with `_` is also framework-internal, as are the statics `durable`
+and `title`.
 
 If the natural name is taken, the usual fix is a more specific one — `headline`,
 `mediaTitle` — which often reads better than `title` did.

package/docs/flow/layouts.md

@@ -149,7 +149,7 @@ Flow assembles the outer document itself and emits `<html lang="en">`, and a `La
 change it. `head` injects into `<head>`; the `<html>` attributes are not reachable from a layout.
 
 For a localised app, put `lang` (and any locale-dependent class) on the layout's own wrapper element.
-Both are valid on a `div` and apply to every descendant, so the *content* is correctly marked up —
+Both are valid on a `div` and apply to every descendant, so the _content_ is correctly marked up —
 but the document still declares English to anything reading the root element, which is wrong for a
 screen reader announcing the page in the wrong voice:
 

package/docs/flow/lifecycle.md

@@ -94,11 +94,19 @@ Avoid expensive database queries in `onBoot()` — it fires on every round-trip,
 
 Runs once on the initial `GET` render, then is skipped on all subsequent WebSocket updates. It's the primary place to load data for the page.
 
-It receives the route `HttpContext` — the same argument a controller action gets — so a page on a dynamic segment reads its [route-model binding](/docs/routing#route-model-binding) straight off `ctx.params` instead of querying for it:
+A page on a dynamic segment needs no code here for the record it is about. A field of the model's type is [filled from the segment](/docs/flow/routing#path-parameters) before `onMount()` runs, so the query, the id field, and the 404 all belong to the route:
 
 ```typescript
-override async onMount({ params: { post } }: HttpContext<{ post: Post }>) {
-  this.post = post; // resolved by the router; a missing record 404s before this runs
+export class PostPage extends Component {
+  @locked post!: Post; // /posts/:post — nothing to load
+}
+```
+
+What `onMount()` is for is everything the URL does not carry. It receives the route `HttpContext` — the same argument a controller action gets — which is where the signed-in user lives, and `ctx.params` is still there for a segment no field claimed:
+
+```typescript
+override async onMount({ user }: HttpContext) {
+  this.canEdit = user?.id === this.post.authorId;
 }
 ```
 
@@ -106,21 +114,23 @@ The context is passed to `onBoot()` too, but only the initial `GET` populates `c
 
 ```typescript
 override async onMount() {
-  const [posts, user] = await Promise.all([
+  const [posts, drafts] = await Promise.all([
     Post.query()
       .where("status", "published")
       .orderBy("created_at", "desc")
       .limit(20)
       .get(),
-    User.findOrFail(this.currentUserId),
+    Post.query().where("status", "draft").count(),
   ]);
 
-  this.posts = posts;
-  this.user  = user;
-  this.total = posts.length;
+  this.posts  = posts;
+  this.drafts = drafts;
+  this.total  = posts.length;
 }
 ```
 
+Lists and counts are what belongs here — the things no route resolved and no parent passed down.
+
 To force `onMount()` to re-run during a WebSocket action — for example after creating a new record and wanting to reload the list — call `this.refresh()` inside the action:
 
 ```typescript
@@ -139,25 +149,30 @@ Runs on every WebSocket round-trip, immediately after state is restored from the
 
 ```typescript
 export class PostEditorPage extends Component {
-  @locked postId: number = 0; // persisted in snapshot
-  @transient post: Post | null = null; // NOT persisted — reset each round-trip
+  @expose post!: Post; // /posts/:post/edit — re-read from the row every round-trip
+  @transient wordCount = 0; // NOT persisted — derived again each time
 
   override async onHydrate() {
-    // Re-load the full Post model from the database using the persisted ID:
-    if (this.postId) {
-      this.post = await Post.findOrFail(this.postId);
-    }
+    await this.post.loadMissing(["author"]); // relations do not survive the round-trip
+    this.wordCount = this.post.body.split(/\s+/).length;
   }
 
   @expose async updateTitle(title: string): Promise<void> {
-    if (!this.post) return;
     await this.post.fill({ title }).save();
     this.flash("Title updated.");
   }
 }
 ```
 
-This is the correct pattern for holding live model instances on a component: persist only the ID in `@locked`, then re-query the model in `onHydrate()`. The model is always fresh from the database, never stale from a deserialized snapshot.
+> **This used to say to hold the id and re-query the model here.** A component could not hold a
+> model then, so `@locked postId` plus a `@transient post` re-fetched in `onHydrate()` was the
+> way to keep one fresh. It is no longer needed: a model held directly is [re-read from its row
+> on every round-trip](/docs/flow/models#freshness), which is the same guarantee with none of
+> the bookkeeping. The pattern still works — it is just two fields and a query doing what one
+> field now does.
+
+What is left for `onHydrate()` is the state a snapshot genuinely cannot carry: relations, which
+are not part of a re-read, and anything derived from them.
 
 ## Intercepting client writes
 

package/docs/flow/models.md

@@ -0,0 +1,284 @@
+---
+title: Models in Components
+description: Put an ORM model on a Flow component — what crosses the wire, what the client may change, and what stays on the server.
+---
+
+# Models in Components
+
+A Flow component can hold an ORM model directly. On a route that names one, it arrives loaded:
+
+```tsx
+import { Component, locked } from "@zerotal/flow";
+import { Post } from "@app/models/Post.ts";
+
+export class ShowPost extends Component {
+  @locked post!: Post; // /posts/:post — the record, already found
+
+  override async render() {
+    return <article>{this.post.title}</article>;
+  }
+}
+```
+
+There is no `onMount()`, because there is nothing to fetch. The router resolved `:post` before
+the component was built, and a field of that type receives the result — so the query, the
+`postId` field it would have needed, and the 404 handling all belong to the route rather than
+to this page. [Path parameters](/docs/flow/routing#path-parameters) covers what a segment
+binds to and how a model resolves by something other than its primary key.
+
+The other way a model arrives is from a parent that already has it, as a prop:
+
+```tsx
+<PostCard post={this.post} />
+```
+
+Either way the model is a model on the other side — not a plain object shaped like one — and
+everything below applies the same to both.
+
+Nothing has to be declared. A model travels under its table name — the one `@table("…")`
+sets, or the inflected default — which the app already declares and a minifier cannot mangle.
+On the way back it is found through the registry that `app/models` discovery populates, which
+is every model in the app.
+
+> **Fetching a model in `onMount()` is the older way of doing this**, from before a component
+> could hold one. It still runs, and it is still right for a record no route names and no
+> parent has — a list, a lookup keyed off something the URL does not carry. It is the wrong
+> shape for the record the page is _about_: that one the route already found.
+
+The decorator is the whole decision: **`@locked` for a model the page displays, `@expose` for
+one it edits.** Both put the model on the client; only `@expose` accepts anything back.
+
+## What crosses the wire
+
+The snapshot carries the model's **id** and the result of its `toJSON()` — the same
+serialisation your API responses use, honouring `visible`, `hidden` and `appends`.
+
+```ts
+@table("users")
+export class User extends BaseModel {
+  static fillable = ["name", "email", "password"];
+  static hidden = ["password"];
+}
+```
+
+`password` is never sent. Nothing else has to be configured for that: the model already
+declares its serialisation surface, and Flow uses it.
+
+> **`hidden` is a security control here.** On an API response an omitted column is a matter of
+> shape. On a component it is the only thing keeping a value out of the page. A snapshot is
+> signed, not encrypted — the browser can read every byte of it. Declare `hidden` (or
+> `visible`) on any model a component holds.
+
+A loaded relation is resolved the same way, through its own `toJSON()` — every model hides
+its own columns, however deep it sits.
+
+The id travels separately from the values, in the part of the snapshot a client write cannot
+reach. **Which record a component points at is not something the browser can change** — only
+the values on it, and only the ones below.
+
+## What the client may change
+
+Only `fillable`. Everything else is server-owned, whatever the browser sends:
+
+| Column                               | Sent to the client | Client may write |
+| ------------------------------------ | ------------------ | ---------------- |
+| `id` — the identity                  | yes                | no               |
+| `name` — fillable, not hidden        | yes                | **yes**          |
+| `role` — not fillable                | yes                | no               |
+| `password` — fillable **and** hidden | no                 | **yes**          |
+
+A model that declares no `fillable` is read-only in the browser. That is the ORM's default:
+it guards mass assignment until told otherwise, and a component does not widen it.
+
+A field outside that set is **ignored**, not rejected — a crafted payload does not become a
+server error. To refuse a value loudly instead, or to vet one before it lands, throw from
+[`onUpdating()`](/docs/flow/lifecycle#intercepting-client-writes).
+
+### Editing
+
+Bind to a field of an `@expose`d model and it is two-way:
+
+```tsx
+export class EditProfile extends Component {
+  @expose user!: User;
+
+  @expose async save(): Promise<void> {
+    if (this.user.name.trim().length < 2) {
+      this.addError("name", "Your name needs at least two characters.");
+      return;
+    }
+    await this.user.save();
+    this.flash("Saved");
+  }
+
+  override async render() {
+    return (
+      <form onSubmit={this.save}>
+        <input value={this.user.name} blur />
+        <span error={this.errors.name} />
+        <button>Save</button>
+      </form>
+    );
+  }
+}
+```
+
+`save()` writes only the columns that actually differ. The row was re-read a moment earlier
+(see [Freshness](#freshness)), so the model's idea of "unchanged" is the row as it is now, not
+the one the page was built from.
+
+A `@locked` model is display-only, and its fields are not bound: render them as text —
+`<p>{this.post.title}</p>` — rather than as an input. An input pointed at one accepts typing
+and sends nothing.
+
+### Validating a model's fields
+
+`this.validate()` rules are keyed by the component's **own** exposed properties, and a model's
+columns are not among them: `"user.name"` looks for a property with that name, finds nothing,
+and fails whatever the field actually holds. Two ways round it:
+
+- **Check in the action**, then `this.addError(field, message)` — as above. Right for a field
+  or two.
+- **Use a [form object](/docs/flow/forms)** for anything larger. It is the shape built for
+  validated multi-field editing, and it can carry values no column has: a confirmation field,
+  a current-password check, an upload.
+
+### Hidden fields are writable
+
+`hidden` governs what is _shown_, not what may be written. A password is the case that makes
+the difference: fillable because a user sets it, hidden because the stored hash must never
+reach the page.
+
+```tsx
+<input type="password" value={this.user.password} blur />
+```
+
+The stored hash is never sent, so the field starts empty. What the user types is held until
+they save — it travels back to the browser that produced it, and nowhere else. A value the
+_server_ set is never echoed, and a half-typed one is never written to the
+[durable store](/docs/flow/lifecycle).
+
+What reaches the database is a hash rather than what was typed, as long as the column is
+listed in the model's `hashable` — see [Password hashing](/docs/orm#password-hashing).
+
+## Relations
+
+A relation that is loaded when the page renders travels with the model, through its own
+`toJSON()`. It does not survive the round-trip:
+
+```tsx
+override async onMount(): Promise<void> {
+  await this.post.loadMissing(["author"]); // this.post came from the route
+}
+```
+
+That renders. **The next interaction has no `author`** — the re-read is a find by id, which
+fetches the row and not the relations that happened to be loaded around it. Reading it then
+throws the ORM's guard: `Relation "author" was accessed on Post without eager loading`.
+
+Load what an action needs, where it needs it:
+
+```ts
+@expose async approve(): Promise<void> {
+  await this.post.loadMissing(["author"]);
+  this.post.approved = true;
+  await this.post.save();
+  this.flash(`Approved — ${this.post.author.name} has been credited.`);
+}
+```
+
+When the page _displays_ the relation, load it once per round-trip in
+[`onHydrate()`](/docs/flow/lifecycle#re-deriving-state-after-hydration) instead. Rendering is
+the case worth watching: a template reading `this.post.author.name` works on the first paint
+and throws on every interaction after it.
+
+```ts
+override async onHydrate(): Promise<void> {
+  await this.post.loadMissing(["author"]);
+}
+```
+
+## Freshness
+
+The model is **re-read from the database on every round-trip**, by id. What the client holds
+is a rendering of a row, not the row.
+
+Two consequences worth knowing:
+
+- **Server-owned columns are always current.** If someone else changes `role`, the next
+  interaction shows the new value.
+- **Unsaved changes survive.** A change an action made without calling `save()` is restored
+  from the snapshot, so a half-filled field does not revert the moment something else happens.
+  Only the writable fields are restored; everything else comes from the fresh row.
+
+If two people edit the same record, the one who saves last wins. Flow does not add optimistic
+locking — add a version column and check it in `save()` if a record needs it.
+
+### A row that disappears
+
+The re-read is a `findOrFail`, and it applies the same scopes your own queries do. A record
+deleted — or soft-deleted — while a page holds it makes the next interaction fail: nothing is
+patched, and the browser console carries the error. So follow a delete with a navigation
+rather than leaving the prop pointing at a row that is gone:
+
+```ts
+@expose async destroy(): Promise<void> {
+  await this.post.delete();
+  this.redirect("/posts");
+}
+```
+
+## Collections
+
+An array of models is sent as ids and re-read with a single `whereIn` query:
+
+```tsx
+@locked posts: Post[] = [];
+```
+
+Collections are read-only on the client. Bind to a single model when you need to edit one.
+
+Two things follow from ids and one `whereIn`:
+
+- **Order does not travel.** The re-read carries no `order by`, so the order you loaded them
+  in is not guaranteed to come back. Sort where you render, or re-run the real query in
+  `onHydrate()`.
+- **Rows that vanish drop out quietly.** A `whereIn` returns what it finds, so a deleted
+  record leaves the array one shorter — unlike a single model, whose disappearance fails the
+  interaction.
+
+## What a round-trip costs
+
+Each model prop is one query per interaction, and each collection one more. That is the price
+of never showing a stale row, and for most pages it is the right trade. When it is not:
+
+- **[`@transient`](/docs/flow/decorators#the-transient-decorator)** keeps a value off the
+  client and out of the snapshot entirely — nothing is sent, and nothing is re-read.
+- **Hold an id and query it yourself** in `onHydrate()` when the query needs shaping the
+  re-read cannot do: eager loads, ordering, a scope. `@locked postId: number` plus one query
+  is the whole pattern.
+- **A [form object](/docs/flow/forms)** when the page is editing many fields — it edits a
+  plain object, and touches the database once, in your action.
+
+## Troubleshooting
+
+| What you see                            | What it means                                                        |
+| --------------------------------------- | -------------------------------------------------------------------- |
+| `No model maps to "posts"`              | The class is not in `app/models`, or its `@table` no longer matches. |
+| `Post has no table name`                | Give the class `@table("…")`.                                        |
+| `Relation "author" was accessed`        | It was loaded in `onMount()`, and this is a later round-trip.        |
+| An edited field never saves             | It is not in `fillable`, so the write was ignored.                   |
+| A field snaps back after an interaction | The same cause, seen from the page: the fresh row won the re-render. |
+| A password field empties itself         | The column is `hidden` but not `fillable`, so nothing was applied.   |
+
+## Next steps
+
+- [Decorators](/docs/flow/decorators) — `@expose`, `@locked` and the rest of the property
+  contract.
+- [Lifecycle](/docs/flow/lifecycle) — `onHydrate()`, `onUpdating()` and where per-round-trip
+  work belongs.
+- [Forms & Uploads](/docs/flow/forms) — form objects, which are the right shape for
+  multi-field editing and for anything a model cannot carry.
+- [Mass assignment](/docs/orm#mass-assignment) — `fillable`, `guarded`, `hidden` and
+  `visible`, which this page builds on.
+- [Relationships](/docs/orm/relationships) — eager loading, `load()` and `loadMissing()`.

package/docs/flow/performance.md

@@ -49,12 +49,12 @@ N of M Flow pages (75%) render through the runtime fallback instead of compiled
 
 Set `ZT_FLOW_COMPILE_LOG=1` to print what blocks each page. The common causes:
 
-| Blocker | Fix |
-| --- | --- |
-| `render()` with more than one `return` | Build the branches into a variable and return once |
-| A function call in a text child — including **`__()`** | See below |
-| An imported child component in `render()` (`<Header/>`) | Inline it, or accept the fallback |
-| `class={someLocalConst}` or a numeric-literal attribute (`rows={3}`) | Use a literal string |
+| Blocker                                                              | Fix                                                |
+| -------------------------------------------------------------------- | -------------------------------------------------- |
+| `render()` with more than one `return`                               | Build the branches into a variable and return once |
+| A function call in a text child — including **`__()`**               | See below                                          |
+| An imported child component in `render()` (`<Header/>`)              | Inline it, or accept the fallback                  |
+| `class={someLocalConst}` or a numeric-literal attribute (`rows={3}`) | Use a literal string                               |
 
 **`__()` is the one that matters most.** A translated template is a function call in a text child,
 so a page that translates a single string falls off the fast path — which in an app where `__()`

package/docs/flow/references.md

@@ -180,7 +180,7 @@ override async render() {
 
 > **The payload does not say which container took the drop.** The client reads `flow:sort` off the
 > container a child was dropped **into** and calls it `(key, index)` — so the destination is
-> encoded in *which method runs*, and nowhere else. For a single sortable list that is invisible.
+> encoded in _which method runs_, and nowhere else. For a single sortable list that is invisible.
 > For dragging **between** containers under one `sortGroup` it means one action per container:
 >
 > ```tsx
@@ -189,7 +189,7 @@ override async render() {
 > ```
 >
 > An arrow (`onSort={(k, i) => this.move("todo", k, i)}`) cannot stand in, because the attribute's
-> value is used as a method *name* rather than evaluated. `onSort` accepts the name as a string,
+> value is used as a method _name_ rather than evaluated. `onSort` accepts the name as a string,
 > so the handlers can come from a lookup table keyed by column, but they must be declared members.
 
 ### DOM utilities
@@ -197,7 +197,7 @@ override async render() {
 | You write         | Behaviour                                                    | Compiles to     |
 | ----------------- | ------------------------------------------------------------ | --------------- |
 | `teleport="body"` | Move the element to a CSS selector target (modals, tooltips) | `flow:teleport` |
-| `ref="name"`      | Name this element as `$refs.name` for `this.client()` calls  | `x-ref`         |
+| `ref="name"`      | Name this element as `$refs.name` for ``this.$`…` `` scripts | `x-ref`         |
 
 ### Alpine plugins
 

package/docs/flow/routing.md

@@ -426,15 +426,27 @@ export class DashboardPage extends Component {
 }
 ```
 
-For per-action dynamic titles, use `this.title()` inside an action:
+### The page title
+
+`static title` takes a string, or a function of the component:
+
+```typescript
+static title = "Posts";
+static title = (c: PostPage) => `${c.post?.title ?? "Loading"} — My App`;
+```
+
+The function form is resolved on the server for every render and every patch, so a title
+that depends on state follows it without an action doing anything:
 
 ```typescript
 @expose async loadPost(slug: string): Promise<void> {
   this.post = await Post.where("slug", slug).firstOrFail();
-  this.title(`${this.post.title} — My App`);
+  // the title updates with it — nothing else to call
 }
 ```
 
+Only the resolved string is sent to the browser; the function stays on the server.
+
 For per-render `<head>` content (meta tags, OG tags), use `<Head>` inside `render()`:
 
 ```tsx

package/docs/getting-started.md

@@ -11,7 +11,7 @@ provider.
 
 ## Requirements
 
-- **Bun** ≥ 1.1 — [install](https://bun.sh/docs/installation)
+- **Bun** ≥ 1.3.14 — [install](https://bun.sh/docs/installation)
 - A PostgreSQL, MySQL, or SQLite database (SQLite requires nothing extra)
 
 ## Create a new project
@@ -47,14 +47,14 @@ bunx create-zerotal my-app --yes            # take the defaults for anything uns
 bunx create-zerotal --help
 ```
 
-| Flag | |
-| ---- | --- |
-| `-t`, `--template <name>` | `api`, `admin`, `flow`, `react`, `vue`, `minimal` |
-| `--db <name>` | `sqlite`, `postgres`, `mysql` — API template only |
-| `-y`, `--yes` | Take defaults for anything not given; never prompt |
-| `--no-install` | Skip `bun install` |
-| `-h`, `--help` | Usage |
-| `-v`, `--version` | The scaffolder's own version |
+| Flag                      |                                                    |
+| ------------------------- | -------------------------------------------------- |
+| `-t`, `--template <name>` | `api`, `admin`, `flow`, `react`, `vue`, `minimal`  |
+| `--db <name>`             | `sqlite`, `postgres`, `mysql` — API template only  |
+| `-y`, `--yes`             | Take defaults for anything not given; never prompt |
+| `--no-install`            | Skip `bun install`                                 |
+| `-h`, `--help`            | Usage                                              |
+| `-v`, `--version`         | The scaffolder's own version                       |
 
 An answer that is missing and cannot be asked for is an error naming the flag
 that would supply it, and the exit code is non-zero — so a pipeline fails where

package/docs/i18n.md

@@ -15,7 +15,7 @@ The string you pass to `__()` is the English sentence, not a name for it:
 __("Email"); // not __("auth.email")
 ```
 
-English is the source language, so the source text *is* the key. That one
+English is the source language, so the source text _is_ the key. That one
 decision removes the `en.json` file, the naming argument, and the class of bug
 where a screen ships reading `auth.email` because somebody mistyped a key.
 
@@ -188,7 +188,7 @@ A component then calls it with no import and no hook:
 > TypeScript program, so `@zerotal/i18n`'s declaration already covers these call
 > sites; a second `var __` is a duplicate identifier, not an override.
 
-> **Note** — do not sync from `router.on("navigate")`. That event fires *after*
+> **Note** — do not sync from `router.on("navigate")`. That event fires _after_
 > the component swap, so the first render of a new page still carries the
 > previous locale's catalog — visible as one flash of the old language every time
 > someone switches.
@@ -295,7 +295,7 @@ returns a value listed in `supportedLocales` (otherwise `defaultLocale`):
 
 - **`query`** — useful for a one-off preview link (`?lang=fr`) or language
   switcher, but it doesn't persist. Put it first so it can override the others.
-- **`cookie`** — the choice that *sticks*. List it when you let users pick a
+- **`cookie`** — the choice that _sticks_. List it when you let users pick a
   language and persist it (see [Overriding the locale](#overriding-the-locale)).
 - **`accept-header`** — the visitor's browser preference; a sensible default when
   no explicit choice has been made. List it last as the fallback.

package/docs/routing.md

@@ -486,6 +486,17 @@ the checked signature above decorative.
 Typed names flow through the helpers built on `route()` too — `redirect().to()`,
 `Url.route()`, `Uri.route()`, and Flow's `redirectRoute()`.
 
+The types that checking is built from are exported from `zerotal/routes`, for
+when you write a helper that forwards to `route()` rather than calling it
+directly:
+
+| Type               | What it holds                                                                                                     |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------- |
+| `RouteTarget`      | The name a checked helper accepts: `RouteName` once the registry is generated, plain `string` before it.          |
+| `RouteArgs<N>`     | Everything `route()` takes after the name — params required only when the pattern has one, query always optional. |
+| `RouteParamValues` | The loose param bag the unchecked overload accepts.                                                               |
+| `RouteQuery`       | Query values. `null` and `undefined` entries drop out, and an array repeats the key.                              |
+
 ### route() in the browser
 
 `route()` works on the server with no setup: the application installs the table

package/docs/support-policy.md

@@ -49,11 +49,11 @@ course?", so this is it:
 
 ## Databases
 
-| Database   | Status                                                                                                                                                                                           |
-| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| SQLite     | Supported. The default; the full test suite runs against it on every merge.                                                                                                                      |
-| PostgreSQL | Supported, hardening. The ORM suite runs against a real Postgres in CI; remaining dialect gaps are being driven to zero before the job blocks merges.                                            |
-| MySQL      | Experimental. The ORM ships a MySQL dialect and the scaffolder can configure it, but no CI suite runs against a real MySQL server yet — treat it as unverified until it joins the tested matrix. |
+| Database   | Status                                                                                                                                                                                                                                                                                                                                 |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SQLite     | Supported. The default; the full test suite runs against it on every merge.                                                                                                                                                                                                                                                            |
+| PostgreSQL | Supported. A smoke suite runs against a real PostgreSQL 16 on every merge — schema DDL, identity columns, CRUD, type round-trips, row locks and transaction rollback — and the job blocks a merge when it fails. The bulk of the ORM suite still runs on SQLite, so coverage of the Postgres path is narrower than of the default one. |
+| MySQL      | Experimental. The ORM ships a MySQL dialect and the scaffolder can configure it, but no CI suite runs against a real MySQL server yet — treat it as unverified until it joins the tested matrix.                                                                                                                                       |
 
 Redis-backed drivers (cache, session, queue, broadcasting) build on
 `Bun.RedisClient` and are tested against the protocol surface it provides.
@@ -67,6 +67,14 @@ dependency order, from CI. Never mix versions across packages.
 - **Semantic versioning:** patch for fixes, minor for compatible features, major
   for breaking changes. The [Upgrade Guide](/docs/upgrade) describes the upgrade
   procedure; the [Release Notes](/docs/changelog) list what changed.
+- **One exception, while the 1.x line is young:** a breaking change may land in a
+  minor or a patch when leaving it in place would cost more than the migration
+  does. It is called out in the release notes as **BREAKING**, with the reason and
+  the migration steps, and it is never silent. Two have shipped so far — the
+  `ComponentWith` / `BaseModelWith` removal in 1.3.0 and Flow's `socket:` listener
+  prefix in 1.7.2. This carve-out is a consequence of the project's age, not a
+  standing policy; it will be withdrawn, with a version named here, once adoption
+  makes the cost of a break real.
 - **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

@@ -18,6 +18,8 @@ version line:
 - **Major** (`X.y.z`) — breaking changes; read the version's section in the
   [Release Notes](/docs/changelog) before upgrading.
 
+> **Warning** — while the 1.x line is young, a breaking change may also land in a minor or a patch. It is always labelled **BREAKING** in the [Release Notes](/docs/changelog) with migration steps, and two have shipped so far (1.3.0 and 1.7.2). Read the notes for every version you cross, not only the majors. See [Releases and versioning](/docs/support-policy#releases-and-versioning) for when this carve-out ends.
+
 > **Warning** — always upgrade the `@zerotal/*` packages together. Mixing versions across core, ORM, and feature packages leads to type and runtime mismatches.
 
 ## Upgrade steps

package/package.json

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