@zerotal/arch 1.8.0 → 1.9.0

package/docs/routing.md

@@ -1081,6 +1081,22 @@ Every route registration returns a chainable handle:
 | `bun zt route:list`                    | —                                   | Print every route (`-m` method, `-p` path, `--name`, `-v` middleware).  |
 | `bun zt route:types`                   | `--check`                           | Write `types/routes.generated.ts`; `--check` fails when it is stale.    |
 
+## Types
+
+| Type                 | What it is                                                                                                |
+| -------------------- | --------------------------------------------------------------------------------------------------------- |
+| `HttpMethod`         | The verbs a route can answer on.                                                                          |
+| `HttpResponse`       | What a handler may return when it does not write to `ctx.response`.                                       |
+| `ControllerResponse` | A controller action's return type — `void`, a `ResponseBuilder`, or a `MarkdownBuilder`.                  |
+| `RouteParams`        | The params a pattern captures, as a record.                                                               |
+| `ParamsOf<P>`        | The params of one pattern, derived from the pattern string — what makes `route()` refuse a missing `:id`. |
+| `RouteRegistry`      | The generated name → pattern table, augmented by `types/routes.generated.ts`.                             |
+| `RouteMiddleware`    | What a route's middleware list accepts — a class, an array, or the method map.                            |
+| `GroupOptions`       | `Router.group({ prefix, middleware, domain })`.                                                           |
+| `RoutingConfig`      | The `routing` config namespace.                                                                           |
+| `FileRoutingConfig`  | File-router settings within it.                                                                           |
+| `WebSocketHandlers`  | The handler set a WebSocket route registers.                                                              |
+
 ## Next steps
 
 - [Controllers](/docs/controllers) — move route logic out of closures.

package/docs/scheduler.md

@@ -525,6 +525,17 @@ The `Scheduler` facade resolves the `scheduler` container binding — a
 | `lastDurationMs`   | `get lastDurationMs(): number \| undefined` | Duration of the last run in ms.                   |
 | `isRunning`        | `get isRunning(): boolean`                  | `true` while a run is in flight.                  |
 
+## Types
+
+| Type                                    | What it is                                                                                   |
+| --------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `CronExpression`                        | The schedule string a task declares.                                                         |
+| `TaskGuard`                             | A condition deciding whether a due run actually happens — a feature flag, a leader election. |
+| `TaskHook`                              | What runs before or after a task.                                                            |
+| `ScheduleRunRecord`, `ScheduleRunStore` | One recorded run, and where the log is kept.                                                 |
+| `RunLogConfig`                          | How much of that log is retained.                                                            |
+| `OutputMailer`                          | Sending a task's output somewhere when it finishes.                                          |
+
 ## Next steps
 
 - [Queue](/docs/queue) — schedules typically dispatch jobs; the worker runs both.

package/docs/session.md

@@ -444,6 +444,12 @@ try {
 The fix is nearly always to store an identifier rather than the object, or to
 move to a server-side driver where the cookie holds only the session id.
 
+## Types
+
+`SessionDriver` is the storage contract — implement it to keep sessions somewhere the built-ins
+do not reach. `SessionPayload` is what a driver loads and saves: the id and the data bag.
+`SessionAccessor` is the request-scoped handle `ctx.session` exposes.
+
 ## Next steps
 
 - [Middleware](/docs/middleware) — where `SessionMiddleware` and `CsrfMiddleware`

package/docs/social.md

@@ -516,6 +516,16 @@ validation errors is exactly the string you forward to `?error=`.
 | `OAuthUserFetchError`           | provider message          | User-profile fetch failed.                         |
 | `AppleClientSecretError`        | Apple credentials message | Apple driver has neither a JWT nor raw key trio.   |
 
+## Types
+
+| Type                | What it is                                                                                                                   |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `OAuth2Config`      | What a provider entry in `config/services.ts` holds — id, secret, redirect URI.                                              |
+| `AppleOAuth2Config` | Apple's, which needs more: a team id, a key id, and the private key it signs with.                                           |
+| `SocialSession`     | What the driver stashes between the redirect out and the callback back.                                                      |
+| `GoogleDriver`      | Exported so a custom driver can extend it rather than reimplement OIDC.                                                      |
+| `FakeSocialDriver`  | What `Social.fake()` installs — returns a canned profile instead of exchanging a code. See [Mocking](/docs/testing/mocking). |
+
 ## Next steps
 
 - [Authentication](/docs/authentication) — establish the session after a social login.

package/docs/storage.md

@@ -626,6 +626,27 @@ Manager and exports from `zerotal/storage`:
 | `StorageProvider`        | `class`                                                         | Registers the `storage` binding.                 |
 | `DiskNotConfiguredError` | `class`                                                         | Thrown when a named disk is missing from config. |
 
+### Types
+
+The config shapes are exported, so a `config/storage.ts` can be annotated and a helper that
+builds disk options can be typed:
+
+| Type                  | What it is                                                                 |
+| --------------------- | -------------------------------------------------------------------------- |
+| `DiskConfig`          | The discriminated union of every disk config — `local` and `s3` today.     |
+| `LocalDiskConfig`     | A local disk: `root`, plus `serve` when it is reachable over HTTP.         |
+| `S3DiskConfig`        | An S3 disk: credentials, `region`, `bucket`, and an optional public `url`. |
+| `DiskServeConfig`     | How a disk is exposed over HTTP — the `serve` block `public` uses.         |
+| `StorageFilesOptions` | Options for `StorageFilesMiddleware`, which serves a disk's files.         |
+| `FakeStoredFile`      | What a faked disk records in tests, for asserting on what was written.     |
+
+`StorageError` is the base every storage failure extends, and `UnsupportedOperationError` is
+what a driver throws for something it genuinely cannot do — a local disk asked for a signed
+URL, for instance — rather than failing quietly and returning nothing.
+
+`S3Driver` is exported so a driver for another S3-compatible service can extend it rather than
+reimplement request signing.
+
 ## Next steps
 
 - [Validator](/docs/validator) — validate file uploads before storing them.

package/docs/support-policy.md

@@ -109,7 +109,19 @@ outcomes — promote, keep with a new date and the reason, or withdraw.
 
 | Package       | Now            | Reviewed by |
 | ------------- | -------------- | ----------- |
-| `@zerotal/ai` | `experimental` | **1.9.0**   |
+| `@zerotal/ai` | `experimental` | **1.11.0**  |
+
+`@zerotal/ai`'s date moved once, from 1.9.0, and the reason is the same one that made it
+experimental in the first place: **it graduates in the release after its first real users, and
+it has not had them yet.** Promoting on a date rather than on evidence is how a label becomes
+decoration — a `stable` promise is only worth making about an API that something has pushed
+against.
+
+The date is a forcing function, not a prediction. It moved once; a second move needs a better
+reason than the first, or the honest answer is to withdraw the package rather than keep
+re-dating it. Its surface triage and the tests for its SSE parser and prompt redaction are worth
+doing meanwhile, and are tracked separately — they improve the package whichever way the review
+goes, and they are what would otherwise turn the deadline into a scramble.
 
 `@zerotal/arch` held `beta` with the same date, was reviewed ahead of it, and is
 `stable` — the release that carried the promotion is the one its

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

@@ -256,6 +256,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/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.0",
+  "version": "1.9.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -35,11 +35,11 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.8.0"
+    "@zerotal/core": "1.9.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "@zerotal/orm": "1.8.0"
+    "@zerotal/orm": "1.9.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/ArchInstallCommand.ts

@@ -16,7 +16,7 @@ import type { Application } from "@zerotal/core";
 import { ArchConfig } from "../config.ts";
 import type { ArchConfigShape } from "../config.ts";
 import { NoProjectRootError } from "../errors.ts";
-import { installedPackages } from "../probe/topics.ts";
+import { declaredPackages } from "../probe/topics.ts";
 import { detectAgents } from "./detect.ts";
 import { agentsPreamble, buildGuidelines, claudeShim } from "./guidelines.ts";
 import { detectShape } from "./shape.ts";
@@ -54,7 +54,9 @@ export class ArchInstallCommand extends Command {
     const config = this._config();
 
     const detected = await detectAgents(root);
-    const packages = (await installedPackages(root)).map((pkg) => pkg.name);
+    // Declared, not installed: what an install layout hoists into node_modules
+    // differs between machines, and the guidance must not.
+    const packages = (await declaredPackages(root)).map((pkg) => pkg.name);
     // Read off disk rather than from a booted app: a project that will not boot is
     // often exactly why someone is installing the agent surface.
     const shape = await detectShape(root);

package/src/probe/topics.ts

@@ -304,3 +304,43 @@ export async function installedPackages(root = process.cwd()): Promise<Installed
 function controllerLabel(rawName: string): string {
   return rawName.startsWith("FileRoute<") ? "file" : rawName;
 }
+
+/**
+ * The `@zerotal/*` packages this app *declares*, with their installed versions.
+ *
+ * {@link installedPackages} answers "what is on disk here", which is the right
+ * answer for a version report and the wrong one for guidance. Two things get into
+ * `node_modules/@zerotal` besides an app's own dependencies: transitive ones, and
+ * whatever an install layout decides to hoist — and layouts disagree. The same
+ * commit of one app resolved seventeen packages on a developer's machine and
+ * eleven on its server, because the server hoisted the shared ones to the
+ * workspace root instead.
+ *
+ * That is not a cosmetic difference when the list decides what an agent is told.
+ * `@zerotal/queue` arriving as a transitive dependency does not mean the app runs
+ * jobs, and a block explaining where jobs live is confidently wrong for an app
+ * that has none. It also made the generated file unstable between machines, so a
+ * check comparing it against the project could not tell drift from a difference
+ * of layout.
+ *
+ * Direct dependencies only, which is both deterministic and the honest reading of
+ * "what this app has": you import what you declare.
+ */
+export async function declaredPackages(root = process.cwd()): Promise<InstalledPackage[]> {
+  let declared: Set<string>;
+  try {
+    const manifest = (await Bun.file(`${root}/package.json`).json()) as {
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+    };
+    declared = new Set([
+      ...Object.keys(manifest.dependencies ?? {}),
+      ...Object.keys(manifest.devDependencies ?? {}),
+    ]);
+  } catch {
+    // No manifest to read — every installed package is as good a guess as any.
+    return installedPackages(root);
+  }
+
+  return (await installedPackages(root)).filter((pkg) => declared.has(pkg.name));
+}

package/src/provider/ArchProvider.ts

@@ -142,7 +142,7 @@ export async function agentsFileCheck(
     };
   }
 
-  const [{ buildGuidelines }, { detectShape }, { installedPackages }, markers] = await Promise.all([
+  const [{ buildGuidelines }, { detectShape }, { declaredPackages }, markers] = await Promise.all([
     import("../install/guidelines.ts"),
     import("../install/shape.ts"),
     import("../probe/topics.ts"),
@@ -160,7 +160,7 @@ export async function agentsFileCheck(
     };
   }
 
-  const packages = (await installedPackages(root)).map((pkg) => pkg.name);
+  const packages = (await declaredPackages(root)).map((pkg) => pkg.name);
   const shape = await detectShape(root);
   const expected = buildGuidelines({
     packages,