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

package/docs/handbook/reference/procedure.md

@@ -1,127 +1,19 @@
----
-description: Procedure field reference for Mantle 0.2.0 — input and output, SQL and ref handlers, write rules, row ops and locks, target, mcp annotations, uiSchema and diagnostics.
----
 # Procedure
 
-```yaml
-apiVersion: cms.mantle.aotter.net/v2
-kind: Procedure
-metadata: { name: review-order }
-spec:
-  title: Review order                 # optional, a string or a locale map
-  description: …                      # optional; the MCP tool's and Admin operation's description
-  requires: { … }                     # optional, see Authorization requirements
-  input: { type: object, … }          # required JSON Schema
-  output: { type: object }            # required JSON Schema
-  handler: { sql: "…" }               # or { ref: <name> }
-  target: { schema, id, version? }    # optional; inferred for one locked row op
-  mcp: { destructiveHint: true }      # optional tool annotations
-  uiSchema: { … }                     # optional, Admin only
-```
+A Procedure requires `input`, `output` JSON Schemas and a `handler` containing SQL or a ref name. Optional fields include title, description, requires, target, MCP annotations and Admin uiSchema. See [manifest envelope](manifest.md).
 
-`input` is validated before the handler runs (`INPUT_VALIDATION_FAILED`),
-and the result against `output` (`OUTPUT_VALIDATION_FAILED`, a 500: the bug
-is the handler's). `expectedVersion` is the conventional input name for the
-version a caller read.
+SQL uses declared Schemas, `input.<name>`, `auth.uid()` and native expressions accepted by the selected compiler dialect. Compiler policy supplies scope and system fields. Do not assign scope, version, status, published_at, timestamps or author columns yourself. Publishing writes use generated transitions. `restrict` narrows the rows the statements read and write, as on a [View](view.md#restrict); it is refused on ref handlers.
 
-## `handler.sql`
+A row-classified INSERT/UPDATE/DELETE (one that targets a single row, e.g. `WHERE id = input.id`) must affect one row. Use `WHERE id = input.id AND version = input.expectedVersion` for explicit OCC. Set operations, including UPDATE with a subquery and `INSERT ... SELECT`, may affect zero rows without an error: check the returned rows when zero means failure. A unique clash, a failed Schema `checks` constraint (the message starts with `A check of the Schema failed`; SQLite and D1 add the check expression, PostgreSQL the constraint name) or a failed row assertion is `CONFLICT` (409); statements run atomically. Results are raw `{ results }`, not runtime-validated authored outputs. RETURNING uses SQL output names; quote an explicit alias to preserve declared case (`RETURNING reqStatus AS "reqStatus"`). Generation warns about unaliased direct fields whose declared name differs from storage.
 
-One or more `INSERT`, `UPDATE` and `DELETE` statements separated by `;`,
-applied as one batch: all or nothing, in order. The output is
-`{ "results": [[…], …] }`, the `RETURNING` rows of each statement in order; so
-an `output` of `{ type: object }` accepts it.
+A row-classified UPDATE/DELETE on an excluded or missing id affects zero rows and returns HTTP 409 (`CONFLICT`), just like a stale version; reads return not found. Native Admin's visible-row pre-read returns 404 for excluded/missing ids.
 
-| Statement | Supported |
-|---|---|
-| `INSERT` | `INSERT INTO t (cols) VALUES (…)` (one row), `INSERT INTO t (cols) SELECT …`, `ON CONFLICT (cols) DO NOTHING \| DO UPDATE SET c = EXCLUDED.c …`, `RETURNING` |
-| `UPDATE` | `UPDATE t SET c = <expr> … WHERE …`, `RETURNING` |
-| `DELETE` | `DELETE FROM t WHERE …`, `RETURNING` |
+A ref handler is application code called as `(ctx, input)`. Generation prints required `Handlers` keys; typecheck and implement them. Wire them at `store(db, caller, { handlers })` and selected surfaces. The context has the Caller, the native db and a Store for that caller. A handler is not one transaction by itself: when it runs inside a caller's `store.transaction`, its db and Store are that transaction's; otherwise each write commits on its own. On PostgreSQL and bun:sqlite, `ctx.transaction(async ({ store, db }) => …)` makes writes that must commit together atomic; it joins the transaction the handler already runs in. A joined transaction has no savepoint, so let an error inside `ctx.transaction` propagate: a handler that catches it and carries on keeps the writes made before the error. Keep external calls (payments, supplier APIs) outside it, so a callback never waits for an uncommitted row. D1 has no interactive transactions, so its `HandlerContext` has no `transaction`: put writes that must commit together in one SQL Procedure, whose statements commit together, and call it through `ctx.store.procedures`. It is not a sandbox; the app owns external side effects and input/output handling. The context has no `env`: on Workers read bindings and secrets with `import { env } from "cloudflare:workers"`. The Caller carries no name or email; `userOf(caller)` from `@aotter/mantle/auth` returns the Better Auth user record it was resolved from, for session, OAuth and service credentials alike (undefined for system callers).
 
-Expressions are those of [View SQL](./view.md#what-the-d1-dialect-accepts).
-References: `input.<name>`, `auth.uid()`, `auth.role()`, `now()`.
+`target: { schema, id, version? }` binds an Admin operation to a row. SQL targets can be inferred for a single locked row operation; declare a target for a ref operation when needed. Input fields must have the required shapes.
 
-**A write may not name** the scope field, `version`, `status`, `created_at`,
-`updated_at`, `author_id`, or `id` in an `UPDATE`, in a column list, `SET` or
-`DO UPDATE SET`; on a scoped Schema an `INSERT` names no `id`. Store fills
-them (`SQL_WRITE`). Multi-row `VALUES` is refused: insert from
-`json_each(input.items)` instead. `UPDATE … FROM`, `DELETE … USING`,
-`INSERT OR …` and `last_insert_rowid()` are refused.
+Generated requires checks gate calls. Boundary input validators are generated separately; direct queries accept driver-ready, app-validated input. Dynamic guards and lifecycle hooks are rejected. See [native execution](../guides/native-execution.md) and [surface contracts](surface.md).
 
-**RETURNING names** fold to lower case unless quoted:
-`RETURNING id, orderNumber AS "orderNumber"`.
+SQL INSERT/upsert into a user-field scoped Schema is system-only. For a verified user, insert through `ctx.store` so membership and single-partition autofill run before the native write. `ctx.store` speaks storage names, not the manifest's: the handler's `input` uses authored names (`input.parentId`), while Store writes, filters and rows use the folded column (`insert({ parentid: input.parentId })`, `where: { parentid }`, `row.parentid`); generated Store types show the exact names ([typed queries](../guides/typed-queries.md)). SET cannot change a field-scope column, including ON CONFLICT DO UPDATE. Scoped unique conflict targets gain the owner/field prefix automatically.
 
-### Row ops and set ops
-
-- **Row op**: an `UPDATE` or `DELETE` whose top-level `WHERE` has
-  `id = <value>`, or a one-row `INSERT … VALUES` without `ON CONFLICT`. If it
-  writes no row the batch fails with `CONFLICT` and nothing applies.
-- **Set op**: everything else. Writing no row is a normal result. Refused on a
-  `publishing` Schema, and on a Schema with a `before_*` hook for that
-  operation.
-- **Lock**: `AND version = input.<name>` in a row op's `WHERE`. A stale version
-  matches nothing, so it is `CONFLICT` (HTTP 409).
-
-### `target`
-
-`{ schema, id, version? }`: the Schema the Procedure mutates, the required
-string input holding the row id, and the integer input holding the version it
-locks. Admin binds an operation to a row by it. A Procedure whose SQL is
-exactly one row op pinning `id` (and `version`) to inputs gets it inferred;
-declare it for a `ref` handler. `PROCEDURE_TARGET_INVALID` when the inputs do
-not have those shapes.
-
-## `handler.ref`
-
-```yaml
-handler: { ref: cancelOrder }
-```
-
-The name of a function in the service's `handlers` map. The generated
-`MantleHandlers` type lists exactly the plan's refs, with typed input and
-output; boot refuses a missing one (`HANDLER_NOT_REGISTERED`) and an extra
-one (`HANDLER_NOT_DECLARED`).
-
-```ts
-(input, ctx) => output | Promise<output>
-// ctx: { caller, cause, store, invoke, env, waitUntil }
-```
-
-A handler reaches Mantle-owned rows only through `ctx.store`
-([Query from TypeScript](../guides/typed-queries.md)). It throws
-`DiagnosticError` (from `@aotter/mantle`) to answer with a code; any
-other throw is logged and answered as `INTERNAL_ERROR`. Guards, before hooks
-and lifecycle targets must be `ref` handlers.
-
-## `requires`
-
-`requires.auth.all` (predicates) and `requires.guard.procedure` (a `ref`
-Procedure run before this one). See
-[Authorization requirements](./authorization.md).
-
-## `mcp`
-
-`readOnlyHint`, `destructiveHint`, `openWorldHint` (booleans), copied onto the
-MCP tool. `readOnlyHint` and `destructiveHint` may not both be true, and a SQL
-handler, which always writes, may not claim `readOnlyHint: true`.
-
-## `uiSchema`
-
-| Key | Effect in Admin |
-|---|---|
-| `fields.<name>.widget: textarea` | a multiline input |
-| `collectionAction: <schema>` | offer the operation on that collection's list |
-
-Admin lists a Procedure as an operation only when a Trigger binds it to the
-staff MCP surface.
-
-## Diagnostics
-
-Validate: `SQL_SYNTAX`, `SQL_UNSUPPORTED`, `SQL_FUNCTION`, `SQL_RELATION`,
-`SQL_COLUMN`, `SQL_WRITE`, `SQL_SHAPE`, `SQL_TYPE`, `PROCEDURE_TARGET_INVALID`,
-`GUARD_PROCEDURE_UNKNOWN`, `GUARD_SELF_REFERENCE`, `GUARD_PROCEDURE_NOT_REF`,
-`GUARD_CHAIN_NOT_ALLOWED`, `MCP_TOOL_DESCRIPTION_MISSING` (a warning),
-`MCP_TOOL_INPUT_UNION_AMBIGUOUS`, `MCP_TOOL_INPUT_UNBOUNDED`. Boot:
-`HANDLER_NOT_REGISTERED`, `HANDLER_NOT_DECLARED`. Run time:
-`INPUT_VALIDATION_FAILED`, `UNAUTHENTICATED`, `AUTH_DENIED`,
-`ENTITLEMENT_REQUIRED`, `CONFLICT`, `OUTPUT_VALIDATION_FAILED`,
-`INVOCATION_DEPTH_EXCEEDED`, `INTERNAL_ERROR`. See [Diagnostics](./diagnostics.md).
+Triggers are the only way request data reaches a Procedure: REST and MCP validate the input against the Procedure's schema, then call it. App code may also call a generated Procedure directly (`import run from "../generated/procedures/<name>.js"`, `await run(db, caller, input)`); `requires`, row policy and checks still apply, but input validation does not, so pass only data the app produced or has verified (a cron job, a callback after its signature check). A page that takes user input submits it to the Procedure's REST Trigger; see `docs/examples/purchasing/src/requests-page.ts`.

package/docs/handbook/reference/schema.md

@@ -1,201 +1,94 @@
----
-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. 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, ending with `id` as the tiebreak: `ORDER BY createdAt 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.
+
+`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.
 
-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).
+## Admin uiSchema
 
-## `ttl`
+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 and the Store, not by the database: a SQL Procedure that inserts the row sets the field itself. A root `readOnly: true` makes the whole Schema read-only in Admin.
 
-`{ 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.
+`fields.<name>.widget/options` select supported controls or extension contributions; `list.primaryField`, columns/cells and enum `filterField` select list presentation; `nav.standalone/parentField` control child navigation; `nav.group/order/hidden` place it in the sidebar ([sidebar](../guides/native-admin.md#sidebar)); panels select record sidebars. Generation validates these against declared fields/indexes and selected extension declarations. 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.
 
-## `localized` and `translates`
+See [Admin](../guides/admin-ui.md), [extensions](../guides/admin-extensions.md) and [diagnostics](diagnostics.md).
 
-`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.
+### Field scope
 
-## `uiSchema`
+`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.
 
-Admin presentation only; it never changes validation or MCP.
+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.
 
-| 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 |
+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. Procedure INSERT/upsert is trusted-only; use the scoped Store for user writes. 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.
 
-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).