@zerotal/arch 1.7.4 → 1.8.0

package/docs/monitor.md

@@ -136,7 +136,7 @@ Everything is driven by core's `FrameworkEvents` bus, the same synchronous subst
 
 For anything that does not flow through the bus — a deploy marker, or a third-party call you make without the `Http` client — the `Monitor` facade records it directly and takes precedence. Every `Monitor.*` call is a safe no-op until the provider boots, so you can call it from anywhere without guarding.
 
-```ts
+```ts fragment
 import { Monitor } from "@zerotal/monitor";
 
 Monitor.recordDeploy(gitSha);
@@ -187,7 +187,7 @@ export default MonitorConfig({
 
 The `auth` callback receives the authenticated user (or `undefined`) and returns whether to allow access. The default permits access only outside production, which is safe for local development but means **you must set an `auth` gate before deploying** — otherwise the panel, which exposes request payloads, user identities, and logs, is unreachable in production by default but wide open the moment you flip the environment. Gate it to an admin role:
 
-```ts
+```ts fragment
 auth: (user) => user?.role === "admin",
 ```
 
@@ -197,7 +197,7 @@ The same gate protects the JSON export route. The Prometheus endpoint is deliber
 
 The panel evaluates threshold alerts every fifteen seconds against the live snapshot. Out of the box it watches four signals: the 5xx error rate, p95 latency, total pending jobs across queues, and transaction rollbacks. Tune the limits through `alertThresholds`:
 
-```ts
+```ts fragment
 alertThresholds: { errorRatePct: 5, p95Ms: 2000, queuePending: 500, rolledBackInWindow: 10 },
 ```
 
@@ -205,7 +205,7 @@ Alerts are edge-triggered — each one fires once when it crosses its threshold
 
 When an alert fires it is logged, recorded so the Alerts tab can show it with its full context, and dispatched. There are two ways to be paged. The simplest is a webhook — set `alertWebhook` to a Slack-compatible URL and each firing is POSTed as JSON, no extra dependency. For richer routing, register a handler and wire it to notifications, PagerDuty, or anything else:
 
-```ts
+```ts fragment
 import { onAlert } from "@zerotal/monitor";
 
 onAlert((alert) => {
@@ -268,7 +268,7 @@ The panel owns the shell, the time-range selector, the storage and the retention
 
 A section is _described_, not rendered. The contributor returns stats and tables; the panel draws them. That keeps the panel coherent no matter who contributed a section, and means the contributing package needs no JSX and no dependency on `@zerotal/monitor`:
 
-```ts
+```ts fragment
 // In a contributing provider's onBooting()
 interface MonitorHost {
   enabled(id: string): boolean;
@@ -311,7 +311,7 @@ This is the other half of how the recorders already work. A package writes its m
 
 To keep a contributor installed but drop its section, name it in `sections`:
 
-```ts
+```ts fragment
 // config/monitor.ts
 export default MonitorConfig({
   sections: { scheduler: false },

package/docs/notifications.md

@@ -137,7 +137,7 @@ sends one real message and prints whatever the server said.
 Extend `Notification`, declare `channels()`, then implement a `to*()` method for
 each declared channel:
 
-```ts
+```ts fragment
 // app/notifications/OrderShippedNotification.ts
 import { Notification, MailMessage } from "@zerotal/notifications";
 import type { Notifiable } from "@zerotal/notifications";
@@ -188,7 +188,7 @@ export class OrderShippedNotification extends Notification {
 `channels()` receives the recipient, so a single notification can respect each
 person's preferences instead of forcing every recipient down the same path:
 
-```ts
+```ts fragment
 // app/notifications/OrderShippedNotification.ts
 channels(user: Notifiable) {
   // Everyone gets the inbox copy; how they're alerted is their choice.
@@ -202,7 +202,7 @@ common case, and `channels()` with no arguments stays valid.
 A recipient can also redirect an individual channel without any notification
 knowing about it, by implementing `routeNotificationFor`:
 
-```ts
+```ts fragment
 // app/models/User.ts
 routeNotificationFor(channel: string) {
   // Invoices go to the billing contact; everything else to the usual address.
@@ -221,7 +221,7 @@ afterwards as a `NotificationDispatchError`. A Slack webhook returning a 500 doe
 not cost the recipient the email and the stored row that were declared alongside
 it.
 
-```ts
+```ts fragment
 // in a controller or service
 try {
   await Notify.send(user, new OrderShippedNotification(order));
@@ -289,7 +289,7 @@ export class User extends AuthUser.using(Notifiable) {
 }
 ```
 
-```ts
+```ts fragment
 // in a controller or service
 await user.notify(new OrderShippedNotification(order)); // send now
 await user.notifyLater(new OrderShippedNotification(order)); // queue for background
@@ -301,7 +301,7 @@ await user.markNotificationsAsRead();
 
 ### Via the Notify facade
 
-```ts
+```ts fragment
 // in a controller or service
 import { Notify } from "@zerotal/notifications";
 
@@ -315,7 +315,7 @@ await Notify.queue(user, new OrderShippedNotification(order)); // queue for back
 independent: one failing does not stop the rest, and the errors are reported
 together at the end.
 
-```ts
+```ts fragment
 // in a controller or service
 const admins = await User.where("role", "admin").get();
 await Notify.sendMany(admins, new LowStockNotification(product));
@@ -326,7 +326,7 @@ await Notify.sendMany(admins, new LowStockNotification(product));
 Some notifications go to a destination rather than a user — an on-call address, a
 webhook, a number typed into a form. `route()` takes the destinations directly:
 
-```ts
+```ts fragment
 // in a controller or service
 await Notify.route({ mail: "ops@acme.test" }).notify(new DeployFinished(build));
 
@@ -343,7 +343,7 @@ normally declares only transport channels.
 
 ### Via the NotificationManager directly
 
-```ts
+```ts fragment
 // in a service
 import { NotificationManager } from "@zerotal/notifications";
 import { Application } from "zerotal";
@@ -361,7 +361,7 @@ to the notifiable's `email`, so you rarely set `to()`. The mail channel is
 built-in and works on the `log` driver out of the box; switch to `smtp` or
 `resend` in `config/notifications.ts`.
 
-```ts
+```ts fragment
 // in a Notification
 import { MailMessage } from "@zerotal/notifications";
 import type { Notifiable } from "@zerotal/notifications";
@@ -379,7 +379,7 @@ Attach files with `attach()` when you already have the bytes, or `attachFile()`
 to read one from disk. `embed()` places an image in the body rather than listing
 it as a download — reference it from your HTML as `cid:the-id`:
 
-```ts
+```ts fragment
 // in a Notification
 async toMail(_n: Notifiable): Promise<MailMessage> {
   return (await new MailMessage()
@@ -416,7 +416,7 @@ Read and mark stored notifications through the [mixin helpers](#via-the-notifiab
 Inbox reads return the 100 most recent rows unless told otherwise. Pass a limit
 and offset to page, or `limit: 0` for everything:
 
-```ts
+```ts fragment
 // in a controller
 const page = await user.notifications({ limit: 20, offset: 40 });
 const badge = await user.unreadNotificationCount(); // counts without loading rows
@@ -430,7 +430,7 @@ past an age threshold; add `--all` to include unread ones. Schedule it.
 
 Implement `toSlack(notifiable)` returning a `SlackMessage`:
 
-```ts
+```ts fragment
 // in a Notification
 import type { SlackMessage } from "@zerotal/notifications";
 
@@ -453,7 +453,7 @@ channel raises a `NotificationChannelNotConfiguredError` naming the notification
 Implement `toSms(notifiable)` returning an `SmsMessage`. Supported drivers:
 `twilio` and `vonage`.
 
-```ts
+```ts fragment
 // in a Notification
 import type { SmsMessage } from "@zerotal/notifications";
 
@@ -474,7 +474,7 @@ Push a notification to a connected client in real time via
 returning a `BroadcastMessage` (or a plain data object), and optionally
 `broadcastType()` to set the wire `type`:
 
-```ts
+```ts fragment
 // app/notifications/InvoicePaid.ts
 import { Notification, BroadcastMessage } from "@zerotal/notifications";
 import type { Notifiable } from "@zerotal/notifications";
@@ -504,7 +504,7 @@ The broadcast channel works like this:
   `private-notifications.{id}` by default. Override per notifiable with
   `receivesBroadcastNotificationsOn(): string`:
 
-  ```ts
+  ```ts fragment
   // app/models/User.ts
   class User extends Model {
     receivesBroadcastNotificationsOn() {
@@ -521,14 +521,14 @@ The broadcast channel works like this:
   stored notification.
 - **Authorize** the per-user channel in `routes/channels.ts`:
 
-  ```ts
+  ```ts fragment
   // routes/channels.ts
   Broadcast.channel("notifications.[id]", (user, id) => String(user.id) === id);
   ```
 
 - **Client** (any Pusher-compatible client):
 
-  ```ts
+  ```ts fragment
   // in your frontend
   Socket.private(`notifications.${userId}`).listen("notification", (n) => {
     console.log(n.type, n);
@@ -541,7 +541,7 @@ A broadcast goes out inline, which is the point of the channel. When one fans ou
 widely enough that the request should not wait for it, `.onQueue(name)` hands it
 to a worker instead — at the cost of arriving whenever that worker picks it up.
 
-```ts
+```ts fragment
 // in a Notification
 toBroadcast(_n: Notifiable) {
   return new BroadcastMessage({ id: this.report.id }).onQueue("broadcasts");
@@ -554,7 +554,7 @@ The five built-in channels are registered the same way yours are, so adding a
 channel is not a special case. Register a factory under a name, and any
 notification can declare it:
 
-```ts
+```ts fragment
 // app/providers/DiscordChannelProvider.ts
 import type { NotificationChannel, Notifiable } from "@zerotal/notifications";
 
@@ -576,7 +576,7 @@ const notifications = this.app.container.makeSync("notifications");
 notifications.extend("discord", () => new DiscordChannel());
 ```
 
-```ts
+```ts fragment
 // app/notifications/DeployFinished.ts
 channels() {
   return ["database", "discord"];
@@ -612,7 +612,7 @@ notification you queue.
 `app/notifications/` are found automatically. One that lives elsewhere must
 register itself:
 
-```ts
+```ts fragment
 // app/domain/billing/InvoiceOverdue.ts
 import { NotificationRegistry } from "@zerotal/notifications";
 
@@ -627,7 +627,7 @@ By default a notification's own enumerable fields are serialized, which covers a
 constructor that assigns plain values. When it holds something JSON cannot carry
 — a model instance, a `Map`, a closure — say how to shrink and rebuild it:
 
-```ts
+```ts fragment
 // app/notifications/InvoicePaid.ts
 export class InvoicePaid extends Notification {
   constructor(private invoice: Invoice) {
@@ -649,7 +649,7 @@ export class InvoicePaid extends Notification {
 `NotificationFake` swaps the `"notifications"` container binding for an
 in-memory recorder, so assertions run without hitting any real channel:
 
-```ts
+```ts fragment
 // tests/orders.test.ts
 import { NotificationFake } from "@zerotal/notifications";
 import { describe, it, beforeEach, afterEach } from "bun:test";

package/docs/orm/casts.md

@@ -58,7 +58,7 @@ export class Post extends Model {
 `json` and `array` encode on write and parse on read, in both directions, so a value
 round-trips as the type you gave it — including a bare scalar:
 
-```typescript
+```typescript fragment
 setting.value = "62812345678"; // stored as "62812345678", read back as a string
 setting.value = "051001"; // a branch code keeps its leading zero
 setting.value = { plan: "pro" }; // objects and arrays as you would expect
@@ -79,7 +79,7 @@ was a numeric string may come back as a number; coerce on read where it matters.
 Reads and writes the value as a string with exactly `N` decimal places. Useful
 for currency, where you want to avoid floating-point drift:
 
-```typescript
+```typescript fragment
 // app/models/Product.ts
 @column({ type: "number", cast: "decimal:2" }) price!: string;
 // DB stores "9.99" — the model reads it back as the string "9.99".
@@ -94,7 +94,7 @@ for currency, where you want to avoid floating-point drift:
 Behaves like `'datetime'` on read (constructs a [Carbon](/docs/carbon)) and
 serializes to an ISO 8601 string on write:
 
-```typescript
+```typescript fragment
 // app/models/Booking.ts
 @column({ type: "datetime", cast: "immutable_datetime" }) lockedAt?: Carbon;
 
@@ -112,7 +112,7 @@ Stores and retrieves the raw enum value (the underlying string or number);
 TypeScript narrows the property type. The cast itself is a pass-through, so pair
 it with `enumValues` to document the enum:
 
-```typescript
+```typescript fragment
 // app/models/Post.ts
 enum Status {
   Draft     = "draft",
@@ -132,7 +132,7 @@ The column stores an opaque AES-256-GCM payload keyed by `APP_KEY`; the property
 holds the value you assigned. Nothing in between — your code, validation,
 `$dirty` — has to know:
 
-```typescript
+```typescript fragment
 // app/models/Client.ts
 @column("encrypted", { nullable: true }) idNumber?: string;
 
@@ -150,7 +150,7 @@ that ciphertext outgrows its plaintext.
 
 For several columns at once, list them instead — it means exactly the same thing:
 
-```typescript
+```typescript fragment
 class Client extends BaseModel {
   static encryptable = ["idNumber", "passportNumber"];
 }
@@ -160,7 +160,7 @@ A column in that list whose `@column({ type })` is `json` encrypts as
 `encrypted:json` automatically, so the structure survives the round trip rather
 than reaching the cipher as `"[object Object]"`.
 
-Unlike [`hashable`](/docs/orm/index), this is reversible and does not touch the
+Unlike [`hashable`](/docs/orm), this is reversible and does not touch the
 instance: after `save()`, `client.idNumber` still reads as the plaintext you set.
 `$dirty` therefore compares plaintext, and an unchanged column is not rewritten
 with a fresh IV on every unrelated save.
@@ -195,7 +195,7 @@ one, and re-encrypt it on the next save, losing the original for good.
 Pass an object with `get` and `set` functions for complete control over
 serialization:
 
-```typescript
+```typescript fragment
 // app/models/Place.ts
 interface GeoPoint { lat: number; lng: number }
 
@@ -232,7 +232,7 @@ export class MoneyCast extends Cast<number> {
 }
 ```
 
-```typescript
+```typescript fragment
 // app/models/Invoice.ts
 import { column } from "@zerotal/orm";
 import { MoneyCast } from "../casts/MoneyCast.ts";
@@ -243,7 +243,7 @@ import { MoneyCast } from "../casts/MoneyCast.ts";
 For JSON columns the ORM ships ready-made helpers that optionally hydrate the
 parsed value into a class:
 
-```typescript
+```typescript fragment
 // app/models/Customer.ts
 import { column } from "@zerotal/orm";
 import { json, objectOf, arrayOf } from "@zerotal/orm";
@@ -263,7 +263,7 @@ import { Address } from "../value-objects/Address.ts";
 An alternative to `@column()` for columns you don't declare directly (e.g. from
 an external schema, a view, or a generated table):
 
-```typescript
+```typescript fragment
 // app/models/Post.ts
 @table("posts")
 export class Post extends Model {
@@ -300,7 +300,7 @@ does not mark the column dirty and won't be persisted on the next `save()`.
 Enable `reactiveCasts` to make `json` and `array` columns use a reactive proxy
 that tracks deep mutations:
 
-```typescript
+```typescript fragment
 // app/models/Post.ts
 @table("posts")
 export class Post extends Model {
@@ -318,7 +318,7 @@ await post.save(); // persists the updated meta
 
 Without `reactiveCasts`, replace the whole value to ensure dirty tracking:
 
-```typescript
+```typescript fragment
 // in a controller
 post.meta = { ...post.meta, views: (post.meta.views as number) + 1 };
 await post.save();
@@ -359,7 +359,7 @@ Cast options accepted by `@column()`:
 
 ## Next steps
 
-- [ORM](/docs/orm/index) — defining models and columns.
+- [ORM](/docs/orm) — defining models and columns.
 - [Queries](/docs/orm/queries) — the query builder and scopes.
 - [Serialization](/docs/orm/serialization) — control JSON output.
 - [Carbon](/docs/carbon) — the date type behind `datetime` casts.

package/docs/orm/factories.md

@@ -37,7 +37,7 @@ This writes `database/factories/PostFactory.ts`. A factory is `Factory.define(Mo
 definition)`, where the definition callback receives the built-in [`fake`](#the-fake-helper)
 helper and returns the model's default attributes:
 
-```typescript
+```typescript fragment
 // database/factories/PostFactory.ts
 import { Factory } from "@zerotal/testing";
 import { Post } from "../../app/models/Post.ts";
@@ -56,7 +56,7 @@ supply them at create time with [`.for()`](#relating-models) or an override.
 
 ## Creating records
 
-```typescript
+```typescript fragment
 // in a test or seeder
 // Persist one record → Promise<Post>
 const post = await PostFactory.create();
@@ -93,7 +93,7 @@ wins).
 `.for(parent)` injects the parent's primary key as a foreign key, derived from the
 parent's class name (`User` → `userId`):
 
-```typescript
+```typescript fragment
 // in a test or seeder
 const user = await UserFactory.create();
 
@@ -114,7 +114,7 @@ base factory stays reusable.
 Force the created instance into a model state via `forceState()` (bypassing guards
 and transition callbacks — see [Lifecycle & Events](/docs/orm/lifecycle)):
 
-```typescript
+```typescript fragment
 // in a test or seeder
 const expired = await SubscriptionFactory.state("expired").create();
 ```
@@ -123,7 +123,7 @@ const expired = await SubscriptionFactory.state("expired").create();
 
 Run logic after each instance is saved — e.g. attaching related records:
 
-```typescript
+```typescript fragment
 // in a test or seeder
 const user = await UserFactory.afterCreate(async (u) => {
   await PostFactory.for(u).count(3).create();
@@ -138,7 +138,7 @@ needs the full lifecycle to fire:
 > **Note** — Suppressing hooks keeps seeding side-effect free (no logs, emails, or
 > queued jobs). Call `dispatchEvents()` to let observers and hooks run.
 
-```typescript
+```typescript fragment
 // in a test
 // Silent — no "user registered" side effects:
 await UserFactory.count(20).create();
@@ -150,7 +150,7 @@ Queue.assertDispatched(WelcomeEmailJob);
 
 ## In seeders
 
-```typescript
+```typescript fragment
 // database/seeders/DatabaseSeeder.ts
 import { Seeder } from "@zerotal/orm";
 import { UserFactory } from "../factories/UserFactory.ts";
@@ -172,7 +172,7 @@ See [Seeding](/docs/seeding) for running seeders.
 
 Factories are the standard way to arrange database state in a test:
 
-```typescript
+```typescript fragment
 // in a test
 import { UserFactory } from "../../database/factories/UserFactory.ts";
 

package/docs/orm/index.md

@@ -59,7 +59,9 @@ import { DatabaseConfig } from "@zerotal/orm";
 import { env } from "zerotal";
 
 export default DatabaseConfig({
-  driver: env("DB_DRIVER", "sqlite"), // 'sqlite' | 'postgres' | 'mysql'
+  // One of 'sqlite' | 'postgres' | 'mysql', written literally: the field is that
+  // union, and `env()` returns a plain string. Scaffolding writes your choice here.
+  driver: "sqlite",
   url: env("DATABASE_URL", "./database/db.sqlite"),
 
   // PostgreSQL:  'postgres://user:pass@localhost:5432/mydb'
@@ -101,7 +103,7 @@ export default DatabaseConfig({
 
 Every model is configured with the `@table()` decorator. It accepts a fluent chain or an options object — both styles are equivalent:
 
-```typescript
+```typescript fragment
 // app/models/Post.ts
 import { Model, column, table } from "@zerotal/orm";
 
@@ -143,7 +145,7 @@ Timestamps are **on by default**, so `@table("ledger")` alone still writes `crea
 `updated_at`. For an append-only table whose migration creates neither column, say so —
 otherwise the first save fails with `table ledger has no column named updated_at`:
 
-```typescript
+```typescript fragment
 @(table("ledger").withoutTimestamps())
 export class LedgerEntry extends Model {
   /* … */
@@ -173,7 +175,7 @@ export class LedgerEntry extends Model {
 
 Declare typed columns. Accepts a shorthand cast string or a full options object:
 
-```typescript
+```typescript fragment
 // in a model class body
 import { column } from "@zerotal/orm";
 
@@ -220,7 +222,7 @@ fails at the first `.diffForHumans()` or arithmetic.
 
 Declare constraints on the column and schema generation emits them, so `migrate:generate` produces a schema with the guarantees your application depends on rather than a bare set of columns:
 
-```typescript
+```typescript fragment
 @column({ unique: true }) idempotencyKey!: string;   // unique index
 @column({ index: true })  status!: string;           // plain index
 ```
@@ -233,7 +235,7 @@ Reusable model behaviour ships as **mixins** — soft deletes, state machines, t
 roles, permissions, notifications, tenancy, auditing. A model opts into the ones it wants with the
 `Model.using(...)` static, so a model that does not use a feature does not carry its API:
 
-```typescript
+```typescript fragment
 import { Model, SoftDeletes } from "@zerotal/orm";
 import { Authenticatable, Roles, Permissions } from "@zerotal/auth";
 
@@ -274,7 +276,7 @@ The mixins the framework ships:
 `using` composes onto whatever class you call it on, not onto `Model` specifically, so an
 app-level base model can carry its own configuration and still take mixins:
 
-```typescript
+```typescript fragment
 class AppModel extends Model {
   static override primaryKey = "uuid";
 }
@@ -324,7 +326,7 @@ in `ctx.body()`. To allow columns through, you opt in explicitly.
 Any attribute not permitted by the active list throws `MassAssignmentError` (it is
 **not** silently dropped), so a mistake surfaces loudly instead of quietly failing:
 
-```typescript
+```typescript fragment
 // app/models/Post.ts
 @table("posts")
 export class Post extends Model {
@@ -342,7 +344,7 @@ export class Post extends Model {
 
 Use the `Columns<T>` utility for compile-time safety against typos:
 
-```typescript
+```typescript fragment
 // app/models/Post.ts
 import type { Columns } from "@zerotal/orm";
 
@@ -353,7 +355,7 @@ static fillable: Columns<Post>[] = ["title", "body", "status"];
 Declare `fillable` as a literal tuple (`as const`) and `create()` narrows its payload to
 exactly those columns:
 
-```typescript
+```typescript fragment
 @table("customers")
 export class Customer extends Model {
   static fillable = ["name", "email"] as const;
@@ -378,7 +380,7 @@ mistake from a runtime `MassAssignmentError` to a compile error.
 For data you construct yourself (seeders, factories, framework-internal writes)
 the guard is just friction. Bypass it deliberately:
 
-```typescript
+```typescript fragment
 // Per call — skip the guard for one write:
 role.forceFill({ name, guard });
 await Role.forceCreate({ name, guard });
@@ -407,7 +409,7 @@ An explicit `fillable` / `guarded` list is always honoured, even under a global
 
 ### fill instance method
 
-```typescript
+```typescript fragment
 // in a controller
 post.fill({ title: "New title", body: "Updated body" }); // throws if a key isn't fillable
 await post.save();
@@ -421,7 +423,7 @@ await post.save();
 
 Fields listed in `hashable` are automatically hashed with `Bun.password.hash()` (bcrypt) before every `INSERT`, and on `UPDATE` only when the value has changed since the last load:
 
-```typescript
+```typescript fragment
 // app/models/User.ts
 @table("users")
 export class User extends Model {
@@ -443,14 +445,14 @@ const ok = await Bun.password.verify(candidate, user.password);
 
 `dispatchesEvents` connects ORM lifecycle hooks to the application event bus without wiring every observer manually. Declare a map from lifecycle event names to event classes:
 
-```typescript
+```typescript fragment
 // app/events/UserCreated.ts
 export class UserCreated {
   constructor(public user: User) {}
 }
 ```
 
-```typescript
+```typescript fragment
 // app/models/User.ts
 @table("users")
 export class User extends Model {
@@ -466,7 +468,7 @@ export class User extends Model {
 
 Each event class is constructed with the model instance as its first argument and emitted on the container's event bus (a no-op when no bus is bound, so it's safe in standalone ORM use). Subscribe anywhere:
 
-```typescript
+```typescript fragment
 // app/listeners/sendWelcome.ts
 import { Events } from "zerotal";
 import { UserCreated } from "#app/events/UserCreated.ts";
@@ -506,7 +508,7 @@ export class Post extends Model {
 
 ## Full model example
 
-```typescript
+```typescript fragment
 // app/models/Post.ts
 import { Model, column, table, hasMany, belongsTo } from "@zerotal/orm";
 import type { Columns } from "@zerotal/orm";
@@ -557,7 +559,7 @@ worth knowing: `UserFactory.create()` writes the row without firing `creating`,
 jobs. A test asserting on a side-effect of creation therefore sees nothing —
 and reads as a bug in your observer rather than in the test.
 
-```typescript
+```typescript fragment
 // tests/models/User.test.ts
 import { test } from "bun:test";
 import { QueueFake } from "@zerotal/queue";
@@ -578,7 +580,7 @@ test("creating a user queues the welcome email", async () => {
 them against the model directly — it is faster and the failure points at the
 right line:
 
-```typescript
+```typescript fragment
 // tests/models/Post.test.ts
 import { test, expect } from "bun:test";
 import { PostFactory } from "../../database/factories/PostFactory.ts";
@@ -598,7 +600,7 @@ test("the published scope excludes drafts", async () => {
 ambiguous. Assert on both sides — gone from the normal query, present with
 `withTrashed()`:
 
-```typescript
+```typescript fragment
 // tests/models/Post.test.ts
 await post.delete();