@zerotal/arch 1.8.1 → 1.10.0

package/docs/monitor.md

@@ -262,6 +262,40 @@ Every colour in the panel resolves to a token — `bg-card`, `text-muted-foregro
 
 Practically, this means re-branding the monitor is a few CSS variables rather than a fork, and a contributed section written against the same tokens matches the built-in ones for free.
 
+## The snapshot shape
+
+**Export JSON** hands you a `MonitorSnapshot` — the whole panel for the selected range, as data.
+It is worth knowing the shape if you post it somewhere, diff two of them, or drive an alerting
+integration off it rather than off the built-in thresholds.
+
+`range` is a `MonitorRange`, and the rest is one field per thing the panel draws:
+
+| Area                 | Fields and their row types                                                                             |
+| -------------------- | ------------------------------------------------------------------------------------------------------ |
+| Live                 | `pulse: PulseStats` — in-flight requests, connections, rate, error rate. Not windowed.                 |
+| Overview             | `statCards: StatCard[]`, `percentiles: Percentile[]`, `apdex`, `throughput`, `slowRoutes: RouteStat[]` |
+| Requests             | `requests` / `slowRequests: RequestEntry[]`, `topUsers: UserUsage[]`, `topMemory: MemoryRoute[]`       |
+| Outgoing             | `outgoingHttp: OutgoingHttp[]`                                                                         |
+| Queues               | `queueStats: QueueMetric[]`, `queues: QueueRow[]`, `failedJobs: FailedJob[]`, `deadLetter: DeadJob[]`  |
+| Schedule             | `scheduledJobs: ScheduledJob[]`, `scheduledRuns: FeedEvent[]`, `slowJobs`                              |
+| Database             | `dbStats: DbStat[]`, `slowQueries: SlowQuery[]`, `transactions: TxStats`, `nplusOnes: NPlusOne[]`      |
+| Exceptions           | `exceptions: ExceptionGroup[]` — grouped, so one recurring error is one row.                           |
+| Cache & realtime     | `cache: CacheStats`, `realtime: RealtimeStats`                                                         |
+| Mail & notifications | `mail`, `notifications: NotificationEntry[]`                                                           |
+| Models               | `models`, `recentModels: ModelEvent[]`                                                                 |
+| Health               | `health: HealthEntry[]`, `gauges: Gauge[]`, `commands: CommandEntry[]`                                 |
+| Feeds                | `security` / `logs: FeedEvent[]`, `alertHistory: AlertEntry[]`                                         |
+
+A few names carry more than their field suggests. `CacheKey` and `CacheStats` separate the hot
+keys from the aggregate. `StatusClassCount` is the 2xx/3xx/4xx/5xx split behind an error rate.
+`ConnectedClient` and `WsAction` are what `realtime` counts. `CheckIn` is a heartbeat from a
+scheduled job that reported in, `UptimeCheck` an external probe, `RequestSpan` / `RequestQuery`
+/ `RequestPayload` / `RequestLog` the detail behind one `RequestEntry`, and `RouteDetail` the
+per-route drill-down. `SystemMeta` and `StorageInfo` describe the machine rather than the app.
+
+`Tone` (and `MonitorTone`) is the good/warn/bad colouring the panel applies to a stat, and
+`AlertContext` is what an alert carries when it fires.
+
 ## Adding your own sections
 
 The panel owns the shell, the time-range selector, the storage and the retention policy — but it doesn't own the knowledge of what is worth watching about any given package. So it's a **host**: it publishes a write surface as the `monitor.panel` container binding, and a package pushes a section into it at boot.
@@ -318,6 +352,25 @@ export default MonitorConfig({
 });
 ```
 
+### Typing a section
+
+Declaring the host's shape locally is the documented path and stays supported. If you would
+rather have the real types — because your `resolve` is large enough that a typo in a column key
+should be a compile error rather than a blank cell — they are exported:
+
+| Type                 | What it is                                                                 |
+| -------------------- | -------------------------------------------------------------------------- |
+| `MonitorSection`     | The whole contribution: `id`, `label`, optional `group`, and `resolve`.    |
+| `MonitorSectionData` | What `resolve` returns — the `stats` and `tables` below.                   |
+| `MonitorStat`        | One figure: label, value, optional `percent` and `tone`.                   |
+| `MonitorTable`       | One table: title, columns, rows, and the `empty` line when there are none. |
+| `MonitorTableColumn` | One column: `key`, `label`, and the `mono` / `align` presentation flags.   |
+| `MonitorRow`         | One row — a record keyed by the columns' `key` values.                     |
+
+Importing them means depending on `@zerotal/monitor`, which is the trade the structural form
+exists to avoid. For a section of two stats and one table, the local interface is still the
+better answer.
+
 ### Scheduled tasks
 
 `@zerotal/scheduler` ships the first contributed section. A cron task that silently stopped firing is one of the harder failures to notice — nothing errors, work just stops happening — so the section leads with counts of tasks that are failing or have never run, then lists every task with its cron expression, last result, duration and next due time. Install both providers and it appears under **Infrastructure**; no configuration.
@@ -369,6 +422,12 @@ Types: `MonitorConfigShape`, `ResolvedMonitorConfig`, `MonitorStoreOptions`,
 `@zerotal/monitor` ships no CLI commands. The panel is a route, not a console
 tool — everything is read through the browser or the Prometheus endpoint.
 
+### The metrics snapshot
+
+`httpMetrics()` returns an `HttpMetricsSnapshot` — request counts, durations and status classes
+since the process started. It is what the Prometheus endpoint renders, and it is exported so an
+app can ship the same numbers somewhere the panel does not reach.
+
 ## Next steps
 
 - [Telemetry](/docs/telemetry) — export the same signal to an OTLP backend for long-term storage.

package/docs/notifications.md

@@ -840,6 +840,17 @@ durable record is the database channel.
 | `OnDemandNotifiable` | The recipient `Notify.route()` builds — a destination with no model behind it. Its database rows are keyed to a random id nothing can query back, so on-demand notifications normally declare transport channels only. |
 | `RichLine`           | The chainable line returned inside `MailMessage` for mixed formatting (`.text()`, `.color()`).                                                                                                                         |
 
+## Types
+
+| Type                                                       | What it is                                                                                  |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `MailDriver`                                               | The transport contract — implement it to send through something the built-ins do not cover. |
+| `MailPayload`                                              | One message as the driver receives it.                                                      |
+| `MailAddress`, `AddressInput`                              | A recipient, and the forms one may be given in.                                             |
+| `MailAttachment`                                           | A file on a message.                                                                        |
+| `TextStyle`                                                | How the plain-text alternative is derived from the HTML.                                    |
+| `SmsConfigShape`, `TwilioConfigShape`, `VonageConfigShape` | SMS configuration, and the two providers' own settings.                                     |
+
 ## Next steps
 
 - [Broadcasting](/docs/broadcasting) — the real-time broadcast channel and channel auth.

package/docs/orm/casts.md

@@ -357,6 +357,12 @@ Cast options accepted by `@column()`:
 | `cast`       | shorthand string, `{ get, set }`, or `CastContract` | The transform applied on read/write.            |
 | `enumValues` | `Record<string, string \| number>`                  | The TS enum object, paired with `cast: "enum"`. |
 
+## Types
+
+`CastField` is what a cast declaration holds. `EncryptedCastName` names the encrypted cast
+variants, and `isEncryptedCast` says whether a given cast is one — which matters because an
+encrypted column cannot be queried by value, only by a blind index kept beside it.
+
 ## Next steps
 
 - [ORM](/docs/orm) — defining models and columns.

package/docs/orm/lifecycle.md

@@ -413,6 +413,24 @@ the two are identical.
 | `static dispatchesEvents` | `Record<string, new (model) => object>` | Maps lifecycle keys to app-bus event classes.              |
 | `static massPrune`        | `boolean` (default `false`)             | Permanently delete prunable rows instead of soft-deleting. |
 
+## Types
+
+**State machines.** `StateMachine` guards a column against transitions that should not happen —
+an order going from `shipped` back to `pending` is a bug, and the place to refuse it is the model
+rather than every call site.
+
+| Type                                      | What it is                                                             |
+| ----------------------------------------- | ---------------------------------------------------------------------- |
+| `StateGuard`                              | The condition allowing one transition.                                 |
+| `TransitionCallback`, `TransitionContext` | What runs on a transition, and what it receives.                       |
+| `TransitionResult`                        | Whether it happened.                                                   |
+| `RejectTransition`                        | The refusal — a value, so a caller can branch on it rather than catch. |
+
+**Errors.** `TransactionError` wraps a failure inside a transaction with what was being
+attempted; `UnsupportedDialectError` is thrown when a driver genuinely cannot do something —
+a signed URL on a local disk, an advisory lock on SQLite — rather than failing quietly and
+returning nothing. `TransactionContext` is the ambient handle a transaction carries.
+
 ## Next steps
 
 - [ORM](/docs/orm) — model basics and the `dispatchesEvents` bridge.

package/docs/orm/queries.md

@@ -683,6 +683,16 @@ Child models inherit all global scopes registered on a parent model.
 | `toRawSql`                              | `toRawSql(): string`                                    | SQL with values inlined (logging only).   |
 | `clone`                                 | `clone(): this`                                         | Copy the builder to branch conditions.    |
 
+## Types
+
+| Type                  | What it is                                                      |
+| --------------------- | --------------------------------------------------------------- |
+| `WhereOperator`       | The comparison operators `where()` accepts.                     |
+| `OrderDirection`      | `asc` / `desc`.                                                 |
+| `DatePart`            | The parts date helpers can compare on — year, month, day.       |
+| `PaginateMeta`        | The page, per-page, total and last-page a paginator reports.    |
+| `GlobalScopeCallback` | A scope applied to every query for a model until it is removed. |
+
 ## Next steps
 
 - [ORM](/docs/orm) — model definition, columns, and configuration.

package/docs/orm/relationships.md

@@ -432,6 +432,36 @@ Pivot collection methods on a `ManyToMany<T>` relation.
 | `sync`   | `sync(ids[]): Promise<void>`                    | Replace all pivot rows with the given set.            |
 | `toggle` | `toggle(id \| id[]): Promise<void>`             | Attach missing ids and detach present ones.           |
 
+### Types
+
+Every decorator above returns a typed relation, and every one takes an options shape. Both are
+exported, so a helper that builds relations or a signature that accepts one can be annotated.
+
+| Type                 | What it is                                                                         |
+| -------------------- | ---------------------------------------------------------------------------------- |
+| `HasOne<T>`          | What `@hasOne` produces — one related record, or `null`.                           |
+| `HasMany<T>`         | What `@hasMany` produces — a queryable collection of related records.              |
+| `BelongsTo<T>`       | What `@belongsTo` produces — the owning record, or `null`.                         |
+| `RelationType`       | The relation kinds as a union: `hasOne`, `hasMany`, `belongsTo`, `manyToMany`, …   |
+| `RelationDefinition` | One declared relation: its type, target model, and keys.                           |
+| `RelationMetadata`   | What the decorator records about a relation, read by eager loading and `whereHas`. |
+| `RelationConstraint` | The callback form — `with({ posts: (q) => q.where(…) })`.                          |
+| `WithLoaded<T, K>`   | A model type narrowed to say which relations are loaded, so reading one is safe.   |
+
+The option shapes match their decorators: `HasManyThroughOptions`, `ManyToManyOptions`,
+`MorphOneOptions`, `MorphManyOptions`, `MorphToOptions`, `MorphToManyOptions` and
+`MorphedByManyOptions`.
+
+`relationRegistry` is the map the decorators write into and eager loading reads back. It is
+framework wiring rather than something an app calls, but it is exported because the testing
+helpers reach for it.
+
+> **`RelationNotLoadedError`** is thrown when you read a relation that was never loaded, rather
+> than returning `undefined`. That is the whole reason the error exists: a silent `undefined`
+> reads as "no related records" and is indistinguishable from a genuine empty result, so an
+> N+1 you meant to fix becomes a page that quietly shows nothing. Load it with `with()`, or ask
+> for it explicitly with `await post.load("author")`.
+
 ## Next steps
 
 - [ORM queries](/docs/orm/queries) — eager loading, `whereHas`, and aggregates in depth.

package/docs/queue.md

@@ -550,6 +550,16 @@ try {
 process is draining, not that anything is broken, so the right response is to
 re-dispatch on the next boot rather than to fail the request.
 
+## Types
+
+| Type                                         | What it is                                                                                      |
+| -------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `QueueDriver`                                | The contract a backend implements — implement it to queue somewhere the built-ins do not reach. |
+| `JobRecord`, `JobStatus`                     | A queued job as stored, and where it is in its life.                                            |
+| `SerializedJob`                              | The wire form — what a driver actually persists.                                                |
+| `BatchOptions`, `BatchRecord`, `BatchStatus` | A batch's settings, its stored form, and its progress.                                          |
+| `WorkerPoolOptions`, `WorkerResult`          | How many workers run and what one attempt returned.                                             |
+
 ## Next steps
 
 - [Scheduler](/docs/scheduler) — run recurring jobs alongside the queue worker.

package/docs/rate-limiting.md

@@ -65,10 +65,53 @@ ThrottleMiddleware.with({
 | `keyResolver`    | no       | client IP   | Function returning the rate-limit key for a request.        |
 | `trustedProxies` | no       | `undefined` | Number of trusted upstream proxies (see the warning below). |
 
-> **Danger** — With `trustedProxies` left `undefined`, the limiter trusts the
-> leftmost `X-Forwarded-For` entry, which a client behind a real proxy can forge
-> to dodge the limit. Set `trustedProxies` to the exact number of proxies in
-> front of your server (`0` when there is none) so the real client IP is used.
+`X-Forwarded-For` is written by the client, so it is consulted **only** when
+`trustedProxies` says how many proxies sit in front of the app — the count is what says
+which entry is not attacker-controlled. Left `undefined` (or `0`), the unspoofable socket
+address is used.
+
+**Counted from the right, and that is the whole of it.** Each proxy _appends_ the address
+it received the request from, so the rightmost entries are the ones your own
+infrastructure wrote and the leftmost is whatever the client sent. Reading the header
+left-to-right — the obvious way, and how most hand-rolled versions do it — hands the
+limiter's key to the attacker: they set `X-Forwarded-For: <your CFO's IP>`, spend the
+budget, and the person whose address they borrowed is locked out of the form. A limiter
+that can be aimed is worse than no limiter, because it looks like it is working.
+
+> **Danger** — That default is right, and it is the wrong answer the moment you deploy
+> behind a proxy. The socket address is then the _proxy's_ — `127.0.0.1` for every visitor
+> — so everyone shares one bucket per form and the limiter inverts into the thing it was
+> installed to prevent: one attacker making twenty bad sign-ins a minute locks the whole
+> staff out of the console. Nothing fails; you put Caddy in front, everything works, and
+> the limiter quietly stops telling people apart. Set `trustedProxies` to the number of
+> proxies you actually run. `zt doctor` warns when a production-like deployment has a
+> throttle and no `trustedProxies` — see [Deployment](/docs/deployment#behind-a-reverse-proxy).
+
+### One `.with()` call, one bucket
+
+Each `.with()` call returns its own class, and the hit counter belongs to the class — so
+**re-using one `.with()` export on two routes gives them a shared budget**:
+
+```typescript fragment
+// One bucket: 5 attempts across BOTH forms.
+const AuthThrottle = ThrottleMiddleware.with({ maxAttempts: 5, windowSeconds: 60 });
+Router.post("/login", AuthController, "login", [AuthThrottle]);
+Router.post("/two-factor", AuthController, "challenge", [AuthThrottle]);
+
+// A bucket each, which is almost always what was meant.
+Router.post("/login", AuthController, "login", [
+  ThrottleMiddleware.with({ maxAttempts: 5, windowSeconds: 60 }),
+]);
+Router.post("/two-factor", AuthController, "challenge", [
+  ThrottleMiddleware.with({ maxAttempts: 5, windowSeconds: 60 }),
+]);
+```
+
+The sharing is deliberate — it is what lets you spend one allowance across a group of
+related routes on purpose — and it is not what a reader expects from a factory. On a sign-in
+flow it bites: a handful of fumbled passwords can spend the allowance a legitimate person
+needs to answer their second factor. Call `.with()` once per thing that deserves its own
+budget.
 
 ## RateLimiter — named limiters
 
@@ -82,8 +125,9 @@ import { RateLimiter } from "zerotal";
 // 1000 req/hour per authenticated user (falls back to IP when unauthenticated)
 RateLimiter.for("api").limit(1000).every(3600).byUser().register();
 
-// 5 login attempts per minute, per IP
-RateLimiter.for("login").limit(5).every(60).byIp().register();
+// 5 login attempts per minute, per IP. `.trustedProxies(1)` because this app is
+// behind one reverse proxy — without it every visitor shares the proxy's address.
+RateLimiter.for("login").limit(5).every(60).byIp().trustedProxies(1).register();
 
 // 500 req/min keyed by an API-key header (unknown key → per IP)
 RateLimiter.for("partner").limit(500).every(60).byApiKey("x-api-key").register();
@@ -105,12 +149,30 @@ RateLimiter.for("upload")
 Each `.by*()` call sets how requests are bucketed. The default (no `.by*()` call)
 is the client IP.
 
-| Method               | Keys on                                     | Falls back to            |
-| -------------------- | ------------------------------------------- | ------------------------ |
-| `.byUser()`          | `ctx.user.id`                               | IP when unauthenticated  |
-| `.byApiKey(header?)` | `x-api-key` header (or a custom header)     | IP when header is absent |
-| `.byIp()`            | Socket IP → `X-Forwarded-For` → `X-Real-IP` | `'unknown'`              |
-| `.by(fn)`            | Return value of your function               | —                        |
+| Method               | Keys on                                 | Falls back to            |
+| -------------------- | --------------------------------------- | ------------------------ |
+| `.byUser()`          | `ctx.user.id`                           | IP when unauthenticated  |
+| `.byApiKey(header?)` | `x-api-key` header (or a custom header) | IP when header is absent |
+| `.byIp()`            | Client IP (the explicit default)        | `'unknown'`              |
+| `.by(fn)`            | Return value of your function           | —                        |
+
+> **Danger** — **Every one of the built-in strategies can end up keying on an
+> address**, including `.byUser()` and `.byApiKey()` — for a request with no user and
+> no key, which on a login form is every request that matters. So a named limiter
+> behind a reverse proxy needs `.trustedProxies(n)` for exactly the reason
+> [`ThrottleMiddleware` does](#throttlemiddleware--inline): without it the address is
+> the socket's, which is the _proxy's_, and every visitor shares one bucket. A
+> `login` limiter of five attempts a minute becomes five attempts a minute for your
+> whole user base, and one attacker locks everybody out.
+>
+> ```typescript fragment
+> // config/limiters.ts — behind one reverse proxy
+> RateLimiter.for("login").limit(5).every(60).byIp().trustedProxies(1).register();
+> ```
+>
+> `zt doctor` reports a named limiter that keys on an address and was never told
+> about a proxy. `.by(fn)` is yours — it is exempt, and resolving the address is on
+> you if you use one.
 
 ### Applying a named limiter
 
@@ -228,15 +290,16 @@ await app.post("/login", { email: "a@b.c" }, { "X-Forwarded-For": "10.0.0.7" });
 
 ### `LimiterDefinition` (fluent)
 
-| Method     | Signature                                    | Description                                                |
-| ---------- | -------------------------------------------- | ---------------------------------------------------------- |
-| `limit`    | `limit(max: number): this`                   | Maximum requests in the window (default `60`).             |
-| `every`    | `every(seconds: number): this`               | Window duration in seconds (default `60`).                 |
-| `byUser`   | `byUser(): this`                             | Key by `ctx.user.id`; IP when unauthenticated.             |
-| `byApiKey` | `byApiKey(header?: string): this`            | Key by header value (default `x-api-key`); IP when absent. |
-| `byIp`     | `byIp(): this`                               | Key by client IP (the explicit default).                   |
-| `by`       | `by(fn: (ctx: HttpContext) => string): this` | Key by your own resolver.                                  |
-| `register` | `register(): this`                           | Register the limiter with the global registry.             |
+| Method           | Signature                                    | Description                                                |
+| ---------------- | -------------------------------------------- | ---------------------------------------------------------- |
+| `limit`          | `limit(max: number): this`                   | Maximum requests in the window (default `60`).             |
+| `every`          | `every(seconds: number): this`               | Window duration in seconds (default `60`).                 |
+| `byUser`         | `byUser(): this`                             | Key by `ctx.user.id`; IP when unauthenticated.             |
+| `byApiKey`       | `byApiKey(header?: string): this`            | Key by header value (default `x-api-key`); IP when absent. |
+| `byIp`           | `byIp(): this`                               | Key by client IP (the explicit default).                   |
+| `by`             | `by(fn: (ctx: HttpContext) => string): this` | Key by your own resolver.                                  |
+| `trustedProxies` | `trustedProxies(count: number): this`        | Proxies in front of the app — required behind one.         |
+| `register`       | `register(): this`                           | Register the limiter with the global registry.             |
 
 ### `ThrottleMiddleware`
 

package/docs/responses.md

@@ -327,6 +327,29 @@ Common status codes:
 | `ctx.redirect(url, 303)` | 303    | After POST/PUT/DELETE                            |
 | `ctx.redirect(url, 301)` | 301    | Permanent redirect                               |
 
+## Negotiating by client
+
+One route, three audiences. `negotiate(ctx)` picks a branch from the `Accept` header and how the
+request arrived, so a handler answers a browser, an API client and the console without three
+copies of the logic:
+
+```typescript fragment
+import { negotiate } from "zerotal/http";
+
+await negotiate(http)({
+  web: () => http.redirect("/dashboard"),
+  api: () => http.json({ ok: true }),
+  cli: () => http.text("done"),
+});
+```
+
+`NegotiateMap` is that object; `WebContext`, `ApiContext` and `CliContext` are what each branch
+receives. A missing branch falls through to `web`, because the browser is the audience most
+likely to be looking.
+
+This is what the framework's own error handler uses, which is why a 422 is a redirect-with-errors
+for a form post and a JSON body for a fetch — see [Errors](/docs/errors#response-format-by-client-type).
+
 ## Next steps
 
 - [Requests Context](/docs/context) — read input from the incoming request.

package/docs/routing.md

@@ -1081,6 +1081,22 @@ Every route registration returns a chainable handle:
 | `bun zt route:list`                    | —                                   | Print every route (`-m` method, `-p` path, `--name`, `-v` middleware).  |
 | `bun zt route:types`                   | `--check`                           | Write `types/routes.generated.ts`; `--check` fails when it is stale.    |
 
+## Types
+
+| Type                 | What it is                                                                                                |
+| -------------------- | --------------------------------------------------------------------------------------------------------- |
+| `HttpMethod`         | The verbs a route can answer on.                                                                          |
+| `HttpResponse`       | What a handler may return when it does not write to `ctx.response`.                                       |
+| `ControllerResponse` | A controller action's return type — `void`, a `ResponseBuilder`, or a `MarkdownBuilder`.                  |
+| `RouteParams`        | The params a pattern captures, as a record.                                                               |
+| `ParamsOf<P>`        | The params of one pattern, derived from the pattern string — what makes `route()` refuse a missing `:id`. |
+| `RouteRegistry`      | The generated name → pattern table, augmented by `types/routes.generated.ts`.                             |
+| `RouteMiddleware`    | What a route's middleware list accepts — a class, an array, or the method map.                            |
+| `GroupOptions`       | `Router.group({ prefix, middleware, domain })`.                                                           |
+| `RoutingConfig`      | The `routing` config namespace.                                                                           |
+| `FileRoutingConfig`  | File-router settings within it.                                                                           |
+| `WebSocketHandlers`  | The handler set a WebSocket route registers.                                                              |
+
 ## Next steps
 
 - [Controllers](/docs/controllers) — move route logic out of closures.

package/docs/scheduler.md

@@ -61,17 +61,43 @@ import { SchedulerConfig } from "@zerotal/scheduler";
 import { env } from "zerotal";
 
 export default SchedulerConfig({
-  timezone: env("APP_TIMEZONE", "UTC"),
+  timezone: env("APP_TIMEZONE", "Africa/Johannesburg"),
 });
 ```
 
-| Field      | Required | Default | Description                                                                             |
-| ---------- | -------- | ------- | --------------------------------------------------------------------------------------- |
-| `timezone` | no       | `"UTC"` | Informational only — `Bun.cron` uses the system timezone. Set per task with `timezone`. |
+| Field      | Required | Default         | Description                                                                        |
+| ---------- | -------- | --------------- | ---------------------------------------------------------------------------------- |
+| `timezone` | no       | the system zone | IANA zone every cron expression is read in, unless a task sets its own `timezone`. |
 
-> **Note** — The config `timezone` is informational. To evaluate a cron in a
-> specific zone, set `timezone` on the `Schedule` subclass or `.timezone(tz)` on a
-> facade task; that value is passed through to `Bun.cron`.
+## Timezones
+
+A cron expression is a wall clock: `0 3 * * *` means three in the morning
+_somewhere_. By default that somewhere is the server's zone. Set `scheduler.timezone`
+to make it one zone for the whole app, or `timezone` on a single schedule to override
+it:
+
+```typescript fragment
+export class SendDailyReports extends Schedule {
+  cron = "0 8 * * *";
+  timezone = "Africa/Johannesburg"; // 08:00 there, whatever the server is on
+}
+```
+
+The zone is evaluated by Zerotal, not by `Bun.cron` — which reads the system zone and
+has no option to change it. A zoned task ticks every minute and runs on the ticks
+where its expression matches the clock in its own zone, so it stays correct across a
+daylight-saving change rather than drifting by an hour twice a year. A minute is also
+the finest granularity `Bun.cron` accepts, so nothing is given up.
+
+Two consequences worth knowing:
+
+- **A skipped hour skips the schedules inside it, and a repeated hour runs them
+  twice.** That is what every cron does. A task at `0 2 * * *` in a zone that springs
+  from 01:59 to 03:00 does not run that day.
+- **An unknown zone name refuses at boot, loudly, and takes only its own task out.**
+  A registration failure used to propagate: the worker died during boot and
+  restart-looped, so one bad schedule stopped every schedule in the app. Now the
+  others start and the log names the one that did not.
 
 ## Defining schedules
 
@@ -134,7 +160,7 @@ Every setting is an optional property (or method) on your `Schedule` subclass:
 | `cron`                                                         | `string`                        | Cron expression (5- or 6-field). Set this **or** override `frequency()`.                                      |
 | `frequency(every)`                                             | method                          | Build the cadence fluently; return the task (see helpers below).                                              |
 | `name`                                                         | `string`                        | Task name in `schedule:list` and logs. Defaults to the class name.                                            |
-| `timezone`                                                     | `string`                        | IANA timezone the cron is evaluated in.                                                                       |
+| `timezone`                                                     | `string`                        | IANA timezone the cron is evaluated in — overrides `scheduler.timezone`. See [Timezones](#timezones).         |
 | `withoutOverlapping`                                           | `boolean \| OverlapLockOptions` | Skip a tick while a previous run is active; also takes a cross-process lock when a lock driver is configured. |
 | `environments`                                                 | `string[]`                      | Only run when `APP_ENV` is one of these.                                                                      |
 | `inBackground`                                                 | `boolean`                       | Run the body without blocking the scheduler tick.                                                             |
@@ -489,6 +515,19 @@ override async onStarted(): Promise<void> {
 For production, run the worker as a separate process so it can be scaled, restarted,
 and monitored independently of the web server.
 
+> **A web process says so when it is not running your schedules.** `app/schedules/`
+> is only discovered in `worker` and `console`, so a web process skips it by not
+> looking — which used to be completely silent, and is how an app runs for weeks in
+> production with every schedule written and none of them ever firing. A boot line
+> now names it:
+>
+> ```
+> Skipping 3 file(s) in app/schedules — the "schedules" convention does not run in env=web (it runs in: worker, console).
+> ```
+>
+> Seeing that on a web process is correct. Seeing it and having no worker running is
+> the hole.
+
 ## References
 
 The `Scheduler` facade resolves the `scheduler` container binding — a
@@ -514,6 +553,30 @@ The `Scheduler` facade resolves the `scheduler` container binding — a
 | `stop`  | `stop(): void`                                                     | Stop every running task.                           |
 | `tasks` | `get tasks(): ReadonlyMap<string, ScheduledTask>`                  | The registered tasks, keyed by name.               |
 
+### Timezone helpers
+
+The zone arithmetic the scheduler uses to evaluate a cron somewhere other than the
+server, exported because an app doing its own time-window logic needs the same
+answers.
+
+| Export                          | Signature                                            | Description                                                                                    |
+| ------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `isValidTimeZone`               | `isValidTimeZone(tz: string): boolean`               | Whether this runtime knows the IANA zone. Check before storing one a user typed.               |
+| `wallClockIn`                   | `wallClockIn(date: Date, tz: string): Date`          | The same instant, shifted so the Date's _local_ getters read that zone's clock face.           |
+| `CronExpression.matchesIn`      | `matchesIn(date: Date, tz: string): boolean`         | Whether the expression fires at `date`, read in `tz`.                                          |
+| `CronExpression.nextRunAfterIn` | `nextRunAfterIn(expr, from: Date, tz): Date \| null` | The next real instant the expression fires on that zone's clock — correct across a DST change. |
+
+`wallClockIn` returns a Date that is a lie about the instant and true about the clock
+face: its epoch value is off by the zone offset. Pass it to a field comparison, never
+back to a caller.
+
+### Errors
+
+| Error                  | Thrown when                                                                                 |
+| ---------------------- | ------------------------------------------------------------------------------------------- |
+| `SchedulerError`       | Base class for everything this package throws. Catch it to catch them all.                  |
+| `UnknownTimeZoneError` | A task declares a `timezone` this runtime does not know — at registration, naming the task. |
+
 ### ScheduledTask introspection
 
 | Member             | Signature                                   | Description                                       |
@@ -525,6 +588,17 @@ The `Scheduler` facade resolves the `scheduler` container binding — a
 | `lastDurationMs`   | `get lastDurationMs(): number \| undefined` | Duration of the last run in ms.                   |
 | `isRunning`        | `get isRunning(): boolean`                  | `true` while a run is in flight.                  |
 
+## Types
+
+| Type                                    | What it is                                                                                   |
+| --------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `CronExpression`                        | The schedule string a task declares.                                                         |
+| `TaskGuard`                             | A condition deciding whether a due run actually happens — a feature flag, a leader election. |
+| `TaskHook`                              | What runs before or after a task.                                                            |
+| `ScheduleRunRecord`, `ScheduleRunStore` | One recorded run, and where the log is kept.                                                 |
+| `RunLogConfig`                          | How much of that log is retained.                                                            |
+| `OutputMailer`                          | Sending a task's output somewhere when it finishes.                                          |
+
 ## Next steps
 
 - [Queue](/docs/queue) — schedules typically dispatch jobs; the worker runs both.

package/docs/session.md

@@ -444,6 +444,12 @@ try {
 The fix is nearly always to store an identifier rather than the object, or to
 move to a server-side driver where the cookie holds only the session id.
 
+## Types
+
+`SessionDriver` is the storage contract — implement it to keep sessions somewhere the built-ins
+do not reach. `SessionPayload` is what a driver loads and saves: the id and the data bag.
+`SessionAccessor` is the request-scoped handle `ctx.session` exposes.
+
 ## Next steps
 
 - [Middleware](/docs/middleware) — where `SessionMiddleware` and `CsrfMiddleware`

package/docs/social.md

@@ -516,6 +516,16 @@ validation errors is exactly the string you forward to `?error=`.
 | `OAuthUserFetchError`           | provider message          | User-profile fetch failed.                         |
 | `AppleClientSecretError`        | Apple credentials message | Apple driver has neither a JWT nor raw key trio.   |
 
+## Types
+
+| Type                | What it is                                                                                                                   |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `OAuth2Config`      | What a provider entry in `config/services.ts` holds — id, secret, redirect URI.                                              |
+| `AppleOAuth2Config` | Apple's, which needs more: a team id, a key id, and the private key it signs with.                                           |
+| `SocialSession`     | What the driver stashes between the redirect out and the callback back.                                                      |
+| `GoogleDriver`      | Exported so a custom driver can extend it rather than reimplement OIDC.                                                      |
+| `FakeSocialDriver`  | What `Social.fake()` installs — returns a canned profile instead of exchanging a code. See [Mocking](/docs/testing/mocking). |
+
 ## Next steps
 
 - [Authentication](/docs/authentication) — establish the session after a social login.

package/docs/storage.md

@@ -626,6 +626,27 @@ Manager and exports from `zerotal/storage`:
 | `StorageProvider`        | `class`                                                         | Registers the `storage` binding.                 |
 | `DiskNotConfiguredError` | `class`                                                         | Thrown when a named disk is missing from config. |
 
+### Types
+
+The config shapes are exported, so a `config/storage.ts` can be annotated and a helper that
+builds disk options can be typed:
+
+| Type                  | What it is                                                                 |
+| --------------------- | -------------------------------------------------------------------------- |
+| `DiskConfig`          | The discriminated union of every disk config — `local` and `s3` today.     |
+| `LocalDiskConfig`     | A local disk: `root`, plus `serve` when it is reachable over HTTP.         |
+| `S3DiskConfig`        | An S3 disk: credentials, `region`, `bucket`, and an optional public `url`. |
+| `DiskServeConfig`     | How a disk is exposed over HTTP — the `serve` block `public` uses.         |
+| `StorageFilesOptions` | Options for `StorageFilesMiddleware`, which serves a disk's files.         |
+| `FakeStoredFile`      | What a faked disk records in tests, for asserting on what was written.     |
+
+`StorageError` is the base every storage failure extends, and `UnsupportedOperationError` is
+what a driver throws for something it genuinely cannot do — a local disk asked for a signed
+URL, for instance — rather than failing quietly and returning nothing.
+
+`S3Driver` is exported so a driver for another S3-compatible service can extend it rather than
+reimplement request signing.
+
 ## Next steps
 
 - [Validator](/docs/validator) — validate file uploads before storing them.

package/docs/support-policy.md

@@ -109,7 +109,19 @@ outcomes — promote, keep with a new date and the reason, or withdraw.
 
 | Package       | Now            | Reviewed by |
 | ------------- | -------------- | ----------- |
-| `@zerotal/ai` | `experimental` | **1.9.0**   |
+| `@zerotal/ai` | `experimental` | **1.11.0**  |
+
+`@zerotal/ai`'s date moved once, from 1.9.0, and the reason is the same one that made it
+experimental in the first place: **it graduates in the release after its first real users, and
+it has not had them yet.** Promoting on a date rather than on evidence is how a label becomes
+decoration — a `stable` promise is only worth making about an API that something has pushed
+against.
+
+The date is a forcing function, not a prediction. It moved once; a second move needs a better
+reason than the first, or the honest answer is to withdraw the package rather than keep
+re-dating it. Its surface triage and the tests for its SSE parser and prompt redaction are worth
+doing meanwhile, and are tracked separately — they improve the package whichever way the review
+goes, and they are what would otherwise turn the deadline into a scramble.
 
 `@zerotal/arch` held `beta` with the same date, was reviewed ahead of it, and is
 `stable` — the release that carried the promotion is the one its