@aotter/mantle 0.2.0-alpha.5 → 0.2.0-alpha.7

package/docs/handbook/guides/email.md

@@ -0,0 +1,86 @@
+# Transactional email
+
+Import the optional email port from `@aotter/mantle/email`. Mantle supplies
+`EmailSender`, `EmailSendArgs`, English `signInCodeEmail`, `signInLinkEmail`
+and `adminInvitationEmail` templates, and `ConsoleEmailSender` for local
+development. Applications select and configure their sender and Better Auth
+plugins.
+
+`send({ to, subject, text, html?, locale, category? })` returns `Promise<void>`.
+The templates return `{ subject, text }`, with the same English text as 0.2;
+they do not translate or consume `locale`. Pass the recipient's locale through
+to the sender, which can select localized templates. Existing categories are
+`auth.email-otp.<type>`, `auth.magic-link.sign-in` and `auth.admin-invitation`.
+
+## Application wiring
+
+```ts
+import { emailOTP } from "better-auth/plugins";
+import { hashEmailOtp } from "@aotter/mantle/auth/hardening";
+import { signInCodeEmail, adminInvitationEmail, type EmailSender } from "@aotter/mantle/email";
+
+const locale = (request?: Request) =>
+  request?.headers.get("accept-language")?.split(",")[0]?.split(";")[0]?.trim() || "en";
+
+// Include this plugin in the app's Better Auth options.
+export const emailPlugin = (sender: EmailSender, secret: string) => emailOTP({
+  storeOTP: { hash: otp => hashEmailOtp(secret, otp) },
+  sendVerificationOTP: ({ email, otp, type }, ctx) => sender.send({
+    to: email, ...signInCodeEmail(otp), locale: locale(ctx?.request),
+    category: `auth.email-otp.${type}`,
+  }),
+});
+
+// Use the configured, trusted application origin, never an incoming Host or
+// Origin header. The application grants the OSS "admin" role before sending.
+export const inviteEmail = (sender: EmailSender, origin: string, to: string, language: string) =>
+  sender.send({
+    to, ...adminInvitationEmail("admin", new URL("/admin/sign-in", origin).href),
+    locale: language, category: "auth.admin-invitation",
+  });
+```
+
+For magic links, pass Better Auth's generated URL to `signInLinkEmail(url)`;
+configure Better Auth's `baseURL` and `trustedOrigins` to prevent untrusted
+callback destinations. Templates preserve their input as plain text and never
+interpret it as HTML. If a sender supplies `html`, it owns escaping untrusted
+text and attributes and validating link destinations. Pass structured fields
+to the provider; do not interpolate them into raw MIME headers.
+
+Use `new ConsoleEmailSender()` only in explicitly selected local development.
+It logs recipients, codes and links and sends nothing; never select it in
+production or log live messages in a production sender. Provider failures
+reject the promise; the application owns error handling and retry policy.
+
+**Never let the response wait for the send.** Better Auth calls
+`sendVerificationOTP` for `email-verification` and `forget-password` only when
+the user exists, so a response that waits for the provider reveals whether an
+account exists. Configure Better Auth's `advanced.backgroundTasks.handler` (on
+Workers, `ctx.waitUntil`) so the send runs after the response, as 0.2 did; the
+app-owned auth template wires it.
+
+## Cloudflare Email Service binding
+
+Use a verified sender and a Cloudflare Email Service `send_email` binding.
+The binding composes the message natively; no mail SDK or MIME builder is needed.
+
+```jsonc
+{ "send_email": [{ "name": "EMAIL" }] }
+```
+
+```ts
+import type { SendEmail } from "@cloudflare/workers-types";
+import type { EmailSender } from "@aotter/mantle/email";
+
+interface Env { EMAIL: SendEmail; EMAIL_FROM: string }
+export const emailSender = (env: Env): EmailSender => ({
+  async send({ to, subject, text, html }) {
+    await env.EMAIL.send({ from: env.EMAIL_FROM, to, subject, text, html });
+  },
+});
+```
+
+The English example ignores `locale` and `category`; a localized provider may
+use both. The binding's verified sender and recipient restrictions still apply.
+This example does not provision a sender, enable an auth method or send mail
+without application wiring.

package/docs/handbook/guides/mcp-apps.md

@@ -0,0 +1,44 @@
+# MCP Apps
+
+Generated `mcp()` accepts app-owned UI resources on either endpoint. Each
+endpoint accepts one contributor or an array; Admin uses the same public hook:
+
+```ts
+import type { McpApps } from '@aotter/mantle/mcp';
+import { adminMcpApps } from '@aotter/mantle-admin/mcp';
+import { mcp } from './generated/mcp.js';
+
+const app: McpApps = { resources: [{
+  uri: 'ui://my-app/records', name: 'my-app-records',
+  html: () => loadAppHtml(), renders: ['records'],
+}] };
+const handler = mcp({ db, caller, apps: {
+  public: app, admin: [adminMcpApps(adminOptions), adminApp],
+} });
+```
+
+Use your own `ui://<app>/…` prefix. `ui://mantle-admin/…` is reserved for Admin.
+HTML is reusable static content; caller-specific data comes from tool results.
+Build the front end with the official `@modelcontextprotocol/ext-apps` client.
+`renders` links tools to `_meta.ui.resourceUri`; `appOnly` adds
+`visibility: ["app"]`. Both name tools actually exposed on that endpoint.
+Resources may supply CSP, permissions and `prefersBorder`.
+
+For static tool tables, construction checks contributors. Request-bound tool tables check on the first matching request and recheck changed tool names. Duplicate
+resource URIs or names, conflicting tool ownership, and absent or foreign-endpoint
+tools throw `ContractError` with code `MCP_APP_CONFLICT`. HTML loaders never run during import or handler construction. Treat descriptors as
+immutable after construction. HTML loads only on `resources/read`; failures
+return a redacted internal error.
+
+Generated media-enabled handlers keep the same cache while resolving their tool
+table against each request's environment. Database handles, storage and Caller
+are never retained in that cache. The low-level SDK also accepts an async
+`(request, env) => tools` resolver; its names must match the endpoint's App
+catalogue. If its tool names change, those links are checked again, and a call
+always uses the current request's tool table.
+
+Clients advertise `io.modelcontextprotocol/ui` and MIME type
+`text/html;profile=mcp-app` in initialization capabilities or, for stateless
+requests, in `params._meta["io.modelcontextprotocol/clientCapabilities"]`.
+An explicit capability declaration without UI support receives no UI resources, UI tool metadata or App-only tools. A stateless request with no capability declaration is treated as unknown and retains App support. Other tools retain their existing validation,
+authorization, caller, origin and database behavior.

package/docs/handbook/guides/native-admin.md

@@ -0,0 +1,298 @@
+# Native Admin
+
+Select Admin explicitly; use the exact installed SDK/Admin versions.
+
+## Packages and generation
+
+There are three packages, pinned to matching versions:
+
+| Package | Owns |
+| --- | --- |
+| `@aotter/mantle` | One native Core SDK: compiler, generator, query kernel and optional auth/surface primitives. |
+| `@aotter/mantle-admin` | Optional Admin server, SPA, extensions, design preview and Admin MCP App. |
+| `@aotter/mantle-ui` | Shared UI kit and generic interaction controller. |
+
+The SDK does not import Admin or its assets. Selecting Admin emits application
+code that imports its small public server helpers. The SPA retains all 22
+languages, rich editors and the developer workspace; language, editor and
+workspace chunks load on demand. It is not part of the SDK query bundle.
+
+Select Admin explicitly:
+
+```sh
+pnpm exec mantle generate cloudflare-d1 generated manifests/*.yaml --admin
+pnpm exec tsc --noEmit
+```
+
+Targets are `bun-sqlite`, `bun-postgres`, `cloudflare-d1` and
+`cloudflare-postgres`. Programmatic generation accepts `admin: true` with the
+same target/source options. Optional `--auth`, `--site` and `--admin-extensions`
+modules follow their [generation contracts](../cloudflare/service-entry.md).
+Generate, typecheck, implement every printed `Handlers` key, then typecheck
+again. Commit generated TypeScript, SQL and Wrangler edits. Never edit the
+output by hand; regenerate after merging authored inputs. Use the matching
+CLI's `--check` with the same selected options in CI.
+
+Apply initial `schema.sql` and selected auth/site DDL only during explicit
+setup of a new database. Existing data needs reviewed migrations. Imports and
+metadata factories do no storage work. Requests run no DDL or storage checks;
+the only request-time write outside app operations is the configured OAuth
+resource row (see [OAuth](oauth.md)).
+
+## Mount the API and console
+
+```ts
+import { admin } from '@aotter/mantle-admin/server';
+import { entries } from '@aotter/mantle-admin/server/entries';
+import { adminBindings } from './generated/admin-bindings.js';
+import { handlers } from './handlers.js';
+import { resolveRequestCaller } from './identity.js'; // application-owned
+
+const bindings = adminBindings({ handlers });
+const api = admin(bindings.metadata, bindings.views, bindings.operations, {
+  db: (env: Env) => env.DB,
+  caller: resolveRequestCaller,
+  routes: entries(bindings.schemas, bindings.adapter),
+  developerViews: bindings.developerViews,
+});
+// In app-owned fetch: await api(request, env); undefined means fall through.
+```
+
+Ref operations run with the handlers given to `adminBindings({ handlers })`; `admin()` needs no second copy. Without ref Procedures, omit `handlers` and use `adminBindings()`. The app's
+resolver verifies the caller; Admin accepts an admin cookie session classified from
+Better Auth’s admin plugin `adminRoles` (default `["admin"]`), and cookie writes
+retain the shared same-origin check. Comma-separated roles are supported.
+Do not manufacture an admin/system Caller from request input. Views and operations
+also retain their own generated `requires` checks. Share one request-local
+resolver with auth, consent, MCP and REST; preserve its response cookie headers.
+
+The API handles `/admin/api/*`. The app separately serves
+`@aotter/mantle-admin/admin/index.html` and its directory at `/admin`, including
+client routes such as `/admin/sign-in`; missing assets stay 404. Do not serve
+that directory bare: `adminShell(request, assets)` from
+`@aotter/mantle-admin/server` returns the shell for every `/admin` page with
+`frame-ancestors 'none'`, `X-Frame-Options: DENY`, `no-store` and `nosniff`, and
+refuses traversal, encoded separators and NUL (`assets` fetches one built file
+by path; a 404 means missing; it returns `undefined` for other requests). Read the
+installed Admin README for asset bindings, CSP/import-map hashes and preview
+framing. `@aotter/mantle-ui` continues to supply the shared kit. See
+[service composition](../cloudflare/service-entry.md) for the complete Fetch/Bun wiring.
+
+## HTTP routes
+
+All paths below start with `/admin/api` and require an admin session; mutations
+also require the shared same-origin check. Mount `entries(...)` for collection
+routes. Send JSON with `Content-Type: application/json`.
+
+| Method and path | Request / response |
+| --- | --- |
+| `POST /entries` | Body `{ collection, data }`; creates an entry. |
+| `GET /entries/{id}?collection=<schema>` | Reads an entry and its current `entry.version`. |
+| `PATCH /entries/{id}?collection=<schema>` | Body `{ data, expectedVersion }`; sends the observed version, not the next one. Publishing entries must be drafts. |
+| `POST /entries/{id}/publish?collection=<schema>` | Body `{ expectedVersion }`; validates required data before publishing. |
+| `POST /entries/{id}/unpublish?collection=<schema>` | Body `{ expectedVersion }`; returns the entry to draft. |
+| `POST /operations/{name}` | Body is the Procedure's input; runs an Admin operation (a Procedure with `requires: ctx.admin` or a `target`). |
+| `GET /views/{name}` | Generated admin View query parameters plus `limit`/`cursor`; returns `{ rows, nextCursor? }`. |
+| `GET /me` | Returns `{ userId, role, admin, login, image }` for the signed-in caller. |
+
+Entry create/read/patch/transitions return
+`{ collection, entry, parentEntryId, parentEntryTitle, related }`; the entry has
+`{ id, collection, locale, status, version, data, created_at, updated_at }`.
+Transitions accept `{}` to use the current version; tests should send the
+observed `expectedVersion` to catch stale writes. Generic writes reject native
+columns inside `data`. See [publishing](../concepts/lifecycle-and-locales.md).
+
+## Generated reads and writes
+
+`adminBindings()` returns static metadata, schemas, views, operations and the
+selected native adapter. Metadata-only endpoints add no storage read of their
+own; authentication, optional user enrichment or site loading may still query.
+The shared get/page/statistics functions select quoted tables and columns only
+from generated whitelists. Search/filter/cursor/range values are binds, never
+SQL identifiers. Core compiles scope, TTL, publishing and parent predicates;
+there is no request-time manifest/schema/SQL AST interpreter.
+
+Scoped rows remain private even from other admin. Translation reads merge at
+most one visible parent with the matching join key; scoped parents correlate
+scope in every mode, including trusted reads. Child declarations win over parent
+fields, and a parent's public same-named field cannot replace a child's private
+scope. Unrelated scoped Schemas cannot hide an ordinary public field. Scope and
+storage-only fields are absent from entry data and generated CSV export fields.
+Geo remains experimental: existing native outputs are readable, not generically
+editable. Metadata derives child relationships from `allCollections`.
+
+Entry queries validate indexed sort fields, directions, filters and limits
+1–500. `filter_field` and JSON `filter_values` are paired; each batch has at most
+50 scalar values. Search reuses native SQLite/D1 FTS and PostgreSQL behavior.
+Pages keep native NULL ordering, id ties, microsecond timestamp keys and an
+opaque cursor bound to caller, input, filters and ordering. Malformed/foreign
+cursors and unknown selectors fail before acquiring the route's DB handle;
+the app's authentication may already have used its own database. Admin manifest
+Views retain their complete proved key tuple, not a two-key approximation.
+
+Generated full/partial input checks validate creates, edits, operations and
+filters. Plain titled string `oneOf` choices use the same enum checks; general
+or constrained alternatives remain refused. Draft creates can be incomplete;
+publish checks required data. Publishing edits apply only to drafts. Read-only
+collections refuse generic edits while their declared Procedures can still run.
+
+Writes use compiler-printed native Procedure frames, bind recipes and only the
+supplied field fragments. They do not update omitted columns or run a schema
+interpreter. PATCH retains its visible-row read and exact OCC check; the mutation
+returns its row. Missing/excluded rows are 404; stale locks or failed state guards
+are 409. Safe versions are numbers; exact native int64 strings can be bound
+without rounding, while unsafe numbers are rejected. The console keeps versions
+outside its supported safe range read-only rather than casting them to numbers.
+Full cross-target int64 output parity remains incomplete; bare driver values
+are unchanged.
+
+Publishing/custom Admin operations load existing generated Procedure modules
+when invoked. Ref handlers retain the original typed `{ caller, db, store }`
+context and authorization. Ordinary SDK/REST/MCP emission and the synchronous
+public Store API are unchanged. Selected JSON boundaries preserve declared JSON/boolean conversions and safe
+cross-target integer normalization from SQL text; exact unsafe values are not rounded. Bare
+Views, Store and SQL Procedures keep their driver-native contract. Native
+unique/OCC errors and uncertain transaction outcomes keep their contracts. A 503 outcome may mean a write committed: do not
+retry automatically or turn it into a success by reading afterward. Core
+`statusOf` maps core codes only. App media/site/partial errors use `mediaError`
+from `@aotter/mantle/media`; other custom ContractErrors must carry an explicit
+status, otherwise the boundary returns a redacted 500. Do not leak native
+error messages, tokens or credentials to clients.
+
+## Statistics and extensions
+
+`GET /admin/api/collections/{name}/statistics?range=7d` supports primary or
+standalone collections; folded children/translations are not primary routes.
+Ranges are `1h`, `24h`, `7d` (default) and `20d`. It returns
+`{ total, buckets, from, to, bucketMs }` in one native aggregate query. `total`
+counts currently caller-visible retained rows, including rows outside the
+requested window; expired rows are excluded. Buckets use `[from, to)` and the
+same generated scope/TTL/parent policy. The shared native function accepts at
+most 20 days and 480 buckets, with safe microsecond arithmetic. Temporal enum
+subtypes return original metadata keys; equivalent offset spellings count once
+under the first key, and separate microseconds remain distinct.
+
+Site/media/identity, extensions, WebMCP, design preview and MCP Apps are selected
+through the public Admin modules, not added to the SDK kernel. Extension
+contribution declarations go to `--admin-extensions`; executable handlers and
+sources stay in app-owned server configuration. Raw extension handlers receive
+the original Request without pre-reading, cloning or rebuilding it. Custom
+`bodyLimit` checks Content-Length before DB access; the app must bound reads of
+unknown-length raw streams. Built-in JSON routes use the shared bounded reader
+(default 1,000,000 bytes) after caller/origin checks and before DB acquisition.
+The API advertises capabilities for actually mounted routes, including statistics.
+
+## Acceptance
+
+Use a disposable database for native tests, then exercise actual OTP sign-in,
+the Admin console and member frontend. Check invalid input, another tenant's
+rows, expired rows, publishing transitions, related/translated entries, paging,
+statistics, CSV, operations/ref effects, stale OCC and persisted state after a
+restart. Recheck extensions, previews, all supported UI languages and the
+complete developer workspace. A generated file, typecheck or HTTP 200 alone
+does not verify these flows.
+
+Native adapter evidence covers all four targets; local D1 uses real workerd.
+Initial Admin module imports perform no DB work. Startup graphs, uploaded total,
+SDK package bytes and query/write/cold timing are separate checks. Extra selected
+Admin indexes add write/storage maintenance; an indexed SELECT plan does not
+prove unchanged write latency. Report remaining gates honestly; this guide does not promise measured performance.
+
+## Extension declarations
+
+Pass full declarations to `--admin-extensions`. Generation emits
+`extensionMetadata` in `admin-descriptors.ts` and compiled settings checks plus
+`extensionBindings` in `admin-extensions.ts`. Bind the same runtime definitions
+(including handlers) with `extensionBindings(adminExtensions)`, and merge the
+returned `extensions` and `routes` into `admin()` options. Declaration drift is
+refused before any handler runs. The older descriptor `extensionBindings` export
+contains manifest UI references only; it is not the runtime binding function.
+
+Native Admin does not serve `source` modules or modify shell import maps. Serve
+an extension's `module` at a same-origin absolute path and install its `integrity`
+in the host shell import map. Selecting `source` fails generation with that
+instruction. This differs from historical 0.2's automatic source-module route.
+
+Entry lists and editor reads/writes return translation badges and related
+sections in one authorized HTTP response. `/bootstrap?collection=...` can include
+the first requested list page. CSV exports use `/entries/export` and
+`/views/{name}/export`; native browser downloads stream paged server output.
+A failure after headers aborts the stream, so a download can fail after partial
+bytes have arrived. Existing databases need an app-owned migration for the
+Admin-selected `created_at` statistics indexes emitted in initial `schema.sql`.
+
+## Collection list template today
+
+The compiler derives display/filter metadata from Schema `uiSchema`, searchable fields from `searchableFields`, and sortable fields from indexes plus required/non-null fields and selected system columns. It emits per-collection quoted fragments, row policies and bind recipes; Admin uses one shared `nativeEntryPage` implementation, not Store `find`, `search` or `count` for these lists.
+
+Requests select only generated fields and append only supplied predicates. Absent filters are omitted, rather than expressed as `(? IS NULL OR …)`. Sorts and scalar values are checked before the route acquires its DB handle. In 0.2.0 there is no generated Cartesian set of filter variants or variant cap: runtime SQL shapes depend on selected filters, bounded IN lists, search, cursor and order. Only sortable fields are checked for indexes; there is no per-filter-combination index proof. Inspect EXPLAIN for the actual workload.
+
+Store keeps `find({ search })`, `first({ search })` and `count(where?)`. See [Store search and count costs](typed-queries.md#store-reads-and-writes): Admin shares the dialect search, and a View does not make PostgreSQL ILIKE faster.
+
+## Collection navigation and operation placement
+
+A Schema with a required `x-mantle-ref` folds under its parent collection: it
+opens from the parent entry's workbench and stays out of the sidebar, while
+`/admin/c/<schema>` still lists it; translation children remain on language
+tabs. Set `Schema.spec.uiSchema.nav.standalone: true` to put a required-ref child
+at the top level instead. With multiple eligible references, set
+`nav.parentField` to the chosen reference field.
+
+### Sidebar
+
+By default the sidebar lists publishing Schemas under Content, operational Schemas under Records (`operations`),
+admin Views under Reports and Admin's own pages under More, each in name order. A project arranges it for how its
+staff work, in the same manifest change that adds a Schema or View. Placement is presentation only: permissions,
+REST, MCP and storage are unchanged, entries a caller cannot see stay hidden, and an empty group is not shown.
+
+- `Schema.spec.uiSchema.nav` and admin `View.spec.uiSchema.nav` take `group` (a group id), `order` (an integer;
+  ascending, entries without one follow in name order) and `hidden: true` (out of the sidebar, still at its URL).
+- Built-in groups need no declaration: `content`, `operations`, `reports`, `more`. Project groups are declared once
+  as `navGroups` in the `--admin-extensions` module, with a title (text or `{ locale: text }`) and an `order` among
+  the built-in groups' content 10, operations 20 and reports 30 (default 50); More always stays last.
+- Extension pages use the same ids: `pages[].nav: { group, order }` (`more` and `settings` keep their places).
+
+```ts
+// src/admin.ts, passed as --admin-extensions src/admin.ts (the app shell already does)
+import type { AdminExtension, AdminNavGroup } from "@aotter/mantle-admin/server/extensions";
+export const navGroups: AdminNavGroup[] = [{ id: "approvals", title: { en: "Approvals", "zh-TW": "簽核" }, order: 5 }];
+export const adminExtensions: AdminExtension[] = [];
+```
+
+```yaml
+# a Schema or an admin View
+uiSchema: { nav: { group: approvals, order: 1 } }
+```
+
+`mantle generate` refuses an undeclared group, a duplicate or built-in `navGroups` id and a non-integer `order`.
+The purchasing example puts its approval queue and requests in an Approvals group.
+
+Operational collections have no generic create or draft: officers add records through a Procedure placed with `collectionAction` (the list header shows its button and input form), so every write is a declared, validated program. For a user-field scoped Schema, SQL INSERT is system-only, so that Procedure is a ref handler that inserts through `ctx.store` ([procedure.md](../reference/procedure.md)).
+
+Admin operations are Procedures exposed by an admin MCP Trigger. Declare
+`Procedure.spec.uiSchema.collectionAction: <schema-name>` to show the operation
+in that collection's list header. Row operations are chosen by the Procedure's
+explicit `target: { schema, id, version? }`: `id` names the input bound to the
+row id, and optional `version` names the input bound to its reviewed OCC version.
+Names such as `approve` never determine placement. An operation without a row
+target or collection action appears on the Operations page, whose sidebar link
+appears whenever such operations exist.
+
+Generated row metadata includes simple AND-ed equality/IN literal conditions
+from the target-row UPDATE/DELETE WHERE. The menu hides known mismatches; missing
+preview values and unsupported predicates leave actions available. These are
+presentation hints: the Procedure still enforces its WHERE and authorization.
+Conflicts show a localized refresh message with the technical diagnostic in
+Details. Successful actions show a short summary and changes, with raw output
+in a collapsed Details disclosure. CSV exports retain UTC wire timestamps.
+
+Developer Model and Logic pages share an object sidebar on wide containers
+and an object-list drawer on narrow containers.
+Schema Live data previews use collection routes even for folded children.
+Pass `bindings.developerViews` as the Admin `developerViews` option for
+public and admin View previews; ordinary Admin View routes and exports use
+only `bindings.views` (admin Views). View previews use the read-only `/admin/api/developer/views/<view>` route,
+with the signed-in admin caller and the same authorization, scope, TTL and
+publishing policy as REST. Public Views retain public visibility; internal or
+disallowed Views show an unavailable explanation. Previews never use a system
+caller or bypass a View's `requires`.

package/docs/handbook/guides/native-execution.md

@@ -0,0 +1,132 @@
+# Generated native execution
+
+Views and SQL Procedures execute compiled SQL through the selected native driver. The compiler stays build-time only. The app owns native handles, pools, verified Caller, boundary validation and resources. Import direct operation entries to omit unused operations.
+
+Supported targets are Bun SQLite/PostgreSQL and Cloudflare D1/PostgreSQL. The [driver boundary is open; dialects are closed](../concepts/runtime-and-adapters.md#drivers-and-dialects). Generation emits initial SQL; [the runtime runs no DDL or schema checks](../concepts/runtime-and-adapters.md#schema-installation-and-migrations).
+
+## Query inputs, values and outcomes
+
+The default typed query accepts application-validated parameters and a verified
+Caller, binds literal SQL using the official driver, and returns that target's
+native result types. Generated TypeScript is a compile-time contract, not a
+validator for untrusted data. The application must validate external input before
+calling it. Generate-time schema/SQL diagnostics remain mandatory.
+
+The bare query must not recursively scan JSON, construct validators, revalidate
+known database rows, normalize errors across databases, or require universal row
+decoding. Direct in-process values are owned by their application caller; input
+bounds, JSON defaults and computed result types are handled explicitly by the
+application boundary rather than assumed from TypeScript.
+
+Driver-native PostgreSQL types and SQLite/D1 types need not match, except for
+declared date-time and date outputs (below), which the SQL formats. That does not
+justify overriding every PG type parser or adding a generic decoder to the bare
+query. Authored output names should be emitted into SQL where valid, avoiding
+an extra per-row projection merely to repair names already known at generation.
+
+Selected REST/MCP/Admin boundaries use static generated column lineage. Declared
+integers (including aliased system versions) are `number | string | null` on every
+target: safe integers become numbers; unsafe integers remain exact decimal text.
+Selected SQL projections cast integers and hidden integer cursor keys to text
+before the driver reads them, preserving stored int64 values on SQLite/D1 and
+PostgreSQL. Values already rounded when written
+(e.g. by a JavaScript number) cannot be recovered.
+`views/<name>.ts` exports both driver-native `Row` and `WireRow` (declared wire fields agree across targets);
+`paged/views/<name>.ts` keeps native `Row` rows; REST/MCP use separate
+`paged/wire/views/<name>.ts` SQL and convert at their boundary. SQLite/D1 declared JSON
+and boolean columns become JSON values and booleans, preserving aliases and nulls;
+PostgreSQL already returns those native values.
+Declared real/float outputs remain numbers. Computed outputs without proved lineage,
+SQL Procedures and app-owned ref results retain native values and types.
+Bare Views/Procedures, the Store, web pages and internal paged Views stay
+driver-native; bare queries and the Store receive no integer SQL projection,
+transport conversion or runtime schema interpreter.
+
+Declared authorization, ownership/TTL SQL policy, explicit OCC and atomic writes
+remain required. Generate them as the native application would implement them.
+Transaction rollback and uncertain COMMIT handling must still preserve data-loss
+protection and client disposal responsibility; native errors are rethrown (one exception, below), and
+redaction before they reach HTTP users belongs to the application boundary through `wire` / `surfaceFailure`. Removing generic error
+normalization does not authorize dropping transaction outcome evidence.
+
+**Single-statement writes:** a Procedure with one statement is atomic on its own
+and runs in autocommit, with no BEGIN/COMMIT on PG or native transaction on Bun
+SQLite. A row-classified statement touches at most one row (one-row INSERT or
+unique `id =`), so a failed count check after autocommit has changed nothing.
+On PG it runs at the server's default isolation, not SERIALIZABLE: a concurrent
+OCC loser re-evaluates its `version =` predicate, matches zero rows and returns
+`CONFLICT` instead of SQLSTATE 40001. A server ErrorResponse (SQLSTATE and
+severity) is a known rollback and is rethrown natively, except a unique violation (23505, SQLite's `UNIQUE constraint failed`), which, in a generated Procedure or a Store write, is `ContractError("CONFLICT")` with the native error as `cause` on every target, and except connection,
+resource and shutdown classes (08, 28, 53, 57, 58, XX), which, like any failure
+without a server response (lost socket), are `OUTCOME_UNKNOWN`. SQLSTATE is
+`errno` on Bun.SQL and `code` on postgres.js. Multi-statement Procedures run in
+`begin("isolation level serializable", ...)`: a failure before the callback
+returns was rolled back by `begin`; only a failed COMMIT is classified as above.
+
+**Date-time wire form:** a View output that is a declared `date-time` column
+(including `created_at`/`updated_at`) returns the handbook's wire form, an ISO
+string in UTC with six fractional digits; a declared `date` returns `YYYY-MM-DD`.
+The generator wraps those SELECT items before the dialect's own printer prints them
+(`to_char` on PostgreSQL, `strftime`/`date` with floor arithmetic on SQLite), so the
+database formats them and no row decoder runs. Bun.SQL's `Date` would drop
+microseconds. A write's `RETURNING` of such a column gets the same form. Inputs bound to a declared date-time take the same ISO text (or a
+valid `Date`), and a declared date takes `YYYY-MM-DD` text, on every target: a
+timestamp needs `Z` or an offset and hours 00-23, a day that does not exist is refused with `SQL_TYPE` before the write, and SQLite receives
+microseconds and days while PostgreSQL receives the canonical text. Computed values
+(`now()`, `date_trunc`, `CAST`) carry no declared type and stay driver-native; on
+PostgreSQL through Bun.SQL that is a `Date`, which drops microseconds. Other
+declared scalars are driver-native.
+
+Driver-ready JSON parameters are text on every target (a JavaScript array would otherwise be bound as a PostgreSQL array), so the application serializes them. Bare PG SQL declares each JSON parameter as text
+(`CAST(CAST($n AS text) AS jsonb)`), so Bun.SQL sends the text verbatim instead of
+JSON-encoding it again; generation refuses a JSON parameter used any other way. SQLite bool/date/timestamp/numeric parameters use their declared
+storage representations. Bound optional fields become explicit required values,
+with null representing absence; D1 cannot bind undefined. Native output keys are
+SQL names rather than a post-query camel-case projection. PG uses the driver's
+default type parsers (including Date and int8 strings); custom application parser
+configuration changes application-owned behavior. Procedures expose raw
+`{ results }`, not a claim of validated authored output.
+
+The application resolves a verified Caller once at its entry, using its selected
+auth module or identity. Bare queries accept that application-supplied Caller and
+do not verify credentials. SQL binds the caller subject directly; a system
+caller is application-owned and never wire input.
+
+
+## PostgreSQL settings
+
+The app owns role/database configuration, statement timeouts, pool lifetime and retries. Configure persistent session settings there rather than issuing request-time SETs; Hyperdrive does not retain them. UTC is useful for application-owned timestamp expressions; generated declared timestamp outputs are formatted explicitly. Requests neither set nor validate role settings.
+
+## Ref Procedures
+
+Generation emits a `Handlers` interface. Pass implementations at `store(db, caller, { handlers })` and to selected surfaces. `requires` is checked before the ref handler receives `(ctx, input)`; `ctx` contains `{ caller, db, store }` bound to the actual Caller and transaction. Missing implementations fail typechecking; a missing runtime key is `HANDLER_NOT_REGISTERED`. Handler failures propagate unchanged. Handlers own business rules, side effects and explicit transaction boundaries.
+
+Lifecycle and schedule Triggers and dynamic authorization guards are rejected by generation. Use app-owned handlers and scheduling. HTTP/MCP Triggers expose declared Procedures.
+
+## TTL maintenance
+
+A TTL Schema generates `<schema>.sweepExpired(db, caller, { limit?, cursor?, delete? })`
+in `procedures/<schema>.sweepExpired.ts`. Only an application-created system caller
+with a non-empty reason may invoke it; HTTP/OAuth callers cannot become system
+callers. The app owns scheduling. Schedule/lifecycle Triggers remain refused.
+
+The sweep returns `{ scanned, removed, nextCursor? }`, defaults to 500 candidates,
+and accepts limits 1..500. `delete: false` scans without deleting. Cursors belong
+to that Schema's sweep. NULL and future TTL values survive; a timestamp exactly
+at the shared dialect cutoff expires. Maintenance deliberately ignores scope and
+publishing visibility, deleting expired rows across tenants. Candidate selection
+and deletion run atomically through the native driver with its existing uncertain
+transaction outcome handling. Native triggers may suppress deletes, so scanned
+and removed counts can differ; the cursor advances over selected candidates.
+
+
+Keep the sweep import in the scheduled entry; apps selecting unrelated operations
+exclude maintenance code. Set `triggers.crons` in Wrangler yourself. The SDK's
+`toCloudflareCron` helper (the `cron` subpath) converts five-field POSIX schedules
+(weekday 0=Sunday) to Cloudflare weekdays (1=Sunday); it refuses ambiguous schedules
+that restrict both day-of-month and weekday. This is conversion only, no dispatcher.
+Bound scheduled work to your host's execution budget; keep the returned cursor
+when continuing a larger sweep in a later invocation.
+
+
+See [publishing and translations](../concepts/lifecycle-and-locales.md), [Store](typed-queries.md), [surfaces](../reference/surface.md) and [Admin](native-admin.md) for selected capabilities.