@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.1

package/docs/examples/procurement.md

@@ -0,0 +1,215 @@
+---
+description: Members submit purchase requisitions and see only their own; staff review the queue with an optimistic lock.
+---
+# Procurement approvals with member and staff roles
+
+[Examples hub](./README.md)
+
+Two audiences share one table: signed-in members submit and track their own
+requisitions, and staff approve or reject them. Every Procedure is SQL.
+
+## Problem
+
+A signed-in member submits a request number, an item, a quantity, a need-by
+date and a justification, and sees only their own requisitions. Staff with the
+`owner` or `editor` role see every `submitted` requisition, soonest need-by
+date first, and mark each `approved` or `rejected` with a note. Two reviewers
+must not silently overwrite each other's decision.
+
+## Manifest
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: purchase-requisitions }
+spec:
+  title: Purchase requisitions
+  description: Member-submitted purchase needs waiting for staff review.
+  lifecycle: operational
+  uniqueIndexes: [[requestNumber]]
+  indexes:
+    - [requestedBy, needBy]
+    - [requestStatus, needBy]
+  schema:
+    type: object
+    additionalProperties: false
+    required: [requestNumber, requestedBy, item, quantity, needBy, justification, requestStatus]
+    properties:
+      requestNumber: { type: string, maxLength: 40, pattern: "^REQ-[A-Z0-9-]+$" }
+      requestedBy: { type: string }
+      item: { type: string, minLength: 1, maxLength: 160 }
+      quantity: { type: integer, minimum: 1 }
+      needBy: { type: string, format: date }
+      justification: { type: string, minLength: 1, maxLength: 1000 }
+      requestStatus: { type: string, enum: [submitted, approved, rejected] }
+      reviewerNote: { type: string, maxLength: 1000 }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: my-requisitions }
+spec:
+  title: My requisitions
+  description: The signed-in member's own purchase requisitions and their approval status.
+  surface: public
+  requires: { auth: { all: [ctx.user] } }
+  sql: |
+    SELECT id, requestNumber, item, quantity, needBy, justification, requestStatus, reviewerNote, created_at
+    FROM "purchase-requisitions"
+    WHERE requestedBy = auth.uid()
+    ORDER BY created_at DESC LIMIT 100
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: pending-approvals }
+spec:
+  title: Pending approvals
+  description: Purchase requisitions waiting for a staff decision, soonest need-by date first.
+  surface: staff
+  requires: { auth: { all: [{ ctx.staff: [owner, editor] }] } }
+  sql: |
+    SELECT id, version, requestNumber, requestedBy, item, quantity, needBy, justification, created_at
+    FROM "purchase-requisitions"
+    WHERE requestStatus = 'submitted'
+    ORDER BY needBy LIMIT 100
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: submit-requisition }
+spec:
+  title: Submit requisition
+  description: Submit a purchase requisition as the signed-in member.
+  requires: { auth: { all: [ctx.user] } }
+  input:
+    type: object
+    additionalProperties: false
+    required: [requestNumber, item, quantity, needBy, justification]
+    properties:
+      requestNumber: { type: string, maxLength: 40, pattern: "^REQ-[A-Z0-9-]+$" }
+      item: { type: string, minLength: 1, maxLength: 160 }
+      quantity: { type: integer, minimum: 1 }
+      needBy: { type: string, format: date }
+      justification: { type: string, minLength: 1, maxLength: 1000 }
+  output: { type: object }
+  handler:
+    sql: |
+      INSERT INTO "purchase-requisitions" (requestNumber, requestedBy, item, quantity, needBy, justification, requestStatus)
+      VALUES (input.requestNumber, auth.uid(), input.item, input.quantity, input.needBy, input.justification, 'submitted')
+      RETURNING id, requestNumber AS "requestNumber"
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: review-requisition }
+spec:
+  title: Review requisition
+  description: Approve or reject a submitted requisition, with the version the reviewer saw.
+  requires: { auth: { all: [{ ctx.staff: [owner, editor] }] } }
+  input:
+    type: object
+    additionalProperties: false
+    required: [id, expectedVersion, requestStatus]
+    properties:
+      id:
+        type: string
+        x-mantle-ref: { schema: purchase-requisitions, field: id }
+      expectedVersion: { type: integer, minimum: 1 }
+      requestStatus: { type: string, enum: [approved, rejected] }
+      reviewerNote: { type: string, maxLength: 1000 }
+  output: { type: object }
+  handler:
+    sql: |
+      UPDATE "purchase-requisitions"
+      SET requestStatus = input.requestStatus, reviewerNote = COALESCE(input.reviewerNote, reviewerNote)
+      WHERE id = input.id AND version = input.expectedVersion AND requestStatus = 'submitted'
+      RETURNING id, version, requestStatus AS "requestStatus"
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: submit-requisition-http }
+spec:
+  source: { kind: http, method: POST, path: /api/requisitions }
+  target: { procedure: submit-requisition }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: submit-requisition-mcp }
+spec:
+  source: { kind: mcp, surface: public }
+  target: { procedure: submit-requisition }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: review-requisition-mcp }
+spec:
+  source: { kind: mcp, surface: staff }
+  target: { procedure: review-requisition }
+```
+
+### Ownership without trusting the caller
+
+- **The writer is `auth.uid()`, never an input.** `submit-requisition` sets
+  `requestedBy` to the caller's subject key in its SQL, and its input has no
+  such field. The status starts as the literal `'submitted'`.
+- **Why not `scope`?** `scope: { requestedBy: auth.uid() }` would hide every
+  other member's rows from *every* user caller, staff included, so reviewers
+  could not see the queue. Scope is for rows only their owner may ever see.
+  Here the member View filters on `requestedBy = auth.uid()` instead, and
+  `requires: ctx.user` means an anonymous caller is 401 before the query runs.
+- **A Schema whose name is not a plain identifier is quoted in SQL**:
+  `"purchase-requisitions"`.
+
+### Optimistic concurrency
+
+`review-requisition` pins one row with `id = input.id AND version =
+input.expectedVersion`. `expectedVersion` is the version the reviewer read,
+not that value plus one. A stale version matches no row, and a row op that
+writes nothing fails with `CONFLICT` (HTTP 409), so nothing changes and the
+reviewer reads again. `requestStatus = 'submitted'` in the same `WHERE` keeps a
+decided row from being decided twice. The Procedure's `target` is inferred from
+that `WHERE`.
+
+The object form of `x-mantle-ref` names the bound field. The Schema's one
+single-field unique index is `[requestNumber]`, so the string form would leave
+Admin to guess, and it would pick the request number.
+
+## Handlers
+
+None.
+
+## Try it
+
+```sh
+curl -i http://127.0.0.1:8787/api/views/my-requisitions
+# HTTP 401, {"error":{"code":"UNAUTHENTICATED",...}}
+
+curl -sS -X POST http://127.0.0.1:8787/api/requisitions \
+  -H 'content-type: application/json' -H "origin: http://127.0.0.1:8787" -H "cookie: $SESSION_COOKIE" \
+  -d '{"requestNumber":"REQ-2026-0002","item":"Monitor arm","quantity":2,"needBy":"2026-11-02","justification":"Second screen for review work."}'
+```
+
+A duplicate `requestNumber` is HTTP 409 `CONFLICT`. Staff call
+`pending_approvals` on `/mcp/staff`, then:
+
+```json
+{
+  "jsonrpc": "2.0", "id": 2, "method": "tools/call",
+  "params": { "name": "review_requisition", "arguments": { "id": "<id>", "expectedVersion": 1, "requestStatus": "approved", "reviewerNote": "Within budget." } }
+}
+```
+
+Replaying `expectedVersion: 1` afterwards is an error result with code
+`CONFLICT`. A contributor gets `AUTH_DENIED`. The public surface lists
+`submit_requisition` and `my_requisitions`; `review_requisition` is only on the
+staff surface.
+
+## What this leaves out
+
+- **Approval chains.** One decision by one staff member. Sequential approvers
+  need a step field and a `before_update` hook that checks the transition.
+- **Budgets.** A live budget check belongs in a `requires.guard` handler.
+- **Notifications.** See the `after_create` hook in
+  [Intake with bot check and notification](./intake-hooks.md).
+
+## Source
+
+- [Authorization](../handbook/concepts/authorization.md): `scope`, `auth.uid()` and `requires`
+- [Procedure reference](../handbook/reference/procedure.md): row ops and locks

package/docs/examples/publication.md

@@ -0,0 +1,211 @@
+---
+description: Localized posts with a stable parent identity, a public per-locale list, public full-text search and a reader suggestion box.
+---
+# Publication: localized posts with a public list
+
+[Examples hub](./README.md)
+
+Posts in several languages, a public list per locale, public search, and
+reader suggestions. Every Procedure is SQL; editors draft and publish through
+Admin.
+
+## Problem
+
+Editors draft posts in one or more locales and publish each language version
+on its own. Every language version shares one stable identity, its slug, so
+the site can link translations and Admin can group them. Visitors read a
+per-locale list of published posts, newest first, and search them. Readers may
+suggest topics; suggestions are records staff read, never published.
+
+## Manifest
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: posts }
+spec:
+  title: Posts
+  description: Stable post identities shared by every language version.
+  lifecycle: publishing
+  uniqueIndexes: [[slug]]
+  schema:
+    type: object
+    required: [slug]
+    properties:
+      slug: { type: string, maxLength: 120, pattern: "^[a-z0-9-]+$" }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: post-translations }
+spec:
+  title: Post translations
+  description: Localized titles and bodies for each post.
+  localized: true
+  translates: { parent: posts, on: slug }
+  lifecycle: publishing
+  uniqueIndexes: [[slug, locale]]
+  indexes: [[locale, publishedAt]]
+  searchableFields: [title, excerpt, body]
+  schema:
+    type: object
+    required: [slug, locale, title, publishedAt]
+    properties:
+      slug: { type: string, maxLength: 120, pattern: "^[a-z0-9-]+$" }
+      locale: { type: string }
+      title: { type: string }
+      excerpt: { type: string }
+      body: { type: string, x-mcp-hint: markdown }
+      publishedAt: { type: string, format: date-time }
+---
+# Public Views over publishing Schemas see published rows only.
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: published-posts }
+spec:
+  title: Published posts
+  description: Published posts in one locale, newest first.
+  surface: public
+  input:
+    type: object
+    additionalProperties: false
+    required: [locale]
+    properties:
+      locale: { type: string }
+  sql: |
+    SELECT id, slug, locale, title, excerpt, publishedAt, updated_at
+    FROM "post-translations"
+    WHERE locale = input.locale
+    ORDER BY publishedAt DESC LIMIT 50
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: search-posts }
+spec:
+  title: Search posts
+  description: Full-text search over published posts in one locale.
+  surface: public
+  input:
+    type: object
+    additionalProperties: false
+    required: [locale, q]
+    properties:
+      locale: { type: string }
+      q: { type: string, minLength: 1 }
+  sql: |
+    SELECT t.id, t.slug, t.title, t.excerpt FROM "post-translations" t
+    WHERE t.locale = input.locale AND mantle.search(t, input.q)
+    ORDER BY mantle.search_rank(t), t.id
+    LIMIT 20
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: post-suggestions }
+spec:
+  title: Post suggestions
+  description: Reader suggestions for future posts.
+  lifecycle: operational
+  schema:
+    type: object
+    required: [title, email]
+    properties:
+      title: { type: string }
+      email: { type: string, format: email }
+      note: { type: string }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: submit-post-suggestion }
+spec:
+  input:
+    type: object
+    additionalProperties: false
+    required: [title, email]
+    properties:
+      title: { type: string }
+      email: { type: string, format: email }
+      note: { type: string }
+  output: { type: object }
+  handler:
+    sql: |
+      INSERT INTO "post-suggestions" (title, email, note)
+      VALUES (input.title, input.email, input.note)
+      RETURNING id
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: submit-post-suggestion-http }
+spec:
+  source: { kind: http, method: POST, path: /api/post-suggestions }
+  target: { procedure: submit-post-suggestion }
+```
+
+How the pieces fit:
+
+- **`posts` is the parent** and holds only what every language shares: the
+  slug.
+- **`post-translations` is the localized child.** `translates: { parent: posts,
+  on: slug }` needs `localized: true`, at least one content field besides
+  `slug` and `locale`, and a parent that exists and is not itself localized.
+  Admin uses it to group translations under their post.
+- **`locale` is a plain field in 0.2.0.** `localized` is presentation
+  metadata: Store does not check a row's `locale` against the site's locales.
+  Validate it in the Procedure or guard that writes it if it matters.
+- **Published-only is injected.** Both public Views read a `publishing`
+  Schema, so drafts and archived rows never appear, and the SQL does not test
+  `status`.
+- **Search is `mantle.search`** over `searchableFields`, a trigram full-text
+  index, so a three-character Chinese substring matches. A shorter query falls
+  back to a scan. `mantle.search_rank` orders by relevance; the trailing `t.id`
+  is the tiebreak a cursor needs. `publishedAt` is a display time set by
+  editors; nothing publishes a draft at that time.
+
+### The single-Schema alternative
+
+One localized `posts` Schema with `uniqueIndexes: [[slug, locale]]` and no
+parent also works: each locale row is independent, and only the slug
+convention links them. Choose it when translations share no fields and editors
+do not need to see which languages are missing. Both shapes serve the same
+`published-posts` View.
+
+## Handlers
+
+None.
+
+## Rendering
+
+0.2.0 has no Mantle-rendered public pages; `createWebSurface` is not ported.
+Render `/en/posts/<slug>` from the service's own `fetch` (or any frontend) over
+the REST View, escape every field, and render `body` from Markdown with HTML
+disabled.
+
+## Try it
+
+```sh
+curl -sS 'http://127.0.0.1:8787/api/views/published-posts?locale=en&limit=10'
+curl -sS 'http://127.0.0.1:8787/api/views/search-posts?locale=en&q=index'
+curl -sS -X POST http://127.0.0.1:8787/api/post-suggestions \
+  -H 'content-type: application/json' \
+  -d '{"title":"Write about indexes","email":"reader@example.test"}'
+```
+
+A View answers `{ "rows": [...], "nextCursor": "…" }`; pass `cursor` back for
+the next page. Leaving out `locale` is HTTP 400 `INPUT_VALIDATION_FAILED`.
+
+| MCP surface | Tool | From |
+|---|---|---|
+| `/mcp` | `published_posts`, `search_posts` (plus `limit` and `cursor`) | the public Views |
+
+There is no `submit_post_suggestion` tool, because no MCP Trigger targets that
+Procedure. Editors write posts through Admin's API, not through generated
+record tools.
+
+## What this leaves out
+
+- **Comments.** Another operational Schema with its own moderation Procedures.
+- **Scheduled publishing.** A schedule Trigger whose `ref` handler sets
+  `status` with `ctx.store.write` could do it; SQL cannot set `status`.
+
+## Source
+
+- [Schema reference](../handbook/reference/schema.md) and [View reference](../handbook/reference/view.md): `localized`, `translates`, `searchableFields`, `input`
+- [Lifecycle and locales](../handbook/concepts/lifecycle-and-locales.md)

package/docs/examples/reference-service/.dev.vars.example

@@ -0,0 +1,4 @@
+# Copy to .dev.vars for local sign-in: one-time codes are printed to the wrangler log. Never deploy these values.
+PUBLIC_ORIGIN=http://127.0.0.1:8787
+ADMIN_EMAIL=you@example.com
+BETTER_AUTH_SECRET=replace-with-a-random-32-byte-secret

package/docs/examples/reference-service/.mantle/generated/mantle.ts

@@ -0,0 +1,174 @@
+// Generated by `mantle generate`. Do not edit by hand.
+import type { Caller, HandlerContext, InvocationCause, MantleStore, StoreDelete, StoreInsert, StoreRow, StoreSelect, StoreSelectResult, StoreUpdate, StoreViewOptions, StoreWriteResult } from "@aotter/mantle";
+import type { ContentState, RuntimePlan } from "@aotter/mantle/spec";
+import planFile from "./plan.json" with { type: "json" };
+
+/** The sealed plan, for `createMantle(service, { plan })`. */
+export const plan = planFile.plan as unknown as RuntimePlan;
+/** SHA-256 of the manifest sources the plan was compiled from; not part of the fingerprint. */
+export const sourceHash: string = planFile.sourceHash;
+
+export namespace Mantle {
+
+  /** Entry data for Schema 'items' */
+  export interface Entry_items {
+    sku: string;
+    name: string;
+    priceCents?: number;
+    stock: number;
+    [key: string]: unknown;
+  }
+
+  /** Entry data for Schema 'orders' */
+  export interface Entry_orders {
+    owner: string;
+    itemId: string;
+    qty: number;
+    orderStatus: "placed" | "cancelled";
+    placedAt?: string;
+    [key: string]: unknown;
+  }
+
+  /** Entry data for Schema 'activity' */
+  export interface Entry_activity {
+    kind: string;
+    subject: string;
+    detail?: string;
+    [key: string]: unknown;
+  }
+
+  /** Procedure 'place-order' input */
+  export interface ProcInput_place_u002d_order {
+    itemId: string;
+    qty: number;
+    [key: string]: unknown;
+  }
+
+  /** Procedure 'place-order' output */
+  export interface ProcOutput_place_u002d_order {
+    [key: string]: unknown;
+  }
+
+  /** Procedure 'cancel-order' input */
+  export interface ProcInput_cancel_u002d_order {
+    orderId: string;
+    expectedVersion: number;
+    [key: string]: unknown;
+  }
+
+  /** Procedure 'cancel-order' output */
+  export interface ProcOutput_cancel_u002d_order {
+    [key: string]: unknown;
+  }
+
+  /** Procedure 'restock' input */
+  export interface ProcInput_restock {
+    sku: string;
+    name: string;
+    qty: number;
+    [key: string]: unknown;
+  }
+
+  /** Procedure 'restock' output */
+  export interface ProcOutput_restock {
+    [key: string]: unknown;
+  }
+
+  /** Procedure 'record-orders' input */
+  export interface ProcInput_record_u002d_orders {
+    [key: string]: unknown;
+  }
+
+  /** Procedure 'record-orders' output */
+  export interface ProcOutput_record_u002d_orders {
+    [key: string]: unknown;
+  }
+
+  /** Procedure 'weekly-digest' input */
+  export interface ProcInput_weekly_u002d_digest {
+    [key: string]: unknown;
+  }
+
+  /** Procedure 'weekly-digest' output */
+  export interface ProcOutput_weekly_u002d_digest {
+    [key: string]: unknown;
+  }
+
+  /** Row shape returned by View 'catalog' */
+  export type ViewRow_catalog = { readonly "id": unknown; readonly "sku": NonNullable<Entry_items["sku"]> | null; readonly "name": NonNullable<Entry_items["name"]> | null; readonly "priceCents": NonNullable<Entry_items["priceCents"]> | null; readonly "stock": NonNullable<Entry_items["stock"]> | null; };
+
+  /** Input accepted by View 'search-items' */
+  export type ViewInput_search_u002d_items = {
+  q: string;
+  [key: string]: unknown;
+};
+
+  /** Row shape returned by View 'search-items' */
+  export type ViewRow_search_u002d_items = { readonly "id": unknown; readonly "name": NonNullable<Entry_items["name"]> | null; readonly "stock": NonNullable<Entry_items["stock"]> | null; };
+
+  /** Row shape returned by View 'my-orders' */
+  export type ViewRow_my_u002d_orders = { readonly "id": unknown; readonly "qty": NonNullable<Entry_orders["qty"]> | null; readonly "orderStatus": NonNullable<Entry_orders["orderStatus"]> | null; readonly "item": NonNullable<Entry_items["name"]> | null; readonly "version": unknown; };
+
+  /** Row shape returned by View 'sales-by-item' */
+  export type ViewRow_sales_u002d_by_u002d_item = { readonly "name": NonNullable<Entry_items["name"]> | null; readonly "orders": unknown; readonly "units": unknown; };
+
+  /** Row shape returned by View 'recent-activity' */
+  export type ViewRow_recent_u002d_activity = { readonly "kind": NonNullable<Entry_activity["kind"]> | null; readonly "subject": NonNullable<Entry_activity["subject"]> | null; readonly "detail": NonNullable<Entry_activity["detail"]> | null; };
+
+}
+
+export interface Schemas {
+  readonly "activity": Mantle.Entry_activity;
+  readonly "items": Mantle.Entry_items;
+  readonly "orders": Mantle.Entry_orders;
+}
+/** Optional fields: omitted, a value, or `null` to leave or make them empty. */
+type Nullable<T> = { readonly [K in keyof T]?: T[K] | null };
+type InsertValues = {
+  readonly "activity": Pick<Schemas["activity"], "kind" | "subject"> & Nullable<Pick<Schemas["activity"], "detail">>;
+  readonly "items": Pick<Schemas["items"], "sku" | "name"> & Partial<Pick<Schemas["items"], "stock">> & Nullable<Pick<Schemas["items"], "priceCents">>;
+  readonly "orders": Pick<Schemas["orders"], "itemId" | "qty" | "orderStatus"> & Nullable<Pick<Schemas["orders"], "placedAt">>;
+};
+type UpdateSet = {
+  readonly "activity": Partial<InsertValues["activity"]>;
+  readonly "items": Partial<InsertValues["items"]>;
+  readonly "orders": Partial<InsertValues["orders"]>;
+};
+
+export interface Views {
+  readonly "catalog": { readonly input: undefined; readonly row: Mantle.ViewRow_catalog; readonly required: false };
+  readonly "my-orders": { readonly input: undefined; readonly row: Mantle.ViewRow_my_u002d_orders; readonly required: false };
+  readonly "recent-activity": { readonly input: undefined; readonly row: Mantle.ViewRow_recent_u002d_activity; readonly required: false };
+  readonly "sales-by-item": { readonly input: undefined; readonly row: Mantle.ViewRow_sales_u002d_by_u002d_item; readonly required: false };
+  readonly "search-items": { readonly input: Mantle.ViewInput_search_u002d_items; readonly row: Mantle.ViewRow_search_u002d_items; readonly required: true };
+}
+
+/** Views page with `limit` and `cursor`; `search` and `filters` match the View's `uiSchema.list` fields (ADR-0032 decision 5). */
+export type ViewOptions<N extends keyof Views> = { readonly limit?: number; readonly cursor?: string } & Pick<StoreViewOptions, "search" | "filters"> &
+  (Views[N]["input"] extends undefined ? {} : Views[N]["required"] extends true ? { readonly input: Views[N]["input"] } : { readonly input?: Views[N]["input"] });
+type Write = { [N in keyof Schemas & string]:
+  | (Omit<StoreInsert, "insert" | "values"> & { readonly insert: N; readonly values: InsertValues[N] })
+  | (Omit<StoreUpdate, "update" | "set"> & { readonly update: N; readonly set: UpdateSet[N] })
+  | (Omit<StoreDelete, "delete"> & { readonly delete: N })
+}[keyof Schemas & string];
+
+/** `runtime.store`, typed over this plan's Schemas and Views. */
+export type Store = Omit<MantleStore, "as" | "select" | "write" | "view"> & {
+  as(caller: Caller, cause?: InvocationCause): CallerStore;
+  select(query: Omit<StoreSelect, "from"> & { readonly from: "activity" }): Promise<StoreSelectResult<StoreRow & Partial<Schemas["activity"]>>>;
+  select(query: Omit<StoreSelect, "from"> & { readonly from: "items" }): Promise<StoreSelectResult<StoreRow & Partial<Schemas["items"]>>>;
+  select(query: Omit<StoreSelect, "from"> & { readonly from: "orders" }): Promise<StoreSelectResult<StoreRow & Partial<Schemas["orders"]>>>;
+  write(ops: readonly Write[]): Promise<readonly StoreWriteResult[]>;
+  view<N extends keyof Views & string>(name: N, ...options: Views[N]["required"] extends true ? [ViewOptions<N>] : [ViewOptions<N>?]): Promise<StoreSelectResult<Views[N]["row"]>>;
+};
+/** `ctx.store`: scope follows the caller. `sweepExpired` is present only for the system caller (a schedule Trigger). */
+export type CallerStore = Omit<Store, "as" | "sweepExpired"> & { readonly sweepExpired?: Store["sweepExpired"] };
+
+/** A handler receives this plan's typed `ctx.store`. */
+export type Handler<I, O, Env = unknown> = (input: I, ctx: Omit<HandlerContext<Env>, "store"> & { readonly store: CallerStore }) => O | Promise<O>;
+/** Exactly the plan's handler refs: a missing or an extra one is a type error. */
+export type MantleHandlers<Env = unknown> = {
+  readonly "cancelOrder": Handler<Mantle.ProcInput_cancel_u002d_order, Mantle.ProcOutput_cancel_u002d_order, Env>;
+  readonly "recordOrders": Handler<Mantle.ProcInput_record_u002d_orders, Mantle.ProcOutput_record_u002d_orders, Env>;
+  readonly "weeklyDigest": Handler<Mantle.ProcInput_weekly_u002d_digest, Mantle.ProcOutput_weekly_u002d_digest, Env>;
+};