@zerotal/arch 1.7.4 → 1.7.5

package/CHANGELOG.md

@@ -4,11 +4,43 @@ All notable changes to this package are documented here. The format is
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-**Maturity: beta.** The API is close to final and breaking changes are rare, called out
-here with migration steps — but a minor release may still contain one.
+**Maturity: `stable`** — matching this package's `maturity` field. The public API
+follows SemVer strictly: anything importable without an `@internal` marker keeps its
+shape for the rest of the 1.x line, and `api-surface.md` is diffed by CI on every
+change. That promise covers the MCP tool contract too — the tool names, their inputs
+and the shape of what they return — which is the part an agent client is configured
+against. `mcp-surface.md` is diffed alongside it.
 
 ## [Unreleased]
 
+## [1.7.5] — 2026-08-22
+
+### Changed
+
+- **`@zerotal/arch` is `stable`.** Reviewed ahead of its 1.9.0 date. The public API
+  follows SemVer strictly from here, and that promise covers the MCP tool contract —
+  tool names, their inputs, and the shape of what they return — because that is what
+  an agent client is configured against and nothing type-level can see it. The
+  protocol revision the server speaks is not covered; it follows the protocol.
+
+- **INTERNAL — the writers behind `arch:install` are no longer public API.** `detectAgents`,
+  `applyMcpConfig`, `serverEntry`, `SERVER_ENTRY_PATH`, `applyBlock`, `fence`,
+  `BLOCK_START`, `BLOCK_END`, `agentsPreamble`, `buildGuidelines`, `claudeShim` and
+  their types. They are still exported and still work; they are no longer promised.
+  Their only caller is `ArchInstallCommand`, and freezing them would have committed
+  the shape of `.mcp.json` writing and marker fencing to the rest of the 1.x line on
+  behalf of a caller who never arrived. Marked before the label attached rather than
+  withdrawn after.
+
+- **INTERNAL — `api-surface.md` now honours `@internal` across every package.** The
+  contract has always been stated as "anything importable without an `@internal`
+  marker keeps its shape", and the generator did not read the tag: symbols already
+  marked internal were recorded as though promised. They are omitted now — 374
+  entries across 13 packages, every one verified marked, either at its declaration
+  or by a module docblock covering a whole subpath as `@zerotal/core/dev` does.
+  Nothing changes at runtime or in the types. What changed is that the file listing
+  the promises lists the promises.
+
 ## [1.7.1] — 2026-08-16
 
 ### Fixed

package/README.md

@@ -1,7 +1,9 @@
 # @zerotal/arch
 
-**Maturity: beta.** The API is close to final and breaking changes are rare, called out
-in release notes with migration steps — but a minor release may still contain one. See
+**Maturity: stable.** The public API follows SemVer strictly: anything importable
+without an `@internal` marker keeps its shape for the rest of the 1.x line. That
+covers the MCP tool contract too — tool names, their inputs, and the shape of what
+they return — since that is what an agent client is configured against. See
 the [support policy](https://zerotal.dev/docs/support-policy#maturity-levels).
 
 The Zerotal agent surface: an MCP server that hands a coding agent the framework's

package/docs/about.md

@@ -131,7 +131,7 @@ my-app/
 `zt.ts` is the entry point for **everything** — `bun zt serve`, `migrate`, `test`,
 and every `make:*` generator run through it. It boots `bootstrap/app.ts`:
 
-```ts
+```ts fragment
 // bootstrap/app.ts
 import { Application } from "zerotal";
 import { Handler } from "../app/exceptions/Handler.ts";
@@ -166,7 +166,7 @@ Read [Request Lifecycle](/docs/lifecycle) for the exact sequence.
 Routes are registered by calling static `Router` methods at module load — map a path
 to a controller + action, or to an inline closure:
 
-```ts
+```ts fragment
 // routes/index.ts
 import { Router, view, type HttpContext } from "zerotal";
 import HomeController from "../app/controllers/HomeController.ts";
@@ -200,7 +200,7 @@ the app builder. Full details in [Routing](/docs/routing).
 Controllers are plain classes; the action receives the request `HttpContext` and
 dependencies resolve from the container:
 
-```ts
+```ts fragment
 // app/controllers/PostController.ts
 import type { HttpContext } from "zerotal";
 import Post from "../models/Post.ts";
@@ -233,7 +233,7 @@ e.g. `ctx: HttpContext<{ post: Post }>`. More in [Controllers](/docs/controllers
 Active Record–style models backed by `Bun.sql`. Columns and relationships are
 decorators; the table name is derived by convention (so `@table` is optional):
 
-```ts
+```ts fragment
 // app/models/Post.ts
 import { Model, table, column, hasMany, belongsTo } from "@zerotal/orm";
 
@@ -255,7 +255,7 @@ export default class Post extends Model {
 
 The fluent query builder and relationship loading:
 
-```ts
+```ts fragment
 // in a controller or service
 const posts = await Post.query()
   .withScopes((s) => s.published())
@@ -321,7 +321,7 @@ export class StorePostRequest extends FormRequest {
 }
 ```
 
-```ts
+```ts fragment
 // in a controller — reads the current HttpContext, returns typed data,
 // throws a 422 (JSON) or a redirect-back on failure.
 const data = await StorePostRequest.validate();
@@ -333,7 +333,7 @@ More rules and patterns in [Validation](/docs/validator).
 
 Session auth, bearer tokens, and policy-based authorization ship together:
 
-```ts
+```ts fragment
 // in a controller / service
 import { Auth, Gate, createToken } from "@zerotal/auth";
 
@@ -415,7 +415,7 @@ decorator and directive set.
 Build a React or Vue SPA with no separate API layer. Controllers return page
 responses; the Inertia client renders the matching component:
 
-```ts
+```ts fragment
 // app/controllers/DashboardController.ts
 import { inertia } from "@zerotal/inertia";
 import { Post } from "../models/Post.ts";
@@ -428,7 +428,7 @@ export class DashboardController {
 }
 ```
 
-```tsx
+```tsx fragment
 // resources/js/pages/Dashboard.tsx (React)
 import { Link } from "@inertiajs/react";
 
@@ -457,7 +457,7 @@ reloads, deferred props, SSR, and precognition. See [Inertia](/docs/inertia).
 Push slow work off the request. Jobs serialize to a plain payload so they survive the
 queue:
 
-```ts
+```ts fragment
 // app/jobs/SendWelcomeEmail.ts
 import { Job, JobRegistry } from "@zerotal/queue";
 import { User } from "../models/User.ts";
@@ -487,7 +487,7 @@ export class SendWelcomeEmail extends Job {
 JobRegistry.register(SendWelcomeEmail);
 ```
 
-```ts
+```ts fragment
 // dispatch from anywhere
 import { Queue, Bus } from "@zerotal/queue";
 
@@ -504,7 +504,7 @@ Run a worker with `bun zt queue:work`. There's also a
 
 ## Cache
 
-```ts
+```ts fragment
 // in a controller or service
 import { Cache } from "@zerotal/cache";
 
@@ -512,7 +512,7 @@ const posts = await Cache.remember("posts.recent", 60, () =>
   Post.query().orderBy("created_at", "desc").limit(10).get(),
 );
 
-await Cache.put("key", value, 300);
+await Cache.set("key", value, 300);
 await Cache.forget("key");
 
 // Tag-based invalidation
@@ -527,7 +527,7 @@ In-memory and Redis drivers, plus idempotency helpers. See [Cache](/docs/cache).
 One `Notification` class fans out across channels — mail, database, broadcast, Slack,
 SMS:
 
-```ts
+```ts fragment
 // app/notifications/InvoicePaid.ts
 import { Notification, MailMessage } from "@zerotal/notifications";
 
@@ -548,7 +548,7 @@ export class InvoicePaid extends Notification {
 }
 ```
 
-```ts
+```ts fragment
 // The User model mixes in Notifiable, which provides .notify()
 await user.notify(new InvoicePaid(invoice));
 ```
@@ -584,7 +584,7 @@ Generate or rotate the key with `bun zt key:generate`. Full system in
 
 First-class HTTP, database, and fake helpers:
 
-```ts
+```ts fragment
 // tests/posts.test.ts
 import { createTestApp, Factory, assertDatabaseHas } from "@zerotal/testing";
 import { NotificationFake } from "@zerotal/notifications";

package/docs/admin/actions.md

@@ -9,7 +9,7 @@ Actions power the row, header, and bulk buttons. The defaults are
 `viewAction()/editAction()/deleteAction()` (rows), `createAction()` (header), and
 `bulkDeleteAction()` (bulk) — override the corresponding methods to customize.
 
-```ts
+```ts fragment
 import { action, editAction, deleteAction, textInput } from "@zerotal/admin";
 
 static recordActions() {
@@ -28,7 +28,7 @@ static recordActions() {
 A row with more than three visible actions collapses the surplus into an overflow
 menu. Actions can also open a **modal form**:
 
-```ts
+```ts fragment
 action("assign")
   .label("Assign reviewer")
   .form([ select("reviewer_id").options(reviewers).required() ])
@@ -43,7 +43,7 @@ action("assign")
 A row with seven buttons is unreadable. `actionGroup` collapses several into one
 labelled dropdown, so the row keeps the two people reach for and files the rest:
 
-```ts
+```ts fragment
 import { actionGroup, replicateAction, deleteAction } from "@zerotal/admin";
 
 static recordActions() {
@@ -67,7 +67,7 @@ nothing. Groups work in the header and the bulk toolbar too.
 `replicateAction()` copies a record and opens the copy for editing. The primary key
 and timestamps are always dropped; name anything else that must stay unique:
 
-```ts
+```ts fragment
 replicateAction()
   .excludeAttributes(["sku", "slug"])
   .beforeReplicaSaved((data) => ({ ...data, name: `${data.name} (copy)`, status: "draft" })),
@@ -75,7 +75,7 @@ replicateAction()
 
 ## Import and export
 
-```ts
+```ts fragment
 import { exportAction, importAction, bulkExportAction } from "@zerotal/admin";
 
 static headerActions() {
@@ -94,7 +94,7 @@ exports the selection instead.
 
 Pass `"xlsx"` for a spreadsheet instead:
 
-```ts
+```ts fragment
 return [createAction(), exportAction(), exportAction("xlsx")];
 ```
 
@@ -107,7 +107,7 @@ header row is frozen with a filter over the used range.
 Keep a column out of the file with `.exportable(false)`. Pay, internal notes and
 anything else that should not travel in a spreadsheet belongs behind that flag:
 
-```ts
+```ts fragment
 text("salary").exportable(false),
 ```
 
@@ -129,7 +129,7 @@ An import runs inline by default, capped at 2,000 rows — a synchronous import
 holds a WebSocket round-trip open, and a bigger file looks like a hang. Hand it
 to a queue instead and the cap lifts:
 
-```ts
+```ts fragment
 static headerActions() {
   return [createAction(), exportAction(), importAction({ queue: true })];
 }
@@ -153,7 +153,7 @@ imported only when an import is actually queued.
 
 Relation managers appear as tables on the View page.
 
-```ts
+```ts fragment
 import { hasMany, belongsToMany } from "@zerotal/admin";
 
 static relations() {

package/docs/admin/auth.md

@@ -9,7 +9,7 @@ Opt in with `Panel.auth({...})` (or `Panel.configure({ auth: {...} })`). The pag
 live behind the `@zerotal/admin/auth` subpath, so the `@zerotal/auth` dependency
 stays optional unless you enable them.
 
-```ts
+```ts fragment
 import { Panel } from "@zerotal/admin";
 
 Panel.auth({
@@ -52,7 +52,7 @@ left to your auth middleware — the rest of the flow ships here.
 
 The panel is public until you set guard middleware. A typical setup:
 
-```ts
+```ts fragment
 Panel.configure({ middleware: [AuthMiddleware, RequireRoleMiddleware.with("admin")] });
 Panel.auth({ enabled: true }); // login lives outside that guard automatically
 ```

package/docs/admin/dashboard.md

@@ -7,7 +7,7 @@ description: Widgets, global search, the command palette, notifications, and the
 
 Register widgets with `Panel.widgets(...)`; they render on the dashboard.
 
-```ts
+```ts fragment
 import { Panel, statsWidget, stat, chartWidget, tableWidget } from "@zerotal/admin";
 
 Panel.widgets(
@@ -41,7 +41,7 @@ The dashboard answers "how is the business doing". A resource's own widgets
 answer "what is going on in _this_ list" — a pending count above the orders
 table, stock value above products:
 
-```ts
+```ts fragment
 export class OrderResource extends Resource {
   static override widgets() {
     return [
@@ -62,7 +62,7 @@ someone watching a queue actually wants.
 A dashboard on a second screen is stale the moment it renders. `.poll()` gives a
 widget an interval:
 
-```ts
+```ts fragment
 statsWidget(async () => [
   stat("Awaiting payment", await Order.query().where("status", "pending").count()),
 ]).poll("30s"),
@@ -85,7 +85,7 @@ page.
 The admin owns the bell + notifications page UI; your app supplies the data through a
 provider (the same split as relations — admin UI, app data):
 
-```ts
+```ts fragment
 import { Panel } from "@zerotal/admin";
 
 Panel.notifications({
@@ -124,7 +124,7 @@ notifications" depends on your auth and your schema. When both are the ordinary
 ones — `@zerotal/auth` for the user, `@zerotal/notifications`' `DatabaseChannel`
 for storage — there is a ready-made one:
 
-```ts
+```ts fragment
 import { databaseNotifications } from "@zerotal/admin";
 
 Panel.notifications(databaseNotifications());

package/docs/admin/extending-ui.md

@@ -23,7 +23,7 @@ everything else alone.
 **Table cells.** The column still owns its label, sorting, search and export;
 only the cell is yours:
 
-```ts
+```ts fragment
 text("health")
   .label("Health")
   .sortable()
@@ -32,7 +32,7 @@ text("health")
 
 **Infolist entries.** The section's grid still places it:
 
-```ts
+```ts fragment
 textEntry("route").render((value) => <RouteMap path={String(value)} />),
 ```
 
@@ -40,7 +40,7 @@ textEntry("route").render((value) => <RouteMap path={String(value)} />),
 saves like any other — you supply only the control. Bind your markup to
 `form.<key>` for the value to round-trip:
 
-```ts
+```ts fragment
 customField("coordinates")
   .label("Location")
   .required()
@@ -55,7 +55,7 @@ what lets a control react to a sibling field.
 A contributed page can only add a page. A hook adds markup at a named position
 in the chrome — a trial banner, a compliance notice, an environment badge:
 
-```ts
+```ts fragment
 Panel.renderHook("page.header.end", () => <TrialBanner />);
 
 // Conditional placement: register once, decide per render.
@@ -92,7 +92,7 @@ A resource does not have to be backed by a model. Return rows from `data()` and
 the panel filters, sorts and paginates them in memory, so search, tabs,
 summaries and the query builder all keep working:
 
-```ts
+```ts fragment
 export class RegionResource extends Resource {
   static override async data() {
     return await fetch("https://api.example.com/regions").then((r) => r.json());
@@ -115,7 +115,7 @@ rows and not millions. Past that, back it with a model or a view.
 
 Four statics change how a list renders:
 
-```ts
+```ts fragment
 export class ProductResource extends Resource {
   static override tableLayout = "grid"; // "table" (default) | "grid" | "kanban" | "calendar"
   static override striped = true;
@@ -131,7 +131,7 @@ title, and the next few render as label/value pairs. No second description.
 
 **Kanban** turns a status column into lanes, for records that read as a pipeline:
 
-```ts
+```ts fragment
 static override tableLayout = "kanban";
 static override kanbanColumn = "status";
 static override kanbanLanes = { pending: "Pending", paid: "Paid", shipped: "Shipped" };
@@ -144,7 +144,7 @@ does, not a second source of truth. A value present in the data but missing from
 
 **Calendar** lays the page out as a month grid keyed on a date column:
 
-```ts
+```ts fragment
 static override tableLayout = "calendar";
 static override calendarColumn = "startsOn";
 ```
@@ -159,7 +159,7 @@ on wide or long tables.
 
 A resource whose records nest under each other renders as a tree:
 
-```ts
+```ts fragment
 export class CategoryResource extends Resource {
   static override treeParentColumn = "parentId";
 }
@@ -176,7 +176,7 @@ than disappearing, so a filtered tree never hides a record.
 
 A resource whose text exists in several languages edits one at a time:
 
-```ts
+```ts fragment
 export class PostResource extends Resource {
   static override translatable = ["title", "excerpt"];
   static override locales = ["en", "fr"];
@@ -193,7 +193,7 @@ turning this on for an existing column does not blank it.
 
 A column can carry its own filter box in the table header:
 
-```ts
+```ts fragment
 text("sku").filterable();
 selectColumn("status", STATUS).filterable();
 ```
@@ -209,7 +209,7 @@ the active-filter chips, and land in a saved view.
 Filters sit above the table by default. Once there are more than a few, collapse
 them:
 
-```ts
+```ts fragment
 static override filterLayout = "panel";   // "inline" (default) | "panel" | "drawer"
 ```
 

package/docs/admin/extending.md

@@ -55,11 +55,20 @@ That last row is the important one. A panel with no authorization wired stays
 closed in production, the same posture the panel guard already takes, which is
 what makes it safe for a package to add pages without the app asking.
 
-```ts
+```ts fragment
 // config/admin.ts
-export default {
-  authorize: (ability) => currentUser()?.permissions.includes(ability) ?? false,
-};
+import { AdminConfig } from "@zerotal/admin";
+import { Auth } from "@zerotal/auth";
+
+// Through the factory, not a bare object: it is what types `ability`, and every
+// other config in the framework is written this way.
+export default AdminConfig({
+  // `userOrNull()`, not `user()` — this runs for guests too, and `user()` throws
+  // rather than returning one. `can()` comes from the permissions mixin on your
+  // own User model, which is why this block is a fragment: the type depends on
+  // your app, not on the framework.
+  authorize: (ability) => Auth.userOrNull()?.can(ability) ?? false,
+});
 ```
 
 Resources are the exception: they authorize through their own
@@ -75,7 +84,7 @@ and without depending on `@zerotal/admin`.
 
 A contributing provider resolves the binding in its `onBooting` and pushes:
 
-```ts
+```ts fragment
 // packages/queue/src/admin.ts
 interface AdminHost {
   enabled(id: string): boolean;
@@ -117,7 +126,7 @@ JSX, no `@zerotal/flow` dependency and no build configuration. The panel owns
 the markup, which also means every console looks like the rest of the admin
 without trying to.
 
-```ts
+```ts fragment
 panel.console({
   slug: "jobs",
   title: "Jobs",
@@ -180,7 +189,7 @@ is read early enough.
 Application code can name the panel directly, so it doesn't need the container
 dance. Group a set of related contributions behind an `AdminPlugin`:
 
-```ts
+```ts fragment
 await Panel.plugin({
   id: "billing",
   install: (panel) => {

package/docs/admin/forms.md

@@ -8,7 +8,7 @@ description: Build create and edit forms, and lay out the read-only view screen.
 `form()` returns fields (and layout components). An empty `form()` disables
 Create/Edit for the resource.
 
-```ts
+```ts fragment
 import {
   textInput, textarea, select, toggle, datePicker, fileUpload, richEditor,
   formSection, formTabs, formTab, wizard, wizardStep,
@@ -80,7 +80,7 @@ patch)` runs server-side and merges a patch into the form (e.g. derive a slug).
 `repeater` edits an array of objects sharing one sub-schema; `builder` edits an array
 of typed blocks. Rows can be added, removed, and reordered.
 
-```ts
+```ts fragment
 import { repeater, builder, builderBlock, textInput, textarea, fileUpload } from "@zerotal/admin";
 
 repeater("contacts").minItems(1).addActionLabel("Add contact").schema([
@@ -101,7 +101,7 @@ Repeaters serialize to `[{ ...fields }]`; builders to `[{ type, data }]`.
 `infolist()` describes the read-only detail page. Omit it to fall back to a section
 derived from `columns()`.
 
-```ts
+```ts fragment
 import { section, textEntry, iconEntry } from "@zerotal/admin";
 
 static infolist() {
@@ -136,7 +136,7 @@ usefully read as text:
 `repeatableEntry` is the read side of `repeater`: whatever the form wrote into a
 JSON column, this reads back in the same shape.
 
-```ts
+```ts fragment
 section("Line items").schema([
   repeatableEntry("lines")
     .placeholder("This order has no line items.")

package/docs/admin/index.md

@@ -47,7 +47,7 @@ List / View / Create / Edit page per resource under the configured `path`.
 
 ## Quick start
 
-```ts
+```ts fragment
 // app/admin.ts
 import { Panel, Resource, text, textInput } from "@zerotal/admin";
 import { User } from "./models/User.ts";
@@ -88,7 +88,7 @@ Edit / View / Delete — and the form above on the Create and Edit pages.
 Configure the panel with `Panel.configure(...)` in `app/admin.ts`, or by exporting
 an `admin` config object the provider merges on boot.
 
-```ts
+```ts fragment
 Panel.configure({
   path: "/admin",
   brand: "Acme",

package/docs/admin/operations.md

@@ -30,7 +30,7 @@ as it does today.
 
 Turn it on per resource:
 
-```ts
+```ts fragment
 export class ProductResource extends Resource {
   static override history = true;
 }
@@ -50,7 +50,7 @@ ago should not also undo the description somebody fixed yesterday.
 The support request nobody can reproduce is usually solved by seeing what the person
 actually sees.
 
-```ts
+```ts fragment
 export class UserResource extends Resource {
   static override impersonatable = true;
 
@@ -79,7 +79,7 @@ Every bit of list state already lives in the URL: search, filters, tab, sort, co
 visibility, grouping, page size. So a saved view is a saved query string, and
 restoring one is a link.
 
-```ts
+```ts fragment
 Panel.savedViews({
   async list(resource) {
     /* … */
@@ -103,7 +103,7 @@ A file upload field puts a file somewhere and stores a path. That works until th
 logo is needed on twenty products, or somebody wants to know what is still pointing at
 a file before deleting it.
 
-```ts
+```ts fragment
 import { databaseMedia, mediaPicker } from "@zerotal/admin";
 
 Panel.media(databaseMedia());
@@ -117,7 +117,7 @@ somewhere else.
 Configured, the panel gains a Media page — a grid with upload, search, folder
 filtering, alt-text editing and deletion — and forms can use the picker:
 
-```ts
+```ts fragment
 mediaPicker("imageUrl").label("Image");
 ```
 
@@ -134,7 +134,7 @@ Authorization already works without a UI: a resource's `can()` answers every que
 the panel asks. What is missing is the other direction — seeing who can do what, and
 changing it, without editing code.
 
-```ts
+```ts fragment
 import { authRoles } from "@zerotal/admin";
 
 Panel.roles(authRoles({ superusers: ["admin"] }));
@@ -162,7 +162,7 @@ week.
 What belongs at the top of a dashboard differs by role, and neither the finance lead
 nor support wants to scroll past the other's widget every morning.
 
-```ts
+```ts fragment
 Panel.dashboardLayout({
   async load() {
     return Auth.user()?.dashboard ?? null;
@@ -193,7 +193,7 @@ stale key mentions it.
 Two people editing the same record is normal; one of them losing their work silently
 is not.
 
-```ts
+```ts fragment
 export class ProductResource extends Resource {
   static override optimisticLock = "version";
 }
@@ -207,7 +207,7 @@ overwriting loses somebody's work, and merging blind is worse.
 
 The expensive mistake is editing production believing it is staging.
 
-```ts
+```ts fragment
 import { environmentIndicator } from "@zerotal/admin";
 
 Panel.renderHook("body.start", environmentIndicator());

package/docs/admin/resources.md

@@ -18,7 +18,7 @@ Scaffold one with the generator, which writes `app/admin/<Name>Resource.ts`:
 bun zt make:admin-resource Post
 ```
 
-```ts
+```ts fragment
 class PostResource extends Resource {
   static model = Post;
 
@@ -71,7 +71,7 @@ class PostResource extends Resource {
 A resource does nothing until the panel knows about it. Register it where the panel
 is configured:
 
-```ts
+```ts fragment
 Panel.register(PostResource);
 ```
 
@@ -93,7 +93,7 @@ any of its links changing.
 Override `can(ability, record?)` to gate the built-in actions. Abilities used by the
 presets: `create`, `update`, `delete`, `restore`, `forceDelete`.
 
-```ts
+```ts fragment
 static can(ability: string, record?: AdminRecord) {
   return Gate.allows(ability, record ?? this.model);
 }