@aotter/mantle 0.1.4 → 0.2.0-alpha.1

package/docs/handbook/reference/schema.md

@@ -1,260 +1,201 @@
 ---
-description: Schema field reference — JSON Schema subset, extension keywords, uiSchema, indexes, searchable fields, translates and lifecycle rules.
+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 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 of data fields and native entry columns. 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 are valid in View `fields`, `filter`, `orderBy` and `uiSchema.list.columns`, and `indexes` may include them (`uniqueIndexes` may not). `uiSchema.list.primaryField` is the entry title and must be a declared data property. A data property may not reuse one of these names: validate fails closed with `INVALID_MANIFEST_ENVELOPE` at `/spec/schema/properties/<name>`, because SQLite-family and IndexedDB storage would otherwise resolve the name differently and an index declared today could change meaning when a same-named property is added later. Use a domain name instead (`submittedAt`, `orderStatus`, `submittedBy`); the native column is still there and still readable (ADR-0025). `locale` is a reserved data field: only a localized Schema may declare it, and the runtime requires it on writes to a localized Schema. 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
+apiVersion: cms.mantle.aotter.net/v2
 kind: Schema
-metadata:
-  name: product-translations
+metadata: { name: orders }
 spec:
-  title: Product translations
-  localized: true
-  translates: { parent: products, on: sku }
-  schema:
+  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
+  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
     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]]
+    required: [owner, orderNumber, qty, orderStatus]
+    properties: { … }
 ```
 
-`locale` is declared but not listed in `required`; the write-time gate enforces presence.
+Unknown keys are refused. A Schema compiles to one table named after
+`metadata.name`.
 
-| 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` |
+## `schema`
 
-## JSON Schema subset
+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.
 
-Authors write JSON Schema; the runtime validates with zod via `z.fromJSONSchema`. The parser accepts a bounded subset so every manifest converts.
+| 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` |
 
-| 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 |
+### Reserved entry columns
 
-| Rejected keywords (`JSON_SCHEMA_UNSUPPORTED`) |
-|---|
-| `anyOf`, `allOf`, `not`, `if`, `then`, `else`, `$anchor`, `$dynamicAnchor`, `$dynamicRef`, `definitions`, `patternProperties`, `prefixItems`, `contains`, `dependentSchemas`, `propertyNames`, `unevaluatedProperties` |
+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.
 
-Other standard keywords are not rejected by the parser, but only the recognized set is part of the documented contract.
+Property extensions:
 
-| Rule | Diagnostic |
+| Keyword | Meaning |
 |---|---|
-| 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 accepted spellings are normalized 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`
+| `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 |
 
-Marks a property as server-stamped. The value is a closed enum; anything else is `BIND_VALUE_NOT_IN_ENUM`.
+`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.
 
-| 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` |
+### JSON Schema limits
 
-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.
+These hold for every JSON Schema Mantle checks: a Schema's `schema`, and View
+and Procedure inputs and outputs.
 
-### `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 |
+| Limit | Diagnostic |
 |---|---|
-| `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`).
+| 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).
 
-### Root `readOnly: true`
+## Indexes
 
-`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.
+- `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.
 
-## `uiSchema`
+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)).
 
-Closed Admin-only roots: `fields`, `list`, `nav`. Nested keys are closed too. Unknown roots or nested keys are `SCHEMA_UI_INVALID`.
+## `checks`
 
-| 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 or native entry columns, 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. |
+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:
 
 ```yaml
-uiSchema:
-  list:
-    primaryField: name
-    columns: [status]
-  nav:
-    standalone: true
-    parentField: organizationId
+checks: ["stock >= 0", "partySize IS NULL OR partySize BETWEEN 1 AND 20"]
 ```
 
-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/cf-primitives-commerce-inventory.md).
+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>`.
 
-## Indexes
+## `searchableFields`
 
-`uniqueIndexes` and `indexes` are arrays of ordered field tuples. Shape errors are `INVALID_MANIFEST_ENVELOPE`; semantic errors are `SCHEMA_INDEX_INVALID` unless noted. Each index is an array of field names, even when it has one field; a bare string is rejected.
+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.
 
-| 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` |
-| `uniqueIndexes` fields are data properties. `indexes` fields may also be the native columns `id`, `status`, `version`, `createdAt`, `updatedAt`, `authorId`, which map to their `_mantle_*` columns. | `SCHEMA_INDEX_INVALID` |
-| Data 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.
-
-A public View over a `publishing` Schema is compiled with `status = published`
-whether or not the manifest writes it ([View surfaces](./view.md#surfaces)), so
-its hot path always starts with an equality on `status`. Lead the index with
-it, then the ordered field: `indexes: [[status, publishedAt]]`. A bare
-`[[publishedAt]]` does not serve that query on production SQLite (no planner
-statistics), which sorts every published row in a temporary B-tree instead
-(#962). Declare the index the query needs; Mantle does not derive one (ADR-0025).
-Unique indexes are also checked before every write; a conflicting row is
-`CONFLICT`. After the first deployment, adding, removing, reordering, or changing
-any `uniqueIndexes` tuple is destructive and requires rebuilding the instance
-and moving required data manually. Automatic deployment rejects the change.
-
-## `searchableFields`
+## `scope`
 
-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`.
+```yaml
+scope: { owner: auth.uid() }
+indexes: [[owner]]
+```
 
-## Lifecycle
+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).
 
-`publishing` is the default state machine.
+## `ttl`
 
-| From | To |
-|---|---|
-| `draft` | `published`, `archived` |
-| `published` | `archived`, `draft` |
-| `archived` | `draft` |
+`{ 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.
 
-`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.
+## `localized` and `translates`
 
-Deleting a `published` entry of a publishing Schema is `CONFLICT` (unpublish first). Operational entries can be deleted in any status.
+`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.
 
-### Write-time locale gate
+## `uiSchema`
 
-Every authoring path (Admin, Staff MCP, builtin Procedures) runs the same guard after stamping, per request, reading the current site locales.
+Admin presentation only; it never changes validation or MCP.
 
-| Condition | Result |
+| Key | Values |
 |---|---|
-| 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)
+| `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 |
+
+Other keys are refused (`SCHEMA_UI_INVALID`).
+
+## 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).