@aotter/mantle 0.1.0-alpha.9 → 0.1.2-alpha.2

package/docs/handbook/reference/schema.md

@@ -0,0 +1,250 @@
+---
+description: Schema field reference — JSON Schema subset, extension keywords, uiSchema, indexes, searchable fields, translates and lifecycle rules.
+---
+# Schema
+
+A Schema declares one collection: the JSON Schema for each entry's `data`, its indexes, its Admin presentation and its lifecycle mode. Schemas are never exposed directly; Views read them and Procedures write them. This page is the field-level contract; the concepts are in [The four atoms](../concepts/four-atoms.md) and [Lifecycle and locales](../concepts/lifecycle-and-locales.md). Envelope rules are in [Manifest envelope and conventions](./manifest.md).
+
+## Fields
+
+| Field | Type | Required | Default | Rules |
+|---|---|---|---|---|
+| `title` | LocalizedText | yes | — | Admin label. Non-empty string or locale map. |
+| `description` | LocalizedText | no | — | Same shape as `title`. |
+| `schema` | JSON Schema 2020-12 | yes | — | Must be an object. Walked by the [subset validator](#json-schema-subset). |
+| `uiSchema` | object | no | — | Accepts `fields`, `list`, and `nav`. Violations are `SCHEMA_UI_INVALID`. |
+| `uniqueIndexes` | `string[][]` | no | `[]` | Ordered tuples of top-level scalar fields. See [Indexes](#indexes). |
+| `indexes` | `string[][]` | no | `[]` | Ordered non-unique tuples. Must not repeat a `uniqueIndexes` tuple. |
+| `searchableFields` | `string[]` | no | `[]` | Top-level string fields for Admin and Staff MCP substring search. |
+| `localized` | boolean | no | `false` | When `false`, a `locale` property is rejected. Must be a boolean. |
+| `translates` | `{ parent, on }` | no | — | Marks a translation child. Requires `localized: true`. |
+| `lifecycle` | `publishing` \| `operational` | no | `publishing` | Selects the [state machine](#lifecycle). |
+
+### Reserved entry columns
+
+Every entry carries `id`, `status`, `version`, `createdAt`, `updatedAt` and `authorId` as native columns outside `data`. They cannot be indexed (`SCHEMA_INDEX_INVALID`) but are valid in View `fields`, `filter`, `orderBy` and `uiSchema.list`. `locale` is a reserved data field: only a localized Schema may declare it, and the runtime requires it on writes to a localized Schema. Do not name data properties after the native columns; SQL Views project the native column. Do not declare `expectedVersion` under `spec.schema.properties` — that name is the reserved Procedure OCC token; validate fails closed with `INVALID_MANIFEST_ENVELOPE` (ADR-0022). New reserved Procedure input names need an ADR.
+
+## Example
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata:
+  name: support-requests
+spec:
+  title: { en: Support requests, "zh-TW": 客服請求 }
+  description: Requests submitted from the public contact form.
+  lifecycle: operational
+  schema:
+    type: object
+    additionalProperties: false
+    required: [ticketNumber, subject, body, requestStatus]
+    properties:
+      ticketNumber: { type: string, pattern: "^SR-[0-9]{6}$" }
+      subject: { type: string, minLength: 1, maxLength: 200 }
+      body: { type: string, x-mcp-hint: markdown }
+      requestStatus: { type: string, enum: [open, waiting, closed], default: open }
+      customerId: { type: string, x-mantle-ref: customers }
+      attachmentId: { type: string, x-mantle-ref: media_assets, x-mcp-hint: media-file }
+      submittedBy: { type: string, x-mantle-bind: ctx.user }
+      submittedAt: { type: integer, x-mcp-hint: timestamp-ms, x-mantle-bind: now }
+  uiSchema:
+    fields:
+      body: { widget: textarea }
+    list:
+      filterField: requestStatus
+      primaryField: ticketNumber
+      columns: [subject, requestStatus, submittedAt]
+  uniqueIndexes: [[ticketNumber]]
+  indexes: [[requestStatus, submittedAt], [customerId]]
+  searchableFields: [ticketNumber, subject]
+```
+
+## `translates`
+
+A translation child holds the locale-specific fields of a non-localized parent, joined on a shared field.
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata:
+  name: product-translations
+spec:
+  title: Product translations
+  localized: true
+  translates: { parent: products, on: sku }
+  schema:
+    type: object
+    required: [sku, name]
+    properties:
+      sku: { type: string }
+      locale: { type: string }
+      name: { type: string, minLength: 1 }
+      description: { type: string, x-mcp-hint: markdown }
+  uniqueIndexes: [[sku, locale]]
+```
+
+`locale` is declared but not listed in `required`; the write-time gate enforces presence.
+
+| Phase | Rule | Diagnostic |
+|---|---|---|
+| parse | `parent` and `on` are non-empty strings; no other keys. | `INVALID_MANIFEST_ENVELOPE` |
+| parse | `localized: true` is set. | `TRANSLATES_REQUIRES_LOCALIZED` |
+| parse | At least one property besides `locale` and the join field. | `TRANSLATES_REQUIRES_CONTENT_FIELD` |
+| parse | `on` is declared in this Schema's `properties`. | `TRANSLATES_FIELD_NOT_IN_CHILD` |
+| validate and boot | `parent` names a declared Schema. | `TRANSLATES_PARENT_UNKNOWN` |
+| validate and boot | The parent is not `localized: true`. | `TRANSLATES_PARENT_IS_LOCALIZED` |
+| validate and boot | `on` is declared in the parent's `properties`. | `TRANSLATES_FIELD_NOT_IN_PARENT` |
+| boot | A localized Schema needs at least one site locale. | `SCHEMA_LOCALIZED_REQUIRES_SITE_LOCALES` |
+
+## JSON Schema subset
+
+Authors write JSON Schema; the runtime validates with zod via `z.fromJSONSchema`. The parser accepts a bounded subset so every manifest converts.
+
+| Recognized keywords |
+|---|
+| `$defs`, `$ref`, `oneOf`, `const`, `type`, `properties`, `required`, `items`, `enum`, `format`, `pattern`, `minLength`, `maxLength`, `minimum`, `maximum`, `minItems`, `maxItems`, `nullable`, `readOnly`, `default`, `additionalProperties`, `title`, `description`, and any `x-` keyword |
+
+| Rejected keywords (`JSON_SCHEMA_UNSUPPORTED`) |
+|---|
+| `anyOf`, `allOf`, `not`, `if`, `then`, `else`, `$anchor`, `$dynamicAnchor`, `$dynamicRef`, `definitions`, `patternProperties`, `prefixItems`, `contains`, `dependentSchemas`, `propertyNames`, `unevaluatedProperties` |
+
+Other standard keywords are not rejected by the parser, but only the recognized set is part of the documented contract.
+
+| Rule | Diagnostic |
+|---|---|
+| Nesting deeper than 100 levels, or more than 10,000 schema nodes. | `JSON_SCHEMA_LIMIT_EXCEEDED` |
+| `$ref` must begin `#/$defs/` and resolve to an object in the same document. | `JSON_SCHEMA_REF_INVALID` |
+| `pattern` must compile as a JavaScript regular expression. | `INVALID_PATTERN` |
+| Every `required` entry of `spec.schema` must be declared under `properties`. | `REQUIRED_FIELD_UNKNOWN` |
+| `properties` and `$defs` must be objects; `oneOf` a non-empty array; `additionalProperties` a boolean or a schema. | `INVALID_MANIFEST_ENVELOPE` |
+
+Two compatibility normalizations run at the boundary: `nullable: true` becomes a `type` array that includes `"null"`, and `format: url` becomes `format: uri`. `additionalProperties` keeps standard semantics: omitted or `true` preserves extra keys, `false` rejects them, a schema validates them.
+
+### `x-mantle-bind`
+
+Marks a property as server-stamped. The value is a closed enum; anything else is `BIND_VALUE_NOT_IN_ENUM`.
+
+| Value | Stamped as | Typical field |
+|---|---|---|
+| `ctx.user` | `ctx.user?.id ?? null` | `authorId`, `submittedBy` |
+| `ctx.staff` | `ctx.staff?.id ?? null` | `approvedBy`, `grantedBy` |
+| `now` | write-time Unix epoch milliseconds | `createdAt`, `submittedAt` |
+
+Stamping semantics: on create the computed value replaces whatever the caller sent. On update the existing stamp is preserved and only computed when the stored row lacks it, so a `now` bind does not become an updated-at field. A `null` stamp is dropped before JSON Schema validation, so `type: string` passes for anonymous callers. Bound properties are removed from Staff MCP `create_*` and `update_*` tool schemas. Stamped values appear in View output as ordinary fields.
+
+### `x-mantle-ref`
+
+An informational foreign-key marker on a string property that holds another collection's entry id (`x-mantle-ref: customers`). Nothing is enforced: no constraint, cascade or orphan check. Admin uses it for pickers and related rows; `x-mantle-ref: media_assets` marks a media asset id. Declare a single-field index on the ref field when reverse lookups must stay bounded. On a Procedure input property the marker exposes a row action; see [Procedure](./procedure.md#uischema).
+
+### `x-mcp-hint`
+
+A free-form string that tells agents and Admin widgets how to render or produce a value. The grammar accepts any string; these values are conventional.
+
+| Value | Meaning |
+|---|---|
+| `markdown`, `richtext`, `code` | Text editor and authoring format. |
+| `media`, `media-image`, `media-video`, `media-file` | Media-shaped URL or asset reference (`isMediaMcpHint`). |
+| `money-minor` | Integer amount in minor currency units. |
+| `timestamp-ms` | Unix epoch milliseconds. |
+| `idempotency-key` | On a Procedure input: Admin generates and hides one UUID per form; other callers generate one and reuse it on retry. |
+
+Do not use a hint for optimistic concurrency. The reserved Procedure input name `expectedVersion` is the OCC token (observed `entry.version` at read time). First-party Admin binds and hides it by that name. Schema `spec.schema.properties` must not declare it (`INVALID_MANIFEST_ENVELOPE`).
+
+### Root `readOnly: true`
+
+`schema.readOnly: true` at the root marks a Procedure-managed collection. Staff MCP emits no `create_*` or `update_*` tool for it, and Admin's generic create, update, status change and delete return `CONFLICT` with the message that the Schema is read-only on generic authoring surfaces. Declared Views and Procedures (builtin or `ref`) keep working.
+
+## `uiSchema`
+
+Closed Admin-only roots: `fields`, `list`, `nav`. Nested keys are closed too. Unknown roots or nested keys are `SCHEMA_UI_INVALID`.
+
+| Key | Rule |
+|---|---|
+| `fields.<field>.widget` | Only `textarea`. The field must be a top-level property with a string type (`string` or `[string, null]`). |
+| `list.filterField` | Operational Schemas only. A declared property with a non-empty string `enum` that is the first field of some `indexes` or `uniqueIndexes` tuple. Admin renders the enum as sidebar links and list tabs. |
+| `list.primaryField` | Operational Schemas only. A non-empty top-level scalar property; rendered as the linked leading column. |
+| `list.columns` | Operational Schemas only. Top-level properties, no repeats and not repeating `primaryField`; structured values render as compact JSON. |
+| `nav.standalone` | Boolean. `true` also emits a main Admin Nav list entry with a **parent autocomplete filter**. It does not unfold: required `x-mantle-ref` children still compose under the parent. Omit or `false` means fold-only (discover via the parent-entry workbench). Rejected on top-level Schemas, `translates` children, and Schemas with no eligible required-ref parent. |
+| `nav.parentField` | Allowed only with `standalone: true`. Names a required `x-mantle-ref` field used as the parent filter. One eligible required ref is inferred; more than one requires an explicit `parentField`. Do not rely on property-order heuristics when multiple refs exist. |
+
+```yaml
+uiSchema:
+  list:
+    primaryField: name
+    columns: [status]
+  nav:
+    standalone: true
+    parentField: organizationId
+```
+
+Every violation is `SCHEMA_UI_INVALID`. Without `primaryField` and `columns`, Admin lists an operational collection with platform metadata only. `nav` is operational Admin navigation only — it does not change runtime, MCP, or publishing validation. Parent autocomplete coexists with `list.filterField` enum tabs as a separate control.
+
+Keep implementation-detail children fold-only. Use `nav.standalone: true` when staff also need a cross-parent list; see the [inventory example](../examples/commerce-transaction.md).
+
+## Indexes
+
+`uniqueIndexes` and `indexes` are arrays of ordered field tuples. Shape errors are `INVALID_MANIFEST_ENVELOPE`; semantic errors are `SCHEMA_INDEX_INVALID` unless noted. Bare strings and the retired `indexedFields` key are rejected; each index is an array of field names, even when it has one field.
+
+| Rule | Diagnostic |
+|---|---|
+| When any index is declared, `metadata.name` matches `/^[A-Za-z][A-Za-z0-9_.-]*$/`. | `SCHEMA_INDEX_INVALID` at `/metadata/name` |
+| Each tuple is a non-empty array of strings. | `INVALID_MANIFEST_ENVELOPE` (shape) or `SCHEMA_INDEX_INVALID` (empty) |
+| No field repeats within a tuple; field names match the same safe pattern. | `SCHEMA_INDEX_INVALID` |
+| Fields are not reserved entry columns. | `SCHEMA_INDEX_INVALID` |
+| Fields are exact top-level keys of `properties`. | `UNIQUE_INDEX_FIELD_UNKNOWN` or `SCHEMA_INDEX_FIELD_UNKNOWN` |
+| Fields are indexable scalars: exactly one non-null type, optionally nullable. `string` maps to TEXT, `integer` and `boolean` to INTEGER, `number` to REAL. | `SCHEMA_INDEX_INVALID` |
+| No tuple repeats within a list; `indexes` does not repeat a `uniqueIndexes` tuple. | `SCHEMA_INDEX_INVALID` |
+
+On SQLite storage each Schema is a native table and every tuple becomes an
+index over its native field columns; queries benefit from a leftmost prefix.
+Unique indexes are also checked before every write; a conflicting row is
+`CONFLICT`.
+
+## `searchableFields`
+
+An array of unique top-level string properties (`string` or `[string, null]`). Non-array or non-string entries are `INVALID_MANIFEST_ENVELOPE`; duplicates and non-string properties are `SCHEMA_SEARCH_INVALID`; unknown fields are `SCHEMA_SEARCH_FIELD_UNKNOWN`. The entry `id` is always searched. Substring search does not use `indexes`.
+
+## Lifecycle
+
+`publishing` is the default state machine.
+
+| From | To |
+|---|---|
+| `draft` | `published`, `archived` |
+| `published` | `archived`, `draft` |
+| `archived` | `draft` |
+
+`operational` has no transitions. Entries are created with `status: published`, edited in place, and any publish, unpublish or archive request returns `CONFLICT`. Admin hides lifecycle controls; Staff MCP emits `create_record_<segment>` and `update_record_<segment>` instead of the draft tools. A builtin `archive` Procedure cannot target an operational Schema.
+
+Deleting a `published` entry of a publishing Schema is `CONFLICT` (unpublish first). Operational entries can be deleted in any status.
+
+### Write-time locale gate
+
+Every authoring path (Admin, Staff MCP, builtin Procedures) runs the same guard after stamping, per request, reading the current site locales.
+
+| Condition | Result |
+|---|---|
+| Non-localized Schema and `data.locale` is present. | `INPUT_VALIDATION_FAILED` |
+| Localized Schema and `data.locale` missing or empty. | `INPUT_VALIDATION_FAILED` (skipped for partial draft saves; publish re-checks). |
+| Localized Schema and `data.locale` not in the site locales. | `INPUT_VALIDATION_FAILED` with the enabled locales as candidates. |
+| Site locales list is empty. | Locale membership is not checked. |
+
+Site locales are configured in [Site config](./site-config.md).
+
+## Source
+
+- [`packages/mantle-spec/src/domain/model/ManifestGrammar.ts`](../../../packages/mantle-spec/src/domain/model/ManifestGrammar.ts)
+- [`packages/mantle-spec/src/domain/service/ManifestParser.ts`](../../../packages/mantle-spec/src/domain/service/ManifestParser.ts)
+- [`packages/mantle-spec/src/domain/service/ManifestGraphValidator.ts`](../../../packages/mantle-spec/src/domain/service/ManifestGraphValidator.ts)
+- [`packages/mantle-spec/src/domain/service/CrossSchemaChecker.ts`](../../../packages/mantle-spec/src/domain/service/CrossSchemaChecker.ts)
+- [`packages/mantle-spec/src/domain/service/SchemaIndexChecker.ts`](../../../packages/mantle-spec/src/domain/service/SchemaIndexChecker.ts)
+- [`packages/mantle-spec/src/domain/service/SchemaSearchChecker.ts`](../../../packages/mantle-spec/src/domain/service/SchemaSearchChecker.ts)
+- [`packages/mantle-spec/src/domain/service/SchemaAdminUiChecker.ts`](../../../packages/mantle-spec/src/domain/service/SchemaAdminUiChecker.ts)
+- [`packages/mantle-spec/src/domain/service/LifecycleStateMachine.ts`](../../../packages/mantle-spec/src/domain/service/LifecycleStateMachine.ts)
+- [`packages/mantle-spec/src/domain/service/JsonSchemaToZod.ts`](../../../packages/mantle-spec/src/domain/service/JsonSchemaToZod.ts)
+- [`packages/mantle-runtime/src/domain/service/BuiltinProjector.ts`](../../../packages/mantle-runtime/src/domain/service/BuiltinProjector.ts)
+- [`packages/mantle-runtime/src/domain/service/io/EntryWriteGuard.ts`](../../../packages/mantle-runtime/src/domain/service/io/EntryWriteGuard.ts)
+- [`packages/mantle-runtime/src/domain/service/io/EntryDeleteGuard.ts`](../../../packages/mantle-runtime/src/domain/service/io/EntryDeleteGuard.ts)
+- [`packages/mantle-runtime/src/infrastructure/mcp/McpToolCatalog.ts`](../../../packages/mantle-runtime/src/infrastructure/mcp/McpToolCatalog.ts)
+- [`packages/mantle-admin/src/mountMantleAdmin.ts`](../../../packages/mantle-admin/src/mountMantleAdmin.ts)

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

@@ -0,0 +1,233 @@
+---
+description: siteDefaults reference — locales, brand, icons, media purposes, the runtime SiteConfig read shape, site_config row ownership and what boot validates.
+---
+# Site config
+
+Site config is a sibling of the Manifest grammar, not part of it. The four atoms describe content; `siteDefaults` describes the deployment: the locales the site publishes in, its brand and title, its canonical origin, its icons, its analytics ids and its media taxonomy. The deployment declares it as a TypeScript object and passes it to the adapter; the runtime seeds it into the `site_config` table and every render, MCP catalog build and Admin page reads it back from there.
+
+## `siteDefaults`
+
+| Key | Type | Required | Rules |
+|---|---|---|---|
+| `locales` | `string[]` | no | Ordered. `locales[0]` is the canonical locale. Empty or omitted turns the locale subsystem off site-wide. Every entry must canonicalize; see [Boot validation](#validated-at-boot). |
+| `brand` | string | no | Operator-facing label for Admin chrome and MCP `serverInfo.title`. Distinct from `title`. |
+| `title` | string | no | Site title — `<title>` suffix and `og:site_name`. |
+| `description` | string | no | Default `<meta name="description">` and `og:description` for entries with none. |
+| `origin` | string | no | Canonical absolute origin, no trailing slash, for example `https://example.com`. Used to build absolute URLs in `/llms.txt`, the `.md` mirrors and `/sitemap.xml`. An empty origin yields relative URLs. |
+| `icons` | `SiteIcon[]` | no | One site identity reused by browser favicons, Admin chrome and MCP `serverInfo.icons`. Declaring an empty array is an error. |
+| `ga4MeasurementId` | string | no | GA4 Measurement ID such as `G-XXXXXXXXXX`. When present the runtime injects the standard gtag snippet into rendered public HTML. |
+| `facebookPixelId` | string | no | Meta Pixel ID. When present the runtime injects the standard Pixel base snippet. |
+| `media.purposes` | `MediaPurposePolicy[]` | no | The upload taxonomy. Omitting the key, or declaring an empty array, keeps first-party media uploads disabled. |
+
+Nothing in this object is validated for length or content beyond the rules above: `brand`, `title`, `description` and `origin` are free strings.
+
+## `SiteIcon`
+
+```ts
+interface SiteIcon {
+  readonly src: string;
+  readonly mimeType?: "image/png" | "image/jpeg" | "image/svg+xml" | "image/webp";
+  readonly sizes?: readonly string[];
+  readonly theme?: "light" | "dark";
+}
+```
+
+| Field | Rules |
+|---|---|
+| `src` | Either root-relative (starts with a single `/`, no whitespace, no backslash) or an absolute `https:` URL. Anything else is rejected. |
+| `mimeType` | Optional. One of the four listed types. |
+| `sizes` | Optional. When present, a non-empty array whose entries are `any` or `<width>x<height>` with non-zero decimal dimensions, for example `64x64`. |
+| `theme` | Optional. `light` or `dark`. |
+
+When the deployment declares no icons, the runtime stores `DEFAULT_SITE_ICONS`:
+
+```ts
+const DEFAULT_SITE_ICONS = [{
+  src: "/_mantle/admin/favicon.svg",
+  mimeType: "image/svg+xml",
+  sizes: ["any"],
+}];
+```
+
+Multiple renditions are allowed. Keep SVG as the source and add a PNG rendition when a target MCP client needs a baseline raster format. `GET /favicon.ico` resolves against this list; see [Surface](./surface.md).
+
+## `MediaPurposePolicy`
+
+```ts
+interface MediaPurposePolicy {
+  readonly name: string;
+  readonly required: readonly string[];
+  readonly maxBytes: Readonly<Record<string, number>>;
+}
+```
+
+| Field | Rules |
+|---|---|
+| `name` | The slug callers pass as `purpose`. Must match `^[a-z0-9]+(-[a-z0-9]+)*$`: lowercase alphanumerics, dash-separated, no leading, trailing or repeated dashes. |
+| `required` | Ordered list of acceptable mime **slots**, at least one. Each entry uses the HTML `<input accept>` grammar. |
+| `maxBytes` | Per-mime byte cap keyed by fully expanded mime type. Must name every mime that appears in any slot after expansion, and every value must be a positive number. |
+
+A slot entry is one of a full mime (`image/jpeg`), a comma-list of full mimes (`image/jpg,image/png`, meaning either is acceptable for that slot), or a shorthand subtype (`webp` expands to `image/webp`, `jpg` and `image/jpg` both expand to `image/jpeg`). Whitespace around commas is tolerated.
+
+Slot position does not determine variant role. Per asset the uploading agent picks one mime per slot and independently declares exactly one supplied variant as `primary` — the format `<img>` falls back to — with the rest `alternate`, preferred through `<picture><source>`. Because a variant maps to a slot by its mime alone, mime sets across slots must not overlap; an overlap is rejected at boot rather than per upload.
+
+## Runtime `SiteConfig`
+
+`siteDefaults` is the author-time declaration. `SiteConfig` is the read shape that templates, the MCP catalog and Admin see after the seed has run and an operator has had a chance to edit.
+
+| Field | Type | Value when the row is absent |
+|---|---|---|
+| `title` | string | `"CMS"` |
+| `description` | string | `""` |
+| `origin` | string | `""` |
+| `brand` | string | `"AotterMantle"` |
+| `locales` | `readonly string[]` | `[]` |
+| `canonicalLocale` | `string \| null` | `locales[0]` or `null` when the list is empty |
+| `icons` | `readonly SiteIcon[]` | `DEFAULT_SITE_ICONS` |
+| `ga4MeasurementId` | `string \| undefined` | `undefined` (an empty stored value also reads as `undefined`) |
+| `facebookPixelId` | `string \| undefined` | `undefined` |
+| `media.purposes` | `readonly MediaPurposePolicy[]` | `[]` |
+
+`canonicalLocale` is computed, never stored. Templates emit `<html lang>` only when it is non-null; silent omission is the correct behaviour for a zero-locale site, not a fabricated default.
+
+## `site_config` rows
+
+The table is a flat key/value store. Keys fall into two ownership classes, and the seed treats them differently.
+
+| Key | Ownership | Written by seed | Source of truth |
+|---|---|---|---|
+| `brand` | UI-editable, seed-once | `INSERT … ON CONFLICT DO NOTHING` | The database, once the row exists |
+| `title` | UI-editable, seed-once | `INSERT … ON CONFLICT DO NOTHING` | The database, once the row exists |
+| `description` | UI-editable, seed-once | `INSERT … ON CONFLICT DO NOTHING` | The database, once the row exists |
+| `ga4MeasurementId` | UI-editable, seed-once | `INSERT … ON CONFLICT DO NOTHING` | The database, once the row exists |
+| `facebookPixelId` | UI-editable, seed-once | `INSERT … ON CONFLICT DO NOTHING` | The database, once the row exists |
+| `origin` | Code-canonical, boot-synced | Upsert when the stored value differs | The declaration |
+| `faviconUrl` | Code-canonical, boot-synced | Upsert when the stored value differs; holds the `icons` array as JSON | The declaration |
+| `locales` | Code-canonical, boot-synced | Upsert when the stored value differs; holds the declared list as a comma-separated string | The declaration |
+| `mediaPurposes` | Code-canonical, boot-synced | Upsert when the stored value differs; holds the purposes array as JSON | The declaration |
+
+Blank values are skipped in both classes: an absent, empty or empty-array field never writes and never clears an existing row, so a partial declaration cannot clobber stored values. The boot-synced keys are read-compared before writing, so an unchanged deployment issues no write.
+
+The seed-once keys have an Admin edit path at `PATCH /admin/api/site-settings` (owner only); the boot-synced keys do not, which is why the declaration wins on every boot. A custom-domain change therefore becomes canonical by editing the code and redeploying, with no manual database edit.
+
+> **Warning**
+> `mediaPurposes` is JSON. Rows written by pre-`#272` deployments used a CSV form and do not round-trip. Re-run the seed, or delete the row, after upgrading.
+
+## Validated at boot
+
+Storage preparation calls `assertSiteDefaultsCanonical(siteDefaults)` synchronously, before the runtime accepts traffic. It throws — it does not return diagnostics — so a typo rejects the deployment rather than corrupting the seed.
+
+| Error | Thrown when |
+|---|---|
+| `InvalidSiteDefaultsError` | Any declared locale fails canonicalization. Carries `invalidLocales`; the message adds script-subtag guidance when one is present. |
+| `InvalidSiteIconsError` | `icons` is declared as an empty array, or any icon fails the [`SiteIcon`](#siteicon) rules. Carries the offending icons. |
+| `InvalidMediaPurposesError` | Any declared purpose fails a policy rule. Carries one issue per purpose. |
+
+`InvalidMediaPurposesError` reports exactly one reason per purpose, checked in this order and stopping at the first hit:
+
+| Reason | Meaning |
+|---|---|
+| `invalid-slug` | `name` does not match the slug pattern. |
+| `empty-required` | `required` is an empty array. |
+| `empty-required-slot` | A `required` entry parses to zero mimes. |
+| `overlapping-slot-mimes` | Two slots accept the same mime, so a variant cannot be mapped to one slot. |
+| `maxBytes-missing-mime` | `maxBytes` has no entry for a mime that some slot accepts. |
+| `maxBytes-non-positive` | A `maxBytes` entry is not a positive number. |
+
+Locale canonicalization accepts a 2- or 3-letter ISO 639 language plus an optional 2-letter ISO 3166 region, separated by `-` or `_`, or run together in the 2+2 form. Case is irrelevant: `zh-tw`, `ZH_TW` and `zhTW` all canonicalize to `zh-TW`. The canonicalized list is deduplicated, so `["zh-tw", "zh-TW"]` collapses to one entry. Script subtags are valid BCP 47 but deliberately unsupported in v0.1 — `zh-Hant`, `zh-Hans`, `sr-Latn` and `sr-Cyrl` are all rejected; use region tags such as `zh-TW` and `zh-CN`. Variants such as `de-1996` are likewise rejected. The `locales` row stores the declared list verbatim once it validates.
+
+Deployment readiness runs alongside the seed and collects boot-phase diagnostics, throwing `BootValidationError` when any is an error.
+
+| Check | Diagnostic |
+|---|---|
+| `checkSiteLocales`: the site locale list canonicalizes. | `INVALID_LOCALE` at `site_config/locales`, listing the invalid entries |
+| `checkSiteLocales`: no Schema declares `localized: true` while the site has zero valid locales. | `SCHEMA_LOCALIZED_REQUIRES_SITE_LOCALES` |
+| `translates` references resolve: the parent exists, is not itself localized, and declares the join field. | `TRANSLATES_PARENT_UNKNOWN`, `TRANSLATES_PARENT_IS_LOCALIZED`, `TRANSLATES_FIELD_NOT_IN_PARENT` |
+| Every `handler.kind: ref` key is registered in the `handlers` map. The registered keys are attached as `candidates`. | `HANDLER_NOT_REGISTERED` |
+| No HTTP Trigger path falls under an adapter-reserved prefix. | `TRIGGER_PATH_INVALID` |
+| Every `sql` View's dialect is supported by the bound storage adapter. | `VIEW_DIALECT_UNSUPPORTED` |
+
+## Checked per request
+
+| Read | When |
+|---|---|
+| `siteConfig.load()` | Every public render, every `/llms.txt`, `.md` mirror and sitemap response, every MCP catalog build, the Admin site payload. Reads all rows and applies the fallbacks above. |
+| `siteConfig.readLocales()` | Locale resolution on public routes and the write-time locale gate. Reads only the `locales` row; the value is memoized per repository instance once a prepared revision proves the code-owned locale policy is current. |
+| `siteConfig.readMediaPurposes()` | Upload authorization. Always reads the canonical row, never a cached catalog snapshot. |
+
+The `data.locale` write gate runs on every authoring path — Admin, Staff MCP and builtin Procedures — after stamping, against the locales read for that request. Its Schema-side rules are in [Schema](./schema.md#write-time-locale-gate).
+
+| Condition | Result |
+|---|---|
+| Non-localized Schema and `data.locale` is present. | `INPUT_VALIDATION_FAILED` |
+| Localized Schema and `data.locale` is missing or empty. | `INPUT_VALIDATION_FAILED`, skipped for partial draft saves; publish re-checks. |
+| Localized Schema and `data.locale` is not in the site locales. | `INPUT_VALIDATION_FAILED` with the enabled locales as `candidates` |
+| The site locale list is empty. | Membership is not checked. |
+
+Media checks run per upload. `create_media_upload` and `commit_media_upload` are registered only when the runtime has a `mediaStorage` port bound **and** at least one purpose is declared; without both, the tools do not appear in `tools/list` at all.
+
+| Condition | Diagnostic |
+|---|---|
+| `purpose` is not one of the declared slugs. The declared set is returned in `expected`. | `MEDIA_PURPOSE_REJECTED` |
+| The variants manifest does not cover every required mime for the purpose. | `MEDIA_VARIANTS_INCOMPLETE` |
+| A variant's declared `byteSize` exceeds its mime's `maxBytes`. | `MEDIA_VARIANT_SIZE_EXCEEDED` |
+| A single upload exceeds its cap. | `MEDIA_SIZE_EXCEEDED` |
+| A modern format is larger than its fallback, which means the uploader skipped optimization. | `MEDIA_VARIANTS_SUSPICIOUS_SIZE` |
+
+The Cloudflare recipe for binding R2 is in [Media on R2](../cloudflare/media-r2.md).
+
+## Example
+
+```ts
+import { createMantleWorker } from "@aotter/mantle/cloudflare";
+import { plan } from "../.mantle/generated/mantle.js";
+import { handlers } from "./handlers.js";
+
+export default createMantleWorker({
+  plan,
+  handlers,
+  siteDefaults: {
+    locales: ["en", "zh-TW"],
+    brand: "Northwind",
+    title: "Northwind Supply",
+    description: "Industrial parts, shipped the same day.",
+    origin: "https://northwind.example.com",
+    icons: [
+      { src: "/site-icon.svg", mimeType: "image/svg+xml", sizes: ["any"] },
+      { src: "/site-icon.png", mimeType: "image/png", sizes: ["64x64"] },
+    ],
+    ga4MeasurementId: "G-XXXXXXXXXX",
+    media: {
+      purposes: [
+        {
+          name: "product-cover",
+          required: ["image/jpg,image/png", "webp", "avif"],
+          maxBytes: {
+            "image/jpeg": 5_000_000,
+            "image/png": 5_000_000,
+            "image/webp": 3_000_000,
+            "image/avif": 2_000_000,
+          },
+        },
+      ],
+    },
+  },
+});
+```
+
+`en` is canonical, so `/` redirects to `/en` and `zh-TW` is served at `/zh-tw`. Both icon files live in the project's `public/` directory. The one purpose declares three slots: the first accepts a JPEG or a PNG primary, the other two carry the modern alternates. See [Conventional Worker](../cloudflare/conventional-worker.md) for the surrounding bindings and [Public web](../cloudflare/public-web.md) for what the locale list turns on.
+
+## Source
+
+- [`packages/mantle-spec/src/domain/model/SiteConfig.ts`](../../../packages/mantle-spec/src/domain/model/SiteConfig.ts)
+- [`packages/mantle-spec/src/domain/model/MediaMimeAccept.ts`](../../../packages/mantle-spec/src/domain/model/MediaMimeAccept.ts)
+- [`packages/mantle-spec/src/domain/service/SiteDefaultsValidator.ts`](../../../packages/mantle-spec/src/domain/service/SiteDefaultsValidator.ts)
+- [`packages/mantle-spec/src/domain/service/LocaleCanonicalizer.ts`](../../../packages/mantle-spec/src/domain/service/LocaleCanonicalizer.ts)
+- [`packages/mantle-spec/src/domain/service/CrossSchemaChecker.ts`](../../../packages/mantle-spec/src/domain/service/CrossSchemaChecker.ts)
+- [`packages/mantle-runtime/src/infrastructure/persistence/DatabaseSiteConfigRepository.ts`](../../../packages/mantle-runtime/src/infrastructure/persistence/DatabaseSiteConfigRepository.ts)
+- [`packages/mantle-runtime/src/usecase/boot/ValidateBootUseCase.ts`](../../../packages/mantle-runtime/src/usecase/boot/ValidateBootUseCase.ts)
+- [`packages/mantle-runtime/src/usecase/media/diagnostics.ts`](../../../packages/mantle-runtime/src/usecase/media/diagnostics.ts)
+- [`packages/mantle-runtime/src/domain/service/io/EntryWriteGuard.ts`](../../../packages/mantle-runtime/src/domain/service/io/EntryWriteGuard.ts)
+- [`packages/mantle-runtime/src/infrastructure/mcp/McpToolCatalog.ts`](../../../packages/mantle-runtime/src/infrastructure/mcp/McpToolCatalog.ts)
+- [`packages/adapters/cloudflare/src/worker/createMantleWorker.ts`](../../../packages/adapters/cloudflare/src/worker/createMantleWorker.ts)
+- [`docs/media-uploads.md`](../../../docs/media-uploads.md)