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

package/dist/kernel/store.js

@@ -0,0 +1,269 @@
+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 { 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 };
+}
+export function renderTerm(d, t, prefix, placeholder) {
+    const literal = (v) => `'${v.replaceAll("'", "''")}'`;
+    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") {
+        const [column, , value, parent] = t, alias = prefix === "_mantle_parent." || prefix === d.ident("_mantle_parent") + "." ? "_mantle_parent_" : "_mantle_parent";
+        const conditions = [`${alias}.${d.ident(column)} = ${prefix}${d.ident(column)}`, ...(parent.scope ? [`${alias}.${d.ident(parent.scope[0])} = ${prefix}${d.ident(parent.scope[1])}`] : []), ...parent.terms.map(t => renderTerm(d, t, alias + ".", param))];
+        const exists = `EXISTS (SELECT 1 FROM ${d.ident(parent.table)} ${alias} WHERE ${conditions.join(" AND ")})`;
+        return parent.admin ? `(${param(value)} = 1 OR ${exists})` : exists;
+    }
+    const [column, op, value, published] = t;
+    if (op !== 'eq' && op !== 'ttl' && op !== 'admin')
+        throw new ContractError('USER_REFS_VERSION', 'Unknown row-policy operator.');
+    const c = prefix + d.ident(column), bound = param(value);
+    if (op === "admin")
+        return `(${c} = ${literal(published)} OR ${bound} = 1)`;
+    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 }));
+}
+export function createStore(d, drv, rules, facts, operations) {
+    const prepared = new Map();
+    const prepare = (name) => {
+        let p = prepared.get(name);
+        if (!p) {
+            const f = facts[name];
+            prepared.set(name, p = { name, f, scope: f.s?.toLowerCase(), x: expand(rules, f), from: ` FROM ${d.ident(name)} r`, ts: ["created_at", "updated_at", ...f.ts ?? []], d: f.d ?? [], policy: new Map() });
+        }
+        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);
+        if (cached)
+            return cached;
+        const recipes = [], param = (r) => (recipes.push(r), d.param(recipes.length));
+        const sql = terms.map(t => renderTerm(d, t, "r.", param)).join(" AND ");
+        let from = p.from, projection = "";
+        const parent = p.f.parent;
+        if (parent) {
+            const alias = "_mantle_merge", conditions = [`${alias}.${d.ident(parent.on)} = r.${d.ident(parent.on)}`, ...(parent.scope ? [`${alias}.${d.ident(parent.scope[0])} = r.${d.ident(parent.scope[1])}`] : []), ...parentTerms.map(t => renderTerm(d, t, alias + ".", param))];
+            from += ` LEFT JOIN ${d.ident(parent.table)} ${alias} ON ${alias}.${ID} = (SELECT ${alias}.${ID} FROM ${d.ident(parent.table)} ${alias} WHERE ${conditions.join(" AND ")} ORDER BY ${alias}.${d.ident("created_at")} DESC, ${alias}.${ID} DESC LIMIT 1)`;
+            projection = parent.fields.map(c => `${(parent.ts.includes(c) ? d.wireTimestamp(alias + "." + d.ident(c)).join("") : parent.d.includes(c) ? d.wireDate(alias + "." + d.ident(c)).join("") : alias + "." + d.ident(c))} AS ${d.ident(c)}`).join(", ");
+        }
+        const preparedPolicy = { sql, recipes, from, projection, terms };
+        p.policy.set(trusted, preparedPolicy);
+        return preparedPolicy;
+    };
+    return ((db, caller, options) => make(db, caller, false, options));
+    function make(db, caller, inTransaction = false, options) {
+        const pending = new WeakMap();
+        const write = (build, project, path) => {
+            const state = { build: () => { checkFresh(caller, false, path); return build(); }, project };
+            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;
+        };
+        const store = {
+            collection: (name) => collection(db, caller, prepare(name), write),
+            ...Object.fromEntries(Object.keys(operations ?? {}).map(kind => {
+                const cache = Object.create(null);
+                return [kind, new Proxy(operations[kind], { get: (functions, name) => {
+                            if (Object.hasOwn(cache, name))
+                                return cache[name];
+                            const fn = functions[name];
+                            return fn && (cache[name] = (input) => fn(db, caller, input, options && { ...options, store }));
+                        } })];
+            })),
+            ...(!inTransaction && { batch: async (writes) => {
+                    const states = writes.map(w => pending.get(w));
+                    if (new Set(writes).size !== writes.length || states.some(s => !s || s.claimed))
+                        throw new Error("Batch needs unused Writes from this Store.");
+                    for (const s of states)
+                        s.claimed = true;
+                    const rows = writes.length ? await drv.procedure(db, states.map(s => s.build()), "store/batch") : [];
+                    return states.map((s, i) => s.project(rows[i]));
+                } }),
+            ...(drv.transaction && { transaction: async (fn, txOptions) => {
+                    if (inTransaction)
+                        throw new Error("Nested transactions are not supported.");
+                    return drv.transaction(db, tx => fn(make(tx, caller, true, options), tx), txOptions);
+                } }),
+        };
+        if (inTransaction)
+            transactionStores.add(store);
+        return store;
+    }
+    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));
+            return d.cast(d.param(values.length), type);
+        };
+        const conditions = (where, values) => {
+            const out = [];
+            for (const [name, spec] of Object.entries(where ?? {})) {
+                const operators = spec !== null && typeof spec === "object" && !(spec instanceof Date) && !Array.isArray(spec) ? Object.entries(spec) : [["eq", spec]];
+                for (const [op, v] of operators) {
+                    const left = `r.${d.ident(name)}`, bind = (x) => put(values, name, x);
+                    out.push(op === "isNull" ? condition(d, left, v ? "eq" : "ne", null, bind) : condition(d, left, op, v, bind));
+                }
+            }
+            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)
+                delete r[f.s];
+        } return list; };
+        const select = () => pol.select ??= `SELECT r.*, ${wires(p, "r.")}${pol.projection ? ", " + pol.projection : ""}${pol.from}`;
+        const where = (conds) => { const all = pol.sql ? [pol.sql, ...conds] : conds; return all.length ? ` WHERE ${all.join(" AND ")}` : ""; };
+        const base = () => evaluate(d, pol.recipes, caller);
+        async function find(q = {}) {
+            const dir = q.order ?? "asc", name = q.orderBy ?? "id", limit = q.limit ?? 50;
+            if (!Number.isInteger(limit) || limit < 1 || limit > 500)
+                throw no("limit is 1 to 500");
+            const values = base(), conds = conditions(q.where, values);
+            if (q.search !== undefined) {
+                if (typeof q.search !== "string" || !q.search.trim() || q.search.includes("\0"))
+                    throw no("search takes a non-empty string without NUL");
+                values.push(q.search.trim());
+                const query = d.param(values.length), exact = `r.${ID} = ${query}`;
+                conds.push(f.search?.length ? `(${exact} OR ${d.search(p.name, f.search, "r", query)})` : exact);
+            }
+            const id = `r.${ID}`, kc = `r.${d.ident(name)}`, up = dir === "asc", way = up ? "ASC" : "DESC";
+            if (q.cursor !== undefined) {
+                const [v, last] = decodeCursor(q.cursor, p.name + "/cursor");
+                values.push(last);
+                const after = `${id} ${up ? ">" : "<"} ${d.param(values.length)}`;
+                if (name === "id")
+                    conds.push(after);
+                else if (v === null)
+                    conds.push(`(${kc} IS NULL AND ${after})`);
+                else {
+                    const m = put(values, name, v);
+                    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);
+                if (v !== null)
+                    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, "")}` };
+        };
+        return {
+            async findById(id) {
+                const values = base();
+                values.push(id);
+                return clean(await rows(pol.byId ??= `${select()}${where([`r.${ID} = ${d.param(values.length)}`])} LIMIT 1`, values))[0] ?? null;
+            },
+            find,
+            async first(q = {}) { return (await find({ ...q, limit: 1 })).rows[0] ?? null; },
+            async count(w) {
+                const values = base(), conds = conditions(w, values);
+                return Number((await rows(`SELECT COUNT(*) AS "count"${pol.from}${where(conds)}`, values))[0].count);
+            },
+            insert(set) {
+                return write(() => {
+                    if (f.s && caller.kind === "anonymous")
+                        throw new ContractError("UNAUTHENTICATED", "A scoped insert requires an authenticated caller.", `${p.name}/insert`);
+                    if (f.u?.length)
+                        set = d.scopeInsert(f.u.map(u => ({ column: u[0], field: u[2].field, type: u[2].type })), caller, set);
+                    const w = writer(), names = [], marks = [];
+                    for (const [name, mark] of w.given(set, true)) {
+                        names.push(name);
+                        marks.push(mark);
+                    }
+                    for (const [column, v] of x.fills) {
+                        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`);
+            },
+            update(id, set, { lock }) {
+                return write(() => {
+                    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`);
+            },
+            delete(id, { lock }) {
+                return write(() => {
+                    const w = writer(lock);
+                    return w.step(`DELETE FROM ${w.into}${w.guard(id)}`);
+                }, () => undefined, `${p.name}/delete`);
+            },
+        };
+    }
+}

package/dist/kernel/surface.d.ts

@@ -0,0 +1,10 @@
+/** INPUT_VALIDATION_FAILED at `path`. */
+export declare function invalid(message: string, path: string): never;
+/**
+ * How each validated boundary field becomes a driver input, per declared bind: `json` is stringified, `bool` becomes
+ * 0/1 (SQLite only), anything else passes through; a missing value binds as null. Only fields an input bind reads.
+ */
+export type Conversions = ReadonlyArray<readonly [field: string, type: "" | "json" | "bool"]>;
+export declare function convert(input: Record<string, unknown>, fields?: Conversions): void;
+/** Path decoding for a matched template; a malformed escape is an input failure at `path`. */
+export declare function decode(keys: readonly string[], match: RegExpExecArray, message: string, path: string): Record<string, string>;

package/dist/kernel/surface.js

@@ -0,0 +1,19 @@
+/** 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) {
+        const value = input[key];
+        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])]));
+    }
+    catch {
+        invalid(message, path);
+    }
+}

package/dist/kernel/sweep.d.ts

@@ -0,0 +1,17 @@
+/** Host-only TTL maintenance; the selected candidates and delete share one native transaction. */
+import { type Caller, type Row } from "./contracts.js";
+import { type Values } from "./binds.js";
+export interface SweepInput {
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly delete?: boolean;
+}
+export interface SweepResult {
+    readonly scanned: number;
+    readonly removed: number;
+    readonly nextCursor?: string;
+}
+export declare function sweep<DB>(db: DB, caller: Caller, input: SweepInput, path: string, seconds: number, sql: readonly [string, string], d: Values, execute: (db: DB, steps: {
+    sql: string;
+    binds: unknown[];
+}[], path: string) => Promise<Row[][]>): Promise<SweepResult>;

package/dist/kernel/sweep.js

@@ -0,0 +1,27 @@
+/** 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) {
+    if (caller.kind !== "system" || typeof caller.reason !== "string" || !caller.reason.trim())
+        throw new ContractError("AUTH_DENIED", "TTL maintenance requires a host system caller with a reason.", path);
+    const limit = input.limit ?? 500;
+    const invalid = () => { throw new ContractError("INPUT_VALIDATION_FAILED", "Sweep limit must be 1..500, delete boolean, and cursor belong to this sweep.", path); };
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 500 || input.delete !== undefined && typeof input.delete !== "boolean")
+        invalid();
+    let after = 0;
+    if (input.cursor !== undefined) {
+        try {
+            const value = JSON.parse(decodeURIComponent(input.cursor));
+            if (!Array.isArray(value) || value.length !== 2 || value[0] !== path || !Number.isSafeInteger(value[1]) || value[1] < 1)
+                invalid();
+            after = value[1];
+        }
+        catch {
+            invalid();
+        }
+    }
+    const values = [...binds(d, [{ k: "cutoff", seconds }], caller), after, limit];
+    const [selected, deleted] = await execute(db, (input.delete === false ? [sql[0]] : sql).map(sql => ({ sql, binds: values })), path);
+    const last = Number(selected.at(-1)?._rid);
+    return { scanned: selected.length, removed: deleted?.length ?? 0, ...(selected.length === limit ? { nextCursor: encodeURIComponent(JSON.stringify([path, last])) } : {}) };
+}

package/dist/kernel/translations.d.ts

@@ -0,0 +1 @@
+export declare function toCanonicalLocale(value: string): string;

package/dist/kernel/translations.js

@@ -0,0 +1,13 @@
+/** Locale values stay ordinary strings; applications opt into canonicalisation. */
+import { invalid } from "./surface.js";
+export function toCanonicalLocale(value) {
+    if (typeof value !== "string" || !value)
+        invalid("Invalid locale.", "locale");
+    let parts = value.replaceAll("_", "-").split("-");
+    if (parts.length === 1 && parts[0].length === 4)
+        parts = [parts[0].slice(0, 2), parts[0].slice(2)];
+    const language = parts[0], region = parts[1];
+    if (!/^[A-Za-z]{2,3}$/.test(language) || region !== undefined && !/^[A-Za-z]{2}$/.test(region))
+        invalid("Invalid locale.", "locale");
+    return language.toLowerCase() + (region === undefined ? "" : "-" + region.toUpperCase());
+}

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

@@ -0,0 +1,31 @@
+import type { Caller, CredentialKind } from "./contracts.js";
+import type { AllValues, UserFields } from "./user-fields.js";
+export declare const isAllValues: (value: unknown) => value is AllValues;
+/** Role names follow Better Auth's role strings; `-` is allowed. */
+export declare const roleName: RegExp;
+/** Better Auth stores roles comma-separated; split exactly as it does and fail fast on a name no manifest could match. */
+export declare function rolesFrom(role: unknown): readonly string[];
+/** Better Auth's configured admin layer, independent of per-operation access control. */
+export declare function adminLayerOf(user: {
+    id: string;
+    role?: unknown;
+}, options?: {
+    adminRoles?: readonly string[];
+    adminUserIds?: readonly string[];
+}): boolean;
+/** Auth integration and test helpers validate a verified Better Auth-shaped user once. */
+export declare function userCaller(user: Readonly<Record<string, unknown>> & {
+    readonly id: string;
+}, options?: {
+    readonly fields?: UserFields;
+    readonly adminRoles?: readonly string[];
+    readonly adminUserIds?: readonly string[];
+    readonly credential?: CredentialKind;
+    readonly credentialId?: string | null;
+    readonly clientId?: string | null;
+    readonly scopes?: readonly string[];
+    readonly issuer?: string;
+    readonly impersonatedBy?: string;
+}): Extract<Caller, {
+    kind: "user";
+}>;

package/dist/kernel/user-caller.js

@@ -0,0 +1,67 @@
+/** 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) {
+    if (isAllValues(value))
+        return Object.freeze({ all: true });
+    const scalar = (value) => {
+        if (typeof value !== spec.type)
+            return invalid(`User field '${field}' must contain ${spec.type} values.`);
+        if (typeof value === "number") {
+            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.`);
+        if (spec.enum && !spec.enum.includes(value))
+            return invalid(`User field '${field}' is outside its enum.`);
+        return value;
+    };
+    if (!Array.isArray(value))
+        return scalar(value);
+    if (!spec.multiple)
+        return invalid(`User field '${field}' holds one value.`);
+    if (value.length > 64)
+        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([]);
+    if (typeof role !== "string")
+        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.");
+    const roles = rolesFrom(user.role);
+    const fields = Object.create(null);
+    for (const [field, spec] of Object.entries(options.fields ?? {})) {
+        if (!validUserFieldName(field))
+            return invalid(`Invalid or reserved user field '${field}'.`);
+        if (Object.hasOwn(user, field) && user[field] !== undefined && user[field] !== null)
+            fields[field] = valueOf(user[field], spec, field);
+    }
+    Object.freeze(fields);
+    const caller = { kind: "user", subject: user.id, role: typeof user.role === "string" ? user.role : null,
+        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 } : {}) }));
+    return caller;
+}

package/dist/kernel/user-field-name.js

@@ -0,0 +1,3 @@
+const name = /^[a-z][a-zA-Z0-9_]{0,62}$/;
+const reserved = " id email emailVerified name image createdAt updatedAt role banned banReason banExpires ";
+export const validUserFieldName = (field) => name.test(field) && !reserved.includes(' ' + field + ' ') && !field.startsWith("mantle");

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

@@ -0,0 +1,35 @@
+import type { Caller } from "./contracts.js";
+import type { Recipe } from './binds.js';
+export declare const USER_REFS_V1: 1;
+/** The typed "every value" state of one field: a structural value, never a magic string. */
+export interface AllValues {
+    readonly all: true;
+}
+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)[];
+}
+export type UserFields = Readonly<Record<string, UserField>>;
+/** Whether the caller holds `{ all: true }` for a field: its row-template term is dropped. */
+export declare const isAll: (caller: Caller, field: string) => boolean;
+/** Generated SQL prints each Schema scope term twice; `{ all: true }` keeps the always-true form, every other caller the filter. */
+export declare const scoped: (sql: string, caller: Caller) => string;
+export declare const scopedAll: <T>(value: T, caller: Caller) => T;
+/** Store and Admin share the insert membership check. */
+export declare function scopeInsert(scopes: readonly {
+    readonly column: string;
+    readonly field: string;
+    readonly type: 'string' | 'number';
+}[], caller: Caller, set: object): object;
+export { modeOf } from "./caller-identity.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, input?: Readonly<Record<string, unknown>>) => unknown;
+export { roleName, rolesFrom } from "./user-caller.js";

package/dist/kernel/user-fields.js

@@ -0,0 +1,81 @@
+/** 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) => {
+    if (isHostCaller(caller))
+        throw new ContractError("HOST_CONTRACT", `The target needs user field '${field}'.`, "", { status: 412, fields: { field } });
+    if (caller.kind === "anonymous")
+        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)) {
+            if (!given)
+                throw new ContractError('INPUT_VALIDATION_FAILED', `An explicit '${scope.column}' value is required.`);
+            continue;
+        }
+        const value = valueFor(caller, scope.field), values = value === undefined ? [] : Array.isArray(value) ? value : [value];
+        if (!values.length)
+            missing(caller, scope.field);
+        if (given) {
+            if (typeof given[1] !== scope.type || !values.includes(given[1]))
+                throw new ContractError('AUTH_DENIED', `The value is outside the caller's '${scope.field}' scope.`);
+            continue;
+        }
+        if (values.length !== 1)
+            throw new ContractError('INPUT_VALIDATION_FAILED', `'${scope.column}' is required: the caller holds several '${scope.field}' values.`);
+        out = { ...out, [scope.column]: values[0] };
+    }
+    return out;
+}
+export { modeOf } from "./caller-identity.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))
+        throw new ContractError('AUTH_DENIED', `This target restricts rows by '${recipe.field}', which needs explicit values; { all: true } does not lift a restrict.`);
+    const values = value === undefined ? [] : Array.isArray(value) ? value : [value];
+    if (!values.length)
+        missing(caller, recipe.field);
+    return sqlite ? JSON.stringify(values) : pgArray(values);
+};
+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, 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;
+        }
+        throw new ContractError('USER_REFS_VERSION', `Unknown user-reference bind recipe '${recipe.k}'.`);
+    };
+};
+export { roleName, rolesFrom } from "./user-caller.js";

package/dist/kernel/validation.d.ts

@@ -0,0 +1,15 @@
+/** INPUT_VALIDATION_FAILED at the JSON pointer `path`. */
+export declare function fail(path: string, message: string): never;
+/** JSON equality for `enum`. */
+export declare function equal(a: unknown, b: unknown): boolean;
+/** The check of the publishing transitions' input `{id, expectedVersion}` at `path`. */
+export declare function transition(path: string, raw: unknown): Record<string, unknown>;
+/**
+ * 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 declare function query(params: URLSearchParams, validate: (raw: unknown) => Record<string, unknown>, operation: string, fields: ReadonlyArray<readonly [key: string, type?: "boolean" | "integer" | "number"]>): {
+    input: Record<string, unknown>;
+    limit?: number;
+    cursor?: string;
+};