@zerotal/arch 1.8.1 → 1.10.0

package/api-surface.md

@@ -119,7 +119,7 @@ interface DoctorReport = {
 interface GuidelineOptions = {
   packages: string[]
   serverName: string
-  shape?: ProjectShape
+  shape?: ProjectShape | undefined
 }
 
 interface InstalledPackage = {
@@ -177,8 +177,8 @@ interface SchemaReport = {
 }
 
 interface SpawnProbeOptions = {
-  cwd?: string
-  timeoutMs?: number
+  cwd?: string | undefined
+  timeoutMs?: number | undefined
 }
 
 interface ToolContext = {
@@ -262,10 +262,10 @@ interface ServerIdentity = {
 }
 
 interface StdioOptions = {
-  input?: ReadableStream<Uint8Array<ArrayBufferLike>>
-  log?: (message: string) => void
+  input?: ReadableStream<Uint8Array<ArrayBufferLike>> | undefined
+  log?: ((message: string) => void) | undefined
   server: McpServer
-  write?: (frame: string) => void
+  write?: ((frame: string) => void) | undefined
 }
 
 interface ToolOutcome = {

package/docs/admin/actions.md

@@ -177,6 +177,21 @@ When the model uses the ORM `SoftDeletes` mixin, the List page gains an
 **Active / All / Trashed** switch and the row + bulk actions gain Restore and
 Force-delete automatically — no extra configuration.
 
+## Types
+
+| Type                                   | What it is                                                               |
+| -------------------------------------- | ------------------------------------------------------------------------ |
+| `ActionItem`                           | One action as the panel holds it, after `action()` has built it.         |
+| `ActionHandler`                        | The callback an action runs, given its `ActionContext`.                  |
+| `ActionContext`                        | What that callback receives — the record or selection, and the page.     |
+| `ActionVisible`                        | The predicate deciding whether an action appears for this record at all. |
+| `ActionColor`                          | The emphasis it is drawn with.                                           |
+| `ConsoleAction`, `ConsoleHeaderAction` | The console's own row and header actions.                                |
+
+**`ActionVisible` hides, it does not authorize.** An action absent from the UI is still
+reachable by anyone who can form the request, so the authorization check belongs in the handler
+as well — see [Authorization](/docs/authorization).
+
 ## Next steps
 
 - [Admin overview](/docs/admin) — the guide's front page and the rest of the sections.

package/docs/admin/auth.md

@@ -83,6 +83,16 @@ Panel.configure({
 `adminTokensCss()` the `:root`/`.dark` custom properties — feed both into your own
 `tailwind.config` so a compiled stylesheet renders identically.
 
+## Types
+
+| Type                          | What it is                                                                                                                                                              |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AdminAuthConfig`             | Who may reach the panel and how they sign in.                                                                                                                           |
+| `AdminAuthorizer`             | The check run before a page renders.                                                                                                                                    |
+| `AuthRolesOptions`            | How panel access maps onto the app's roles.                                                                                                                             |
+| `AdminThemeConfig`            | Panel theming.                                                                                                                                                          |
+| `EnvironmentIndicatorOptions` | The banner naming which deployment you are looking at — worth setting, because the panel looks identical in staging and production and that is exactly when it matters. |
+
 ## Next steps
 
 - [Admin overview](/docs/admin) — the guide's front page and the rest of the sections.

package/docs/admin/dashboard.md

@@ -149,6 +149,18 @@ Custom pages and anything contributed by a package sit in the same sidebar, sort
 and grouped by the same rules — a page's group heading is just a string, so a page
 and a resource that name the same group land together.
 
+## Types
+
+| Type                                      | What it is                                                                  |
+| ----------------------------------------- | --------------------------------------------------------------------------- |
+| `DashboardWidget`                         | One widget as declared.                                                     |
+| `WidgetContribution`                      | A widget pushed in by another package.                                      |
+| `WidgetTone`                              | Its good/warn/bad colouring.                                                |
+| `StatsResolver`                           | Supplies a stat widget's numbers for the selected range.                    |
+| `ChartResolver`, `ChartData`              | The same for a chart, and the shape it returns.                             |
+| `TableWidgetColumn`                       | A column in a table widget — narrower than a resource table's.              |
+| `DashboardLayout`, `DashboardLayoutStore` | An arrangement of widgets, and where a user's own arrangement is persisted. |
+
 ## Next steps
 
 - [Admin overview](/docs/admin) — the guide's front page and the rest of the sections.

package/docs/admin/extending-ui.md

@@ -221,6 +221,20 @@ the table — the search term, each filter, the trashed scope — and each chip
 its own undo. A table showing four of two hundred rows for no visible reason is
 the most common way a panel misleads someone; the chips are the fix.
 
+## Types
+
+The contribution shapes another package pushes into the panel:
+
+| Type                                                               | What it is                                                               |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| `NavItem`, `NavGroup`, `NavContribution`                           | A sidebar entry, a heading it sits under, and a contributed one.         |
+| `PageContribution`                                                 | A whole page added to the panel.                                         |
+| `UserMenu`, `UserMenuItem`, `UserMenuContribution`                 | The account menu and its entries.                                        |
+| `TopbarSlot`                                                       | Where something may be placed in the top bar.                            |
+| `RenderHookName`                                                   | Every point the panel can be extended at — the enumeration of the slots. |
+| `RenderHookContext`                                                | What a hook receives when it runs.                                       |
+| `ConsoleContribution`, `ConsoleColumn`, `ConsoleRow`, `ConsoleTab` | Contributions to the console page.                                       |
+
 ## Next steps
 
 - [Tables](/docs/admin/tables) — columns, filters and the query builder.

package/docs/admin/forms.md

@@ -149,6 +149,21 @@ section("Line items").schema([
 ]),
 ```
 
+## Types
+
+| Type               | What it is                                                                        |
+| ------------------ | --------------------------------------------------------------------------------- |
+| `FormComponent`    | Anything that can appear in a form — a field, a layout block, a custom component. |
+| `FormBlock`        | A grouping: a section, a tab, a fieldset.                                         |
+| `FieldMode`        | Whether a field is editable, read-only or hidden in this context.                 |
+| `FieldPredicate`   | The condition behind a conditional field.                                         |
+| `FormModeConfig`   | How the form differs between create and edit.                                     |
+| `UploadedFileLike` | What a file field hands your handler.                                             |
+
+Infolists — the read-only counterpart — use `InfolistComponent`, with `EntryKind`,
+`EntryDisplay`, `EntrySize` and `EntryWeight` describing one entry's type and presentation.
+`PrimeKind` is the leading entry a record view opens with.
+
 ## Next steps
 
 - [Admin overview](/docs/admin) — the guide's front page and the rest of the sections.

package/docs/admin/operations.md

@@ -217,6 +217,18 @@ A coloured strip across the top names the environment — red for production, am
 staging. It returns nothing in local development, so registering it unconditionally is
 the intended usage; there is nothing to switch off per environment.
 
+## Types
+
+| Type                                        | What it is                                             |
+| ------------------------------------------- | ------------------------------------------------------ |
+| `HistoryOptions`, `HistoryChange`           | Record history: what is tracked, and one entry of it.  |
+| `ImportRecordsPayload`                      | What the import action hands your handler.             |
+| `AdminNotification`, `StoredNotification`   | A panel notification, and the persisted form.          |
+| `DatabaseNotificationOptions`               | Where those are stored.                                |
+| `StoreMediaOptions`, `DatabaseMediaOptions` | Media handling and its database backing.               |
+| `SearchHit`, `PanelSearchProvider`          | One global-search result, and where results come from. |
+| `CalloutTone`                               | The emphasis a callout is drawn with.                  |
+
 ## Next steps
 
 - [Panel Structure](/docs/admin/structure) — clusters, nested resources, multiple panels.

package/docs/admin/resources.md

@@ -125,6 +125,12 @@ including on create.
 Both save hooks receive the `mode`, so one implementation can branch on `"create"`
 versus `"edit"` instead of duplicating the resource.
 
+## Types
+
+`AdminModel` is what a resource's `model` accepts, and `AdminQuery` the query it builds — the
+seam where the panel hands off to the ORM. `ListOptions` configures the list page,
+and `RelationKind` names the relation types a relation manager understands.
+
 ## Next steps
 
 - [Admin overview](/docs/admin) — the guide's front page and the rest of the sections.

package/docs/admin/tables.md

@@ -179,6 +179,27 @@ How the table renders — grid instead of rows, striping, sticky headers, densit
 and where the filters sit are covered in
 [Extending the UI](/docs/admin/extending-ui#table-presentation).
 
+## Types
+
+What a column, filter and query rule are made of. All exported, so a helper that builds a
+column set for several resources can be typed rather than repeated.
+
+| Type                                                       | What it is                                                                                          |
+| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| `ColumnKind`                                               | Which column type this is — text, badge, boolean, date, and the rest.                               |
+| `ColumnOption`                                             | One column's settings.                                                                              |
+| `CellAlign`                                                | `start` / `center` / `end`.                                                                         |
+| `ColumnSummary`, `SummaryKind`, `SummaryResult`            | A footer aggregate: what to compute, and what comes back.                                           |
+| `BadgeTone`                                                | The colouring a badge column maps a value to.                                                       |
+| `EmptyState`                                               | What the table shows instead of rows when there are none.                                           |
+| `PivotColumn`                                              | A column reading a pivot table's own attributes on a many-to-many.                                  |
+| `FilterOption`, `FilterType`, `FilterApply`                | A filter's declaration, its kind, and how it modifies the query.                                    |
+| `ConstraintKind`, `ConstraintOperator`, `ConstraintOption` | The query-builder constraints behind advanced filtering.                                            |
+| `QueryRule`, `Conjunction`, `QueryModifier`                | One rule, how rules combine (`and` / `or`), and a raw modifier for what the builder cannot express. |
+| `SavedView`, `SavedViewProvider`                           | A stored filter set, and where those are kept.                                                      |
+| `TableRowsResolver`                                        | Supplying rows yourself instead of letting the resource query.                                      |
+| `ExportFormat`                                             | What the export action writes.                                                                      |
+
 ## Next steps
 
 - [Admin overview](/docs/admin) — the guide's front page and the rest of the sections.

package/docs/audit.md

@@ -359,6 +359,11 @@ app.container.singleton(
 | `auditLog`  | `(event: AuditEvent, payload?: InstanceAuditPayload) => Promise<void>` | Log a custom event against this instance.   |
 | `auditLogs` | `() => ModelQueryBuilder<AuditLog>`                                    | Chainable query of this instance's history. |
 
+## Types
+
+`AuditableOptions` is what `Model.using(Auditable)` accepts — which columns are tracked and
+which are ignored. `AuditConfigShape` is the `audit` config namespace.
+
 ## Next steps
 
 - [ORM Lifecycle](/docs/orm/lifecycle) — the model hooks the audit system listens to.

package/docs/authentication.md

@@ -94,7 +94,12 @@ export class User extends AuthUser {
 }
 ```
 
-`AuthUser` provides `getAuthId()` (returns `this.id`) and `getAuthPassword()` (returns `this.password`). Make `Auth.user()` return your concrete type by augmenting `UserModel` once:
+`AuthUser` provides `getAuthId()` (returns `this.id`) and `getAuthPassword()` (returns `this.password`).
+
+### Bind the type — a required step
+
+Do this once, or every `Auth.user()` in the app returns the framework's minimal `UserModel`
+and reading your own columns off it is a type error:
 
 ```typescript fragment
 // bootstrap/app.ts (or any file imported at boot)
@@ -105,6 +110,17 @@ declare module "@zerotal/auth" {
 }
 ```
 
+`AuthenticatableUser` in `@zerotal/core/contracts` is the same seam one layer down: `@zerotal/core`
+has to talk about "the user" without depending on `@zerotal/auth`, so it declares an empty
+interface for apps to augment, and `UserModel` extends it. Augmenting either resolves to the same
+shape — augment `UserModel`, which is the one the auth docs and examples use.
+
+**The empty body is the point.** The interface is not being given members — it is being
+pointed at your class, so that everywhere the framework says `UserModel` it means `User`.
+That is not a shape anyone guesses, which is why it is here in setup rather than filed
+under advanced usage. Put it somewhere that is imported at boot and leave a comment saying
+what it is for; it looks like dead code otherwise.
+
 ## How it works
 
 On every request `PersistUserMiddleware` reads `user_id` from the session and populates `ctx.user`. If `user_id` is present but the user no longer exists, the stale key is cleared.
@@ -133,6 +149,20 @@ await Auth.login(user); // write user_id to session, set ctx.user
 await Auth.logout(); // clear user_id from session, unset ctx.user
 ```
 
+> **`Auth.user()` throws for a guest, and the name does not telegraph that.** It is the right
+> call behind `AuthMiddleware`, where a user is guaranteed — that guarantee is what makes its
+> non-optional return type honest. It is the wrong call on any route a signed-out person can
+> reach. Plenty of audited things happen with nobody signed in: a storefront checkout, a
+> customer approving a change from a tokenised link, an incoming webhook. On those routes an
+> audit line that reaches for `Auth.user()` turns into a 401 on a public page, and the 401 is
+> about the audit line rather than about the request.
+>
+> ```typescript fragment
+> // A guest is a normal outcome here, not a failure.
+> const actor = Auth.userOrNull();
+> await Audit.record("checkout.completed", { actorId: actor?.getAuthId() ?? null });
+> ```
+
 `Auth.attempt()` rolls credential lookup, password verification, and login into one call:
 
 ```typescript fragment
@@ -939,8 +969,87 @@ res.assertOk();
 res.assertSee("Welcome back");
 ```
 
+## Passkeys
+
+A passkey replaces the password with a key pair held by the device: the private half never
+leaves the authenticator, so there is nothing on your server worth stealing and nothing for a
+user to reuse across sites. `PasskeyService` implements both WebAuthn ceremonies.
+
+You supply where credentials are stored — the service does not assume a schema:
+
+```typescript fragment
+import { PasskeyService } from "@zerotal/auth";
+
+const passkeys = new PasskeyService({
+  rpName: "Acme",
+  rpId: "acme.test", // the domain, no scheme and no port
+  origin: "https://acme.test", // or an array, for staging alongside production
+  store: {
+    findUserCredentials: (userId) => Credential.where("user_id", userId).all(),
+    findCredential: (credentialId) => Credential.where("credential_id", credentialId).first(),
+    saveCredential: (credential) => Credential.create(credential),
+    updateCounter: (id, counter) => Credential.where("id", id).update({ counter }),
+  },
+});
+```
+
+Each ceremony is two calls — options out, response verified in. The challenge you hand back to
+`verify…` is the one you issued, which is what stops a replay:
+
+| Call                                                 | What it does                                                                                                                                          |
+| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `registrationOptions(user, existing?)`               | Options for enrolment. Pass the user's existing credentials so the browser refuses to register the same authenticator twice.                          |
+| `verifyRegistration(user, response, challenge, ctx)` | Verifies enrolment and stores the credential.                                                                                                         |
+| `authenticationOptions(userId?)`                     | Options for sign-in. Omit `userId` for a usernameless flow, where the authenticator offers the account.                                               |
+| `verifyAuthentication(assertion, challenge, ctx)`    | Returns `{ credential, userId }`, or the string `"passkey.invalid"` — a value rather than a throw, because a failed assertion is an ordinary outcome. |
+
+`PasskeyUser` is the minimum the ceremonies need (`id`, `name`, `email`); `PasskeyCredential` is
+what your store holds.
+
+> **`requireUserVerification` defaults to `true`, and that is what makes a passkey a second
+> factor.** With it off, an assertion succeeds on possession of an unlocked authenticator alone
+> — whoever picks up the phone is the user. Turn it off only for a deliberate "the device is the
+> credential" flow, and then do not count the passkey as a second factor.
+
+`rpId` is the domain alone — no scheme, no port — and it must match the site the browser is on
+or the ceremony fails with an error that does not say why. `origin` takes an array when the same
+deployment answers on more than one.
+
 ## References
 
+### Types
+
+Every middleware and broker takes an options shape, exported so a helper that builds one can be
+typed:
+
+| Type                                | Configures                                                              |
+| ----------------------------------- | ----------------------------------------------------------------------- |
+| `AuthOptions`                       | `AuthMiddleware` — `redirectTo`, `mustVerifyEmail`, `verifyRedirectTo`. |
+| `GuestOptions`                      | `GuestMiddleware` — where a signed-in visitor is sent instead.          |
+| `BasicAuthOptions`                  | HTTP Basic auth.                                                        |
+| `ConfirmPasswordOptions`            | `ConfirmPasswordMiddleware`, including the confirmation window.         |
+| `AuthenticateSessionOptions`        | Session-guard behaviour on a password change elsewhere.                 |
+| `RememberMeOptions`                 | The persistent-login cookie.                                            |
+| `TwoFactorOptions`                  | The second-factor gate.                                                 |
+| `LoginThrottleOptions`              | Sign-in rate limiting.                                                  |
+| `EmailOtpOptions`                   | Passwordless codes by email.                                            |
+| `MagicLinkBrokerOptions`            | Magic-link sign-in.                                                     |
+| `PasskeysOptions`                   | `PasskeyService`, above.                                                |
+| `CompromisedCheckOptions`           | The have-i-been-pwned style check on a chosen password.                 |
+| `JwtGuardOptions`, `JwtSignOptions` | The JWT guard and how tokens are minted.                                |
+| `QrSvgOptions`                      | The 2FA enrolment QR code.                                              |
+
+What the brokers and guards hand back: `PasswordBrokerResult`, `MagicLinkBrokerResult` and
+`MagicLinkUser` for the link flows, `JwtPayload` and `TokenBundle` for JWT, and
+`PasskeyCredential` / `PasskeyUser` for passkeys.
+
+### Events
+
+Emitted on `FrameworkEvents`, so an app can audit or react without wrapping the calls that
+raise them: `EmailVerified`, `PasswordConfirmed`, `PasswordResetLinkSent`, `PasswordResetEvent`
+and `CurrentDeviceLogout`. `LoginSucceeded`, `LoggedOut` and `OtherDeviceLogout` are documented
+above with the calls that emit them.
+
 ### Commands
 
 `@zerotal/auth` ships two commands:

package/docs/broadcasting/references.md

@@ -77,6 +77,23 @@ Notifications can be delivered over a broadcast channel in real time — add `'b
 notification's `channels()` and implement `toBroadcast()`. See
 [Notifications → Broadcasting](/docs/notifications#broadcast).
 
+## Types
+
+Channel and event types, most of which are inferred from your channel declarations:
+
+| Type                                                      | What it is                                                                              |
+| --------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `StaticChannels`, `ParameterizedChannels`                 | Channels with fixed names, and those taking params.                                     |
+| `ChannelParams`, `ChannelParamRecord`                     | What a parameterised channel captures.                                                  |
+| `ChannelAuthFn`                                           | The authorization callback for a private channel.                                       |
+| `PresenceAuthFn`, `PresenceMemberData`                    | The same for presence, plus what a member publishes to the others.                      |
+| `AuthorizeResult`                                         | What an auth callback may return — a refusal, or the member data.                       |
+| `TypedBroadcastEvent`, `EventsOf`, `PayloadOf`            | An event on a channel, the events a channel carries, and one event's payload.           |
+| `BroadcastsModelEventsOptions`, `ModelBroadcastEventName` | Broadcasting a model's own lifecycle, and the event names it produces.                  |
+| `BroadcastRecord`                                         | A queued broadcast as stored.                                                           |
+| `WsConnectionData`                                        | What the server holds per connection.                                                   |
+| `PusherPresenceResolver`                                  | Resolving presence members when running against Pusher rather than the built-in server. |
+
 ## Next steps
 
 - [Broadcasting overview](/docs/broadcasting) — the guide's front page and the rest of the sections.

package/docs/cache.md

@@ -381,6 +381,11 @@ does.
 > `CacheSerializationError` at write time. It is a bug in the caller rather than
 > a cache fault, so let it surface in development instead of swallowing it.
 
+## Types
+
+`IdempotencyOptions` configures `Cache.idempotent()` — the key, the window, and what happens to
+a second identical request that arrives while the first is still running.
+
 ## Next steps
 
 - [Query Builder](/docs/query-builder) — the queries you'll most often wrap in `remember()`.

package/docs/carbon.md

@@ -823,6 +823,11 @@ test("survives a DST spring-forward", () => {
 | `forHumans`                     | `forHumans(options?: { join?: string; short?: boolean }): string` | Human-readable description.                           |
 | `toISO`                         | `toISO(): string`                                                 | ISO 8601 duration string (`toJSON` alias).            |
 
+## Types
+
+`DurationLike` is what the arithmetic methods accept — `add`, `subtract` and their kin — so a
+duration can be built once and passed around rather than spelled out at each call site.
+
 ## Next steps
 
 - [Casts & Mutators](/docs/orm/casts) — `datetime` columns hydrate to Carbon automatically.