@zerotal/arch 1.12.0 → 1.13.1

package/docs/changelog.md

@@ -27,6 +27,104 @@ 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.1 — 2026-08-31
+
+One addition, found by sizing a job rather than doing it.
+
+The 2.0 ledger carries an entry to prefix every `@internal` export with `_` — 270 symbols,
+filed as mechanical. Three of them are `Job` classes, and a job class name is not a source
+symbol: `JobRegistry` keys on it and that string is written into the persisted queue payload,
+so a job enqueued yesterday is resolved by today's process. Renaming one invalidates every job
+already in the queue, at deploy time rather than at change time, and no test sees it because a
+test enqueues and runs in the same process.
+
+The rename is re-scoped. The hazard it exposed is fixed here.
+
+### Added
+
+- **`Job.jobName`** — a declared name for the queue payload, so renaming a job class is free:
+
+  ```ts
+  export class SendWelcomeEmail extends Job {
+    static override jobName = "SendWelcomeEmail"; // survives a class rename
+    async handle(): Promise<void> {}
+  }
+  ```
+
+  It defaults to the class name, so a job that declares nothing behaves exactly as before.
+  This is the same tool [`Migration.id`](/docs/upgrade#1-10-to-1-11) is for a migration's
+  filename, shipped in 1.11.0 for the same reason: an identity the framework derived from a
+  name someone was free to change, with no way to say otherwise.
+
+  It also decouples the queue from a build that mangles names. `zt compile` does not minify
+  today, so that is not a live hazard — but nothing in the registry said it depended on that,
+  and an assumption worth relying on is worth writing down.
+
+## 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.

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/queue.md

@@ -141,6 +141,37 @@ export class PruneDeletedContentJob extends Job {
 JobRegistry.register(PruneDeletedContentJob as never);
 ```
 
+### Renaming a job class
+
+A queued job is a **persisted reference to a class**. The payload in the database or in Redis
+carries a string, and the worker resolves the class by it — so a job enqueued yesterday is
+looked up by today's process. That makes the class name a compatibility surface, and renaming
+the class a silent data migration: jobs already in the queue under the old name stop resolving
+at the moment you deploy.
+
+It is invisible to a test suite, because a test enqueues and runs in the same process.
+
+Declare the stored name and the class is free to move:
+
+```ts
+import { Job } from "@zerotal/queue";
+
+export class SendWelcomeEmail extends Job {
+  // The name in the queue payload. Keep it when the class is renamed.
+  static override jobName = "SendWelcomeEmail";
+
+  async handle(): Promise<void> {}
+}
+```
+
+It defaults to the class name, so a job that says nothing behaves exactly as before. Declare it
+when you rename a job class, or ahead of time on jobs you expect to rename — it is the same
+tool `Migration.id` is for a migration's filename, and the same reason.
+
+**Drain before you rename, if you have not declared one.** A rename with jobs in flight and no
+`jobName` leaves rows the worker reports as an unknown job class; `zt queue:failed` lists them
+and `zt queue:retry` can replay them once the name matches again.
+
 ## Auto-registration
 
 You don't import or wire up your jobs anywhere. Any job class placed under

package/docs/support-policy.md

@@ -75,11 +75,12 @@ 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. Six 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, SQLite
   foreign-key enforcement in 1.11.0, `countTokens` returning `number | null` in
-  1.11.2, and the refusal to write a boolean into a text column in 1.12.0.
+  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`

package/docs/upgrade.md

@@ -289,6 +289,64 @@ 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.

package/package.json

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