@aotter/mantle 0.2.0-alpha.9 → 0.2.0

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;

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,9 @@
-/** 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";
 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;

package/dist/kernel/rest.js

@@ -7,7 +7,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 +14,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/scalars.js

@@ -1,8 +1,3 @@
-/**
- * Declared date-time and date inputs are ISO on every target (the handbook's wire form). A timestamp needs an explicit
- * Z or offset; a day that does not exist (2026-02-30) is refused rather than rolled over. SQLite stores microseconds
- * and days; PostgreSQL receives the canonical text, so it keeps every microsecond.
- */
 import { ContractError } from "./contracts.js";
 export function encodeTimestamptz(v) {
     if (v instanceof Date) {
@@ -11,7 +6,6 @@ export function encodeTimestamptz(v) {
             throw new ContractError("SQL_TYPE", "Invalid Date is not a timestamp");
         return micros;
     }
-    // hours 00-23: Date.parse would roll T24:00 over to the next day
     const m = /^(\d{4}-\d\d-\d\d)[T ]((?:[01]\d|2[0-3]):\d\d(?::\d\d)?)(?:\.(\d{1,6}))?(Z|[+-]\d\d(?::?\d\d)?)$/.exec(v.trim());
     if (!m)
         throw new ContractError("SQL_TYPE", `'${v}' is not a timestamp with an explicit offset`);
@@ -24,14 +18,13 @@ export function encodeTimestamptz(v) {
         throw new ContractError("SQL_TYPE", `'${v}' is not a valid timestamp`);
     return micros;
 }
-/** A date is the string a calendar shows; a Date instant has no single calendar day, so it is not accepted. */
 export function encodeDate(v) {
     const m = /^(\d{4})-(\d\d)-(\d\d)$/.exec(v);
     if (!m)
         throw new ContractError("SQL_TYPE", `'${v}' is not a date`);
     const [, y, mo, d] = m;
     const dt = new Date(0);
-    dt.setUTCFullYear(+y, +mo - 1, +d); // Date.UTC would read years 0 to 99 as 1900 to 1999
+    dt.setUTCFullYear(+y, +mo - 1, +d);
     if (dt.getUTCDate() !== +d || dt.getUTCMonth() !== +mo - 1)
         throw new ContractError("SQL_TYPE", `'${v}' is not a valid date`);
     return dt.getTime() / 86_400_000;
@@ -40,5 +33,4 @@ export function isoTimestamptz(v) {
     const us = encodeTimestamptz(v), ms = Math.floor(us / 1000);
     return new Date(ms).toISOString().replace("Z", String(us - ms * 1000).padStart(3, "0") + "Z");
 }
-/** The input itself: the pattern admits only the canonical form, and a day that does not exist was refused. */
 export const isoDate = (v) => (encodeDate(v), v);

package/dist/kernel/search.js

@@ -1,4 +1,3 @@
-/** Native substring predicates matching Core's mantle.search lowering. Values remain bound. */
 export function searchLike(columns, query, operator) {
     const pattern = `'%' || replace(replace(replace(${query}, '!', '!!'), '%', '!%'), '_', '!_') || '%'`;
     return columns.map(column => `${column} ${operator} ${pattern} ESCAPE '!'`).join(' OR ');

package/dist/kernel/site.js

@@ -1,4 +1,3 @@
-/** Optional site capability. Construction does no database work; deployment facts come from generated constants. */
 import { isAdmin, deny } from "./contracts.js";
 import { invalid } from "./surface.js";
 import { mediaLibrary } from "./media.js";
@@ -23,7 +22,6 @@ export function createSite(db, d, caller, defaults, policies) {
             return read();
         }, media(storage) { admin(); return mediaLibrary(db, d, storage, policies); } };
 }
-/** 0.2 /admin/api/site projection; the app supplies its selected capabilities. */
 export function siteInfo(config, options) {
     const { origin, ...stored } = config;
     const publicUrl = URL.canParse(origin) ? origin : options.origin;

package/dist/kernel/store.d.ts

@@ -44,6 +44,14 @@ export interface Fact {
     readonly d?: readonly string[];
     /** Declared searchable text fields; omitted collections search id only. */
     readonly search?: readonly string[];
+    /** `x-mantle-ref` columns to a scoped Schema (Core's `refChecks`): a caller's write names a row it sees, in the child's partition. */
+    readonly ref?: readonly {
+        readonly column: string;
+        readonly table: string;
+        readonly field: string;
+        readonly same: readonly (readonly [parent: string, child: string])[];
+        readonly terms: readonly Term[];
+    }[];
     /** Generated parent policy and inherited read-only columns; no authored schema is interpreted. */
     readonly parent?: {
         readonly on: string;
@@ -130,8 +138,10 @@ export interface Collection<T extends Table> {
         readonly lock: number | string;
     }): Write<void>;
 }
-/** Lazy, single-execution write: await directly or submit once to its Store's batch. */
+/** Lazy, single-execution write: await it (or `.then`/`.catch`/`.finally`, which run it) or submit it once to its Store's batch. */
 export interface Write<T> extends PromiseLike<T> {
+    catch<R = never>(onrejected?: ((reason: any) => R | PromiseLike<R>) | null): Promise<T | R>;
+    finally(onfinally?: (() => void) | null): Promise<T>;
 }
 export interface TransactionOptions {
     readonly isolation?: "serializable" | "repeatable read" | "read committed" | "read uncommitted";