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

package/dist/domain/entry.js

@@ -0,0 +1,33 @@
+/** Direct entry files: one View or Procedure per module, so a request bundle excludes the others. */
+/**
+ * Stable, injective build-only export names, so a stale entry file cannot bind a new ordinal: every byte outside [A-Za-z0-9]
+ * (including `$` and `_`) is `$` and two hex digits.
+ * @internal
+ */
+export const exportName = (kind, name) => kind + "_" + name.replace(/[^A-Za-z0-9]+/g, run => Array.from(new TextEncoder().encode(run), b => "$" + b.toString(16).padStart(2, "0")).join(""));
+/** A direct entry: `import` then `export`, because Bun 1.3 drops a bare `export { x as default } from` binding under "sideEffects": false. `extra` is any further re-export line. */
+/** @internal */
+export const entry = (kind, name, types, extra = "") => `import { ${exportName(kind, name)} as operation } from "../generated.js";\nexport default operation;\nexport type { ${types} } from "../generated.js";\n${extra}`;
+/** Source text of a JSON value. @internal */
+export const q = JSON.stringify;
+/** Whether a target's database is SQLite (bun:sqlite or D1). @internal */
+export const isSqlite = (target) => target === "bun-sqlite" || target === "cloudflare-d1";
+/** A View's lazy paged boundary and validated query reader, bound as `page<index>` and `<query><index>`. @internal */
+export const viewImports = (name, index, query = "query") => [`const page${index}: typeof import("./paged/views/${encodeURIComponent(name)}.js").default = async (...args) => (await import("./paged/views/${encodeURIComponent(name)}.js")).default(...args);`, `import { query as ${query}${index} } from "./validation/views/${encodeURIComponent(name)}.js";`];
+/** A generated host handle import, shared by the optional boundaries. @internal */
+export const driverFor = (target) => target === "bun-sqlite" ? "bun-sqlite" : target === "cloudflare-d1" ? "d1" : "postgres";
+export const databaseImport = (target) => driverFor(target) === "postgres" ? 'import type { Postgres as Database } from "@aotter/mantle/contracts";' : `import type { Handle as Database } from "@aotter/mantle/driver/${driverFor(target)}";`;
+/** Shared source ownership marker; only newly emitted files are wrapped. */
+export const GENERATED = "Generated by mantle generate — do not edit.";
+export function generatedFiles(files) {
+    return Object.fromEntries(Object.entries(files).map(([name, source]) => [name,
+        `${name.endsWith(".sql") ? "--" : "//"} ${GENERATED}\n${source}`]));
+}
+/** JavaScript data literals preserve own __proto__ keys instead of mutating the object's prototype. */
+export function literal(value) {
+    if (Array.isArray(value))
+        return `[${value.map(literal).join(",")}]`;
+    if (value && typeof value === "object")
+        return `{${Object.entries(value).map(([key, child]) => `${key === "__proto__" ? `[${q(key)}]` : q(key)}:${literal(child)}`).join(",")}}`;
+    return q(value);
+}

package/dist/domain/generated-tools.js

@@ -0,0 +1,19 @@
+export const publishingTransitions = [["publish", ["draft"], "published"], ["unpublish", ["published", "archived"], "draft"], ["archive", ["draft", "published"], "archived"]];
+/** Only archive withdraws an entry from both drafts and the public. */
+export const publishingAnnotations = (verb) => ({ readOnlyHint: false, destructiveHint: verb === "archive" });
+export const publishingInput = { type: "object", properties: { id: { type: "string", minLength: 1 }, expectedVersion: { type: "integer", minimum: 1 } }, required: ["id", "expectedVersion"], additionalProperties: false };
+export function mediaDefinitions() {
+    const define = (name, description, inputSchema, action, readOnlyHint = false) => ({ name, description, inputSchema, action, annotations: { readOnlyHint, destructiveHint: action === "delete", openWorldHint: true } });
+    const string = { type: "string" };
+    const texts = { alt: { type: "string", maxLength: 1000 }, caption: { type: "string", maxLength: 1000 } };
+    const input = (properties, required = []) => ({ type: "object", properties, required, additionalProperties: false });
+    return [
+        define("get_media_upload_policy", "Read declared image purpose MIME slots and byte caps before preparing variants or requesting an upload. Optimization runs locally, never in the host.", input({}), "policy", true),
+        define("create_media_upload", "Create short-lived PUT capabilities for image variants. Read site media purpose policy first; optimize images locally. Obtain attachment bytes yourself, then PUT each variant with its requiredHeaders and call commit_media_upload. Never store upload URLs as published images or ask the user to run terminal commands.", input({ filename: { type: "string", maxLength: 255 }, purpose: string, variants: { type: "array", minItems: 1, items: input({ mimeType: string, byteSize: { type: "integer", minimum: 1 }, role: { type: "string", enum: ["primary", "alternate", "fallback"] } }, ["mimeType", "byteSize", "role"]) }, ...texts }, ["filename", "purpose", "variants"]), "create"),
+        define("commit_media_upload", "Verify all uploaded variants and commit one permanent media asset. Store the returned asset id in fields referencing media_assets.id, never a temporary upload URL. Unknown or expired upload groups require a new create_media_upload.", input({ uploadGroupId: string, ...texts }, ["uploadGroupId"]), "commit"),
+        define("list_media_assets", "List committed image assets, newest first, with their permanent variants and alt/caption. Search matches id, alt or caption; reuse only a returned cursor.", input({ limit: { type: "integer", minimum: 1, maximum: 500 }, cursor: string, search: string }), "list", true),
+        define("get_media_asset", "Read one committed media asset and its permanent variant URLs.", input({ id: string }, ["id"]), "get", true),
+        define("update_media_asset", "Update committed asset alt or caption; omitted fields remain unchanged and empty strings clear text.", input({ id: string, ...texts }, ["id"]), "update"),
+        define("delete_media_asset", "Delete an asset's objects and library record. Check application references first. A partial failure can be retried using the same id.", input({ id: string }, ["id"]), "delete"),
+    ];
+}

package/dist/domain/generation.d.ts

@@ -0,0 +1,16 @@
+/** Public generation targets and result envelope. */
+export type Target = "bun-sqlite" | "bun-postgres" | "cloudflare-d1" | "cloudflare-postgres";
+export interface GenerateDiagnostic {
+    readonly code: string;
+    readonly path: string;
+    readonly message: string;
+}
+export type GenerateResult = {
+    readonly ok: true;
+    readonly files: Readonly<Record<string, string>>;
+    readonly refProcedures: readonly string[];
+    readonly warnings?: readonly string[];
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly GenerateDiagnostic[];
+};

package/dist/domain/generation.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/input.js

@@ -0,0 +1,17 @@
+import { q } from "./entry.js";
+/** The kernel's `Conversions` for the fields an input bind reads (see kernel/surface), as a literal; empty when none. */
+export function conversions(properties, binds, target) {
+    const fields = Object.keys(properties ?? {}).flatMap(field => {
+        const bind = binds.find(b => b.k === "input" && String(b.name).toLowerCase() === field.toLowerCase());
+        if (!bind || bind.k !== "input")
+            return [];
+        const type = String(bind.type);
+        return [[field, type === "json" ? "json" : type === "bool" && !target.endsWith("postgres") ? "bool" : ""]];
+    });
+    return fields.length ? q(fields) : "";
+}
+/** Only build-time authorization assembly; generated queries retain their existing predicates. @internal */
+export const authLines = (requires, path, binds = [], sqlite = true, trustedOnly = false) => [...(trustedOnly ? [`  deny(caller, caller.kind === "system", ${q(path)});`] : []), ...(requires?.auth?.all ?? []).map((p, index) => {
+        const allowed = typeof p === "string" ? p === "ctx.admin" ? 'isAdmin(caller)' : 'isUser(caller)' : `caller.kind === "user" && caller.scopes.includes(${q(p["ctx.auth.scope"])})`;
+        return `  deny(caller, ${allowed}, ${q(`${path}/requires/auth/all/${index}`)});`;
+    }), ...binds.filter(b => b.k === "user").map(b => `  userBinds(${sqlite})(${q(b)}, caller);`)];

package/dist/domain/model.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/paging.js

@@ -0,0 +1,230 @@
+/** Build-time proofs for the compiler's keyset keys. No AST reaches a generated operation. */
+import { NATIVE_COLUMNS, NATIVE_NOT_NULL, notNullColumns } from "../build/compiler.js";
+import { declaredType } from "./columns.js";
+/** Storage column -> the native field a manifest index names. */
+const NATIVE_FIELDS = new Map(Object.entries(NATIVE_COLUMNS).map(([field, column]) => [column, field]));
+const fieldName = (n) => n.ColumnRef?.fields?.at(-1)?.String?.sval;
+const scalar = (n) => !!(n.ParamRef || n.A_Const || n.TypeCast && scalar(n.TypeCast.arg));
+// A user-field term lowers to the dialect's anyOf, `(col) IN (SELECT value FROM json_each((?)))` or `(col) = ANY(CAST(...(?)...))`.
+const anyOf = (raw) => raw?.length === 8 && raw[1]?.ColumnRef && raw[5]?.ParamRef && /^ (IN \(SELECT value FROM json_each\(|= ANY\()/.test(raw[3]);
+// A scope prints `/*s:field*/ kept /*|*/ kept OR 1 = 1 /*;*/`, so `{ all: true }` drops it; any other anyOf is a restrict, which it never lifts.
+const scopeTerm = (raw) => typeof raw?.[0] === "string" && raw[0].startsWith("/*s:");
+const restricts = (n) => !!n && typeof n === "object" && (anyOf(n.Raw?.parts) || !scopeTerm(n.Raw?.parts) && Object.values(n).some(restricts));
+const aggregate = (n) => !!n && !n.SubLink && !n.SelectStmt && (n.FuncCall && !n.FuncCall.over && ["count", "sum", "min", "max", "avg"].includes(n.FuncCall.funcname?.at(-1)?.String?.sval) || Object.values(n).some(v => v && typeof v === "object" && (Array.isArray(v) ? v.some(aggregate) : aggregate(v))));
+/** Only complete grouped tuples, base ids and non-fanning singleton joins are proved. */
+export function provePaging(plan, ast) {
+    let reason;
+    const fail = (message) => { reason = message; return undefined; };
+    const select = (s, inherited = new Map()) => {
+        if (!s || s.distinctClause || s.op && s.op !== "SETOP_NONE")
+            return;
+        const ctes = new Map(inherited);
+        for (const c of s.withClause?.ctes ?? []) {
+            const n = c.CommonTableExpr;
+            ctes.set(n.ctename, undefined);
+            ctes.set(n.ctename, n.aliascolnames?.length ? undefined : select(n.ctequery.SelectStmt, ctes)?.relation);
+        }
+        reason = undefined;
+        const aliases = new Map();
+        const reduced = !!s.groupClause?.length || (s.targetList ?? []).some((t) => aggregate(t.ResTarget.val));
+        const relation = (n) => {
+            if (n.JoinExpr) {
+                const left = relation(n.JoinExpr.larg), before = new Set(aliases.keys()), right = relation(n.JoinExpr.rarg);
+                if (!left || !right)
+                    return;
+                const column = (v) => v?.ColumnRef?.fields?.length === 2 ? aliases.get(v.ColumnRef.fields[0].String?.sval)?.fields.get(fieldName(v)) : undefined;
+                const lookup = (side, other, term) => {
+                    if (term?.BoolExpr?.boolop === "AND_EXPR")
+                        return term.BoolExpr.args.some((x) => lookup(side, other, x));
+                    const e = term?.A_Expr, id = side.fields.get("id"), otherId = other.fields.get("id");
+                    if (!side.unique || !id || !otherId || e?.kind !== "AEXPR_OP" || e.name?.[0]?.String?.sval !== "=")
+                        return false;
+                    const a = column(e.lexpr), b = column(e.rexpr);
+                    const unique = (f, value) => f && value && f.source === id.source && value.source === otherId.source &&
+                        (f.name === id.name || (!f.schema.userScopes?.length && !f.schema.scope && f.schema.unique?.some(index => index.length === 1 && index[0] === f.name)));
+                    return !!(unique(a, b) || unique(b, a));
+                };
+                const rightSingle = right.single || lookup(right, left, n.JoinExpr.quals);
+                const leftSingle = left.single || lookup(left, right, n.JoinExpr.quals);
+                if (!rightSingle && (!leftSingle || n.JoinExpr.jointype === "JOIN_LEFT") && !reduced)
+                    return fail(`Fanning join '${[...aliases.keys()].filter(alias => !before.has(alias)).join(", ")}': join on the joined Schema's id or a single-field unique key, or reduce it to one row.`);
+                if (n.JoinExpr.jointype === "JOIN_FULL" || n.JoinExpr.jointype === "JOIN_RIGHT")
+                    return;
+                // The right side of LEFT JOIN may be absent: its fields cannot become NOT NULL cursor keys.
+                if (n.JoinExpr.jointype === "JOIN_LEFT")
+                    for (const [alias, r] of aliases)
+                        if (!before.has(alias))
+                            r.fields = new Map([...r.fields].map(([k, f]) => [k, { ...f, notNull: false }]));
+                return rightSingle ? left : leftSingle ? right : { ...left, unique: false };
+            }
+            const r = n.RangeVar, sub = n.RangeSubselect;
+            let fact;
+            if (r && r.mantle !== "cte" && plan.schemas[r.relname]) {
+                const schema = plan.schemas[r.relname], notNull = notNullColumns(schema), source = {};
+                const fields = new Map();
+                for (const name of [...Object.keys(schema.fields), "id", "version", "created_at", "updated_at", "author_id", "status"]) {
+                    const type = declaredType(schema.fields, name) ?? (name === "version" ? "integer" : "text");
+                    fields.set(name, { schema, name, type, notNull: NATIVE_NOT_NULL.has(name) || notNull.has(name), source });
+                }
+                fact = { fields, names: new Set(fields.keys()), single: false, unique: true, fixed: new Set(), sets: new Set() };
+            }
+            else if (r?.mantle === "cte")
+                fact = ctes.get(r.relname);
+            else if (sub)
+                fact = select(sub.subquery.SelectStmt, ctes)?.relation;
+            if (fact) {
+                // Two aliases of one Schema/CTE are distinct row sources, including a singleton joined to many rows.
+                const sources = new Map();
+                fact = { ...fact, fields: new Map([...fact.fields].map(([name, f]) => {
+                        if (!sources.has(f.source))
+                            sources.set(f.source, {});
+                        return [name, { ...f, source: sources.get(f.source) }];
+                    })), fixed: new Set(fact.fixed), sets: new Set(fact.sets) };
+                aliases.set(r?.alias?.aliasname ?? r?.relname ?? sub.alias.aliasname, fact);
+            }
+            return fact;
+        };
+        const from = s.fromClause ?? [];
+        let base;
+        for (const n of from) {
+            const r = relation(n);
+            if (!r || base && !base.single && !r.single)
+                return;
+            if (!base || !r.single)
+                base = r;
+        }
+        base ??= { fields: new Map(), names: new Set(), single: true, unique: false, fixed: new Set(), sets: new Set() };
+        const targets = new Map((s.targetList ?? []).map((t) => [t.ResTarget.name ?? fieldName(t.ResTarget.val), t.ResTarget.val]));
+        const resolve = (n, output = true) => {
+            const fields = n?.ColumnRef?.fields;
+            if (fields?.every((f) => f.String) && fields.length <= 2) {
+                const name = fieldName(n);
+                if (fields.length === 2)
+                    return aliases.get(fields[0].String.sval)?.fields.get(name);
+                if (output && targets.has(name))
+                    return resolve(targets.get(name), false);
+                const matches = [...aliases.values()].filter(r => r.names.has(name));
+                return matches.length === 1 ? matches[0].fields.get(name) : undefined;
+            }
+            const f = n?.FuncCall;
+            if (f && !f.over && !f.agg_filter && ["min", "max"].includes(f.funcname?.at(-1)?.String?.sval) && f.args?.length === 1 && s.groupClause?.length)
+                return resolve(f.args[0], false);
+            const pos = n?.A_Const?.ival?.ival;
+            if (output && pos > 0)
+                return resolve(s.targetList[pos - 1]?.ResTarget.val, false);
+            return;
+        };
+        const fixed = (n) => {
+            if (n?.BoolExpr?.boolop === "AND_EXPR")
+                n.BoolExpr.args.forEach(fixed);
+            // `col IN auth.user(field)` (a scope or restrict) never fixes a prefix (#1644): the plan is prepared for a set, so
+            // native ORDER BY after it reads and sorts all the caller's rows. It is only remembered for the refusal's guidance.
+            const raw = n?.Raw?.parts;
+            if (scopeTerm(raw))
+                return fixed(raw[1]);
+            if (anyOf(raw)) {
+                const col = resolve(raw[1], false);
+                if (col && col.source === base.fields.get("id")?.source)
+                    base.sets.add(col.name);
+                return;
+            }
+            const e = n?.A_Expr;
+            if (e?.kind !== "AEXPR_OP" || e.name?.[0]?.String?.sval !== "=")
+                return;
+            const col = scalar(e.rexpr) ? resolve(e.lexpr, false) : scalar(e.lexpr) ? resolve(e.rexpr, false) : undefined;
+            if (col && col.source === base.fields.get("id")?.source)
+                base.fixed.add(col.name);
+        };
+        fixed(s.whereClause);
+        const fields = new Map();
+        for (const [name, expr] of targets) {
+            const field = resolve(expr, false);
+            if (field && name)
+                fields.set(name, field);
+        }
+        const group = s.groupClause ?? [], sorts = s.sortClause ?? [];
+        const keys = sorts.map(k => resolve(k.SortBy.node));
+        if (keys.some(k => k && !k.notNull))
+            return fail(`Nullable ORDER BY key '${keys.find(k => k && !k.notNull).name}': make the operational Schema field required and non-null, and order by the preserved side of a LEFT JOIN.`);
+        if (keys.some(k => !k?.notNull || !["text", "bool", "integer", "int4", "int8", "real", "float8", "date", "timestamptz"].includes(k.type) && !/^numeric\(/.test(k.type)))
+            return;
+        const same = (a, b) => a && b && a.name === b.name && a.source === b.source;
+        if (sorts.length) {
+            if (group.length) {
+                // Full GROUP BY keys, not an id from an arbitrary row in the group, make the result unique.
+                if (!group.every(g => {
+                    // GROUP BY prefers an input column over a colliding output alias; ORDER BY does the reverse.
+                    const source = g.ColumnRef?.fields?.length === 1 ? [...aliases.values()].filter(r => r.names.has(fieldName(g))) : [];
+                    const f = source.length ? source.length === 1 ? source[0].fields.get(fieldName(g)) : undefined : resolve(g);
+                    return f?.notNull && keys.some(k => same(k, f));
+                }))
+                    return;
+            }
+            else {
+                if (!base.unique || !keys.some(k => same(k, base.fields.get("id"))))
+                    return fail("Incomplete ORDER BY key tuple: include the base Schema's id as a tiebreak and preserve its row identity.");
+                const order = keys.filter(k => k.name !== "id");
+                if (order.length) {
+                    const schema = order[0].schema;
+                    if (order.some(f => f.source !== base.fields.get("id")?.source))
+                        return;
+                    const serving = (prefix) => [...(schema.indexes ?? []), ...(schema.unique ?? [])].find(index => {
+                        let i = 0;
+                        while (i < index.length && prefix.has(index[i]) && index[i] !== order[0].name)
+                            i++;
+                        return order.every((f, n) => index[i + n] === f.name);
+                    });
+                    if (!serving(base.fixed)) {
+                        // SQL names a column (`created_at`), a manifest index the field (`createdAt`).
+                        const index = serving(new Set([...base.fixed, ...base.sets])), named = (c) => schema.names?.[c] ?? c, field = (c) => schema.names?.[c] ?? NATIVE_FIELDS.get(c) ?? c;
+                        const columns = order.map(f => named(f.name)).join(", "), fields = order.map(f => field(f.name)).join(", ");
+                        if (!index)
+                            return fail(`Missing index for ORDER BY (${columns}): declare a Schema index with [${fields}] in this order after any fixed equality prefix.`);
+                        const prefix = index.slice(0, index.indexOf(order[0].name)), set = prefix.filter(c => !base.fixed.has(c));
+                        // The suggested order is the index from its first set-bound column: an equality-fixed column between stays in it.
+                        const lead = prefix.slice(prefix.indexOf(set[0])), quoted = (cs) => cs.map(c => `'${field(c)}'`).join(", ");
+                        // The scope-first order is offered only when SQL can name every added column and none can be null. The owner
+                        // scope column is NOT NULL in storage, but a View cannot address it.
+                        const notNull = notNullColumns(schema), owner = lead.filter(c => c === schema.scope), nullable = lead.filter(c => !NATIVE_NOT_NULL.has(c) && !notNull.has(c) && c !== schema.scope);
+                        const dir = (f) => sorts[keys.indexOf(f)].SortBy.sortby_dir === "SORTBY_DESC" ? " DESC" : "";
+                        const sorted = [...lead.map(c => named(c) + dir(order[0])), ...order.map(f => named(f.name) + dir(f))].join(", ");
+                        const desc = order.some(f => dir(f)) ? ", read backwards; on PostgreSQL confirm with EXPLAIN that no Sort remains" : "";
+                        // `{ all: true }` drops only scope terms: offer it an index on the View's equality-fixed columns, unless a restrict remains.
+                        const eq = [...base.fixed].filter(c => c !== "id" && !order.some(f => f.name === c));
+                        const ways = [...nullable.length || owner.length ? [] : [`ORDER BY ${sorted} (same index${desc})`], ...restricts(ast) ? [] : [`for { all: true } callers only, index [${[...eq.map(field), fields].join(", ")}, id]`]];
+                        const why = [...owner.length ? [`${quoted(owner)} is the owner column, which SQL cannot name`] : [], ...nullable.length ? [`${quoted(nullable)} can be null`] : []];
+                        const unavailable = why.length ? ` Scope-first ORDER BY unavailable: ${why.join("; ")}${ways.length ? "." : ""}` : "";
+                        return fail(`ORDER BY (${columns}) needs index [${index.map(field).join(", ")}] past ${quoted(set)}, which a user-field scope or restrict binds to a set of values: every page would sort all of the caller's rows.${unavailable}${ways.length ? ` Bounded: ${ways.join("; ")}` : ""} (handbook: reference/schema.md#index-prefixes-for-paged-views).`);
+                    }
+                }
+            }
+        }
+        const single = base.single || !group.length && (s.targetList ?? []).some((t) => aggregate(t.ResTarget.val)) || s.limitCount?.A_Const?.ival?.ival === 1 || base.unique && base.fixed.has("id");
+        return { relation: { fields, names: new Set(targets.keys()), single, unique: !group.length && base.unique && !!same(fields.get("id"), base.fields.get("id")), fixed: base.fixed, sets: base.sets }, keys: keys };
+    };
+    const result = select(ast.SelectStmt);
+    return result ? { types: result.keys.map(f => f.type), single: result.relation.single } : reason ? { types: [], single: false, reason } : undefined;
+}
+/** Cast only cursor ParamRefs in the outer predicate, never authored literals or bare projections. */
+export function castCursor(ast, sources, types, postgres) {
+    const typeOf = (source) => source && "cursor" in source ? types[source.cursor] : undefined;
+    const typed = (type) => type && (postgres ? ["timestamptz", "date"] : ["integer", "int4", "int8"]).includes(type);
+    if (!sources.some(source => typed(typeOf(source))))
+        return ast;
+    const where = structuredClone(ast.SelectStmt.whereClause), base = ast.SelectStmt.limitCount.ParamRef.number - sources.length, pending = [where];
+    while (pending.length) {
+        const node = pending.pop();
+        if (!node || typeof node !== "object")
+            continue;
+        if (node.ParamRef) {
+            const number = node.ParamRef.number, type = typeOf(sources[number - base - 1]);
+            if (typed(type)) {
+                delete node.ParamRef;
+                node.Raw = { parts: postgres ? ["CAST(CAST(", { ParamRef: { number } }, ` AS text) AS ${type})`] : ["CAST(", { ParamRef: { number } }, " AS INTEGER)"] };
+            }
+        }
+        else
+            pending.push(...Object.values(node));
+    }
+    return { ...ast, SelectStmt: { ...ast.SelectStmt, whereClause: where } };
+}

package/dist/domain/recipes.js

@@ -0,0 +1,24 @@
+const KINDS = new Set(["uid", "admin", "user", "now", "cutoff", "const", "input", "version", "scoped"]);
+/** @internal */
+export function recipesOf(statement, fields, refuse, values) {
+    const field = (bound) => {
+        const name = fields.find(field => field.toLowerCase() === String(bound).toLowerCase());
+        if (name === undefined)
+            refuse(`Input bind '${bound}' has no declared field.`);
+        return name ?? String(bound);
+    };
+    return statement.binds.map(b => {
+        if (!KINDS.has(b.k))
+            refuse(`Bind recipe '${b.k}' needs an explicit native implementation.`);
+        if (b.k === "now" || b.k === "cutoff")
+            values?.add(b.k);
+        if (b.k === "scoped" && b.name !== undefined)
+            return { ...b, name: field(b.name) };
+        if (b.k !== "input")
+            return b;
+        if (b.type === "date" || b.type === "timestamptz")
+            values?.add(b.type === "date" ? "date" : "timestamp");
+        // only a date-time, a date or JSON is converted at bind time (`encode` in kernel/binds)
+        return { k: "input", name: field(b.name), ...(b.type === "timestamptz" || b.type === "date" || b.type === "json" ? { type: b.type } : {}) };
+    });
+}

package/dist/domain/userReferences.js

@@ -0,0 +1,5 @@
+/** Conditional capability imports keep applications without user references unchanged. */
+export function userReferences(plan, sqlite) {
+    const used = !!plan.access;
+    return { used, code: used ? `import * as USER from "@aotter/mantle/user-fields";\nconst USER_VALUES = { scopeInsert: USER.scopeInsert, scopedAll: USER.scopedAll, userRefs: USER.userRefs(${sqlite}, 1) };` : '', values: used ? '...USER_VALUES' : '' };
+}

package/dist/domain/wireScalars.js

@@ -0,0 +1,47 @@
+import { declaredType } from "./columns.js";
+const raw = (...parts) => ({ Raw: { parts } });
+/** Temporal SQL forms, plus selected integer text before driver rounding. */
+const wire = (type, d, v, boundary = false) => type === "timestamptz" ? raw(...d.wireTimestamp(v)) : type === "date" ? raw(...d.wireDate(v)) : boundary && type && ["integer", "int8", "int4"].includes(type) ? raw("CAST(", v, " AS text)") : undefined;
+/**
+ * Formats declared temporal outputs and selected integers in a View's top-level SELECT, preserving names.
+ * Returns a refusal when the outputs cannot be matched to SELECT items by position.
+ */
+export function wireScalars(ast, keys, types, d, boundary = false) {
+    if (!types.some(type => type === "timestamptz" || type === "date" || boundary && type && ["integer", "int8", "int4"].includes(type)) || !ast.SelectStmt)
+        return ast;
+    const select = (s) => {
+        if (s.op && s.op !== "SETOP_NONE") {
+            const larg = select(s.larg), rarg = select(s.rarg);
+            return typeof larg === "string" ? larg : typeof rarg === "string" ? rarg : { ...s, larg, rarg };
+        }
+        if (s.targetList?.length !== keys.length || s.targetList.some((t) => !t.ResTarget || t.ResTarget.val?.ColumnRef?.fields?.at(-1)?.A_Star))
+            return "Declared timestamp and date outputs need one SELECT item per output. Expand the SELECT list explicitly.";
+        return { ...s, targetList: s.targetList.map((t, i) => {
+                const val = wire(types[i], d, t.ResTarget.val, boundary);
+                return val ? { ResTarget: { ...t.ResTarget, name: keys[i], val } } : t;
+            }) };
+    };
+    const out = select(ast.SelectStmt);
+    return typeof out === "string" ? out : { ...ast, SelectStmt: out };
+}
+/** The same wire form for a write's RETURNING list (Core has already expanded `*`): a column of the written table is wrapped by its declared type. */
+export function wireReturning(ast, schemas, d, boundary = false) {
+    const [kind, stmt] = Object.entries(ast)[0] ?? [];
+    const list = stmt?.returningClause?.exprs;
+    if (!list?.length || !["InsertStmt", "UpdateStmt", "DeleteStmt"].includes(kind))
+        return ast;
+    const schema = schemas[stmt.relation?.relname];
+    if (!schema)
+        return ast;
+    let changed = false;
+    const exprs = [];
+    for (const t of list) {
+        const fields = t.ResTarget?.val?.ColumnRef?.fields;
+        const col = fields?.at(-1)?.String?.sval;
+        const val = col === undefined ? undefined : wire(declaredType(schema.fields, col), d, t.ResTarget.val, boundary);
+        if (val)
+            changed = true;
+        exprs.push(val ? { ResTarget: { ...t.ResTarget, name: t.ResTarget.name ?? col, val } } : t);
+    }
+    return changed ? { [kind]: { ...stmt, returningClause: { ...stmt.returningClause, exprs } } } : ast;
+}

package/dist/infrastructure/adminEntries.js

@@ -0,0 +1,153 @@
+/** Selected Admin queries/procedures: Core checks, rewrites and prints every native fragment at generation. */
+import { enumOptions, protectedColumns } from "../build/compiler.js";
+import { parsePgSql } from "../build/compiler.js";
+import { compileProgram } from "../build/compiler.js";
+import { adminOrder } from "../domain/adminOrder.js";
+import { declaredType, serverOwned } from "../domain/columns.js";
+import { wireScalars, wireReturning } from "../domain/wireScalars.js";
+import { recipesOf } from "../domain/recipes.js";
+const ref = (...names) => ({ ColumnRef: { fields: names.map(sval => ({ String: { sval } })) } });
+const op = (lexpr, rexpr) => ({ A_Expr: { kind: "AEXPR_OP", name: [{ String: { sval: "=" } }], lexpr, rexpr } });
+const and = (...args) => args.length === 1 ? args[0] : { BoolExpr: { boolop: "AND_EXPR", args } };
+const system = (s) => ["id", "version", "created_at", "updated_at", "author_id", ...(s.publishing ? ["status", "published_at"] : [])];
+const fields = (s) => Object.keys(s.fields).filter(f => f !== s.scope).flatMap(f => s.fields[f] === "geo" ? [f + "_lat", f + "_lng"] : [f]);
+export async function adminEntries(plan, dialect, wire, refusals) {
+    const result = Object.create(null), postgres = !!dialect.nativeOrder;
+    const tableNames = new Set(Object.keys(plan.schemas).map(name => name.toLowerCase()));
+    let rowsName = "_mantle_admin_rows";
+    while (tableNames.has(rowsName.toLowerCase()))
+        rowsName += "_";
+    const rowsAlias = { name: rowsName, sql: wire.ident(rowsName) };
+    const parse = async (sql) => { const { stmts } = await parsePgSql(sql); const visit = (n) => { if (n.RangeVar)
+        n.RangeVar.mantle = "table"; for (const value of Object.values(n))
+        if (value && typeof value === "object")
+            Array.isArray(value) ? value.forEach(visit) : visit(value); }; stmts.forEach(visit); return stmts; };
+    const print = (ast) => dialect.print(ast, plan.schemas);
+    const expr = (value) => print({ SelectStmt: { targetList: [{ ResTarget: { val: value } }], op: "SETOP_NONE", limitOption: "LIMIT_OPTION_DEFAULT" } }).replace(/^SELECT /, "");
+    for (const s of Object.values(plan.schemas))
+        try {
+            const columns = [...system(s), ...fields(s)], writable = Object.keys(s.fields).filter(f => f !== s.scope && s.fields[f] !== "geo");
+            const parent = s.translates && plan.schemas[s.translates.parent.toLowerCase()];
+            const types = columns.map(f => declaredType(s.fields, f) ?? (f === "version" ? "integer" : f.endsWith("_lat") || f.endsWith("_lng") ? "real" : "text"));
+            // Compiler scope names belong only to relations this generated query can reference.
+            const schemas = Object.create(null);
+            let relation = s;
+            while (relation && !Object.hasOwn(schemas, relation.name)) {
+                schemas[relation.name] = relation;
+                relation = relation.translates ? plan.schemas[relation.translates.parent.toLowerCase()] : undefined;
+            }
+            const ctx = (kind, trusted, inputs) => ({ dialect, schemas, inputs, kind, mode: trusted ? "trusted" : "admin", uncheckedRefs: true });
+            const select = `SELECT ${columns.map(c => `${wire.ident(s.name)}.${wire.ident(c)}`).join(",")} FROM ${wire.ident(s.name)}`;
+            const base = await parse(select);
+            const project = (ast, names, keys) => {
+                const projected = wireScalars(ast, [...names, ...keys.map((_, i) => `_k${i}`)], [...names.map(n => types[columns.indexOf(n)] ?? (parent ? declaredType(parent.fields, n) : undefined)), ...keys], wire, true);
+                if (typeof projected === "string")
+                    throw Error(projected);
+                return projected;
+            };
+            let marker = 32767;
+            const authored = JSON.stringify([plan.schemas, s]);
+            while (authored.includes(String(marker)))
+                marker++;
+            const markerText = wire.param(marker);
+            const usedNames = new Set([...columns, ...(parent ? fields(parent) : [])].map(name => name.toLowerCase()));
+            const cursorAliases = [0, 1].map(i => { let name = "_mantle_admin_key" + i; while (usedNames.has(name.toLowerCase()))
+                name += "_"; usedNames.add(name.toLowerCase()); return { name, sql: wire.ident(name) }; });
+            const ordered = adminOrder(s), fieldFacts = Object.create(null);
+            for (const column of [...system(s), ...writable]) {
+                const type = declaredType(s.fields, column) ?? (column === "version" ? "integer" : "text");
+                if (!["text", "integer", "int4", "int8", "real", "float8", "bool", "date", "timestamptz"].includes(type))
+                    continue;
+                const expression = wire.ident(s.name) + "." + wire.ident(column), [kind, nullable] = (Object.hasOwn(ordered, column) ? ordered[column] : undefined) ?? [];
+                fieldFacts[column] = { expression, value: wire.cast(markerText, type), wire: kind && ["integer", "int8", "int4"].includes(type) ? `CAST(${expression} AS text)` : kind && type === "date" ? wire.wireDate(expression).join("") : kind && type === "timestamptz" ? wire.wireTimestamp(expression).join("") : expression, nullable: nullable ?? true, ...(kind ? { kind } : {}) };
+            }
+            const filter = s.uiSchema?.list?.filterField, enums = enumOptions(filter ? s.schema.properties?.[filter] : undefined)?.map(choice => choice.value);
+            const literal = (v) => "'" + v.replaceAll("'", "''") + "'";
+            let subtype = "NULL", option = 0;
+            if (filter && enums?.length) {
+                const type = s.fields[filter.toLowerCase()], temporal = type === "date" || type === "timestamptz";
+                try {
+                    subtype = "CASE " + enums.map((value, index) => {
+                        option = index;
+                        if (postgres && temporal && /^0000-/.test(value.trim()))
+                            throw Error("PostgreSQL requires a nonzero year.");
+                        const native = type === "date" ? wire.date(value) : type === "timestamptz" ? wire.timestamp(value) : value;
+                        return `WHEN ${wire.ident(s.name)}.${wire.ident(filter.toLowerCase())} = ${typeof native === "number" ? String(native) : wire.cast(literal(String(native)), type ?? "")} THEN ${literal(value)}`;
+                    }).join(" ") + " ELSE NULL END";
+                }
+                catch {
+                    throw Object.assign(Error(`Statistics filter option must be a valid ${type ?? "string"}${postgres && temporal ? " with a nonzero PostgreSQL year" : ""}.`), { path: `schemas/${s.name}/admin/statistics/${filter}/${option}` });
+                }
+            }
+            const modes = await Promise.all([false, true].map(async (trusted) => {
+                const [compiled] = compileProgram(base, ctx("view", trusted, {}));
+                if (!compiled)
+                    throw Error("Missing compiled collection View.");
+                // Keep the compiler's verified policy, but share the physical SELECT template at requests.
+                const baseInner = compiled.ast.SelectStmt.fromClause[0].RangeSubselect.subquery.SelectStmt, policy = baseInner.whereClause;
+                compiled.ast.SelectStmt.fromClause = [baseInner.fromClause[0]];
+                // The native merge is a scalar-id lookup, never a fanning join. Core owns both sides' visibility.
+                if (parent) {
+                    const own = new Set(Object.keys(s.fields).flatMap(f => s.fields[f] === "geo" ? [f + "_lat", f + "_lng"] : [f]));
+                    const inherited = fields(parent).filter(f => !own.has(f)), on = s.translates.on.toLowerCase(), alias = "_mantle_merge";
+                    const [pc] = compileProgram(await parse(`SELECT id FROM ${wire.ident(parent.name)} ORDER BY created_at DESC,id DESC LIMIT 1`), ctx("view", trusted, {}));
+                    if (!pc)
+                        throw Error("Missing compiled parent View.");
+                    const renumber = (n) => { if (n.ParamRef)
+                        n.ParamRef.number += compiled.binds.length; for (const v of Object.values(n))
+                        if (v && typeof v === "object")
+                            Array.isArray(v) ? v.forEach(renumber) : renumber(v); };
+                    renumber(pc.ast);
+                    const inner = pc.ast.SelectStmt.fromClause[0].RangeSubselect.subquery.SelectStmt;
+                    pc.ast.SelectStmt.fromClause = inner.fromClause;
+                    pc.ast.SelectStmt.whereClause = and(...(inner.whereClause ? [inner.whereClause] : []), op(ref(parent.name, on), ref(s.name, on)), ...(parent.scope ? [op(ref(parent.name, parent.scope), ref(s.name, s.scope))] : []));
+                    compiled.binds.push(...pc.binds);
+                    const relation = { RangeVar: { relname: parent.name, alias: { aliasname: alias }, mantle: "system", inh: true, relpersistence: "p" } };
+                    compiled.ast.SelectStmt.fromClause = [{ JoinExpr: { jointype: "JOIN_LEFT", larg: compiled.ast.SelectStmt.fromClause[0], rarg: relation, quals: op(ref(alias, "id"), { SubLink: { subLinkType: "EXPR_SUBLINK", subselect: pc.ast } }) } }];
+                    compiled.ast.SelectStmt.targetList.push(...inherited.map(f => ({ ResTarget: { name: f, val: ref(alias, f) } })));
+                }
+                const names = compiled.ast.SelectStmt.targetList.map((t) => t.ResTarget.name ?? t.ResTarget.val.ColumnRef.fields.at(-1).String.sval);
+                const projection = print(project({ SelectStmt: { targetList: compiled.ast.SelectStmt.targetList, op: "SETOP_NONE", limitOption: "LIMIT_OPTION_DEFAULT" } }, names, [])).replace(/^SELECT /, "");
+                const from = print({ SelectStmt: { ...compiled.ast.SelectStmt, targetList: [{ ResTarget: { val: { A_Const: { ival: { ival: 1 } } } } }] } }).replace(/^SELECT 1/, "");
+                // Core compiles all writable fields once; request-time work selects only generated fragments.
+                const inputs = { ...Object.fromEntries(writable.map(f => [f, s.fields[f]])), id: "text" };
+                const returning = columns.map(wire.ident).join(",");
+                const insertAst = writable.length ? (await parse(`INSERT INTO ${wire.ident(s.name)} (${writable.map(wire.ident).join(",")}) VALUES (${writable.map(f => `input.${wire.ident(f)}`).join(",")}) RETURNING ${returning}`))[0] : { InsertStmt: { relation: { RangeVar: { relname: s.name, mantle: "table", inh: true, relpersistence: "p" } }.RangeVar, cols: [], selectStmt: { SelectStmt: { valuesLists: [{ List: { items: [] } }] } }, returningClause: { exprs: columns.map(f => ({ ResTarget: { val: ref(f) } })) } } };
+                const updateFields = writable.filter(field => !protectedColumns(s).includes(field));
+                const updateAst = (await parse(`UPDATE ${wire.ident(s.name)} SET ${updateFields.length ? updateFields.map(f => `${wire.ident(f)}=input.${wire.ident(f)}`).join(",") : "id=input.id"} WHERE id=input.id RETURNING ${returning}`))[0];
+                if (!updateFields.length)
+                    updateAst.UpdateStmt.targetList = [];
+                const deleteAst = (await parse(`DELETE FROM ${wire.ident(s.name)} WHERE id=input.id RETURNING id`))[0];
+                const write = (ast) => {
+                    const [c] = compileProgram([ast], { ...ctx("procedure", trusted || !!(s.userScopes?.length && ast.InsertStmt), inputs), lockVersion: true });
+                    if (!c || c.kind !== "row")
+                        throw Error("Admin writes must affect exactly one row.");
+                    const fixed = c.binds.filter(b => !(b.k === "input" && writable.includes(String(b.name)))), rewritten = wireReturning(c.ast, plan.schemas, wire, true);
+                    const rewrite = (n) => { if (n.ParamRef) {
+                        const b = c.binds[n.ParamRef.number - 1];
+                        if (b.k === "input" && writable.includes(String(b.name))) {
+                            delete n.ParamRef;
+                            n.Raw = { parts: [wire.cast(markerText, String(b.type))] };
+                            return;
+                        }
+                        n.ParamRef.number = fixed.indexOf(b) + 1;
+                    } for (const v of Object.values(n))
+                        if (v && typeof v === "object")
+                            Array.isArray(v) ? v.forEach(rewrite) : rewrite(v); };
+                    rewrite(rewritten);
+                    return { ast: rewritten, binds: recipesOf({ binds: fixed }, ["id"], message => { throw Error(message); }) };
+                };
+                const create = write(insertAst), patch = write(updateAst), remove = write(deleteAst), entryFields = Object.create(null);
+                const insert = create.ast.InsertStmt, update = patch.ast.UpdateStmt;
+                for (const [i, field] of writable.entries())
+                    entryFields[field] = { column: wire.ident(field), insert: expr(insert.selectStmt.SelectStmt.fromClause[0].RangeSubselect.subquery.SelectStmt.valuesLists[0].List.items[i]), ...(!protectedColumns(s).includes(field) && !serverOwned(s.schema, field) ? { update: wire.ident(field) + " = " + expr(update.targetList[updateFields.indexOf(field)].ResTarget.val) } : {}) };
+                const returnSQL = (ast) => " RETURNING " + ast.returningClause.exprs.map((t) => expr(t.ResTarget.val) + (t.ResTarget.name ? " AS " + wire.ident(t.ResTarget.name) : "")).join(",");
+                return { projection, from, policy: policy ? expr(policy) : "", binds: recipesOf(compiled, [], message => { throw Error(message); }), fields: entryFields, create: { prefix: print(create.ast).slice(0, print(create.ast).indexOf(" (")) + " (", between: ") VALUES (", suffix: ")", binds: create.binds, columns: insert.cols.slice(writable.length).map((t) => wire.ident(t.ResTarget.name)), values: insert.selectStmt.SelectStmt.targetList.slice(writable.length ? 1 : 0).map((t) => expr(t.ResTarget.val)), returning: returnSQL(insert) }, patch: { prefix: print(patch.ast).slice(0, print(patch.ast).indexOf(" SET ")) + " SET ", binds: patch.binds, sets: update.targetList.slice(updateFields.length).map((t) => wire.ident(t.ResTarget.name) + " = " + expr(t.ResTarget.val)), where: " WHERE " + expr(update.whereClause), returning: returnSQL(update) }, remove: { sql: print(remove.ast), binds: remove.binds, row: true } };
+            }));
+            result[s.name] = { ...(s.userScopes?.length ? { userScopes: s.userScopes } : {}), cursorAliases, scoped: !!s.scope, path: "schemas/" + s.name + "/admin", marker: markerText, id: wire.ident(s.name) + "." + wire.ident("id"), fields: fieldFacts, orderFields: Object.keys(ordered), search: `(${wire.ident(s.name)}.${wire.ident("id")} = ${markerText}${s.search?.length ? ` OR ${wire.search(s.name, s.search, wire.ident(s.name), markerText)}` : ""})`, statistics: { rowsAlias, column: wire.ident(s.name) + "." + wire.ident("created_at"), time: postgres ? `extract(epoch FROM ${wire.ident(s.name)}.${wire.ident("created_at")}) * 1000000` : wire.ident(s.name) + "." + wire.ident("created_at"), subtype }, caller: modes[0], trusted: modes[1] };
+        }
+        catch (error) {
+            refusals.push({ code: "GENERATE_UNSUPPORTED", path: error instanceof Error && "path" in error && typeof error.path === "string" ? error.path : "schemas/" + s.name + "/admin", message: error instanceof Error ? error.message : String(error) });
+        }
+    return result;
+}