@zerotal/arch 1.7.3 → 1.7.5

package/docs/conventions.md

@@ -42,7 +42,7 @@ app/providers/*    →   register → boot phases   →   app/middleware/*   →
 
 Every `Model` subclass under `app/models/` is registered automatically:
 
-```typescript
+```typescript fragment
 // app/models/User.ts
 import { Model, column, hasMany } from "@zerotal/orm";
 import { Post } from "./Post.ts";
@@ -65,7 +65,7 @@ No `@table` needed. The table name is derived by convention — `pluralize(snake
 
 Override the name (or set timestamps/soft-deletes) with `@table` whenever you need to:
 
-```typescript
+```typescript fragment
 // app/models/Account.ts
 @table("legacy_accounts", { softDeletes: true })
 export class Account extends Model {
@@ -86,7 +86,7 @@ export class Account extends Model {
 `XObserver` is attached to model `X` automatically (the `Observer` suffix is stripped and matched
 against the discovered models):
 
-```typescript
+```typescript fragment
 // app/observers/UserObserver.ts
 import type { ModelObserver } from "@zerotal/orm";
 import type { User } from "../models/User.ts";
@@ -107,7 +107,7 @@ Override the target with `static model = SomeModel` when the name doesn't match.
 
 `XPolicy` is registered with the Gate for model `X`:
 
-```typescript
+```typescript fragment
 // app/policies/PostPolicy.ts
 import { Policy } from "@zerotal/auth";
 import type { Post } from "../models/Post.ts";
@@ -130,14 +130,14 @@ model's class automatically. Override the target with `static model = Post`.
 
 A listener declares the event(s) it handles via `static listens`:
 
-```typescript
+```typescript fragment
 // app/events/UserRegistered.ts
 export class UserRegistered {
   constructor(public user: User) {}
 }
 ```
 
-```typescript
+```typescript fragment
 // app/listeners/SendWelcomeEmail.ts
 import { UserRegistered } from "../events/UserRegistered.ts";
 
@@ -158,7 +158,7 @@ them and runs any module-level side effects before listeners bind).
 A model can map its lifecycle events to event classes, which are dispatched on the bus when they
 fire — listeners then react with no coupling to the model:
 
-```typescript
+```typescript fragment
 // app/models/Order.ts
 export class Order extends Model {
   static dispatchesEvents = { created: OrderPlaced, deleted: OrderCancelled };
@@ -181,10 +181,18 @@ Any `ServiceProvider` under `app/providers/` is registered automatically — you
 (`onRegister` → `onBooting` → `onBooted`), appended **after** the providers you registered
 explicitly (so framework providers boot first), and de-duplicated if also listed by hand.
 
-```typescript
+```typescript fragment
 // app/providers/AppServiceProvider.ts
 import { ServiceProvider } from "zerotal";
 
+// A string token is only valid once it is declared, which is what keeps
+// `make("billing")` typed at the call site. See Container for the full pattern.
+declare module "zerotal" {
+  interface ContainerBindings {
+    billing: Billing;
+  }
+}
+
 export class AppServiceProvider extends ServiceProvider {
   override onRegister() {
     this.app.container.singleton("billing", () => new Billing());
@@ -197,7 +205,7 @@ export class AppServiceProvider extends ServiceProvider {
 Each middleware class under `app/middleware/` is registered as a **named group** under its class
 name, so routes can reference it by string without importing it:
 
-```typescript
+```typescript fragment
 // app/middleware/EnsureSubscribed.ts
 import { BaseMiddleware } from "zerotal";
 
@@ -208,7 +216,7 @@ export class EnsureSubscribed extends BaseMiddleware<{}> {
 }
 ```
 
-```typescript
+```typescript fragment
 // routes/web.ts — reference by class name
 Router.group({ middleware: ["EnsureSubscribed"] }, () => {
   /* … */
@@ -218,7 +226,7 @@ Router.group({ middleware: ["EnsureSubscribed"] }, () => {
 Middleware is **not** applied globally by default. Opt a class into the global pipeline with
 `static global = true`:
 
-```typescript
+```typescript fragment
 // app/middleware/RequestId.ts
 export class RequestId extends BaseMiddleware<{}> {
   static global = true; // runs on every request
@@ -281,7 +289,7 @@ export class NotifyFollowersJob extends Job {
 
 Dispatch it from anywhere without importing the class into a barrel:
 
-```typescript
+```typescript fragment
 // in a controller
 await Queue.dispatch(new NotifyFollowersJob(post.id));
 ```
@@ -296,7 +304,7 @@ registered with the scheduler at boot. Each declares its cadence (a `cron` strin
 `frequency()` method) and its work (`handle()`); the loader translates the class's declarative
 settings into a scheduled task.
 
-```typescript
+```typescript fragment
 // app/schedules/SendDailyReports.ts
 import { Schedule } from "@zerotal/scheduler";
 
@@ -342,7 +350,7 @@ import only runs because this concern imports it.
 Once models are registered at boot, Zerotal can sync the schema additively — create missing tables
 and add missing columns to match your models (TypeORM-style `synchronize`):
 
-```typescript
+```typescript fragment
 // config/database.ts
 import { DatabaseConfig } from "@zerotal/orm";
 
@@ -413,7 +421,7 @@ let you relocate any concern. Files starting with `_` and `*.test.ts` / `*.test.
 Discovery is extensible. A provider can contribute its own concern descriptor via
 `app.registerConcern(...)`:
 
-```typescript
+```typescript fragment
 // app/providers/AppServiceProvider.ts — inside onRegister/onBooting
 this.app.registerConcern({
   name: "validators",

package/docs/cookies.md

@@ -28,7 +28,7 @@ When you need to read or set a raw cookie directly, you work with the standard
 
 Cookies arrive in the request's `Cookie` header. Read and parse it from the context:
 
-```ts
+```ts fragment
 // in a controller
 import type { HttpContext } from "zerotal";
 
@@ -49,7 +49,7 @@ const theme = readCookie(ctx, "theme") ?? "light";
 Set the response with a `ctx` helper, then append a `Set-Cookie` header to it. Use
 `append` (not `set`) so multiple cookies can be sent in one response:
 
-```ts
+```ts fragment
 // in a controller
 ctx.json({ ok: true }); // assigns ctx.response
 
@@ -75,7 +75,7 @@ ctx.response!.headers.append(
 
 To **delete** a cookie, set it again with `Max-Age=0`:
 
-```ts
+```ts fragment
 // in a controller
 ctx.response!.headers.append("Set-Cookie", "theme=; Path=/; Max-Age=0");
 ```

package/docs/csrf.md

@@ -55,7 +55,7 @@ Register `CsrfMiddleware` **after** `SessionMiddleware` — it reads and writes
 session. In production over HTTPS, set `secure: true` so the cookie carries the
 `Secure` flag:
 
-```typescript
+```typescript fragment
 // bootstrap/app.ts
 import { SessionMiddleware, CsrfMiddleware } from "@zerotal/session";
 
@@ -89,7 +89,7 @@ on every mutating request.
 Expose the token server-side and send it in the header (or a hidden field your
 handler reads). `CsrfMiddleware.token()` returns the current session's token:
 
-```typescript
+```typescript fragment
 // in an Inertia shared-props factory
 import { CsrfMiddleware } from "@zerotal/session";
 
@@ -99,7 +99,7 @@ Inertia.share({ csrf_token: () => CsrfMiddleware.token() });
 // <meta name="csrf-token" content="${CsrfMiddleware.token()}">
 ```
 
-```typescript
+```typescript fragment
 // client-side fetch
 await fetch("/posts", {
   method: "POST",
@@ -140,7 +140,7 @@ is the rare feature whose test is mostly about proving a request **fails**.
 worth asserting by number — a `403` in this test means your authorization denied
 the request and CSRF never ran:
 
-```typescript
+```typescript fragment
 // tests/http/csrf.test.ts
 import { test } from "bun:test";
 import { createApp } from "../helpers.ts";
@@ -159,7 +159,7 @@ test("an unsafe request without a token is refused", async () => {
 that is the only request in the test, the middleware could be absent entirely and
 the suite would stay green:
 
-```typescript
+```typescript fragment
 // tests/http/csrf.test.ts
 test("GET is never challenged", async () => {
   (await app.get("/posts")).assertOk(); // passes with or without CSRF — not a CSRF test
@@ -169,7 +169,7 @@ test("GET is never challenged", async () => {
 To test the **success** path, seed the session with a token you choose and send
 the same value on the header the middleware reads:
 
-```typescript
+```typescript fragment
 // tests/http/csrf.test.ts
 const token = "test-csrf-token";
 

package/docs/database.md

@@ -56,7 +56,9 @@ import { env } from "zerotal";
 export default DatabaseConfig({
   driver: "postgres",
   url: env("DATABASE_URL", "./database/db.sqlite"),
-  replicas: [env("REPLICA_1_URL"), env("REPLICA_2_URL")],
+  // `env()` with no fallback is `string | undefined`, and an unset replica should
+  // drop out rather than become an empty connection string.
+  replicas: [env("REPLICA_1_URL"), env("REPLICA_2_URL")].filter((url) => url !== undefined),
 });
 ```
 
@@ -98,7 +100,7 @@ Three styles, in order of preference:
 
 Pass a callback to `DB.transaction()`. Bun commits on resolve and rolls back on throw — you never call commit/rollback manually:
 
-```typescript
+```typescript fragment
 // in a controller or service
 import { DB } from "@zerotal/orm";
 
@@ -120,7 +122,7 @@ await DB.transaction(async (trx) => {
 
 All `Model` and `DB` queries made inside the callback automatically use the transaction connection via `AsyncLocalStorage` — you don't need to pass `trx` explicitly unless you're mixing raw `DB.table()` calls with model calls:
 
-```typescript
+```typescript fragment
 // in a service
 await DB.transaction(async () => {
   // These automatically use the transaction without passing trx:
@@ -136,7 +138,7 @@ await DB.transaction(async () => {
 
 Nested `DB.transaction()` calls automatically use SAVEPOINTs. An inner throw rolls back only the inner block, not the entire outer transaction:
 
-```typescript
+```typescript fragment
 // in a service
 await DB.transaction(async () => {
   await Order.create({ userId, total });
@@ -159,7 +161,7 @@ await DB.transaction(async () => {
 
 Pass the number of attempts as a second argument to retry automatically on deadlock or serialization failures:
 
-```typescript
+```typescript fragment
 // in a service
 await DB.transaction(async () => {
   // critical concurrent write
@@ -208,7 +210,7 @@ chain handles all four CRUD operations: call a read terminal like `get()` to fet
 rows, or a write method like `insert()`, `update()`, or `delete()` to change them.
 Values are always parameterised for you, so there's no injection risk:
 
-```typescript
+```typescript fragment
 // in a controller or service
 import { DB } from "@zerotal/orm";
 
@@ -237,7 +239,7 @@ Use when the query builder doesn't cover what you need.
 
 > **Danger** — Always parameterise values; never interpolate them directly into the SQL string. String interpolation opens a SQL injection hole.
 
-```typescript
+```typescript fragment
 // in a service
 import { DB } from "@zerotal/orm";
 
@@ -260,7 +262,7 @@ const [{ version }] = await DB.raw<{ version: string }>("SELECT version()");
 
 `whereJson` takes the column and a JSON path joined with `->`, then the value to match:
 
-```typescript
+```typescript fragment
 // in a service
 // Equivalent SQL: WHERE meta->>'notifications.email' = ?
 await DB.table("settings").whereJson("meta->notifications.email", true).get();
@@ -279,8 +281,10 @@ import { DatabaseConfig } from "@zerotal/orm";
 import { env } from "zerotal";
 
 export default DatabaseConfig({
-  url: env("DATABASE_URL"),
-  replicas: [env("REPLICA_1_URL"), env("REPLICA_2_URL")],
+  url: env("DATABASE_URL", "./database/db.sqlite"),
+  // `env()` with no fallback is `string | undefined`, and an unset replica should
+  // drop out rather than become an empty connection string.
+  replicas: [env("REPLICA_1_URL"), env("REPLICA_2_URL")].filter((url) => url !== undefined),
 });
 ```
 
@@ -296,7 +300,7 @@ No model code changes needed. Routing is automatic:
 
 After a write, the replica may lag. Use `DB.onPrimary()` when you need to read the just-written data immediately:
 
-```typescript
+```typescript fragment
 // in a controller
 const post = await Post.create({ title: "Hello", userId });
 
@@ -327,7 +331,7 @@ that did not exist. `NPlusOneError.distinctArgs` carries the count if you want t
 Tune the detector once at boot. Lower the `threshold` to catch leaks sooner, and set
 `mode: "throw"` in CI so an N+1 query fails the test suite instead of just logging:
 
-```typescript
+```typescript fragment
 // bootstrap/app.ts — or a service provider
 DB.preventNPlusOne({
   threshold: 3, // warn after 3 repetitions instead of 5
@@ -341,7 +345,7 @@ Some repetition is intentional — a polling endpoint, an audit log — and you
 the detector crying wolf. Call `allowNPlusOne` to silence a specific table, either for
 good or just for the current request:
 
-```typescript
+```typescript fragment
 // in a service provider or request handler
 // Suppress permanently for a table/pattern
 DB.allowNPlusOne("activity_logs");
@@ -373,7 +377,7 @@ With the connection registered, set `static connection` on any model that should
 there. From then on every query that model makes — reads, writes, pagination — is routed
 to that connection with no extra arguments:
 
-```typescript
+```typescript fragment
 // app/models/AnalyticsEvent.ts
 export class AnalyticsEvent extends Model {
   static connection = "analytics";
@@ -400,7 +404,7 @@ Connection resolution priority (highest to lowest):
 
 Use advisory locks for application-level mutual exclusion — e.g. preventing two workers from processing the same job simultaneously:
 
-```typescript
+```typescript fragment
 // in a job or worker
 import { DB } from "@zerotal/orm";
 
@@ -435,9 +439,10 @@ from a service provider:
 For example, subscribe to `QueryExecuted` in a provider to surface slow queries in your
 logs — the handler receives the SQL, its bindings, and how long it took:
 
-```typescript
+```typescript fragment
 // in a service provider
-import { FrameworkEvents, QueryExecuted } from "zerotal";
+import { FrameworkEvents } from "zerotal";
+import { QueryExecuted } from "@zerotal/orm";
 
 // Log slow queries
 FrameworkEvents.on(QueryExecuted, (e) => {

package/docs/deployment.md

@@ -228,7 +228,7 @@ which behind a proxy is the loopback address it bound to (`http://127.0.0.1:3002
 the public URL the browser sends. So the public origin has to come from config, and it
 does: `AppConfig()` fills `app.allowedOrigins` from `url`.
 
-```ts
+```ts fragment
 // config/app.ts
 export default AppConfig({
   name: "My App",
@@ -240,7 +240,7 @@ Name additional origins only when a genuinely different host drives the app —
 `app.example.com` calling `api.example.com`. What you pass is added to the URL's origin
 rather than replacing it:
 
-```ts
+```ts fragment
 // config/app.ts
 export default AppConfig({
   url: env("APP_URL"),

package/docs/devtools.md

@@ -57,7 +57,7 @@ lifecycle order, all of them additionally short-circuited in production):
 > **Note** — Nothing happens at import time. The trace store opens its database
 > on first use rather than in a constructor, so importing this package in an app
 > that runs in production writes nothing and starts no timer. N+1 detection
-> itself is owned by the [ORM](/docs/orm/index) provider (and env-gated there);
+> itself is owned by the [ORM](/docs/orm) provider (and env-gated there);
 > DevTools only consumes the `NPlusOneDetected` event and surfaces it.
 
 ## Start the client panel
@@ -100,7 +100,7 @@ after works the way you would expect.
 
 `DevTools.start()` accepts three optional fields:
 
-```typescript
+```typescript fragment
 // resources/js/app.js
 DevTools.start({ endpoint: "/__zerotal/devtools", mode: "floating" }); // defaults
 ```
@@ -356,7 +356,7 @@ log line's, a stack frame. Going from "this query is slow" to the line that ran
 it is the most frequent move in a debugging session, and without this it is two
 manual searches.
 
-```typescript
+```typescript fragment
 // config/devtools.ts
 export default DevtoolsConfig({
   editor: "cursor", // vscode | vscode-insiders | cursor | windsurf | zed | webstorm
@@ -369,7 +369,7 @@ Set `editor: null` to render locations as plain text instead.
 the one with your editor on it — a container reports `/app/src/Foo.ts` for a file
 that lives at `~/project/src/Foo.ts`. Map it home:
 
-```typescript
+```typescript fragment
 export default DevtoolsConfig({
   editorPathMap: { "/app": "/Users/you/project" },
 });
@@ -425,7 +425,7 @@ things that look like secrets. `console.log(user)` is masked field by field;
 
 Open individual names back up, close extra ones, or turn it off entirely:
 
-```typescript
+```typescript fragment
 // config/devtools.ts
 export default DevtoolsConfig({
   redact: {
@@ -458,7 +458,7 @@ directly when you are recording values somewhere else and need the same three
 problems solved — cycles, a depth bound, and values like `Date` or `File` that
 read better flat than walked — but want your own markers:
 
-```typescript
+```typescript fragment
 import { redactGraph } from "@zerotal/core/security";
 
 const safe = redactGraph(payload, {
@@ -557,7 +557,7 @@ the inspector on a shared staging box was to lie about `APP_ENV`.
 
 There is now a supported way:
 
-```typescript
+```typescript fragment
 // config/devtools.ts
 export default DevtoolsConfig({
   enabled: true, // explicit; `null` follows the dev-surface gate
@@ -589,7 +589,7 @@ there the way in is the dashboard at `/__zerotal/devtools`.
 
 To switch it off entirely without removing the provider:
 
-```typescript
+```typescript fragment
 // config/devtools.ts
 export default DevtoolsConfig({ enabled: false });
 ```
@@ -618,7 +618,7 @@ the way — not about the panel itself.
 injection middleware appends a script tag to every HTML response, and a
 misconfigured deploy that ships it exposes request traces to your users:
 
-```typescript
+```typescript fragment
 // tests/devtools/injection.test.ts
 import { test } from "bun:test";
 import { createApp } from "../helpers.ts";
@@ -637,7 +637,7 @@ test("the devtools script is not injected outside development", async () => {
 to a JSON body or a file download corrupts it, and the failure shows up as a
 parse error somewhere unrelated:
 
-```typescript
+```typescript fragment
 // tests/devtools/injection.test.ts
 test("JSON responses are left alone", async () => {
   const res = await app.get("/api/posts", { Accept: "application/json" });
@@ -650,7 +650,7 @@ test("JSON responses are left alone", async () => {
 **The trace store is an ordinary object**, so a panel plugin you write tests
 without a browser:
 
-```typescript
+```typescript fragment
 // tests/devtools/plugin.test.ts
 import { traceStore } from "@zerotal/devtools";
 
@@ -753,7 +753,7 @@ leaves. Each node's own fields become its `treeBadge` chip, its `flags`, and a
 dim attribute line, so you describe what a node _is_ without the panel knowing
 what any of it means:
 
-```typescript
+```typescript fragment
 trace.channel({
   id: "widgets",
   label: "Widgets",
@@ -779,7 +779,7 @@ every value any package might use.
 
 The shape pushed to the store and streamed to the panel:
 
-```typescript
+```typescript fragment
 // from @zerotal/devtools
 interface RequestTrace {
   id: string;
@@ -903,7 +903,7 @@ Resolve `devtools.trace` from the container, declare how your entries should
 read, then record one per event. Guard the lookup: it is absent when devtools is
 not installed or the app is in production, and your package must not care.
 
-```typescript
+```typescript fragment
 // your-package/src/observability.ts
 import { FrameworkEvents, RequestContext } from "zerotal";
 import type { Application } from "zerotal";
@@ -955,7 +955,7 @@ and entries recorded before a channel is declared still appear once it is.
 From your package's **browser** code, register a panel on the global registry the
 panel exposes:
 
-```ts
+```ts fragment
 window.__zerotalDevtools?.register({
   id: "my-panel", // unique — the tab is addressed internally as `plugin:my-panel`
   title: "My Panel", // tab label
@@ -1010,4 +1010,4 @@ folded follow-up (`child`).
 - [Query builder](/docs/query-builder) — the queries DevTools traces and flags for N+1.
 - [Events](/docs/events) — the `FrameworkEvents` that DevTools subscribes to.
 - [Telemetry](/docs/telemetry) — production-grade metrics once you move past the dev panel.
-- [Testing](/docs/testing/index) — assert on requests without the floating panel.
+- [Testing](/docs/testing) — assert on requests without the floating panel.

package/docs/email-verification.md

@@ -18,7 +18,7 @@ in `@zerotal/core` signs the link, and `ValidateSignatureMiddleware` in
 `@zerotal/auth` checks it. There is no extra package and no extra table:
 
 ```typescript
-import { Url } from "zerotal";
+import { Url } from "zerotal/http";
 import { ValidateSignatureMiddleware } from "@zerotal/auth";
 ```
 
@@ -51,7 +51,7 @@ register ──▶ Url.sign(/auth/verify?id&email, ttl) ──▶ email link
 
 Add a nullable `email_verified_at` column to your users table:
 
-```typescript
+```typescript fragment
 // database/migrations/002_add_email_verified_at.ts
 export default class AddEmailVerifiedAt extends Migration {
   async up(schema: Schema) {
@@ -140,7 +140,7 @@ The verify route is already guarded by `ValidateSignatureMiddleware`, so the
 controller can trust that the URL is intact — it only checks that the `id`/`email`
 pair still resolves to a real user:
 
-```typescript
+```typescript fragment
 // app/controllers/VerificationController.ts
 import { Auth } from "@zerotal/auth";
 import { Notify } from "@zerotal/notifications";
@@ -199,7 +199,7 @@ export class VerificationController {
 
 ## Routes
 
-```typescript
+```typescript fragment
 // routes/web.ts
 import { ValidateSignatureMiddleware } from "@zerotal/auth";
 import { RequireAuthMiddleware } from "#app/middleware/RequireAuth.ts";
@@ -220,7 +220,7 @@ Router.post("/auth/verify/resend", VerificationController, "resend", [RequireAut
 Call `Notify.queue()` at the end of your registration handler so the HTTP response
 returns immediately while delivery happens in the background:
 
-```typescript
+```typescript fragment
 // app/controllers/AuthController.ts
 import { Notify } from "@zerotal/notifications";
 import { VerifyEmailNotification } from "#app/notifications/VerifyEmailNotification.ts";
@@ -242,7 +242,7 @@ Write a `VerifiedMiddleware` once and apply it to routes that must only be
 accessible to verified users. It extends `BaseMiddleware` (from `zerotal`)
 and reads the current user via `Auth.userOrNull()`:
 
-```typescript
+```typescript fragment
 // app/middleware/Verified.ts
 import { BaseMiddleware } from "zerotal";
 import type { HttpContext, NextFn } from "zerotal";
@@ -273,7 +273,7 @@ export class VerifiedMiddleware extends BaseMiddleware {
 Apply it alongside `RequireAuthMiddleware` so unverified users are bounced to the
 notice page:
 
-```typescript
+```typescript fragment
 // routes/web.ts
 Router.group({ middleware: [RequireAuthMiddleware, VerifiedMiddleware] }, () => {
   Router.get("/dashboard", DashboardController, "index");
@@ -284,7 +284,7 @@ Router.group({ middleware: [RequireAuthMiddleware, VerifiedMiddleware] }, () =>
 
 ## Testing
 
-```typescript
+```typescript fragment
 // tests/email-verification.test.ts
 it("unverified user is redirected to notice page", async () => {
   const user = await UserFactory.create({ emailVerifiedAt: null });

package/docs/encryption.md

@@ -81,7 +81,7 @@ Crypt.decrypt<{ userId: number }>(blob).userId; // 7
 algorithm is auto-detected on verify, so changing the default never breaks
 existing hashes.
 
-```ts
+```ts fragment
 // in a controller or service
 import { Hash } from "zerotal/security";
 
@@ -147,7 +147,7 @@ thread a signing key through your code.
 
 ### Generating a signed URL
 
-```ts
+```ts fragment
 function sign(
   base: string,
   params?: Record<string, string>,
@@ -173,7 +173,7 @@ per-feature invite secret): `Url.sign(base, params, minutes, inviteSecret)`.
 
 ### Verifying a signed URL
 
-```ts
+```ts fragment
 // in a controller
 import { Url } from "zerotal/http";
 
@@ -209,7 +209,7 @@ Apply `ValidateSignatureMiddleware` to any route that receives signed URLs — i
 rejects invalid or expired links with a 403 JSON response, so your controller
 only runs when the signature is good:
 
-```ts
+```ts fragment
 // routes/web.ts
 import { ValidateSignatureMiddleware } from "@zerotal/auth";
 
@@ -277,7 +277,7 @@ that a round-trip test alone would never notice.
 **Tampering must throw**, and proving it is what tells you the payload is
 authenticated rather than merely scrambled:
 
-```typescript
+```typescript fragment
 // tests/security/Crypt.test.ts
 import { DecryptionError } from "zerotal/security";
 
@@ -292,7 +292,7 @@ test("a modified payload is rejected", () => {
 **`encrypt()` round-trips any JSON value**, so a test covering an object confirms
 the serialisation as well as the cipher:
 
-```typescript
+```typescript fragment
 // tests/security/Crypt.test.ts
 const payload = Crypt.encrypt({ userId: 7, scopes: ["read"] });
 
@@ -303,7 +303,7 @@ Hashing has its own trap: every `Hash` method except `needsRehash` is async, and
 forgotten `await` yields a `Promise`, which is always truthy — the one mistake in
 this API that silently passes.
 
-```typescript
+```typescript fragment
 // tests/security/Hash.test.ts
 import { Hash } from "zerotal/security";