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

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, ROW_CONFLICT } from "./contracts.js";
-import { checkFresh } from "./caller-identity.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);

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.js

@@ -1,19 +1,12 @@
 import { scoped } from "./user-fields.js";
-import { modeOf, checkFresh } from "./caller-identity.js";
-/**
- * Generic Store over Core's rowPolicy/writePolicy rules and per-Schema Facts (scope, TTL, publishing, dates).
- * Generated types own storage column names, values, filters and writable columns; the dialect quotes names and binds values.
- * Runtime refuses unsafe limits, system/scope writes, undefined values. It applies row rules, not requires.
- */
+import { modeOf, checkFresh } from "./caller-mode.js";
 import { binds as evaluate, encode } from "./binds.js";
 import { ContractError } from "./contracts.js";
 import { condition } from "./where.js";
 import { decodeCursor, encodeCursor } from "./paging.js";
 export { decodeCursor, encodeCursor };
 export const SCOPE = "$scope", TTL = "$ttl";
-/** The columns Mantle owns: no write names them (nor the scope column), and `_rid` is never returned. */
 const SYSTEM = ["id", "version", "created_at", "updated_at", "author_id", "status", "published_at", "_rid"];
-/** A Schema's rules: the shared ones with its scope and TTL put in, and a term dropped where it has none. The generator proves this equals Core's for every Schema. */
 export function expand(r, f) {
     const all = (l) => l.flatMap(([c, ...t]) => (c = c === SCOPE ? f.s : c === TTL ? f.ttl?.[0] : c === "status" && !f.pub ? "" : c) ? [[c, ...t.map(v => v.k === "cutoff" ? { ...v, seconds: f.ttl[1] } : v)]] : []);
     return { caller: [...all(r.caller), ...(f.parent ? [f.parent.visible] : []), ...(f.u ?? [])], trusted: all(r.trusted), fills: all(r.fills), sets: all(r.sets), lock: r.lock };
@@ -23,7 +16,6 @@ export function renderTerm(d, t, prefix, placeholder) {
     const param = (r) => typeof placeholder === "string" ? placeholder : placeholder(r);
     if (t[1] === 'in') {
         const kept = d.anyOf(prefix + d.ident(t[0]), param(t[2]), t[2].type);
-        // The same two forms the SQL compiler prints for a Schema scope term (see `scoped`); one parameter either way.
         return t[2].scope ? `(/*s:${t[2].field}*/${kept}/*|*/(${kept} OR 1 = 1)/*;*/)` : kept;
     }
     if (t[1] === "parent") {
@@ -41,10 +33,6 @@ export function renderTerm(d, t, prefix, placeholder) {
     return op === "ttl" ? `(${c} IS NULL OR ${c} > ${bound})` : `${c} = ${bound}`;
 }
 const transactionStores = new WeakSet();
-/**
- * A ref handler's `ctx.transaction` on drivers with interactive transactions: it opens one on the handler's Store, or
- * joins the one that Store already runs in (a handler called through `tx.procedures`), so the handler need not know.
- */
 export function handlerTransaction(store, db) {
     const open = store.transaction;
     return (fn) => transactionStores.has(store) ? fn({ store, db }) : open((tx, txDb) => fn({ store: tx, db: txDb }));
@@ -59,10 +47,8 @@ export function createStore(d, drv, rules, facts, operations) {
         }
         return p;
     };
-    /** The columns whose wire form the database formats, replacing the same names `*` brings (of two same-named columns a driver keeps the last). */
     const wires = (p, prefix) => [p.ts, p.d].flatMap((columns, i) => columns.map(c => `${(i ? d.wireDate : d.wireTimestamp)(prefix + d.ident(c)).join("")} AS ${d.ident(c)}`)).join(", ");
     const ID = d.ident("id");
-    /** The row rules of one mode, numbered from 1; the SQL is rendered once per mode. */
     const policy = (p, trusted, terms) => {
         const parentTerms = p.f.parent ? trusted ? p.f.parent.trusted : p.f.parent.caller : [];
         const cached = p.policy.get(trusted);
@@ -129,7 +115,6 @@ export function createStore(d, drv, rules, facts, operations) {
     }
     function collection(db, caller, p, write) {
         const trusted = modeOf(caller) === "trusted", { f, x } = p, terms = trusted ? x.trusted : x.caller, pol = policy(p, trusted, terms), no = (message) => new ContractError("INPUT_VALIDATION_FAILED", `${p.name}: ${message}`);
-        /** A value as the engine stores it, as a placeholder. Date-times and dates are known from the fact; a JSON object is told by its JS type (a boolean binds as it is on every driver). */
         const put = (values, column, v) => {
             const type = p.ts.includes(column) ? "timestamptz" : p.d.includes(column) ? "date" : v !== null && typeof v === "object" && !(v instanceof Date) ? "json" : "";
             values.push(type === "json" ? JSON.stringify(v) : encode(d, type, v));
@@ -147,7 +132,6 @@ export function createStore(d, drv, rules, facts, operations) {
             return out;
         };
         const rows = (sql, values) => drv.read(db, scoped(sql, caller), values);
-        /** Core never reads back the scope column, and `_rid` is storage's. */
         const clean = (list) => { for (const r of list) {
             delete r._rid;
             if (f.s)
@@ -182,26 +166,21 @@ export function createStore(d, drv, rules, facts, operations) {
                     conds.push(`(${kc} ${up ? ">" : "<"} ${m} OR (${kc} = ${m} AND ${after}) OR ${kc} IS NULL)`);
                 }
             }
-            // an ORDER BY column is NOT NULL (the generated type offers no other), so no NULL placement
             const list = await rows(`${select()}${where(conds)} ORDER BY ${name === "id" ? "" : `${kc} ${way} NULLS LAST, `}${id} ${way} LIMIT ${limit + 1}`, values);
             if (list.length <= limit)
                 return { rows: clean(list), cursor: null };
             const page = list.slice(0, limit), end = page[limit - 1];
             return { rows: clean(page), cursor: encodeCursor(end[name], end.id) };
         }
-        /** A write: placeholders are numbered as values are pushed; a Core bind recipe is evaluated against this caller and clock. */
         const writer = (lock) => {
             const values = [], ms = Date.now(), into = d.ident(p.name);
             const push = (v) => (values.push(v), d.param(values.length));
             const recipe = (r) => push(evaluate(d, [r], caller, { version: lock }, ms)[0]);
-            /** The marks of the non-null columns written, by folded name. */
             const marks = new Map();
             const given = (set, insert = false) => Object.entries(set).map(([name, v]) => {
-                // SQLite matches column names without case, so compare folded
                 const key = name.toLowerCase();
                 if (SYSTEM.includes(key) || key === p.scope || !insert && !!f.u?.some(u => u[0] === key))
                     throw no(`${name} is not writable`);
-                // a driver binds undefined as NULL: an update would silently clear the column
                 if (v === undefined)
                     throw no(`${name} is undefined`);
                 const mark = put(values, name, v);
@@ -209,9 +188,7 @@ export function createStore(d, drv, rules, facts, operations) {
                     marks.set(key, mark);
                 return [d.ident(name), mark];
             });
-            /** For each non-null reference written, the referenced row as the caller sees it, in the child's partition (`child`). */
             const refs = (child) => trusted ? [] : (f.ref ?? []).flatMap(r => { const v = marks.get(r.column); return v ? [`EXISTS (SELECT 1 FROM ${d.ident(r.table)} _mantle_ref WHERE ${[`_mantle_ref.${d.ident(r.field)} = ${v}`, ...r.same.map(([parent, column]) => `_mantle_ref.${d.ident(parent)} = ${child(column) ?? "NULL"}`), ...r.terms.map(t => renderTerm(d, t, "_mantle_ref.", recipe))].join(" AND ")})`] : []; });
-            /** `WHERE id = ? AND <the caller's row rules> AND version = ?` */
             const guard = (id, also = []) => ` WHERE ${[`${ID} = ${push(id)}`, ...[...pol.terms, x.lock].map(t => renderTerm(d, t, t[1] === "parent" ? d.ident(p.name) + "." : "", recipe)), ...also].join(" AND ")}`;
             const step = (sql) => ({ sql: scoped(sql, caller), binds: values, row: true });
             return { given, marks, recipe, refs, guard, step, into, returning: () => ` RETURNING *, ${p.returning ??= wires(p, "")}` };
@@ -243,7 +220,6 @@ export function createStore(d, drv, rules, facts, operations) {
                         names.push(d.ident(column));
                         marks.push(v === "newId" ? rules.newId : w.recipe(v));
                     }
-                    // a reference to a scoped Schema: the row is inserted only if the parent check holds, else `row` fails with CONFLICT
                     const refs = w.refs(column => w.marks.get(column));
                     return w.step(`INSERT INTO ${w.into} (${names.join(", ")}) ${refs.length ? `SELECT ${marks.join(", ")} WHERE ${refs.join(" AND ")}` : `VALUES (${marks.join(", ")})`}${w.returning()}`);
                 }, rows => clean(rows)[0], `${p.name}/insert`);
@@ -253,7 +229,6 @@ export function createStore(d, drv, rules, facts, operations) {
                     const w = writer(lock), assigns = w.given(set).map(([name, mark]) => `${name} = ${mark}`);
                     for (const [column, v] of x.sets)
                         assigns.push(`${d.ident(column)} = ${v === "bump" ? `${d.ident(column)} + 1` : w.recipe(v)}`);
-                    // the partition is never SET, so the child's is the row's own
                     const refs = w.refs(column => `${w.into}.${d.ident(column)}`);
                     return w.step(`UPDATE ${w.into} SET ${assigns.join(", ")}${w.guard(id, refs)}${w.returning()}`);
                 }, rows => clean(rows)[0], `${p.name}/update`);

package/dist/kernel/surface-failure.d.ts

@@ -0,0 +1,10 @@
+import { wire, type Caller } from "./contracts.js";
+/** A cookie is ambient authority; bearer credentials deliberately supplied by the app are not. */
+export declare function checkOrigin(request: Request, caller: Caller): void;
+/** A resolver's ContractError (e.g. UNAUTHENTICATED for an expired token) keeps its status; anything else is an application failure. */
+export declare function surfaceCaller<Env>(request: Request, env: Env, resolve: (request: Request, env: Env, authority: {
+    readonly readOnly: boolean;
+}) => Caller | Promise<Caller>, readOnly?: boolean): Promise<Caller>;
+/** 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 declare function surfaceError(error: unknown, where?: string): ReturnType<typeof wire>;
+export declare function surfaceFailure(error: unknown, challenge?: string, where?: string): Response;

package/dist/kernel/surface-failure.js

@@ -0,0 +1,29 @@
+import { ContractError } from "./contract-error.js";
+import { wire } from "./contracts.js";
+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");
+}
+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 });
+    }
+}
+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 } : {}) } });
+}

package/dist/kernel/surface.js

@@ -1,6 +1,4 @@
-/** Shared request-time core of the generated surfaces: input failures and declared bind conversion. */
 import { ContractError } from "./contracts.js";
-/** INPUT_VALIDATION_FAILED at `path`. */
 export function invalid(message, path) { throw new ContractError("INPUT_VALIDATION_FAILED", message, path); }
 export function convert(input, fields = []) {
     for (const [key, type] of fields) {
@@ -8,7 +6,6 @@ export function convert(input, fields = []) {
         input[key] = value == null ? null : type === "json" ? JSON.stringify(value) : type === "bool" ? Number(value) : value;
     }
 }
-/** Path decoding for a matched template; a malformed escape is an input failure at `path`. */
 export function decode(keys, match, message, path) {
     try {
         return Object.fromEntries(keys.map((key, index) => [key, decodeURIComponent(match[index + 1])]));

package/dist/kernel/sweep.js

@@ -1,4 +1,3 @@
-/** Host-only TTL maintenance; the selected candidates and delete share one native transaction. */
 import { ContractError } from "./contracts.js";
 import { binds } from "./binds.js";
 export async function sweep(db, caller, input, path, seconds, sql, d, execute) {

package/dist/kernel/translations.js

@@ -1,4 +1,3 @@
-/** Locale values stay ordinary strings; applications opt into canonicalisation. */
 import { invalid } from "./surface.js";
 export function toCanonicalLocale(value) {
     if (typeof value !== "string" || !value)

package/dist/kernel/user-caller.js

@@ -1,9 +1,7 @@
-/** Validation runs when an identity is built, outside ordinary query startup. */
 import { ContractError } from "./contract-error.js";
 import { validUserFieldName } from "./user-field-name.js";
 import { identities } from "./caller-identity.js";
 export const isAllValues = (value) => !!value && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length === 1 && value.all === true;
-/** Role names follow Better Auth's role strings; `-` is allowed. */
 export const roleName = /^[a-z][a-zA-Z0-9_-]{0,62}$/;
 const invalid = (message) => { throw new ContractError("USER_FIELD_INVALID", message, "auth:user", { status: 400 }); };
 function valueOf(value, spec, field) {
@@ -30,7 +28,6 @@ function valueOf(value, spec, field) {
         return invalid(`User field '${field}' accepts at most 64 values.`);
     return Object.freeze([...new Set(value.map(scalar))]);
 }
-/** Better Auth stores roles comma-separated; split exactly as it does and fail fast on a name no manifest could match. */
 export function rolesFrom(role) {
     if (role == null || role === "")
         return Object.freeze([]);
@@ -38,11 +35,9 @@ export function rolesFrom(role) {
         return invalid("User role must be comma-separated text.");
     return Object.freeze([...new Set(role.split(",").map(part => roleName.test(part) ? part : invalid(`Invalid role '${part}'.`)))]);
 }
-/** Better Auth's configured admin layer, independent of per-operation access control. */
 export function adminLayerOf(user, options = {}) {
     return !!options.adminUserIds?.includes(user.id) || rolesFrom(user.role).some(role => (options.adminRoles ?? ["admin"]).some(name => name.trim() === role));
 }
-/** Auth integration and test helpers validate a verified Better Auth-shaped user once. */
 export function userCaller(user, options = {}) {
     if (typeof user.id !== 'string' || !user.id || /^(host|system):/i.test(user.id))
         return invalid("User subjects must be non-empty strings without reserved prefixes.");
@@ -59,7 +54,6 @@ export function userCaller(user, options = {}) {
         admin: adminLayerOf(user, options), roles, fields,
         ...(options.issuer ? { issuer: options.issuer } : {}), scopes: Object.freeze([...(options.scopes ?? [])]),
         credential: options.credential ?? "session", credentialId: options.credentialId ?? null, clientId: options.clientId ?? null };
-    // The real actor is read from the brand, so a spread or forged copy never carries it.
     if (options.impersonatedBy)
         Object.defineProperty(caller, "impersonatedBy", { get() { return identities.get(this)?.impersonatedBy; } });
     identities.set(Object.freeze(caller), Object.freeze({ roles, fields, admin: caller.admin, ...(options.impersonatedBy ? { impersonatedBy: options.impersonatedBy } : {}) }));

package/dist/kernel/user-fields.d.ts

@@ -24,7 +24,7 @@ export declare function scopeInsert(scopes: readonly {
     readonly field: string;
     readonly type: 'string' | 'number';
 }[], caller: Caller, set: object): object;
-export { modeOf } from "./caller-identity.js";
+export { modeOf } from "./caller-mode.js";
 export interface UserRecipe extends Extract<Recipe, {
     k: "user";
 }> {

package/dist/kernel/user-fields.js

@@ -1,12 +1,9 @@
-/** Only the original caller carries authority. */
 import { ContractError } from "./contract-error.js";
 export const USER_REFS_V1 = 1;
 import { valueFor, isHostCaller } from "./caller-identity.js";
 import { isAllValues } from "./user-caller.js";
-/** Whether the caller holds `{ all: true }` for a field: its row-template term is dropped. */
 export const isAll = (caller, field) => isAllValues(valueFor(caller, field));
 const SCOPE_TERM = /\/\*s:(\w+)\*\/([^]*?)\/\*\|\*\/([^]*?)\/\*;\*\//g;
-/** Generated SQL prints each Schema scope term twice; `{ all: true }` keeps the always-true form, every other caller the filter. */
 export const scoped = (sql, caller) => sql.replace(SCOPE_TERM, (_, field, kept, all) => isAll(caller, field) ? all : kept);
 export const scopedAll = (value, caller) => JSON.parse(JSON.stringify(value), (_key, v) => typeof v === "string" ? scoped(v, caller) : v);
 const missing = (caller, field) => {
@@ -16,12 +13,10 @@ const missing = (caller, field) => {
         throw new ContractError('UNAUTHENTICATED', `Rows scoped by '${field}' require an authenticated caller.`);
     throw new ContractError('AUTH_DENIED', `The caller has no value for '${field}', which scopes these rows.`);
 };
-/** Store and Admin share the insert membership check. */
 export function scopeInsert(scopes, caller, set) {
     let out = set;
     for (const scope of scopes) {
         const own = ([field]) => field.toLowerCase() === scope.column;
-        // An optional input forwarded as `undefined` is "not given": autofill or the usual refusal applies, not a scope denial.
         out = Object.fromEntries(Object.entries(out).filter(entry => !(own(entry) && entry[1] === undefined)));
         const given = Object.entries(out).find(own);
         if (caller.kind === 'system' || isAll(caller, scope.field)) {
@@ -43,12 +38,10 @@ export function scopeInsert(scopes, caller, set) {
     }
     return out;
 }
-export { modeOf } from "./caller-identity.js";
+export { modeOf } from "./caller-mode.js";
 const pgArray = (values) => `{${values.map(value => `"${String(value).replace(/[\\"]/g, "\\$&")}"`).join(",")}}`;
-/** A missing or empty value is refused here, before any SQL runs; correctness never relies on NULL semantics. */
 export const userBinds = (sqlite) => (recipe, caller) => {
     const value = valueFor(caller, recipe.field);
-    // An all-values scope still binds its parameter; restrict never widens.
     if (isAllValues(value) && recipe.scope)
         return sqlite ? "[]" : "{}";
     if (isAllValues(value))
@@ -65,12 +58,9 @@ export const userRefs = (sqlite, version) => {
     return (recipe, caller, input) => {
         if (recipe.k === 'user')
             return user(recipe, caller);
-        // A field-scoped Schema's scope column on an SQL INSERT: the Store's insert rule. A surface converts an omitted
-        // optional input that SQL also reads elsewhere to null, and a scope column is never null, so null is "not given".
         if (recipe.k === 'scoped') {
             const given = recipe.name !== undefined ? input?.[recipe.name] ?? undefined : recipe.value;
             const value = scopeInsert([recipe], caller, { [recipe.column]: given })[recipe.column];
-            // scopeInsert checks the type only against a caller's own set; { all: true } and system callers name any value.
             if (typeof value !== recipe.type)
                 throw new ContractError('INPUT_VALIDATION_FAILED', `'${recipe.column}' must be a ${recipe.type}.`);
             return value;

package/dist/kernel/validation.js

@@ -1,8 +1,5 @@
-/** Helpers of generated input validation: the checks themselves are compiled per operation, no schema is read at request time. */
 import { invalid } from "./surface.js";
-/** INPUT_VALIDATION_FAILED at the JSON pointer `path`. */
 export function fail(path, message) { return invalid(message, path); }
-/** JSON equality for `enum`. */
 export function equal(a, b) {
     if (a === b)
         return true;
@@ -15,7 +12,6 @@ const pointer = (key) => key.replace(/~/g, "~0").replace(/\//g, "~1");
 const tests = { string: (value) => typeof value === "string", number: Number.isFinite, integer: Number.isSafeInteger, boolean: (value) => typeof value === "boolean", object: (value) => typeof value === "object" && value !== null && !Array.isArray(value) };
 const is = (value, path, type, nullable) => { if (!(tests[type](value) || nullable && value === null))
     fail(path, "Expected " + type + (nullable ? " or null." : ".")); };
-/** The check of the publishing transitions' input `{id, expectedVersion}` at `path`. */
 export function transition(path, raw) {
     const keys = ["id", "expectedVersion"];
     is(raw, path, "object");
@@ -38,10 +34,6 @@ function number(raw, path, integer) { const value = Number(raw); if (raw.trim()
     fail(path, "Expected a valid number."); return value; }
 function boolean(raw, path) { if (raw !== "true" && raw !== "false")
     fail(path, "Expected true or false."); return raw === "true"; }
-/**
- * A View's query string: each declared field (typed `boolean`, `integer` or `number` when the input says so) is read
- * from `params`, then validated; `limit` and `cursor` are the paging options. `operation` is `views/<name>`.
- */
 export function query(params, validate, operation, fields) {
     const input = {};
     for (const [key, type] of fields) {