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

package/docs/handbook/reference/schema.md

@@ -1,201 +1,110 @@
----
-description: Schema field reference for Mantle 0.2.0 — the JSON Schema, field types and storage, indexes, checks, search, scope, TTL, lifecycle, localization and uiSchema.
----
 # Schema
 
+A Schema declares one table and its typed Store collection. Required keys are title and an object JSON Schema. Optional keys include lifecycle, scope, TTL, indexes, uniqueIndexes, checks, searchableFields, localized, translates and uiSchema. Unknown keys fail validation.
+
 ```yaml
 apiVersion: cms.mantle.aotter.net/v2
 kind: Schema
 metadata: { name: orders }
 spec:
-  title: Orders                      # required; a string or a locale map
-  description: …                     # optional
-  lifecycle: operational             # publishing (default) | operational
-  scope: { owner: auth.uid() }       # optional
-  ttl: { field: expiresAt, expireAfterSeconds: 0 }   # optional
-  checks: ["qty > 0"]                # optional
+  title: Orders
+  lifecycle: operational
+  scope: "owner = auth.uid()"
   uniqueIndexes: [[owner, orderNumber]]
-  indexes: [[owner], [orderStatus, createdAt]]
   searchableFields: [orderNumber]
-  localized: false
-  translates: { parent: …, on: … }   # optional, localized child only
-  uiSchema: { … }                    # optional, Admin only
-  schema:                            # required: JSON Schema of the row
+  checks: ["qty > 0"]
+  schema:
     type: object
-    required: [owner, orderNumber, qty, orderStatus]
-    properties: { … }
+    additionalProperties: false
+    required: [owner, orderNumber, qty]
+    properties:
+      owner: { type: string }
+      orderNumber: { type: string }
+      qty: { type: integer, minimum: 1 }
 ```
 
-Unknown keys are refused. A Schema compiles to one table named after
-`metadata.name`.
-
-## `schema`
-
-A JSON Schema object for the row's fields. It is checked on every write, Admin
-and `ctx.store` included. `required` fields must be present on an operational
-insert and when a draft is published; a draft may be saved incomplete.
-
-| Property | Stored as (`sqlite`) | Stored as (`postgres`) | Notes |
-|---|---|---|---|
-| `type: string` | `TEXT` | `text` | |
-| `type: string, format: date-time` | integer microseconds | `timestamptz` | an ISO string on the wire; compare with `now()` and `interval` in SQL |
-| `type: string, format: date` | integer days | `date` | `"2026-10-01"` on the wire |
-| `type: integer` | `INTEGER` | `int8` | |
-| `type: number` | `REAL` | `float8` | |
-| `type: boolean` | integer 0/1 | `bool` | `true`/`false` on the wire |
-| `type: object`, `type: array` | JSON | `jsonb` | read with `->>` or `json_each` in SQL |
-| `format: geo` | two `REAL` columns and an R*Tree | two `float8` columns | `{ lat, lng }`; query with `mantle.near` and `mantle.distance` |
-
-### Reserved entry columns
-
-A field may not be named like a native column (`id`, `status`, `version`,
-`createdAt`, `updatedAt`, `authorId`), nor `expectedVersion`, nor `locale` on
-a non-localized Schema. Two fields may not differ only in case
-(`FIELD_NAME_CASE_COLLISION`): SQL resolves names case-insensitively.
-
-Property extensions:
-
-| Keyword | Meaning |
-|---|---|
-| `x-mantle-ref: <schema>` or `{ schema, field }` | the value is another Schema's `id` (or the named single-field unique field). Admin relates and binds rows by it, either way; a required one folds the child under its parent. `MANTLE_REF_INVALID` when the target is not `id` or a unique field |
-| `oneOf: [{ const, title }, …]` | a string field whose options each have a label (a string or a locale map): stored as text, checked like an `enum`, usable as `uiSchema.list.filterField`, and shown by its `title` in Admin |
-| `x-mcp-hint` | a widget hint: `markdown`, `html`, `richtext`, `code`, `media`, `media-image`, `media-video`, `media-file`, `money-minor`, `timestamp-ms`, `idempotency-key` |
-| `title`, `description` | a field's label and help, a string or a locale map |
-| `readOnly: true` (at the root) | Admin's generic entry routes refuse writes; declared Procedures still write |
-
-`x-mantle-bind` is refused in 0.2.0: use `scope`, or set the value with
-`auth.uid()` or `now()` in the Procedure's SQL.
-
-### JSON Schema limits
-
-These hold for every JSON Schema Mantle checks: a Schema's `schema`, and View
-and Procedure inputs and outputs.
-
-| Limit | Diagnostic |
-|---|---|
-| at most 100 levels deep and 10,000 schema nodes; an `enum` of at most 1,000 values | `JSON_SCHEMA_LIMIT_EXCEEDED` |
-| a `pattern` of at most 1,000 characters that compiles as a JavaScript regex | `INVALID_PATTERN` |
-| no repeated group whose body repeats or alternates (`(a+)+`, `(a\|b)*`, `^[a-z0-9]+(-[a-z0-9]+)*$`) and no backreference | `INVALID_PATTERN` |
-| a `pattern` costs at most branches × maxLength^e ≤ 10,000,000, and declares `maxLength` when e > 0 | `INVALID_PATTERN` |
-
-A JavaScript regex backtracks, and the pattern runs on every caller's string,
-so its work is bounded by the string's `maxLength`. The exponent e counts the
-variable quantifiers (`*`, `+`, `?`, `{m,}`, `{m,n}`, outside `[...]`), plus
-1 when the pattern does not start with `^`, because an unanchored pattern is
-retried at every offset; branches multiplies the alternatives of every
-alternation. `^[a-z0-9-]+$` (e = 1) allows any maxLength up to 10,000,000,
-the email `^[^@]+@[^@]+$` (e = 2) up to 3162, `^(?:[a-f0-9]{40}|[a-f0-9]{64})$`
-(e = 0, 2 branches) needs none. A string longer than its `maxLength` is
-refused before its pattern runs. The message names the largest maxLength the
-pattern allows; lower it, anchor the pattern with `^`, or use fewer variable
-quantifiers or alternatives.
-
-These checks catch the patterns that backtrack catastrophically by accident;
-they are a guard, not a proof that every accepted pattern is fast. Fixed
-counts (`{1000}`), lookarounds and arrays of patterned strings still cost
-work the estimate leaves out, so keep patterns short and anchored, and a host
-that runs plans it does not trust bounds CPU per request.
-
-A slug is `{ type: string, maxLength: 120, pattern: "^[a-z0-9-]+$" }`. It
-accepts leading, trailing and doubled hyphens; to refuse them on a Schema
-field, add `checks: ["slug NOT LIKE '-%' AND slug NOT LIKE '%-' AND slug NOT LIKE '%--%'"]`.
-
-## `lifecycle`
-
-`publishing` (the default) gives rows the `draft` → `published` → `archived`
-workflow; only drafts are editable, and a public View sees published rows only.
-`operational` rows are live on insert and edit in place. See
-[Lifecycle and locales](../concepts/lifecycle-and-locales.md).
-
-## Indexes
-
-- `indexes`: ordered composite non-unique indexes over top-level scalar fields
-  and native columns, spelled in camelCase here (`createdAt`, not
-  `created_at`). `status` exists only on a `publishing` Schema.
-- `uniqueIndexes`: composite unique indexes. On a scoped Schema every entry
-  starts with the scope field. A write that breaks one is `CONFLICT` with
-  `conflict.reason: unique`; an `ON CONFLICT (<columns>)` target names one.
-
-Boot creates a missing index; a declared one whose columns changed is blocked
-until you drop the old one ([Deploy and operate](../cloudflare/deploy-and-operate.md)).
-
-## `checks`
-
-Boolean SQL expressions over the row's own columns, enforced on every insert
-and update by what storage convergence creates: triggers on SQLite, a `CHECK`
-constraint added `NOT VALID` on PostgreSQL. Rows that predate a check are left
-alone:
+## Fields and storage
 
-```yaml
-checks: ["stock >= 0", "partySize IS NULL OR partySize BETWEEN 1 AND 20"]
-```
+A string `pattern` needs a `maxLength`: generation bounds each regex's backtracking and, when it refuses one (`INVALID_PATTERN`), names the largest `maxLength` it accepts. Anchor patterns with `^` and avoid nested quantifiers such as `(-[a-z0-9]+)*`.
 
-Storage prints a check into the table as written, so it names only the
-Schema's own columns, unqualified, and calls only the functions SQLite and
-PostgreSQL spell alike, each on one argument: `lower`, `upper` and `length`
-on text, `abs` on a number. No subqueries, casts, `auth.*` or `now()`; a rule
-about the caller belongs in a Procedure's guard. Other type mismatches
-(`name > 5` on a text field) are the database's to refuse when the app boots. A violation fails the whole write with
-`INPUT_VALIDATION_FAILED` and the message `CHECK <schema>: <expression>`.
+| Field | sqlite | postgres |
+| --- | --- | --- |
+| string | TEXT | text |
+| date-time | integer microseconds | timestamptz |
+| date | integer days | date |
+| integer | INTEGER | int8 |
+| number | REAL | float8 |
+| boolean | 0/1 | bool |
+| object/array | JSON text | jsonb |
+| geo | lat/lng columns, R*Tree | lat/lng columns |
 
-## `searchableFields`
+System columns include id, version, created_at, updated_at and author_id; publishing adds status/published_at. Initial DDL declares a field NOT NULL when an `operational` Schema lists it in `required` and it does not allow null; `default` never does, and no column gets a DDL `DEFAULT` ([server-maintained fields](#admin-uischema)). Do not declare reserved fields. Manifest native column names in indexes use camelCase (`createdAt`); generated Store/SQL use storage names (`created_at`). Scope is omitted from returned rows.
 
-Top-level string fields for full-text search. On SQLite, an FTS5 trigram
-index kept in step by triggers: a query of three characters or more matches
-substrings (Chinese included); a shorter one scans. On PostgreSQL, a
-case-insensitive substring scan (`ILIKE`) over the fields. Used by `mantle.search(t, q)` in SQL,
-`search` in `ctx.store.select`, and Admin's search box. `id` is always
-searched by Store's `search`. Date and date-time fields are refused.
+Declared date/date-time outputs are SQL-formatted strings (`YYYY-MM-DD`, UTC ISO with six fractional digits). Computed timestamps remain native. Inputs and other output scalars follow [the native contract](../guides/native-execution.md). Date conversion through JS Date loses microseconds.
 
-## `scope`
+Generated types constrain Store fields and writes; Store does not interpret a JSON Schema on each call. Validate untrusted inputs at the boundary. Selected Admin emits full/partial field checks; drafts may be incomplete, while publishing checks required data. Native constraints remain database-enforced.
 
-```yaml
-scope: { owner: auth.uid() }
-indexes: [[owner]]
-```
+## Row rules
+
+Schemas default to operational. Publishing opts into draft/published/archived and generated admin/system transitions. Store cannot assign system columns or scope; generated policy fills them. See [lifecycle and locales](../concepts/lifecycle-and-locales.md).
+
+Owner and field columns prefix every unique index in that order. User reads/writes see their own rows; anonymous reads see none. System callers bypass scope. TTL uses `{ field, expireAfterSeconds }` over a date-time field; expired rows become invisible but remain stored until a system sweep. TTL is not allowed on translations.
+
+`localized` and `translates: { parent, on }` declare a translation child. Parent visibility and publication are retained, with matching scope where needed. Locale values stay plain strings.
+
+## Indexes, checks and search
+
+Indexes are ordered composite scalar/native columns. A paged View's `ORDER BY` must match an index on the base Schema after any fixed equality prefix ([index prefixes](#index-prefixes-for-paged-views)), ending with `id` as the tiebreak: `ORDER BY created_at DESC, id DESC` needs `indexes: [[createdAt, id]]` (generation reports `Missing index for ORDER BY ...` otherwise). Required operational fields are NOT NULL; publishing drafts may be incomplete. Store sortable types use indexed/non-null columns, with explicit nullable published_at support.
+
+### Index prefixes for paged Views
+
+Only equality fixes an index prefix: `col = input.x`, `col = 'literal'` and an `= auth.uid()` scope or restrict. A user-field term (`region IN auth.user('region')`, as a `scope` or `restrict`) binds a set of values, so it never fixes a prefix, even when the caller holds one value or `{ all: true }`: the statement is prepared for a set, and an `ORDER BY` after that column would read and sort all of the caller's rows on every page. With `scope: "region IN auth.user('region')"`, `indexes: [[region, orderNo, id]]` and `ORDER BY orderNo`, generation refuses the View, names the bounded order and links here. The bounded ways:
+
+- `ORDER BY region, orderNo`, served by the same index: rows come back grouped by region. `region DESC, orderNo DESC` reads it backwards; on PostgreSQL confirm with `EXPLAIN` that no Sort remains. Every column added to the `ORDER BY` must be non-null and nameable in SQL; a `publishing` Schema field other than a user-field scope column can be null, and the `scope` owner column cannot be named, so the refusal then says this order is unavailable.
+- A View input bound with equality, `WHERE region = input.region ORDER BY orderNo`: the input fixes the prefix, and the scope still applies. Every set-bound column before the ordered ones needs its own equality.
+- For `{ all: true }` callers, an index on the equality-fixed columns, then the ordered columns, then `id`: `[orderNo, id]` here, `[tier, orderNo, id]` with `WHERE tier = input.tier`. It is not bounded for scoped callers, who scan the index and filter, and it does not help a View with any `restrict`, which [`{ all: true }` never lifts](view.md#restrict).
+
+Declaring both indexes does not make one View bounded for every caller. System (trusted) reads drop scope terms, so a scope-first index such as `[owner, at]` is not a proved range scan for them.
+
+`uniqueIndexes` accept declared fields only, never native entry columns such as `authorId`. For per-member uniqueness, declare a required string `member` field, write `member: caller.subject` in a handler, and use `uniqueIndexes: [[member, orderNumber]]`; do not take `member` from client input.
+
+Publishing fields may be NULL in drafts even when required, so they cannot be View paging keys. Store accepts `published_at` ordering, but View paging rejects it. Use `ORDER BY id`, or keep the business date in an operational Schema as an indexed, required non-null field. See [View paging](view.md#results-and-paging).
+
+`checks` are restricted SQL expressions over the table's columns, emitted in initial DDL. Native databases enforce them; bare database errors are not automatically mapped to input-validation failures. Searchable fields must be plain string fields. SQLite/D1 emit FTS5 trigram tables and maintenance triggers; PostgreSQL uses ILIKE. Short SQLite terms use LIKE. Store search additionally matches exact id and combines with row policy.
+
+The runtime never creates, alters or checks tables. Initial DDL is for an empty database. Changed fields, checks, indexes and search DDL require [agent-owned native migrations](../concepts/runtime-and-adapters.md#schema-installation-and-migrations), including explicit data migration for destructive/type changes. Mantle drops nothing.
+
+## Admin uiSchema
+
+A property marked `readOnly: true` in the JSON Schema is server-maintained (a counter, a total): Admin's generic create stores its `default` whatever the input says, Admin edits ignore it, and only Procedures (or server code through the Store) change it afterwards. JSON Schema defaults are applied by Admin's generic create only, not by the Store or the database: initial DDL emits no `DEFAULT` for a field, so server code through the Store and a SQL Procedure that inserts the row set the field themselves. A root `readOnly: true` makes the whole Schema read-only in Admin: a generic Admin write is refused with 403 `AUTH_DENIED` (not a 409 version conflict).
+
+`default` does not make a column NOT NULL; `required` does (in an `operational` Schema). For a server-maintained value that is never NULL, list it in both, `required: [name, total]` with `total: {type: integer, readOnly: true, default: 0}`: initial DDL declares `total` NOT NULL, Store and View row types read it as `number` rather than `number | null`, Admin's create still fills the default when the client omits it, and the Store's insert type requires server code to pass it. Without `required` the column stays nullable, and an INSERT that omits it stores NULL. Adding `required` to an existing table is a [migration](../concepts/runtime-and-adapters.md#schema-installation-and-migrations): backfill NULLs, then add NOT NULL.
 
-Exactly one field, bound to `auth.uid()`. It must be a required string, lead
-an index, and lead every `uniqueIndexes` entry. Every read and write of a user
-caller is limited to its own rows, anonymous callers reach none, Store fills
-the field on insert, and no write may set it. `runtime.store` and the system
-caller are not scoped. See [Authorization](../concepts/authorization.md).
+`fields.<name>.widget` selects a built-in control (`textarea`); `list.primaryField`, `list.columns` and enum `filterField` select list presentation (operational Schemas only; a publishing Schema's list shows its title field and status); `nav.parentField` chooses the parent a child folds under (required when two or more required `id` references exist) and `nav.standalone` lists the child in the sidebar; `nav.group/order/hidden` place it in the sidebar ([sidebar](../guides/native-admin.md#sidebar)). `list.columns` must not repeat `list.primaryField` or itself (`SCHEMA_UI_INVALID`). Generation validates these against declared fields/indexes. Components that render a field, cell or record aside are not manifest references: they live in `defineAdmin` ([customising Admin](../guides/native-admin.md#customising-admin)), and a manifest that still names one (`widget: <extension>/<contribution>`, `widget` `options`, `list.cells`, `panels`) is refused. JSON Schema root `schema.readOnly: true` disables generic Admin writes, not declared Procedures; `uiSchema.readOnly` is rejected with `SCHEMA_UI_INVALID`. `x-mantle-ref` relates a field to another Schema id or single-field unique field. It is not a foreign key: the database does not check that the referenced row exists, and deleting that row leaves the reference dangling. Check existence in the write (a JOIN or `EXISTS` in the Procedure) and guard deletes with `NOT EXISTS` ([SQL patterns](../guides/sql-patterns.md)).
 
-## `ttl`
+See [Admin](../guides/admin-ui.md) and [diagnostics](diagnostics.md).
 
-`{ field, expireAfterSeconds }`: `field` is a top-level `date-time` field. A
-row is invisible to every read and write from `field + expireAfterSeconds`;
-`runtime.store.sweepExpired({ collection })` (or a schedule handler's
-`ctx.store.sweepExpired`) removes expired rows; until then an expired row
-still holds its unique keys. Not allowed on a translation Schema.
+### Field scope
 
-## `localized` and `translates`
+`scope` is one predicate of terms joined by `AND`: at most one `<column> = auth.uid()` and any number of `<column> IN auth.user('<field>')`, for example `scope: "tenant = auth.uid() AND region IN auth.user('region')"`. Scoped columns are required, non-null, and lead an index. The scope protects every SQL relation, Store, REST/MCP and native Admin access.
 
-`localized: true` declares a `locale` string field. `translates: { parent, on }`
-makes the Schema the localized child of a non-localized parent, joined on a
-field both declare; it needs at least one content field besides `on` and
-`locale`. Store does not check `locale` against the site's locales in 0.2.0.
+A caller whose value for a field is `{ all: true }` drops that field's term only; the other terms still apply. Generated SQL holds one statement per target and selects the form for each caller at run time; values are always bound parameters. Neither roles nor the admin layer widen a field scope or a translation parent's visibility. A Schema whose `x-mantle-ref` points to a field-scoped Schema must carry the same scope terms.
 
-## `uiSchema`
+For inserts, one allowed partition autofills a missing value; multiple values require an explicit allowed partition, and missing/empty values fail with `AUTH_DENIED`. Callers holding `{ all: true }` and system callers always provide an explicit partition. A Procedure `INSERT … VALUES` follows the same rule for user callers, checked before any SQL runs: leave the partition column out to autofill a caller's single value, or take it from an input declared with the column's own type (`VALUES (input.region, …)`) or a matching literal, which must be inside the caller's set; any other expression there is refused. A Procedure that callers holding several values or `{ all: true }` use, such as an Admin create action, takes the partition as an optional input. `INSERT … SELECT` into a field-scoped Schema, and an insert into a Schema the target `restrict`s, run only for system callers, which this check does not cover: they name the partition themselves; use the scoped Store for user writes there. The partition is never writable through SET, including upsert and native Admin patch. An excluded id behaves like a missing row: reads return not found; Store update/delete and row-classified Procedure UPDATE/DELETE affecting zero rows return HTTP 409 (`CONFLICT`). Native Admin's visible-row pre-read returns 404 for either id. SQLite binds a JSON array; PostgreSQL binds a quoted, escaped array. Public Views over field scope warn that anonymous callers are refused.
 
-Admin presentation only; it never changes validation or MCP.
+#### References to a scoped Schema
 
-| Key | Values |
-|---|---|
-| `fields.<name>.widget` | `textarea` |
-| `list.primaryField` | a scalar data field shown first (operational Schemas) |
-| `list.columns` | data fields and native columns, in order (operational Schemas) |
-| `list.filterField` | a string enum field that leads an index: tabs per value (operational Schemas) |
-| `nav.standalone` | `true`: also list a folded child in navigation |
-| `nav.parentField` | which `x-mantle-ref` field filters it, when several could |
+A non-null `x-mantle-ref` value that points to a scoped Schema (field or owner scope) must name a row of that Schema the caller can read, matched on `id` or on the object form's `field`, and that row must have the same value as the child for every scope field the two share (`ADR-0034`: a reference between scoped Schemas stays inside one owner or partition). A Store insert or update, a Procedure `INSERT … VALUES`, `UPDATE … SET` or `DO UPDATE SET`, and native Admin's generic create and patch check it in the same statement; a missing, unreadable or other-partition parent behaves like a missing row: a single-row statement returns HTTP 409 (`CONFLICT`), and an `ON CONFLICT` insert or a set update writes nothing for that row. A caller holding several values or `{ all: true }` can still not point a child in one partition at a parent in another. `INSERT … SELECT` that writes such a reference runs only for system callers. A caller's `UPDATE … SET` or `DO UPDATE SET` of such a reference takes no subquery, which could read the parent's columns as its own. Trusted writes (system callers, `runtime.store`) are not checked, like the other row rules. NULL is always allowed; deleting a parent does not touch its children.
 
-Other keys are refused (`SCHEMA_UI_INVALID`).
+## Reserved entry columns
 
-## Diagnostics
+Every Schema row has native columns that a Schema must not declare as data properties: `id`, `status`, `version`,
+`createdAt`, `updatedAt` and `authorId` (SQL `id`, `status`, `version`, `created_at`, `updated_at`, `author_id`).
+Use a domain name for your own fields (`requestStatus`, `submittedAt`). Views read native columns and `spec.indexes`
+can index them without declaring them; `uniqueIndexes` cannot include them. `status` and `published_at` belong to
+the publishing lifecycle; `version` backs `expectedVersion`; `author_id` is the verified creator used by
+`restrict: { <schema>: "author_id = auth.uid()" }`.
 
-`SCHEMA_INDEX_INVALID`, `SCHEMA_INDEX_FIELD_UNKNOWN`,
-`UNIQUE_INDEX_FIELD_UNKNOWN`, `SCHEMA_SEARCH_INVALID`,
-`SCHEMA_SEARCH_FIELD_UNKNOWN`, `SCHEMA_TTL_INVALID`, `SCHEMA_UI_INVALID`,
-`SCHEMA_NAME_CASE_COLLISION`, `FIELD_NAME_CASE_COLLISION`,
-`MANTLE_REF_INVALID`, the `TRANSLATES_*` codes, `JSON_SCHEMA_UNSUPPORTED`; at
-boot `STORAGE_CHANGE_BLOCKED` and `STORAGE_TABLE_NOT_OWNED`. See
-[Diagnostics](./diagnostics.md).
+A seed or other SQL that inserts rows outside Mantle (`wrangler d1 execute --file seed.sql`) sets the native columns
+itself: `id` (text, unique) and `created_at` (integer microseconds since the Unix epoch, e.g. `1767225600000000`);
+`updated_at` and `version` have defaults. Procedures and the Store fill them for you.

package/docs/handbook/reference/site-config.md

@@ -1,69 +1,9 @@
----
-description: The optional site capability in Mantle 0.2.0 — SiteDefaults passed to the storage adapter, the site_config table, which fields are seeded or synced, Admin's site routes and media purposes.
----
-# Site defaults and `site_config`
+# Site defaults and settings
 
-Site settings and the media library are one optional capability. A service
-turns it on by passing `SiteDefaults` to its storage adapter:
+Select `--site <module>` exporting `siteDefaults`, or pass the same options to programmatic generation. `SiteDefaults` from `@aotter/mantle/site` contains title, brand, description, origin, locales, optional icons and media purposes.
 
-```ts
-storage: (env) => d1Storage(env.DB, {
-  site: {
-    title: "Notes",
-    brand: "Notes",
-    description: "A small notebook.",
-    origin: "https://notes.example.com",
-    locales: ["en", "zh-TW"],
-    icons: [{ src: "/favicon.svg", mimeType: "image/svg+xml", sizes: ["any"] }],
-    media: { purposes: [{ name: "cover", required: ["image/webp", "image/jpeg,image/png"], maxBytes: { "image/webp": 2_000_000, "image/jpeg": 2_000_000, "image/png": 2_000_000 } }] },
-  },
-}),
-```
+Generation emits the generated site module, deployment DDL for `site_config`, `media_assets`, `pending_media_uploads`, and `site-seed.sql`. Apply initial schema only to an empty database. Apply seed SQL explicitly: only absent brand/title/description are seeded without overwriting edits. Origin, locales, icons and media purposes come from generated defaults. Runtime construction neither seeds nor migrates.
 
-With `site`, boot creates Mantle's product tables (`site_config`,
-`media_assets`, `pending_media_uploads`), writes the defaults, and the runtime
-carries `runtime.site`. Without it those tables are not created,
-`runtime.site` is absent, Admin's `/site-settings` answers 501
-`SITE_NOT_CONFIGURED` and its media routes 501 `MEDIA_NOT_CONFIGURED`, and the
-console leaves Settings and Media out of its navigation. The generated preset
-does not pass `site`; add it in `src/service.ts`. In 0.2.0 only the `sqlite`
-dialect's storage takes `site` (`d1Storage`, `sqliteStorage`,
-`bunSqliteStorage`); PostgreSQL storage has no site settings or media.
+Import the generated `site`, then use `site(db, verifiedCaller).read()` and `.updateSettings({ brand, title, description })`. Media is `site(db, caller).media(storage)`. Native SQLite/PostgreSQL are supported. Only selected modules enter the application bundle.
 
-## `SiteDefaults`
-
-| Field | Kind | At boot |
-|---|---|---|
-| `title`, `brand`, `description` | operator | written once if the row is missing; after that the database wins, so an owner's edit in Admin is never overwritten by code |
-| `origin` | deployment | synced every boot: the canonical absolute origin, no trailing slash |
-| `locales` | deployment | synced every boot; the first is the canonical locale |
-| `icons` | deployment | synced every boot: `[{ src, mimeType?, sizes?, theme? }]`, root-relative or absolute HTTPS. Without it the defaults are `/admin/favicon.png` and `/admin/favicon.svg`, served with the Admin console |
-| `media.purposes` | deployment | synced every boot: `[{ name, required: [mime slots], maxBytes: { mime: bytes } }]`; `name` is a lowercase slug |
-
-A blank value is skipped, so it never clears a stored one. Boot validates the
-defaults and refuses a malformed purpose or locale.
-
-## Reading and editing
-
-- `runtime.site.read()` returns `{ title, description, origin, locales,
-  canonicalLocale, brand, icons, media: { purposes } }`.
-- `runtime.site.updateSettings({ brand?, title?, description? })` edits the
-  operator fields; an empty string clears one.
-- Admin: `GET /admin/api/site` (any staff role) answers the site for the
-  console, with `mcpEndpoints` from `createAdminSurface`'s
-  `site: { mcpEndpoints }` (with feature `mcp` the preset passes
-  `{ public: "/mcp", staff: "/mcp/staff" }`; default `null`). `GET` and `PATCH /admin/api/site-settings` (owner) read and
-  edit the operator fields.
-
-## Media purposes
-
-A purpose names a kind of upload and the variants it needs. Each `required`
-entry is one MIME slot in `<input accept>` grammar (`"image/webp"`,
-`"image/jpeg,image/png"` for either, `"webp"` for short), and an upload supplies
-one variant per slot; slots must not overlap. `maxBytes` caps each full MIME
-type and must cover every type a slot accepts. Separately, exactly one variant
-of an upload says `role: "primary"` (what `<img>` falls back to); the others are
-`alternate` or `fallback`. The accepted types are PNG, JPEG, WebP, AVIF and GIF
-(SVG is refused). An upload request names its purpose; a missing slot or a
-byte size over the cap is refused before any upload URL is issued. See
-[Media uploads with R2](../cloudflare/media-r2.md).
+Admin site/media routes are optional capabilities; their additional admin-cookie gate and origin checks remain required. The app owns object storage, signing and upload CORS. See [media wiring](../cloudflare/media-r2.md).

package/docs/handbook/reference/sql.md

@@ -0,0 +1,64 @@
+---
+description: The SQL that Views and Procedures accept on SQLite/D1 and on PostgreSQL, and what each refuses with which diagnostic.
+---
+# SQL accepted by each dialect
+
+Views and Procedures share one allowlist with two profiles. SQLite and D1 run the base profile; PostgreSQL runs the
+base profile plus the additions below. Anything not listed is refused at generation with a code (`SQL_UNSUPPORTED`,
+`SQL_FUNCTION`, `SQL_SHAPE`, `SQL_TYPE`) and a source position, so generation is the authority for each target. For
+worked examples see [SQL patterns](../guides/sql-patterns.md).
+
+## Both dialects
+
+| Area | Accepted |
+| --- | --- |
+| Statements | `SELECT`, `INSERT … VALUES` / `INSERT … SELECT`, `UPDATE … SET … WHERE`, `DELETE … WHERE`, each with `RETURNING`; `WITH` (non-recursive) on a `SELECT` |
+| Upsert | `ON CONFLICT (<unique index columns>) DO NOTHING` / `DO UPDATE SET …`, with `excluded.<column>` |
+| Joins | `INNER JOIN`, `LEFT JOIN`; a comma join only for a row source (`json_each`, or PostgreSQL's below) |
+| Clauses | `WHERE`, `GROUP BY`, `HAVING`, `ORDER BY`, `LIMIT` |
+| Predicates | `=`, `<>`, `!=`, `<`, `>`, `<=`, `>=`, `AND`, `OR`, `NOT`, `IS [NOT] NULL`, `IS [NOT] DISTINCT FROM`, `[NOT] BETWEEN`, `IN (list)`, `IN (subquery)`, `LIKE`, `[NOT] EXISTS (subquery)` |
+| Expressions | `+ - * / %`, `\|\|`, `->>` (JSON field), `CASE`, `COALESCE`, `NULLIF`, scalar subqueries, `CAST(… AS text \| int4 \| int8 \| float8 \| bool \| timestamptz \| date \| numeric \| interval)` |
+| Aggregates | `count`, `sum`, `min`, `max`, `avg` |
+| Windows | `row_number()`, `rank()`, `sum()`, `count()` with `OVER (PARTITION BY … ORDER BY …)` and the default frame |
+| Scalar functions | `lower`, `upper`, `length`, `abs`, `round`, `substr`, `replace`, `trim`, `ltrim`, `rtrim`, `instr` |
+| Time | `now()`, `date_trunc('hour' \| 'day' \| 'week' \| 'month' \| 'year', …)`, `extract(year \| month \| day \| dow \| hour FROM …)` |
+| Mantle | `auth.uid()`, `input.<name>`, `mantle.search`, `mantle.search_rank`, `mantle.near`, `mantle.distance` ([features](features.md)) |
+
+## SQLite and D1 only
+
+| Accepted | PostgreSQL instead |
+| --- | --- |
+| `json_each(<array>)` as a row source (`FROM json_each(input.items) j`, `j.value ->> 'field'`) | `jsonb_array_elements(…) AS j(value)` |
+| `json_group_array`, `json_group_object` | `jsonb_agg`, `jsonb_object_agg` |
+| `json_extract`, `json_set`, `json_insert`, `json_remove`, `json_array_length`; build an object with `json_set('{}', '$.k', v, …)` (`json_object` is refused) | `jsonb_build_object`, `jsonb_build_array` and the jsonb operators |
+| `typeof`, `hex` | refused (`typeof` is SQLite's; PostgreSQL has `pg_typeof`) |
+
+An integer `CAST` of anything but a literal is refused (`SQL_TYPE`): SQLite truncates where PostgreSQL rounds. Write
+`round(x)`; `->>` already returns a JSON number as a number.
+
+## PostgreSQL additions
+
+| Area | Accepted |
+| --- | --- |
+| Set operations | `UNION [ALL]`, `INTERSECT`, `EXCEPT`, inside a `WITH` or a subquery (the View's own SELECT is the one that pages) |
+| Relations | `LATERAL` subqueries, `WITH RECURSIVE`, `MATERIALIZED` / `NOT MATERIALIZED` CTEs |
+| Row sources | `jsonb_array_elements`, `jsonb_array_elements_text`, `jsonb_each`, `jsonb_each_text`, with `WITH ORDINALITY` |
+| Operators | `ILIKE`, `~`, `~*`, `!~`, `!~*`, jsonb `->`, `#>`, `#>>`, `@>`, `<@`, `?`, `?\|`, `?&` |
+| Aggregates | `string_agg`, `jsonb_agg`, `jsonb_object_agg`, with `FILTER (WHERE …)` and `ORDER BY` inside the call |
+| Windows | also `avg`, `min`, `max`, `lag`, `lead`, `first_value`, `last_value`, `dense_rank`; frames except `GROUPS` and `EXCLUDE` |
+| Functions | `GREATEST`, `LEAST`, `floor`, `ceil`, `sqrt`, `power`, `split_part`, `timezone`, `jsonb_build_object`, `jsonb_build_array`, `jsonb_strip_nulls`, `to_jsonb`, `jsonb_typeof`, `CAST(… AS jsonb)` |
+| Time | `date_trunc` also `'minute'`, `'quarter'`; `extract` also `minute`, `quarter`, `week`, `isoyear`, `isodow`, `doy`, `epoch` |
+
+`jsonb_agg` of no rows is `NULL`: write `COALESCE(jsonb_agg(…), CAST('[]' AS jsonb))` for an empty array.
+
+## Refused on every target
+
+- `OFFSET`: page with the generated cursor (`limit`, `cursor`) instead.
+- `RIGHT` and `FULL` joins, `UPDATE … FROM`, `DELETE … USING`, DDL and any function not listed.
+- `DISTINCT` with `ORDER BY`: the paging key Mantle appends would change what is distinct; use `GROUP BY`.
+- A program of more than 2000 syntax nodes.
+
+Two write rules come from Mantle, not the dialect ([Procedure](procedure.md)). A row-classified `UPDATE`/`DELETE`
+(`WHERE id = input.id …`) must change exactly one row, otherwise `CONFLICT`. A set form (`WHERE id IN (SELECT …)`,
+`INSERT … SELECT`) may change none, so write a conditional write that may do nothing in that form. Scope, version,
+timestamps and author columns are assigned by Mantle, never by your SQL.