@zerotal/arch 1.13.0 → 1.13.1

package/docs/changelog.md

@@ -27,6 +27,39 @@ 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

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/package.json

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