@zerotal/arch 1.7.2 → 1.7.4

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/inertia/index.md

@@ -162,7 +162,7 @@ export default function Dashboard({ posts, auth }: Props) {
       <h1>Dashboard</h1>
       {auth.user && <p>Welcome back, {auth.user.name}</p>}
       {posts.map((post) => (
-        <Link key={post.id} href={`/posts/${post.slug}`}>
+        <Link key={post.id} href={route("posts.show", { slug: post.slug })}>
           {post.title}
         </Link>
       ))}
@@ -176,6 +176,11 @@ Note `auth` is available without the controller passing it — see
 [`make:page`](/docs/inertia/build#generating-a-page) and bundle them with
 [`inertia:build`](/docs/inertia/build#building-assets).
 
+`route("posts.show", { slug })` builds the URL from the route's **name** rather than
+hard-coding the path, so renaming a route updates every link to it and a typo fails
+the build. Prefer it over a literal `href` anywhere you link — see
+[Building URLs](/docs/inertia/rendering#building-urls-with-route).
+
 ## Testing
 
 Set your suite up once as described in [Testing](/docs/testing). An Inertia route

package/docs/inertia/props.md

@@ -339,7 +339,7 @@ export default function Page() {
   return (
     <>
       {flash.success && <div className="toast">{flash.success}</div>}
-      {auth.user ? <span>{auth.user.name}</span> : <a href="/login">Sign in</a>}
+      {auth.user ? <span>{auth.user.name}</span> : <a href={route("login")}>Sign in</a>}
     </>
   );
 }

package/docs/inertia/rendering.md

@@ -147,6 +147,85 @@ array** directly as a shorthand. To use both, pass props third and middleware fo
 Router.inertia("/admin", "Admin/Dashboard", { title: "Admin" }, [AuthMiddleware]);
 ```
 
+## Building URLs with route()
+
+A hard-coded `href="/posts/hello"` is a string nothing checks. Rename the route and
+every link to it keeps compiling and starts 404ing — a bug that surfaces when
+someone clicks, not when someone builds.
+
+Name the route instead, and let the URL be derived:
+
+```tsx
+import { Link } from "@inertiajs/react";
+
+<Link href={route("posts.show", { slug: post.slug })}>{post.title}</Link>
+<Link href={route("posts.index", {}, { page: 2 })}>Next</Link>
+```
+
+No import for `route` — `defineRoutes()` installs it globally, and the names are
+checked against the same registry your controllers use, so `route("posts.shwo")`
+fails the build. [Routing](/docs/routing#route-in-the-browser) owns the mechanics:
+the generated table, wiring your entry point, typing, and `route.dynamic()` for a
+name only known at runtime.
+
+### Forms submit to a name too
+
+A form's action is the same kind of string as a link's `href`, and gets the same
+treatment. `useForm()` and `router` both take a URL, so hand them one that was built
+from the route name:
+
+```tsx
+import { useForm, router } from "@inertiajs/react";
+
+export default function Edit({ post }: Props) {
+  const form = useForm({ title: post.title, body: post.body });
+
+  const submit = (e: React.FormEvent) => {
+    e.preventDefault();
+    form.put(route("posts.update", { slug: post.slug }));
+  };
+
+  const destroy = () => {
+    router.delete(route("posts.destroy", { slug: post.slug }));
+  };
+
+  return (
+    <form onSubmit={submit}>
+      <input value={form.data.title} onChange={(e) => form.setData("title", e.target.value)} />
+      {form.errors.title && <span>{form.errors.title}</span>}
+      <button disabled={form.processing}>Save</button>
+      <button type="button" onClick={destroy}>
+        Delete
+      </button>
+    </form>
+  );
+}
+```
+
+The names follow the same convention the router generates: a `POST` is
+`posts.store`, `PUT`/`PATCH` is `posts.update`, `DELETE` is `posts.destroy`. So the
+name in the component and the route the controller is mounted on cannot drift apart
+silently — change the URL and both ends move together.
+
+This matters more for a form than for a link. A broken link 404s where someone can
+see it; a form posting to a stale URL fails **after** the user has filled it in, and
+the data goes with it.
+
+Build the URL the same way for [Precognition](/docs/inertia/props#precognition), so
+live validation and the real submit cannot end up aimed at different routes — the
+failure there is a form that validates clean and then rejects on save.
+
+### One thing Inertia adds: define the routes in _both_ entries
+
+An Inertia page renders twice — once in the SSR process, once in the browser — so a
+component calling `route()` runs in both. A table defined in only one of them throws
+in the other: miss the SSR entry and `POST /__ssr` answers `500` with
+`[Inertia] SSR render failed` in the log, for a page the browser then renders
+perfectly well.
+
+Call `defineRoutes(ROUTES)` in your browser entry **and** in your
+[SSR entry](/docs/inertia/ssr). Same static import, same table.
+
 ## Redirects
 
 After a non-GET action (a form POST/PUT/DELETE), redirect as usual — return a 302 and

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 and `ALTER`, identity columns, CRUD, type round-trips, unique and NOT NULL enforcement, 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 the Postgres path is covered more narrowly than the default one. |
+| MySQL      | Supported, hardening. The same smoke suite runs against a real MySQL 8 on every merge and blocks on failure. It is newer than the Postgres job and has found one defect already (`string()` was not indexable), so treat MySQL as verified in the paths the suite covers and less proven than PostgreSQL outside them.                                                            |
 
 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.
@@ -92,6 +100,21 @@ a contract, not a mood:
 - **experimental** — no compatibility promise. The API may change or the package
   may be absorbed into another in any release. Build on it with your eyes open.
 
+### A label below stable carries a review date
+
+An honest "experimental" is useful once and corrosive indefinitely: a package that
+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.9.0**   |
+| `@zerotal/arch` | `beta`         | **1.9.0**   |
+
+Neither is in the `zerotal` meta-package and nothing `stable` depends on either,
+so the cost of the label falling due is ours and not yours.
+
 A package is never more mature than what it is built on: a stable package whose
 foundation can change under it is not stable, whatever its own label says. So
 `@zerotal/admin` and `@zerotal/monitor` cannot pass `@zerotal/flow`, and the

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