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

package/dist/kernel/contracts.js

@@ -1,20 +1,14 @@
-/** Boundary primitives only. No plan, SQL interpreter or resource ownership. */
 import { ContractError } from "./contract-error.js";
 export { ContractError } from "./contract-error.js";
 import { hasRole, isAdminCaller as isAdmin } from "./caller-identity.js";
-/** Gateway mode or the one execution prop carrying forwarded authority. */
 export const forwarded = (ctx, gateway) => !!(gateway || ctx?.props && Object.hasOwn(ctx.props, "mantle"));
-/** Privilege never follows a member role name. Only the original verified identity carries the admin layer. */
 export { isAdmin };
-/** Both authenticated layers pass ctx.user; the host layer still needs its original brand. */
 export const isUser = (caller) => caller.kind === "user" || isAdmin(caller);
 export const hasAdminRole = (caller, name) => isAdmin(caller) && hasRole(caller, name);
-/** Only the core transport failures; other codes carry their own status, and unknown codes remain server errors. */
 export const statusOf = (code) => ({ __proto__: null,
     INPUT_VALIDATION_FAILED: 400, UNAUTHENTICATED: 401, AUTH_DENIED: 403, NOT_FOUND: 404,
     METHOD_NOT_ALLOWED: 405, CONFLICT: 409, OUTCOME_UNKNOWN: 503,
 }[code] ?? 500);
-/** Redact native errors at the selected boundary; the bare query preserves their identity. */
 export function wire(error) {
     const status = error instanceof ContractError ? error.status ?? statusOf(error.code) : 500;
     if (status !== 500) {
@@ -46,52 +40,17 @@ export function wireRows(rows, fields = []) {
         return result;
     });
 }
-/** Deny unless `allowed`: a user is AUTH_DENIED, anyone else UNAUTHENTICATED. */
 export function deny(caller, allowed, path) {
     if (!allowed)
         throw new ContractError("subject" in caller ? "AUTH_DENIED" : "UNAUTHENTICATED", "Authorization predicate not satisfied.", path);
 }
-/** A row statement that changed no row cannot tell why without leaking whether the row exists, so it says how to recover. */
 export const ROW_CONFLICT = "No row matched this change: it does not exist or is not visible to you, it changed since it was read, or its state no longer allows this change. Read it again before deciding whether to retry.";
-/** CONFLICT for a write the database refused: a unique-index clash (`fields.kind` "unique"), or a row statement that did not change exactly one row ("row"). */
 export const conflict = (path, unique, cause) => new ContractError("CONFLICT", unique ? "A unique constraint of the Schema was violated." : ROW_CONFLICT, path, { cause, fields: { kind: unique ? "unique" : "row" } });
-/** A Schema `checks` violation (Mantle's SQLite check trigger, or PostgreSQL SQLSTATE 23514) is a CONFLICT naming the check. */
 export const checkConflict = (path, error) => {
     const message = error?.message ?? "", marker = /MANTLE_CHECK ([^:\n]+): (.+)/.exec(message);
     if (!/MANTLE_CHECK /.test(message))
         return undefined;
-    // D1 appends its own `: SQLITE_CONSTRAINT (extended: …)`; it stays in `cause`, not in what a client reads.
     return schemaCheckFailed(path, error, marker?.[1], marker?.[2]?.replace(/: SQLITE_CONSTRAINT.*$/, ""));
 };
-/** One message on every target, built from the parsed fields; the driver's own text stays in `cause`. */
 export const schemaCheckFailed = (path, cause, schema, check) => new ContractError("CONFLICT", schema && check ? `A check of the Schema failed: ${schema}: ${check}` : "A check of the Schema failed.", path, { cause, fields: { kind: "check", schema, check } });
-/** A cookie is ambient authority; bearer credentials deliberately supplied by the app are not. */
-export function checkOrigin(request, caller) {
-    if (!("credential" in caller) || caller.credential !== "session" || ["GET", "HEAD", "OPTIONS"].includes(request.method))
-        return;
-    const site = request.headers.get("sec-fetch-site"), origin = request.headers.get("origin");
-    if ((!site && !origin) || (site && site !== "same-origin" && site !== "none") || (origin && origin !== new URL(request.url).origin))
-        throw new ContractError("AUTH_DENIED", "Cross-origin session mutation rejected.", "request:origin");
-}
-/** A resolver's ContractError (e.g. UNAUTHENTICATED for an expired token) keeps its status; anything else is an application failure. */
-export async function surfaceCaller(request, env, resolve, readOnly = false) {
-    try {
-        return await resolve(request, env, { readOnly });
-    }
-    catch (cause) {
-        if (cause instanceof ContractError)
-            throw cause;
-        throw new Error("Caller resolution failed.", { cause });
-    }
-}
-/** The client sees the redacted wire form; the log gets the surface (a route or tool, never headers) and the original message, stack and cause. */
-export function surfaceError(error, where = "surface") {
-    const result = wire(error);
-    if (result.status === 500)
-        console.error(`[mantle ${where}] unhandled failure`, error);
-    return result;
-}
-export function surfaceFailure(error, challenge, where) {
-    const result = surfaceError(error, where);
-    return Response.json({ error: result.error }, { status: result.status, headers: { "cache-control": "private, no-store", ...(challenge && [401, 403].includes(result.status) && result.error.path !== "request:origin" ? { "www-authenticate": challenge } : {}) } });
-}
+export { checkOrigin, surfaceCaller, surfaceError, surfaceFailure } from "./surface-failure.js";

package/dist/kernel/cron.js

@@ -1,8 +1,6 @@
-/** SDK-owned POSIX to Cloudflare cron conversion, copied verbatim from Core's CloudflareCron so Workers don't pull Core's D1 driver; Core is retired with 0.2.0, so this copy becomes the only one. */
 const PART = /^(\*|\d+|[A-Za-z]{3})(?:-(\d+|[A-Za-z]{3}))?(?:\/(\d+))?$/;
 const MONTHS = ["JAN", "FEB", "MAR", "APR", "MAY", "JUN", "JUL", "AUG", "SEP", "OCT", "NOV", "DEC"];
 const DAYS = ["SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT"];
-/** label, lowest, highest, names (by value from `lowest`) */
 const FIELDS = [["minute", 0, 59, null], ["hour", 0, 23, null], ["day of month", 1, 31, null], ["month", 1, 12, MONTHS], ["weekday", 0, 6, DAYS]];
 export function toCloudflareCron(cron) {
     const refuse = (why) => {
@@ -14,7 +12,6 @@ export function toCloudflareCron(cron) {
     const weekday = [];
     fields.forEach((field, i) => {
         const [label, min, max, names] = FIELDS[i];
-        // a value as a number: a name counts as its number, and a number must be written plainly (`01` and `1` are one value)
         const value = (token) => {
             if (/^\d+$/.test(token)) {
                 if (token.length > 1 && token.startsWith("0"))
@@ -51,7 +48,6 @@ export function toCloudflareCron(cron) {
         if (i === 4)
             weekday.push(...out);
     });
-    // POSIX runs on either day when both are restricted; Cloudflare does not document that rule, so only one may be
     if (fields[2] !== "*" && fields[4] !== "*")
         refuse("restrict the day of month or the weekday, not both");
     return [...fields.slice(0, 4), weekday.join(",")].join(" ");

package/dist/kernel/dialect/common.js

@@ -1,6 +1,3 @@
-/** What SQLite and PostgreSQL spell identically, defined once; each dialect module re-exports it. */
-/** A (possibly schema-qualified) name, quoted. */
 export const ident = (name) => name.split(".").map(part => `"${part.replaceAll('"', '""')}"`).join(".");
-/** A literal piece of text for a LIKE pattern: `\`, `%` and `_` match themselves. Pair with `likeEscape`. */
 export const escapeLike = (value) => value.replace(/[\\%_]/g, "\\$&");
 export const likeEscape = " ESCAPE '\\'";

package/dist/kernel/dialect/postgres.js

@@ -1,4 +1,3 @@
-/** PostgreSQL: `$n` placeholders, time as timestamptz (ISO text keeps every microsecond). */
 import { isoDate, isoTimestamptz } from "../scalars.js";
 import { searchLike } from "../search.js";
 import { escapeLike, ident, likeEscape } from "./common.js";
@@ -13,6 +12,5 @@ export const cutoff = (ms, seconds) => new Date(ms - seconds * 1000);
 export const timestamp = isoTimestamptz;
 export const date = isoDate;
 export const cast = (placeholder, type) => type === "timestamptz" || type === "date" ? `CAST(CAST(${placeholder} AS text) AS ${type})` : type === "json" ? `CAST(CAST(${placeholder} AS text) AS jsonb)` : placeholder;
-// ponytail: preserve Core's ILIKE scan; add pg_trgm only when measured search latency needs it.
 export const search = (_table, fields, alias, query) => searchLike(fields.map(field => `${alias}.${ident(field)}`), query, "ILIKE");
 export const dialect = { param, ident, escapeLike, likeEscape, like, search, wireTimestamp, wireDate, now, cutoff, timestamp, date, cast, anyOf };

package/dist/kernel/dialect/sqlite.js

@@ -1,24 +1,19 @@
 import { ContractError } from "../contracts.js";
-/** SQLite and Cloudflare D1: `?n` placeholders, time as microseconds and dates as days since the epoch. */
 import { encodeDate, encodeTimestamptz } from "../scalars.js";
 import { searchLike } from "../search.js";
 import { escapeLike, ident, likeEscape } from "./common.js";
 export { ident, escapeLike, likeEscape };
 export const param = (n) => `?${n}`;
 export const anyOf = (column, placeholder) => `${column} IN (SELECT value FROM json_each(${placeholder}))`;
-export const like = () => "LIKE"; // SQLite's LIKE already ignores ASCII case
-/** A write that broke a UNIQUE index or the id's UNIQUE (bun:sqlite and D1 word it the same). */
+export const like = () => "LIKE";
 export const unique = (error) => /UNIQUE constraint failed/.test(String(error?.message));
-/** Positive rollback evidence only. Plain/network/I/O errors are deliberately uncertain. */
 export function definitive(error) {
     if (error instanceof ContractError)
         return error.code === "CONFLICT";
     const e = error;
-    // Bun before 1.4 omits `code` on statement errors; its SQLiteError still carries the native errno.
     const native = typeof e?.code === "string" ? e.code.startsWith("SQLITE_") : e?.name === "SQLiteError";
     return native && typeof e.errno === "number" && [1, 19, 20, 25].includes(e.errno & 255);
 }
-// floor, not SQLite's truncating `/` and `%`: a time before 1970 is a negative number of microseconds
 export const wireTimestamp = (v) => ["strftime('%Y-%m-%dT%H:%M:%S', ((", v, ") - ((", v, ") % 1000000 + 1000000) % 1000000) / 1000000, 'unixepoch') || '.' || substr('00000' || (((", v, ") % 1000000 + 1000000) % 1000000), -6) || 'Z'"];
 export const wireDate = (v) => ["date((", v, ") * 86400, 'unixepoch')"];
 export const now = (ms) => ms * 1000;

package/dist/kernel/drain.js

@@ -1,25 +1,19 @@
-/** Request-time only: no Worker startup path imports this. */
-/** Read and discard what is left of a request body, at most 1 MiB and 1 s. A response sent over an unread POST body makes local
- *  `wrangler dev` break the connection, and the next request fails with "Network connection lost". */
 async function drain(request) {
     let reader;
     const timer = setTimeout(() => reader?.cancel().catch(() => { }), 1000);
     try {
-        reader = request.body?.getReader(); // a body the app consumed is done; one it still holds is locked and throws
+        reader = request.body?.getReader();
         for (let read = 0, chunk; reader && !(chunk = await reader.read()).done;)
             if ((read += chunk.value.byteLength) > 1024 * 1024) {
                 await reader.cancel();
                 return;
             }
     }
-    catch { /* the client went away */ }
+    catch {  }
     finally {
         clearTimeout(timer);
     }
 }
-/** A request handler that drains the body once it has answered or thrown. `undefined` and `null` mean the request is not this
- *  handler's, so the next handler can still read it. A handler that answers and reads the request later (in `waitUntil`) must
- *  read or lock the body before answering. */
 export const draining = (handle) => async (...args) => {
     let response;
     try {

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

@@ -7,31 +7,19 @@ 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; };
 const check = (path, e) => schemaCheckFailed(path, e, e.table ?? e.table_name, e.constraint ?? e.constraint_name);
-/** A structured server ErrorResponse proves rollback; missing evidence is uncertain. */
 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 = [];
@@ -55,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,7 +29,6 @@ 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, !!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");
@@ -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.js

@@ -1,22 +1,18 @@
 import { linkApps, linkSurface, resourcesOf } from "./mcp-apps.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;
-    // 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 {
@@ -35,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;