@aotter/mantle 0.2.0-alpha.6 → 0.2.0-alpha.8

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.

package/docs/handbook/guides/oauth.md

@@ -0,0 +1,161 @@
+# 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.
+
+`/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.
+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,53 @@
+# 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). 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.
+
+## Check before you report done
+
+Request the HTML without running JavaScript and check the items above; publish, edit and unpublish an item and check
+that its page, Markdown, sitemap and `llms.txt` follow. The `mantle` skill's
+`references/local-testing.md` covers running this against `wrangler dev`.

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.

package/docs/handbook/guides/typed-queries.md

@@ -1,26 +1,20 @@
 ---
-description: Read and write through the typed Store from handlers and service code, call named Views, and choose between ctx.store, runtime.store and runtime.store.as(caller).
+description: Choose Store for writes and simple lookups; declare internal Views for richer reads.
 ---
 # Query from TypeScript
 
-Handler and service code reach Mantle-owned rows only through Store. The
-generated `.mantle/generated/mantle.ts` types it over your Schemas and Views:
-`ctx.store` in a `MantleHandlers` handler is its `CallerStore`, while
-`runtime.store` is the untyped `MantleStore` until you cast it to the
-generated `Store`.
+| Work | Data path |
+| --- | --- |
+| Writes | Store `insert` / `update` / `delete`, atomic `batch`, supported `transaction`, or declared Procedures |
+| Id lookup or simple AND filter | Store `findById` / `find` / `first`, inside handlers or an existing application |
+| Joins, aggregates, OR, reusable reads | Internal View: manifest SQL that is reviewable and typed |
 
-| Store | Where | Scope |
-|---|---|---|
-| `ctx.store` | inside a `ref` handler | bound to the invocation's caller. A guard or a before hook gets a read-only one |
-| `runtime.store.as(caller)` | service code that has resolved a caller | that caller |
-| `runtime.store` | trusted host code (imports, maintenance) | none: no caller scope. TTL still applies |
-
-Each one applies TTL visibility, and published-only on public Views. Only
-`runtime.store` skips caller scope, so never hand it a request's input
-unchecked.
+Never write raw SQL to Mantle collections: it bypasses scope, TTL, publishing and system-column rules. The Store applies row rules but does not check a View's or Procedure's `requires`; authorize your handler before using it.
 
 ## Declare an internal View
 
+Save this as `manifests/tickets.yaml`:
+
 ```yaml
 apiVersion: cms.mantle.aotter.net/v2
 kind: Schema
@@ -49,107 +43,50 @@ spec:
     properties:
       ticketState: { type: string, enum: [open, closed] }
   sql: |
-    SELECT id, subject, ticketState FROM tickets
+    SELECT id, subject, ticketState AS "ticketState" FROM tickets
     WHERE ticketState = input.ticketState
-    ORDER BY created_at DESC LIMIT 50
+    ORDER BY id ASC
 ```
 
-`internal` keeps the View off REST, MCP and Admin. It is still in the plan and
-the typed Store. It is not a security bypass: a `requires` on it is checked
-for the caller the Store is bound to.
-
-## Call it
+Generate with `mantle generate cloudflare-d1 generated manifests/tickets.yaml`.
+An internal View has no public REST route or MCP tool. Its generated function still applies declared authorization and compiled row policy.
 
 ```ts
-import type { MantleHandlers } from "../.mantle/generated/mantle.js";
-
-export const handlers: MantleHandlers = {
-  closeStale: async (_input, ctx) => {
-    const { rows, nextCursor } = await ctx.store.view("tickets-by-state", { input: { ticketState: "open" }, limit: 20 });
-    // rows: { id: unknown; subject: string | null; ticketState: "open" | "closed" | null }[]
-    return { open: rows.length, more: nextCursor !== undefined };
-  },
-};
+import { store } from './generated/generated.js';
+import ticketsByState from './generated/views/tickets-by-state.js';
+import type { Caller } from '@aotter/mantle/contracts';
+
+export async function readTickets(db: Parameters<typeof store>[0], caller: Caller) {
+  const tickets = store(db, caller).collection('tickets');
+  const first = await tickets.first({ where: { ticketstate: 'open' } });
+  const rows = await ticketsByState(db, caller, { ticketState: 'open' });
+  return { first, rows };
+}
 ```
 
-The View name, its `input` and its row type are checked by `tsc`. A staff View
-with `uiSchema.list.searchFields` or `filterFields` also takes `search` and
-`filters` (`ctx.store.view(name, { search: "refund", filters: { ticketState: "open" } })`);
-Store refuses a filter the View does not declare. An output that reads a
-Schema field unchanged has that field's type, `created_at` and `updated_at`
-are `string | null`, and an expression, or another native column such as `id`,
-is `unknown`. Page with `limit` (default 50, at most 500) and the opaque
-`cursor` from `nextCursor`.
+The app supplies a verified Caller and its existing native handle. External input needs boundary validation. Store rows, filters and writes use storage names (`ticketstate`, `created_at`); View aliases use the SQL output names.
 
-## `select` and `write`
+## Store reads and writes
 
-For a query that needs no declared View, `select` takes a JSON query over one
-Schema:
+`find` returns `{ rows, cursor }` (null cursor on the last page), with limits 1–500 and opaque keyset cursors. `where` combines fields with AND; `orderBy` selects a generated indexed column with `id` ties. Most order columns must be NOT NULL; publishing `published_at` supports nulls. For a proved pageable internal View, import `paged/views/<encoded-name>.ts` and call `(db, caller, input, { limit?, cursor? })`. Other internal Views retain their bare row-array function.
 
-```ts
-const { rows } = await ctx.store.select({
-  from: "tickets",
-  columns: ["id", "subject"],
-  where: { ticketState: "open", subject: { like: "%refund%" } },
-  orderBy: { updatedAt: "desc" },
-  limit: 20,
-});
-```
+Store keeps `find({ search: 'text' })`, `first({ search: 'text' })` and `count(where?)`. Search matches exact id or declared searchable fields under the same row policy.
 
-- `where`: `{ column: value }` is equality and sibling keys are AND; also
-  `{ column: { eq, ne, gt, gte, lt, lte, like, in, notIn, isNull } }`, and
-  `and`, `or`, `not`. `in` takes a list or `{ select, from, where }`.
-- `orderBy`: one column; `id` breaks ties. Default `{ updatedAt: "desc" }`.
-- `search`: text matched against `searchableFields` (and `id`).
-- Native columns are camelCase here (`createdAt`, `authorId`), while SQL spells
-  them snake_case (`created_at`).
+`count` scans every matching row. For large tables or frequently shown totals, use an internal View with indexed predicates or avoid exact totals; a View's aggregate still scans the matching rows.
 
-`write` applies every operation or none, in order:
+Store search, Admin list search and Views using `mantle.search` share the same dialect search. SQLite/D1 use FTS5 trigram for queries of 3 or more characters, and LIKE for shorter queries. PostgreSQL uses ILIKE over the declared fields, which scans by default. A View does not make PostgreSQL search faster. For large PostgreSQL tables, the application's agent adds trigram indexes in a migration; ILIKE then uses them with no code change:
 
-```ts
-await ctx.store.write([
-  { update: "tickets", set: { ticketState: "closed" }, where: { id }, lock: expectedVersion },
-  { insert: "ticket-events", values: { ticketId: id, kind: "closed" } },
-]);
+```sql
+CREATE EXTENSION IF NOT EXISTS pg_trgm;
+CREATE INDEX articles_title_trgm ON articles USING gin (title gin_trgm_ops);
 ```
 
-- `insert` with `values`, optional client `id` (`ctx.store.id()`) and
-  `onConflict: "ignore" | { columns, update }`. A scoped Schema refuses a
-  client `id`, because a chosen id could collide with another owner's row and
-  reveal it: give such rows a field of your own that is unique with the scope
-  field (`uniqueIndexes: [[owner, clientKey]]`) when other rows of the same
-  write must point at them, or when a retry must find them.
-- `update` with `set` and `where`; `delete` with `where`. A `where` that pins
-  `id` is a row op: it may carry `lock` (the version the caller saw), and
-  writing no row is `CONFLICT`.
-- A result is `{ id, version }` for a row op and `{ affected }` for a set op.
-- `set` and `values` never name the scope field or a native column (except
-  `status` on a `publishing` Schema, below); Store
-  fills them. A `null` leaves empty, or clears, a field the Schema does not
-  require (the generated `values` and `set` types accept it); for a required
-  field it is refused. On a `publishing` Schema, `set: { status }` is how a `ref`
-  handler publishes, unpublishes or archives.
-
-Failures throw `DiagnosticError` with `INPUT_VALIDATION_FAILED` (including a
-failed `check`), `CONFLICT` (`conflict.reason` is `lock`, `expect` or
-`unique`, and `conflict.opIndex` names the operation; for `unique` it is
-present when exactly one operation of the write targets the violated Schema,
-since the engine names the table and not the statement), `RESOURCE_UNAVAILABLE`
-or `OUTCOME_UNKNOWN`. Nothing is written on any failure. After
-`OUTCOME_UNKNOWN`, retry with the same client ids and locks: a replayed insert
-conflicts on its id, a replayed update on its lock.
-
-## From service code
-
-The service's `fetch` receives the runtime. Resolve the caller first, as the
-generated `withCaller` does, and bind Store to it:
+Index each searched field as needed and inspect EXPLAIN for the workload. Case folding follows the engine.
 
-```ts
-const caller = await resolveCaller(request);
-if (!("caller" in caller)) return new Response("unauthorized", { status: 401 });
-const { rows } = await runtime.store.as(caller.caller).view("tickets-by-state", { input: { ticketState: "open" } });
-```
+Writes are lazy and execute once when awaited. Insert/update return native rows; delete returns void. `update(id, set, { lock })` and `delete(id, { lock })` require the version the caller reviewed. A stale lock, excluded row or unique clash is `CONFLICT`. `batch` atomically executes unused Writes from one Store in input order; a step cannot use a prior result.
+
+Interactive `transaction(async tx => …)` exists on bun:sqlite and PostgreSQL, with collections, Views and Procedures bound to the transaction. D1 supports batches only. PostgreSQL defaults to serializable, with an explicit isolation override; SQLite uses BEGIN IMMEDIATE. Use `tx` inside the callback, not the outer Store or handle. Nested transactions and `tx.batch` are refused; there is no automatic retry.
+
+Ref handlers receive `{ caller, db, store }` bound to the same Caller and transaction. Implement the generated `Handlers` interface and pass it to `store(db, caller, { handlers })`. Direct Procedure modules expose SQL Procedures; ref Procedures are reached through the bound Store or selected surfaces.
 
-To run a Procedure from service code, with its auth, guard and validation, call
-`runtime.invokeProcedure({ procedure, input, caller, cause: { kind: "internal", id } })`.
-Inside a handler, `ctx.invoke(name, input)` does the same and keeps the caller.
+See [native execution](native-execution.md) for values and write outcomes and [migrations](../concepts/runtime-and-adapters.md#schema-installation-and-migrations) before changing a Schema.