@aotter/mantle 0.2.0-alpha.8 → 0.2.0

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,16 +1,11 @@
-/**
- * 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) {
-        if (Number.isNaN(v.getTime()))
+        const micros = v.getTime() * 1000;
+        if (!Number.isSafeInteger(micros))
             throw new ContractError("SQL_TYPE", "Invalid Date is not a timestamp");
-        return v.getTime() * 1000;
+        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`);
@@ -23,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;
@@ -39,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";

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);
@@ -86,13 +72,14 @@ export function createStore(d, drv, rules, facts, operations) {
         const pending = new WeakMap();
         const write = (build, project, path) => {
             const state = { build: () => { checkFresh(caller, false, path); return build(); }, project };
-            const value = { then: (yes, no) => {
-                    if (!state.promise) {
-                        state.promise = state.claimed ? Promise.reject(new Error("Write has already been batched.")) : Promise.resolve().then(async () => project((await drv.procedure(db, [state.build()], path))[0]));
-                        state.claimed = true;
-                    }
-                    return state.promise.then(yes, no);
-                } };
+            const run = () => {
+                if (!state.promise) {
+                    state.promise = state.claimed ? Promise.reject(new Error("Write has already been batched.")) : Promise.resolve().then(async () => project((await drv.procedure(db, [state.build()], path))[0]));
+                    state.claimed = true;
+                }
+                return state.promise;
+            };
+            const value = { then: (yes, no) => run().then(yes, no), catch: no => run().catch(no), finally: done => run().finally(done) };
             pending.set(value, state);
             return value;
         };
@@ -128,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));
@@ -146,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)
@@ -181,32 +166,32 @@ 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]);
+            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`);
-                return [d.ident(name), put(values, name, v)];
+                const mark = put(values, name, v);
+                if (v !== null)
+                    marks.set(key, mark);
+                return [d.ident(name), mark];
             });
-            /** `WHERE id = ? AND <the caller's row rules> AND version = ?` */
-            const guard = (id) => ` WHERE ${[`${ID} = ${push(id)}`, ...[...pol.terms, x.lock].map(t => renderTerm(d, t, t[1] === "parent" ? d.ident(p.name) + "." : "", recipe))].join(" AND ")}`;
+            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 ")})`] : []; });
+            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, recipe, guard, step, into, returning: () => ` RETURNING *, ${p.returning ??= wires(p, "")}` };
+            return { given, marks, recipe, refs, guard, step, into, returning: () => ` RETURNING *, ${p.returning ??= wires(p, "")}` };
         };
         return {
             async findById(id) {
@@ -235,7 +220,8 @@ export function createStore(d, drv, rules, facts, operations) {
                         names.push(d.ident(column));
                         marks.push(v === "newId" ? rules.newId : w.recipe(v));
                     }
-                    return w.step(`INSERT INTO ${w.into} (${names.join(", ")}) VALUES (${marks.join(", ")})${w.returning()}`);
+                    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`);
             },
             update(id, set, { lock }) {
@@ -243,7 +229,8 @@ 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)}`);
-                    return w.step(`UPDATE ${w.into} SET ${assigns.join(", ")}${w.guard(id)}${w.returning()}`);
+                    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`);
             },
             delete(id, { lock }) {

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) {
@@ -13,8 +11,8 @@ function valueOf(value, spec, field) {
         if (typeof value !== spec.type)
             return invalid(`User field '${field}' must contain ${spec.type} values.`);
         if (typeof value === "number") {
-            if (!Number.isFinite(value))
-                return invalid(`User field '${field}' must be finite.`);
+            if (!(spec.integer ? Number.isInteger(value) : Number.isFinite(value)))
+                return invalid(`User field '${field}' must be ${spec.integer ? "an integer" : "finite"}.`);
         }
         else if (typeof value === "string" && (!value.isWellFormed() || value.includes("\0") || new TextEncoder().encode(value).length < 1 || new TextEncoder().encode(value).length > 256))
             return invalid(`User field '${field}' must be 1–256 UTF-8 bytes, without NUL or lone surrogates.`);
@@ -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

@@ -8,6 +8,7 @@ export interface AllValues {
 export type UserValue = string | number | readonly (string | number)[] | AllValues;
 export interface UserField {
     readonly type: "string" | "number";
+    readonly integer?: true;
     readonly multiple: boolean;
     readonly enum?: readonly (string | number)[];
 }
@@ -23,12 +24,12 @@ 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";
 }> {
 }
 /** A missing or empty value is refused here, before any SQL runs; correctness never relies on NULL semantics. */
 export declare const userBinds: (sqlite: boolean) => (recipe: UserRecipe, caller: Caller) => unknown;
-export declare const userRefs: (sqlite: boolean, version: number) => (recipe: Recipe, caller: Caller) => unknown;
+export declare const userRefs: (sqlite: boolean, version: number) => (recipe: Recipe, caller: Caller, input?: Readonly<Record<string, unknown>>) => unknown;
 export { roleName, rolesFrom } from "./user-caller.js";

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))
@@ -62,9 +55,16 @@ export const userRefs = (sqlite, version) => {
     if (version !== USER_REFS_V1)
         throw new ContractError('USER_REFS_VERSION', 'User-reference bind version differs.');
     const user = userBinds(sqlite);
-    return (recipe, caller) => {
+    return (recipe, caller, input) => {
         if (recipe.k === 'user')
             return user(recipe, caller);
+        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];
+            if (typeof value !== recipe.type)
+                throw new ContractError('INPUT_VALIDATION_FAILED', `'${recipe.column}' must be a ${recipe.type}.`);
+            return value;
+        }
         throw new ContractError('USER_REFS_VERSION', `Unknown user-reference bind recipe '${recipe.k}'.`);
     };
 };

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

package/dist/kernel/web-gateway.js

@@ -1,4 +1,3 @@
-/** Selected web authorization loads on a request, outside the ordinary web startup graph. */
 import { web } from "./web.js";
 import { gatewayCaller, hostFailure } from "./host-caller.js";
 import { accessRequest } from "./host-access.js";
@@ -34,7 +33,6 @@ export function gatewayWeb(options, table) {
                             throw error;
                         }
                     } }]));
-            // The ordinary renderer validates query/path fields; wrapped pages decide before any SQL.
             const result = await site[method](request, env, options.gateway ? undefined : ctx);
             if (failure)
                 throw failure;

package/dist/kernel/web-head.js

@@ -1,4 +1,3 @@
-/** HTML head formatting loads only when the application asks for head tags. */
 const escape = (v) => String(v).replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
 export function headTags(canonical, row, markdown, locales) {
     let tags = '<link rel="canonical" href="' + escape(canonical) + '">';

package/dist/kernel/web-index.js

@@ -0,0 +1,39 @@
+const escape = (v) => String(v).replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+const label = (v) => String(v).replace(/[\r\n]/g, " ").replace(/[\\[\]]/g, "\\$&");
+const size = (s) => new TextEncoder().encode(s).length;
+export async function webIndex(sitemap, options, pages, list, validUrl) {
+    const cap = sitemap ? 50000 : 5000, limit = sitemap ? 50 * 1024 * 1024 : 1024 * 1024;
+    const start = sitemap ? '<?xml version="1.0" encoding="UTF-8"?><urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">' : "# " + label(options.title) + "\n\n> " + label(options.description) + "\n\n## Pages\n\n", end = sitemap ? "</urlset>" : "\n";
+    const links = [];
+    let visited = 0, requests = 0, bytes = size(start + end);
+    if (bytes > limit)
+        throw new TypeError("Web index header exceeds its byte limit.");
+    pagesLoop: for (const entry of pages) {
+        if (!entry.page.list)
+            continue;
+        let cursor;
+        do {
+            if (requests >= (sitemap ? 100 : 10))
+                break pagesLoop;
+            requests++;
+            const page = await list(entry.page.list, cursor);
+            for (const row of page.rows) {
+                if (visited++ >= cap)
+                    break pagesLoop;
+                const url = validUrl(entry.path, row, entry.page.view);
+                if (!url)
+                    continue;
+                const line = sitemap ? "<url><loc>" + escape(url) + "</loc></url>" : "- [" + label(row.title ?? url) + "](" + url + "): " + label(row.description ?? "") + "\n";
+                const length = size(line);
+                if (bytes + length > limit)
+                    break pagesLoop;
+                bytes += length;
+                links.push(line);
+            }
+            if (visited >= cap)
+                break pagesLoop;
+            cursor = page.nextCursor;
+        } while (cursor);
+    }
+    return start + links.join("") + end;
+}

package/dist/kernel/web-response.js

@@ -1,4 +1,3 @@
-/** Response hashing is needed only when a Web route actually renders. */
 export async function webResponse(request, body, type, cacheControl) {
     const hash = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(body));
     const etag = '"' + Array.from(new Uint8Array(hash), b => b.toString(16).padStart(2, '0')).join('') + '"';