@aotter/mantle 0.2.0-alpha.8 → 0.2.0-alpha.9

package/README.md

@@ -46,6 +46,15 @@ state column names, value types and the writable columns, and the Store enforces
 **not** a View's or Procedure's `requires`: authorize before calling it. Design, limits and what the runtime still refuses are in
 [Store guide](./docs/handbook/guides/typed-queries.md).
 
+For simple creates and partial updates, prefer a declared Store-backed ref
+Procedure: await the caller-bound insert/update, return an allowlist with the
+actual returned `id`/`version`, and preserve omitted fields. Keep Procedure
+`requires` and boundary validation; Store row policy is not operation
+permission. Retain SQL Procedures for atomic conditional/multi-entity writes
+such as stock/order changes and additive upserts. D1 batches cannot consume a
+prior step's result and have no interactive transaction callback. See the
+[write design guidance](./docs/handbook/guides/typed-queries.md#prefer-store-backed-ref-procedures-for-simple-writes).
+
 Importing generated modules does not initialize the Store. The first `store()`
 call prepares its metadata factory once; every call binds its own database,
 Caller and handlers. Unused Stores still tree-shake out of direct operations.
@@ -66,6 +75,14 @@ Rank-ordered exposed Views still need supported keyset ordering; use an internal
 View for arbitrary rank ordering. Applying changed search DDL remains the app's
 migration responsibility; no request runs DDL or rebuilds indexes.
 
+## Independently accept user-facing work
+
+Before reporting any user-facing deliverable as done, follow the version-matched
+[independent acceptance guide](./docs/handbook/guides/agent-workflow-acceptance.md)
+with a fresh agent on the surface its user uses. For MCP work, also run the
+guide's design audit before implementing tools; scripted checks remain separate
+evidence.
+
 ## Publishing
 
 Schemas default to `lifecycle: operational`. Opt-in `lifecycle: publishing` adds status

package/dist/auth/adapter.js

@@ -70,19 +70,22 @@ function customAdapter(d, exec, seed, insertOnly = false, options) {
         const { adminRoles: roles, adminUserIds } = options ? adminOptionsOf({ options }) : { adminRoles: [], adminUserIds: [] };
         const holdsAdmin = (role) => typeof role === "string" && role.split(",").some(role => roles.includes(role));
         const field = (name) => getFieldName({ model: "user", field: name });
-        const protects = (modelKey, values) => modelKey === "user" && roles.length > 0 &&
+        const protects = (modelKey, values) => modelKey === "user" && (roles.length > 0 || adminUserIds.length > 0) &&
             (!values || values[field("banned")] === true || values[field("banned")] === 1 || Object.hasOwn(values, field("role")) && !holdsAdmin(values[field("role")]));
-        const membership = (s, alias) => '(' + roles.map(role => `${d === sqlite ? "instr" : "strpos"}(',' || COALESCE(${alias}.${ident(field("role"))}, '') || ',', ${s.bind(',' + role + ',')}) > 0`).join(' OR ') + ')';
-        const lastAdminGuard = (s, model) => {
+        const membership = (s, alias) => '(' + [...roles.map(role => `${d === sqlite ? "instr" : "strpos"}(',' || COALESCE(${alias}.${ident(field("role"))}, '') || ',', ${s.bind(',' + role + ',')}) > 0`), d === sqlite ? "0" : "FALSE"].join(' OR ') + ')';
+        const allowlisted = (s, alias) => `(${[...adminUserIds.map(id => `${alias}.${idOf("user")} = ${s.bind(id)}`), d === sqlite ? "0" : "FALSE"].join(" OR ")})`;
+        const administrator = (s, alias) => `(${membership(s, alias)} OR ${allowlisted(s, alias)})`;
+        const lastAdminGuard = (s, model, keepsAllowlisted = false) => {
             const table = ident(model), other = '"_mantle_other_admin"', no = d === sqlite ? '0' : 'FALSE';
-            return `(NOT ${membership(s, table)} OR EXISTS (SELECT 1 FROM ${table} ${other} WHERE (${membership(s, other)}${adminUserIds.map(id => ` OR ${other}.${idOf("user")} = ${s.bind(id)}`).join("")}) AND ${other}.${idOf("user")} <> ${table}.${idOf("user")} AND COALESCE(${other}.${ident(field("banned"))}, ${no}) = ${no}))`;
+            return `(${keepsAllowlisted ? `${allowlisted(s, table)} OR ` : ""}NOT ${administrator(s, table)} OR EXISTS (SELECT 1 FROM ${table} ${other} WHERE ${administrator(s, other)} AND ${other}.${idOf("user")} <> ${table}.${idOf("user")} AND COALESCE(${other}.${ident(field("banned"))}, ${no}) = ${no}))`;
         };
         const mutation = async (model, modelKey, where, values) => {
             const protect = protects(modelKey, values);
+            const keepsAllowlisted = protect && !!values && values[field("banned")] !== true && values[field("banned")] !== 1;
             if (protect && (where.length !== 1 || where[0].field !== field("id") || where[0].operator && where[0].operator !== "eq"))
                 throw new APIError("FORBIDDEN", { code: "AUTH_DENIED", message: "Destructive admin identity writes require one user id." });
-            const result = await run(s => `${values ? `UPDATE ${ident(model)} SET ${assign(s, values)}` : `DELETE FROM ${ident(model)}`}${s.where(modelKey, where, protect ? lastAdminGuard(s, model) : undefined)} RETURNING *`, protect);
-            if (protect && !result.changes && (await run(s => `SELECT ${idOf(modelKey)} FROM ${ident(model)}${s.where(modelKey, where, `NOT ${lastAdminGuard(s, model)}`)} LIMIT 1`)).rows.length)
+            const result = await run(s => `${values ? `UPDATE ${ident(model)} SET ${assign(s, values)}` : `DELETE FROM ${ident(model)}`}${s.where(modelKey, where, protect ? lastAdminGuard(s, model, keepsAllowlisted) : undefined)} RETURNING *`, protect);
+            if (protect && !result.changes && (await run(s => `SELECT ${idOf(modelKey)} FROM ${ident(model)}${s.where(modelKey, where, `NOT ${lastAdminGuard(s, model, keepsAllowlisted)}`)} LIMIT 1`)).rows.length)
                 throw new APIError("CONFLICT", { code: "CONFLICT", message: "This is the last admin; promote another admin before removing or banning this one." });
             return result;
         };

package/dist/auth/routes.js

@@ -28,8 +28,9 @@ export function authRoutes(loader, options) {
             if (basePathOf(auth.options) !== base)
                 throw new Error("authRoutes basePath differs from betterAuth options.");
             try {
-                await guardAuthAdminRequest(request, () => resolve(request), base);
-                const registration = request.method === "POST" && pathname === `${base}/oauth2/register` ? await loopbackClientsAreNative(request) : request;
+                const bounded = request.body ? new Request(request, { body: await readBody(request) }) : request;
+                await guardAuthAdminRequest(bounded, () => resolve(bounded), base);
+                const registration = bounded.method === "POST" && pathname === `${base}/oauth2/register` ? await loopbackClientsAreNative(bounded) : bounded;
                 return await normalizeAuthResponseCookies(await auth.handler(registration));
             }
             catch (error) {

package/dist/build/compiler.js

@@ -5094,7 +5094,7 @@ function lifecycleHookSets(plan) {
 }
 
 // src/build/core/version.ts
-var MANTLE_VERSION = "0.2.0-alpha.8";
+var MANTLE_VERSION = "0.2.0-alpha.9";
 
 // src/build/core/sql/ast.ts
 var S = (s) => ({ String: { sval: s } });

package/dist/infrastructure/bundle.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
-import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import { build } from "esbuild";
 import { INPUTS_FILE, authTableSql, extraRoles, generatedTarget, staleInputs } from "./inputs.js";
@@ -41,14 +41,27 @@ export function guardStartup(metafile, entry) {
         }
     }
 }
+/** The physical spelling of a path, including a nonexistent tail below its nearest existing ancestor. */
+const physical = (input) => {
+    let found = resolve(input);
+    const tail = [];
+    while (!existsSync(found)) {
+        const parent = dirname(found);
+        if (parent === found)
+            return found;
+        tail.unshift(basename(found));
+        found = parent;
+    }
+    return resolve(realpathSync(found), ...tail);
+};
 /** Whether `inner` is `outer` or inside it. */
 const within = (outer, inner) => {
-    const path = relative(resolve(outer), resolve(inner));
+    const path = relative(physical(outer), physical(inner));
     return path === "" || (path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path));
 };
 /** A directory a build empties must not be the working directory or hold the source entry. */
 function assertCleanable(label, dir, entry) {
-    if (resolve(dir) === process.cwd())
+    if (physical(dir) === physical(process.cwd()))
         throw new Error(`${label} must not be the working directory: it is cleaned before building.`);
     if (within(dir, entry))
         throw new Error(`${label} must not contain the source entry: it is cleaned before building.`);

package/dist/infrastructure/generate.js

@@ -90,6 +90,14 @@ function outputNameWarnings(plan) {
             inspect("Procedure", name, procedure.handler.sql.stmts);
     return [...new Set(warnings)];
 }
+function missingMcpWarnings(plan) {
+    const mcp = new Set(Object.values(plan.triggers).flatMap(trigger => trigger.source.kind === "mcp" ? [trigger.procedure] : []));
+    const http = new Set(Object.values(plan.triggers).flatMap(trigger => trigger.source.kind === "http" ? [trigger.procedure] : []));
+    return [...http].filter(name => !mcp.has(name)).map(name => {
+        const surface = plan.procedures[name]?.requires?.auth?.all.includes("ctx.admin") ? "admin" : "public";
+        return `Procedure '${name}' has an http Trigger but no mcp Trigger, so the user's AI cannot reach this operation. Add a Trigger with spec.source: { kind: mcp, surface: ${surface} } and spec.target: { procedure: ${name} }.`;
+    });
+}
 export async function generateFromSources(request, schema) {
     const postgres = request.target.endsWith("postgres");
     const compiler = postgres ? postgresCompiler : sqliteCompiler;
@@ -170,5 +178,5 @@ export async function generateFromSources(request, schema) {
     const gatewayFiles = generatedFiles({ "access-targets.ts": `import type { AccessTarget } from "@aotter/mantle/contracts";\nexport const targets: Readonly<Record<string, AccessTarget>> = ${JSON.stringify(accessTargets)};\n` });
     const ddl = [...(postgres ? postgresSchema : sqliteSchema)(compiled.plan.schemas), ...publishingSql(compiled.plan.schemas, !postgres), ...(request.admin ? adminIndexes(compiled.plan.schemas, !postgres) : []), ...(schema?.() ?? [])];
     const { "site-schema.sql": siteSql = "", ...files } = result.files;
-    return { ...result, warnings: [...outputNameWarnings(compiled.plan), ...(request.admin ? adminCreateWarnings(compiled.plan) : []), ...(compiled.plan.access?.warnings ?? [])], files: { ...files, ...gatewayFiles, ...generatedFiles({ "schema.sql": ddl.join(";\n\n") + ";\n" + siteSql }) } };
+    return { ...result, warnings: [...missingMcpWarnings(compiled.plan), ...outputNameWarnings(compiled.plan), ...(request.admin ? adminCreateWarnings(compiled.plan) : []), ...(compiled.plan.access?.warnings ?? [])], files: { ...files, ...gatewayFiles, ...generatedFiles({ "schema.sql": ddl.join(";\n\n") + ";\n" + siteSql }) } };
 }

package/dist/infrastructure/generateAuth.js

@@ -1,4 +1,5 @@
 import { generateFromSources as generate } from "./generate.js";
+import { admin, anonymous, jwt, phoneNumber, siwe, twoFactor } from "better-auth/plugins";
 import { authSchemaSql } from "./authSchema.js";
 /** One or more Better Auth instances (each with its own table names); their DDL is merged. */
 export function generateFromSources(request) {
@@ -12,6 +13,8 @@ function authSql(instances, dialect) {
         if (ids.includes("oauth-provider") && !ids.includes("mantle-oauth-grant-revocation") /* oauthGrantRevocation().id */)
             throw new Error("Better Auth has an OAuth provider (oauthProvider or mcp) without oauthGrantRevocation(): add it from @aotter/mantle/auth/oauth to the plugins, so a password reset, an admin ban or session revocation ends that user's OAuth grants.");
     }
+    if (instances.length > 1)
+        refuseSharedPluginMappings(instances);
     const statements = [...new Set(instances.flatMap(options => authSchemaSql(options, dialect)))];
     // CREATE TABLE IF NOT EXISTS would silently keep the first of two different definitions.
     // Identical statements are already merged, so a repeated table name means two different definitions.
@@ -21,3 +24,51 @@ function authSql(instances, dialect) {
         throw new Error(`Better Auth instances define table ${twice} differently; give each instance its own table names (user.modelName, session.modelName, ...).`);
     return statements;
 }
+// Plugins whose factory hands back one module-level schema object (mergeSchema writes `schema` options into it); no options leaves it untouched.
+const sharedSchema = {
+    jwt: () => jwt().schema, admin: () => admin().schema, anonymous: () => anonymous().schema,
+    "phone-number": () => phoneNumber({}).schema, siwe: () => siwe({}).schema, "two-factor": () => twoFactor().schema,
+};
+// Plugins that share field objects (device-authorization) or copy per call (oauth-provider, listed on request) are only checked for equal resolved names.
+const checkedPlugins = new Set([...Object.keys(sharedSchema), "device-authorization", "oauth-provider"]);
+/** Names a plugin's tables and fields resolve to, keyed `table` / `table.field`; only mappings that differ from the key are listed. */
+function mapped(schema) {
+    const names = new Map();
+    for (const [table, model] of Object.entries(schema)) {
+        if (model.modelName && model.modelName !== table)
+            names.set(table, model.modelName);
+        for (const [field, type] of Object.entries(model.fields ?? {})) {
+            const name = type.fieldName;
+            if (name && name !== field)
+                names.set(`${table}.${field}`, name);
+        }
+    }
+    return names;
+}
+/** Better Auth plugin factories share their schema object, so differing plugin field/model mappings across instances in one Worker override each other. */
+function refuseSharedPluginMappings(instances) {
+    const byPlugin = new Map();
+    instances.forEach((options, index) => (options.plugins ?? []).forEach(plugin => {
+        const schema = plugin.schema;
+        if (schema && checkedPlugins.has(plugin.id))
+            byPlugin.set(plugin.id, [...(byPlugin.get(plugin.id) ?? []), { index, schema }]);
+    }));
+    for (const [id, uses] of byPlugin) {
+        const names = uses.map(use => mapped(use.schema));
+        if (uses.length < 2 || !names.some(own => own.size))
+            continue;
+        const fail = (reason, which) => { throw new Error(`Better Auth plugin ${id} is used by instances ${which.join(", ")} (--auth order, from 0) and ${reason}. Plugin factories share their schema object, so differing plugin field/model mappings across instances in one Worker override each other: pass an explicit \`schema\` mapping to the ${id} plugin in every instance, with names that differ between instances, and give each instance its own copy right after constructing it, \`{ ...plugin, schema: structuredClone(plugin.schema) }\`; or keep the ${id} plugin at its defaults and separate the instances by core table names.`); };
+        const shared = sharedSchema[id]?.();
+        const holders = uses.filter(use => use.schema === shared).map(use => use.index);
+        if (holders.length)
+            fail("a non-default mapping exists while an instance holds the plugin's shared schema object (no own copy)", holders);
+        for (const [i, a] of uses.entries())
+            for (const [j, b] of uses.entries()) {
+                if (j <= i)
+                    continue;
+                for (const [key, name] of names[i])
+                    if (names[j].get(key) === name)
+                        fail(`both resolve ${key} to "${name}"; non-default plugin names must differ between instances, because generate cannot tell an identical mapping from an inherited one`, [a.index, b.index]);
+            }
+    }
+}

package/dist/infrastructure/wrangler.js

@@ -36,7 +36,7 @@ export function configureWrangler(configPath, entry, outdir, generated, check =
             throw new Error("--check requires a JSON or JSONC Wrangler config; TOML generation only prints manual edits.");
         console.log(`Leave ${configPath} unchanged. Add these Wrangler TOML keys (include nodejs_compat and global_fetch_strictly_public in every compatibility_flags override):\n` +
             `main = ${JSON.stringify(keys.main)}\nno_bundle = true\nfind_additional_modules = true\nbase_dir = ${JSON.stringify(worker)}\ncompatibility_flags = ${JSON.stringify(requiredFlags)}\n\n` +
-            (assets === undefined ? "" : `[assets]\ndirectory = ${JSON.stringify(local(assets))}\n\n`) +
+            (assets === undefined ? "" : `[assets]\ndirectory = ${JSON.stringify(local(assets))}\nbinding = "ASSETS"\nrun_worker_first = true\nhtml_handling = "none"\n\n`) +
             `[[rules]]\ntype = "ESModule"\nglobs = ["**/*.js"]\nfallthrough = true\n\n[build]\ncommand = ${JSON.stringify(keys.build.command)}\nwatch_dir = ${JSON.stringify(keys.build.watch_dir)}`);
         return false;
     }
@@ -80,9 +80,24 @@ export function configureWrangler(configPath, entry, outdir, generated, check =
         edit([key], value);
     for (const [key, value] of Object.entries(buildKeys))
         edit(["build", key], value);
-    // Only the directory: the binding, run_worker_first and html_handling stay the application's.
-    if (assets !== undefined)
-        edit(["assets", "directory"], local(assets));
+    if (assets !== undefined) {
+        const wireAssets = (path, current) => {
+            edit([...path, "directory"], local(assets));
+            const ownsDefaults = current === undefined || current?.binding === undefined;
+            if (ownsDefaults && current?.binding === undefined)
+                edit([...path, "binding"], "ASSETS");
+            if (ownsDefaults && current?.run_worker_first === undefined)
+                edit([...path, "run_worker_first"], true);
+            // The shell fetches index.html itself; asset canonicalization would redirect it back to /admin/ forever.
+            if (current?.html_handling === undefined && (current?.run_worker_first === true || (ownsDefaults && current?.run_worker_first === undefined)))
+                edit([...path, "html_handling"], "none");
+        };
+        wireAssets(["assets"], config.assets);
+        for (const [name, environment] of Object.entries(config.env ?? {})) {
+            if (environment?.assets !== undefined)
+                wireAssets(["env", name, "assets"], environment.assets);
+        }
+    }
     if (!(config.rules ?? []).some((r) => isDeepStrictEqual(r, rule)))
         edit(config.rules === undefined ? ["rules"] : ["rules", -1], config.rules === undefined ? [rule] : rule);
     const changed = !exists || text !== original;

package/dist/kernel/binds.d.ts

@@ -36,9 +36,6 @@ export type Bound = {
 };
 /** The dialect functions the recipes in use call; generated code passes only those. */
 export type Values = Partial<Pick<Dialect, "now" | "cutoff" | "timestamp" | "date">> & {
-    readonly user?: (recipe: Extract<Recipe, {
-        k: "user";
-    }>, caller: Caller) => unknown;
     readonly scopeInsert?: Dialect['scopeInsert'];
     readonly userRefs?: (recipe: Recipe, caller: Caller) => unknown;
     /** Present only in apps with user fields: keeps, per caller, one printed form of each Schema scope term. */

package/dist/kernel/contracts.d.ts

@@ -111,7 +111,7 @@ export declare function deny(caller: Caller, allowed: boolean, path: string): vo
 /** CONFLICT for a write the database refused: a unique-index clash, or a row statement that did not change exactly one row. */
 export declare const conflict: (path: string, unique: boolean, cause?: unknown) => ContractError;
 /** A Schema `checks` violation (Mantle's SQLite check trigger, or PostgreSQL SQLSTATE 23514) is a CONFLICT naming the check. */
-export declare const checkConflict: (path: string, error: unknown, violated?: boolean) => ContractError | undefined;
+export declare const checkConflict: (path: string, error: unknown) => ContractError | undefined;
 /** One result of `unsafe`: the rows (typed by the generated function), plus the affected count. */
 export type PostgresResult = any[] & {
     readonly count: number | null;

package/dist/kernel/contracts.js

@@ -54,11 +54,11 @@ export function deny(caller, allowed, path) {
 /** CONFLICT for a write the database refused: a unique-index clash, or a row statement that did not change exactly one row. */
 export const conflict = (path, unique, cause) => new ContractError("CONFLICT", unique ? "A unique constraint of the Schema was violated." : "Expected one affected row.", path, { cause });
 /** A Schema `checks` violation (Mantle's SQLite check trigger, or PostgreSQL SQLSTATE 23514) is a CONFLICT naming the check. */
-export const checkConflict = (path, error, violated = /MANTLE_CHECK /.test(String(error?.message))) => {
-    if (!violated)
+export const checkConflict = (path, error) => {
+    const message = error?.message ?? "", marker = /MANTLE_CHECK ([^:\n]+): (.+)/.exec(message);
+    if (!/MANTLE_CHECK /.test(message))
         return undefined;
-    const message = String(error?.message ?? "");
-    return new ContractError("CONFLICT", `A check of the Schema failed: ${/MANTLE_CHECK [^\n'"]+/.exec(message)?.[0] ?? message}`, path, { cause: error });
+    return new ContractError("CONFLICT", `A check of the Schema failed: ${marker?.[0] ?? message}`, path, { cause: error, fields: { kind: "check", schema: marker?.[1], check: marker?.[2]?.replace(/: SQLITE_CONSTRAINT.*$/, "") } });
 };
 /** A cookie is ambient authority; bearer credentials deliberately supplied by the app are not. */
 export function checkOrigin(request, caller) {

package/dist/kernel/dialect/common.d.ts

@@ -10,7 +10,6 @@ export declare const likeEscape = " ESCAPE '\\'";
  */
 export interface Dialect {
     readonly userRefs?: import('../binds.js').Values['userRefs'];
-    readonly user?: import('../binds.js').Values['user'];
     readonly anyOf?: (column: string, placeholder: string, type: 'string' | 'number') => string;
     readonly scopeInsert?: (scopes: readonly {
         readonly column: string;

package/dist/kernel/driver/postgres.js

@@ -1,4 +1,4 @@
-import { checkConflict, conflict, ContractError } from "../contracts.js";
+import { conflict, ContractError } from "../contracts.js";
 import { context, guard } from "./transaction-context.js";
 const transactions = new WeakSet();
 const ISOLATION = ["serializable", "repeatable read", "read committed", "read uncommitted"];
@@ -9,6 +9,7 @@ export async function run(db, sql, binds) {
 }
 /** SQLSTATE of a server error: `errno` on Bun.SQL, `code` on postgres.js. */
 const sqlstate = (error) => { const e = error; return typeof e?.errno === "string" ? e.errno : e?.code; };
+const check = (path, e) => new ContractError("CONFLICT", `A check of the Schema failed: ${e.message}`, path, { cause: e, fields: { kind: "check", schema: e.table ?? e.table_name, check: e.constraint ?? e.constraint_name } });
 /** A structured server ErrorResponse proves rollback; missing evidence is uncertain. */
 export function definitive(error) {
     if (error instanceof ContractError)
@@ -35,7 +36,7 @@ export async function procedure(db, steps, path) {
     const execute = async (handle) => {
         const results = [];
         for (const s of steps) {
-            const { rows, changes } = await run(handle, s.sql, s.binds).catch(error => { throw sqlstate(error) === "23505" ? conflict(path, true, error) : checkConflict(path, error, sqlstate(error) === "23514") ?? error; });
+            const { rows, changes } = await run(handle, s.sql, s.binds).catch(error => { throw sqlstate(error) === "23505" ? conflict(path, true, error) : sqlstate(error) === "23514" ? check(path, error) : error; });
             if (s.row && changes !== 1)
                 throw conflict(path, false);
             results.push(rows);

package/dist/kernel/mcp-apps.js

@@ -35,6 +35,6 @@ export function linkApps(apps, tools, views) {
 }
 /** One endpoint's Apps bound to its tool table; `previous` is reused while the table's names are unchanged. */
 export function linkSurface(apps, selected, previous) {
-    const key = JSON.stringify(selected.map(tool => tool.name).sort());
+    const key = JSON.stringify(selected.map(tool => [tool.name, !!tool.page]).sort(([a], [b]) => a.localeCompare(b)));
     return previous?.key === key ? previous : { key, links: linkApps(apps, new Set(selected.map(tool => tool.name)), new Set(selected.filter(tool => tool.page).map(tool => tool.name))) };
 }

package/dist/kernel/mcp-handler.js

@@ -94,7 +94,7 @@ export function handler(tools, options, apps = {}, reads = []) {
                     observe(options.onRefusal, { at: Date.now(), status: result.status, reason: "credential" });
                 }
                 if (result.status === 401)
-                    scope ??= requiredScopes.join(" ");
+                    scope = union(scope === undefined ? requiredScopes : scope.split(" "), options.authorizationScopes ?? []);
                 return (await import("./host-caller.js")).hostFailure(error, resolved, `mcp ${path}`, bare ? undefined : 'Bearer ' + (scope ? (result.status === 403 ? 'error="insufficient_scope", ' : '') + 'scope="' + scope + '", ' : '') + 'resource_metadata="' + (options.resourceMetadata ?? url.origin + '/.well-known/oauth-protected-resource/mcp') + '"');
             };
             let caller;

package/dist/kernel/mcp.d.ts

@@ -2,7 +2,9 @@
 import type { Caller, Target, Authorize, Gateway, RequestContext, GatewayOptions } from "./contracts.js";
 import type { Conversions } from "./surface.js";
 import { type McpAppsSource } from "./mcp-apps.js";
-export { callTool, callToolLazy } from "./mcp-call.js";
+type Call = typeof import("./mcp-call.js");
+export declare const callTool: Call["callTool"];
+export declare const callToolLazy: Call["callToolLazy"];
 export type { McpApps, McpAppsSource, McpAppResource, McpAppRender, McpAppPage, McpAppCsp } from "./mcp-apps.js";
 /** Options of a generated `mcp(...)`; it adds required `handlers` when the app declares ref Procedures. */
 export interface Options<Env, Database> extends GatewayOptions {
@@ -28,6 +30,8 @@ export interface Options<Env, Database> extends GatewayOptions {
         }[];
     };
     requiredScopes?: readonly string[];
+    /** Additional scopes requested by an unauthenticated OAuth challenge (for example offline_access), not an API scope floor. */
+    authorizationScopes?: readonly string[];
     resourceMetadata?: string;
     /** Browser origins MCP answers besides loopback, compared by hostname: `https://console.example` or the official SDK's bare `console.example`. The site's own origin is not implied. */
     allowedOrigins?: readonly string[];

package/dist/kernel/mcp.js

@@ -1,5 +1,6 @@
 import { linkApps, linkSurface, resourcesOf } from "./mcp-apps.js";
-export { callTool, callToolLazy } from "./mcp-call.js";
+export const callTool = async (...args) => (await import("./mcp-call.js")).callTool(...args);
+export const callToolLazy = async (...args) => (await import("./mcp-call.js")).callToolLazy(...args);
 /** The selected MCP routes; all request work loads only when an MCP request arrives. */
 export function mcp(tools, options, reads = []) {
     let serve;

package/dist/kernel/scalars.js

@@ -6,9 +6,10 @@
 import { ContractError } from "./contracts.js";
 export function encodeTimestamptz(v) {
     if (v instanceof Date) {
-        if (Number.isNaN(v.getTime()))
+        const micros = v.getTime() * 1000;
+        if (!Number.isSafeInteger(micros))
             throw new ContractError("SQL_TYPE", "Invalid Date is not a timestamp");
-        return v.getTime() * 1000;
+        return micros;
     }
     // hours 00-23: Date.parse would roll T24:00 over to the next day
     const m = /^(\d{4}-\d\d-\d\d)[T ]((?:[01]\d|2[0-3]):\d\d(?::\d\d)?)(?:\.(\d{1,6}))?(Z|[+-]\d\d(?::?\d\d)?)$/.exec(v.trim());

package/dist/kernel/web-index.js

@@ -0,0 +1,40 @@
+/** /llms.txt and /sitemap.xml bodies; loaded only when an index is requested, so page Workers do not pay for it at startup. */
+const escape = (v) => String(v).replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+const label = (v) => String(v).replace(/[\r\n]/g, " ").replace(/[\\[\]]/g, "\\$&");
+const size = (s) => new TextEncoder().encode(s).length;
+export async function webIndex(sitemap, options, pages, list, validUrl) {
+    const cap = sitemap ? 50000 : 5000, limit = sitemap ? 50 * 1024 * 1024 : 1024 * 1024;
+    const start = sitemap ? '<?xml version="1.0" encoding="UTF-8"?><urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">' : "# " + label(options.title) + "\n\n> " + label(options.description) + "\n\n## Pages\n\n", end = sitemap ? "</urlset>" : "\n";
+    const links = [];
+    let visited = 0, requests = 0, bytes = size(start + end);
+    if (bytes > limit)
+        throw new TypeError("Web index header exceeds its byte limit.");
+    pagesLoop: for (const entry of pages) {
+        if (!entry.page.list)
+            continue;
+        let cursor;
+        do {
+            if (requests >= (sitemap ? 100 : 10))
+                break pagesLoop;
+            requests++;
+            const page = await list(entry.page.list, cursor);
+            for (const row of page.rows) {
+                if (visited++ >= cap)
+                    break pagesLoop;
+                const url = validUrl(entry.path, row, entry.page.view);
+                if (!url)
+                    continue;
+                const line = sitemap ? "<url><loc>" + escape(url) + "</loc></url>" : "- [" + label(row.title ?? url) + "](" + url + "): " + label(row.description ?? "") + "\n";
+                const length = size(line);
+                if (bytes + length > limit)
+                    break pagesLoop;
+                bytes += length;
+                links.push(line);
+            }
+            if (visited >= cap)
+                break pagesLoop;
+            cursor = page.nextCursor;
+        } while (cursor);
+    }
+    return start + links.join("") + end;
+}

package/dist/kernel/web.js

@@ -1,9 +1,6 @@
 /** Web output for a generated public View table: /llms.txt, /sitemap.xml, Markdown pages and head tags. SQL owns visibility. */
 import { forwarded, wire, ContractError } from "./contracts.js";
 import { convert, decode } from "./surface.js";
-const escape = (v) => String(v).replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
-const label = (v) => String(v).replace(/[\r\n]/g, " ").replace(/[\\[\]]/g, "\\$&");
-const size = (s) => new TextEncoder().encode(s).length;
 const NO_STORE = { "cache-control": "no-store" };
 const notFound = () => new Response(null, { status: 404, headers: NO_STORE });
 export function web(options, table) {
@@ -76,40 +73,9 @@ export function web(options, table) {
                 const ctx = await context(request, env, execution);
                 caller = ctx.caller;
                 if (index) {
-                    const sitemap = path === "/sitemap.xml", cap = sitemap ? 50000 : 5000, limit = sitemap ? 50 * 1024 * 1024 : 1024 * 1024;
-                    const start = sitemap ? '<?xml version="1.0" encoding="UTF-8"?><urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">' : "# " + label(options.title) + "\n\n> " + label(options.description) + "\n\n## Pages\n\n", end = sitemap ? "</urlset>" : "\n";
-                    const links = [];
-                    let visited = 0, requests = 0, bytes = size(start + end);
-                    if (bytes > limit)
-                        throw new TypeError("Web index header exceeds its byte limit.");
-                    pagesLoop: for (const entry of pages) {
-                        if (!entry.page.list)
-                            continue;
-                        let cursor;
-                        do {
-                            if (requests >= (sitemap ? 100 : 10))
-                                break pagesLoop;
-                            requests++;
-                            const page = await query(entry.page.list, ctx.db, ctx.caller, new URLSearchParams(), cursor);
-                            for (const row of page.rows) {
-                                if (visited++ >= cap)
-                                    break pagesLoop;
-                                const url = validUrl(entry.path, row, entry.page.view);
-                                if (!url)
-                                    continue;
-                                const line = sitemap ? "<url><loc>" + escape(url) + "</loc></url>" : "- [" + label(row.title ?? url) + "](" + url + "): " + label(row.description ?? "") + "\n";
-                                const length = size(line);
-                                if (bytes + length > limit)
-                                    break pagesLoop;
-                                bytes += length;
-                                links.push(line);
-                            }
-                            if (visited >= cap)
-                                break pagesLoop;
-                            cursor = page.nextCursor;
-                        } while (cursor);
-                    }
-                    return response(request, start + links.join("") + end, sitemap ? "application/xml" : "text/plain", ctx.caller);
+                    const sitemap = path === "/sitemap.xml";
+                    const body = await (await import("./web-index.js")).webIndex(sitemap, options, pages, (list, cursor) => query(list, ctx.db, ctx.caller, new URLSearchParams(), cursor), validUrl);
+                    return response(request, body, sitemap ? "application/xml" : "text/plain", ctx.caller);
                 }
                 const exact = match(path);
                 if (exact)

package/dist/usecase/publishing.js

@@ -36,7 +36,7 @@ export function emitPublishing(plan, isSqlite, declarations, procedures, entries
                 // 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);

package/dist/usecase/site.js

@@ -32,7 +32,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/validation.js

@@ -157,6 +157,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)

package/docs/examples/README.md

@@ -31,5 +31,5 @@ shell's allow-all `src/signup.ts`, unless sign-up should be invite-only. Purchas
 
 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-alpha.9/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

@@ -39,8 +39,9 @@ on one version.
 | `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). |
 
-`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.
 
@@ -52,6 +53,9 @@ Search for `AGENT:` to find what an app must fill in.
   the previous role; `/admin/api/me` shows the current one.
 - Admin HTTP routes are listed in `docs/handbook/guides/native-admin.md`.
 
+Scripted smoke is not independent acceptance; before reporting a user-facing
+deliverable done, follow the [independent acceptance guide](../../handbook/guides/agent-workflow-acceptance.md).
+
 ### MCP acceptance
 
 Generation declares tools; the app owns whether and where a remote endpoint is mounted.

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

@@ -14,8 +14,8 @@
     "smoke": "node smoke.mjs"
   },
   "dependencies": {
-    "@aotter/mantle": "0.2.0-alpha.8",
-    "@aotter/mantle-ui": "0.2.0-alpha.8",
+    "@aotter/mantle": "0.2.0-alpha.9",
+    "@aotter/mantle-ui": "0.2.0-alpha.9",
     "@better-auth/cimd": "1.7.7",
     "@better-auth/core": "1.7.7",
     "@better-auth/mcp": "1.7.7",
@@ -24,7 +24,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-alpha.9",
     "react": "19.3.0",
     "react-dom": "19.3.0"
   },

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
   ];

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

@@ -56,8 +56,8 @@ export async function fetchService(request: Request, env: Env, context: Executio
       }
       response = await serveAdmin(request, env);
     } else if (/^\/mcp(?:\/admin)?\/*$/.test(url.pathname)) {
-      // --- MCP (optional): delete this branch with the MCP plugins in auth.ts if the app has no MCP.
-      serveMcpHandler ??= serveMcp(tools, { ...options, apps: { admin: adminMcpApps({ catalogue: mcpAppCatalogues.admin }) } });
+      // --- MCP / OAuth (deliberate exception): remove with the auth plugins only for intentional asymmetric exposure.
+      serveMcpHandler ??= serveMcp(tools, { ...options, authorizationScopes: ["offline_access"], apps: { admin: adminMcpApps({ catalogue: mcpAppCatalogues.admin }) } });
       response = await serveMcpHandler(request, env);
     } else {
       response = await serveRest(request, env);