@aotter/mantle 0.2.0-alpha.6 → 0.2.0-alpha.7

package/docs/examples/commerce-inventory.md

@@ -1,498 +0,0 @@
----
-description: A guest checkout that re-prices on the server, reserves stock atomically in Store, expires unpaid orders on a schedule and settles from a verified payment callback.
----
-# Commerce inventory: reservations, expiry and settlement
-
-[Examples hub](./README.md) · Without stock or payments, this is [Commerce catalog and orders](./commerce.md).
-
-The most involved pattern here. Staff publish a catalog. A guest's order is
-re-priced on the server and reserves stock; payment arrives later from a
-provider callback, never from the browser; an unpaid order is released after
-fifteen minutes. Every stock change writes an audit row in the same atomic
-write.
-
-## Problem
-
-Stock must never go negative, two guests must never buy the last unit, and an
-order, its reservation and its audit rows must change together or not at all.
-Staff adjust stock, fulfil paid orders and read a picking list.
-
-In 0.1.x this needed a Durable Object as the stock authority and a Queue for
-expiry. In 0.2.0 Store is enough: a `write` applies all its operations or none,
-`checks` refuse a negative count in the database, and an optimistic lock on
-each inventory row turns a race into a `CONFLICT` the client retries.
-
-## Manifest
-
-```yaml
-apiVersion: cms.mantle.aotter.net/v2
-kind: Schema
-metadata: { name: products }
-spec:
-  title: Products
-  lifecycle: publishing
-  uniqueIndexes: [[slug]]
-  schema:
-    type: object
-    additionalProperties: false
-    required: [slug, title, priceMinor, currency]
-    properties:
-      slug: { type: string, maxLength: 120, pattern: "^[a-z0-9-]+$" }
-      title: { type: string, minLength: 1, maxLength: 160 }
-      summary: { type: string, maxLength: 500 }
-      priceMinor: { type: integer, minimum: 0, x-mcp-hint: money-minor }
-      currency: { type: string, pattern: "^[A-Z]{3}$" }
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Schema
-metadata: { name: inventory }
-spec:
-  title: Inventory
-  description: Stock per product. Only the declared Procedures change it.
-  lifecycle: operational
-  checks: ["available >= 0", "reserved >= 0"]
-  uniqueIndexes: [[productSlug]]
-  uiSchema:
-    list: { primaryField: productSlug, columns: [available, reserved] }
-  schema:
-    type: object
-    readOnly: true
-    required: [productSlug, available, reserved]
-    properties:
-      productSlug: { type: string, x-mantle-ref: { schema: products, field: slug } }
-      available: { type: integer }
-      reserved: { type: integer }
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Schema
-metadata: { name: inventory-movements }
-spec:
-  title: Inventory movements
-  description: Append-only audit trail, written in the same write as each stock change.
-  lifecycle: operational
-  uniqueIndexes: [[movementKey]]
-  indexes: [[productSlug], [orderToken]]
-  schema:
-    type: object
-    readOnly: true
-    required: [movementKey, productSlug, kind, availableDelta, reservedDelta]
-    properties:
-      movementKey: { type: string }
-      productSlug: { type: string }
-      orderToken: { type: string }
-      kind: { type: string, enum: [adjust, reserve, sale, release] }
-      availableDelta: { type: integer }
-      reservedDelta: { type: integer }
-      note: { type: string }
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Schema
-metadata: { name: orders }
-spec:
-  title: Orders
-  description: Guest orders, written only by the declared Procedures.
-  lifecycle: operational
-  uniqueIndexes: [[orderToken]]
-  indexes: [[orderStatus, expiresAt]]
-  searchableFields: [orderToken, customerName, customerEmail]
-  uiSchema:
-    list: { primaryField: orderToken, columns: [orderStatus, customerEmail, totalMinor] }
-  schema:
-    type: object
-    readOnly: true
-    required: [orderToken, orderStatus, currency, totalMinor, customerName, customerEmail, shippingAddress, items, expiresAt]
-    properties:
-      orderToken: { type: string }
-      orderStatus: { type: string, enum: [pending_payment, paid, fulfilled, cancelled] }
-      currency: { type: string, pattern: "^[A-Z]{3}$" }
-      totalMinor: { type: integer, minimum: 0, x-mcp-hint: money-minor }
-      customerName: { type: string, minLength: 1, maxLength: 120 }
-      customerEmail: { type: string, format: email }
-      shippingAddress: { type: string, minLength: 1, maxLength: 500 }
-      items:
-        type: array
-        items:
-          type: object
-          required: [productSlug, title, quantity, unitPriceMinor]
-          properties:
-            productSlug: { type: string }
-            title: { type: string }
-            quantity: { type: integer, minimum: 1 }
-            unitPriceMinor: { type: integer, minimum: 0 }
-      expiresAt: { type: string, format: date-time }
-      trackingNumber: { type: string }
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: View
-metadata: { name: public-products }
-spec:
-  surface: public
-  description: The published catalog with what is in stock.
-  sql: |
-    SELECT p.id, p.slug, p.title, p.summary, p.priceMinor, p.currency, coalesce(i.available, 0) AS available
-    FROM products p LEFT JOIN inventory i ON i.productSlug = p.slug
-    ORDER BY p.slug LIMIT 100
----
-# Internal: no surface lists it. The expiry handler reads it; SQL compares the times.
-apiVersion: cms.mantle.aotter.net/v2
-kind: View
-metadata: { name: expired-orders }
-spec:
-  surface: internal
-  sql: |
-    SELECT id, version, orderToken, items FROM orders
-    WHERE orderStatus = 'pending_payment' AND expiresAt < now()
-    ORDER BY expiresAt LIMIT 100
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: View
-metadata: { name: picking-list }
-spec:
-  title: Picking list
-  surface: staff
-  requires: { auth: { all: [{ ctx.staff: [owner, editor] }] } }
-  sql: |
-    SELECT o.orderToken, o.customerName, o.shippingAddress,
-           item.value ->> 'productSlug' AS "productSlug",
-           item.value ->> 'title' AS "productTitle",
-           item.value ->> 'quantity' AS quantity
-    FROM orders o, json_each(o.items) item
-    WHERE o.orderStatus = 'paid'
-    ORDER BY o.created_at LIMIT 200
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Procedure
-metadata: { name: place-order }
-spec:
-  title: Place order
-  description: Price a cart from the published catalog, reserve its stock and return a token to pay within fifteen minutes.
-  input:
-    type: object
-    additionalProperties: false
-    required: [customerName, customerEmail, shippingAddress, items]
-    properties:
-      customerName: { type: string, minLength: 1, maxLength: 120 }
-      customerEmail: { type: string, format: email }
-      shippingAddress: { type: string, minLength: 1, maxLength: 500 }
-      items:
-        type: array
-        minItems: 1
-        maxItems: 20
-        items:
-          type: object
-          additionalProperties: false
-          required: [productSlug, quantity]
-          properties:
-            productSlug: { type: string, maxLength: 120, pattern: "^[a-z0-9-]+$" }
-            quantity: { type: integer, minimum: 1, maximum: 99 }
-  output:
-    type: object
-    required: [orderToken, expiresAt, totalMinor, currency]
-    properties:
-      orderToken: { type: string }
-      expiresAt: { type: string }
-      totalMinor: { type: integer }
-      currency: { type: string }
-  handler: { ref: placeOrder }
----
-# No Trigger: only the service's verified payment callback calls it, as the system caller.
-apiVersion: cms.mantle.aotter.net/v2
-kind: Procedure
-metadata: { name: settle-order }
-spec:
-  input:
-    type: object
-    additionalProperties: false
-    required: [orderToken]
-    properties:
-      orderToken: { type: string }
-  output:
-    type: object
-    required: [outcome]
-    properties:
-      outcome: { type: string, enum: [paid, already_paid, expired, missing] }
-  handler: { ref: settleOrder }
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Procedure
-metadata: { name: release-expired-orders }
-spec:
-  input: { type: object }
-  output:
-    type: object
-    properties:
-      released: { type: integer }
-  handler: { ref: releaseExpiredOrders }
----
-# SQL is enough when a write needs no read first. The movement row comes first: a replayed operationId
-# fails its unique index, so the whole write is refused and the stock is not changed twice.
-apiVersion: cms.mantle.aotter.net/v2
-kind: Procedure
-metadata: { name: adjust-inventory }
-spec:
-  title: Adjust inventory
-  description: Add or remove available stock for one product, with a reason. Reuse the operationId on retry.
-  requires: { auth: { all: [{ ctx.staff: [owner] }] } }
-  input:
-    type: object
-    additionalProperties: false
-    required: [operationId, productSlug, delta, reason]
-    properties:
-      operationId: { type: string, format: uuid, x-mcp-hint: idempotency-key }
-      productSlug: { type: string, maxLength: 120, pattern: "^[a-z0-9-]+$", x-mantle-ref: { schema: products, field: slug } }
-      delta: { type: integer, minimum: -100000, maximum: 100000 }
-      reason: { type: string, minLength: 1, maxLength: 500 }
-  uiSchema:
-    fields:
-      reason: { widget: textarea }
-  output: { type: object }
-  handler:
-    sql: |
-      INSERT INTO "inventory-movements" (movementKey, productSlug, kind, availableDelta, reservedDelta, note)
-      VALUES (input.operationId, input.productSlug, 'adjust', input.delta, 0, input.reason);
-      INSERT INTO inventory (productSlug, available, reserved) VALUES (input.productSlug, input.delta, 0)
-      ON CONFLICT (productSlug) DO UPDATE SET available = inventory.available + EXCLUDED.available
-      RETURNING productSlug AS "productSlug", available, reserved
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Procedure
-metadata: { name: fulfill-order }
-spec:
-  title: Fulfill order
-  description: Mark a paid order fulfilled, with an optional tracking number.
-  requires: { auth: { all: [{ ctx.staff: [owner, editor] }] } }
-  input:
-    type: object
-    additionalProperties: false
-    required: [id, expectedVersion]
-    properties:
-      id: { type: string, x-mantle-ref: orders }
-      expectedVersion: { type: integer, minimum: 1 }
-      trackingNumber: { type: string, maxLength: 120 }
-  output: { type: object }
-  handler:
-    sql: |
-      UPDATE orders SET orderStatus = 'fulfilled', trackingNumber = COALESCE(input.trackingNumber, trackingNumber)
-      WHERE id = input.id AND version = input.expectedVersion AND orderStatus = 'paid'
-      RETURNING id, version
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Trigger
-metadata: { name: place-order-http }
-spec:
-  source: { kind: http, method: POST, path: /api/commerce/orders }
-  target: { procedure: place-order }
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Trigger
-metadata: { name: adjust-inventory-mcp }
-spec:
-  source: { kind: mcp, surface: staff }
-  target: { procedure: adjust-inventory }
----
-apiVersion: cms.mantle.aotter.net/v2
-kind: Trigger
-metadata: { name: fulfill-order-mcp }
-spec:
-  source: { kind: mcp, surface: staff }
-  target: { procedure: fulfill-order }
----
-# POSIX cron, UTC: every five minutes.
-apiVersion: cms.mantle.aotter.net/v2
-kind: Trigger
-metadata: { name: release-expired-orders }
-spec:
-  source: { kind: schedule, cron: "*/5 * * * *" }
-  target: { procedure: release-expired-orders }
-```
-
-Points worth noticing:
-
-- **Root `readOnly: true`** on `orders`, `inventory` and `inventory-movements`
-  keeps Admin from offering generic edits. Only the declared Procedures change
-  them.
-- **`checks` are the last line.** The handlers compute new counts from rows
-  they read under a lock, so a race is a `CONFLICT`; the checks make a negative
-  count impossible whatever writes the row.
-- **`settle-order` and `release-expired-orders` have no HTTP or MCP Trigger.**
-  The schedule runs the second as the system caller, and only the service's own
-  callback route invokes the first. A system caller satisfies no
-  `requires.auth` predicate, so both declare none.
-- **`expired-orders` is `internal`:** callable only through
-  `ctx.store.view` or `runtime.store`. SQL compares `expiresAt` with `now()`.
-- **`picking-list`** unnests order lines with `json_each`, the one comma join
-  the D1 dialect allows. This example's SQL is D1 (SQLite) SQL. On PostgreSQL
-  the same View reads:
-
-  ```sql
-  SELECT o.orderToken, o.customerName, o.shippingAddress,
-         item.value ->> 'productSlug' AS "productSlug",
-         item.value ->> 'title' AS "productTitle",
-         item.value ->> 'quantity' AS quantity
-  FROM orders o, jsonb_array_elements(o.items) WITH ORDINALITY AS item(value, n)
-  WHERE o.orderStatus = 'paid'
-  ORDER BY o.created_at, item.n LIMIT 200
-  ```
-
-  `jsonb_array_elements_text(o.items) WITH ORDINALITY AS j(value, n)` is the
-  form for text elements. A sorted View over a row source needs the alias and
-  `WITH ORDINALITY`; Mantle pages by `n`. The
-  [rewrite table](../handbook/concepts/runtime-and-adapters.md#the-postgresql-dialect)
-  lists the other SQLite spellings PostgreSQL refuses.
-
-## Handlers
-
-```ts
-// src/handlers.ts
-import { DiagnosticError, runtimeDiagnostic } from "@aotter/mantle";
-import type { MantleHandlers } from "../.mantle/generated/mantle.js";
-import type { Env } from "./service.js";
-
-const CHECKOUT_TTL_MS = 15 * 60 * 1000;
-type Line = { readonly productSlug: string; readonly quantity: number };
-type Ctx = Parameters<MantleHandlers<Env>["placeOrder"]>[1];
-type Op = Parameters<Ctx["store"]["write"]>[0][number];
-
-const fail = (code: "CONFLICT" | "INPUT_VALIDATION_FAILED", path: string, message: string): never => {
-  throw new DiagnosticError(runtimeDiagnostic({ code, severity: "error", path, message }));
-};
-
-/** One locked update per product, plus its audit row: every count comes from a row read here, so a race is a CONFLICT. */
-async function stockOps(ctx: Ctx, lines: readonly Line[], kind: "reserve" | "sale" | "release", orderToken: string): Promise<Op[]> {
-  const qty = new Map<string, number>();
-  for (const l of lines) qty.set(l.productSlug, (qty.get(l.productSlug) ?? 0) + l.quantity);
-  const { rows } = await ctx.store.select({ from: "inventory", where: { productSlug: { in: [...qty.keys()] } } });
-  const ops: Op[] = [];
-  for (const [slug, q] of qty) {
-    const row = rows.find((r) => r.productSlug === slug) ?? fail("INPUT_VALIDATION_FAILED", "/items", `no stock record for ${slug}`);
-    const [availableDelta, reservedDelta] = kind === "reserve" ? [-q, q] : kind === "sale" ? [0, -q] : [q, -q];
-    ops.push(
-      { update: "inventory", set: { available: Number(row.available) + availableDelta, reserved: Number(row.reserved) + reservedDelta }, where: { id: String(row.id) }, lock: Number(row.version) },
-      { insert: "inventory-movements", values: { movementKey: `${orderToken}:${kind}:${slug}`, productSlug: slug, orderToken, kind, availableDelta, reservedDelta } },
-    );
-  }
-  return ops;
-}
-
-export const handlers: MantleHandlers<Env> = {
-  placeOrder: async (input, ctx) => {
-    // re-price from published products only; a draft or unknown slug is refused
-    const slugs = [...new Set(input.items.map((l) => l.productSlug))];
-    const { rows: products } = await ctx.store.select({ from: "products", where: { slug: { in: slugs }, status: "published" } });
-    const lines = input.items.map((l) => {
-      const p = products.find((r) => r.slug === l.productSlug) ?? fail("INPUT_VALIDATION_FAILED", "/items", `${l.productSlug} is not for sale`);
-      return { productSlug: l.productSlug, title: String(p.title), quantity: l.quantity, unitPriceMinor: Number(p.priceMinor), currency: String(p.currency) };
-    });
-    const currency = lines[0]!.currency;
-    if (lines.some((l) => l.currency !== currency)) fail("INPUT_VALIDATION_FAILED", "/items", "one order has one currency");
-    const totalMinor = lines.reduce((sum, l) => sum + l.unitPriceMinor * l.quantity, 0);
-    const orderToken = ctx.store.id();
-    const expiresAt = new Date(Date.now() + CHECKOUT_TTL_MS).toISOString();
-    // the order, the reservation and its audit rows: all or nothing. Too little stock fails a check; a race fails a lock.
-    await ctx.store.write([
-      { insert: "orders", values: {
-        orderToken, orderStatus: "pending_payment", currency, totalMinor, expiresAt,
-        customerName: input.customerName, customerEmail: input.customerEmail, shippingAddress: input.shippingAddress,
-        items: lines.map(({ currency: _c, ...line }) => line),
-      } },
-      ...(await stockOps(ctx, lines, "reserve", orderToken)),
-    ]);
-    return { orderToken, expiresAt, totalMinor, currency };
-  },
-
-  settleOrder: async ({ orderToken }, ctx) => {
-    const [order] = (await ctx.store.select({ from: "orders", where: { orderToken } })).rows;
-    if (!order) return { outcome: "missing" };
-    if (order.orderStatus !== "pending_payment") return { outcome: order.orderStatus === "cancelled" ? "expired" : "already_paid" };
-    const lines = order.items as unknown as Line[];
-    // a payment that lands after the deadline releases the stock instead of selling it; the provider refunds
-    const late = Date.parse(String(order.expiresAt)) <= Date.now();
-    await ctx.store.write([
-      { update: "orders", set: { orderStatus: late ? "cancelled" : "paid" }, where: { id: String(order.id) }, lock: Number(order.version) },
-      ...(await stockOps(ctx, lines, late ? "release" : "sale", orderToken)),
-    ]);
-    return { outcome: late ? "expired" : "paid" };
-  },
-
-  // runs as the system caller every five minutes; one write per order, so one CONFLICT never blocks the rest
-  releaseExpiredOrders: async (_input, ctx) => {
-    const { rows } = await ctx.store.view("expired-orders");
-    let released = 0;
-    for (const order of rows) {
-      try {
-        await ctx.store.write([
-          { update: "orders", set: { orderStatus: "cancelled" }, where: { id: String(order.id) }, lock: Number(order.version) },
-          ...(await stockOps(ctx, order.items as unknown as Line[], "release", String(order.orderToken))),
-        ]);
-        released++;
-      } catch (error) {
-        // a payment settled it first, or a stock row changed: the next run reads it again
-        if (!(error instanceof DiagnosticError && error.diagnostic.code === "CONFLICT")) throw error;
-      }
-    }
-    return { released };
-  },
-};
-```
-
-## The payment callback
-
-A provider signs its callback over the raw body, so it is verified in the
-service's own `fetch`, before any surface. Only a verified event reaches
-`settle-order`, as the system caller. In `src/service.ts`:
-
-```ts
-import { systemCaller } from "@aotter/mantle";
-
-// inside the function the service's fetch returns, before the auth routes:
-if (pathname === "/payments/callback" && request.method === "POST") {
-  const raw = await request.text();
-  const event = await verifyProviderEvent(raw, request.headers.get("x-provider-signature"), env.PAYMENT_WEBHOOK_SECRET);
-  if (!event) return new Response("invalid signature", { status: 400 });
-  if (event.type !== "payment.succeeded") return new Response("ignored");
-  await runtime.invokeProcedure({
-    procedure: "settle-order",
-    input: { orderToken: event.orderToken },
-    caller: systemCaller("payment-callback"),
-    cause: { kind: "internal", id: event.id }, // the provider's event id: stable across its retries
-  });
-  return new Response("OK"); // paid, already_paid, expired and missing are all final for the provider
-}
-```
-
-`verifyProviderEvent` is the provider SDK's signature check, with
-`PAYMENT_WEBHOOK_SECRET` as a Worker secret. A thrown `CONFLICT` (a
-concurrent expiry) answers 500 here, so the provider retries and the next
-attempt reads the settled state.
-
-## Try it
-
-```sh
-curl -sS -X POST http://127.0.0.1:8787/api/commerce/orders \
-  -H 'content-type: application/json' \
-  -d '{"customerName":"Ada","customerEmail":"ada@example.test","shippingAddress":"1 Shell Lane","items":[{"productSlug":"notebook","quantity":2}]}'
-```
-
-The answer carries `orderToken`, `expiresAt`, and the total from the
-published price. An unknown or unpublished product is HTTP 400. Ordering more
-than is available fails the `available >= 0` check, also HTTP 400 (`CHECK
-inventory: available >= 0`), and writes nothing. Two guests racing for one
-row: one succeeds, the other gets `CONFLICT` and retries.
-
-Staff, on `/mcp/staff`: `adjust_inventory` (Admin generates the
-`operationId`), `fulfill_order` and `picking_list`. Fire the schedule locally
-with `curl 'http://127.0.0.1:8787/__scheduled?cron=*/5+*+*+*+*'` under
-`wrangler dev --test-scheduled`.
-
-## What this leaves out
-
-- **Refunds.** A late payment releases stock; refunding it is the provider's
-  API, from a `ref` handler.
-- **Guest cancellation.** It would be one more Procedure shaped like
-  `settleOrder` with `"release"`, authorized by the order token.
-- **More than 100 expired orders per run.** The next run takes the rest.
-
-## Source
-
-- [Writes: Procedures, Triggers and hooks](../handbook/concepts/procedures-and-triggers.md): atomic writes, locks, schedules
-- [The service and its entry](../handbook/cloudflare/service-entry.md): a route before the surfaces