@aotter/mantle 0.2.0-alpha.9 → 0.2.1-alpha.1

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,9 @@ 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 MCP_INPUT_ELEMENTS = 10_000;
 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 +32,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 +43,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 +111,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 +166,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 +182,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 +206,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 } : {});
+                const server = new McpServer(serverInfo, { maxToolInputElements: MCP_INPUT_ELEMENTS, ...(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 +224,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 +239,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 +280,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 +299,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 +322,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;

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

package/dist/kernel/rest-dispatch.js

@@ -1,4 +1,3 @@
-/** View/Procedure dispatch loads only on a matched REST request, after caller resolution. */
 import { authorizeTarget } from "./authorization.js";
 import { convert, invalid } from "./surface.js";
 import { body } from "./rest.js";

package/dist/kernel/rest-router.js

@@ -1,10 +1,10 @@
-/** Route matching and caller enforcement load on the first request. */
-import { forwarded, ContractError, checkOrigin, surfaceCaller } from "./contracts.js";
+import { forwarded, ContractError } from "./contracts.js";
+import { checkOrigin, surfaceCaller } from "./surface-failure.js";
 import { decode, invalid } from "./surface.js";
 import { draining } from "./drain.js";
+import { canonicalPath } from "./route-pattern.js";
 const isApi = (path) => path === "/api" || path.startsWith("/api/");
 const fail = message => invalid(message, "rest");
-/** Shared matching/auth/error envelope; selected dispatch is supplied by the surface. */
 export function router(routes, options, send) {
     return draining(async (request, env, ctx) => {
         let caller;
@@ -15,11 +15,8 @@ export function router(routes, options, send) {
             if (isForwarded)
                 caller = (await import("./host-caller.js")).gatewayCaller(ctx, options.gateway, options.fields);
             const original = new URL(request.url).pathname;
-            let path;
-            try {
-                path = original.split("/").map(segment => encodeURIComponent(decodeURIComponent(segment))).join("/");
-            }
-            catch {
+            const path = canonicalPath(original);
+            if (path === undefined) {
                 if (!isApi(original))
                     return undefined;
                 fail("Malformed request path.");

package/dist/kernel/rest.d.ts

@@ -1,6 +1,8 @@
 /** REST request handling for a generated route table: matching, body and parameter decoding, dispatch and errors. */
 import type { Caller, Target, Authorize, Gateway, RequestContext, GatewayOptions } from "./contracts.js";
 import { type Conversions } from "./surface.js";
+/** The routers' path grammar, for Admin's router: its mount, route patterns and the canonical request path. */
+export { ADMIN_API_BASE, canonicalPath, routeSource } from "./route-pattern.js";
 type Paging = {
     limit?: number;
     cursor?: string;
@@ -55,4 +57,3 @@ export declare function rest<Env, Database, Handlers = never>(routes: readonly R
 export declare function nativeRest<Env, Database, Handlers = never>(routes: readonly Route<Database, Handlers, Env>[], options: Options<Env, Database> & {
     handlers?: Handlers;
 }): (request: Request, env: Env, ctx?: RequestContext) => Promise<Response | undefined>;
-export {};

package/dist/kernel/rest.js

@@ -1,5 +1,6 @@
 import { ContractError } from "./contract-error.js";
 import { invalid } from "./surface.js";
+export { ADMIN_API_BASE, canonicalPath, routeSource } from "./route-pattern.js";
 const headers = { "cache-control": "private, no-store" };
 const fail = message => invalid(message, "rest");
 export async function body(request, limit = 1_000_000) {
@@ -7,7 +8,6 @@ export async function body(request, limit = 1_000_000) {
         fail(`Request body exceeds ${limit} bytes.`);
     return (await import("./json-body.js")).body(request, limit, fail);
 }
-/** Shared matching/auth/error envelope; selected dispatch is supplied by the surface. */
 function router(routes, options, send) {
     let handle;
     return async (request, env, ctx) => {
@@ -15,14 +15,12 @@ function router(routes, options, send) {
         return handle(request, env, ctx);
     };
 }
-/** Generated REST routes retain the native View/Procedure dispatch. */
 export function rest(routes, options) {
     return router(routes, options, async (route, request, env, caller, params, access) => {
         const { dispatch } = await import("./rest-dispatch.js");
         return dispatch(route, request, () => options.db(env), caller, params, options, access);
     });
 }
-/** A selected surface's raw/JSON handlers; its branches are absent from ordinary REST bundles. */
 export function nativeRest(routes, options) {
     return router(routes, options, async (route, request, env, caller, params, access) => {
         if (Number(request.headers.get("content-length")) > (route.bodyLimit ?? 1_000_000))

package/dist/kernel/route-pattern.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The one path grammar of the generated REST router, the Admin router and describe's `matchTarget`: a route template's
+ * pattern, the request path it is tested against and REST precedence. Pure; no database, application or other module.
+ */
+/** Where Admin serves its API. Admin route templates and `admin:` describe ids are relative to it. */
+export declare const ADMIN_API_BASE = "/admin/api";
+/**
+ * An http Trigger path as a describe template: `{name}` becomes `:name`. The compiler refuses other braces and
+ * `:`-prefixed segments in these paths, so `routePath` inverts it exactly.
+ */
+export declare const pathTemplate: (path: string) => string;
+/** A describe template as the route path the routers compile: `:name` segments become `{name}`. */
+export declare const routePath: (template: string) => string;
+/**
+ * A template's anchored pattern source and capture keys. A `{name}` segment captures one segment; with `suffix`,
+ * `{name*}` captures the rest of the path. Other segments, `:name` included, match literally in encoded form. One
+ * trailing slash is optional.
+ */
+export declare function routeSource(template: string, base?: string, suffix?: boolean): {
+    source: string;
+    keys: string[];
+};
+/** The path the routers test: each segment decoded and re-encoded, so equivalent escapes match alike. Malformed escapes are undefined. */
+export declare function canonicalPath(pathname: string): string | undefined;
+/** REST precedence over route paths: fewer parameters, then a literal before a parameter from the left, then the path. */
+export declare function routeOrder(a: string, b: string): number;

package/dist/kernel/route-pattern.js

@@ -0,0 +1,34 @@
+export const ADMIN_API_BASE = "/admin/api";
+export const pathTemplate = (path) => path.replace(/\{([^}]+)\}/g, ":$1");
+export const routePath = (template) => template.split("/").map(segment => segment.startsWith(":") ? `{${segment.slice(1)}}` : segment).join("/");
+export function routeSource(template, base = "", suffix = false) {
+    const keys = [];
+    const path = template.split("/").map(segment => {
+        const rest = suffix ? /^\{([a-zA-Z]\w*)\*\}$/.exec(segment) : null, one = /^\{([^}]+)\}$/.exec(segment);
+        if (rest || one) {
+            keys.push((rest ?? one)[1]);
+            return rest ? "(.*)" : "([^/]+)";
+        }
+        return encodeURIComponent(segment).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    }).join("/");
+    return { source: `^${base}${path}/?$`, keys };
+}
+export function canonicalPath(pathname) {
+    try {
+        return pathname.split("/").map(segment => encodeURIComponent(decodeURIComponent(segment))).join("/");
+    }
+    catch {
+        return undefined;
+    }
+}
+const isParameter = (segment) => /^\{[^}]+\}$/.test(segment);
+export function routeOrder(a, b) {
+    const x = a.split("/"), y = b.split("/");
+    const count = (segments) => segments.filter(isParameter).length;
+    if (count(x) !== count(y))
+        return count(x) - count(y);
+    for (let i = 0; i < Math.min(x.length, y.length); i++)
+        if (isParameter(x[i]) !== isParameter(y[i]))
+            return isParameter(x[i]) ? 1 : -1;
+    return a < b ? -1 : a > b ? 1 : 0;
+}