@zerotal/arch 1.8.1 → 1.10.0

package/docs/telemetry.md

@@ -497,6 +497,14 @@ console.log(mem.spans[0]?.attributes["x"]); // 1
 | `'producer'` | Enqueuing a message.                                        |
 | `'consumer'` | Processing a queued message.                                |
 
+## Types
+
+| Type                           | What it is                                                                               |
+| ------------------------------ | ---------------------------------------------------------------------------------------- |
+| `TelemetryOptions`             | What `TelemetryConfig()` accepts.                                                        |
+| `OtlpExporterOptions`          | Where spans are shipped, and how.                                                        |
+| `SpanStatus`, `SpanStatusCode` | A span's outcome — `unset`, `ok` or `error`, which is what a backend colours a trace by. |
+
 ## Next steps
 
 - [Logger](/docs/logger) — pair traces with structured logs.

package/docs/tenancy.md

@@ -593,6 +593,12 @@ Resolved from the container binding `"tenancy"`; the `Tenant` value is the facad
 | `evict`         | `evict(tenant): void`                | Close and drop a tenant's connection.             |
 | `closeAll`      | `closeAll(): void`                   | Close every open connection.                      |
 
+## Types
+
+`TenancyStrategy` is how a tenant is resolved from a request — subdomain, path, header, or the
+authenticated user. `TenantManagerOptions` configures the manager, and `TenantDeletedHook` runs
+when a tenant is removed, which is where the data belonging to it gets cleaned up.
+
 ## Next steps
 
 - [ORM](/docs/orm) — how `Tenantable` composes onto your models via `Model.using`.

package/docs/testing/index.md

@@ -209,6 +209,105 @@ 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`.
 
+## `bun test` vs `bun zt test`
+
+Both run the same files. `bun zt test` is a wrapper that sets up three things Bun's
+runner does not, and each of them has cost somebody a day:
+
+|                  | `bun test`            | `bun zt test`                                              |
+| ---------------- | --------------------- | ---------------------------------------------------------- |
+| Per-test timeout | Bun's default, 5000ms | 30000ms (`--timeout`, override with `--timeout=`)          |
+| Runtime check    | none                  | refuses a Bun below the project's `engines.bun`            |
+| DB wiring        | none                  | preloads `@zerotal/testing/preload` and passes `ZT_DB_URL` |
+
+### The timeout
+
+Bun's default per-test timeout is 5000ms, and a suite that boots an app per file
+exceeds it on a loaded machine — CI, or a laptop that has just run `tsc`. The
+failures look like flakes, which is the expensive part: a flake gets re-run, and a
+re-run passes.
+
+`bun zt test` sets `--timeout=30000`. If you run `bun test` directly, pass it
+yourself, because **the two documented-looking alternatives do not work**:
+
+- `[test] timeout` in `bunfig.toml` — ignored.
+- `setDefaultTimeout()` in a preload — applies to the first test file only. Bun
+  re-imports the preload per file, but the setting does not survive.
+
+The command-line flag is the only mechanism that covers hooks as well as tests,
+which matters because it is usually a `beforeAll` that boots the app.
+
+### The runtime
+
+`engines.bun` in your `package.json` is a floor, and until you enforce it, it is a
+comment. The shell's `bun` and the project's can differ, and the difference between
+two Bun releases is real and narrow: `Intl` formatting, the SQLite bindings and
+`node:` compatibility all move. So a handful of currency or date assertions go red
+and the rest pass, and you go looking for a bug in the code they touch, because
+nothing in the failure says "wrong binary".
+
+`bun zt test` refuses to run below the declared floor. Direct `bun test` runs get the
+same check as a warning if you load the preload:
+
+```toml
+# bunfig.toml
+[test]
+preload = ["@zerotal/testing/preload"]
+timeout = 30000  # note: currently ignored by Bun — pass --timeout on the command line
+```
+
+Set `ZT_ALLOW_RUNTIME_MISMATCH=1` to downgrade the refusal to a warning while you
+are mid-upgrade.
+
+### `@zerotal/core/runtime`
+
+The checks behind the two paragraphs above, exported so a script or a test of your
+own can make the same assertion. `zt` runs both at the top of every command; the test
+preload runs the floor check as a warning.
+
+| Export                     | Signature                                                 | What it answers                                                                             |
+| -------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `declaredBunFloor`         | `declaredBunFloor(cwd): { range, manifest } \| null`      | The nearest `engines.bun` up the tree from `cwd`.                                           |
+| `runtimeBelowFloor`        | `runtimeBelowFloor(cwd?): RuntimeFloor \| null`           | Is this process below that floor? `null` when it is met or none is declared.                |
+| `runtimeBelowFloorMessage` | `runtimeBelowFloorMessage(floor): string`                 | The explanation to print — both versions, the manifest, and the way out.                    |
+| `installedBunVersion`      | `installedBunVersion(cwd): { version, manifest } \| null` | The Bun in `node_modules`, if the project installs one as a package.                        |
+| `runtimeMismatch`          | `runtimeMismatch(cwd?): RuntimeMismatch \| null`          | Does the running Bun differ from the installed one? Compared exactly — a patch is a binary. |
+| `runtimeMismatchMessage`   | `runtimeMismatchMessage(mismatch): string`                | The explanation for that one.                                                               |
+| `runtimeMismatchAllowed`   | `runtimeMismatchAllowed(): boolean`                       | Whether `ZT_ALLOW_RUNTIME_MISMATCH` is set.                                                 |
+| `bunBinary`                | `bunBinary(): string`                                     | The binary to spawn a child with — `process.execPath`, never the name PATH resolves.        |
+| `RUNTIME_MISMATCH_ESCAPE`  | `"ZT_ALLOW_RUNTIME_MISMATCH"`                             | The env var name, so a script can set it without hardcoding the string.                     |
+
+`RuntimeFloor` is `{ running, required, manifest }`; `RuntimeMismatch` is
+`{ running, installed, manifest }`. Both name the file the second version came from,
+because "which one is wrong" is the question you actually have.
+
+## Configuration is per-process, and `bun test` is one process
+
+Zerotal resolves configuration once, at boot. `bun test` runs every file in the same
+process, so **whichever file boots the app first fixes the configuration for all of
+them.**
+
+A test that sets an environment variable in its own `beforeAll` and then asserts on
+the resulting behaviour passes alone and fails in the suite — or worse, passes in the
+suite for a reason unrelated to what it claims to test:
+
+```typescript fragment
+// Passes alone. In a suite, the app may already be booted with CSRF on, and the
+// three "rejects without a token" assertions below pass on a 419 they would have
+// got anyway — never reaching the guard they name.
+beforeAll(() => {
+  Bun.env.CSRF_DISABLED = "1";
+});
+```
+
+Assert on the _relationship_ rather than on a literal — the published origin equals
+the configured one, whatever it is — or boot a dedicated app for the case:
+
+```typescript fragment
+const app = await createTestApp({ config: { app: { url: "https://example.test" } } });
+expect(page.canonical).toBe(config("app.url"));
+```
+
 ## 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:
@@ -256,6 +355,12 @@ its full surface.
 | `fake`                  | `typeof fake`                                                                                    | South-African-flavoured random data generator.       |
 | `fakeFile`              | `typeof fakeFile`                                                                                | Real PNG/JPEG/GIF/PDF files for upload tests.        |
 
+### Types
+
+`TestResponseContext` is what an assertion receives, `SessionDecoder` reads the session out of a
+response so a test can assert on it, and `FakeFile` / `TestFileInput` / `TestFormValue` are the
+shapes a multipart submission takes in a test.
+
 ## Next steps
 
 - [HTTP Tests](/docs/testing/http) — the full `TestApp` and `TestResponse` API.

package/docs/upgrade.md

@@ -169,6 +169,54 @@ these are the changes that need action. Full detail is in the
    interface so pages that read them do not look unpassed; see
    [Typed props](/docs/inertia/props#typed-props).
 
+## 1.9 to 1.10
+
+Three settings changed meaning. Each is quiet if it does not apply to you, and each is
+worth thirty seconds of checking if it does.
+
+1. **`scheduler.timezone` is honoured.** It was documented as informational and read by
+   nothing, so whatever you put there had no effect and your schedules ran in the
+   server's zone. It is now the zone every schedule is evaluated in unless the task sets
+   its own.
+
+   Its default moved from the literal `"UTC"` to **the system zone**, so an app that never
+   set the key keeps doing exactly what it did. The case to check is an app that _did_:
+
+   ```ts fragment
+   // config/scheduler.ts
+   export default SchedulerConfig({ timezone: env("APP_TIMEZONE", "UTC") });
+   ```
+
+   On a server that is not on UTC, that line used to do nothing and now moves every
+   schedule. Either set it to the zone you actually want your crons read in — which is
+   the point of the setting — or delete the key to keep the server's zone.
+
+   `bun zt schedule:list` prints each task's next run in its own zone, which is the
+   quickest way to see whether anything moved.
+
+2. **Named rate limiters need `.trustedProxies(n)` behind a proxy.** `RateLimiter`'s
+   `.byIp()`, `.byUser()` and `.byApiKey()` ignored the proxy count entirely and read
+   `X-Forwarded-For` unconditionally. They now follow the same rule `ThrottleMiddleware`
+   already did — the header is consulted only when you say how many proxies sit in front:
+
+   ```ts fragment
+   RateLimiter.for("login").limit(5).every(60).byIp().trustedProxies(1).register();
+   ```
+
+   Without it the address used is the socket's, which behind a proxy is the _proxy's_, and
+   every visitor shares one bucket. `bun zt doctor` reports any limiter that needs this —
+   it could not before, because its check exempted custom key resolvers and all three of
+   these are one.
+
+3. **React apps using SSR need `@inertiajs/react` installed.** The same adapter your
+   browser entry point already uses. Server-side rendering now goes through its `<App>`,
+   which is what makes `<Head>` produce a title and an og: card in the HTML your server
+   actually sends. If it is missing you get a named error at render time, not a silent
+   omission.
+
+   Nothing to change if you already have it as a dependency, which every React Inertia app
+   does.
+
 ## The managed zt.ts
 
 `zt.ts` is framework-managed — the header says _do not modify_. If a release

package/docs/validator.md

@@ -540,6 +540,15 @@ res.assertUnprocessable(); // 422 for a JSON request
 | `validate`        | `validate(ctx, factory): Promise<Infer<…>>`  | One-off HTTP validation; throws on failure.          |
 | `Validator.check` | `check(data, factory): ValidationOutcome<…>` | Non-HTTP validation; returns a result, never throws. |
 
+## Types
+
+| Type                        | What it is                                                                                               |
+| --------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `ValidationErrors`          | The error bag — field name to messages, which is what `withErrors()` and the `errors` shared prop carry. |
+| `FieldRuleDefinition`       | One field's rules as declared.                                                                           |
+| `InferFieldType<R>`         | The type a rule set produces, so validated data is typed rather than `unknown`.                          |
+| `PrecognitionResponseError` | What a precognition request returns when a field fails ahead of submission.                              |
+
 ## Next steps
 
 - [Requests Context](/docs/context#reading-input) — read the input that `FormRequest` validates.

package/docs/view.md

@@ -444,6 +444,12 @@ res.assertDontSee("Draft"); // unpublished posts stay hidden
 | `Children`       | Type for the `children` prop.                                                                                             |
 | `HttpContext<T>` | The request context a view component or controller action receives; route params and model bindings live on `ctx.params`. |
 
+## Types
+
+`ViewComponent` is what `view()` accepts — a function taking the request context and your props,
+returning markup. `ViewLayout` is the wrapper form a layout takes. Both are exported so a helper
+that returns a component, or a registry that holds several, can be typed.
+
 ## Next steps
 
 - [Flow](/docs/flow) — server-driven interactive components over WebSocket.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/arch",
-  "version": "1.8.1",
+  "version": "1.10.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -35,11 +35,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.8.1"
+    "@zerotal/core": "1.10.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "@zerotal/orm": "1.8.1"
+    "@zerotal/orm": "1.10.0"
   },
   "description": "The Zerotal agent surface — an MCP server that hands coding agents the framework's machine-readable truth: exact API signatures, live routes and schema, version-matched docs, and `zt doctor`.",
   "keywords": [

package/src/install/guidelines.ts

@@ -150,7 +150,7 @@ export interface GuidelineOptions {
    * How this project is configured, from {@link detectShape}. Omitted, the block
    * is what it always was — a function of the package list.
    */
-  shape?: ProjectShape;
+  shape?: ProjectShape | undefined;
 }
 
 /**

package/src/mcp/stdio.ts

@@ -27,11 +27,11 @@ import type { JsonRpcResponse } from "./types.ts";
 export interface StdioOptions {
   server: McpServer;
   /** Byte source. Defaults to this process's stdin. */
-  input?: ReadableStream<Uint8Array>;
+  input?: ReadableStream<Uint8Array> | undefined;
   /** Frame sink. Defaults to this process's stdout. Injected in tests. */
-  write?: (frame: string) => void;
+  write?: ((frame: string) => void) | undefined;
   /** Diagnostics sink. Defaults to stderr — never stdout. */
-  log?: (message: string) => void;
+  log?: ((message: string) => void) | undefined;
 }
 
 /**

package/src/tools/_probe.ts

@@ -35,8 +35,8 @@ export interface ProbeRunner {
 
 export interface SpawnProbeOptions {
   /** Where to start looking for the app. Defaults to the server's working directory. */
-  cwd?: string;
-  timeoutMs?: number;
+  cwd?: string | undefined;
+  timeoutMs?: number | undefined;
 }
 
 /**