@aotter/mantle 0.2.0-alpha.1 → 0.2.0-alpha.10

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

@@ -0,0 +1,133 @@
+# 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` on every
+target, `| null` unless the View proves the column NOT NULL ([nullability](../reference/view.md#results-and-paging)): 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, and computed outputs that are JSON documents by construction
+(JSON aggregates and builders), 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.
+
+JSON parameters are text on every target (a JavaScript array would otherwise be bound as a PostgreSQL array): an input field read as JSON takes its authored array or object, which the generated query serializes, and a string is bound as it is. 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.

package/docs/handbook/guides/oauth.md

@@ -0,0 +1,219 @@
+# OAuth provider and consent
+
+Auth remains app-owned. Install the existing optional Better Auth peers and
+create your `betterAuth()` instance with `jwt({ disableSettingJwtHeader: true })`
+and `oauthProvider` (or the provider's MCP preset). Append `oauthGrantExtension`
+**first** in its `extensions`. The helper comes from
+`@aotter/mantle/auth/oauth` and binds issued access tokens to the current consent
+ID and Better Auth’s consent reference without changing `referenceId`. Add
+`oauthGrantRevocation()` from the same module to the plugins: it ends a user's
+grants on a password reset or admin action (below), and `mantle generate --auth`
+refuses an OAuth provider without it.
+Configure
+`consentPage: "/oauth/consent"`, loginPage,
+resources, allowed/default client registration scopes, and public/native DCR
+explicitly. For MCP clients use the SDK's `mcp` preset, `allowPublicClientPrelogin:
+true`, and a `90d` registration client-secret expiration. The application selects
+plugins and options; Mantle does not wrap Better Auth or run runtime DDL.
+
+With Mantle's native adapters, `oauthProvider.resources` comes from runtime
+configuration, including environment-derived identifiers. `schema.sql` contains
+auth DDL only. On the first OAuth lookup of a configured resource (authorization,
+token issuance, registration defaults or audience checks), the adapter validates
+and inserts the missing row with insert-if-absent semantics. Concurrent requests
+are safe; subsequent lookups preserve persisted policy edits. No resource deploy
+step is required, and `resourceSeedMode` does not overwrite existing rows.
+To retire a resource, set its persisted `disabled` policy (or configure it disabled
+before its first lookup). Removing configuration does not disable an existing row.
+Do not delete a configured resource row: a later lookup in a new adapter instance
+can recreate it from configuration. On
+`/oauth2/authorize` an invalid configured identifier surfaces as the provider's
+`invalid_target` redirect rather than HTTP 500.
+
+Auth initialization, cookie/bearer resolution and normal MCP/REST requests perform
+no resource SELECT or INSERT. The adapter suppresses the provider's eager and
+bulk lazy seeding. Invalid configured identifiers produce HTTP 500 with
+`AUTH_CONFIGURATION_ERROR` and no write; unconfigured identifiers keep the
+provider's normal rejection. Validation follows upstream's identifier validator
+(or absolute URI without a fragment by default); unsupported signing algorithms
+are dropped before insertion.
+
+```ts
+import { authRoutes } from "@aotter/mantle/auth/routes";
+import { authLoader } from "@aotter/mantle/auth";
+const auth = authLoader(() => import("./auth.js").then(m => m.auth));
+const routes = authRoutes(auth, {
+  methods: [{ kind: "email-otp" }],
+  connectedAppsPage: "/admin/connected-apps", // optional; otherwise plain HTML
+});
+// In fetch: await routes(request) ?? otherRoutes(request).
+```
+
+`GET /api/auth/methods` exposes only the supplied method descriptions and does
+not load auth. `basePath` must match Better Auth if changed. Better Auth owns all
+`/api/auth/*` endpoints and RFC 8414/9728 well-known discovery routes. Mount those
+well-known paths at the origin, before a catch-all or proxy; retain the external
+issuer/resource URL and trusted forwarding rules. The SDK handler receives them
+unchanged. A POST registration whose redirect URIs are all HTTP localhost,
+127.0.0.1 or [::1] becomes `application_type: "native"` when omitted; explicit
+types and mixed/external callbacks stay under the SDK's validation.
+
+With the optional Admin UI selected, use `consentPage:
+"/admin/oauth/consent"`, as in `docs/examples/app-shell/src/auth.ts`, and keep
+`adminShell` mounted in the service entry. That page uses mantle-ui's `AuthCard`,
+cards and sign-in buttons; it loads the verified request from
+`/oauth/consent/data` and posts the original signed payload to `/oauth/consent`.
+The UI displays the client, callback origin, requested scopes and background
+access explanation. Keep Core's script-free `/oauth/consent` HTML as the
+adapter-neutral fallback, not as the reference application's styled page.
+
+`/oauth/consent` and `/oauth/consents` serve escaped, script-free English or zh-TW
+HTML. Their `/data` routes serve the 0.2 UI JSON shapes. Consent approval and
+`POST /oauth/consents/revoke` require a live cookie session and same-origin
+mutation; bearer credentials cannot grant or disconnect apps. Consent completion
+uses only the provider-validated signed query and redirect. All responses are
+private/no-store. Connected-app redirects must be same-origin paths.
+
+`resolveCaller(request, loader, { audience, scopes })` verifies token signature,
+issuer, audience and request-bound DPoP through Better Auth, including a durable
+single-use proof reservation. It then checks the live consent and session and
+loads the current database user.
+All of sub, azp, mantle_consent_id and the consent reference must match, and so
+must sid while the token stands on its session (an `offline_access` token may
+outlive it; see below). The consent must cover the resource and every token
+scope. `scopes` adds a resource-specific scope floor (403 when missing).
+Unbound legacy tokens fail closed. Disconnect deletes the grant first, revokes
+its access/refresh tokens. Tokens issued without an active consent fail closed.
+First-party `skip_consent` tokens instead require a live, enabled client with
+`skipConsent` and allowed scopes, plus the same session or `offline_access`
+rule as consented tokens. Already-issued
+JWTs fail on the next call, and reconsenting cannot revive the old JWT lineage.
+
+Grant lifetime follows Better Auth. Better Auth issues a refresh token only when
+the grant includes `offline_access`; a client registered for `authorization_code`
+may use `refresh_token` too, so registering only `authorization_code` does not
+prevent long-lived grants.
+CIMD is the primary client-discovery path; dynamic client registration (DCR)
+remains available for older MCP clients. Both paths require the client to request
+`offline_access` and the user to consent before a renewable grant is issued.
+The DCR registration defaults below apply only to that compatibility path.
+
+For renewable MCP connections, the examples set both `scopes` and
+`clientRegistrationDefaultScopes` to `["mcp", "offline_access"]`, so a dynamically
+registered client that omits `scope` is registered for `mcp offline_access`. The
+client must request those registered scopes during authorization and the user must
+consent to background access. If the client explicitly requests only `mcp`, OAuth
+must not add a scope the user did not consent to: the resulting grant is bound to
+the browser session and has no refresh token. The client must request
+`offline_access`, or the user must reconnect and authorize it, to gain renewable
+access. Declaring the `refresh_token` grant type alone is insufficient.
+`offline_access` belongs in authorization-server metadata, not in the protected
+resource's required scope floor; resource metadata continues to advertise `mcp`.
+
+For renewable connections, the app-shell's MCP handler also supplies an explicit
+OAuth linking hint:
+
+```ts
+const handleMcp = mcp({
+  db: (env: Env) => env.DB,
+  caller: resolveRequestCaller,
+  authorizationScopes: ["offline_access"],
+});
+```
+
+`authorizationScopes` adds scopes to the standard `WWW-Authenticate` challenge
+when the caller is unauthenticated. With the default `requiredScopes`, that
+challenge requests `mcp offline_access`. It does **not** change the API scope
+floor, add scopes to a valid token, issue tokens or modify an already-signed
+authorization request. An existing valid `mcp`-only token can still call a tool
+that only requires `mcp`. The application must independently permit
+`offline_access` in its provider and the user must explicitly consent.
+Verify the actual requested scopes, refresh-token issuance and post-expiry
+rotation in the intended client. Do not put `offline_access` in the resource's
+required scope floor or silently add it after consent.
+
+For an existing connection granted only `mcp`, deploy the allowed-scope change,
+refresh the client's discovery/registration metadata, then reconnect or reauthorize
+once with `offline_access` and obtain updated consent. Allowing a scope does not
+add it to a stored consent. Do not edit consent rows, prolong access-token TTLs or
+disable grant checks to avoid that step. Verify a refresh token was issued and
+that the client can rotate it and resume MCP after access expiry; a successful
+initial `tools/list` does not prove renewable authorization. The reference service's
+local smoke exercises issuance, refresh after website sign-out, rotation retry
+and revocation using real OAuth endpoints and a disposable D1.
+
+Without `offline_access` the grant is bound to the browser session: its tokens
+stop working when that session expires or the user signs out. A refresh that
+narrows the scope to drop `offline_access` after the session ends returns
+`invalid_grant`, so it never yields an unusable token. An `offline_access` grant
+outlives the browser session. Expiry, deletion and sign-out of the session leave
+it usable until its current refresh token expires or is revoked. Revocation
+includes disconnect, refresh-token revocation and Better Auth's reuse detection.
+Each refresh rotates the token with a fresh `refreshTokenExpiresIn` (30 days by
+default), so an offline grant that keeps refreshing does not expire. Without a live session, its access tokens need an
+unrevoked, unexpired `offline_access` refresh token for the same user and client.
+The consent, client, scope, resource and ban checks still apply. An access token
+issued before sign-out stays valid until it expires (one hour by default).
+`oauthGrantRevocation()` ends every OAuth grant of the user once one of these
+succeeds: revokes their refresh and access tokens, deletes their consents for
+every client (the next authorization asks again, except for a first-party
+`skip_consent` client, which never asks) and their unredeemed
+authorization codes. The events and the sessions each one ends:
+
+| Event | Sessions ended |
+| --- | --- |
+| Password reset (`/reset-password`, `/email-otp/reset-password`, `/phone-number/reset-password`) | all |
+| Admin password change (`/admin/set-user-password`) | all |
+| Password change with `revokeOtherSessions` | all; Better Auth gives the current device a new session |
+| Admin ban (`/admin/ban-user`, or `/admin/update-user` setting `banned: true`) | all (Better Auth) |
+| Admin session revocation (`/admin/revoke-user-sessions`) | all (Better Auth) |
+| Email OTP or magic-link sign-in (`/sign-in/email-otp`, `/magic-link/verify`) that proves the address of an unverified user | all, and its password and linked accounts (Better Auth) |
+
+The last row covers account pre-hijacking: someone who signed up with another
+person's address before it was verified loses their OAuth grants as well as the
+password, linked accounts and sessions that Better Auth strips when the owner
+proves the address. Mantle ends these grants before Better Auth checks the code or
+link, while the user is still unverified, so a failed OTP or magic-link attempt on an
+unverified user also ends that user's OAuth grants.
+
+Otherwise a failed attempt, session expiry, a password change without `revokeOtherSessions`,
+and the user's own sign-out, `/revoke-sessions` and `/revoke-other-sessions`
+("sign out everywhere") end no OAuth grant, as in Better Auth; the user ends a
+connected app's grant by disconnecting it on the connected-apps page
+(`/oauth/consents`). Unbanning does not restore grants. An access token issued
+before the event is rejected on its next use, with one exception: an
+`offline_access` access token of a first-party `skip_consent` client passes again,
+until it expires (one hour by default), once the user grants that client offline
+access anew, because it is checked against any live `offline_access` refresh token
+of the same user and client. Better Auth's `/oauth2/introspect` reports a refreshed
+token inactive once its original session has expired, while Mantle's resource
+check accepts it; Mantle does not use introspection.
+Database failures remain server errors, rather than silently authenticating.
+
+For app-owned API keys/personal tokens, supply `resolveCredential(request)` in
+`resolveCaller` options. It runs before OAuth/cookies; return a verified user
+Caller or null when absent, and throw when presented but invalid. The same scope
+floor applies. Any non-Bearer/DPoP Authorization header (including Basic from a staging
+gateway), unless handled by the app-owned credential hook, is UNAUTHENTICATED
+and never falls back to a cookie. The application owns credential verification;
+Mantle loads live roles, bans and declared stored fields.
+
+For the 0.2 legacy-DCR cleanup policy, call `pruneLegacyOAuthClients(auth)` from
+an application-owned hourly scheduled job. It deletes only ownerless,
+non-CIMD/non-reference clients older than 90 days; it runs no boot-time work.
+
+When configuring session secondary storage, set `verification.storeInDatabase: true` and `session.storeSessionInDatabase: true`: live grants and durable DPoP single-use reservations must use the database, never a non-atomic session KV cache.
+
+Auth routing also guards Better Auth’s raw `/api/auth/admin/*` endpoints (including percent-encoded admin paths): only a fresh primary-database `admin` cookie session may enter, and mutations require same origin. A stale admin snapshot in session KV cannot bypass demotion, ban or session deletion. App-owned auth mounts can reuse `guardAuthAdminRequest` from `@aotter/mantle/auth/admin` with a resolver that reads current authority.
+
+Use primary database sessions without session secondaryStorage as the simple
+safe configuration. If optional session caching is enabled, use the
+**authority-bound** secondary-storage adapter from the identity/auth template
+(`@aotter/mantle/auth/hardening`, #1499): every snapshot must be checked against the primary session and current
+user before the SDK can read it, including raw SDK endpoints and session lists.
+Arbitrary session KV snapshots are outside this secure configuration: middleware
+may trust stale roles or refresh an expired primary session from a snapshot.
+Merely setting storeSessionInDatabase true does not fix those SDK endpoints.
+Mantle's caller and raw-admin guard validate primary authority before refreshing,
+but do not make arbitrary SDK session caching safe. Keep verification
+consumption and DPoP single-use reservations in the database.

package/docs/handbook/guides/postgres-adapters.md

@@ -0,0 +1,56 @@
+# Application-owned PostgreSQL adapters
+
+Bun.SQL and postgres.js satisfy `Postgres` from `@aotter/mantle/contracts` directly. Other drivers need `unsafe(text, values)` returning a row array with `.count`, and `begin(options, fn)` pinning one connection until the callback resolves and COMMIT succeeds. Preserve native SQLSTATE/severity evidence; generated writes classify uncertain commits.
+
+This node-postgres adapter accepts an app-owned `pg.Pool` through its structural shape:
+
+```ts
+import type { Postgres } from '@aotter/mantle/contracts';
+
+type Connection = {
+  query(text: string, values?: any[]): Promise<{ rows: any[]; rowCount: number | null }>;
+};
+// Pass a node-postgres Pool; its connections and lifetime stay app-owned.
+export function nodePostgres(pool: Connection & {
+  connect(): Promise<Connection & { release(discard?: boolean): void }>;
+}): Postgres {
+  const unsafe = (connection: Connection): Postgres['unsafe'] => async (text, values) => {
+    const result = await connection.query(text, values);
+    return Object.assign(result.rows, { count: result.rowCount });
+  };
+  return {
+    unsafe: unsafe(pool),
+    async begin(options, fn) {
+      if (!/^isolation level (serializable|repeatable read|read committed|read uncommitted)$/.test(options))
+        throw new Error('Unsupported transaction options');
+      const client = await pool.connect();
+      let discard = false;
+      try {
+        await client.query(`BEGIN ${options}`);
+        const tx: Postgres = {
+          unsafe: unsafe(client),
+          begin: async () => { throw new Error('Nested transactions are unsupported'); },
+        };
+        let value;
+        try { value = await fn(tx); }
+        catch (error) {
+          try { await client.query('ROLLBACK'); } catch { discard = true; }
+          throw error;
+        }
+        await client.query('COMMIT');
+        return value;
+      } catch (error) { discard = true; throw error; }
+      finally { client.release(discard); }
+    },
+  };
+}
+```
+
+The pool stays application-owned. There is no automatic retry. A COMMIT connection failure remains an error with its original evidence; the SDK can report `OUTCOME_UNKNOWN`. Adapters without interactive transactions must reject in `begin` before invoking the callback. They cannot run multi-statement Procedures or multi-write batches by independent autocommit calls.
+
+Test on disposable storage with the [adapter conformance corpus](../../source/scripts/postgres-adapter.ts), covering bound date-time/date/JSON text, SELECT and RETURNING timestamp microseconds,
+row arrays/counts, safe and unsafe int8 precision (including int64 extrema), aliased
+selected-page integer/version number-or-string outputs, native numeric text and
+booleans, unique/OCC failures, commit/rollback, nested handles and uncertain outcomes. This is an application-owned adapter, not an additional supported driver. Mantle's supported PostgreSQL drivers are Bun.SQL and postgres.js.
+
+The driver layer is open; [dialects remain postgres and sqlite only](../concepts/runtime-and-adapters.md#drivers-and-dialects).

package/docs/handbook/guides/public-pages.md

@@ -0,0 +1,87 @@
+# Public pages: SEO, AEO and languages
+
+This page is the one list of what a public (anonymous, indexable) page emits. Skills, examples and other pages link
+here instead of repeating it.
+
+## Two ways to serve them
+
+- **Generated `web()`**: list and detail pages straight from public Views, with `llms.txt`, sitemap, Markdown
+  alternates and canonical tags. Its contract and limits are in [surface contracts](../reference/surface.md#optional-web-output);
+  the smallest example is `node_modules/@aotter/mantle/docs/examples/generated-web`.
+- **App-owned pages** in `src/routes.ts`, when the page needs its own layout, JSON-LD or languages. The reference
+  implementation is `node_modules/@aotter/mantle/docs/examples/recipes` (`src/pages.ts`, `src/routes.ts`; `smoke.mjs` checks every item below).
+
+## Every public page
+
+- Server-rendered HTML per URL with the content in the body. A client-only SPA shell or metadata set by script is not
+  enough for search or answer engines.
+- `<html lang>`, `<title>`, `<meta name="description">`.
+- `<link rel="canonical">` built from the configured origin (`PUBLIC_ORIGIN`), never from the request `Host`.
+- Open Graph: `og:type`, `og:url` (the canonical), `og:title`, `og:description`, `og:site_name`, `og:locale`
+  (underscore form, `zh_TW`), and `og:image` when the content has an image.
+- Unknown URLs answer 404; drafts and anything a visitor may not read are absent, even when the request carries an
+  admin session (read as an anonymous caller).
+
+## Detail pages
+
+- JSON-LD of the matching schema.org type (`Recipe`, `Article`, `Event`, `Product`, ...), built from the same row as
+  the visible content: `name`, `description`, `url`, `inLanguage`, `datePublished`, `dateModified`, and `image` when
+  there is one (some rich results require it). A type that has no date or language properties (`Product`) gets them on
+  a page node instead: an `@graph` with an `ItemPage` (`inLanguage`, dates, `mainEntity`) pointing to the `Product`
+  (`offers` with `price` and `priceCurrency`). Escape `<` in the serialized JSON so stored text cannot close the
+  script element. Do not add facts the page does not show.
+- A short answer block for answer engines: one question heading and a one-sentence answer from the row's data.
+- A Markdown alternate at `<url>.md`, linked with `<link rel="alternate" type="text/markdown">`.
+
+## More than one language
+
+- One URL per language (`/{locale}/...`), with `hreflang` alternates for each language the page exists in, plus
+  `x-default`. A language that is not published for this item gets no alternate and its URL is a 404.
+- `og:locale:alternate` for the other languages, and a visible language switcher with `hreflang` and `lang` on links.
+- Per-language Markdown alternates; `llms.txt` lists each language's items.
+
+## Site files
+
+- `/sitemap.xml` with every public URL in every language, walking the complete cursor chain of the list View (the
+  recipes example reads one page of 100 per language and marks the paging as `AGENT:` work).
+- `/robots.txt` with `Disallow: /admin/` and the sitemap URL.
+- `/llms.txt` ([llmstxt.org](https://llmstxt.org)): a title, a one-line summary and a link to each item's Markdown
+  alternate.
+
+## A complete site
+
+When the brief names a site, shop, catalogue or blog for visitors, these are part of the work without the user
+listing them:
+
+- Every item on this page, for every public page type the site has.
+- Accessible, responsive pages with the app's own styling; the examples are unstyled on purpose.
+- Content managed in Admin (draft, publish, edit, unpublish) shows on the site without a rebuild. Images go through
+  Admin's media library (`mantle help media-r2`); store committed asset IDs and never use an ID as an image URL.
+- Members' pages, if any, send anonymous visitors to `/sign-in` (`signInRedirect` in the app shell's `src/sign-in.ts`).
+- Who runs the site: an About/contact page and a footer with the business's name, location and contact, and on the
+  home page `Organization` (or `LocalBusiness`) JSON-LD with the same facts and the logo. Answer engines use these to
+  say whether the site is legitimate. Ask for the facts the brief lacks; never invent an address.
+- A favicon, and `og:image` on the home and list pages too.
+- A detail page leads to the action the brief sells (order, register, book), saying when it needs an account.
+- A cache policy: `Last-Modified` (from the row's `updated_at`) or an `ETag` on pages, `.md`, sitemap and `llms.txt`,
+  so crawlers can revalidate; `no-store` everywhere is safe but makes every crawl a full fetch.
+- Structured data and answer blocks state only what the page shows. Never promise ranking or AI citation.
+
+## Check before you report done
+
+Request each page without running JavaScript (plain `fetch` in `smoke.mjs`; `mantle help local-testing`) and assert:
+
+1. HTML content type and the visible content; `<title>`, description, canonical on `PUBLIC_ORIGIN`, Open Graph; on
+   detail pages JSON-LD that parses with the visible name, and the answer block.
+2. Each `.md` alternate returns `text/markdown` with the current text.
+3. Walk the list View's complete cursor chain: its rows equal the `llms.txt` entries and the sitemap's detail URLs
+   (below the generated `web()` caps: 5,000 rows for `llms.txt`, 50,000 for the sitemap). `/robots.txt` names the
+   sitemap.
+4. An unknown URL, a malformed path, a draft and a row the visitor may not read are 404, also with an admin session.
+5. Publish, edit and unpublish an item through Admin's API (or the Procedure Admin uses); after each, its page,
+   `.md`, sitemap and `llms.txt` follow.
+6. Stored text with `<`, `&` and `</script>` renders escaped in HTML and inside JSON-LD.
+
+Report a check you could not run (for example a production origin you do not have) as UNVERIFIED with the reason.
+Then run [independent acceptance](agent-workflow-acceptance.md) with a visitor evaluator in a browser on the
+`pnpm accept` URL.

package/docs/handbook/guides/size-and-startup.md

@@ -0,0 +1,9 @@
+# Size and startup
+
+The SDK ships kernel, CLI, generator and private compiler together. Request modules do not import compiler code. Import only selected generated operations and bindings; direct operations can omit Store/Admin/auth entirely.
+
+Workers use `mantle bundle` to emit split ESM. Keep Better Auth behind `authLoader(() => import(...))`; the startup graph guard rejects eager auth imports, and Admin's browser code (`@aotter/mantle-admin/app`, `/hooks`, and so `generated/admin-client.ts`): import those only from `admin.tsx`, which `mantle bundle` builds into the assets directory. The official MCP SDK and selected Admin operations load on matching requests. Generated module imports perform no SQL or kernel initialization; Store metadata initializes on first use without SQL.
+
+Contributor checks use tracked fixtures to compare runtime/startup graphs against `size-budgets.json` and inspect the published allowlist in `check:package`. Package packed/unpacked bytes are reported separately from request startup and query costs. Do not infer latency from bundle bytes.
+
+Cloudflare startup_time_ms needs an actual upload/deployment; offline dry runs do not measure it. Measure on the selected host and report first use and warm work separately. Applications own deployment authorization and resources.