@aotter/mantle 0.0.11-alpha.73 → 0.1.0-alpha.10

package/docs/design-atoms.md

@@ -3,14 +3,7 @@
 > If you're an AI working in a project that consumes `@aotter/mantle-*`,
 > read this first. It explains the entire surface area in one page.
 >
-> **Status**: v0.1 grammar lock. Atoms are shipped; rich sub-spec
-> grammar (policies, recursive views, temporal predicates, quotas,
-> projection triggers, cron/queue sources, and extended lifecycle hooks) is
-> reserved as **DRAFT** — see "Future grammar" appendix. Editorial
-> lifecycle is the one shipped grammar key whose runtime is **deferred
-> to v0.1.x**: parser and boot accept the shape, while
-> `request_publish` rejects it with `LIFECYCLE_NOT_IN_V010` until the approval
-> queue lands. Do not use editorial for a v0.1 publishing workflow.
+> **Status**: v0.1 shipped grammar. Unknown keys and enum values are rejected.
 >
 > **This is the reference manual** — what the system is. For *why* it
 > ended up this shape (alternatives considered, trade-offs accepted),
@@ -32,8 +25,8 @@ primitives Postgres has shipped for 30 years.
 |---|---|---|---|
 | **`Schema`** | `CREATE TABLE` | no (manipulated via View / Procedure) | no |
 | **`View`** | `CREATE VIEW` | **yes** (auto-mounted on its declared public/staff REST and MCP surface; see ADR-0012) | no |
-| **`Procedure`** | `CREATE FUNCTION ... LANGUAGE plpgsql` | **no** (transport-agnostic; needs a `Trigger` to bind it) | **yes — handler ref to consumer's TS file** |
-| **`Trigger`** | `CREATE TRIGGER` + `pg_cron` + PostgREST route + `LISTEN/NOTIFY` | yes (the binding atom — turns Procedures into HTTP endpoints, cron jobs, MCP tools, lifecycle hooks) | no |
+| **`Procedure`** | `CREATE FUNCTION ... LANGUAGE plpgsql` | **no** (transport-agnostic; needs a `Trigger` to bind it) | **yes — handler ref to the consumer's registry** |
+| **`Trigger`** | `CREATE TRIGGER` + route/tool binding | yes (the binding atom — turns Procedures into HTTP endpoints, MCP tools, and lifecycle hooks) | no |
 
 The **read/write asymmetry is by design** and matches HTTP safe-vs-unsafe
 semantics. Reads (`View`) are idempotent and cacheable; the SDK
@@ -52,16 +45,14 @@ these four plus your own TypeScript.
 apiVersion: cms.mantle.aotter.net/v1
 kind: Schema | View | Procedure | Trigger
 metadata:
-  name: posts                # required, kebab-case, unique within deployment
-  labels: { ... }            # optional, free-form
+  name: posts                # required, non-empty, unique within its kind
 spec:
   ...                        # kind-specific
 ```
 
-There is **no `namespace` field**. Resource names are unique within the
-deployment. K8s-style namespaces are a "premature scale" abstraction for
-our scope; SaaS multi-tenancy belongs in the consumer's app layer with a
-`tenant_id` column gated by RBAC, not in the SDK metadata layer.
+There is **no manifest `namespace` field**. Resource names are unique within
+their kind, so a Schema and View may share a name. SaaS multi-tenancy belongs
+in the consumer's app layer, not in manifest metadata.
 
 ### Multi-doc YAML — keeping file count down
 
@@ -73,7 +64,7 @@ A logical feature commonly bundles a Procedure + a Trigger (and often a
 Schema and a View). Put related atoms in one file separated by `---`:
 
 ```yaml
-# manifests/contact.yaml
+# manifests/contact.yml
 apiVersion: cms.mantle.aotter.net/v1
 kind: Procedure
 metadata: { name: send-contact-message }
@@ -93,8 +84,9 @@ spec:
   target: { procedure: send-contact-message }
 ```
 
-One file, two atoms. File count stays low; conceptual atom separation
-stays honest.
+Use one file or split features across files. Mantle reads every immediate
+`.yaml` and `.yml` file in `./manifests` by default; `---` separates multiple
+documents in one file.
 
 ## What each atom is for (v0.1 minimum essential grammar)
 
@@ -112,7 +104,7 @@ metadata: { name: posts }
 spec:
   title: Posts                    # required: human-readable label for the admin UI
   localized: true                 # opt-in: row carries data.locale (ADR-0010)
-  lifecycle: simple               # default; 'none' is operational, 'editorial' is reserved
+  lifecycle: publishing               # default; use 'operational' for live records
   schema:
     $schema: https://json-schema.org/draft/2020-12/schema
     type: object
@@ -126,7 +118,8 @@ spec:
                                    # against localized Schemas.
       content:  { type: string }
       authorId: { type: string, format: uuid, x-mantle-bind: ctx.user }
-      createdAt: { type: string, format: date-time, x-mantle-bind: now }
+      createdAt: { type: integer, x-mcp-hint: timestamp-ms, x-mantle-bind: now }
+  searchableFields: [title, slug]   # id is always searched
   uniqueIndexes: [[slug, locale]]
   indexes: [[locale, title]]        # ordered, non-unique hot path
 ```
@@ -135,6 +128,33 @@ spec:
 in the user's primary language (the install-time chosen locale); the
 SPA shows this everywhere instead of `metadata.name`.
 
+Schema titles and optional descriptions accept either a string or a locale
+map such as `{ en: Products, "zh-TW": 商品 }`. Procedure titles and
+descriptions and View titles use the same shape; all are optional.
+
+**`spec.searchableFields`** — optional allowlist of top-level string
+properties used by Admin and Staff MCP substring search. Entry id is always
+searchable. This is separate from `indexes`; ordinary B-tree indexes do not
+accelerate leading-wildcard substring search.
+
+**`spec.uiSchema.list.filterField`** — optional Admin-only primary filter for
+an operational collection. The field must declare a non-empty string `enum`
+and be the first field of an `indexes` or `uniqueIndexes` tuple. Admin reuses
+the enum for sidebar links and list tabs; Staff MCP uses declared Views for
+richer query capabilities instead of reading UI configuration.
+
+Operational list data is also explicit: `uiSchema.list.primaryField` names the
+linked leading value and `uiSchema.list.columns` names the remaining scalar
+columns. Without them Admin shows only platform metadata. Form-only choices use
+`uiSchema.fields.<field>.widget: textarea`; rich content remains declared with
+`x-mcp-hint: markdown|html|richtext`. Neither setting changes runtime or MCP
+input validation.
+
+A staff-operable Procedure may declare `uiSchema.collectionAction: orders` to
+appear as an action in that collection's Admin header. The target must be an
+existing Schema. This binding is Admin-only; the Procedure input, authorization,
+runtime handler, and MCP exposure remain unchanged.
+
 **`spec.localized: bool`** (default `false`, ADR-0010) — opt-in per
 Schema. Localized Schemas store locale in `data.locale`; non-localized
 Schemas reject `data.locale` writes. Site config must declare the set
@@ -144,25 +164,22 @@ validates manifest shape.
 
 **`spec.translates: { parent, on }`** (ADR-0010) — declares this
 Schema as the translation companion to a non-localized parent, joined
-on the named field (typically `slug`). Implies `localized: true`. The
+on the named field (typically `slug`). Requires an explicit
+`localized: true`. The
 admin UI surfaces the child only as locale tabs in the parent's editor.
 
+Use a standalone localized Schema only when each locale row is an
+independent record. When several locale rows are versions of one entity,
+declare a non-localized parent plus a localized `translates` child; that
+relationship is what powers translation grouping and completeness in Admin.
+
 #### Lifecycle
 
-**`spec.lifecycle: 'simple' | 'editorial' | 'none'`** — controls the
+**`spec.lifecycle: 'publishing' | 'operational'`** — controls the
 entry's state machine.
 
-- `simple` (default) — `draft → published → archived`. No approval
-  queue. **This is the only content-workflow mode whose runtime ships
-  in v0.1.0.**
-- `editorial` — the six-state machine with an approval queue
-  (`draft → review → approved → scheduled → published → archived`,
-  with `published` returnable to `draft` for republish). The grammar and
-  state-machine vocabulary are reserved for forward compatibility, but the
-  approval/request-publish runtime is on the v0.1.x roadmap. In v0.1,
-  `request_publish` rejects with `LIFECYCLE_NOT_IN_V010`; do not declare
-  editorial for a current publishing workflow.
-- `none` — **operational records**, not authored content: orders,
+- `publishing` (default) — `draft → published → archived`. No approval queue.
+- `operational` — records that are not authored content: orders,
   inventory snapshots, grant/audit rows — anything written by
   Procedures as a side effect rather than drafted by a person. No
   content workflow applies: entries are live (`published`) the moment
@@ -175,8 +192,15 @@ entry's state machine.
   `update_record_<schema>` for these Schemas instead of draft tools.
 
 The modes are **per-Schema and mix freely** within a site. There is no
-site-wide lifecycle setting; one Schema can be `simple` while another
-is `editorial` and a third is `none`.
+site-wide lifecycle setting; one Schema can be `publishing` while another
+is `operational`.
+
+**Root `schema.readOnly: true`** — standard JSON Schema annotation for a
+Procedure-managed collection. Admin and Staff MCP keep list/detail access and
+declared row Procedures, but suppress and reject generic create, update,
+status-change, and delete operations. Trusted Procedure handlers may still use
+the runtime write use cases to maintain the projection. Put this on operational
+mirrors and audit rows whose authority lives outside generic authoring.
 
 **Property-level extensions** (JSON Schema vendor keywords, all optional):
 
@@ -188,9 +212,9 @@ extensions. Three are part of `cms.mantle.aotter.net/v1`:
 > See ADR-0002 for rationale — why this is a closed enum and not an
 > open expression language.
 
-Marks a property as **server-controlled**. The SDK fills the value at
-write time; the caller MUST NOT supply it (callers who try to set a
-bound field get `INPUT_VALIDATION_FAILED`). Eliminates the entire
+Marks a property as **server-controlled**. On create, the SDK overwrites any
+caller value with the bound value; updates preserve the existing stamp. This
+eliminates the entire
 class of handler-side `userId: ctx.user.id` boilerplate, and gives
 the dispatcher an authoritative "who/when" tag without trusting the
 wire.
@@ -201,20 +225,12 @@ wire.
 |---|---|---|
 | `ctx.user` | UUID of the signed-in end-user (from session cookie); `null` if anonymous | row ownership: `authorId`, `submittedBy`, `creatorId` |
 | `ctx.staff` | UUID of the staff member acting (when a staff session is active); `null` for end-user-only paths | audit trail: `approvedBy`, `moderatedBy`, `grantedBy` |
-| `now` | Server timestamp at write (ISO-8601 string with timezone) | `createdAt`, `submittedAt`, `grantedAt` |
+| `now` | Server timestamp at write (Unix epoch milliseconds) | `createdAt`, `submittedAt`, `grantedAt` |
 
 **v0.1 stamping behavior**:
-- Stamped on `INSERT` only. Update-stamping (e.g. `updatedAt: now` that
-  re-stamps on every UPDATE) is DRAFT — it lands when first use case
-  surfaces.
-- Caller-supplied value: rejected at input validation. The Procedure's
-  effective input schema strips bound fields before checking caller
-  input, so callers can't accidentally send them.
+- Stamped on `INSERT` only.
+- Caller-supplied create value: ignored and replaced by the server stamp.
 - Visible in View output: yes, as ordinary columns. No special masking.
-- Used by `requires.auth.owns:` predicate (DRAFT): the predicate
-  compares a row's `x-mantle-bind: ctx.user` field to the current
-  `:ctx.user` to verify ownership without configuring per-Schema
-  owner-column names.
 
 **Why a closed enum** (highest-leverage discipline in the spec): bind
 values are server-controlled identity + time facts. If we accepted
@@ -227,9 +243,9 @@ named bounds the semantic surface forever.
 properties:
   title:     { type: string, minLength: 1, maxLength: 200 }
   authorId:  { type: string, format: uuid, x-mantle-bind: ctx.user }
-  createdAt: { type: string, format: date-time, x-mantle-bind: now }
+  createdAt: { type: integer, x-mcp-hint: timestamp-ms, x-mantle-bind: now }
   # caller sends only: { title }
-  # SDK stamps: { title, authorId: <session UUID>, createdAt: <now ISO> }
+  # SDK stamps: { title, authorId: <session UUID>, createdAt: <epoch ms> }
 ```
 
 #### `x-mantle-ref: <other-schema-name>` — cross-Schema reference
@@ -237,7 +253,17 @@ properties:
 Informational FK marker on a string-typed field that holds an ID
 referencing rows in another Schema. Not enforced in v0.1 (the SDK
 passes it through; no foreign-key constraint, no cascade, no orphan
-detection). Future grammar may upgrade it to enforced.
+detection). The admin uses declared refs to show related rows and to nest
+required child collections; it does not infer relationships from field names.
+Declare a single-field `indexes` entry for the ref field (for example,
+`indexes: [[authorId]]`) when reverse lookups must stay bounded. Mantle adds
+the native entry-order columns to that access path.
+
+On a Procedure input property, the Admin also uses `x-mantle-ref` to expose
+that Procedure in the referenced collection row's three-dot menu. It locks
+the referenced value to the selected row and infers the remaining form from
+the Procedure input schema. The value comes from a same-named Schema property,
+then a lone single-field unique index, and finally the entry `id`.
 
 **Example**:
 ```yaml
@@ -258,7 +284,9 @@ Descriptive hint for AI agents and admin UI widgets. The string is
 accepted as free-form for forward compatibility, but conventional
 values (`markdown`, `richtext`, `code`, `media`, `media-image`,
 `media-video`, `media-file`) tell consumers how to render or generate
-the field's value.
+the field's value. `idempotency-key` asks the Admin to generate and hide a
+stable UUID for one form invocation; other callers must generate one and reuse
+it when retrying the same operation.
 
 **Examples** (from the publication/blog starter manifests):
 ```yaml
@@ -281,21 +309,16 @@ MCP tool schemas preserve the hint for agents. Admin surfaces expose
 media-shaped fields but first-party upload hosting is optional and not
 part of first-run provisioning.
 
----
-
-Anything beyond these three (policies, computed columns, RBAC grants,
-owner declarations, `x-mantle-bind` enum extension) is **DRAFT** — see
-appendix.
-
 **Postgres analogue**: `CREATE TABLE posts (id UUID PRIMARY KEY, ...,
 UNIQUE (slug, locale));`
 
 ### 2. `View` — the read surface (auto-exposed by surface)
 
-A named, declarative read over Schemas. No Trigger is required. A View with
-no `spec.surface` (or `surface: public`) mounts at
-`GET /api/views/<name>` and becomes `query_view_<name>` on `/mcp`.
-`surface: staff` instead mounts at `GET /admin/api/views/<name>` behind the
+A named, read-only SQL query over Schemas. Every Schema is available to SQL as
+a logical table named after `Schema.metadata.name`; storage internals stay
+hidden. No Trigger is required. `surface` is required: `surface: public` mounts
+at `GET /api/views/<name>` and becomes `query_view_<name>` on `/mcp`, while
+`surface: staff` mounts at `GET /admin/api/views/<name>` behind the
 staff gate and appears only on `/mcp/staff`. See ADR-0012 for the full design
 rationale.
 
@@ -304,34 +327,35 @@ apiVersion: cms.mantle.aotter.net/v1
 kind: View
 metadata: { name: recent-published }
 spec:
-  from: posts
-  fields: [id, title, slug, locale, publishedAt, updatedAt]
-  filter:
-    eq: { field: status, value: published }
-  orderBy:
-    - { field: updatedAt, direction: desc }
+  surface: public
+  sql: |
+    SELECT id, title, slug, locale, publishedAt, updatedAt
+    FROM posts
+    WHERE status = 'published'
+    ORDER BY updatedAt DESC
   limit: 20
 ```
 
 **Param-driven Views** declare `spec.params` (a JSON Schema with
-`type: object`); filter values reference them via the
-`{ $param: <name> }` sentinel:
+`type: object`); SQL references required properties as named `:params`. The
+runtime validates and binds them; it never interpolates caller values:
 
 ```yaml
 apiVersion: cms.mantle.aotter.net/v1
 kind: View
 metadata: { name: posts-by-locale }
 spec:
-  from: post-translations
+  surface: public
+  sql: |
+    SELECT id, slug, locale, title, updatedAt
+    FROM post-translations
+    WHERE status = 'published' AND locale = :locale
+    ORDER BY slug ASC
   params:
     type: object
     properties:
       locale: { type: string }
     required: [locale]
-  filter:
-    and:
-      - eq: { field: status, value: published }
-      - eq: { field: locale, value: { $param: locale } }
   limit: 100
 ```
 
@@ -341,6 +365,22 @@ names — `page` / `show` / `cursor` — must NOT appear in
 `spec.params.properties` (the parser rejects with
 `VIEW_PARAMS_RESERVED_NAME`).
 
+Staff report lists may opt into the Admin's standard columns, substring
+search, and exact filters without changing the public REST/MCP contract:
+
+```yaml
+uiSchema:
+  list:
+    columns: [orderNumber, customerName, orderStatus]
+    searchFields: [orderNumber, customerName, customerEmail]
+    filterFields: [orderStatus]
+```
+
+These names are SQL output aliases. The Admin applies search and filters
+before pagination and carries them into
+`GET /admin/api/views/<name>/export`; the CSV contains all matching rows,
+not only the visible page.
+
 Views may declare the same `requires.auth.all` predicates and optional
 `requires.guard.procedure` as Procedures. Static auth runs before parameter
 validation; the guard receives validated params and authorizes the whole
@@ -356,13 +396,10 @@ Response envelope:
 `hasMore` is the lazy form: `rows.length === show` ⇒ `true`. No COUNT
 query, no `LIMIT n+1` probe.
 
-**v0.1 filter AST**: comparison operators (`eq`, `gt`, `gte`, `lt`,
-`lte`) plus `and` / `or`. Comparison `value` may be a literal or a
-`{ $param: <name> }` sentinel. v0.1.0 enforces required-only param refs;
-optional-with-skip semantics are reserved for v0.1.x. Field-to-field
-comparisons are not supported yet; compare a field to a literal or
-param. Anything else (`contains`, `recursive`, `gatedBy`,
-`join.aggregate`, `policies.skip`) is DRAFT.
+The previous `from` / `fields` / `filter` / `orderBy` declarative form remains
+accepted for existing manifests. New Views should use one `SELECT`; writes,
+multiple statements, semicolons, and combining SQL with the legacy clauses are
+rejected.
 
 **Postgres analogue**: `CREATE VIEW recent_published AS SELECT ...
 FROM posts WHERE status = 'published' ORDER BY updated_at DESC LIMIT
@@ -378,8 +415,8 @@ provides the handler function with auto-generated TS types.
 `Procedure` is **transport-agnostic and not directly exposed**. It does
 not contain HTTP paths, methods, or MCP tool names. To call a Procedure
 from outside the SDK runtime, declare a `Trigger` whose `target` points
-at it. The same Procedure can be bound by multiple Triggers (HTTP +
-cron + MCP + lifecycle, all sharing one handler).
+at it. The same Procedure can be bound by multiple Triggers (HTTP + MCP +
+lifecycle, all sharing one handler).
 
 ```yaml
 apiVersion: cms.mantle.aotter.net/v1
@@ -421,9 +458,6 @@ export const handlers = {
 - `ctx.auth.scope: <scope>` — verified credential carries the exact opaque,
   consumer-owned scope; repeat to require multiple scopes
 
-Anything beyond this (`any:`, `owns:`, `withinMinutes:`, `contains:`,
-`requires.window`, `requires.quota`, `errors`, `retry`) is DRAFT.
-
 Both Procedures and Views may add one dynamic guard beside `auth`:
 
 ```yaml
@@ -480,7 +514,7 @@ spec:
 ```
 
 The same Procedure can have multiple Triggers — that's how it becomes
-"an HTTP endpoint AND a cron job AND an MCP tool" without duplicating
+an HTTP endpoint and an MCP tool without duplicating
 handler logic. Each transport is one Trigger; the Procedure body is
 shared.
 
@@ -491,17 +525,14 @@ tool on `surface: public | staff`), or `lifecycle` (entry-writer hook). For `lif
 Lifecycle hooks are wired through `LifecycleHookingEntryRepository`, so
 MCP, admin, and builtin write paths share the same hook behavior.
 
-- `cron` / `queue` are **DRAFT (v0.2+)** — speculative, gated by
-  concrete consumer demand. Same appendix § "DRAFT (v0.2+)."
-
 The state-machine "lifecycle" from the Schema atom
-(`Schema.spec.lifecycle: simple | editorial`) is a separate domain
+(`Schema.spec.lifecycle: publishing | operational`) is a separate domain
 that shares the word. The Schema setting governs which states an
 entry can be in; shipped lifecycle Triggers govern what fires around
 mutations.
 
 **Postgres analogue**: `CREATE TRIGGER ... AFTER INSERT ON posts
-EXECUTE FUNCTION ...` (lifecycle); `pg_cron` extension (cron); plus
+EXECUTE FUNCTION ...` (lifecycle), plus
 `CREATE FUNCTION` exposed via PostgREST routes (http) — Postgres has
 had all of these via extensions for years, just split across multiple
 mechanisms. We unify them under one atom.
@@ -553,9 +584,8 @@ That split is intentional and load-bearing.
   draft-2020-12 JSON Schema documents. This is what AI authors and
   human authors write, what the admin UI feeds JSON Forms, and what
   the OpenAPI emitter relays unchanged.
-- **Runtime engine** = zod (v3). The `@aotter/mantle-spec`
-  package ships a JSON-Schema → zod converter
-  (`src/json-schema-zod.ts`); the runtime calls the converted zod
+- **Runtime engine** = zod 4. The `@aotter/mantle-spec`
+  package ships a JSON-Schema → zod converter; the runtime calls the converted zod
   schema on every Procedure invocation, View parameter parse, and
   manifest boot check.
 
@@ -579,7 +609,7 @@ different constraints.
 | `UNAUTHENTICATED` | `401` | no active session (admin API: missing/expired session cookie) |
 | `AUTH_DENIED` | `403` | `requires.auth` predicate evaluated false (or admin: caller lacks required staff role) |
 | `ENTITLEMENT_REQUIRED` | `402` | consumer guard denies current payment/membership/transaction entitlement |
-| `NOT_FOUND` | `404` | resource not found — admin: approval id; runtime: View name at `/api/views/<name>` |
+| `NOT_FOUND` | `404` | resource not found — entry id or View name at `/api/views/<name>` |
 | `HANDLER_NOT_REGISTERED` | `500` | `handler.ref` key not registered at boot |
 | `DISPATCHER_NOT_BUILT` | `501` | runtime feature not implemented in this SDK build |
 | `INTERNAL_ERROR` | `500` | uncaught handler exception |
@@ -590,10 +620,7 @@ may also fire in earlier loops (e.g. `HANDLER_NOT_REGISTERED`
 fires at boot — `phase: "boot"` — and that's where it should be
 caught; the runtime occurrence is defense-in-depth).
 
-Additional runtime codes activate as future grammar surfaces (e.g.
-`QUOTA_EXCEEDED → 429` arrives with `requires.quota`).
-
-## RBAC — what v0.1 ships, what's DRAFT
+## RBAC
 
 v0.1 auth gates use `requires.auth.all` with `ctx.user`,
 `ctx.staff: [<roles>]`, `ctx.auth`, and `ctx.auth.scope` predicates on
@@ -601,16 +628,6 @@ Procedures and Views. This covers staff-only, logged-in-only,
 credential-protected, and delegated-scope targets. One Procedure-backed guard
 handles mutable consumer business state without widening the static grammar.
 
-**Not yet shipped** (DRAFT):
-- Row-level read visibility (private posts, friend-only audiences)
-- Field-level write policies (this user can update body but not
-  parent_id)
-- Cross-Schema policy inheritance (gatedBy)
-- Quotas, edit-windows, rate limits
-
-These all live as `Schema.spec.policies.*` and `Procedure.spec.requires.*`
-sub-specs in the DRAFT spec. See "Future grammar" appendix.
-
 ## How to think when extending this CMS
 
 1. **What entities does the feature need?** → `Schema` for each.
@@ -619,13 +636,11 @@ sub-specs in the DRAFT spec. See "Future grammar" appendix.
    external read endpoints).
 3. **What operations?** → `Procedure` for each. One Procedure = one
    typed function call. Compose in handler code, not in YAML.
-4. **What invokes them?** → `Trigger` per source. Multiple Triggers
-   can target the same Procedure (HTTP + MCP + cron, all on one
-   handler).
+4. **What invokes them?** → `Trigger` per declared HTTP, MCP, or lifecycle
+   source. Site-owned events can call the same Procedure binding directly.
 5. **Who's allowed?** → `Procedure/View.spec.requires.auth` for static
    identity/scope; optional `requires.guard.procedure` for one live,
-   consumer-owned business check. Row-level and field-level rules remain
-   future grammar.
+   consumer-owned business check.
 
 If you find yourself wanting a 5th kind, **stop**. Sketch the same
 thing as a composition of the four; almost always it works.
@@ -643,181 +658,20 @@ thing as a composition of the four; almost always it works.
 > fold into JSON Schema inside `Schema` rather than becoming new
 > kinds.
 
-Postgres exposes ~25 object kinds total; an application developer
-typically only writes 4–6 of them. The rest are engine internals that
-Cloudflare D1 / KV abstract away.
-
-## Storage backend — D1 today, Postgres-via-Hyperdrive tomorrow
-
-> See the `mantle-cloudflare` README for rationale — why D1 for
-> v0.1 (no-CC OSS onboarding, platform-native), and the documented
-> PG path.
-
-### How `Schema` data is stored on D1 today
-
-All collections share one `entries` table (defined by the
-Cloudflare adapter's storage migrations in
-`@aotter/mantle-cloudflare`):
-
-```sql
-CREATE TABLE entries (
-  id          TEXT PRIMARY KEY,
-  collection  TEXT NOT NULL,        -- discriminator: 'posts', 'comments', ...
-  status      TEXT NOT NULL,        -- 'draft' / 'published' / ...
-  version     INTEGER NOT NULL,
-  data        TEXT NOT NULL,        -- JSON blob: every Schema property (incl. locale, per ADR-0010)
-  created_at  INTEGER NOT NULL,
-  updated_at  INTEGER NOT NULL,
-  author_id   TEXT REFERENCES users(id)
-);
-```
+Postgres exposes ~25 object kinds total; an application developer typically
+only writes 4–6 of them. The rest belong behind the selected storage adapter.
 
-Reserved metadata are native columns; **everything in your Schema's
-`spec.schema.properties` lives inside the `data` JSON blob**. Locale
-on localized Schemas lives at `data.locale` (per ADR-0010); for
-indexing it surfaces as a JSON-extracted virtual generated column
-(`json_extract(data, '$.locale')`) with a partial unique index, not as
-a top-level column.
-
-`uniqueIndexes` and ordered, non-unique `indexes` declarations compile
-into affinity-correct virtual generated columns plus partial B-tree
-indexes via the spec engine's DDL emitter (`@aotter/mantle-spec`).
-Different collections coexist on the same table without colliding
-because each generated-column expression is gated by `WHEN collection
-= '<name>'`. See [Schema indexes on D1](schema-indexes.md) for the
-grammar, leftmost-prefix rules, SQL helper, and query-plan examples.
-
-### What works well on D1
-
-- D1's SQLite has the **JSON1 extension built in**: `json_extract`,
-  `json_each`, `json_object`, `json_array`, `json_set`, `json_valid`,
-  plus `->` / `->>` operators.
-- Reserved-column queries (`status = 'published'`, `ORDER BY
-  updated_at`) use native indexes — fast.
-- `uniqueIndexes`- and `indexes`-declared paths use virtual columns +
-  partial indexes. Core-compiled Views and repository lookups reference
-  those columns instead of repeating `json_extract`.
-
-### Where D1's JSON support has limits (vs Postgres)
-
-| Concern | D1 / SQLite | Postgres |
-|---|---|---|
-| JSON storage | TEXT — re-parsed on every `json_extract` | JSONB — stored as compact binary; faster repeated extraction |
-| Index any JSON path | must declare each path explicitly via virtual column + index | GIN index on JSONB indexes all paths automatically |
-| Array containment | `EXISTS (SELECT 1 FROM json_each(...) WHERE value = ?)` — full scan unless indexed | `data @> ARRAY[x]` with GIN — native operator |
-| Path operators | `->`, `->>` only | `->`, `->>`, `#>`, `#>>`, `@>`, `?`, `?|`, `?&` |
-| `DEFAULT now()` | not at column level — SDK-stamped via `x-mantle-bind: now` | native column default |
-| Foreign key on JSON path | not supported on `VIRTUAL` columns; needs `STORED` (extra space) | not natively, but B-tree on expression OK |
-| Row-level security | none — SDK-side filter rewriting | native RLS policies |
-| Multi-statement transactions | session API serializes; not true ACID across statements | full ACID transactions |
-
-### Practical scale envelope on D1
-
-- **Blog-scale (< 10k entries / collection)**: today's design is
-  comfortable. Public render hits KV cache, not D1.
-- **Mid-scale (10k – 100k entries)**: declare measured list/filter
-  access paths with ordered `indexes`. Cross-collection JSON-path joins
-  may eventually gain `x-mantle-ref` auto-lift; that remains DRAFT.
-- **Hard D1 limits**: 1 MB max row size; 5,000 rows per query result;
-  single-writer per database (concurrent writes serialize).
-- **Cross-region read**: D1 is region-pinned; first hit from a
-  far region is ~100–200 ms cold replica. Public reads should hit
-  the SDK's KV render cache, not D1, so this rarely matters at the
-  CMS layer.
-
-### Scale-up path: D1 → Postgres via Cloudflare Hyperdrive
-
-Cloudflare does not run a first-party Postgres service. The supported
-path when D1 limits bind is **Cloudflare Hyperdrive** (a connection
-pooler + query-cache that lets a Worker connect to any external
-Postgres at near-edge latency):
-
-- **Neon** (serverless Postgres with scale-to-zero) — closest
-  ergonomic match; tightest CF integration.
-- **Supabase** (PG + auth + storage) — works out of the box.
-- **AWS RDS / Google Cloud SQL / Azure DB / self-hosted PG** — also
-  supported via Hyperdrive.
-
-When this path is taken (post-v0.1; not implemented yet), the
-**author-facing YAML stays unchanged**. The SDK's compile target swaps:
-
-| What changes (SDK runtime) | Author impact |
-|---|---|
-| `data TEXT` → `data JSONB` | none |
-| Virtual generated columns → optional (PG can use GIN) | author may stop declaring `indexes` if defaults suffice; the same YAML remains valid |
-| `json_each` → array operators (`@>`, `&&`) | none — predicates stay declarative |
-| SDK-stamped `now` → `DEFAULT now()` (optional) | none |
-| SDK-side policy rewriting → native RLS (optional) | none |
-| `Trigger.target.project` single-writer DO → real same-transaction trigger | atomicity guarantee strengthens; YAML grammar unchanged (the `atomicity:` declaration just stops needing the eventual-consistency caveat) |
-
-Migration shape: `entries` table dumped from D1, restored to PG. Stay
-single-table-with-discriminator (drop-in) or split into
-table-per-collection (more PG-idiomatic, longer migration). Both shapes
-remain valid `cms.mantle.aotter.net/v1` deployments.
-
-**v0.1 commitment**: D1 only via the Cloudflare adapter. Hyperdrive +
-PG path is documented as the upgrade route but not implemented. SDKs
-and starters target D1 exclusively. The Netlify adapter package
-(`@aotter/mantle-netlify`) is a README stub for v0.2; its
-existence is an engineering forcing function ensuring the runtime
-package stays portable across adapters.
-
-## Roadmap — what's not in v0.1.0
-
-> See [ADR-0001 §"Future grammar discipline"](adr/0001-four-atom-manifest-model.md#future-grammar-discipline-was-poc-adr-0005)
-> for the v0.1 minimum-vs-roadmap discipline, the promotion process,
-> and the YAGNI argument that gates speculative shipping.
-
-The atoms are locked at 4. Their **inner grammar** is intentionally
-narrow at v0.1.0 and grows in two tiers:
-
-1. **v0.1.0 shipped** — grammar parses and runtime behavior is wired
-   in the current rebuild.
-2. **v0.1.x committed** — on the patch-release roadmap. Spec is
-   documented; implementation lands within the v0.1 series. The unsupported
-   runtime path fails closed with a code naming the feature.
-3. **DRAFT (v0.2+)** — speculative, gated by concrete consumer
-   demand. Parser/static validation rejects with `DRAFT_KEY_USED`. May or may
-   not ship — depends on whether real use cases apply pressure.
-
-### v0.1.0 shipped
-
-#### `Trigger.source.kind: lifecycle` — bind a Procedure to a Schema event
+## Storage adapters
 
-Grammar lives in v0.1.0. Runtime is the
-`LifecycleHookingEntryRepository` decorator wrapping the entry-writer
-chokepoint so MCP / admin / builtin paths all fire the same hooks.
-Full shape lives further down.
+Manifests compile to semantic storage ports; they do not select a database.
+Use the shared SQLite adapter for SQLite-compatible hosts, or implement the
+same ports over PostgreSQL, MongoDB, or existing application repositories.
+See the [adapter guide](adapter-guide.md); SQLite index lowering is documented
+separately in [Schema indexes](schema-indexes.md).
 
-#### `Procedure.handler.kind: builtin` — SDK-supplied CRUD Procedure
+## Detailed shipped grammar
 
-Grammar lives in v0.1.0. Runtime is the
-`InvokeBuiltinUseCase` that dispatches `op: create | update | upsert
-| delete | archive` against the entry-writer chokepoint with `x-mantle-bind`
-stamping and `input ∩ Schema.properties` projection. Full shape lives
-further down.
-
-#### `Trigger.source.kind: mcp` and shared authorization
-
-An MCP Trigger binds a declared Procedure to either the public or staff MCP
-surface. Procedures/Views share `ctx.auth`/scope predicates and optional guard
-orchestration across REST and MCP. Staff role is loaded live for each protected
-call; staff Views remain absent and un-callable on public MCP.
-
-### Detailed shipped grammar and v0.1.x reservation
-
-> The `handler.kind: builtin` and `Trigger.source.kind: lifecycle`
-> sections below describe shipped v0.1.0 behavior. Only the
-> `Schema.spec.lifecycle: editorial` subsection remains v0.1.x-committed.
-
-#### `Schema.spec.lifecycle: editorial` runtime
-
-Grammar and boot already accept the key, but `request_publish` emits
-`LIFECYCLE_NOT_IN_V010` because the approval-queue runtime ships in v0.1.x.
-When that runtime lands, the same manifest can use the publish workflow without
-a grammar change.
-
-#### `handler.kind: builtin` — thin shortcut over the storage adapter for trivial CRUD-shaped Procedures
+### `handler.kind: builtin` — thin shortcut over the storage adapter for trivial CRUD-shaped Procedures
 
 Use when the body is "insert a row" / "update a row" / "delete a
 row"; reach for `ref` when there is real business logic. Shape:
@@ -834,11 +688,11 @@ spec:
 
 | op | Behavior |
 |---|---|
-| `create` | INSERT a new row. Project `input ∩ Schema.spec.schema.properties`; stamp `x-mantle-bind` fields; generated id; status is `draft`, or immediately `published` for `lifecycle: none`. |
+| `create` | INSERT a new row. Project `input ∩ Schema.spec.schema.properties`; stamp `x-mantle-bind` fields; generated id; status is `draft`, or immediately `published` for `lifecycle: operational`. |
 | `update` | UPDATE in place. `input.id` + `input.expectedVersion` (OCC) required. Bumps version. |
 | `upsert` | If `input.id` resolves, behaves as `update`; else as `create`. |
 | `delete` | Hard DELETE by id. |
-| `archive` | Soft-archive (status='archived'). The manifest validator permits this builtin only for `editorial` Schemas; the archive transition itself is runtime-wired, while editorial approval/request-publish remains deferred. |
+| `archive` | Soft-archive a publishing entry (`status='archived'`). |
 
 The Procedure's `input` is the contract with the *caller*. It MAY
 declare fields the Schema does not (e.g. a Turnstile token). The
@@ -848,11 +702,10 @@ the side-channel fields pass validation. To act on those fields
 (read the token, call the vendor), declare a `before_create`
 lifecycle Trigger — see below.
 
-`request_publish` and `publish` are intentionally not in the
-builtin vocabulary. They are editorial-workflow operations, not CRUD
-primitives.
+`request_publish` and `publish` are intentionally not in the builtin
+vocabulary. They are lifecycle operations, not CRUD primitives.
 
-#### `Trigger.source.kind: lifecycle` — bind a Procedure to a Schema event
+### `Trigger.source.kind: lifecycle` — bind a Procedure to a Schema event
 
 Shape:
 
@@ -874,12 +727,15 @@ spec:
 |---|---|
 | `before_create` | Before INSERT. Throw cancels. |
 | `after_create` | After INSERT. Default best-effort. |
-| `before_update` | Before UPDATE. Throw cancels. |
-| `after_update` | After UPDATE. Default best-effort. |
+| `before_update` | Before UPDATE or a status transition whose target is not `published` (including unpublish and archive). Throw cancels. |
+| `after_update` | After UPDATE or a status transition whose target is not `published` (including unpublish and archive). Default best-effort. |
 | `before_delete` | Before DELETE. Throw cancels. |
 | `after_delete` | After DELETE. Default best-effort. |
-| `before_publish` | Before any supported status transition to `published` (the shipped workflow is `simple`). |
-| `after_publish` | After any supported status transition to `published` (the shipped workflow is `simple`). |
+| `before_publish` | Before any supported status transition to `published` (the shipped workflow is `publishing`). |
+| `after_publish` | After any supported status transition to `published` (the shipped workflow is `publishing`). |
+
+v0.1 has no separate unpublish or archive hooks. Do not treat
+`before_update` / `after_update` as edit-only hooks.
 
 **Atomicity defaults by phase**:
 - `before_*`: `errorPolicy: abort`. Handler throw cancels the
@@ -910,9 +766,8 @@ post-mutation row for every `after_*`.
 
 **Hook ordering**: when multiple lifecycle Triggers bind the same
 `(schema, hook)`, the runtime fires them **alphabetically by
-`Trigger.metadata.name`**. A `priority: number` key is reserved for
-v0.2; today, choose names that sort correctly (`010-bot-check`,
-`020-rate-limit`).
+`Trigger.metadata.name`**. Choose names that sort correctly
+(`010-bot-check`, `020-rate-limit`).
 
 For deferred delivery, that ordered Trigger-name list is captured in
 one strict versioned event. Every captured Trigger runs before a
@@ -923,103 +778,7 @@ Cloudflare wiring, the 128 KB platform limit, retry/DLQ configuration,
 idempotency, and legacy-envelope draining are specified in
 [Deferred lifecycle hooks on Cloudflare Queues](deferred-lifecycle-queues.md).
 
-`before_publish` and `after_publish` already wrap the shipped simple publish
-transition. When editorial approval lands, the same hooks wrap its final
-transition to `published`; no second hook grammar is planned.
-
-### DRAFT (v0.2+, speculative)
-
-Each item below lands when the first concrete real-world use case
-forces it, not on speculation. Today, do not implement; parser/static
-validation rejects it with `DRAFT_KEY_USED`.
-
-#### Schema future
-- **`x-mantle-ref` auto-lift to virtual column** — when a property
-  carrying `x-mantle-ref: <other-schema>` is referenced in any registered
-  View's `filter:` or future `join:`, the SDK auto-creates the virtual
-  column + non-unique index without requiring an explicit `indexes`
-  declaration. Solves cross-collection JSON-path join
-  performance without making authors think about it. Pure SDK
-  behavior; no new YAML grammar.
-- **`spec.policies.visible`** — row-level read predicate auto-AND'd
-  into Views from this Schema. Lands with first private/audience
-  feature.
-- **`spec.policies.readable.fields`** — field-level wire-mask. Lands
-  when staff-only fields surface (e.g. `threadLength` visible to
-  editors only).
-- **`spec.policies.writable.{fields, create}`** — field-level write
-  gate auto-applied to all writers.
-- **`spec.policies.owner`** — names the ownership column for `owns:`
-  predicate. Currently implicit (`authorId`).
-- **Computed columns via projection Trigger** — see `Trigger.target`.
-
-#### View future
-- **`recursive: { parent, rootWhen, pathBy, depthAs?, pathAs?, maxDepth }`**
-  — declarative recursive CTE. Lands with first threaded-reads feature
-  (comments, taxonomies).
-- **`params: { <name>: <jsonschema> }`** — caller-bound view parameters.
-- **`gatedBy: [{ schema, policy, on }]`** — cross-Schema visibility
-  inheritance.
-- **`join: [{ as, from, on, project?, aggregate?: count|exists, bind? }]`**
-  — joined relations with optional reducer (per-row count or boolean).
-- **`policies: { skip: [<policy-name> | field, ...] }`** — explicit
-  bypass for admin/audit Views.
-- Filter AST extension: `contains` (array containment), `not`, `in`, `like`.
-
-#### Procedure future
-- **`requires.auth.any`** with disjunction; the shipped `all` predicate
-  vocabulary extends to `owns: { schema, idFrom }`, `contains: {
-  schema, idFrom, field, valueFrom }`.
-- **`requires.window.{withinMinutes, column?}`** — temporal
-  precondition, sibling-modifier of `owns:`. DRY rule: window MUST
-  sit beside exactly one `(schema, id)`-binding predicate in the same
-  any/all group.
-- **`requires.quota.{key, limit, per, overrideFrom?}`** — declarative
-  rate cap. Override Schema lookup keyed by `ctx.user`. Counter
-  substrate: Durable Object.
-- **`errors.{onHandlerThrow, onRecursionDepth, maxDepth}`** + **`retry.{
-  limit, backoff, retryOn, idempotencyKey?}`** — failure-policy
-  declared. Retry + `op: create` requires `idempotencyKey:` (parse
-  error otherwise).
-
-#### Trigger future
-- **`source.kind: cron`** with `expr:` — scheduled invocation.
-- **`source.kind: queue`** — async fan-out / message-driven invocation.
-- **`source.kind: lifecycle.foo`** — DRAFT extensions to the shipped
-  lifecycle hooks (e.g. `before_archive`, `after_request_publish`).
-  The 8 hooks listed in the detailed shipped section are the floor,
-  not the ceiling.
-
-(Full lifecycle Trigger spec for the 8 shipped hooks lives
-in the detailed section above. The remaining DRAFT items
-below are the speculative v0.2+ shapes that haven't yet been promoted
-to a committed roadmap.)
-
-- **`target.project: { schema, where, set: { <col>: { aggregate, from,
-  where } } }`** — declarative aggregate-projection across Schemas.
-  Replaces hand-written counter handlers. Same-transaction on PG;
-  bounded-eventual on D1 via single-writer DO.
-- **`atomicity: same-transaction | best-effort`** — explicit guarantee
-  declaration when projection Triggers ship.
-
-#### Cross-cutting future
-- **Closed `ctx.*` predicate identity**: v0.1 `{ user, staff, auth,
-  auth.scope }`
-  extends to `{ ..., system }` when SDK-internal Trigger executor
-  paths land. Multi-tenant deployments would add `{ tenant }` via
-  grammar-revise round if/when that product shape is pursued. New
-  entries require explicit grammar-revise (closed enum is
-  load-bearing infrastructure).
-- **Placeholder namespace `$.*`**: `$.input.<f>`, `$.row.<f>`, `$.op`,
-  `$.params.<f>`, `$.source` — write-time data-flow bindings inside
-  policy ASTs and handler signatures. Distinct from `:ctx.*` identity
-  bindings; one-site evaluation rule.
-- **`Schema.spec.staffBypass: [<role>]`** — DRY shortcut once
-  `ctx.staff: [editor, owner]` repetition crosses 4+ schemas.
-
-Each extension goes through a 3-agent review (yml-editor proposes /
-code-impler tests buildability / fresh-dev verifies clarity) before
-locking. v0.1 is the floor, not the ceiling.
+`before_publish` and `after_publish` wrap the shipped publishing transition.
 
 ## Lineage — the academic foundations
 
@@ -1032,6 +791,6 @@ locking. v0.1 is the floor, not the ceiling.
 
 The composite design — declarative resources + ECA-fired procedures +
 policy-gated execution — is sometimes labeled **Active Database +
-Policy-Based Management**. Postgres + PostgREST + pg_cron is the
+Policy-Based Management**. Postgres + PostgREST is the
 canonical full-stack reference; we abstract that pattern up to the
 application layer with K8s-style YAML manifests.