@aotter/mantle 0.0.11-alpha.59 → 0.0.11-alpha.61

package/README.md

@@ -93,6 +93,10 @@ The `mantle-runtime` package never imports Cloudflare-specific types — adapter
   - `node_modules/@aotter/mantle/docs/api-mcp-authorization.md` (anonymous,
     API-key, paid guard, personal-token, OAuth, REST, and MCP examples)
   - `node_modules/@aotter/mantle/docs/media-uploads.md` (Cloudflare R2 adapter recipe)
+  - `node_modules/@aotter/mantle/docs/deferred-lifecycle-queues.md` (versioned
+    Queue wiring, retry/DLQ, idempotency, and delivery guarantees)
+  - `node_modules/@aotter/mantle/docs/schema-indexes.md` (ordered composite
+    JSON-field indexes, D1 query plans, and the safe Procedure SQL helper)
   - `node_modules/@aotter/mantle/docs/adr/`
   - `node_modules/@aotter/mantle/skills/develop/SKILL.md`
   - `node_modules/@aotter/mantle/skills/plugin/SKILL.md`
@@ -103,6 +107,8 @@ The `mantle-runtime` package never imports Cloudflare-specific types — adapter
 - [Repo](https://github.com/aotter/mantle)
 - [4-atom manifest model (ADR-0001)](https://github.com/aotter/mantle/blob/develop/docs/adr/0001-four-atom-manifest-model.md)
 - [API and MCP authorization](https://github.com/aotter/mantle/blob/develop/docs/api-mcp-authorization.md)
+- [Deferred lifecycle Queues](https://github.com/aotter/mantle/blob/develop/docs/deferred-lifecycle-queues.md)
+- [Schema indexes on D1](https://github.com/aotter/mantle/blob/develop/docs/schema-indexes.md)
 - [Release process](https://github.com/aotter/mantle/blob/develop/docs/release-process.md)
 - [Issues](https://github.com/aotter/mantle/issues)
 

package/docs/adapter-guide.md

@@ -25,10 +25,17 @@ Optional ports are enabled only when a feature needs them:
 | Contract | Source | Required when |
 |---|---|---|
 | `MediaStorage` | `packages/mantle-runtime/src/domain/port/MediaStorage.ts` | The adapter exposes admin/MCP media upload flows. |
-| `DeferredHookDispatcher` | `packages/mantle-runtime/src/domain/port/DeferredHookDispatcher.ts` | The adapter wants durable queue delivery for `after_*` lifecycle hooks. |
+| `DeferredHookDispatcher` | `packages/mantle-runtime/src/domain/port/DeferredHookDispatcher.ts` | The adapter wants at-least-once queue delivery for `after_*` lifecycle hooks. |
 
 Test seams such as `Clock` and `IdGenerator` are injectable through `createCmsRuntime`, but normal adapters do not need custom implementations.
 
+Deferred delivery is an optional, versioned wire contract. Queue acceptance is
+not atomic with the entry write; adapters must preserve the supplied event id,
+validate untrusted messages before dereferencing them, surface handler failures
+to their retry mechanism, and document poison-message/DLQ behavior. See
+[Deferred lifecycle hooks on Cloudflare Queues](deferred-lifecycle-queues.md)
+for the reference implementation and exact guarantees.
+
 ## Runtime boot
 
 Adapters compose the runtime through `createCmsRuntime`:
@@ -148,6 +155,8 @@ Minimum auth/MCP behavior:
 - [ ] Prove one guarded target has identical REST/MCP outcomes, including
       mutable revocation on the next call.
 - [ ] Add optional `MediaStorage` or `DeferredHookDispatcher` only when the adapter supports those features.
+- [ ] For deferred hooks, document at-least-once delivery, idempotency,
+      message limits, retries/DLQ, and the non-transactional write-to-enqueue gap.
 - [ ] Verify the runtime package still has no platform-specific imports.
 
 ## Current non-goals

package/docs/adr/0001-four-atom-manifest-model.md

@@ -285,6 +285,7 @@ forces it.
 **Schema (v0.1)**:
 - `spec.schema:` (JSON Schema 2020-12 body)
 - `spec.uniqueIndexes:` (composite uniques)
+- `spec.indexes:` (ordered composite, non-unique access paths)
 - Property extensions: `x-mantle-bind`, `x-mantle-ref`, `x-mcp-hint`
 
 **View (v0.1)**:
@@ -332,7 +333,7 @@ forces it.
 #### What's DRAFT (do not implement, do not type)
 
 - Schema: `policies.{visible, readable, writable, owner}`,
-  `indexedFields:`, `x-mantle-ref` auto-lift to virtual column,
+  `x-mantle-ref` auto-lift to virtual column,
   computed columns via projection Trigger
 - View: `recursive`, `gatedBy`, `join`, `policies.skip`,
   filter AST extensions (`contains`, `not`, `in`, `like`)

package/docs/adr/0007-ai-as-primary-author.md

@@ -95,8 +95,8 @@ What it catches:
 - `Trigger.target.procedure` references a Procedure that exists
 - `View.from` references a Schema that exists; `View.fields` and
   `View.filter` refer only to declared properties of that Schema
-- `Schema.uniqueIndexes` lists only properties declared in the
-  Schema's `spec.schema.properties`
+- `Schema.uniqueIndexes` and `Schema.indexes` contain valid ordered
+  tuples of scalar properties declared in `spec.schema.properties`
 - `x-mantle-bind: <value>` is in the closed enum
 - `requires.auth.all` predicates are in the v0.1 vocabulary
 - `Trigger.source.path` does not collide with another Trigger

package/docs/adr/0011-adapter-port-spec.md

@@ -31,17 +31,27 @@ The POC accumulated multiple half-decisions about this seam (POC ADR-0015 docume
 
 Optional feature ports may also live in `domain/port/`, but they are
 not part of the first-run adapter contract until a feature is enabled.
-For v0.1.x media hosting and durable lifecycle dispatch:
+For v0.1.x media hosting and deferred lifecycle dispatch:
 
 | Optional port | Surface |
 |---|---|
 | `MediaStorage` | Object-storage-shaped media upload/commit/public URL/delete contract for **public** media. Cloudflare may implement with R2, but runtime must not import R2 types. |
-| `DeferredHookDispatcher` | Queue-shaped dispatcher for durable `after_*` lifecycle hooks. Cloudflare may implement with Workers Queues; other adapters may use a queue, job runner, or leave it unset. |
+| `DeferredHookDispatcher` | Queue-shaped dispatcher for at-least-once `after_*` lifecycle delivery. Cloudflare may implement with Workers Queues; other adapters may use a queue, job runner, or leave it unset. |
 
 These optional ports must not force first-run provisioning to create R2
 resources. Publication starters can carry external image URLs without a
 media storage implementation.
 
+`DeferredHookDispatcher.enqueue` confirms adapter acceptance only. It cannot
+make an entry write and an external queue send atomic. The versioned envelope
+contains a stable event id plus captured Trigger names; handlers combine them
+for idempotency because retries and ambiguous producer fallback can duplicate
+execution. Deferred envelopes carry persisted entry data and normalized actor
+metadata, never arbitrary original request input. Adapter-specific retry,
+delay, batch, DLQ, and message-size settings remain outside manifest grammar.
+The operational reference is
+[`docs/deferred-lifecycle-queues.md`](../deferred-lifecycle-queues.md).
+
 Identity, session, OAuth, and role enforcement are adapter-owned per
 ADR-0014. The runtime does not define `SessionRepository`,
 `OAuthVerifier`, `UserRepository`, or `StaffRepository` ports. Adapters

package/docs/deferred-lifecycle-queues.md

@@ -0,0 +1,267 @@
+# Deferred lifecycle hooks on Cloudflare Queues
+
+Mantle can opt `after_*` lifecycle Triggers into a Cloudflare Queue. This is
+useful for notifications and projections that should not add request latency,
+but it is not an exactly-once transaction boundary.
+
+## Contract
+
+- The entry write commits before Queue delivery. D1 and Queue do not share a
+  transaction, so a Worker failure can still occur in that gap.
+- A resolved `Queue.send()` means Cloudflare accepted the message. Consumption
+  is at-least-once; a message can run more than once.
+- A rejected or ambiguous send falls back with the same event identity through
+  `ctx.waitUntil`, or inline when `waitUntil` is unavailable. `waitUntil` is
+  best-effort and does not close the D1-to-Queue gap.
+- A consumer acknowledges a message only after every captured Trigger
+  succeeds. It runs all captured Triggers before surfacing failures, so a later
+  failure can replay an earlier success.
+- Malformed, unsupported, removed-Trigger, and persistently failing messages
+  are retried and then sent to the configured dead-letter queue (DLQ). Without
+  a DLQ, Cloudflare discards them after `max_retries`.
+
+Deferred handlers must therefore be idempotent. Mantle does not promise
+exactly-once execution.
+
+## Version 1 event
+
+The strict v1 envelope contains:
+
+```ts
+interface DeferredHookEnvelope {
+  version: 1;
+  eventId: string;
+  triggerNames: readonly string[];
+  hook: "after_create" | "after_update" | "after_delete" | "after_publish";
+  schema: string;
+  entry: EntryRow;
+  ctxSnapshot: CtxSnapshot | null;
+}
+```
+
+`triggerNames` is captured when the entry mutation runs. A later deployment
+does not add a new Trigger to an old event. Removing or renaming a captured
+Trigger makes that old message fail validation at dispatch and eventually
+reach the DLQ instead of silently changing its meaning.
+
+Each handler receives persisted `entry.data` as its input and:
+
+```ts
+ctx.event = {
+  id: envelope.eventId,
+  trigger: currentTriggerName,
+  hook: envelope.hook,
+  schema: envelope.schema,
+  entry: envelope.entry,
+};
+```
+
+Use `${ctx.event.id}:${ctx.event.trigger}` as the handler's idempotency key.
+The same key survives enqueue fallback, Queue retries, and replay. Synchronous
+`before_*` hooks may still receive pre-projection request input such as a
+CAPTCHA token; deferred `after_*` envelopes never retain that input. The
+identity snapshot contains normalized actor and credential metadata, never raw
+cookies, tokens, or API keys.
+
+Cloudflare's 128 KB limit is decimal and includes platform metadata. The
+adapter therefore rejects non-JSON envelopes and encoded envelopes at or above
+127,000 bytes before calling `Queue.send`, leaving at least 1 KB of headroom.
+Keep entry payloads smaller than that supported limit.
+
+## Cloudflare opt-in
+
+Create the internal queue and its DLQ:
+
+```sh
+pnpm wrangler queues create mantle-internal
+pnpm wrangler queues create mantle-internal-dlq
+```
+
+Add both producer and consumer bindings. These are adapter settings, not Mantle
+manifest grammar:
+
+```toml
+[[queues.producers]]
+binding = "MANTLE_INTERNAL_QUEUE"
+queue = "mantle-internal"
+
+[[queues.consumers]]
+queue = "mantle-internal"
+max_batch_size = 10
+max_batch_timeout = 5
+max_retries = 5
+retry_delay = 60
+dead_letter_queue = "mantle-internal-dlq"
+```
+
+Wire the producer into `CmsConfig.bindings` and export the consumer alongside
+the existing HTTP/OAuth handler. The same Worker may be both producer and
+consumer:
+
+```ts
+import type { DeferredHookEnvelope } from "@aotter/mantle/runtime";
+import {
+  AssetsAssetServer,
+  D1DatabaseDriver,
+  KvCacheBinding,
+  WorkersQueueHookDispatcher,
+  createCmsRef,
+  createQueueHandler,
+  createOAuthProvider,
+} from "@aotter/mantle/cloudflare";
+
+interface Env {
+  DB: D1Database;
+  KV: KVNamespace;
+  ASSETS: Fetcher;
+  MANTLE_INTERNAL_QUEUE: Queue<DeferredHookEnvelope>;
+}
+
+function buildWorker(env: Env) {
+  const cms = createCmsRef({
+    manifests,
+    handlers,
+    auth: createSiteAuth(env),
+    bindings: {
+      db: new D1DatabaseDriver(env.DB),
+      kv: new KvCacheBinding(env.KV),
+      assets: new AssetsAssetServer(env.ASSETS),
+      deferredHookDispatcher: new WorkersQueueHookDispatcher(
+        env.MANTLE_INTERNAL_QUEUE,
+      ),
+    },
+  });
+
+  const http = createOAuthProvider<Env>({
+    defaultHandler: createSiteHttpHandler(cms),
+    apiHandlers: createSiteMcpHandlers(cms),
+  });
+
+  return { http, consumeMantle: createQueueHandler<Env>(cms) };
+}
+
+let built: ReturnType<typeof buildWorker> | undefined;
+const worker = (env: Env) => built ??= buildWorker(env);
+
+export default {
+  fetch(request, env, ctx) {
+    return worker(env).http.fetch(request, env, ctx);
+  },
+  queue(batch, env) {
+    return worker(env).consumeMantle(batch, env);
+  },
+} satisfies ExportedHandler<Env>;
+```
+
+`createSiteAuth`, `createSiteHttpHandler`, and `createSiteMcpHandlers` above
+stand for the site's existing adapter assembly; Queue opt-in adds only the
+dispatcher binding and `queue` export.
+
+## Idempotent handlers
+
+For a D1-owned effect, make the event/Trigger key a unique database key. This
+example records a site-owned notification job exactly once even when the
+lifecycle handler is replayed:
+
+```sql
+CREATE TABLE notification_jobs (
+  idempotency_key TEXT PRIMARY KEY,
+  entry_id TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  created_at INTEGER NOT NULL
+);
+```
+
+```ts
+import type { HandlerContext } from "@aotter/mantle/runtime";
+
+async function enqueueNotification(
+  input: Record<string, unknown>,
+  ctx: HandlerContext,
+) {
+  if (!ctx.event?.entry) throw new Error("lifecycle entry event required");
+  const key = `${ctx.event.id}:${ctx.event.trigger}`;
+  await (ctx.env as Env).DB.prepare(
+    `INSERT OR IGNORE INTO notification_jobs
+       (idempotency_key, entry_id, payload, created_at)
+     VALUES (?, ?, ?, ?)`,
+  ).bind(key, ctx.event.entry.id, JSON.stringify(input), Date.now()).run();
+  return { ok: true };
+}
+```
+
+For an upstream API that supports idempotency, send the same stable key and
+throw on failure so Queue retries it:
+
+```ts
+const key = `${ctx.event!.id}:${ctx.event!.trigger}`;
+const response = await fetch("https://api.example.com/messages", {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    "Idempotency-Key": key,
+  },
+  body: JSON.stringify(input),
+});
+if (!response.ok) throw new Error(`message provider returned ${response.status}`);
+```
+
+Core intentionally does not add a business outbox, payment state machine,
+provider retry wrapper, or generic job registry. Those remain site-owned.
+
+## Multiplexing site queues
+
+One Worker can consume the Mantle queue and site-owned queues without a Core
+registry. Route on `batch.queue` in the Worker entry:
+
+```ts
+const mantleQueue = createQueueHandler<Env>(cms);
+
+export default {
+  fetch: http.fetch.bind(http),
+  queue(batch, env, ctx) {
+    switch (batch.queue) {
+      case "mantle-internal":
+        return mantleQueue(batch, env);
+      case "billing-jobs":
+        return consumeBilling(batch, env, ctx);
+      default:
+        batch.retryAll();
+        console.error(`No consumer for queue '${batch.queue}'`);
+        return;
+    }
+  },
+} satisfies ExportedHandler<Env>;
+```
+
+The Mantle consumer processes at most five messages concurrently within each
+delivered batch even if `max_batch_size` is raised. It calls `retryAll()` when
+runtime boot fails, `retry()` for one failed event, and `ack()` exactly once
+after success.
+
+## Verification and operations
+
+Run the integrated contract test:
+
+```sh
+pnpm --filter @aotter/mantle-cloudflare test -- mantle-internal-queue.test.ts
+```
+
+It covers real runtime failure propagation, all-Trigger execution, stable
+replay identity, per-message ack/retry, malformed bodies, size/JSON rejection,
+runtime boot failure, and the five-message concurrency bound.
+
+For a site integration, run `wrangler dev`, submit a mutation with an
+`after_*` Trigger, and verify the consumer log. Make one handler fail once and
+confirm its first delivery is retried and the replay sees the same
+`ctx.event.id` and `ctx.event.trigger`. Inspect the DLQ before increasing
+`max_retries`; poison messages otherwise hide as repeated retries.
+
+### Upgrading from the unversioned envelope
+
+Version 1 intentionally rejects the old unversioned envelope and the old
+`originalInput` field. Before deploying this release to a Worker that already
+uses `mantle-internal`, stop old producers and drain the queue (including any
+in-flight retries), or explicitly move the remaining messages to an operator
+workflow. Deploying v1 with legacy messages still queued will retry those
+messages and eventually place them in the DLQ.

package/docs/design-atoms.md

@@ -101,7 +101,7 @@ stays honest.
 ### 1. `Schema` — the entity (internal)
 
 A relation. Defines what data exists. You declare the JSON Schema for
-each row, the unique indexes, the binding directives. Schema is **not
+each row, its indexes, and the binding directives. Schema is **not
 directly externally exposed** — clients don't write to a Schema URL; they
 hit a Procedure that the SDK translates into Schema mutations.
 
@@ -128,6 +128,7 @@ spec:
       authorId: { type: string, format: uuid, x-mantle-bind: ctx.user }
       createdAt: { type: string, format: date-time, x-mantle-bind: now }
   uniqueIndexes: [[slug, locale]]
+  indexes: [[locale, title]]        # ordered, non-unique hot path
 ```
 
 **`spec.title`** — admin UI label. Required. AI authors must populate
@@ -675,11 +676,13 @@ 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` declarations compile into virtual generated columns +
-partial unique indexes via the spec engine's DDL emitter
-(`@aotter/mantle-spec`); different collections coexist on the
-same table without colliding because the generated-column expression
-is gated by `WHEN collection = '<name>'`.
+`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
 
@@ -688,8 +691,9 @@ is gated by `WHEN collection = '<name>'`.
   plus `->` / `->>` operators.
 - Reserved-column queries (`status = 'published'`, `ORDER BY
   updated_at`) use native indexes — fast.
-- `uniqueIndexes`-declared paths use virtual columns + partial unique
-  indexes — fast equality.
+- `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)
 
@@ -708,11 +712,9 @@ is gated by `WHEN collection = '<name>'`.
 
 - **Blog-scale (< 10k entries / collection)**: today's design is
   comfortable. Public render hits KV cache, not D1.
-- **Mid-scale (10k – 100k entries)**: list/filter Views on
-  JSON-internal fields start to need `indexedFields` (future
-  grammar). Cross-collection JSON-path joins start to need
-  `x-mantle-ref` auto-lift. Both are reserved in the future-grammar
-  appendix.
+- **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
@@ -739,7 +741,7 @@ When this path is taken (post-v0.1; not implemented yet), the
 | What changes (SDK runtime) | Author impact |
 |---|---|
 | `data TEXT` → `data JSONB` | none |
-| Virtual generated columns → optional (PG can use GIN) | author may stop declaring `indexedFields` if defaults suffice; same YAML still valid |
+| 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 |
@@ -880,20 +882,29 @@ spec:
 **Atomicity defaults by phase**:
 - `before_*`: `errorPolicy: abort`. Handler throw cancels the
   surrounding mutation; caller receives the diagnostic.
-- `after_*`: `errorPolicy: continue`. Handler throw is logged and
-  discarded; the mutation succeeds. Runs via `ctx.waitUntil` when
-  available so the caller doesn't block on a remote call.
+- `after_*`: `errorPolicy: continue`. The committed mutation remains
+  successful. On the inline / `ctx.waitUntil` path, a failure is logged
+  and swallowed. With an optional `DeferredHookDispatcher`, failures
+  surface to the delivery adapter so its at-least-once retry/DLQ policy
+  can run; they still never roll back the entry mutation.
 
 Authors override either default by declaring `errorPolicy: abort |
 continue` explicitly.
 
-**Hook handlers** receive the *original* (pre-projection) Procedure
-input — so a `before_create` hook on `contact-messages` can read the
-caller's `recaptchaToken` field even though the row never stores it.
-They also receive `ctx.event = { hook, schema, entry }`. `entry` is
-null only on `before_create` (no row exists yet); the pre-mutation
-row on `before_update` / `before_delete` / `before_publish`; the
-persisted post-mutation row on every `after_*`.
+**Hook handler input** is phase-specific. Synchronous `before_*` hooks
+receive the original pre-projection Procedure input, so a
+`before_create` hook on `contact-messages` can read the caller's
+`recaptchaToken` even though the row never stores it. Every `after_*`
+hook receives only persisted `entry.data`; deferred envelopes never
+retain arbitrary request input.
+
+Handlers also receive
+`ctx.event = { id, trigger, hook, schema, entry }`. `id` is stable
+across enqueue fallback and deferred retries; `trigger` is the current
+`Trigger.metadata.name`. Deferred handlers use `${id}:${trigger}` as
+their idempotency key. `entry` is null only on `before_create`; it is
+the pre-mutation row for the other `before_*` hooks and the persisted
+post-mutation row for every `after_*`.
 
 **Hook ordering**: when multiple lifecycle Triggers bind the same
 `(schema, hook)`, the runtime fires them **alphabetically by
@@ -901,6 +912,15 @@ persisted post-mutation row on every `after_*`.
 v0.2; today, 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
+failure is returned to the Queue, so retry may replay Triggers that
+already succeeded. Queue acceptance is not transactional with D1,
+`waitUntil` fallback is best-effort, and exactly-once is not promised.
+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).
+
 **Editorial-lifecycle hooks** (`before_publish`, `after_publish`)
 depend on the `lifecycle: editorial` runtime, which ships in the
 same v0.1.x cut.
@@ -912,18 +932,11 @@ forces it, not on speculation. Today, do not implement; the boot
 validator rejects with `DRAFT_KEY_USED`.
 
 #### Schema future
-- **`spec.indexedFields: [<field-path>, ...]`** — non-unique
-  performance indexes on JSON-internal fields. Compiles to one virtual
-  generated column + one non-unique index per declared field, mirroring
-  the existing `uniqueIndexes` mechanism but without the UNIQUE
-  constraint. Lands when first list/filter Views on JSON-internal
-  fields start to slow (typical threshold: 5–10k rows on a collection
-  whose hot filter or sort key isn't a reserved native column).
 - **`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 explicit
-  `indexedFields` entry. Solves cross-collection JSON-path join
+  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

package/docs/schema-indexes.md

@@ -0,0 +1,169 @@
+# Schema indexes on D1
+
+Mantle stores every authored Schema property inside the shared `entries.data`
+JSON `TEXT` column. Declare `indexes` for measured, hot access paths that need
+an ordered non-unique B-tree index. Use `uniqueIndexes` when the same ordered
+fields are a data-integrity constraint.
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Schema
+metadata: { name: account-members }
+spec:
+  title: Account members
+  lifecycle: none
+  schema:
+    type: object
+    properties:
+      userId:    { type: string }
+      state:     { type: string }
+      accountId: { type: string }
+      email:     { type: [string, "null"] }
+  indexes:
+    - [userId, state, accountId]
+    - [accountId, state, userId]
+  uniqueIndexes:
+    - [accountId, userId]
+    - [accountId, email]
+```
+
+Each inner array is one index. Field order is significant. A one-field array
+is valid; a bare string or the retired `indexedFields` spelling is not.
+Invalid matrix shapes report `INVALID_MANIFEST_ENVELOPE`; invalid index
+semantics report `SCHEMA_INDEX_INVALID`, and unknown fields report
+`SCHEMA_INDEX_FIELD_UNKNOWN` (`uniqueIndexes` keeps its existing
+`UNIQUE_INDEX_FIELD_UNKNOWN` code).
+
+## Leftmost-prefix behavior
+
+For `[userId, state, accountId]`, SQLite can use the index for:
+
+```sql
+WHERE userId = ?
+WHERE userId = ? AND state = ?
+WHERE userId = ? AND state = ? AND accountId = ?
+```
+
+It does not provide the same guarantee when the leftmost field is skipped:
+
+```sql
+WHERE state = ? AND accountId = ?
+```
+
+The second declaration, `[accountId, state, userId]`, supports the other hot
+path and supplies the requested order without a temporary sort:
+
+```sql
+WHERE accountId = ? AND state = ?
+ORDER BY userId
+```
+
+Do not declare every possible permutation. Each index consumes storage and
+adds work to inserts and updates. Start from an observed query plan or hot
+endpoint and declare only the access paths it needs.
+
+## Supported fields
+
+Indexed fields are exact, own, top-level keys of
+`spec.schema.properties`. `a.b` means a literal top-level key named `a.b`; it
+does not traverse `{ a: { b: ... } }`.
+
+An index-bearing Schema name and every indexed field must match
+`^[A-Za-z][A-Za-z0-9_.-]*$`.
+
+The property must declare exactly one non-null scalar type. It may also allow
+`null` with a type array or `nullable: true`.
+
+| JSON Schema type | generated-column affinity |
+|---|---|
+| `string` | `TEXT` |
+| `integer`, `boolean` | `INTEGER` |
+| `number` | `REAL` |
+
+Objects, arrays, enum-only properties, and mixed non-null unions are not
+indexable. Reserved native View fields (`id`, `status`, `version`,
+`createdAt`, `updatedAt`, `authorId`) also cannot be index declarations.
+
+Missing and `null` leftmost values are omitted from the partial index. SQLite
+UNIQUE semantics still allow more than one composite containing `NULL`.
+
+## Core-compiled queries
+
+Mantle creates collection-gated VIRTUAL generated columns during `bootInit`.
+Core-compiled View projections, filters, and ordering automatically reference
+a generated column when their field is declared by `indexes` or
+`uniqueIndexes`; undeclared fields keep using `json_extract`.
+
+D1 stores the original JSON as `TEXT`, not PostgreSQL JSONB. The generated
+scalar columns and their B-tree indexes are the supported indexed-path
+mechanism. Their physical identifiers are private, versioned, and encoded;
+never copy one from `sqlite_schema` into site code.
+
+## Site-owned Procedure SQL
+
+Use the pure helper when a business query remains site-owned. It returns a
+fully quoted reference for a declared field or `null` when that field has no
+declared index. Pass a table alias for joins so the generated column is not
+ambiguous.
+
+```ts
+import {
+  schemaIndexedFieldSql,
+  type SchemaManifest,
+} from "@aotter/mantle/spec";
+import { loadManifests } from "../mantle/manifests.js";
+
+const accountMembers = loadManifests().find(
+  (manifest): manifest is SchemaManifest =>
+    manifest.kind === "Schema" && manifest.metadata.name === "account-members",
+);
+if (!accountMembers) throw new Error("account-members Schema is missing");
+
+const userId = schemaIndexedFieldSql(accountMembers, "userId", "member");
+const state = schemaIndexedFieldSql(accountMembers, "state", "member");
+if (!userId || !state) {
+  throw new Error("account-members actor lookup requires its declared index");
+}
+
+const rows = await env.DB.prepare(
+  `SELECT member.id, member.data
+     FROM entries AS member
+    WHERE member.collection = ?
+      AND ${userId} = ?
+      AND ${state} = ?`,
+)
+  .bind("account-members", actorId, "active")
+  .all();
+```
+
+The helper does not authorize the query or define its business response. The
+site still owns actor resolution, account rules, aggregation, and output.
+
+## Verify a plan
+
+Inspect the real database when adding or changing a hot path:
+
+```sql
+PRAGMA index_list("entries");
+PRAGMA index_xinfo("<index returned above>");
+
+EXPLAIN QUERY PLAN
+SELECT id FROM entries
+WHERE collection = 'account-members'
+  AND "<reference emitted by Core>" = 'user-1';
+```
+
+The plan should contain `SEARCH entries USING INDEX ...`, and an indexed
+filter/order path should not contain `USE TEMP B-TREE FOR ORDER BY`.
+
+Existing databases upgrade by adding new affinity-correct VIRTUAL columns and
+versioned indexes; populated `entries` rows do not need a rewrite. Unused
+generated columns may remain because dropping them is not safe across every D1
+version Mantle supports. Compatible alpha.59 unique indexes remain during a
+rolling upgrade; ambiguous legacy flattened names and indexes removed from
+manifests are reconciled away at boot.
+
+References: [D1 JSON](https://developers.cloudflare.com/d1/sql-api/query-json/),
+[D1 generated columns](https://developers.cloudflare.com/d1/reference/generated-columns/),
+[D1 indexes](https://developers.cloudflare.com/d1/best-practices/use-indexes/),
+[SQLite partial indexes](https://www.sqlite.org/partialindex.html).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.0.11-alpha.59",
+  "version": "0.0.11-alpha.61",
   "description": "Umbrella entry for @aotter/mantle. Adopters install this one package and import from subpaths: /spec, /runtime, /cloudflare, /admin-ui. Sub-packages remain individually installable on npm for tooling / alt-adapter authors. The Netlify adapter ships as a private workspace stub in v0.1 — its subpath will be added when the impl lands in v0.2.",
   "license": "Apache-2.0",
   "homepage": "https://mantle.tools/",
@@ -47,10 +47,10 @@
     "README.md"
   ],
   "dependencies": {
-    "@aotter/mantle-admin-ui": "0.0.11-alpha.59",
-    "@aotter/mantle-runtime": "0.0.11-alpha.59",
-    "@aotter/mantle-cloudflare": "0.0.11-alpha.59",
-    "@aotter/mantle-spec": "0.0.11-alpha.59"
+    "@aotter/mantle-admin-ui": "0.0.11-alpha.61",
+    "@aotter/mantle-cloudflare": "0.0.11-alpha.61",
+    "@aotter/mantle-spec": "0.0.11-alpha.61",
+    "@aotter/mantle-runtime": "0.0.11-alpha.61"
   },
   "peerDependencies": {
     "@cloudflare/workers-oauth-provider": "^0.8.0",