@zerotal/arch 1.8.1 → 1.9.0

package/docs/helpers.md

@@ -214,6 +214,105 @@ singularize("people"); // 'person'
 tableNameFor("BlogPost"); // 'blog_posts'
 ```
 
+## Sharing helpers with the browser — `zerotal/shared`
+
+Importing `zerotal` into a client bundle drags the server in behind it. So the helpers that
+have no server in them are also published on their own entry point:
+
+```tsx
+// resources/js/pages/Trips/Index.tsx — a browser bundle
+import { pluralize, formatMoney, Str } from "zerotal/shared";
+```
+
+Everything reachable from `zerotal/shared` is pure — no `node:` imports, no `Bun` globals, no
+config, no container, no request context. Importing it pulls in these functions and nothing
+else, and a test in the framework's own suite bundles the entry point for the browser to keep
+that true.
+
+It carries `pluralize`, `singularize`, `snakeCase`, `camelCase`, `tableNameFor`, the whole
+`Str` namespace, and the formatters below.
+
+**Why it matters more than convenience.** Without it, a page that needs `pluralize` gets a
+second implementation written by hand — and the second copy is always the worse one, because
+the irregulars and the inflect-only-the-last-word rule are exactly what someone re-deriving
+it leaves out. `pluralize("supplier line")` is `"supplier lines"`; the naive rule gives
+`"suppliers line"`. One import removes the divergence rather than managing it.
+
+### Formatting both sides can agree on
+
+`Intl` is in both runtimes and does the work; the risk is that a server helper and a browser
+helper make the same decision twice. A total that reads `R 39 147` on screen and `R39,147.00`
+on the invoice looks like two different numbers to the person paying it.
+
+```typescript
+import { formatMoney, formatNumber, formatDate } from "zerotal/shared";
+
+// Minor units by default — how a column that must not lose a cent stores it.
+formatMoney(3_914_700, { currency: "ZAR", locale: "en-ZA" });
+formatMoney(39_147, { currency: "USD", locale: "en-US", minorUnits: false });
+
+formatNumber(39147.5, { locale: "en-GB", maximumFractionDigits: 1 }); // '39,147.5'
+
+formatDate("2026-08-28T21:30:00Z", { locale: "en-ZA", timeZone: "Africa/Johannesburg" });
+```
+
+Pass `locale` explicitly wherever the two sides must match. Left off, it is the machine's on
+the server and the reader's in the browser, and those are not the same. Pass `timeZone` for
+the same reason: a machine on UTC and a reader in Cape Town disagree about which _day_ an
+11pm booking happened on, and that is the shape the bug takes.
+
+Each formatter takes its own options interface, all extending `FormatOptions` (which carries
+`locale`):
+
+| Interface       | Used by        | Adds                                                                   |
+| --------------- | -------------- | ---------------------------------------------------------------------- |
+| `FormatOptions` | — (the base)   | `locale`                                                               |
+| `MoneyOptions`  | `formatMoney`  | `currency` (required), `minorUnits` (default `true`), `fractionDigits` |
+| `NumberOptions` | `formatNumber` | `minimumFractionDigits`, `maximumFractionDigits`                       |
+| `DateOptions`   | `formatDate`   | `dateStyle`, `timeStyle`, `timeZone`                                   |
+
+`formatDate` returns an empty string for an unparseable value rather than `Invalid Date`, so
+a bad timestamp renders as a blank rather than as words in the middle of a page.
+
+## Outbound HTTP — Http
+
+`Http` is the fluent client for calling another service. It is `fetch` with the things you would
+otherwise write around every call — auth, timeout, retry, JSON — already there, and one place to
+intercept in a test:
+
+```typescript fragment
+import { Http } from "zerotal/http";
+
+const response = await Http.withToken(apiKey).timeout(5_000).retry(3).post("/charges", { amount });
+
+if (response.ok) {
+  const charge = await response.json<{ id: string }>();
+}
+```
+
+Every verb — `get`, `post`, `put`, `patch`, `delete`, `head` — returns a `PendingRequest`, which
+is awaitable _and_ chainable: `withHeaders`, `withToken`, `withBasicAuth`, `acceptJson`,
+`timeout`, `retry`, `withJson`, `withFormData`. Awaiting it gives an `HttpClientResponse` with
+`status`, `ok`, `headers`, `json()`, `text()` and `blob()`.
+
+**A failed response is not a thrown error by default.** A 404 is an answer, and an integration
+that treats every non-2xx as an exception cannot tell "no such customer" from "the service is
+down". Call `.throw()` on the response when you do want the non-2xx to raise — it throws
+`HttpClientError`, which carries the response so a handler can still read the status.
+
+```typescript fragment
+// Let a 404 be a value, and anything else be a problem.
+const response = await Http.get(`/customers/${id}`);
+if (response.status === 404) return null;
+return response.throw().json<Customer>();
+```
+
+In tests, `Http.fake()` intercepts all of it — see [Mocking](/docs/testing/mocking#outbound-http).
+
+`Http` is a class rather than a facade, so a request is made with the same import everywhere.
+`QueryInput` is what a query object may hold, and `PaginatedData` the shape of a paginated body
+when the other end returns one.
+
 ## Objects — deepMerge
 
 Recursively merge an override object onto a base, lodash-style: nested plain

package/docs/i18n.md

@@ -509,6 +509,11 @@ res.assertSee("Votre panier est vide");
 
 See [Configuration](#configuration) for the `config/i18n.ts` fields.
 
+## Types
+
+`LocaleResolver` decides the locale for a request — the header, a route param, or the signed-in
+user's preference. `TranslatorOptions` configures the translator itself.
+
 ## Next steps
 
 - [Validator](/docs/validator) — pair form validation with translated messages.

package/docs/inertia/props.md

@@ -25,6 +25,70 @@ import { Inertia } from "@zerotal/inertia";
 > `defer()` loads after first paint; `merge()`/`scroll()` combine new data with what
 > the client already has.
 
+## Page props are page source
+
+**A page receives a projection chosen by its route, never a model — unless that model has
+declared which of its columns are safe to publish.**
+
+Everything you hand to `inertia()` is serialised into the HTML document, or returned as JSON
+on an XHR visit. Anyone who views source reads all of it. That is how the protocol works, and
+it is fine right up to the moment a model goes through it:
+
+```ts fragment
+// in a controller
+return inertia("Trips/Show", { trip }); // ← every column of the row, in the page
+```
+
+`trip.toJSON()` ships the whole row. If that row has an internal cost, a margin, a supplier
+reference or a note somebody left about the customer, all of it is now on the customer's own
+screen. Nothing fails, nothing logs, and the page looks right. This is the one mistake on this
+page that does not announce itself.
+
+### Declare the boundary at the model
+
+The ORM's `hidden` and `visible` lists are honoured by `toJSON()`, which is exactly what
+serialises a prop — so declaring them once at the model covers every route that ever passes it:
+
+```ts fragment
+import { Model, type Columns } from "zerotal/orm";
+
+class Trip extends Model {
+  // Never leaves the server, whoever passes this model to whatever page.
+  static hidden: Columns<Trip>[] = ["cost_cents", "markup_percent", "internal_notes"];
+}
+```
+
+`visible` is the allow-list form and takes precedence: state the columns a page may have, and a
+column added to the table later is private by default rather than published by default.
+
+In development, passing a model that declares neither list writes a warning naming the model and
+the number of fields it is about to publish. It fires once per model class and goes quiet as soon
+as either list exists.
+
+### When a route needs its own shape
+
+A `hidden` list is one decision for the whole app. Where two audiences need different columns of
+the same model, project per route and keep the dangerous fields out of the client-facing shape
+entirely:
+
+```ts fragment
+// in a controller
+function forCustomer(trip: Trip) {
+  return { id: trip.id, title: trip.title, total_cents: trip.total_cents };
+}
+
+function forOps(trip: Trip, options: { showCost: boolean }) {
+  return {
+    ...forCustomer(trip),
+    // Absent, not zeroed. A zero looks like a fact; a missing key cannot be misread.
+    ...(options.showCost ? { cost_cents: trip.cost_cents } : {}),
+  };
+}
+```
+
+Prefer omitting a field over blanking it. A `cost_cents: 0` in page source reads as "this trip
+cost us nothing", and somebody will eventually believe it.
+
 ## Partial reloads
 
 On a visit to the _same page_, the client can request a subset of props with `only` / `except`.
@@ -501,6 +565,12 @@ still override one, and no page is forced to pass it.
 - **Before you rebuild the registry**, every name and every prop bag compiles, as
   it always did.
 
+## Types
+
+`PageObject` is what Inertia serialises into the page — component, props, url and version.
+`MergeConfig` and `ScrollConfig` configure `merge()` and `scroll()`, and `PaginatorLike` is what
+`scroll()` accepts from a paginator so the ORM's own and a hand-built one both work.
+
 ## Next steps
 
 - [Inertia overview](/docs/inertia) — the guide's front page and the rest of the sections.

package/docs/lock.md

@@ -447,6 +447,21 @@ sees an isolated, deterministic lock table with no network or file I/O.
 | `exists()`       | `exists(key: string): Promise<boolean>`                                     | `true` if the lock is currently held.               |
 | `dispose?()`     | `dispose?(): void`                                                          | Release background resources (timers, connections). |
 
+### Types
+
+| Type                | What it is                                                                         |
+| ------------------- | ---------------------------------------------------------------------------------- |
+| `LockedCallback<T>` | What `try` and `block` run while holding the lock.                                 |
+| `TryOptions`        | `try`'s options — the TTL and whether a failure throws or returns.                 |
+| `RefreshOptions`    | How a long-running hold extends its own TTL rather than letting it lapse mid-work. |
+
+The three built-in drivers are exported under their own names, so a custom driver can wrap one
+rather than reimplement it: `MemoryLockDriver` (single process — the default, and wrong the
+moment there are two), `SqliteLockDriver` (a file every process on the box can see) and
+`RedisLockDriver` (across machines).
+
+Picking the wrong one fails in the way locks always do: not at all, until there are two workers.
+
 ## Next steps
 
 - [Scheduler](/docs/scheduler#preventing-overlapping-runs) — `withoutOverlapping` builds on the same idea for cron tasks.

package/docs/logger.md

@@ -171,6 +171,44 @@ export default LoggingConfig({
 });
 ```
 
+### Writing your own channel
+
+A channel is one method. Implement `LogChannel` and register it as a driver when the five
+built-ins do not reach where you need entries to go — a hosted log service, a socket, a table:
+
+```typescript
+import type { LogChannel, LogEntry } from "zerotal/logger";
+
+class WebhookChannel implements LogChannel {
+  constructor(private readonly url: string) {}
+
+  async write(entry: LogEntry): Promise<void> {
+    // Failures are swallowed on purpose: a logging sink that throws turns a
+    // warning into an outage, and the entry it was carrying is lost either way.
+    await fetch(this.url, { method: "POST", body: JSON.stringify(entry) }).catch(() => {});
+  }
+}
+```
+
+The built-ins implement the same interface and are exported, so a custom channel can wrap one
+rather than reimplement it — `StackChannel` is itself only a fan-out over other channels.
+
+### Types
+
+| Type            | What it is                                                                     |
+| --------------- | ------------------------------------------------------------------------------ |
+| `LogLevel`      | `"debug" \| "info" \| "warn" \| "error" \| "fatal"` — the severity ladder.     |
+| `LogEntry`      | One record: level, message, context, scope, timestamp, and any captured error. |
+| `LogChannel`    | The one-method sink contract: `write(entry): Promise<void>`.                   |
+| `BoundLogger`   | A logger pinned to a channel and/or a fixed context bag.                       |
+| `ChannelConfig` | The discriminated union of the five driver configs below.                      |
+| `LoggerOptions` | What `LoggingConfig()` accepts.                                                |
+| `TableData`     | Rows for `Log.table()`.                                                        |
+
+The five built-in channels are exported under their own names — `ConsoleChannel`,
+`SingleChannel`, `DailyChannel`, `StackChannel`, `NullChannel` — each matching the `driver`
+value in the table above.
+
 ## The Log facade
 
 `Log` is a static proxy over the `LogManager` singleton. Use it anywhere —

package/docs/migrations.md

@@ -81,6 +81,13 @@ bun zt migrate:rollback
 bun zt migrate:status
 ```
 
+`bun zt doctor` warns when migrations on disk have not run, and names them. It is a warning
+rather than a failure — pending migrations are the ordinary state of a checkout that just
+pulled — but it is the cheapest moment to hear about them: the alternative is finding out from
+a request that fails with `no such table`, an error whose stack is entirely framework frames.
+The [development error page](/docs/errors#missing-tables-and-columns) answers the same question
+after the fact, and can run them for you.
+
 `migrate --fresh`, `migrate:fresh` and `migrate:refresh` all do the same thing:
 roll everything back through each migration's `down()`, then re-run from scratch.
 `migrate:refresh` exists because that is the name the command has elsewhere,
@@ -521,6 +528,46 @@ test("backfills a slug for every existing post", async () => {
 | `hasTable`          | `hasTable(table: string): Promise<boolean>`                        | Whether a table exists.               |
 | `hasColumn`         | `hasColumn(table: string, column: string): Promise<boolean>`       | Whether a column exists.              |
 
+### Types
+
+The builders a migration's `up()` receives, and the shapes they take:
+
+| Type                     | What it is                                                                         |
+| ------------------------ | ---------------------------------------------------------------------------------- |
+| `ColumnBuilder`          | What every `table.string(…)` returns — the chain that adds modifiers.              |
+| `ColumnOptions`          | Length, precision and the other per-type settings a column accepts.                |
+| `ColumnShorthand`        | The short forms (`"string"`, `"integer"`, …) accepted where a full builder fits.   |
+| `ForeignIdColumnBuilder` | What `table.foreignId(…)` returns, adding `.constrained()` to the chain.           |
+| `ForeignKeyBuilder`      | The `.references(…).on(…)` chain, and where `onDelete` / `onUpdate` are set.       |
+| `FKAction`               | `"cascade" \| "restrict" \| "set null" \| "no action"` — what a FK does on change. |
+| `TableOptions`           | Table-level settings: engine, charset, and whether it is temporary.                |
+
+### Running migrations yourself
+
+`MigrationRunner` is the class behind `zt migrate`. Reach for it when you need the runner
+somewhere a command cannot go — a test harness, a deploy script, a tenant provisioner that
+migrates a database it has just created:
+
+```typescript fragment
+import { MigrationRunner } from "@zerotal/orm";
+
+const runner = new MigrationRunner({ connection });
+const ran = await runner.run(entries); // names of the migrations applied
+const status = await runner.status(entries); // ran / pending, per migration
+```
+
+| Type              | What it is                                                                 |
+| ----------------- | -------------------------------------------------------------------------- |
+| `MigrationEntry`  | One migration handed to the runner: its name and its instance.             |
+| `MigrationRecord` | A row of the `migrations` table — name, batch, and when it ran.            |
+| `MigrationStatus` | What `status()` reports per migration: whether it ran, and in which batch. |
+| `MigrationError`  | Thrown when a migration fails, carrying which one and what it was doing.   |
+
+`runner.willRollBackOnFailure` says whether this engine has transactional DDL. On MySQL it is
+false — every DDL statement implicitly commits, so a migration that fails part-way leaves the
+half that succeeded. `zt migrate` warns about this before it starts, while taking a backup is
+still an option.
+
 ## Next steps
 
 - [ORM](/docs/orm) — the models your migrations build tables for.

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,45 @@ 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.
+
+> **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
 

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.