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

package/docs/examples/club-events/manifests/club-events.yaml

@@ -0,0 +1,247 @@
+# Club events: officers (admin) create events in Admin; signed-in members register and cancel their own seats.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: events }
+spec:
+  title: Events
+  lifecycle: operational
+  # Registering adds to seats_taken in the same program as the insert: past capacity the check fails and the insert rolls back.
+  # It also refuses an officer lowering capacity below the seats already taken.
+  checks: ["seats_taken <= capacity"]
+  indexes: [[startsAt, id]]
+  uiSchema: { list: { primaryField: title, columns: [startsAt, capacity, seats_taken, closed] } }
+  schema:
+    type: object
+    required: [title, startsAt, capacity, closed]
+    properties:
+      title: { type: string, minLength: 1 }
+      startsAt: { type: string, format: date-time }
+      capacity: { type: integer, minimum: 0, title: Capacity }
+      # readOnly: server-maintained. Admin's generic create/edit never writes it; only register/cancel change it.
+      seats_taken: { type: integer, minimum: 0, default: 0, readOnly: true, title: Seats taken }
+      closed: { type: boolean, default: false }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: registrations }
+spec:
+  title: Registrations
+  lifecycle: operational
+  # No `scope` here: a field scope would hide rows from officers too. Members are narrowed by `restrict` below.
+  # `member` is written by the register handler from the caller; native authorId cannot be in a unique index.
+  uniqueIndexes: [[eventId, member]]
+  indexes: [[authorId, createdAt, id]]
+  # Officers read registrations in Admin; generic edits would bypass seats_taken, so writes go through the Procedures.
+  uiSchema: { list: { primaryField: eventId, columns: [memberName] } }
+  schema:
+    type: object
+    readOnly: true
+    required: [eventId, member]
+    properties:
+      eventId: { type: string, x-mantle-ref: events }
+      member: { type: string }
+      # A snapshot of the member's name at sign-up, so officers see who registered (member is an opaque id).
+      memberName: { type: string, maxLength: 200 }
+---
+# The sign-up allowlist: officers add members in Admin; src/signup.ts lets only these emails create an account.
+# No View or Trigger reads it, so it stays out of the public API and MCP.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: { name: members }
+spec:
+  title: Members
+  lifecycle: operational
+  uniqueIndexes: [[email]]
+  # Better Auth lowercases emails; the check refuses a mixed-case entry that would never match.
+  checks: ["email = lower(email)"]
+  uiSchema: { list: { primaryField: email, columns: [name] } }
+  schema:
+    type: object
+    required: [email]
+    properties:
+      email: { type: string, format: email, maxLength: 254, title: Email }
+      name: { type: string, maxLength: 200, title: Name }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: events }
+spec:
+  surface: public
+  description: Upcoming club events with the seats still available.
+  requires: { auth: { all: [ctx.user] } }
+  sql: |
+    SELECT id, title, startsAt AS "startsAt", capacity - seats_taken AS seats_left, closed FROM events ORDER BY startsAt, id
+---
+# Only the caller's own rows: restrict narrows registrations to author_id = the caller.
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: my-registrations }
+spec:
+  surface: public
+  description: The signed-in member's registrations.
+  requires: { auth: { all: [ctx.user] } }
+  restrict: { registrations: "author_id = auth.uid()" }
+  sql: |
+    SELECT r.id, r.eventId AS "eventId", e.title, e.startsAt AS "startsAt"
+    FROM registrations r JOIN events e ON e.id = r.eventId
+    ORDER BY r.created_at DESC, r.id DESC
+---
+# Officers' roster: each event with its attendees as one JSON array, so one read answers "who is coming".
+# The correlated subquery gives [] for an event nobody registered for (a LEFT JOIN + GROUP BY would give one empty object).
+# SQLite/D1 builds the objects with json_set; on PostgreSQL write jsonb_agg(jsonb_build_object('memberName', r.memberName)).
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: { name: event-roster }
+spec:
+  title: Event roster
+  surface: admin
+  requires: { auth: { all: [ctx.admin] } }
+  sql: |
+    SELECT e.id, e.title, e.startsAt AS "startsAt", e.seats_taken AS "seatsTaken",
+      (SELECT json_group_array(json_set('{}', '$.memberName', r.memberName)) FROM registrations r WHERE r.eventId = e.id) AS attendees
+    FROM events e ORDER BY e.startsAt, e.id
+---
+# The member-facing entry: a ref handler checks the event, then runs register-write.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: register }
+spec:
+  title: Register for an event
+  description: Take one seat at a club event for the signed-in member. Fails when the event is closed, full or already registered.
+  requires: { auth: { all: [ctx.user] } }
+  input:
+    type: object
+    required: [eventId]
+    additionalProperties: false
+    properties:
+      eventId: { type: string }
+  output: { type: object }
+  handler: { ref: register }
+---
+# Internal (no Trigger): one program, so a failed seat check rolls back the insert too.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: register-write }
+spec:
+  requires: { auth: { all: [ctx.user] } }
+  input:
+    type: object
+    required: [eventId, member]
+    properties:
+      eventId: { type: string }
+      member: { type: string }
+      memberName: { type: string, maxLength: 200 }
+  output: { type: object }
+  handler:
+    sql: |
+      INSERT INTO registrations (eventId, member, memberName) VALUES (input.eventId, input.member, input.memberName) RETURNING id, eventId AS "eventId";
+      UPDATE events SET seats_taken = seats_taken + 1 WHERE id = input.eventId RETURNING capacity - seats_taken AS seats_left
+---
+# restrict: another member's registration is invisible here, so the UPDATE matches no row -> CONFLICT, nothing changes.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: cancel-registration }
+spec:
+  title: Cancel a registration
+  description: Cancel one of the signed-in member's registrations and return the seat.
+  requires: { auth: { all: [ctx.user] } }
+  restrict: { registrations: "author_id = auth.uid()" }
+  input:
+    type: object
+    required: [id]
+    additionalProperties: false
+    properties:
+      id: { type: string }
+  output: { type: object }
+  handler:
+    sql: |
+      UPDATE events SET seats_taken = seats_taken - 1 WHERE id = (SELECT eventId FROM registrations WHERE id = input.id) RETURNING capacity - seats_taken AS seats_left;
+      DELETE FROM registrations WHERE id = input.id RETURNING id
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: register-http }
+spec:
+  source: { kind: http, method: POST, path: /api/registrations }
+  target: { procedure: register }
+---
+# "Your AI" registers for the member over the member MCP endpoint (/mcp) with the member's own sign-in.
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: register-mcp }
+spec:
+  source: { kind: mcp, surface: public }
+  target: { procedure: register }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: cancel-registration-http }
+spec:
+  source: { kind: http, method: POST, path: /api/registrations/cancel }
+  target: { procedure: cancel-registration }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: cancel-registration-mcp }
+spec:
+  source: { kind: mcp, surface: public }
+  target: { procedure: cancel-registration }
+---
+# Officers add records through declared Procedures: operational collections have no generic create in Admin.
+# collectionAction puts the Procedure's button and input form in that collection's list header; the admin MCP
+# Trigger is what makes it an Admin operation (and lets the officers' AI do the same).
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: create-event }
+spec:
+  title: New event
+  description: Create a club event with its capacity.
+  requires: { auth: { all: [ctx.admin] } }
+  uiSchema: { collectionAction: events }
+  input:
+    type: object
+    required: [title, startsAt, capacity]
+    additionalProperties: false
+    properties:
+      title: { type: string, minLength: 1, maxLength: 200, title: Title }
+      startsAt: { type: string, format: date-time, title: Starts at }
+      capacity: { type: integer, minimum: 1, title: Capacity }
+  output: { type: object }
+  handler:
+    sql: |
+      INSERT INTO events (title, startsAt, capacity, closed, seats_taken) VALUES (input.title, input.startsAt, input.capacity, false, 0) RETURNING id
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Procedure
+metadata: { name: add-member }
+spec:
+  title: Add a member
+  description: Let an email sign up as a club member.
+  requires: { auth: { all: [ctx.admin] } }
+  uiSchema: { collectionAction: members }
+  input:
+    type: object
+    required: [email]
+    additionalProperties: false
+    properties:
+      email: { type: string, format: email, maxLength: 254, title: Email }
+      name: { type: string, maxLength: 200, title: Name }
+  output: { type: object }
+  handler:
+    # Better Auth lowercases emails, so the list stores them lowercased too.
+    sql: |
+      INSERT INTO members (email, name) VALUES (lower(input.email), input.name) RETURNING id
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: create-event-admin }
+spec:
+  source: { kind: mcp, surface: admin }
+  target: { procedure: create-event }
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: Trigger
+metadata: { name: add-member-admin }
+spec:
+  source: { kind: mcp, surface: admin }
+  target: { procedure: add-member }

package/docs/examples/club-events/smoke.mjs

@@ -0,0 +1,127 @@
+// Club events acceptance: only listed members sign up; officers create events in Admin, members register/cancel their own seats over REST and MCP.
+import assert from "node:assert/strict";
+import { smoke } from "./smoke-kit.mjs";
+
+await smoke(async ({ call, mcp, signIn, sql, owner, step, logs }) => {
+  assert.equal((await call("POST", "/api/registrations", { body: { eventId: "x" } })).status, 401);
+  assert.equal((await call("GET", "/api/views/events")).status, 401);
+  step("anonymous: register and the event list are 401");
+
+  const admin = await signIn(owner);
+  assert.equal((await call("GET", "/admin/api/me", { cookie: admin })).body.role.split(",")[0], "admin");
+  step("ADMIN_EMAIL signs in although the members list is empty, and becomes the officer (admin)");
+
+  // A verified email that is not on the list: the code is sent, but creating the account is refused.
+  const stranger = "stranger@example.test", ip = "198.51.100.7", logStart = logs().length;
+  assert.equal((await call("POST", "/api/auth/email-otp/send-verification-otp", { body: { email: stranger, type: "sign-in" }, ip })).status, 200);
+  let code;
+  for (let i = 0; i < 40 && !code; i++) {
+    code = /stranger@example\.test: one-time code is (\d{6})/.exec(logs().slice(logStart))?.[1];
+    if (!code) await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  assert.ok(code, "no one-time code for the stranger");
+  const refused = await call("POST", "/api/auth/sign-in/email-otp", { body: { email: stranger, otp: code }, ip });
+  assert.equal(refused.status, 403, JSON.stringify(refused.body));
+  assert.equal(refused.headers.getSetCookie().length, 0);
+  assert.equal((await sql(`SELECT count(*) AS n FROM user WHERE email = '${stranger}'`))[0].n, 0);
+  step("an email not on the members list cannot sign up: 403, no session cookie, no user row");
+
+  for (const name of ["alice", "bob", "carol", "dave", "erin", "frank"]) {
+    const added = await call("POST", "/admin/api/operations/add-member", { cookie: admin, body: { email: `${name}@example.test`, name } });
+    assert.equal(added.status, 200, JSON.stringify(added.body));
+  }
+  const mixed = await call("POST", "/admin/api/operations/add-member", { cookie: admin, body: { email: "Grace@example.test" } });
+  assert.equal(mixed.status, 200, JSON.stringify(mixed.body));
+  assert.equal((await sql("SELECT email FROM members WHERE email = 'grace@example.test'")).length, 1);
+  step("the officer adds members through the add-member operation in Admin (a mixed-case email is stored lowercased)");
+  const create = async (title, seats, closed = false) => {
+    const created = await call("POST", "/admin/api/operations/create-event", { cookie: admin, body: { title, startsAt: "2026-11-01T10:00:00Z", capacity: seats } });
+    assert.equal(created.status, 200, JSON.stringify(created.body));
+    if (!closed) return;
+    // Closing is an ordinary Admin edit: operational collections are editable, only creation needs a Procedure.
+    const id = created.body.output.results[0][0].id;
+    const { version } = (await call("GET", `/admin/api/entries/${id}?collection=events`, { cookie: admin })).body.entry;
+    assert.equal((await call("PATCH", `/admin/api/entries/${id}?collection=events`, { cookie: admin, body: { data: { closed: true }, expectedVersion: version } })).status, 200);
+  };
+  await create("Hike", 3);
+  await create("Workshop", 1);
+  await create("Members' dinner", 10, true);
+  step("an officer creates events through the create-event operation and closes one with an ordinary edit");
+
+  const alice = await signIn("alice@example.test");
+  const events = async cookie => Object.fromEntries((await call("GET", "/api/views/events", { cookie })).body.rows.map(e => [e.title, e]));
+  const { Hike: hike, Workshop: workshop, "Members' dinner": dinner } = await events(alice);
+  const seatsOf = async id => (await sql(`SELECT capacity - seats_taken AS seats_left FROM events WHERE id = '${id}'`))[0].seats_left;
+  const mine = async cookie => (await call("GET", "/api/views/my-registrations", { cookie })).body.rows;
+
+  const registered = await call("POST", "/api/registrations", { cookie: alice, body: { eventId: hike.id } });
+  assert.equal(registered.status, 200, JSON.stringify(registered.body));
+  assert.equal(await seatsOf(hike.id), 2);
+  assert.deepEqual((await mine(alice)).map(r => r.title), ["Hike"]);
+  step("a member registers: the insert and seats_left 3 -> 2 run in one program");
+
+  const twice = await call("POST", "/api/registrations", { cookie: alice, body: { eventId: hike.id } });
+  assert.equal(twice.status, 409, JSON.stringify(twice.body));
+  assert.equal(await seatsOf(hike.id), 2);
+  step("registering twice is 409 (uniqueIndexes [eventId, member]) and takes no seat");
+
+  assert.equal((await call("POST", "/api/registrations", { cookie: alice, body: { eventId: dinner.id } })).status, 409);
+  assert.equal((await call("POST", "/api/registrations", { cookie: alice, body: { eventId: "no-such-event" } })).status, 404);
+  step("the register handler checks first: a closed event is 409, a missing one 404");
+
+  const bob = await signIn("bob@example.test");
+  const [aliceHike] = await mine(alice);
+  assert.deepEqual(await mine(bob), []);
+  const foreign = await call("POST", "/api/registrations/cancel", { cookie: bob, body: { id: aliceHike.id } });
+  assert.equal(foreign.status, 409, JSON.stringify(foreign.body));
+  assert.equal((await sql(`SELECT count(*) AS n FROM registrations WHERE id = '${aliceHike.id}'`))[0].n, 1);
+  assert.equal(await seatsOf(hike.id), 2);
+  step("another member neither sees nor cancels it: cancel is 409, the row and seats_left are unchanged (restrict)");
+
+  const racers = [];
+  for (const name of ["carol", "dave", "erin", "frank"]) racers.push(await signIn(`${name}@example.test`));
+  const race = await Promise.all(racers.map(cookie => call("POST", "/api/registrations", { cookie, body: { eventId: workshop.id } })));
+  assert.deepEqual(race.map(r => r.status).sort(), [200, 409, 409, 409], JSON.stringify(race.map(r => r.body)));
+  assert.equal(await seatsOf(workshop.id), 0);
+  assert.equal((await sql(`SELECT count(*) AS n FROM registrations WHERE eventId = '${workshop.id}'`))[0].n, 1);
+  step("four members race for the last seat: exactly one wins, seats_left is 0, the losers' inserts rolled back");
+
+  const cancelled = await call("POST", "/api/registrations/cancel", { cookie: alice, body: { id: aliceHike.id } });
+  assert.equal(cancelled.status, 200, JSON.stringify(cancelled.body));
+  assert.equal(await seatsOf(hike.id), 3);
+  assert.deepEqual(await mine(alice), []);
+  step("the member cancels their own registration and the seat returns (2 -> 3)");
+
+  assert.ok((await mcp("/mcp", bob)).body.result.tools.some(t => t.name === "register"));
+  const viaAi = await mcp("/mcp", bob, "register", { eventId: hike.id });
+  assert.equal(viaAi.body.result?.isError, undefined, JSON.stringify(viaAi.body));
+  assert.equal(await seatsOf(hike.id), 2);
+  assert.deepEqual((await mine(bob)).map(r => r.title), ["Hike"]);
+  step("the member's AI registers through the public MCP tool `register`");
+
+  const all = await call("GET", "/admin/api/entries?collection=registrations", { cookie: admin });
+  assert.equal(all.status, 200, JSON.stringify(all.body));
+  assert.deepEqual(all.body.items.map(r => r.data.eventId).sort(), [hike.id, workshop.id].sort());
+  assert.equal((await call("GET", "/admin/api/entries?collection=registrations", { cookie: bob })).status, 403);
+  assert.equal((await call("GET", "/admin/api/me", { cookie: bob })).status, 403);
+  assert.ok(all.body.items.every(r => r.data.memberName && r.data.memberName !== r.data.member), JSON.stringify(all.body.items));
+  const roster = await call("GET", "/admin/api/views/event-roster", { cookie: admin });
+  assert.equal(roster.status, 200, JSON.stringify(roster.body));
+  const attendees = row => (typeof row.attendees === "string" ? JSON.parse(row.attendees) : row.attendees).map(a => a.memberName).sort();
+  for (const row of roster.body.rows) assert.equal(attendees(row).length, row.seatsTaken, JSON.stringify(row));
+  assert.ok(roster.body.rows.some(row => attendees(row).length > 0), JSON.stringify(roster.body.rows));
+  assert.equal((await call("GET", "/admin/api/views/event-roster", { cookie: bob })).status, 403);
+  step("officers see every member's registrations, with names, through Admin's API; and every event with its attendees as one JSON array (event-roster); a member gets 403 on Admin");
+
+  const entry = async id => (await call("GET", `/admin/api/entries/${id}?collection=events`, { cookie: admin })).body.entry;
+  const before = await seatsOf(hike.id), read = await entry(hike.id);
+  // The console saves whole records: an edit that echoes seats_taken (or tries to change it) only changes the other fields.
+  const edited = await call("PATCH", `/admin/api/entries/${hike.id}?collection=events`, { cookie: admin, body: { data: { ...read.data, title: "Hike (rescheduled)", seats_taken: 0 }, expectedVersion: read.version } });
+  assert.equal(edited.status, 200, JSON.stringify(edited.body));
+  assert.equal((await entry(hike.id)).data.title, "Hike (rescheduled)");
+  assert.equal(await seatsOf(hike.id), before);
+  const shrunk = await call("PATCH", `/admin/api/entries/${hike.id}?collection=events`, { cookie: admin, body: { data: { capacity: 0 }, expectedVersion: (await entry(hike.id)).version } });
+  assert.equal(shrunk.status, 409, JSON.stringify(shrunk.body));
+  assert.equal(await seatsOf(hike.id), before);
+  step("officers edit an event with the whole record; the server-maintained seats_taken is ignored, and capacity below the seats taken is 409");
+});

package/docs/examples/club-events/src/handlers.ts

@@ -0,0 +1,25 @@
+import { ContractError } from "@aotter/mantle/contracts";
+import { userOf } from "@aotter/mantle/auth";
+import type { Handlers } from "../generated/generated.js";
+
+export const handlers: Handlers = {
+  register: async ({ caller, store }, { eventId }) => {
+    if (caller.kind !== "user") throw new ContractError("AUTH_DENIED", "Sign in as a member to register.", "procedures/register");
+    // Check before writing: a clear refusal for a missing or closed event. Seats are NOT checked here;
+    // the `seats_taken <= capacity` check in register-write is what holds under concurrent requests.
+    const event = await store.collection("events").findById(eventId);
+    if (!event) throw new ContractError("NOT_FOUND", "No such event.", "procedures/register");
+    if (event.closed) throw new ContractError("CONFLICT", "Registration for this event is closed.", "procedures/register");
+    try {
+      // `member` comes from the verified caller, never from request input; uniqueIndexes [eventId, member] refuses a second seat.
+      // userOf: the Better Auth user record the caller was resolved from (any credential), so officers see who registered.
+      const user = userOf(caller);
+      return await store.procedures["register-write"]({ eventId, member: caller.subject, memberName: user?.name || user?.email || caller.subject });
+    } catch (error) {
+      // register-write's only Schema check is the capacity one.
+      if (error instanceof ContractError && error.code === "CONFLICT" && error.fields?.kind === "check" && error.fields.schema === "events")
+        throw new ContractError("CONFLICT", "The event is full.", "procedures/register");
+      throw error;
+    }
+  },
+};

package/docs/examples/club-events/src/signup.ts

@@ -0,0 +1,9 @@
+import { store } from "../generated/generated.js";
+import { handlers } from "./handlers.js";
+
+/** Members-only sign-up: an email may create an account only when officers listed it in the `members` Schema (Admin). */
+export async function allowSignUp(env: Env, email: string): Promise<boolean> {
+  // No user exists yet, so the lookup runs as an application-created system caller (never wire input).
+  const members = store(env.DB, { kind: "system", reason: "sign-up allowlist" }, { handlers }).collection("members");
+  return (await members.count({ email: email.toLowerCase() })) > 0;
+}

package/docs/examples/generated-web/README.md

@@ -0,0 +1,78 @@
+# Generated public website
+
+A minimal application-owned Cloudflare D1 Worker: an HTML list and detail page,
+REST, `llms.txt`, sitemap, Markdown alternates and canonical head tags. It uses the
+positional native generator documented by the installed `@aotter/mantle` version.
+The frontend has no runtime dependencies. It renders Markdown as escaped text,
+preserving the source for the `.md` alternate.
+
+Copy this directory outside the SDK checkout. In that directory, set
+`"type": "module"` in `package.json`, install the exact selected Mantle version
+and host tools, then run:
+
+```sh
+npm install --save-exact @aotter/mantle@<version>
+npm install --save-dev typescript @cloudflare/workers-types wrangler
+npx mantle generate cloudflare-d1 generated posts.yaml
+npx tsc --noEmit
+git init
+git add generated src/worker.ts wrangler.jsonc
+git commit -m "Generate native website contracts"
+npx wrangler d1 execute mantle-generated-web --local --file generated/schema.sql
+npx wrangler d1 execute mantle-generated-web --local --file seed.sql
+npx wrangler dev --local
+```
+
+Keep generated TypeScript, `schema.sql` and the configured Wrangler file in
+version control. The workflow is generate → typecheck → implement any listed ref
+handlers → typecheck → commit generated output. This manifest has no ref handlers.
+Use the installed version's documented commands. CI runs
+`mantle generate cloudflare-d1 generated posts.yaml --check` to refuse stale or
+missing generated files without writing them. `dist/`
+and local Wrangler state stay ignored.
+
+For a linked pre-release SDK, use its installed `mantle` CLI instead of installing
+an unpublished version. Generation adds Wrangler's split build automatically.
+The seed is local test data; never apply it to an existing production database.
+For deployment, set the real D1 binding and `PUBLIC_ORIGIN` to the public origin.
+The app passes a verified anonymous Caller for this public-only site; an
+application with sign-in resolves its Caller once and supplies it to each entry.
+
+Open `/`, `/posts/hello`, `/posts/hello.md`, `/api/views/posts`, `/llms.txt` and
+`/sitemap.xml`. The list pages with an opaque cursor; the detail reads the Store,
+which enforces publication in SQL. `site.head()` reads the declared public View
+and supplies canonical and Markdown alternate tags, even when the request host
+differs from `PUBLIC_ORIGIN`. Both HTML pages have Markdown alternates (`/.md`
+for the index) and a canonical. REST and web fall through to the HTML renderer.
+
+Acceptance:
+
+- Walk every `/api/views/posts` cursor: its rows must match the `llms.txt` detail
+  links and sitemap detail URLs below the documented index caps.
+- Each HTML page includes `rel="canonical"` and a `type="text/markdown"`
+  alternate whose GET returns its current source. The index canonical is `/`.
+- `/posts/draft` and `/posts/draft.md` return 404; the draft is absent from REST,
+  HTML links, `llms.txt` and sitemap. HTML source escapes the fixture's `<world>`.
+- Malformed/foreign list cursors return structured 400 errors with `no-store`.
+- HTML HEAD has no body. Unknown pages return 404 with `no-store`.
+
+Ordinary HTML detail performs two native reads: one Store read for the body, then one
+public View read in `site.head()`. The index likewise performs two reads (list
+and home head). The current head API accepts no preloaded row; there is no
+request cache or extra authentication lookup in this public example. IDs ending
+in `.md` need one additional exact-page probe before HTML rendering (three reads
+total). Markdown may perform two View reads when checking an exact `.md` page
+before its alternate.
+
+Web indexes have deliberate ceilings: 5,000 scanned rows, 10 queries and 1 MiB
+for `llms.txt`; 50,000 rows, 100 queries and 50 MiB for a sitemap. An authored SQL `LIMIT 3` means at most three rows in the entire index,
+not three rows per query. Omit SQL LIMIT to enumerate the whole authorized
+result up to these web ceilings. The renderer requests pages of up to 500
+through generated paging options; transport page size does not expand the
+authored result set. Migration: remove LIMIT only when it was mistakenly
+being used as a page-size setting; retain a business-defined top-N limit. Translation-aware web indexes/hreflang remain a separate
+follow-up; `locales[0]` supplies the currently supported locale alternate.
+
+The SDK runs this exact Worker against a native SQLite database in
+`tests/web-example.test.ts` and bundles/typechecks its D1 form. No measurement
+scripts or benchmark data are part of the example.

package/docs/examples/generated-web/posts.yaml

@@ -0,0 +1,38 @@
+apiVersion: cms.mantle.aotter.net/v2
+kind: Schema
+metadata: {name: posts}
+spec:
+  title: Posts
+  lifecycle: publishing
+  schema:
+    type: object
+    required: [title, body]
+    properties:
+      title: {type: string}
+      body: {type: string}
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: {name: posts}
+spec:
+  surface: public
+  sql: SELECT id, title FROM posts WHERE id <> 'home' ORDER BY id
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: {name: post}
+spec:
+  surface: public
+  input:
+    type: object
+    required: [id]
+    additionalProperties: false
+    properties: {id: {type: string, minLength: 1}}
+  sql: SELECT id, title, body FROM posts WHERE id = input.id ORDER BY id
+---
+apiVersion: cms.mantle.aotter.net/v2
+kind: View
+metadata: {name: home}
+spec:
+  surface: public
+  sql: SELECT id, title, body FROM posts WHERE id = 'home' ORDER BY id

package/docs/examples/generated-web/seed.sql

@@ -0,0 +1,6 @@
+-- Local fixture only. Production publishing goes through the generated Procedures.
+INSERT INTO posts (id, version, created_at, updated_at, title, body, status, published_at) VALUES
+('home', 1, 0, 0, 'Posts', '# Posts — browse the HTML index for articles.', 'published', 0),
+('hello', 1, 0, 0, 'Hello <world>', '# Hello world', 'published', 0),
+('second', 1, 0, 0, 'Second post', '# Second post', 'published', 0),
+('draft', 1, 0, 0, 'Hidden draft', '# Draft', 'draft', NULL);

package/docs/examples/generated-web/src/worker.ts

@@ -0,0 +1,43 @@
+import { surfaceFailure } from "@aotter/mantle/contracts";
+import { store } from '../generated/generated.js';
+import { rest } from '../generated/rest.js';
+import { web } from '../generated/web.js';
+import page from '../generated/paged/views/posts.js';
+
+interface Env { DB: Parameters<typeof store>[0]; PUBLIC_ORIGIN: string }
+const caller = { kind: 'anonymous' } as const;
+const escape = (text: unknown) => String(text).replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]!));
+const segment = (text: string) => encodeURIComponent(text).replace(/[()]/g, c => '%' + c.charCodeAt(0).toString(16).toUpperCase());
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    try {
+      const site = web({ db: env.DB, caller, origin: env.PUBLIC_ORIGIN, title: 'Posts', description: 'A small public website',
+        pages: { '/': { view: 'home', markdown: 'body' }, '/posts/{id}': { view: 'post', list: 'posts', markdown: 'body' } } });
+      const api = await rest<Env>({ db: env => env.DB, caller: async () => caller })(request, env);
+      if (api) return api;
+      const output = await site.fetch(request, env);
+      if (output) return output;
+      const url = new URL(request.url), detail = /^\/posts\/([^/]+)$/.exec(url.pathname);
+      if (url.pathname !== '/' && !detail) return new Response('Not found', { status: 404, headers: { 'cache-control': 'no-store' } });
+      if (!['GET', 'HEAD'].includes(request.method)) return new Response(null, { status: 405, headers: { allow: 'GET, HEAD', 'cache-control': 'no-store' } });
+      let title = 'Posts', body: string;
+      if (detail) {
+        let id: string;
+        try { id = decodeURIComponent(detail[1]!); } catch { return new Response('Invalid path', { status: 400, headers: { 'cache-control': 'no-store' } }); }
+        // The Store applies publishing visibility in SQL. An anonymous caller cannot read a draft.
+        const post = await store(env.DB, caller).collection('posts').findById(id);
+        if (!post) return new Response('Not found', { status: 404, headers: { 'cache-control': 'no-store' } });
+        title = post.title ?? 'Untitled';
+        // Markdown stays plain text here; no untrusted HTML or Markdown renderer is needed.
+        body = `<p><a href="/">All posts</a></p><pre>${escape(post.body ?? '')}</pre>`;
+      } else {
+        const result = await page(env.DB, caller, {}, { limit: 50, cursor: url.searchParams.get('cursor') ?? undefined });
+        body = '<ul>' + result.rows.map(row => `<li><a href="/posts/${segment(String(row.id))}">${escape(row.title)}</a></li>`).join('') + '</ul>';
+        if (result.nextCursor) body += `<a href="/?cursor=${encodeURIComponent(result.nextCursor)}">Next page</a>`;
+      }
+      const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>${escape(title)}</title>${await site.head(request, env)}</head><body><h1>${escape(title)}</h1>${body}</body></html>`;
+      return new Response(request.method === 'HEAD' ? null : html, { headers: { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' } });
+    } catch (error) { return surfaceFailure(error); }
+  }
+};

package/docs/examples/generated-web/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "compilerOptions": {
+    "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext",
+    "strict": true, "noEmit": true, "skipLibCheck": true, "lib": ["ES2022", "DOM"],
+    "types": ["@cloudflare/workers-types"]
+  },
+  "include": ["src", "generated"]
+}

package/docs/examples/generated-web/wrangler.jsonc

@@ -0,0 +1,8 @@
+{
+  "name": "mantle-generated-web",
+  "main": "src/worker.ts",
+  "compatibility_date": "2026-09-28",
+  "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],
+  "vars": { "PUBLIC_ORIGIN": "http://localhost:8787" },
+  "d1_databases": [{ "binding": "DB", "database_name": "mantle-generated-web", "database_id": "local-example" }]
+}

package/docs/examples/purchasing/.dev.vars.example

@@ -0,0 +1,6 @@
+# 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
+SUPPLIER_API_URL=http://127.0.0.1:9999/orders
+SUPPLIER_WEBHOOK_SECRET=replace-with-the-secret-the-supplier-signs-with