@aotter/mantle 0.2.0-alpha.8 → 0.2.0

package/dist/usecase/paging.js

@@ -1,5 +1,4 @@
 import { userReferences } from "../domain/userReferences.js";
-/** Selected View boundary: Core prints keyset SQL once; bare operations retain native rows. */
 import { parseNumeric } from "../build/compiler.js";
 import { outputConversions } from "../domain/columns.js";
 import { authLines } from "../domain/input.js";
@@ -17,10 +16,9 @@ export function emitPaging(plan, lowered, target, refuse, proofs, boundary = fal
         const proof = proofs?.[name];
         if (boundary && (!proof || !proof.types.length && !proof.single))
             continue;
-        // Internal bare queries remain available even when they cannot be safely paged.
         if (!proof || !proof.types.length && !proof.single) {
             if (view.surface !== "internal")
-                refuse(path, proof?.reason ?? "Paged Views need a complete typed NOT NULL key tuple, indexed Schema order and a non-fanning relation, or a proved singleton.");
+                refuse(path, proof?.reason ?? "Paged Views need a complete typed NOT NULL key tuple, indexed Schema order and a non-fanning relation, or a proved singleton. For a lookup by a unique field, end ORDER BY with the Schema's id (`ORDER BY t.id`).");
             continue;
         }
         const mode = view.surface === "public" ? "public" : "caller";

package/dist/usecase/publishing.js

@@ -1,4 +1,3 @@
-/** Opt-in lifecycle: one atomic, version-guarded statement per transition, with Core's row rules. */
 import { rowPolicy } from "../build/compiler.js";
 import { dialect as sqlite } from "../kernel/dialect/sqlite.js";
 import { dialect as postgres } from "../kernel/dialect/postgres.js";
@@ -32,11 +31,9 @@ export function emitPublishing(plan, isSqlite, declarations, procedures, entries
                 const schema = plan.schemas[s.name];
                 const recipes = [{ k: "now" }, { k: "input", name: "id" }, { k: "input", name: "expectedVersion" }];
                 const conditions = [`id = ${d.param(2)}`, `version = ${d.param(3)}`, `status IN (${from.map(v => `'${v}'`).join(", ")})`];
-                // Same visibility as Store and Admin writes, translation parent included (a child under an out-of-set parent is missing);
-                // the status term is replaced by the transition's own `status IN (...)`.
                 for (const term of rowPolicy(schema, trusted ? "trusted" : "caller", plan.schemas))
                     if (term[1] !== "admin")
-                        conditions.push(renderTerm(d, term, "", recipe => (recipes.push(recipe), d.param(recipes.length))));
+                        conditions.push(renderTerm(d, term, term[1] === "parent" ? d.ident(s.name) + "." : "", recipe => (recipes.push(recipe), d.param(recipes.length))));
                 if (verb === "publish")
                     for (const field of s.schema.required ?? []) {
                         const column = Object.keys(s.fields).find(c => (s.names?.[c] ?? c) === field);
@@ -56,7 +53,6 @@ export function emitPublishing(plan, isSqlite, declarations, procedures, entries
         }
     }
 }
-/** Publishing lists get one index, prefixed by scope when present. */
 export function publishingSql(schemas, isSqlite) {
     const d = isSqlite ? sqlite : postgres;
     return Object.values(schemas).filter(s => s.publishing).map(s => `CREATE INDEX ${d.ident(`_mantle_ix_${s.name}_published`)} ON ${d.ident(s.name)} (${[...(s.scope ? [s.scope] : []), ...(s.userScopes ?? []).map(u => u.column), "published_at", "id"].map(d.ident).join(", ")})`);

package/dist/usecase/rest.js

@@ -14,7 +14,6 @@ export function emitRest(plan, lowered, target, description) {
     const views = [], procedures = [];
     let hasWire = false;
     const convert = (code) => code ? `, convert: ${code}` : "";
-    // Each segment matches in its encoded form; `{name}` segments capture.
     const route = (method, path) => {
         const keys = [];
         const source = path.split("/").map(segment => segment.startsWith("{") && segment.endsWith("}") ? (keys.push(segment.slice(1, -1)), "([^/]+)") : encodeURIComponent(segment).replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("/");

package/dist/usecase/site.js

@@ -1,4 +1,3 @@
-/** Generate the optional site/media module and deployment DDL, never runtime preparation. */
 import { assertSiteDefaultsCanonical, canonicalizeLocaleList, expandPolicyRequired } from "../build/compiler.js";
 import { driverFor, isSqlite, q } from "../domain/entry.js";
 export function emitSite(target, defaults, refuse, schemaNames) {
@@ -32,7 +31,6 @@ export function site(db: Database, caller: Caller) { return createSite({read:(sq
 `, "site-seed.sql": seed + "\n", "site-schema.sql": `CREATE TABLE site_config (key TEXT PRIMARY KEY, value TEXT NOT NULL);
 CREATE TABLE media_assets (id TEXT PRIMARY KEY, created_at ${pg ? "BIGINT" : "INTEGER"} NOT NULL, owner_id TEXT, alt TEXT, caption TEXT, variants TEXT NOT NULL, metadata TEXT);
 CREATE INDEX media_assets_by_created_id ON media_assets (created_at DESC, id DESC);
-CREATE INDEX media_assets_by_owner_created ON media_assets (owner_id, created_at DESC);
 CREATE TABLE pending_media_uploads (id TEXT PRIMARY KEY, record TEXT NOT NULL, expires_at ${pg ? "BIGINT" : "INTEGER"} NOT NULL);
 CREATE INDEX pending_media_uploads_expires_at ON pending_media_uploads (expires_at);
 ${seed}

package/dist/usecase/stores.js

@@ -1,24 +1,14 @@
-/**
- * One typed collection per Schema, over the generic `createStore`. Core's row rules (`rowPolicy`, `writePolicy`) are evaluated
- * here, at build time, ONCE for a placeholder scope and TTL into the shared `Rules`; a Schema adds only a `Fact` (scope, TTL,
- * publishing, its date-time and date columns). Generation is refused if a Schema's expanded rules differ from Core's own for it
- * (caller and trusted rows, insert fills, update sets and lock, delete lock).
- * Column names, value types, writable columns and `orderBy` are TypeScript types only: nothing at runtime knows them.
- */
 import { NATIVE_NOT_NULL, notNullColumns, rowPolicy, writePolicy } from "../build/compiler.js";
 import { declaredType, inputType, nativeType } from "../domain/columns.js";
 import { q } from "../domain/entry.js";
 import { expand, SCOPE, TTL } from "../kernel/store.js";
-import { userScopeTerm } from '../build/compiler.js';
-// Types the typed Store compares and writes as plain bind values. Fixed numerics are scaled integers on SQLite; geo is two columns.
+import { refChecks, userScopeTerm } from '../build/compiler.js';
 const SCALAR = new Set(["text", "real", "float8", "integer", "int4", "int8", "bool", "timestamptz", "date"]);
-/** Core's own rules for a Schema, in the shape of `Rules` without the id expression (a delete's lock is compared separately). */
 const core = (s, schemas) => {
     const update = writePolicy(s, "update", { lock: true });
     return { caller: rowPolicy(s, "caller", schemas), trusted: rowPolicy(s, "trusted", schemas), fills: writePolicy(s, "insert").fills, sets: update.sets, lock: update.lock };
 };
 const probe = { scope: SCOPE, ttl: TTL, ttlSeconds: 0, publishing: true };
-/** @internal */
 export function emitStores(schemas, isSqlite, newId, refuse, required = false) {
     const all = Object.values(schemas).sort((a, b) => a.name < b.name ? -1 : 1);
     if (!all.length && !required)
@@ -28,7 +18,7 @@ export function emitStores(schemas, isSqlite, newId, refuse, required = false) {
     for (const s of all) {
         const type = (column) => declaredType(s.fields, column) ?? (column === "version" ? "integer" : column === "published_at" ? "timestamptz" : "text");
         const declared = Object.keys(s.fields).filter(f => f !== s.scope && s.fields[f] !== "geo");
-        const geo = Object.keys(s.fields).filter(f => s.fields[f] === "geo").flatMap(f => [`${f}_lat`, `${f}_lng`]); // `*` returns a geo field's two columns
+        const geo = Object.keys(s.fields).filter(f => s.fields[f] === "geo").flatMap(f => [`${f}_lat`, `${f}_lng`]);
         const names = [...["id", "version", "created_at", "updated_at", "author_id", ...(s.publishing ? ["status", "published_at"] : [])], ...declared];
         const required = new Set(s.schema.required ?? []), notNull = notNullColumns(s);
         const nonNull = (column) => NATIVE_NOT_NULL.has(column) || notNull.has(column);
@@ -36,18 +26,18 @@ export function emitStores(schemas, isSqlite, newId, refuse, required = false) {
         const parent = s.translates && schemas[s.translates.parent.toLowerCase()];
         const inherited = parent ? Object.keys(parent.fields).filter(c => c !== parent.scope && !Object.hasOwn(s.fields, c)).flatMap(c => parent.fields[c] === "geo" ? [`${c}_lat`, `${c}_lng`] : [c]) : [];
         const inheritedType = (c) => parent?.fields[c] ?? "real";
+        const ref = refChecks(s, schemas);
         const fact = {
             ...(s.userScopes?.length ? { u: s.userScopes.map(u => userScopeTerm(u, true)) } : {}),
             ...(s.scope ? { s: s.scope } : {}), ...(s.ttl ? { ttl: [s.ttl, s.ttlSeconds ?? 0] } : {}), ...(s.publishing ? { pub: 1 } : {}),
             ...(ts.length ? { ts } : {}), ...(dates.length ? { d: dates } : {}),
             ...(s.search?.length ? { search: s.search } : {}),
+            ...(ref.length ? { ref } : {}),
             ...(parent ? { parent: { on: s.translates.on.toLowerCase(), ...(parent.scope ? { scope: [parent.scope, s.scope] } : {}), table: s.translates.parent.toLowerCase(), visible: rowPolicy(s, "caller", schemas).find(t => t[1] === "parent"), caller: rowPolicy(parent, "caller", schemas), trusted: rowPolicy(parent, "trusted", schemas), fields: inherited, ts: inherited.filter(c => parent.fields[c] === "timestamptz"), d: inherited.filter(c => parent.fields[c] === "date") } } : {}),
         };
-        // the shared rules, with this Schema's scope and TTL put in, are Core's rules for it: or the runtime would enforce something else
         const expected = q([core(s, schemas), writePolicy(s, "delete", { lock: true }).lock]), got = q([expand(rules, fact), rules.lock]);
         if (expected !== got)
             refuse(`schemas/${s.name}`, `Core's row rules for this Schema differ from the shared rules (${expected} vs ${got}); the generic Store cannot serve it.`);
-        // ORDER BY is allowed where the caller's scoped read can walk an index (its first column, or the one after the scope column) and the column is NOT NULL.
         const indexed = new Set([...(s.publishing ? [[...(s.scope ? [s.scope] : []), "published_at", "id"]] : []), ...(s.indexes ?? []), ...(s.unique ?? [])].map(i => i[0] === s.scope ? i[1] : i[0]).filter((c) => !!c));
         const key = (c) => /^[A-Za-z_]\w*$/.test(c) ? c : q(c);
         const of = (columns, value) => `{ ${columns.map(c => `${key(c)}: ${value(c)};`).join(" ")} }`;

package/dist/usecase/tool-version.js

@@ -1,8 +1,5 @@
-/** Generate-time tool versions: a stale host copy shows the model an older version than results carry. */
 import { canonical, fnv } from "../build/compiler.js";
-/** A hash of what a catalogue lists, so an unchanged definition keeps its version across deploys. */
 export const versionOf = (value) => fnv(canonical(value));
-/** A listed tool: its version, and its description (each locale's) ending with that version. */
 export function versioned(tool) {
     const v = versionOf(tool), mark = (text) => `${text} (tool version ${v})`;
     return { ...tool, description: typeof tool.description === "string" ? mark(tool.description) : Object.fromEntries(Object.entries(tool.description).map(([locale, text]) => [locale, mark(text)])), version: v };

package/dist/usecase/translations.js

@@ -1,12 +1,10 @@
 import { userReferences } from "../domain/userReferences.js";
-/** Translation helpers use generated SQL policy, never a request-time manifest. */
 import { rowPolicy } from "../build/compiler.js";
 import { renderTerm } from "../kernel/store.js";
 import { dialect as SQLITE } from "../kernel/dialect/sqlite.js";
 import { dialect as POSTGRES } from "../kernel/dialect/postgres.js";
 import { declaredType } from "../domain/columns.js";
 import { driverFor, isSqlite, q } from "../domain/entry.js";
-/** The parent is checked by the same atomic UPDATE that publishes the child. */
 export function publishedParent(plan, child, d, recipes, trusted) {
     const tr = child.translates, parent = plan.schemas[tr.parent.toLowerCase()], on = tr.on.toLowerCase();
     const conditions = [`p.${d.ident(on)} = ${d.ident(child.name)}.${d.ident(on)}`];

package/dist/usecase/validation.js

@@ -1,4 +1,3 @@
-/** Compile boundary checks into each operation; no schema enters the request bundle. */
 import { INPUT_RULE_KEYWORDS, lookupLocalRef as lookup, rootRefChain } from "../build/compiler.js";
 import { literal, q } from "../domain/entry.js";
 import { publishingInput } from "./publishing.js";
@@ -6,14 +5,9 @@ import { equal } from "../kernel/validation.js";
 const pointer = (key) => key.replace(/~/g, "~0").replace(/\//g, "~1");
 const supported = new Set([..."$defs $ref $schema $id type nullable properties required additionalProperties items enum const format pattern minLength maxLength minimum maximum exclusiveMinimum exclusiveMaximum multipleOf minItems maxItems title description default readOnly writeOnly examples deprecated x-mantle-ref x-mcp-hint".split(" "), ...INPUT_RULE_KEYWORDS]);
 const shapes = "see docs/handbook/reference/surface.md";
-// YAML .inf and .nan parse to numbers that JSON writes as null.
 const finite = (value) => typeof value === "number" ? Number.isFinite(value) : !!value && typeof value === "object" ? Object.values(value).every(finite) : true;
 const has = (key) => `Object.hasOwn(object,${q(key)})`;
 const exactly = (value, keys) => !!value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).sort().join(" ") === keys;
-/**
- * An object schema's rules, each failing `when` (JavaScript on `object`) with its sentence at the missing field `key`, or the
- * reason a rule has an unsupported shape.
- */
 function rules(schema) {
     const declared = (names) => Array.isArray(names) && names.length > 0 && names.every(name => typeof name === "string" && Object.hasOwn(schema.properties ?? {}, name));
     const list = (names) => names.map(name => `'${name}'`).join(" and ");
@@ -34,7 +28,6 @@ function rules(schema) {
     if (condition !== undefined || then !== undefined || otherwise !== undefined) {
         const [key] = exactly(condition, "properties required") ? Object.keys(condition.properties) : [];
         const value = key === undefined ? undefined : condition.properties[key];
-        // Without required: [key], an absent key satisfies `if`.
         if (key === undefined || !exactly(condition.properties, key) || !exactly(value, "const") || !(["string", "boolean"].includes(typeof value.const) || Number.isFinite(value.const) || value.const === null) || q(condition.required) !== q([key]) || !declared([key]))
             return `if is supported only as exactly { properties: { <field>: { const: <string, finite number, boolean or null> } }, required: [<field>] }, so an absent field does not satisfy it; ${shapes}.`;
         if (then === undefined && otherwise === undefined || [then, otherwise].some(branch => branch !== undefined && !(exactly(branch, "required") && declared(branch.required))))
@@ -47,19 +40,12 @@ function rules(schema) {
     }
     return found;
 }
-/** Whether an input schema accepts `{}`: a list View is read with no input, so web indexes need this. */
 export function acceptsEmpty(input) {
     if (input === undefined)
         return true;
-    // Validation applies a root `$ref`'s target too, so each schema along the chain must accept `{}`; an unresolved or cyclic chain does not.
-    // dependentRequired needs a present key; an if needs its field, so `{}` meets only an else. An enum or const must admit `{}`.
     return rootRefChain(input)?.every(schema => !schema.required?.length && schema.anyOf === undefined && !schema.else?.required?.length
         && (schema.enum === undefined || schema.enum.some(option => equal({}, option))) && (schema.const === undefined || equal({}, schema.const)) && (schema.type === undefined || [schema.type].flat().includes("object"))) ?? false;
 }
-/**
- * An input schema as an AI tool catalogue advertises it: some model APIs refuse rules (a root `anyOf`, `if`), so each rule leaves
- * the schema and becomes a sentence of the description.
- */
 export function advertised(input, description) {
     if (!input)
         return { inputSchema: input, description };
@@ -68,7 +54,6 @@ export function advertised(input, description) {
         if (!node || typeof node !== "object")
             return;
         const schema = node;
-        // An MCP View tool keeps each rule set of its root `$ref` chain as an `allOf` branch over the merged properties.
         const branches = Array.isArray(schema.allOf) ? schema.allOf : [];
         for (const branch of [schema, ...branches.map(branch => ({ ...branch, properties: schema.properties }))]) {
             const found = rules(branch);
@@ -111,9 +96,7 @@ export function emitValidation(plan, refuse = (path, message) => { throw Error(`
                 files[file] = `import { transition } from "@aotter/mantle/validation";\nexport const validate = (raw: unknown) => transition(${q(base)}, raw);\n`;
                 continue;
             }
-            // Only a local `$ref`, or more than 100 nested objects and arrays, can reach the nesting limit: only then is `depth` passed.
             const recursive = json.includes('"$ref"') || json.split(/[[{]/).length > 101, depth = recursive ? ",depth+1" : "";
-            // Identical bodies share one function.
             const nodes = new Map(), bodies = new Map(), functions = [], formats = new Set(), patterns = new Map();
             let equality = false;
             const resolve = (ref) => {
@@ -142,7 +125,6 @@ export function emitValidation(plan, refuse = (path, message) => { throw Error(`
                         refuse(base, `Unsupported input type '${type}'.`);
                 if (types.length)
                     lines.push(typeCheck(types));
-                // After a single type check `fail` (never) has narrowed `value`: that type's guard is implied.
                 const only = types.length === 1 ? types[0] : undefined;
                 const guard = (type, test = `(${condition(type)})`) => only === type || type === "number" && only === "integer" ? "" : test + " && ";
                 if (schema.enum) {
@@ -157,6 +139,14 @@ export function emitValidation(plan, refuse = (path, message) => { throw Error(`
                     equality = true;
                     check(`!equal(value,${literal(schema.const)})`, "Value violates const.");
                 }
+                for (const key of ["minLength", "maxLength", "minItems", "maxItems"])
+                    if (schema[key] !== undefined && (!Number.isSafeInteger(schema[key]) || schema[key] < 0))
+                        refuse(base, `${key} must be a non-negative safe integer.`);
+                for (const key of ["minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum"])
+                    if (schema[key] !== undefined && (typeof schema[key] !== "number" || !Number.isFinite(schema[key])))
+                        refuse(base, `${key} must be a finite number.`);
+                if (schema.multipleOf !== undefined && (typeof schema.multipleOf !== "number" || !Number.isFinite(schema.multipleOf) || schema.multipleOf <= 0))
+                    refuse(base, "multipleOf must be a positive finite number.");
                 for (const [type, measure, keywords] of bounds)
                     for (const [key, operator] of Object.entries(keywords))
                         if (schema[key] !== undefined)
@@ -189,7 +179,6 @@ export function emitValidation(plan, refuse = (path, message) => { throw Error(`
                 }
                 if (schema.items)
                     lines.push(`${only === "array" ? "" : "if (Array.isArray(value)) "}for (let i=0;i<value.length;i++) ${emit(schema.items)}(value[i],path+"/"+i${depth});`);
-                // Several keys that need no JSON-pointer escaping are checked by one loop, in the same order.
                 const required = schema.required ?? [], checks = Object.entries(schema.properties ?? {}).map(([key, child]) => [key, emit(child)]);
                 const loop = (keys) => keys.length > 1 && keys.every(key => pointer(key) === key);
                 const object = loop(required) ? [`for (const key of ${q(required)}) if (!Object.hasOwn(object,key)) fail(path+"/"+key,"Required field is missing.");`] : required.map(key => `if (!Object.hasOwn(object,${q(key)})) fail(path+${q("/" + pointer(key))},"Required field is missing.");`);
@@ -209,7 +198,6 @@ export function emitValidation(plan, refuse = (path, message) => { throw Error(`
                 if (object.length)
                     lines.push(`${only === "object" ? "" : `if (${condition("object")}) `}{ const object = value as Record<string,unknown>;\n${object.join("\n")}\n}`);
                 const body = lines.join("\n");
-                // Without recursion nothing calls a check before its body is complete, so an identical body's function serves it.
                 const fn = recursive ? named : bodies.get(body) ?? named;
                 if (fn === named) {
                     bodies.set(body, fn);

package/docs/examples/README.md

@@ -1,7 +1,8 @@
 # Examples
 
-Start from the **app shell**, then copy the example closest to your app on top of it. Each example shows a few
-capabilities the others do not; combine them for anything else.
+Start an app with `mantle init`, which writes the **app shell** once. The examples are references: each shows a few
+capabilities the others do not. Find each need in **Combining** below, read that example's manifest and source, and
+take the pattern into your own manifests and `src/`. Do not copy an example directory over your app.
 
 | Example | Shows |
 |---|---|
@@ -16,20 +17,27 @@ capabilities the others do not; combine them for anything else.
 | You need | Take |
 |---|---|
 | Stock that never oversells (orders, tickets, bookings) | club-events' capacity: a Schema `checks` constraint plus the decrement in the same program |
+| An order, cart or import with several rows that must all commit or none | one SQL Procedure over `json_each(input.items)` with a counted check that refuses unknown lines (`mantle help typed-queries`, "Several rows that commit together") |
 | Employees or customers who see only their own records | club-events' `restrict: { <schema>: "author_id = auth.uid()" }` |
 | An approval step, or any state machine | purchasing's guarded `UPDATE ... WHERE requestStatus = ...` Procedures |
+| Approve first, then reserve or spend | purchasing's `approve-request-write`: the guarded status change and the budget deduction in one program (`mantle help sql-patterns`, "Approve before reserving") |
+| A status chosen while writing (auto-approve small requests) | purchasing's `submit-request`: `CASE` in the INSERT ("Choose a status while writing: CASE") |
+| Edit only the fields given | `COALESCE(input.field, field)` ("Change only the fields given") |
+| Create or add (restock, counters) | `INSERT ... ON CONFLICT (...) DO UPDATE` ("Create or add") |
+| Refuse while something still refers to it | a `NOT EXISTS` guard in the UPDATE (purchasing's `submit-request` ledger row; "Refuse while something refers to it") |
+| A record with its children in one read | club-events' `event-roster`: a JSON array per row ("A row with its children in one read") |
+| The latest row per group, rankings | `row_number() OVER (PARTITION BY ...)` ("The latest row of each group") |
 | A third-party API that answers later (webhooks, callbacks) | purchasing's `src/routes.ts`: verify the raw request, then call a Procedure |
 | Public, multilingual, search- and AI-friendly pages | recipes' `src/routes.ts` |
 | Invite-only or members-only sign-up | club-events' `members` allowlist + `src/signup.ts` |
 | Notifications and reminders | purchasing's `EmailSender` call and `src/schedule.ts` |
 
-When you copy an example only for one of its patterns, delete what your app does not need. Copying club-events, for
-example, also brings its `members` allowlist and `src/signup.ts` (members-only sign-up); remove both, or restore the
+If you do copy an example's files, delete what your app does not need. Copying club-events, for example, also brings its `members` allowlist and `src/signup.ts` (members-only sign-up); remove both, or restore the
 shell's allow-all `src/signup.ts`, unless sign-up should be invite-only. Purchasing brings its supplier callback
 (`src/routes.ts`, `src/supplier.ts`), email (`src/notify.ts`), cron (`src/schedule.ts` and `triggers.crons`) and its
 `wrangler.jsonc` secrets. `pnpm generate` and `tsc` point at leftovers that reference removed Schemas.
 
 Every example uses two roles: `admin` (the admin layer) and `user`.
 
-[Reference service](https://github.com/aotter/mantle/tree/v0.2.0-alpha.8/docs/examples/reference-service) is the release smoke test for packed packages, not a starting point. Its source lives in the tagged repository; it is not included in the npm docs.
+[Reference service](https://github.com/aotter/mantle/tree/v0.2.0/docs/examples/reference-service) is the release smoke test for packed packages, not a starting point. Its source lives in the tagged repository; it is not included in the npm docs.
 Projects on 0.1.x move with [the upgrade guide](../upgrade-0.1-to-0.2.md).

package/docs/examples/app-shell/README.md

@@ -2,22 +2,23 @@
 
 The wiring every Mantle Cloudflare app needs, ready to copy: Better Auth (email OTP, admin + user roles),
 one Worker fetch (auth routes → your routes → Admin → MCP → generated REST), the Admin console assets, and a
-local acceptance kit. It has no business manifests: add your own, or copy one of the examples on top of it.
+local acceptance kit. It has no business manifests: add your own, taking patterns from the examples (`mantle help examples`).
 
 ## Start an app
 
 ```sh
-cp -R node_modules/@aotter/mantle/docs/examples/app-shell/. my-app/   # or from this repository
-cp -R node_modules/@aotter/mantle/docs/examples/club-events/. my-app/ # optional: an example on top
+npx @aotter/mantle@<exact version> init my-app   # writes this shell once, Mantle packages pinned to that version
 cd my-app
-# package.json: pin the exact installed Mantle version for @aotter/mantle, -admin and -ui
 pnpm install
+# add manifests/*.yaml (mantle help four-atoms; patterns: mantle help examples)
 pnpm generate          # writes generated/ and lists any `handler: { ref }` to implement in src/handlers.ts
 pnpm types && pnpm check
 cp .dev.vars.example .dev.vars
-pnpm db:init && pnpm db:seed   # db:seed only when the example has seed.sql
+pnpm db:init                   # add seed.sql and run pnpm db:seed for fixtures
 pnpm dev                       # one-time codes print to this log
-pnpm smoke                     # when the copied example has smoke.mjs
+pnpm smoke                     # your smoke.mjs on smoke-kit.mjs (see Files you edit)
+pnpm accept                    # hand each role to a fresh evaluator (see Independent acceptance)
+pnpm test                      # Admin MCP App check: needs Chrome (npx playwright-core install chromium, or MANTLE_TEST_CHROMIUM=<executable>)
 ```
 
 npm works too (`npm install`, `npm run …`). `package.json` pins `@better-auth/core` and `@better-auth/utils` even though
@@ -38,9 +39,11 @@ on one version.
 | `src/signup.ts` | `allowSignUp(env, email)`: who may create an account (allow-all by default). `auth.ts` calls it before Better Auth creates a user; `ADMIN_EMAIL` is always allowed. |
 | `src/auth.ts` | Better Auth options. Two roles only: `admin` (the admin layer) and `user`. Replace the console OTP sender before deploying. |
 | `smoke.mjs` | Your acceptance steps on `smoke-kit.mjs` (fresh local D1, OTP sign-in per user, REST/MCP/Admin calls). |
+| `accept.mjs` | Independent acceptance setup: one URL per role that carries its session, plus a minimal MCP client. Add a fixtures module for realistic data. |
 
-`src/service.ts` and `src/index.ts` rarely change. Delete the blocks marked `MCP / OAuth (optional)` in `auth.ts`
-and `service.ts` if the app has no MCP.
+`src/service.ts` and `src/index.ts` rarely change. The default shell mounts REST and MCP together. If the app deliberately
+chooses asymmetric exposure, delete the blocks marked `MCP / OAuth (deliberate exception)` in `auth.ts` and `service.ts`;
+HTTP-only Procedures will keep generating with a warning.
 
 Search for `AGENT:` to find what an app must fill in.
 
@@ -50,8 +53,40 @@ Search for `AGENT:` to find what an app must fill in.
   `cf-connecting-ip`; when testing by hand, wait a minute or vary that header.
 - `ADMIN_EMAIL`'s first verified sign-in becomes `admin` while no admin exists. The sign-in response may still show
   the previous role; `/admin/api/me` shows the current one.
+- More administrators: in Admin, **More → Administrators** invites by email and **More → Members** grants Admin to an
+  existing member. `docs/handbook/cloudflare/authentication.md` (Identity helpers) has the same operations as an API.
 - Admin HTTP routes are listed in `docs/handbook/guides/native-admin.md`.
 
+`mantle help local-testing` lists what the smoke covers: every Procedure at its edges, each caller's isolation,
+visitor pages without JavaScript, MCP discovery and Admin's MCP App.
+Scripted smoke is not independent acceptance; before reporting a user-facing
+deliverable done, follow the independent acceptance guide: `mantle help agent-workflow-acceptance`.
+
+### Independent acceptance
+
+`pnpm accept` (optionally `pnpm accept --fixtures fixtures.mjs --user member@example.test`; with npm, `npm run accept -- --fixtures …`) starts the app on a fresh local D1,
+signs the admin in, runs your fixtures module, signs the user in and prints one local URL per role:
+
+```text
+visitor (anonymous): http://127.0.0.1:18741
+admin (owner@example.test): http://127.0.0.1:46467  MCP http://127.0.0.1:46467/mcp/admin  Admin http://127.0.0.1:46467/admin
+user (member@example.test): http://127.0.0.1:42607  MCP http://127.0.0.1:42607/mcp
+```
+
+Each URL forwards to the app with that role's session; the evaluator never sees a cookie, and the URL refuses
+`/api/auth/*`, so it cannot sign out, sign in as someone else or mint credentials. Give an evaluator only its role's URL:
+
+- MCP: configure the URL as a streamable HTTP MCP server, or, without an MCP client,
+  `node accept.mjs mcp <url>/mcp` lists the tools and `node accept.mjs mcp <url>/mcp <tool> '<json>'` calls one.
+- Admin and member pages: open the URL in a browser (a person's, or Playwright for an agent); it is already
+  signed in.
+- REST: send requests to the URL with no credential.
+
+The fixtures module's default export receives `{ call, mcp, signIn, sql, sessions, user }` and runs between the two
+sign-ins, so an invite-only app can admit the user first. Create records through the app's own REST/MCP as real
+users (other members' records, several states, more than one page); `sql` is for what no surface may write, and returns storage column names (lower case unless aliased).
+Ctrl-C stops the app and deletes its data. To accept an external MCP host's OAuth connection instead, see the guide.
+
 ### MCP acceptance
 
 Generation declares tools; the app owns whether and where a remote endpoint is mounted.

package/docs/examples/app-shell/accept.mjs

@@ -0,0 +1,91 @@
+// Independent acceptance setup (mantle help agent-workflow-acceptance): hands each role to a fresh evaluator without a credential.
+//   node accept.mjs [--fixtures fixtures.mjs] [--user member@example.test]
+//     Starts the app on a fresh local D1 (schema.sql, then seed.sql), signs the admin in with email OTP, runs the optional
+//     fixtures module (default export async ({ call, mcp, signIn, sql, sessions, user }) => {...}: realistic records through
+//     the app's own REST/MCP as real users, e.g. other members' orders and more than one page), signs the user in, then
+//     serves one local proxy per role that adds that role's session to every request. Give an evaluator only its role's URL
+//     (a visitor gets the app's own origin):
+//     MCP at <proxy>/mcp (user) or <proxy>/mcp/admin (admin), Admin at <proxy>/admin, pages and REST at <proxy>/.
+//     The proxy refuses /api/auth/* so the evaluator cannot sign out, sign in or mint credentials. Ctrl-C stops everything.
+//   node accept.mjs mcp <endpoint> [tool [json-arguments]]
+//     A minimal MCP client for an evaluator without one: lists the tools, or calls one and prints the raw result.
+import { createServer } from "node:http";
+import { Readable } from "node:stream";
+import { parseArgs } from "node:util";
+import { pathToFileURL } from "node:url";
+import { resolve } from "node:path";
+
+if (process.argv[2] === "mcp") await client(process.argv[3], process.argv[4], process.argv[5]).catch(error => { console.error(error.message); process.exitCode = 1; });
+else await setup();
+
+async function setup() {
+  const { values } = parseArgs({ args: process.argv.slice(2).filter(arg => arg !== "--"), options: { fixtures: { type: "string" }, user: { type: "string", default: "member@example.test" } } });
+  const { startApp } = await import("./smoke-kit.mjs");
+  const app = await startApp();
+  const stop = async () => { await app.stop(); process.exit(0); };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+  try {
+    // Fixtures run between the two sign-ins, so an invite-only app can admit the user first.
+    const sessions = { admin: await app.signIn(app.owner) };
+    if (values.fixtures) await (await import(pathToFileURL(resolve(values.fixtures)).href)).default({ ...app, sessions, user: values.user });
+    sessions.user = await app.signIn(values.user);
+    const lines = [`visitor (anonymous): ${app.origin}`];
+    for (const [role, cookie] of Object.entries(sessions)) {
+      const url = await proxy(app.origin, cookie);
+      lines.push(`${role} (${role === "admin" ? app.owner : values.user}): ${url}  MCP ${url}/mcp${role === "admin" ? "/admin" : ""}${role === "admin" ? `  Admin ${url}/admin` : ""}`);
+    }
+    console.log(lines.join("\n") + "\nReady. Ctrl-C stops the app and deletes its data.");
+  } catch (error) {
+    console.error(app.logs().slice(-4000));
+    await app.stop();
+    throw error;
+  }
+}
+
+/** A local origin that forwards to the app with one role's session; sliding Set-Cookie updates stay inside the proxy. */
+function proxy(origin, cookie) {
+  const jar = new Map(cookie.split("; ").map(pair => [pair.slice(0, pair.indexOf("=")), pair]));
+  const server = createServer(async (request, response) => {
+    const url = new URL(request.url, origin);
+    if (url.pathname.startsWith("/api/auth/")) { response.writeHead(403, { "content-type": "text/plain" }).end("Sign-in is handled by setup."); return; }
+    const chunks = [];
+    for await (const chunk of request) chunks.push(chunk);
+    const headers = new Headers();
+    for (const [name, value] of Object.entries(request.headers)) if (!["host", "cookie", "origin", "connection", "content-length"].includes(name)) headers.set(name, [value].flat().join(", "));
+    headers.set("cookie", [...jar.values()].join("; "));
+    headers.set("origin", origin);
+    const upstream = await fetch(url, { method: request.method, headers, redirect: "manual", body: chunks.length ? Buffer.concat(chunks) : undefined });
+    for (const set of upstream.headers.getSetCookie()) { const pair = set.split(";")[0]; jar.set(pair.slice(0, pair.indexOf("=")), pair); }
+    const out = {};
+    upstream.headers.forEach((value, name) => { if (!["set-cookie", "content-encoding", "content-length", "transfer-encoding"].includes(name)) out[name] = value; });
+    if (out.location) out.location = out.location.replace(origin, `http://${request.headers.host}`);
+    response.writeHead(upstream.status, out);
+    if (upstream.body) Readable.fromWeb(upstream.body).pipe(response); else response.end();
+  });
+  return new Promise(done => server.listen(0, "127.0.0.1", () => done(`http://127.0.0.1:${server.address().port}`)));
+}
+
+async function client(endpoint, tool, json) {
+  if (!endpoint) throw new Error("usage: node accept.mjs mcp <endpoint> [tool [json-arguments]]");
+  const headers = { "content-type": "application/json", accept: "application/json, text/event-stream" };
+  let id = 0;
+  const rpc = async (method, params) => {
+    const response = await fetch(endpoint, { method: "POST", headers, body: JSON.stringify({ jsonrpc: "2.0", ...(method.startsWith("notifications/") ? {} : { id: ++id }), method, params }) });
+    const session = response.headers.get("mcp-session-id");
+    if (session) headers["mcp-session-id"] = session;
+    const text = await response.text();
+    if (!response.ok && response.status !== 202) throw new Error(`MCP ${method}: HTTP ${response.status} ${text}`);
+    const data = text.split("\n").filter(line => line.startsWith("data:")).map(line => line.slice(5)).join("\n") || text;
+    return data ? JSON.parse(data) : null;
+  };
+  const init = await rpc("initialize", { protocolVersion: "2025-11-25", capabilities: {}, clientInfo: { name: "mantle-accept", version: "1" } });
+  headers["mcp-protocol-version"] = init.result?.protocolVersion ?? "2025-11-25";
+  await rpc("notifications/initialized");
+  if (!tool) {
+    const tools = [];
+    let cursor;
+    do { const page = (await rpc("tools/list", cursor ? { cursor } : {})).result; tools.push(...page.tools); cursor = page.nextCursor; } while (cursor);
+    console.log(JSON.stringify(tools, null, 2));
+  } else console.log(JSON.stringify(await rpc("tools/call", { name: tool, arguments: json ? JSON.parse(json) : {} }), null, 2));
+}

package/docs/examples/app-shell/gitignore

@@ -0,0 +1,7 @@
+node_modules/
+.wrangler/
+.dev.vars
+.env
+*.sqlite
+*.sqlite-shm
+*.sqlite-wal

package/docs/examples/app-shell/package.json

@@ -5,17 +5,18 @@
   "scripts": {
     "generate": "mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --entry src/index.ts --admin",
     "types": "wrangler types --include-runtime=false",
-    "db:init": "wrangler d1 execute mantle-app --local --file generated/schema.sql",
-    "db:seed": "wrangler d1 execute mantle-app --local --file seed.sql",
+    "db:init": "wrangler d1 execute DB --local --file generated/schema.sql",
+    "db:seed": "wrangler d1 execute DB --local --file seed.sql",
     "build": "mantle bundle src/index.ts dist",
     "test": "node --test generated/admin-mcp-app.check.mjs",
     "dev": "wrangler dev --local --ip 127.0.0.1 --port 8787",
     "check": "mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts --entry src/index.ts --admin --check && wrangler types --include-runtime=false --check && tsc --noEmit",
-    "smoke": "node smoke.mjs"
+    "smoke": "node smoke.mjs",
+    "accept": "node accept.mjs"
   },
   "dependencies": {
-    "@aotter/mantle": "0.2.0-alpha.8",
-    "@aotter/mantle-ui": "0.2.0-alpha.8",
+    "@aotter/mantle": "0.2.0",
+    "@aotter/mantle-ui": "0.2.0",
     "@better-auth/cimd": "1.7.7",
     "@better-auth/core": "1.7.7",
     "@better-auth/mcp": "1.7.7",
@@ -24,7 +25,7 @@
     "@modelcontextprotocol/ext-apps": "2.0.0",
     "@modelcontextprotocol/server": "2.2.0",
     "better-auth": "1.7.7",
-    "@aotter/mantle-admin": "0.2.0-alpha.8",
+    "@aotter/mantle-admin": "0.2.0",
     "react": "19.3.0",
     "react-dom": "19.3.0"
   },

package/docs/examples/app-shell/smoke-kit.mjs

@@ -3,6 +3,7 @@
 //   import { smoke } from "./smoke-kit.mjs";
 //   await smoke(async ({ call, mcp, signIn, owner, step }) => { const admin = await signIn(owner); ... step("..."); });
 //   Extra Worker variables: await smoke(scenario, { vars: { SUPPLIER_API_URL: "http://127.0.0.1:9999" } });
+// accept.mjs uses startApp() to keep the app running for fresh evaluators.
 import assert from "node:assert/strict";
 import { execFile, spawn, spawnSync } from "node:child_process";
 import { existsSync, mkdtempSync, rmSync } from "node:fs";
@@ -64,11 +65,23 @@ export async function assertMcpDiscovery(endpoint, { tools, headers = {} }) {
   return names;
 }
 
-const database = "mantle-app"; // wrangler.jsonc d1_databases[0].database_name
+const database = "DB"; // the D1 binding (wrangler.jsonc d1_databases[0].binding), so renaming the database changes nothing here
 const env = { ...process.env, WRANGLER_SEND_METRICS: "false" };
 
-export async function smoke(scenario, { vars = {} } = {}) {
-  const port = 18000 + Math.floor(Math.random() * 1000), origin = `http://127.0.0.1:${port}`, owner = "owner@example.test";
+export async function smoke(scenario, options) {
+  const app = await startApp(options);
+  try {
+    await scenario(app);
+    console.log("smoke passed");
+  } catch (error) {
+    console.error(app.logs().slice(-4000));
+    throw error;
+  } finally { await app.stop(); }
+}
+
+/** Start the app on a fresh local D1 (schema.sql, then seed.sql when present); stop() ends wrangler and deletes the state. */
+export async function startApp({ vars = {}, port = 18000 + Math.floor(Math.random() * 1000) } = {}) {
+  const origin = `http://127.0.0.1:${port}`, owner = "owner@example.test";
   const state = mkdtempSync(join(tmpdir(), "mantle-smoke-"));
   // Deployment DDL is explicit: nothing at runtime creates tables.
   for (const file of ["generated/schema.sql", ...(existsSync("seed.sql") ? ["seed.sql"] : [])]) {
@@ -128,6 +141,17 @@ export async function smoke(scenario, { vars = {} } = {}) {
     assert.fail(`no log line matching ${pattern}`);
   };
   const step = name => console.log(`ok - ${name}`);
+  const stop = async () => {
+    const kill = signal => { try { process.kill(-wrangler.pid, signal); } catch { /* already gone */ } };
+    kill("SIGTERM");
+    await new Promise(resolve => {
+      if (wrangler.exitCode !== null) return resolve();
+      const timer = setTimeout(() => { kill("SIGKILL"); resolve(); }, 5_000);
+      wrangler.once("exit", () => { clearTimeout(timer); resolve(); });
+    });
+    kill("SIGKILL");
+    rmSync(state, { recursive: true, force: true });
+  };
   try {
     for (let attempt = 0; ; attempt++) {
       if (wrangler.exitCode !== null) throw new Error(`wrangler exited ${wrangler.exitCode}`);
@@ -135,20 +159,10 @@ export async function smoke(scenario, { vars = {} } = {}) {
       if (attempt > 240) throw new Error("the Worker did not start");
       await new Promise(resolve => setTimeout(resolve, 250));
     }
-    await scenario({ origin, owner, call, mcp, signIn, sql, cron, waitForLog, step, logs: () => logs });
-    console.log("smoke passed");
   } catch (error) {
     console.error(logs.slice(-4000));
+    await stop();
     throw error;
-  } finally {
-    const stop = signal => { try { process.kill(-wrangler.pid, signal); } catch { /* already gone */ } };
-    stop("SIGTERM");
-    await new Promise(resolve => {
-      if (wrangler.exitCode !== null) return resolve();
-      const timer = setTimeout(() => { stop("SIGKILL"); resolve(); }, 5_000);
-      wrangler.once("exit", () => { clearTimeout(timer); resolve(); });
-    });
-    stop("SIGKILL");
-    rmSync(state, { recursive: true, force: true });
   }
+  return { origin, owner, call, mcp, signIn, sql, cron, waitForLog, step, logs: () => logs, stop };
 }

package/docs/examples/app-shell/src/auth.ts

@@ -34,11 +34,12 @@ export function authOptions(env: Env) {
       if (!/^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/.test(origin)) throw new Error("Configure a production email sender.");
       console.log(`${email}: one-time code is ${otp}`);
     } }),
-    // --- MCP / OAuth (optional): delete these plugins, `disabledPaths` and the MCP block in service.ts if the app has no MCP.
+    // --- MCP / OAuth (deliberate exception): remove only when the app intentionally chooses asymmetric exposure.
     jwt({ disableSettingJwtHeader: true }),
     // Ends a user's OAuth grants (offline ones too) on password reset, admin ban or session revocation.
     oauthGrantRevocation(),
-    mcp({ loginPage: "/admin/sign-in", consentPage: "/admin/oauth/consent", resource: `${origin}/mcp`, scopes: ["mcp"], extensions: [oauthGrantExtension], allowPublicClientPrelogin: true, clientRegistrationClientSecretExpiration: "90d" }),
+    // The client must request and consent to offline_access to receive a rotating refresh token.
+    mcp({ loginPage: "/admin/sign-in", consentPage: "/admin/oauth/consent", resource: `${origin}/mcp`, scopes: ["mcp", "offline_access"], clientRegistrationDefaultScopes: ["mcp", "offline_access"], extensions: [oauthGrantExtension], allowDynamicClientRegistration: true, allowUnauthenticatedClientRegistration: true, allowPublicClientPrelogin: true, clientRegistrationClientSecretExpiration: "90d" }),
     cimd({ fetchClientMetadataResource: (input, init) => fetch(input, { ...init, redirect: "manual" }), metadataProfile: "mcp-2026-07-28" }),
     // --- end MCP / OAuth
   ];