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

package/docs/handbook/reference/schema.md

@@ -1,204 +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 `->>` in SQL, or `json_each` on D1 (PostgreSQL: `jsonb_array_elements_text(…) WITH ORDINALITY AS j(value, n)`) |
-| `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.
+
+## 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 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.
+
+`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.
+
+See [Admin](../guides/admin-ui.md), [extensions](../guides/admin-extensions.md) and [diagnostics](diagnostics.md).
+
+### Field scope
+
+`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.
+
+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.
+
+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.
+
+## Reserved entry columns
+
+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()" }`.
 
-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).
-
-## `ttl`
-
-`{ 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.
-
-## `localized` and `translates`
-
-`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.
-
-## `uiSchema`
-
-Admin presentation only; it never changes validation or MCP.
-
-| Key | Values |
-|---|---|
-| `fields.<name>.widget` | `textarea` (a string field), or `<extension>/<contribution>`: an Admin extension's `field.input/v1` control, for any field type |
-| `fields.<name>.options` | with an extension widget only: an object checked against the contribution's `optionsSchema` |
-| `list.primaryField` | a scalar data field shown first (operational Schemas) |
-| `list.columns` | data fields and native columns, in order (operational Schemas) |
-| `list.cells` | data field or native column -> `<extension>/<contribution>`, an Admin extension's `field.cell/v1` renderer |
-| `panels` | up to 16 `<extension>/<contribution>` names: Admin extension `record.sidebar/v1` panels on the record page |
-| `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 |
-
-Other keys are refused (`SCHEMA_UI_INVALID`). A contribution name is checked for shape here; whether it exists, fits the key and accepts the `options` is checked when Admin starts ([Extend Admin](../guides/admin-extensions.md)).
-
-## Diagnostics
-
-`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).