@aotter/mantle 0.2.0-alpha.9 → 0.2.0

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

@@ -1,4 +1,3 @@
-/** /llms.txt and /sitemap.xml bodies; loaded only when an index is requested, so page Workers do not pay for it at startup. */
 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;

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('') + '"';

package/dist/kernel/web-serve.js

@@ -0,0 +1,97 @@
+import { forwarded, wire, ContractError } from "./contracts.js";
+import { decode } from "./surface.js";
+const NO_STORE = { "cache-control": "no-store" };
+const notFound = () => new Response(null, { status: 404, headers: NO_STORE });
+export function serve(options, views, pages, query) {
+    const origin = new URL(options.origin);
+    const context = async (request, env, ctx) => ({ db: options.db, caller: forwarded(ctx, options.gateway)
+            ? (await import("./host-caller.js")).gatewayCaller(ctx, options.gateway, options.fields)
+            : typeof options.caller === "function" ? await options.caller(request, env, { readOnly: ["GET", "HEAD"].includes(request.method) }) : options.caller ?? { kind: "anonymous" } });
+    const urlFor = (path, row, view) => origin.origin + path.replace(/\{([^{}]+)\}/g, (_, key) => {
+        let value = row[key];
+        if (views.get(view).booleans?.includes(key) && (value === 0 || value === 1))
+            value = Boolean(value);
+        if (value === null || value === undefined)
+            throw new TypeError("List View must return every page parameter: " + key);
+        const segment = String(value);
+        if (segment === "." || segment === "..")
+            return "";
+        return encodeURIComponent(segment).replace(/[()]/g, c => "%" + c.charCodeAt(0).toString(16).toUpperCase());
+    });
+    const validUrl = (path, row, view) => { if ([...path.matchAll(/\{([^{}]+)\}/g)].some(([, key]) => row[key] === "." || row[key] === ".."))
+        return; return urlFor(path, row, view); };
+    const match = (path) => {
+        for (const entry of pages) {
+            const hit = entry.pattern.exec(path);
+            if (!hit)
+                continue;
+            return { ...entry, params: new URLSearchParams(decode(entry.keys, hit, "Malformed URL parameter.", "web/path")) };
+        }
+    };
+    const read = async (entry, ctx) => (await query(entry.page.view, ctx.db, ctx.caller, entry.params)).rows[0];
+    const response = async (request, body, type, caller) => {
+        const { webResponse } = await import('./web-response.js');
+        return webResponse(request, body, type, caller.kind === "anonymous" ? (options.cacheControl ?? "public, max-age=60") : "private, no-store");
+    };
+    return {
+        async fetch(request, env, execution) {
+            let caller;
+            try {
+                if (request.method !== "GET" && request.method !== "HEAD")
+                    return;
+                const path = new URL(request.url).pathname, index = path === "/llms.txt" || path === "/sitemap.xml";
+                const entry = !index && path.endsWith(".md") ? match(path.slice(0, -3)) : undefined, markdown = entry?.page.markdown;
+                if (!index && !markdown)
+                    return;
+                const ctx = await context(request, env, execution);
+                caller = ctx.caller;
+                if (index) {
+                    const sitemap = path === "/sitemap.xml";
+                    const body = await (await import("./web-index.js")).webIndex(sitemap, options, pages, (list, cursor) => query(list, ctx.db, ctx.caller, new URLSearchParams(), cursor), validUrl);
+                    return response(request, body, sitemap ? "application/xml" : "text/plain", ctx.caller);
+                }
+                const exact = match(path);
+                if (exact)
+                    try {
+                        if (await read(exact, ctx))
+                            return;
+                    }
+                    catch (error) {
+                        if (wire(error).status !== 400)
+                            throw error;
+                    }
+                const row = await read(entry, ctx);
+                if (!row)
+                    return notFound();
+                const body = row[markdown];
+                if (body == null)
+                    return notFound();
+                if (typeof body !== "string")
+                    throw new TypeError("Markdown field must return text.");
+                return response(request, body, "text/markdown", ctx.caller);
+            }
+            catch (error) {
+                return (await import("./host-caller.js")).hostFailure(error, caller, "web");
+            }
+        },
+        async head(request, env, execution) {
+            try {
+                const path = new URL(request.url).pathname, entry = match(path);
+                if (!entry)
+                    return "";
+                const ctx = await context(request, env, execution), row = await read(entry, ctx);
+                if (!row)
+                    return "";
+                const canonical = validUrl(entry.path, row, entry.page.view);
+                if (!canonical)
+                    return "";
+                return (await import("./web-head.js")).headTags(canonical, row, !!entry.page.markdown, options.locales);
+            }
+            catch (error) {
+                if (error instanceof ContractError && error.code === "HOST_CONTRACT")
+                    throw error;
+                return "";
+            }
+        },
+    };
+}

package/dist/kernel/web.d.ts

@@ -1,5 +1,5 @@
 /** Web output for a generated public View table: /llms.txt, /sitemap.xml, Markdown pages and head tags. SQL owns visibility. */
-import { type Caller, type Gateway, type RequestContext } from "./contracts.js";
+import type { Caller, Gateway, RequestContext } from "./contracts.js";
 import type { UserFields } from "./user-fields.js";
 import { type Conversions } from "./surface.js";
 /** An app's public Views: row type and input keys per View, and the Views a list may name (input that accepts no fields). */