@zerotal/arch 1.7.4 → 1.8.0

package/docs/tenancy.md

@@ -32,7 +32,7 @@ The package owns the `tenants` registry and the `tenant_members` pivot tables
 
 Supply the config with `TenancyProvider.withConfig(...)`, then add the provider to the array in `bootstrap/providers.ts`:
 
-```typescript
+```typescript fragment
 // bootstrap/providers.ts
 import { TenancyProvider } from "@zerotal/tenancy";
 import tenancyConfig from "../config/tenancy.ts";
@@ -141,7 +141,7 @@ import { RouteParamResolver } from "@zerotal/tenancy";
 new RouteParamResolver({ param: "tenancy" }); // default param name
 ```
 
-```typescript
+```typescript fragment
 // bootstrap/app.ts
 .fileBasedRouting({
   dir: basePath("app/routes"),
@@ -178,7 +178,7 @@ Requests with no authenticated user — login, signup, a public marketing page
 resolve to `null` here, and with `strict: false` (the default) fall through to
 the default connection rather than failing.
 
-```typescript
+```typescript fragment
 // config/tenancy.ts — a non-default column
 new AuthResolver({ column: "organisationId" });
 ```
@@ -208,28 +208,21 @@ export class CookieResolver implements TenantResolver {
 
 `TenancyMiddleware` resolves the tenant and opens the [TenantContext](#tenantcontext-access-the-tenant-anywhere) boundary. Apply it globally or to specific route groups.
 
-### Global
-
-With `TenancyProvider` already registered, add the middleware to the global pipeline with `.use()` in `bootstrap/app.ts`:
+Registering `TenancyProvider` is the whole of it — the provider adds the resolving
+middleware to the global pipeline itself, so every request has a tenant boundary
+opened before it reaches a route:
 
-```typescript
+```typescript fragment
 // bootstrap/app.ts
-import { TenancyMiddleware } from "@zerotal/tenancy";
+import { TenancyProvider } from "@zerotal/tenancy";
 
-Application.create({ providers }).use([TenancyMiddleware]);
+Application.create({ providers: [TenancyProvider] });
 ```
 
-### Route group only
-
-```typescript
-// routes/web.ts
-import { TenancyMiddleware } from "@zerotal/tenancy";
-
-Router.group({ domain: "{tenant}.myapp.com" }, () => {
-  Router.get("/dashboard", DashboardController, "index");
-  Router.get("/settings", SettingsController, "index");
-}).use([TenancyMiddleware]);
-```
+`TenancyMiddleware` is deliberately not exported: there is no arrangement in which
+an app registers it by hand, and one registered twice would resolve the tenant
+twice. To _require_ a tenant on particular routes, reach for
+`EnsureTenancyMiddleware` below.
 
 The middleware throws an [error](/docs/errors) the framework's exception handler renders by content negotiation:
 
@@ -247,21 +240,22 @@ one. Use it on routes that make no sense without a tenant — it throws
 `TenantNotFoundError` when the context is empty rather than letting a query run
 unscoped:
 
-```typescript
+```typescript fragment
 // routes/web.ts
-import { TenancyMiddleware, EnsureTenancyMiddleware } from "@zerotal/tenancy";
+import { EnsureTenancyMiddleware } from "@zerotal/tenancy";
 
-Router.group({ middleware: [TenancyMiddleware, EnsureTenancyMiddleware] }, () => {
+Router.group({ middleware: [EnsureTenancyMiddleware] }, () => {
   Router.get("/billing", BillingController, "index");
 });
 ```
 
-Register it after `TenancyMiddleware`, never instead of it: on its own there is
-nothing to resolve, so every request fails.
+It runs after the global resolving middleware, which the provider has already
+registered, so by the time this asserts there is a tenant the attempt to find one
+has been made.
 
 ## ORM scoping — Tenantable
 
-Compose the `Tenantable` mixin via [`Model.using`](/docs/orm/index#composing-model-mixins) onto any model that belongs to a tenant. Two things happen automatically:
+Compose the `Tenantable` mixin via [`Model.using`](/docs/orm#composing-model-mixins) onto any model that belongs to a tenant. Two things happen automatically:
 
 1. Every query on the model receives `WHERE tenant_id = <current tenant id>` (skipped outside a tenant context).
 2. `create()` / `save()` inject `tenant_id` on new records, so you never accidentally write cross-tenant data.
@@ -278,7 +272,7 @@ export class Project extends Model.using(Tenantable) {
 }
 ```
 
-```typescript
+```typescript fragment
 // in a controller — inside a TenancyMiddleware boundary (tenant id = 7):
 const projects = await Project.all();
 // → SELECT * FROM projects WHERE tenant_id = 7
@@ -312,14 +306,14 @@ export class Invoice extends Model.using(Tenantable) {
 
 ### Single query
 
-```typescript
+```typescript fragment
 // in an admin controller — load every project across all tenants:
 const all = await Project.query().withoutTenancy().get();
 ```
 
 `withoutTenancy()` removes only the tenant scope. To strip every global scope instead:
 
-```typescript
+```typescript fragment
 // in a controller
 const all = await Project.query().withoutGlobalScopes().get();
 ```
@@ -328,7 +322,7 @@ const all = await Project.query().withoutGlobalScopes().get();
 
 Wrap the work in a tenant boundary with `TenantContext.run()` (or `Tenant.run()` via the facade) to scope every query inside it to a specific tenant:
 
-```typescript
+```typescript fragment
 // app/jobs/SendReminders.ts
 import { TenantContext, Tenant } from "@zerotal/tenancy";
 
@@ -375,7 +369,7 @@ if (Tenant.check()) {
 
 Controllers also receive the resolved tenant directly on the request context:
 
-```typescript
+```typescript fragment
 // in a controller
 async index(ctx: HttpContext): Promise<void> {
   const tenant = (ctx as any).tenant as Tenant;
@@ -387,7 +381,7 @@ async index(ctx: HttpContext): Promise<void> {
 
 The package maintains a `tenant_members` pivot linking your authenticated [User](/docs/authentication) model to tenants, with an admin flag. `Tenancy.create()` makes the current user the first admin; `update()` and `delete()` are admin-gated (use the `force*` variants to bypass the check from trusted server code).
 
-```typescript
+```typescript fragment
 // in a controller
 import { Tenant } from "@zerotal/tenancy";
 
@@ -403,7 +397,7 @@ await Tenant.update({ name: "Acme Corp" }); // throws TenantForbiddenError unles
 
 `tenantDisk()` wraps any [storage](/docs/storage) disk and prefixes every path with `tenants/<slug>/` for the active tenant:
 
-```typescript
+```typescript fragment
 // in a controller — inside a tenant boundary (slug = 'acme')
 import { tenantDisk } from "@zerotal/tenancy";
 
@@ -422,7 +416,7 @@ await tenantDisk("s3").put("reports/q4.pdf", pdf);
 A key that tries to climb out of its tenant's folder is rejected with
 `TenantStoragePathError` before it reaches the driver:
 
-```typescript
+```typescript fragment
 await tenantDisk().put("../other-tenant/secrets.txt", buffer);
 // throws TenantStoragePathError
 ```
@@ -437,7 +431,7 @@ the exception handler renders it like any other.
 
 `tenantCache()` wraps the [cache](/docs/cache) and prefixes every key with `tenant:<slug>:`:
 
-```typescript
+```typescript fragment
 // in a controller — inside a tenant boundary (slug = 'acme')
 import { tenantCache } from "@zerotal/tenancy";
 
@@ -467,7 +461,7 @@ export default TenancyConfig({
 });
 ```
 
-```typescript
+```typescript fragment
 // in a controller — Project.all() automatically uses the active tenant's connection:
 const projects = await Project.all();
 ```
@@ -494,7 +488,7 @@ Set your suite up once as described in [Testing](/docs/testing). Tenancy has one
 test that matters more than all the others: **a tenant must not see another
 tenant's rows.** Write it first, and write it as a negative.
 
-```typescript
+```typescript fragment
 // tests/tenancy/isolation.test.ts
 import { test, expect } from "bun:test";
 import { Tenancy, TenantContext } from "@zerotal/tenancy";
@@ -523,7 +517,7 @@ when the query returns everything but that one title.
 broken resolver serves the wrong tenant's data correctly, which no isolation test
 catches:
 
-```typescript
+```typescript fragment
 // tests/tenancy/resolver.test.ts
 const res = await app.get("/dashboard", { Host: "acme.example.test" });
 
@@ -534,7 +528,7 @@ expect(res.json().tenant).toBe("acme");
 tenant and throws leaves it set, and the next test passes or fails for reasons
 that have nothing to do with it:
 
-```typescript
+```typescript fragment
 // tests/tenancy/isolation.test.ts
 afterEach(() => {
   expect(TenantContext.tryGet()).toBeUndefined(); // catches a leak at its source
@@ -601,7 +595,7 @@ Resolved from the container binding `"tenancy"`; the `Tenant` value is the facad
 
 ## Next steps
 
-- [ORM](/docs/orm/index) — how `Tenantable` composes onto your models via `Model.using`.
+- [ORM](/docs/orm) — how `Tenantable` composes onto your models via `Model.using`.
 - [Storage](/docs/storage) — the disks `tenantDisk()` wraps.
 - [Cache](/docs/cache) — the stores `tenantCache()` wraps.
 - [Middleware](/docs/middleware) — where `TenancyMiddleware` runs in the pipeline.

package/docs/testing/browser.md

@@ -37,7 +37,7 @@ bunx playwright install --with-deps
 Add a `playwright.config.ts` that boots your app with the `webServer` option, so the
 server starts once for the whole run and is torn down after:
 
-```typescript
+```typescript fragment
 // playwright.config.ts
 import { defineConfig, devices } from "@playwright/test";
 
@@ -81,18 +81,18 @@ Wire up scripts in `package.json`:
 Specs live in `e2e/` and use Playwright's `test`/`expect`. Drive the page through
 roles and assert on what the user sees:
 
-```typescript
+```typescript fragment
 // e2e/navigate.e2e.ts
 import { test, expect } from "@playwright/test";
 
 test.describe("SPA navigation", () => {
   test("swaps content without a full page reload", async ({ page }) => {
-    await page.goto("/pulse/counter");
+    await page.goto("/demo/counter");
     // A full reload would clear this marker; an SPA swap keeps it.
     await page.evaluate(() => ((window as any).__spa = true));
 
     await page.getByRole("link", { name: "Components" }).click();
-    await expect(page).toHaveURL(/\/pulse\/components/);
+    await expect(page).toHaveURL(/\/demo\/components/);
     await expect(page.getByRole("heading", { name: "Native Components" })).toBeVisible();
 
     const kept = await page.evaluate(() => (window as any).__spa);
@@ -112,7 +112,7 @@ Flow pages finish wiring once Alpine has walked the DOM and fired
 `alpine:initialized`. A fast click can land before that and silently no-op (a flaky,
 browser-dependent failure). Wait for readiness before interacting:
 
-```typescript
+```typescript fragment
 // e2e/support/gotoReady.ts
 import type { Page } from "@playwright/test";
 
@@ -128,7 +128,7 @@ export async function gotoReady(page: Page, url: string): Promise<void> {
 }
 ```
 
-Then `await gotoReady(page, "/pulse/counter")` instead of `page.goto(...)` for
+Then `await gotoReady(page, "/demo/counter")` instead of `page.goto(...)` for
 interactive Flow pages.
 
 > **Warning** — Clicking before `alpine:initialized` fires is the most common source

package/docs/testing/console.md

@@ -41,7 +41,7 @@ describe("cache:clear", () => {
 Pass arguments and flags as a parameter map. Booleans become bare flags when `true`;
 everything else becomes a `key=value` token, mirroring how the CLI parses argv:
 
-```typescript
+```typescript fragment
 // in a test file
 await Artisan.call("migrate", { "--fresh": true });
 await Artisan.call("make:model", { name: "Post", "--migration": true });
@@ -55,7 +55,7 @@ Commands usually do work — touch the database, queue a job, write a file. Asse
 _effect_, not just the output, using the [database](/docs/testing/database) and
 [mocking](/docs/testing/mocking) helpers:
 
-```typescript
+```typescript fragment
 // src/tests/PruneUsersTest.ts
 import { Artisan } from "zerotal";
 import { assertDatabaseCount, QueueFake } from "@zerotal/testing";
@@ -79,7 +79,7 @@ For a focused test of a single command's logic, instantiate it directly and inje
 `BufferWriter` to capture output. The `_writer`, `args`, and `flags` fields are
 internal — the runner normally sets them — so a unit test reaches in with a cast:
 
-```typescript
+```typescript fragment
 // src/tests/GreetCommandTest.ts
 import { expect } from "bun:test";
 import { BufferWriter } from "zerotal";

package/docs/testing/database.md

@@ -21,7 +21,7 @@ import {
 } from "@zerotal/testing";
 ```
 
-> **Note** — These helpers are part of the [testing toolkit](/docs/testing/index) and
+> **Note** — These helpers are part of the [testing toolkit](/docs/testing) and
 > only run inside `bun test`. Install the package as a dev dependency if it isn't
 > already: `bun add -d @zerotal/testing`.
 
@@ -30,7 +30,7 @@ import {
 A test needs tables before it needs rows. Build them by running the project's own
 [migrations](/docs/migrations) rather than by writing the schema a second time:
 
-```typescript
+```typescript fragment
 // tests/Feature/PostTest.ts
 import { migrateDatabase } from "@zerotal/testing";
 
@@ -46,7 +46,7 @@ until something fails for a reason that has nothing to do with the change you
 made. Running the migrations themselves means the schema under test is the schema
 that ships.
 
-```typescript
+```typescript fragment
 // signature
 function migrateDatabase(options?: MigrateDatabaseOptions): Promise<string[]>;
 ```
@@ -61,7 +61,7 @@ It returns the names of the migrations it applied, and is idempotent — a secon
 call applies nothing. `refreshDatabase({ migrate: true })` runs it for you, which
 is usually what you want:
 
-```typescript
+```typescript fragment
 // in a test file
 describe("Post", () => {
   refreshDatabase({ connection: db, migrate: true });
@@ -92,7 +92,7 @@ Call it once inside a `describe` block. Every `it()` in that block runs inside a
 transaction that rolls back when the test ends, so each test starts from the same
 clean baseline:
 
-```typescript
+```typescript fragment
 // tests/Feature/UserTest.ts
 import { describe, it } from "bun:test";
 import { refreshDatabase, assertDatabaseHas, assertDatabaseMissing } from "@zerotal/testing";
@@ -115,7 +115,7 @@ describe("User", () => {
 });
 ```
 
-```typescript
+```typescript fragment
 // signature
 function refreshDatabase(options?: RefreshDatabaseOptions): void;
 ```
@@ -137,7 +137,7 @@ fixtures), while each test's own writes happen inside the rolled-back transactio
 
 When you want rollback for a single test rather than a whole block, wrap the test body:
 
-```typescript
+```typescript fragment
 // in a test file
 import { withDatabase } from "@zerotal/testing";
 
@@ -150,7 +150,7 @@ it(
 ); // ← transaction rolled back here
 ```
 
-```typescript
+```typescript fragment
 // signature
 function withDatabase(fn: () => Promise<void>): () => Promise<void>;
 ```
@@ -201,7 +201,7 @@ await assertMissingFile("local", "uploads/old.jpg");
 Use [factories](/docs/orm/factories) to build the records a test acts on, and
 [seeders](/docs/seeding) for shared fixtures:
 
-```typescript
+```typescript fragment
 // in a test file
 import { UserFactory } from "../database/factories/UserFactory.ts";
 import { PostFactory } from "../database/factories/PostFactory.ts";
@@ -231,7 +231,7 @@ jobs — call `.dispatchEvents()` when a test needs the full lifecycle.
 
 ## Next steps
 
-- [Testing overview](/docs/testing/index) — the full toolkit and a first test.
+- [Testing overview](/docs/testing) — the full toolkit and a first test.
 - [Factories](/docs/orm/factories) — generating model records for tests.
 - [Seeding](/docs/seeding) — reusable fixtures across dev and tests.
 - [Database](/docs/database) — transactions and the raw `DB` layer being rolled back.

package/docs/testing/flow-browser.md

@@ -8,7 +8,7 @@ description: Drive a real page against a real server inside bun test, and assert
 `FlowBrowser` runs a headless browser against your app inside `bun test`, so a test
 can assert on the thing `FlowTest` cannot reach: the WebSocket bridge.
 
-```ts
+```ts fragment
 import { FlowBrowser } from "@zerotal/testing/browser";
 
 const browser = await FlowBrowser.serve(() => import("../bootstrap/app.ts").then((m) => m.default));
@@ -70,7 +70,7 @@ The two environments differ deliberately. **A browser suite that skips itself in
 is worse than no suite**, because it reports green for exactly the failures it exists
 to catch. So pair the skip with a guard that runs regardless:
 
-```ts
+```ts fragment
 import { FlowBrowser, browserAvailability, browserRequired } from "@zerotal/testing/browser";
 
 const availability = await browserAvailability();
@@ -94,7 +94,7 @@ that sets it does not have to hard-code the string.
 
 ## Serving the app
 
-```ts
+```ts fragment
 const browser = await FlowBrowser.serve(bootstrap, options?);
 ```
 
@@ -112,7 +112,7 @@ through a second bootstrap that can drift. The server binds an OS-assigned port.
 Call `await browser.stop()` in `afterAll`: it closes every page it opened, then stops
 the server.
 
-```ts
+```ts fragment
 let browser: FlowBrowser;
 beforeAll(async () => {
   browser = await FlowBrowser.serve(bootstrap);
@@ -168,7 +168,7 @@ suite gets deleted.
 `page.transport()` reports what Chrome saw on the wire — which the page cannot lie
 about. A client that degraded silently still shows zero upgraded sockets here.
 
-```ts
+```ts fragment
 expect(page.socketUpgraded()).toBe(true);
 expect(page.transport().statuses).toContain(101);
 expect(await page.connection()).toBe("online");
@@ -192,7 +192,7 @@ It returns a `TransportReport`:
 `frames` carries the payloads, which is how you assert on what actually crossed the
 wire rather than on what the DOM ended up showing:
 
-```ts
+```ts fragment
 const sent = page.transport().frames.filter((f) => f.direction === "sent");
 expect(sent.some((f) => f.payload.includes(`"method":"save"`))).toBe(true);
 ```

package/docs/testing/http.md

@@ -28,7 +28,7 @@ import { createTestApp, type TestApp } from "@zerotal/testing";
 
 Boot the app once per suite and close it when the suite finishes:
 
-```typescript
+```typescript fragment
 // src/tests/PostTest.ts
 import { describe, it, beforeAll, afterAll } from "bun:test";
 import { createTestApp, type TestApp } from "@zerotal/testing";
@@ -45,7 +45,7 @@ afterAll(() => testApp.close());
 
 `createTestApp()` boots the app and starts it on an OS-assigned port (port `0`):
 
-```typescript
+```typescript fragment
 function createTestApp(
   bootstrap: () => Application | Promise<Application>,
   setup?: () => void,
@@ -82,7 +82,7 @@ call `closeSharedTestApps()`.
 
 ## Sending requests
 
-```typescript
+```typescript fragment
 // in a test
 await testApp.get("/path");
 await testApp.post("/path", body); // body serialized as JSON
@@ -104,7 +104,7 @@ A route meant for a browser should be tested the way a browser reaches it. A JSO
 redirect-back-with-errors branch of validation, the CSRF check, and any middleware
 that reads `application/x-www-form-urlencoded`.
 
-```typescript
+```typescript fragment
 // in a test
 const res = await testApp.postForm("/posts", { title: "Hello", published: true });
 
@@ -120,7 +120,7 @@ strings `"null"` and `"undefined"`.
 `multipart()` is the only way to exercise a route that reads an uploaded file.
 Build the attachments with `fakeFile`:
 
-```typescript
+```typescript fragment
 // in a test
 import { fakeFile } from "@zerotal/testing";
 
@@ -154,7 +154,7 @@ without a request, build one with `UploadedFile.fake('a.png', { type, size })`.
 
 ### Authentication
 
-```typescript
+```typescript fragment
 // in a test
 
 // Forge a signed session cookie so the request is treated as authenticated
@@ -173,7 +173,7 @@ any `user_id` already set by `actingAs()`.
 
 ### Headers and redirects
 
-```typescript
+```typescript fragment
 // in a test
 testApp.withHeaders({ "X-App-Version": "2" });
 testApp.withCookie("theme", "dark");
@@ -203,7 +203,7 @@ An exception inside a route is converted to a response before the test sees it,
 so the assertion reports `500` and the body is an error page. `withoutExceptionHandling()`
 hands you the original instead:
 
-```typescript
+```typescript fragment
 // in a test
 const res = await testApp.withoutExceptionHandling().get("/checkout");
 
@@ -226,7 +226,7 @@ into the test output. Call `withExceptionHandling()` to restore the default.
 Every request returns a `TestResponse`. Assertions are chainable and throw
 descriptive errors on failure.
 
-```typescript
+```typescript fragment
 // in a test
 
 // Status
@@ -300,7 +300,7 @@ A failed validation reaches the client two different ways: an API client gets
 flashed to the session. `assertInvalid` reads both, so the assertion is the same
 either way:
 
-```typescript
+```typescript fragment
 // in a test
 
 // API client
@@ -331,7 +331,7 @@ reporting the key as absent.
 
 Reading the body directly:
 
-```typescript
+```typescript fragment
 // in a test
 const data = res.json<{ id: number }>();
 const html = res.text();
@@ -343,7 +343,7 @@ const ok = res.ok; // boolean
 
 Skip HTTP entirely for fast, focused controller tests by faking the context:
 
-```typescript
+```typescript fragment
 // src/tests/PostControllerTest.ts
 import { HttpContext } from "zerotal";
 

package/docs/testing/index.md

@@ -64,7 +64,7 @@ add it here too — that one edit keeps every test in the suite honest.
 
 From then on a test is two lines of setup:
 
-```typescript
+```typescript fragment
 // tests/http/posts.test.ts
 import { test } from "bun:test";
 import { createApp } from "../helpers.ts";
@@ -149,7 +149,7 @@ building its own.
 `createTestApp()` boots your application, starts it on a random port, and returns a
 `TestApp` client. Pair it with a [factory](/docs/orm/factories) to arrange data:
 
-```typescript
+```typescript fragment
 // tests/Feature/PostTest.ts
 import { describe, it, beforeAll, afterAll } from "bun:test";
 import { createTestApp, migrateDatabase, type TestApp, assertDatabaseHas } from "@zerotal/testing";
@@ -197,7 +197,7 @@ See [HTTP Tests](/docs/testing/http) for the full `TestApp` and `TestResponse` A
 
 ## Resetting framework state
 
-```typescript
+```typescript fragment
 // tests/Feature/SomeTest.ts
 import { resetTestState } from "@zerotal/testing";
 
@@ -209,6 +209,32 @@ observers, global scopes, and state-machine callbacks, plus framework event
 subscriptions. `createTestApp()` and `testApp.close()` call it for you, so suites
 using those helpers don't need the explicit `afterEach`.
 
+## Running the suite from a script
+
+A script that gates on the tests has to read the tests' exit status, and a pipe hides it:
+
+```bash
+bun test 2>&1 | tail -3     # the status is tail's. Always 0, however the suite went.
+```
+
+The suite is verbose enough that piping it somewhere is the natural thing to write, which
+is what makes this worth saying: a deploy script written that way prints `1 fail` and
+carries straight on to upload and restart. Nothing is wrong with the output — it is the
+`$?` behind it that belongs to the last command in the pipe.
+
+Either turn the pipe honest, or do not pipe:
+
+```bash
+set -o pipefail             # bash/zsh: the pipeline fails if any stage does
+bun test 2>&1 | tail -3
+
+# or keep the status and the output separately
+bun test > test.log 2>&1 || { tail -20 test.log; exit 1; }
+```
+
+`set -e` alone does not cover it — the pipeline succeeded, as far as the shell is
+concerned.
+
 ## References
 
 The most-used members exported from `@zerotal/testing`. Each area's page documents

package/docs/testing/mocking.md

@@ -46,7 +46,7 @@ Everything except `Broadcast.fake()` and `Social.fake()` is re-exported from
 `EventFake.install()` replaces the `events` binding, so emitted events are
 recorded and their listeners never run.
 
-```typescript
+```typescript fragment
 // src/tests/PostPublishTest.ts
 import { EventFake } from "@zerotal/testing";
 
@@ -80,7 +80,7 @@ search indexing, cache invalidation.
 `QueueFake.install()` replaces the `queue` binding so dispatched jobs are
 captured instead of persisted or executed.
 
-```typescript
+```typescript fragment
 // src/tests/PostPublishTest.ts
 import { QueueFake } from "@zerotal/testing"; // re-exported from @zerotal/queue
 
@@ -111,7 +111,7 @@ it("queues a job when a post is published", async () => {
 `Notify.send()` and `Notify.queue()` are captured as "sent". The `mail` channel
 runs through `Notify`, so faking notifications also covers email side effects.
 
-```typescript
+```typescript fragment
 // src/tests/InvoiceTest.ts
 import { NotificationFake } from "@zerotal/testing"; // re-exported from @zerotal/notifications
 import { Notify } from "@zerotal/notifications";
@@ -142,7 +142,7 @@ The `Broadcast` facade has its own recorder. Call `Broadcast.fake()` to install
 it and `Broadcast.resetFake()` to restore — the returned fake exposes the
 assertions:
 
-```typescript
+```typescript fragment
 // src/tests/PostBroadcastTest.ts
 import { Broadcast } from "@zerotal/broadcasting";
 
@@ -168,7 +168,7 @@ touches the filesystem, so each test starts empty by construction rather than by
 remembering to clean up — and a suite that forgets to clean up passes the second
 time for the wrong reason.
 
-```typescript
+```typescript fragment
 // src/tests/AvatarTest.ts
 import { Storage } from "zerotal/storage";
 import { fakeFile } from "@zerotal/testing";
@@ -201,7 +201,7 @@ it directly.
 client, so a test that exercises a service integration makes no real network
 call — and does not fail when that service is down or rate-limits you.
 
-```typescript
+```typescript fragment
 // src/tests/PaymentTest.ts
 import { Http } from "@zerotal/testing";
 
@@ -231,9 +231,9 @@ Behaviour that depends on the passage of time — a token that expires in seven
 days, a reminder that only fires after 24 hours — has no way to be tested except
 by waiting. Freeze the clock instead:
 
-```typescript
+```typescript fragment
 // src/tests/InvitationTest.ts
-import { Carbon } from "zerotal";
+import { Carbon } from "zerotal/carbon";
 
 afterEach(() => Carbon.release());
 

package/docs/upgrade.md

@@ -18,7 +18,7 @@ version line:
 - **Major** (`X.y.z`) — breaking changes; read the version's section in the
   [Release Notes](/docs/changelog) before upgrading.
 
-> **Warning** — while the 1.x line is young, a breaking change may also land in a minor or a patch. It is always labelled **BREAKING** in the [Release Notes](/docs/changelog) with migration steps, and two have shipped so far (1.3.0 and 1.7.2). Read the notes for every version you cross, not only the majors. See [Releases and versioning](/docs/support-policy#releases-and-versioning) for when this carve-out ends.
+> **Warning** — while the 1.x line is young, a breaking change may also land in a minor or a patch. It is always labelled **BREAKING** in the [Release Notes](/docs/changelog) with migration steps. Read the notes for every version you cross, not only the majors. See [Releases and versioning](/docs/support-policy#releases-and-versioning) for which ones have shipped and when this carve-out ends.
 
 > **Warning** — always upgrade the `@zerotal/*` packages together. Mixing versions across core, ORM, and feature packages leads to type and runtime mismatches.