@aotter/mantle 0.2.0-alpha.8 → 0.2.0

package/dist/kernel/driver/bun-sqlite.js

@@ -4,7 +4,6 @@ export { definitive } from "../dialect/sqlite.js";
 import { context, guard } from "./transaction-context.js";
 const transactions = new WeakSet();
 const queues = new WeakMap();
-/** Only queued transactions make otherwise synchronous statements wait; a rejection cannot poison the queue. */
 function enqueue(db, fn) {
     const result = (queues.get(db) ?? Promise.resolve()).then(fn);
     const tail = result.then(() => { }, () => { });
@@ -15,11 +14,9 @@ function enqueue(db, fn) {
 }
 const available = (db, fn) => { guard(db); return queues.has(db) ? enqueue(db, fn) : fn(); };
 export const read = (db, sql, binds) => available(db, () => db.query(sql).all(...binds));
-/** One statement is atomic on its own; several run in a transaction, and a row statement that does not change exactly one row rolls it back. A unique-index clash is CONFLICT. */
 export async function procedure(db, steps, path) {
     const execute = (handle) => steps.map(s => {
         const statement = handle.query(s.sql);
-        // a statement with columns (SELECT, RETURNING) gives rows, and their number is its affected count
         let rows = [], changes;
         try {
             rows = statement.columnNames.length ? statement.all(...s.binds) : [];
@@ -27,7 +24,6 @@ export async function procedure(db, steps, path) {
                 changes = rows.length;
             else {
                 statement.run(...s.binds);
-                // Bun's run().changes includes FTS maintenance writes; SQLite changes() counts the authored statement only.
                 changes = s.row ? Number(handle.query("SELECT changes() AS n").all()[0].n) : 0;
             }
         }

package/dist/kernel/driver/d1.js

@@ -2,7 +2,6 @@ import { checkConflict, conflict } from "../contracts.js";
 import { unique } from "../dialect/sqlite.js";
 export { definitive } from "../dialect/sqlite.js";
 export const read = async (db, sql, binds) => (await db.prepare(sql).bind(...binds).all()).results;
-/** The assert table's trigger aborts the whole batch with `CONFLICT op=<k>` when statement k did not change exactly one row. */
 export async function procedure(db, steps, path) {
     const batch = [], at = [];
     steps.forEach((s, i) => {

package/dist/kernel/driver/postgres.js

@@ -1,4 +1,4 @@
-import { checkConflict, conflict, ContractError } from "../contracts.js";
+import { conflict, ContractError, schemaCheckFailed } from "../contracts.js";
 import { context, guard } from "./transaction-context.js";
 const transactions = new WeakSet();
 const ISOLATION = ["serializable", "repeatable read", "read committed", "read uncommitted"];
@@ -7,35 +7,24 @@ export async function run(db, sql, binds) {
     const rows = await read(db, sql, binds);
     return { rows, changes: Number(rows.count ?? 0) };
 }
-/** 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; };
-/** A structured server ErrorResponse proves rollback; missing evidence is uncertain. */
+const check = (path, e) => schemaCheckFailed(path, e, e.table ?? e.table_name, e.constraint ?? e.constraint_name);
 export function definitive(error) {
     if (error instanceof ContractError)
         return error.code === "CONFLICT";
     const state = sqlstate(error);
     return typeof state === "string" && /^[0-9A-Z]{5}$/.test(state) && typeof error?.severity === "string" && !/^(08|28|53|57|58|XX)/.test(state);
 }
-/**
- * The error to throw when a PostgreSQL write fails where it may already have committed (autocommit, or COMMIT).
- * A server ErrorResponse (SQLSTATE + severity) outside connection/resource classes rolled back; anything else, such as a
- * lost socket, is OUTCOME_UNKNOWN.
- */
 export function postgresOutcome(error, path) {
     if (definitive(error))
         return error;
     return new ContractError("OUTCOME_UNKNOWN", "The write outcome is unknown; reconcile before retrying.", path, { cause: error });
 }
-/**
- * One statement is atomic on its own (a row statement touches at most one row, so a failed count check changes nothing)
- * and runs in autocommit. Several run in `begin(serializable)`: a failure before the callback returns was rolled back;
- * only a failed COMMIT can leave the outcome unknown.
- */
 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);
@@ -54,18 +43,15 @@ export async function procedure(db, steps, path) {
     }
     return transaction(db, execute, undefined, path);
 }
-/** Shared BEGIN/COMMIT outcome handling for Procedures and interactive Store transactions. */
 export async function transaction(db, fn, options = {}, path = "store/transaction") {
     guard(db);
     if (transactions.has(db))
         throw new Error("Nested transactions are not supported.");
-    // a transaction handle the app opened (postgres.js types it without `begin`) only suits reads and single statements
     if (typeof db.begin !== "function")
         throw new Error("This PostgreSQL handle is a transaction the app opened and cannot begin another: open the transaction with store(pool, caller).transaction and call Procedures through its tx.");
     let committing = false;
     const state = { outer: db };
     try {
-        // printed into BEGIN, so only PostgreSQL's own four levels: a handler may pass request input here
         const level = options.isolation ?? "serializable";
         if (!ISOLATION.includes(level))
             throw new ContractError("INPUT_VALIDATION_FAILED", `isolation '${level}' is not a PostgreSQL isolation level`, path);

package/dist/kernel/driver/transaction-context.js

@@ -5,7 +5,6 @@ export function guard(db) {
     if (context.getStore()?.outer === db)
         throw new ContractError("INPUT_VALIDATION_FAILED", "Inside store.transaction use tx, not the outer store or handle.", "store/transaction");
 }
-/** One atomic write cannot publish a translation and change its parent's status. */
 export function translationWrite(db, schema, parent) {
     const state = context.getStore();
     if (!state || state.handle !== db)

package/dist/kernel/email.js

@@ -24,10 +24,6 @@ export function adminInvitationEmail(role, signInUrl) {
         signInUrl,
     ]);
 }
-/**
- * Local development only: logs recipients and sign-in secrets, sends nothing.
- * Select at the application's environment boundary; never use in production.
- */
 export class ConsoleEmailSender {
     async send(args) {
         const { to, subject, text, locale, category } = args;

package/dist/kernel/host-access.js

@@ -1,6 +1,6 @@
-/** Request-only gateway decisions and observation; no database or compiler dependencies. */
 import { forwarded, ContractError, wire } from "./contracts.js";
-import { isHostCaller, checkFresh } from "./caller-identity.js";
+import { isHostCaller } from "./caller-identity.js";
+import { checkFresh } from "./caller-mode.js";
 const logged = new WeakSet();
 export function accessRequest(ctx, options) {
     const present = forwarded(ctx);
@@ -43,7 +43,6 @@ export function accessRequest(ctx, options) {
                     logged.add(listener);
                     console.error("[mantle onAccess] listener failed");
                 } };
-                // Schedule observation after the decision without awaiting its promise.
                 queueMicrotask(() => { try {
                     void Promise.resolve(listener(finished)).catch(log);
                 }

package/dist/kernel/host-caller.d.ts

@@ -36,4 +36,4 @@ export declare function gatewayCaller(ctx: RequestContext | undefined, gateway:
 /** Host errors are machine-readable and never challenge for application credentials. */
 export declare function hostFailure(error: unknown, caller?: Caller, where?: string, challenge?: string): Response;
 export { isHostCaller } from "./caller-identity.js";
-export { checkFresh } from "./caller-identity.js";
+export { checkFresh } from "./caller-mode.js";

package/dist/kernel/host-caller.js

@@ -1,10 +1,9 @@
-/** Request-only host contract validation. */
 export { draining } from "./drain.js";
-import { forwarded, ContractError, surfaceError, surfaceFailure } from "./contracts.js";
+import { forwarded, ContractError } from "./contracts.js";
+import { surfaceError, surfaceFailure } from "./surface-failure.js";
 import { userCaller } from "./user-caller.js";
 import { identities, isHostCaller } from "./caller-identity.js";
 const hostContract = (message, field) => { throw new ContractError("HOST_CONTRACT", message, "", { status: 412, fields: field ? { field } : undefined }); };
-/** Validate the forwarding contract and reuse the ordinary user validation and brand. */
 export function hostCaller(props, options) {
     const record = (v) => !!v && typeof v === "object" && !Array.isArray(v) && (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
     const text = (v) => typeof v === "string" && v.length > 0 && !v.includes("\0") && v.isWellFormed();
@@ -35,7 +34,6 @@ export function hostCaller(props, options) {
     identities.set(caller, Object.freeze({ ...identities.get(base), admin: caller.admin, host: true }));
     return caller;
 }
-/** Resolve only forwarded props, or trip on an entry that did not opt in. */
 export function gatewayCaller(ctx, gateway, fields) {
     const present = forwarded(ctx);
     if (!gateway)
@@ -44,7 +42,6 @@ export function gatewayCaller(ctx, gateway, fields) {
         return { kind: 'anonymous' };
     return hostCaller(ctx.props.mantle, { tenant: gateway.tenant, fields });
 }
-/** Host errors are machine-readable and never challenge for application credentials. */
 export function hostFailure(error, caller, where, challenge) {
     if ((!caller || !isHostCaller(caller)) && !(error instanceof ContractError && error.code === 'HOST_CONTRACT'))
         return surfaceFailure(error, challenge, where);
@@ -53,4 +50,4 @@ export function hostFailure(error, caller, where, challenge) {
     return Response.json({ error: { code, ...(typeof result.error.field === 'string' ? { field: result.error.field } : {}), ...(result.error.path ? { target: result.error.path } : {}) } }, { status: result.status === 401 ? 403 : result.status, headers: { 'cache-control': 'private, no-store' } });
 }
 export { isHostCaller } from "./caller-identity.js";
-export { checkFresh } from "./caller-identity.js";
+export { checkFresh } from "./caller-mode.js";

package/dist/kernel/json-body.js

@@ -1,5 +1,3 @@
-/** Request-only JSON reader: bound bytes before copying or parsing, independent of UTF-8 chunk boundaries. */
-/** Bound raw bytes before decoding a request body. */
 export async function bytes(request, limit, fail) {
     if (!Number.isSafeInteger(limit) || limit < 1)
         fail("Body limit must be a positive safe integer.");

package/dist/kernel/mcp-apps.js

@@ -1,9 +1,6 @@
 import { ContractError } from "./contracts.js";
-/** MCP Apps (ADR-0029 D7): UI resources served beside the tools that render in them. */
 export const RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
-/** Flatten contributors; `mcp(...)` reads static resources getters once at construction. */
 export const resourcesOf = (apps) => ({ resources: (Array.isArray(apps) ? apps : [apps]).flatMap(app => app.resources) });
-/** Static contributors are checked at construction; resolved factories are checked per request. A request-bound tool table defers tool-link checks until its first request. */
 export function linkApps(apps, tools, views) {
     const resources = resourcesOf(apps).resources;
     const uris = new Set(), names = new Set(), renders = new Map(), appOnly = new Set();
@@ -24,7 +21,6 @@ export function linkApps(apps, tools, views) {
                 refuse(`Tool '${tool}' is claimed by two MCP App resources.`);
             renders.set(tool, resource.uri);
         }
-        // an App acts for the user without the model seeing the call, so only a read may be hidden from the model
         for (const tool of resource.appOnly ?? []) {
             if (views && !views.has(tool))
                 refuse(`App-only tool '${tool}' must be a View this endpoint serves.`);
@@ -33,8 +29,7 @@ export function linkApps(apps, tools, views) {
     }
     return { resources, renders, appOnly };
 }
-/** 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-call.js

@@ -3,7 +3,6 @@ import { checkPageLimit } from "./paging.js";
 export async function callTool(tool, raw, db, caller, handlers) {
     return callToolLazy(tool, raw, () => db, caller, handlers);
 }
-/** Transport input is checked before acquiring an application-owned native handle. */
 export async function callToolLazy(tool, raw, getDb, caller, handlers, dryRun) {
     if (tool.page) {
         const { limit, cursor, ...input } = raw;

package/dist/kernel/mcp-handler.js

@@ -1,6 +1,6 @@
-/** Request-only MCP implementation, excluded from Worker startup. */
 import { authorized, authorizeTarget } from "./authorization.js";
-import { forwarded, isAdmin, ContractError, checkOrigin, surfaceCaller, surfaceError, wire } from "./contracts.js";
+import { forwarded, isAdmin, ContractError, wire } from "./contracts.js";
+import { checkOrigin, surfaceCaller, surfaceError } from "./surface-failure.js";
 import { draining } from "./drain.js";
 import { callToolLazy as callTool } from "./mcp-call.js";
 import { RESOURCE_MIME_TYPE, linkSurface, resourcesOf } from "./mcp-apps.js";
@@ -19,15 +19,8 @@ function observe(listener, event) {
         catch { }
 }
 const paging = (schema) => ({ ...schema, properties: { ...schema.properties, limit: { type: "integer", minimum: 1, maximum: 500 }, cursor: { type: "string" } } });
-/**
- * Characters of `JSON.stringify(page)` an MCP View page may hold. A result carries its rows twice (text block and
- * `structuredContent`) and hosts are reported to truncate near 150k characters, so one copy stays at 60k.
- * ponytail: one fixed number; raise it or make it an option if hosts publish their limits.
- */
 const MCP_PAGE_BUDGET = 60_000;
-/** The scopes a challenge asks for: the credential's, plus what the request needs. */
 const union = (scopes, extra) => [...new Set([...scopes, ...extra])].join(" ");
-/** The handler for `/mcp` (public tools) and `/mcp/admin` (tools for `admin` roles); other paths are undefined. */
 export function handler(tools, options, apps = {}, reads = []) {
     const allowed = options.allowedOrigins ?? [];
     return draining(async (request, env, ctx) => {
@@ -38,8 +31,6 @@ export function handler(tools, options, apps = {}, reads = []) {
             const url = new URL(request.url), path = url.pathname.replace(/\/+$/, ""), surface = path === "/mcp" ? "public" : path === "/mcp/admin" ? "admin" : undefined;
             if (!surface)
                 return;
-            // MCP transport MUST: a present Origin is a browser, answered only for loopback or `allowedOrigins`. The request's own
-            // host is not implied, since a DNS-rebinding page sends Origin == its rebound Host; a missing Origin is a server client.
             if (request.headers.has("origin")) {
                 const sdk = await import("@modelcontextprotocol/server");
                 const foreign = sdk.originValidationResponse(request, [...sdk.localhostAllowedOrigins(), ...allowed]);
@@ -51,7 +42,6 @@ export function handler(tools, options, apps = {}, reads = []) {
                 }
             }
             const select = async () => (typeof tools === "function" ? await tools(request, env) : tools).filter(tool => tool.surface === surface);
-            // Dynamic admin tables stay behind the admin gate; cache classification uses generated metadata only.
             let selected = surface === "public" ? await select() : [];
             let parsedBody, tooLarge = false;
             const cookieOnly = request.headers.has("cookie") && !request.headers.has("authorization");
@@ -94,7 +84,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;
@@ -120,7 +110,6 @@ export function handler(tools, options, apps = {}, reads = []) {
             }
             if (surface === "admin")
                 selected = await select();
-            // Before per-caller filtering, so every caller of a deploy sees one catalogue version.
             const version = catalogueVersion(selected);
             const { McpServer, ProtocolError, ProtocolErrorCode, createMcpHandler, fromJsonSchema } = await import("@modelcontextprotocol/server");
             if (request.method === "POST" && !cookieOnly && !options.gateway)
@@ -176,7 +165,6 @@ export function handler(tools, options, apps = {}, reads = []) {
                 const sources = (Array.isArray(app) ? app : [app]);
                 const dynamic = sources.some(source => typeof source === "function");
                 const resolved = resourcesOf(await Promise.all(sources.map(source => typeof source === "function" ? source({ env, request }) : source)));
-                // Equal tool names say nothing about request-bound resource identity or ownership.
                 const current = linkSurface(resolved, selected, dynamic ? undefined : apps[surface]);
                 if (!dynamic)
                     apps[surface] = current;
@@ -193,7 +181,6 @@ export function handler(tools, options, apps = {}, reads = []) {
                         tool.check?.(caller);
                         await authorizeTarget(options.authorize, tool.target ?? { kind: tool.page ? "view" : "procedure", name: tool.name }, caller);
                     }
-                    // an App's HTML is rendered for the same tools the caller's tools/list shows
                     if ((Array.isArray(parsedBody) ? parsedBody : [parsedBody]).some(message => message?.method === "tools/list" || message?.method === "resources/read")) {
                         const visible = [];
                         for (const tool of selected) {
@@ -218,17 +205,13 @@ export function handler(tools, options, apps = {}, reads = []) {
                 }
             }
             const serverInfo = { name: "aotter.mantle", ...options.serverInfo, version: options.serverInfo?.version ?? version };
-            // Host calls execute in the SDK callback, after transport validation.
             const handler = createMcpHandler(() => {
                 const schema = (value) => fromJsonSchema(value, { getValidator() { return (input) => ({ valid: true, data: input, errorMessage: undefined }); } });
-                // Tools capability after construction: given to the constructor, the SDK installs its tools/call handler before the wrap below.
                 const server = new McpServer(serverInfo, options.instructions ? { instructions: options.instructions } : {});
                 server.server.registerCapabilities({ tools: { listChanged: false } });
                 if (host)
                     server.server.onclose = () => access?.finish(isRecord(parsedBody) && parsedBody.method === "initialize" ? undefined : new ContractError("INPUT_VALIDATION_FAILED", "MCP request refused.", "mcp", { status: 400 }));
                 const appMeta = links ? registerApps(server, links, parsedBody, new Set(selected.map(tool => tool.name)), { env, request }) : undefined;
-                // A host's stale copy names a tool this catalogue lacks: say so, with the catalogue version, instead of the SDK's bare "not found".
-                // Wrapped where the SDK stores it, so transport and request validation still answer first.
                 const registered = new Set(), set = server.server.setRequestHandler.bind(server.server);
                 server.server.setRequestHandler = ((method, handler) => set(method, method === "tools/call" && typeof handler === "function" ? (request, context) => {
                     if (!registered.has(request.params.name))
@@ -240,7 +223,6 @@ export function handler(tools, options, apps = {}, reads = []) {
                     if (meta === false)
                         continue;
                     registered.add(tool.name);
-                    // Not part of structured output: the version, and on failure the current input contract.
                     const about = (contract) => { const text = [tool.version && `tool version ${tool.version}`, contract && `input schema ${JSON.stringify(tool.page ? paging(tool.inputSchema) : tool.inputSchema)}`].filter(Boolean).join("; "); return text ? [{ type: "text", text }] : []; };
                     server.registerTool(tool.name, { ...(meta ? { _meta: meta } : {}), ...(tool.title ? { title: text(tool.title, locale) } : {}), description: text(tool.description, locale) ?? text(tool.title, locale) ?? tool.name, inputSchema: schema(tool.page ? paging(tool.inputSchema) : tool.inputSchema), ...(tool.outputSchema ? { outputSchema: schema(tool.outputSchema) } : {}), ...(tool.annotations ? { annotations: tool.annotations } : {}) }, async (raw) => {
                         const metadata = options.onObservation ? { kind: "invocation", surface, invocationId: crypto.randomUUID(), tool: tool.name, caller: Object.freeze(caller.kind === "user" ? { ...caller, scopes: Object.freeze([...caller.scopes]) } : { ...caller }) } : undefined;
@@ -256,8 +238,6 @@ export function handler(tools, options, apps = {}, reads = []) {
                             let db;
                             const run = (input) => callTool(tool, input, () => db ??= options.db(env), caller, options.handlers, access?.dryRun ? () => ({ dryRun: true, event: access.finish() }) : undefined);
                             let data = await run(raw);
-                            // A page is cut before the first row that overflows the budget: the same page re-runs with the limit that fits, so the cursor is the View's own.
-                            // Data can change between reads, so the re-run is measured again. A View without an order is one page and refuses a smaller limit: it stays whole.
                             for (let tries = 0; tool.page && isRecord(data) && Array.isArray(data.rows); tries++) {
                                 const rows = data.rows, total = JSON.stringify(data).length;
                                 if (total <= MCP_PAGE_BUDGET)
@@ -299,7 +279,6 @@ export function handler(tools, options, apps = {}, reads = []) {
                         }
                     });
                 }
-                // An empty catalogue still answers tools/list and refuses calls the same way.
                 if (registered.size === 0) {
                     server.server.setRequestHandler("tools/list", () => ({ tools: [] }));
                     server.server.setRequestHandler("tools/call", () => ({ content: [] }));
@@ -319,14 +298,12 @@ export function handler(tools, options, apps = {}, reads = []) {
         }
     });
 }
-/** A hash of the tools an endpoint serves (`surface:name:version`, sorted), as 32-bit FNV-1a hex: it changes with any tool's definition. */
 function catalogueVersion(tools) {
     const text = JSON.stringify(tools.map(tool => `${tool.surface}:${tool.name}:${tool.version ?? ""}`).sort());
     return [...text].reduce((h, c) => Math.imul(h ^ c.codePointAt(0), 16777619) >>> 0, 2166136261).toString(16).padStart(8, "0");
 }
 const CLIENT_CAPABILITIES_META_KEY = "io.modelcontextprotocol/clientCapabilities";
 const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
-/** `unknown`: a stateless request after `initialize` carries no capabilities, so only an explicit refusal hides Apps. */
 function clientUiSupport(message) {
     for (const m of Array.isArray(message) ? message : [message]) {
         if (!isRecord(m) || !isRecord(m.params))
@@ -344,7 +321,6 @@ function appMeta(r, csp = r.csp) {
     const ui = { ...(csp ? { csp } : {}), ...(r.permissions ? { permissions: r.permissions } : {}), ...(r.domain !== undefined ? { domain: r.domain } : {}), ...(r.prefersBorder !== undefined ? { prefersBorder: r.prefersBorder } : {}) };
     return Object.keys(ui).length > 0 ? { ui } : undefined;
 }
-/** Registration uses the official SDK; HTML loaders run only on resources/read. */
 function registerApps(server, links, message, tools, request) {
     const enabled = clientUiSupport(message) !== "unsupported";
     if (enabled)

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,21 +1,18 @@
 import { linkApps, linkSurface, resourcesOf } from "./mcp-apps.js";
-export { callTool, callToolLazy } from "./mcp-call.js";
-/** The selected MCP routes; all request work loads only when an MCP request arrives. */
+export const callTool = async (...args) => (await import("./mcp-call.js")).callTool(...args);
+export const callToolLazy = async (...args) => (await import("./mcp-call.js")).callToolLazy(...args);
 export function mcp(tools, options, reads = []) {
     let serve;
-    // Check known static App configuration now; factories wait for the request caller gate.
     const linked = {};
     const apps = {};
     for (const surface of ["public", "admin"]) {
         const declared = options.apps?.[surface];
         if (declared) {
-            // Read each static contributor's resources getter once, including mixed arrays.
             const sources = (Array.isArray(declared) ? declared : [declared])
                 .map(source => typeof source === "function" ? source : resourcesOf(source));
             const fixed = resourcesOf(sources.filter(source => typeof source !== "function"));
             const dynamic = sources.some(source => typeof source === "function");
             apps[surface] = dynamic ? sources : fixed;
-            // Known static conflicts still fail before any request or dynamic factory runs.
             if (typeof tools === "function")
                 linkApps(fixed);
             else {
@@ -34,7 +31,6 @@ export function mcp(tools, options, reads = []) {
         return serve(request, env, ctx);
     };
 }
-/** `allowedOrigins` as the hostnames the official SDK compares; a bad entry fails here, not on each request. */
 function originHostnames(origins = []) {
     return Object.freeze(origins.map(origin => {
         let url;

package/dist/kernel/media.js

@@ -1,33 +1,23 @@
-/** 0.2 media lifecycle over native target drivers. No bytes pass through this module. */
 import { ContractError } from "./contracts.js";
 const P = "media";
-/** HTTP status of each media code: a custom MediaStorage may throw them without one. */
 const STATUS = new Map(Object.entries({
     MEDIA_PURPOSE_REJECTED: 400, MEDIA_SVG_REJECTED: 400, MEDIA_MIME_REJECTED: 400, MEDIA_VARIANTS_INCOMPLETE: 400, MEDIA_VARIANT_SIZE_EXCEEDED: 400, MEDIA_VARIANTS_SUSPICIOUS_SIZE: 400,
     MEDIA_ASSET_NOT_FOUND: 404, MEDIA_OBJECT_NOT_FOUND: 409, MEDIA_UPLOAD_EXPIRED: 410, SITE_NOT_CONFIGURED: 501, MEDIA_NOT_CONFIGURED: 501, PARTIAL_FAILURE: 503,
 }));
 const extra = (code) => ({ status: STATUS.get(code), ...(code === "PARTIAL_FAILURE" ? { fields: { failure: { outcome: "partial", retry: "safe", resource: "media" } } } : {}) });
-/**
- * A media, site or partial-failure error with the HTTP status (and `failure` payload) its code has on the wire. Code
- * outside this module raising these codes uses it: core `statusOf` maps only the core codes.
- */
 export const mediaError = (code, message, path = P, options) => new ContractError(code, message, path, { ...options, ...extra(code) });
 const fail = (code, message, options) => mediaError(code, message, P, options);
-/** A storage error keeps the wire status its code has always had. */
 const own = (error) => { if (error instanceof ContractError && !error.status && STATUS.has(error.code))
     Object.assign(error, extra(error.code)); return error; };
 const rejected = (results) => results.filter((r) => r.status === "rejected");
 const bad = (expected) => fail("INPUT_VALIDATION_FAILED", `expected ${expected}`);
-/** SVG is refused: object storage does not sanitize it, and an SVG can carry script. */
 const ALLOWED = new Set(["image/png", "image/jpeg", "image/webp", "image/avif", "image/gif"]);
-/** Modern formats a skipped optimization makes larger than the fallback. */
 const MODERN = new Set(["image/avif", "image/webp"]);
 const ROLES = new Set(["primary", "alternate", "fallback"]);
 const TTL_MS = 15 * 60 * 1000;
 const obj = (v) => (v !== null && typeof v === "object" && !Array.isArray(v) ? v : {});
 const MAX_TEXT = 1000;
 const MAX_FILENAME = 255;
-/** `alt` and `caption`: absent, or a string of at most 1000 characters. */
 function texts(body) {
     const b = obj(body);
     for (const k of ["alt", "caption"])
@@ -35,7 +25,6 @@ function texts(body) {
             throw bad(`{ alt?: string, caption?: string }, each at most ${MAX_TEXT} characters`);
     return { ...(typeof b["alt"] === "string" ? { alt: b["alt"] } : {}), ...(typeof b["caption"] === "string" ? { caption: b["caption"] } : {}) };
 }
-/** Exactly one variant per required slot, nothing outside them, and exactly one primary. */
 function checkVariants(policy, variants) {
     const slots = policy.required.map(slot => slot.split(","));
     const slotOf = new Map(slots.flatMap((mimes, i) => mimes.map((m) => [m, i])));
@@ -99,7 +88,6 @@ export function mediaLibrary(driver, d, storage, policies, now = Date.now) {
             checkVariants(policy, asked);
             const at = now();
             const expiresAt = at + TTL_MS;
-            // bearer-equivalent until commit: storage keys under it must not be guessable
             const uploadGroupId = crypto.randomUUID();
             const specs = asked.map(({ mimeType, byteSize, role }) => ({ mimeType, byteSize, role, maxBytes: policy.maxBytes[mimeType] }));
             let capabilities;
@@ -126,7 +114,6 @@ export function mediaLibrary(driver, d, storage, policies, now = Date.now) {
                 return assetOf(committed);
             const row = await one(`SELECT record FROM pending_media_uploads WHERE id = ${p(1)}`, [uploadGroupId]);
             const record = row ? JSON.parse(String(row.record)) : null;
-            // a rejected group's objects are deleted: an upload URL takes any type and size, so what was PUT is not trusted
             const discard = () => removeAll(record?.variants ?? []);
             if (!record || record.expiresAt <= now()) {
                 if (record) {
@@ -139,7 +126,6 @@ export function mediaLibrary(driver, d, storage, policies, now = Date.now) {
             try {
                 asset = await storage.commitUpload({
                     uploadGroupId, filename: record.filename, now: record.createdAt,
-                    // the declared size is the cap: a larger object than announced is refused
                     variants: record.variants.map((v) => ({ mimeType: v.mimeType, role: v.role, storageKey: v.storageKey, maxBytes: Math.min(v.maxBytes, v.expectedSize) })),
                     ...((patch.alt ?? record.alt) !== undefined ? { alt: patch.alt ?? record.alt } : {}),
                     ...((patch.caption ?? record.caption) !== undefined ? { caption: patch.caption ?? record.caption } : {}),
@@ -158,7 +144,6 @@ export function mediaLibrary(driver, d, storage, policies, now = Date.now) {
             if (asset.id !== uploadGroupId)
                 throw new ContractError("OUTCOME_UNKNOWN", "Storage returned a different asset id; reconcile this upload group.", P);
             await driver.write([save(asset, p), unpend(uploadGroupId)]).catch(async (error) => {
-                // Cleanup requires positive native rollback evidence; an unclassified failure may have committed.
                 if (driver.definitive?.(error) === true) {
                     const failed = rejected(await removeAll(asset.variants));
                     if (failed.length)
@@ -168,7 +153,6 @@ export function mediaLibrary(driver, d, storage, policies, now = Date.now) {
                 throw error instanceof ContractError && error.code === "OUTCOME_UNKNOWN" ? error : new ContractError("OUTCOME_UNKNOWN", "The write outcome is unknown; reconcile this upload group before retrying.", P, { cause: error });
             });
             const durable = await get(uploadGroupId);
-            // ON CONFLICT may select another concurrent attempt. Only discard this attempt's unselected copies.
             const selected = new Set(durable.variants.map(v => v.storageKey));
             if (rejected(await removeAll(asset.variants.filter(v => !selected.has(v.storageKey)))).length)
                 throw new ContractError("OUTCOME_UNKNOWN", "The asset is committed, but unselected upload copies need storage reconciliation.", P);
@@ -193,7 +177,6 @@ export function mediaLibrary(driver, d, storage, policies, now = Date.now) {
             const patch = Object.entries(texts(request));
             if (!patch.length)
                 return get(id);
-            // only the patched columns, and only a row that still exists: a concurrent delete or edit of the other field stands
             const [r] = (await driver.write([{ sql: `UPDATE media_assets SET ${patch.map(([k], i) => `${k} = ${p(i + 2)}`).join(", ")} WHERE id = ${p(1)} RETURNING ${COLUMNS}`, binds: [id, ...patch.map(([, v]) => v)] }]))[0];
             if (!r)
                 throw fail("MEDIA_ASSET_NOT_FOUND", `no media asset '${id}'`);
@@ -209,7 +192,6 @@ export function mediaLibrary(driver, d, storage, policies, now = Date.now) {
         },
     };
 }
-/** The 0.2 Admin library item's convenience fields, without changing the storage DTO. */
 export function mediaItem(asset) {
     const primary = asset.variants.find(v => v.role === "primary") ?? asset.variants[0];
     return { id: asset.id, variants: asset.variants, primaryUrl: primary?.publicUrl ?? null, mime: primary?.mimeType ?? null, byteSize: primary?.byteSize ?? null, alt: asset.alt ?? null, caption: asset.caption ?? null, createdAt: asset.createdAt };

package/dist/kernel/paging.js

@@ -1,7 +1,6 @@
-import { modeOf } from "./caller-identity.js";
+import { modeOf } from "./caller-mode.js";
 import { binds } from "./binds.js";
 import { invalid } from "./surface.js";
-/** Shared keyset wire format; a selected View binds its cursor to its operation. */
 export const encodeCursor = (value, id, operation) => encodeURIComponent(JSON.stringify(operation === undefined ? [value, id] : [value, id, operation]));
 export function decodeCursor(cursor, path = "", operation) {
     try {
@@ -12,7 +11,6 @@ export function decodeCursor(cursor, path = "", operation) {
     catch { }
     invalid("Malformed or foreign cursor.", path);
 }
-/** Selected boundaries may accept a NULL key; their generated kind guard validates it before native I/O. */
 export function decodeNullableCursor(cursor, path, operation) {
     try {
         const c = JSON.parse(decodeURIComponent(cursor));
@@ -23,7 +21,6 @@ export function decodeNullableCursor(cursor, path, operation) {
     invalid("Malformed or foreign cursor.", path);
 }
 export const MAX_PAGE_SIZE = 500;
-/** Transport and native entry bounds share one check; Views retain their declared cap. */
 export function checkPageLimit(limit, path) {
     if (!Number.isSafeInteger(limit) || Number(limit) < 1 || Number(limit) > MAX_PAGE_SIZE)
         invalid("limit is 1 to 500.", path);
@@ -41,10 +38,6 @@ export function validCursor(kind, sqlite, key) {
         default: return typeof key === "string";
     }
 }
-/**
- * A View's paged boundary: `options.limit` defaults to min(50, cap) and is capped at cap and 500. Generated modules
- * call it from their exported function, so importing a View runs no kernel code.
- */
 export async function page(spec, db, caller, input, options = {}) {
     const { path, cap } = spec;
     spec.auth?.(caller);
@@ -62,7 +55,6 @@ export async function page(spec, db, caller, input, options = {}) {
                 throw 0;
             if (spec.keys === 1 && encoded[0] !== encoded[1])
                 throw 0;
-            // Preserve the existing [id,id,operation] single-key and [value,id,operation] two-key formats.
             keys = spec.keys === 1 ? [encoded[1]] : encoded.slice(0, -1);
             for (const [i, kind] of spec.cursor.entries()) {
                 if (!validCursor(kind, spec.sqlite, keys[i]))

package/dist/kernel/publishing.js

@@ -1,6 +1,5 @@
-/** A generated publishing transition, admin or system only; `write` claims translation state, released on CONFLICT. */
-import { isAdmin, deny } from "./contracts.js";
-import { checkFresh } from "./caller-identity.js";
+import { isAdmin, deny, ROW_CONFLICT } from "./contracts.js";
+import { checkFresh } from "./caller-mode.js";
 import { bound } from "./binds.js";
 export async function transition(db, caller, input, path, steps, failure, d, execute, write) {
     checkFresh(caller, false, path);
@@ -9,7 +8,7 @@ export async function transition(db, caller, input, path, steps, failure, d, exe
     return { results: await execute(db, bound(d, steps, caller, input), path).catch(error => {
             if (release && error?.code === "CONFLICT")
                 release();
-            if (error?.code === "CONFLICT" && error.message === "Expected one affected row.")
+            if (error?.code === "CONFLICT" && error.message === ROW_CONFLICT)
                 error.message = failure;
             throw error;
         }) };

package/dist/kernel/r2-media.js

@@ -1,4 +1,3 @@
-/** Native R2 binding plus an app-owned SigV4 signer. No SDK dependency. */
 import { ContractError } from "./contracts.js";
 import { mediaError } from "./media.js";
 const EXT = { "image/png": "png", "image/jpeg": "jpg", "image/webp": "webp", "image/avif": "avif", "image/gif": "gif" };
@@ -16,7 +15,6 @@ export function r2MediaStorage({ bucket, signer, endpoint, publicBase }) {
             const ttl = Math.max(60, Math.floor((expiresAt - now) / 1000));
             return {
                 capabilities: await Promise.all(variants.map(async (v) => {
-                    // server-made keys, one directory per asset so its variants list together
                     const storageKey = `${UPLOADS}${purpose}/${uploadGroupId}/${v.role}.${ext(v.mimeType)}`;
                     const target = new URL(`${s3}/${storageKey}`);
                     target.searchParams.set("X-Amz-Expires", String(ttl));
@@ -26,7 +24,6 @@ export function r2MediaStorage({ bucket, signer, endpoint, publicBase }) {
             };
         },
         async commitUpload({ uploadGroupId, filename, variants, alt, caption, now }) {
-            // every variant is checked before any is published, so a rejected group publishes nothing
             const heads = await Promise.all(variants.map(spec => bucket.head(spec.storageKey)));
             for (const [i, spec] of variants.entries()) {
                 const o = heads[i];
@@ -38,19 +35,16 @@ export function r2MediaStorage({ bucket, signer, endpoint, publicBase }) {
                 if (o.size > spec.maxBytes)
                     throw fail("MEDIA_VARIANT_SIZE_EXCEEDED", `the stored ${spec.role} is ${o.size} bytes, more than ${spec.maxBytes}`);
             }
-            // Each attempt owns its public copies: a concurrent loser cannot overwrite or clean up a committed winner.
             const attempt = crypto.randomUUID();
             const out = [];
             try {
                 for (const [i, spec] of variants.entries()) {
                     const key = `committed/${uploadGroupId}/${attempt}/${spec.role}.${ext(spec.mimeType)}`;
                     const o = await bucket.get(spec.storageKey);
-                    // an upload URL may PUT again between the check and the copy: the copy must be what was checked
                     if (!o || o.size !== heads[i].size || o.httpMetadata?.contentType !== spec.mimeType) {
                         await cancel(o);
                         throw fail("MEDIA_OBJECT_NOT_FOUND", `variant ${spec.role} of '${uploadGroupId}' changed during commit`);
                     }
-                    // Remember a possibly published key before awaiting put: a failed response may still have stored it.
                     out.push({ mimeType: spec.mimeType, publicUrl: `${base}/${key}`, storageKey: key, byteSize: o.size, role: spec.role });
                     try {
                         await bucket.put(key, o.body, {
@@ -63,7 +57,6 @@ export function r2MediaStorage({ bucket, signer, endpoint, publicBase }) {
                         throw error;
                     }
                 }
-                // The use case removes upload keys only after its SQL transaction is durable.
             }
             catch (error) {
                 const cleanup = await Promise.allSettled(out.map(v => bucket.delete(v.storageKey)));