@aotter/mantle 0.2.0-alpha.6 → 0.2.0-alpha.8

package/dist/infrastructure/generate.js

@@ -0,0 +1,174 @@
+import { describeApp } from "../domain/describe/index.js";
+/** Build-time assembly only. None of these imports enter generated applications. */
+import { compilePlan, viewOutputs, sqliteCompiler, postgresCompiler, d1Dialect, postgresDialect, lowerPlan, sqliteSchema, postgresSchema } from "../build/compiler.js";
+import { wireReturning, wireScalars } from "../domain/wireScalars.js";
+import { boundaryType, outputType } from "../domain/columns.js";
+import { castCursor, provePaging } from "../domain/paging.js";
+import { dialect as sqliteDialect } from "../kernel/dialect/sqlite.js";
+import { cast, dialect as postgresDialect_ } from "../kernel/dialect/postgres.js";
+import { adminBindingsOf } from "./adminPaging.js";
+import { adminIndexes } from "../domain/adminOrder.js";
+import { publishingSql } from "../usecase/publishing.js";
+import { searchDiagnostics } from "../usecase/search.js";
+import { generate } from "../usecase/generate.js";
+import { generatedFiles } from "../domain/entry.js";
+/** Core's own new-entry-id lowering for a dialect, printed once as an SQL expression: the Store's inserts carry the same one its compiled INSERTs do. */
+export const coreNewId = (dialect, schemas) => dialect.print({ SelectStmt: { targetList: [{ ResTarget: { val: dialect.lowering.newId() } }], limitOption: "LIMIT_OPTION_DEFAULT", op: "SETOP_NONE" } }, schemas).replace(/^SELECT /, "");
+// JSON, date-time and date inputs are driver-ready text. Declaring their parameter as text makes every driver send it verbatim:
+// Bun.SQL would JSON-encode a string bound to jsonb a second time, and postgres.js turns one bound to timestamptz or date into a
+// JavaScript Date, which loses microseconds. Core prints `CAST($n AS <type>)`; the PostgreSQL dialect spells what replaces it (the
+// same cast the Store writes with). Any other use of such a parameter is refused.
+const CORE_CAST = { json: "jsonb", timestamptz: "timestamptz", date: "date" };
+function castInputs(statement, path, refusals) {
+    let sql = statement.sql;
+    for (const [i, b] of statement.binds.entries()) {
+        const type = b.k === "input" ? String(b.type) : "", target = CORE_CAST[type];
+        if (!target)
+            continue;
+        const param = `$${i + 1}`, core = `CAST(${param} AS ${target})`;
+        if (sql.split(core).join("").match(new RegExp(`\\$${i + 1}(?!\\d)`)))
+            refusals.push({ code: "GENERATE_UNSUPPORTED", path, message: `Input ${param} must appear only as ${core}. Wrap each occurrence in ${core}.` });
+        sql = sql.replaceAll(core, cast(param, type));
+    }
+    Object.assign(statement, { sql });
+}
+/** Operational records are added in Admin only through a Procedure placed with `uiSchema.collectionAction`; name the Schemas left without one. */
+function adminCreateWarnings(plan) {
+    const placed = new Set(Object.values(plan.procedures).map(p => p.uiSchema?.["collectionAction"]).filter((name) => typeof name === "string").map(name => name.toLowerCase()));
+    return Object.values(plan.schemas).filter(s => {
+        const required = new Set(s.schema.required ?? []);
+        // Folded children open from their parent; translations from their language tabs.
+        const folded = Object.entries(s.schema.properties ?? {}).some(([name, property]) => required.has(name) && typeof property?.["x-mantle-ref"] === "string");
+        // Field-scoped rows belong to their members, who create them.
+        return !s.publishing && s.schema.readOnly !== true && !s.scope && !s.translates && !folded && !placed.has(s.name.toLowerCase());
+    }).map(s => `Schema '${s.name}' is operational and writable, but no Procedure places a create action on it, so Admin cannot add its records. Add a Procedure with uiSchema.collectionAction: ${s.name} and an admin MCP Trigger, or mark the Schema readOnly.`).concat(Object.values(plan.schemas).flatMap(s => Object.entries(s.schema.properties ?? {})
+        .filter(([name, property]) => property?.readOnly === true && (s.schema.required ?? []).includes(name) && property.default === undefined)
+        .map(([name]) => `Schema '${s.name}' field '${name}' is required and readOnly without a default, so Admin cannot create its records. Give it a default (Admin stores it on create).`)));
+}
+/** Warn about SQL's case folding without changing the authored output names. */
+function outputNameWarnings(plan) {
+    const warnings = [];
+    const inspect = (kind, name, stmts) => {
+        for (const stmt of stmts) {
+            const select = stmt.SelectStmt, write = stmt.InsertStmt ?? stmt.UpdateStmt ?? stmt.DeleteStmt;
+            const targets = kind === "View" ? select?.targetList : write?.returningClause?.exprs;
+            const relations = new Map();
+            const from = (node) => {
+                if (node.JoinExpr) {
+                    from(node.JoinExpr.larg);
+                    from(node.JoinExpr.rarg);
+                    return;
+                }
+                const r = node.RangeVar ?? node;
+                if (r.relname)
+                    relations.set(r.alias?.aliasname ?? r.relname, r.mantle === "table" ? r.relname : undefined);
+            };
+            if (write)
+                from(write.relation);
+            for (const node of select?.fromClause ?? write?.fromClause ?? write?.usingClause ?? [])
+                from(node);
+            for (const { ResTarget: target } of targets ?? []) {
+                const refs = target.val?.ColumnRef?.fields;
+                if (target.name || !refs?.every((ref) => ref.String) || refs.length > 2)
+                    continue;
+                const column = refs.at(-1).String.sval;
+                const candidates = refs.length === 2 ? [relations.get(refs[0].String.sval)] : [...relations.values()].filter(schema => schema && plan.schemas[schema]?.fields[column]);
+                if (candidates.length !== 1 || !candidates[0])
+                    continue;
+                const declared = plan.schemas[candidates[0]]?.names?.[column];
+                if (declared && declared !== column) {
+                    const reference = refs.length === 2 ? `${refs[0].String.sval}.${declared}` : declared;
+                    warnings.push(`${kind} '${name}' field '${declared}' outputs storage name '${column}'; use ${reference} AS "${declared}" to preserve the declared name.`);
+                }
+            }
+        }
+    };
+    for (const [name, view] of Object.entries(plan.views))
+        inspect("View", name, view.stmts);
+    for (const [name, procedure] of Object.entries(plan.procedures))
+        if ("sql" in procedure.handler)
+            inspect("Procedure", name, procedure.handler.sql.stmts);
+    return [...new Set(warnings)];
+}
+export async function generateFromSources(request, schema) {
+    const postgres = request.target.endsWith("postgres");
+    const compiler = postgres ? postgresCompiler : sqliteCompiler;
+    const compiled = await compilePlan(request.sources, compiler, "operational");
+    if (!compiled.ok)
+        return { ok: false, diagnostics: compiled.diagnostics.map(({ code, path, message }) => ({ code, path, message })) };
+    const dialect = postgres ? postgresDialect() : d1Dialect;
+    const wire = postgres ? postgresDialect_ : sqliteDialect;
+    const viewKeys = Object.fromEntries(Object.entries(compiled.plan.views).map(([name, view]) => {
+        const output = viewOutputs(view, compiled.plan.schemas);
+        return [name, output.positions?.length === output.keys?.length ? output.keys : undefined];
+    }));
+    const refusals = [], paging = {};
+    const lower = (boundary) => lowerPlan(compiled.plan, dialect, {
+        pageQuery(ast, name) {
+            // Core visits public/caller before trusted. Prove the real caller equality prefixes;
+            // a trusted all-scope read does not acquire a fictional scope predicate.
+            if (!Object.hasOwn(paging, name))
+                paging[name] = provePaging(compiled.plan, ast);
+            return ast;
+        },
+        project(ast, kind, name, page) {
+            if (kind === "procedure")
+                return wireReturning(ast, compiled.plan.schemas, wire);
+            if (page && !page.flat)
+                ast = castCursor(ast, page.sources, paging[name]?.types ?? [], postgres);
+            const keys = page && !page.flat ? [...page.names, ...Array.from({ length: page.nkeys }, (_, i) => `_k${i}`)] : viewKeys[name];
+            if (!keys)
+                return ast;
+            const types = page && !page.flat ? [...page.names.map(key => boundaryType(compiled.plan, name, key)), ...(paging[name]?.types ?? [])] : keys.map(key => page ? boundaryType(compiled.plan, name, key) : outputType(compiled.plan, name, key));
+            let projected = wireScalars(ast, keys, types, wire, boundary && !!page);
+            if (typeof projected !== "string" && page && !page.flat && !boundary)
+                projected = wireScalars(projected, keys, [...page.names.map(() => undefined), ...(paging[name]?.types ?? []).map(type => ["integer", "int8", "int4"].includes(type) ? type : undefined)], wire, true);
+            if (typeof projected !== "string")
+                return projected;
+            refusals.push({ code: "GENERATE_UNSUPPORTED", path: `views/${name}`, message: projected });
+            return ast;
+        },
+    });
+    const { lowered, warnings } = lower(false);
+    const wireLowered = lower(true).lowered;
+    if (postgres) {
+        const seen = new Set();
+        const plans = [lowered, wireLowered];
+        for (const plan of plans)
+            for (const [kind, all] of [["views", plan.views], ["procedures", plan.procedures]])
+                for (const [name, modes] of Object.entries(all)) {
+                    for (const statement of Object.values(modes).flat())
+                        if (!seen.has(statement)) {
+                            seen.add(statement);
+                            castInputs(statement, `${kind}/${name}`, refusals);
+                            if ("paged" in statement)
+                                for (const page of Object.values(statement.paged)) {
+                                    const inputPage = { ...statement, sql: page.sql };
+                                    castInputs(inputPage, `${kind}/${name}`, refusals);
+                                    Object.assign(page, { sql: inputPage.sql });
+                                }
+                        }
+                }
+    }
+    const searchProblems = searchDiagnostics(warnings);
+    refusals.push(...searchProblems);
+    const adminReads = request.admin ? await adminBindingsOf(compiled.plan, dialect, paging, wire, refusals) : undefined;
+    const { adminPages, adminEntries } = adminReads ?? {};
+    const report = await describeApp(compiled.plan);
+    const result = generate({ description: report, target: request.target, admin: request.admin, adminPages, adminEntries, site: request.site, plan: compiled.plan, lowered, wireLowered, viewKeys, newId: coreNewId(dialect, compiled.plan.schemas), paging });
+    if (refusals.length) {
+        const diagnostics = result.ok ? [] : result.diagnostics.filter(d => !searchProblems.some(p => p.path === d.path) ||
+            !["Every reachable visibility mode must have canonical lowered SQL.", "Both caller and trusted SQL must be lowered."].includes(d.message));
+        return { ok: false, diagnostics: [...refusals, ...diagnostics] };
+    }
+    if (!result.ok)
+        return result;
+    const accessTargets = Object.fromEntries(report.targets.map(({ _meta: m }) => {
+        const policy = ({ opaque, requires }) => ({ opaque, ...(requires.guard ? { guard: requires.guard } : {}) });
+        return [m.id, { targetHash: m.targetHash, ...policy(m), ...(m.variants.length ? { variants: m.variants.map(v => ({ id: v.id, ...policy(v) })) } : {}) }];
+    }));
+    const gatewayFiles = generatedFiles({ "access-targets.ts": `import type { AccessTarget } from "@aotter/mantle/contracts";\nexport const targets: Readonly<Record<string, AccessTarget>> = ${JSON.stringify(accessTargets)};\n` });
+    const ddl = [...(postgres ? postgresSchema : sqliteSchema)(compiled.plan.schemas), ...publishingSql(compiled.plan.schemas, !postgres), ...(request.admin ? adminIndexes(compiled.plan.schemas, !postgres) : []), ...(schema?.() ?? [])];
+    const { "site-schema.sql": siteSql = "", ...files } = result.files;
+    return { ...result, warnings: [...outputNameWarnings(compiled.plan), ...(request.admin ? adminCreateWarnings(compiled.plan) : []), ...(compiled.plan.access?.warnings ?? [])], files: { ...files, ...gatewayFiles, ...generatedFiles({ "schema.sql": ddl.join(";\n\n") + ";\n" + siteSql }) } };
+}

package/dist/infrastructure/generateAuth.d.ts

@@ -0,0 +1,8 @@
+/** Selected Auth generation; the compiler and request DTO remain shared with the bare entry. */
+import type { BetterAuthOptions } from "better-auth/types";
+import { type GenerateRequest } from "./generate.js";
+/** One or more Better Auth instances (each with its own table names); their DDL is merged. */
+export declare function generateFromSources(request: GenerateRequest & {
+    readonly auth?: BetterAuthOptions | readonly BetterAuthOptions[];
+}): Promise<import("../domain/generation.js").GenerateResult>;
+export type { GenerateRequest } from "./generate.js";

package/dist/infrastructure/generateAuth.js

@@ -0,0 +1,23 @@
+import { generateFromSources as generate } from "./generate.js";
+import { authSchemaSql } from "./authSchema.js";
+/** One or more Better Auth instances (each with its own table names); their DDL is merged. */
+export function generateFromSources(request) {
+    const instances = request.auth ? [request.auth].flat() : [];
+    return generate(request, instances.length ? () => authSql(instances, request.target.endsWith("postgres") ? "postgres" : "sqlite") : undefined);
+}
+function authSql(instances, dialect) {
+    for (const options of instances) {
+        const ids = (options.plugins ?? []).map(plugin => plugin.id);
+        // Offline OAuth grants outlive sessions; without the revocation plugin a password reset or ban would not end them. mcp() spreads oauthProvider, id included.
+        if (ids.includes("oauth-provider") && !ids.includes("mantle-oauth-grant-revocation") /* oauthGrantRevocation().id */)
+            throw new Error("Better Auth has an OAuth provider (oauthProvider or mcp) without oauthGrantRevocation(): add it from @aotter/mantle/auth/oauth to the plugins, so a password reset, an admin ban or session revocation ends that user's OAuth grants.");
+    }
+    const statements = [...new Set(instances.flatMap(options => authSchemaSql(options, dialect)))];
+    // CREATE TABLE IF NOT EXISTS would silently keep the first of two different definitions.
+    // Identical statements are already merged, so a repeated table name means two different definitions.
+    const tables = statements.map(statement => /^CREATE TABLE IF NOT EXISTS ("(?:[^"]|"")+")/.exec(statement)?.[1]).filter(Boolean);
+    const twice = tables.find((table, i) => tables.indexOf(table) !== i);
+    if (twice)
+        throw new Error(`Better Auth instances define table ${twice} differently; give each instance its own table names (user.modelName, session.modelName, ...).`);
+    return statements;
+}

package/dist/infrastructure/inputs.js

@@ -0,0 +1,41 @@
+/** `mantle generate` fingerprints its inputs next to the output; `mantle bundle` refuses output whose inputs changed since. */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+export const INPUTS_FILE = ".mantle-inputs.json";
+/** The installed `@aotter/mantle` version (dist/infrastructure → package root). */
+const MANTLE_VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+// Line endings are normalized so a CRLF checkout (core.autocrlf) matches the LF fingerprint.
+const digest = (path) => existsSync(path) ? createHash("sha256").update(readFileSync(path, "utf8").replaceAll("\r\n", "\n")).digest("hex") : null;
+/** The target and the manifests and option modules (`--auth`, `--site`) one generate run read, by path relative to its output. */
+export function inputsFingerprint(destination, paths, target) {
+    const inputs = Object.fromEntries(paths.map(path => [relative(resolve(destination), resolve(path)).replaceAll("\\", "/"), digest(path)]));
+    return JSON.stringify({ mantle: MANTLE_VERSION, target, inputs }, null, 2) + "\n";
+}
+/** The generate target recorded beside `generatedModule` (undefined without a fingerprint, or one written before targets were recorded). */
+export function generatedTarget(generatedModule) {
+    const file = resolve(dirname(generatedModule), INPUTS_FILE);
+    return existsSync(file) ? JSON.parse(readFileSync(file, "utf8")).target : undefined;
+}
+/** Why the generated output that holds `generatedModule` no longer matches its inputs (empty when it does, or when it has no fingerprint). */
+export function staleInputs(generatedModule) {
+    const directory = dirname(generatedModule), file = resolve(directory, INPUTS_FILE);
+    if (!existsSync(file))
+        return [];
+    const recorded = JSON.parse(readFileSync(file, "utf8"));
+    const stale = recorded.mantle === MANTLE_VERSION ? [] : [`generated by Mantle ${recorded.mantle}, building with ${MANTLE_VERSION}`];
+    for (const [path, hash] of Object.entries(recorded.inputs))
+        if (digest(resolve(directory, path)) !== hash)
+            stale.push(`${relative(process.cwd(), resolve(directory, path))} changed`);
+    return stale;
+}
+/** Better Auth roles an app declares beyond `admin` and `user` (`<name>: ac.newRole(...)`), for a one-line design note. */
+export function extraRoles(source) {
+    return [...source.matchAll(/["']?([A-Za-z][\w-]*)["']?\s*:\s*ac\.newRole\(/g)].map(m => m[1]).filter(role => role !== "admin" && role !== "user");
+}
+/** Better Auth tables an app's own code queries with SQL (`FROM "user"`, `JOIN session` ...), for a one-line note. */
+export function authTableSql(source) {
+    // Only lines that read like SQL statements, so prose such as "take into account" is not a finding.
+    const sql = source.split("\n").filter(line => /\b(?:SELECT|INSERT|UPDATE|DELETE)\b/.test(line)).join("\n");
+    return [...new Set([...sql.matchAll(/\b(?:FROM|JOIN|UPDATE|INTO)\s+"?(user|session|account|verification)"?(?=[\s;),`'"]|$)/gi)].map(m => m[1].toLowerCase()))];
+}

package/dist/infrastructure/wrangler.js

@@ -0,0 +1,94 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { applyEdits, modify, parse } from "jsonc-parser";
+const requiredFlags = ["nodejs_compat", "global_fetch_strictly_public"];
+/** Newest date the project's installed workerd supports, as create-cloudflare picks it; a fixed date before Wrangler is installed. */
+function compatibilityDate(dir) {
+    try {
+        let from = join(dir, "package.json");
+        for (const name of ["wrangler", "miniflare", "workerd"])
+            from = createRequire(from).resolve(`${name}/package.json`);
+        const [, y, m, d] = /^\d+\.(\d{4})(\d{2})(\d{2})\./.exec(JSON.parse(readFileSync(from, "utf8")).version) ?? [];
+        if (y)
+            return `${y}-${m}-${d}`;
+    }
+    catch { }
+    return "2026-09-28";
+}
+/** `assets`: with `--admin`, the static assets directory `mantle bundle` builds Admin into (`<assets>/admin`). */
+export function configureWrangler(configPath, entry, outdir, generated, check = false, assets, publicFetchRequired = false) {
+    const configDir = dirname(resolve(configPath));
+    const local = (path) => relative(configDir, resolve(path)).replaceAll("\\", "/") || ".";
+    const output = local(outdir);
+    const quote = (arg) => /^[\w./-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", "'\\''")}'`;
+    const worker = `${output}/worker`;
+    const assetsFlag = assets !== undefined && resolve(assets) !== resolve(outdir, "client") ? ` --assets ${quote(assets)}` : "";
+    const keys = {
+        main: `${worker}/${basename(entry).replace(/\.[^.]+$/, "")}.js`, no_bundle: true,
+        find_additional_modules: true, base_dir: worker,
+        rules: [{ type: "ESModule", globs: ["**/*.js"], fallthrough: true }],
+        build: { command: `mantle bundle ${quote(entry)} ${quote(outdir)}${assetsFlag}`, watch_dir: [local(dirname(entry)), local(generated)] },
+    };
+    if (configPath.endsWith(".toml")) {
+        if (check)
+            throw new Error("--check requires a JSON or JSONC Wrangler config; TOML generation only prints manual edits.");
+        console.log(`Leave ${configPath} unchanged. Add these Wrangler TOML keys (include nodejs_compat and global_fetch_strictly_public in every compatibility_flags override):\n` +
+            `main = ${JSON.stringify(keys.main)}\nno_bundle = true\nfind_additional_modules = true\nbase_dir = ${JSON.stringify(worker)}\ncompatibility_flags = ${JSON.stringify(requiredFlags)}\n\n` +
+            (assets === undefined ? "" : `[assets]\ndirectory = ${JSON.stringify(local(assets))}\n\n`) +
+            `[[rules]]\ntype = "ESModule"\nglobs = ["**/*.js"]\nfallthrough = true\n\n[build]\ncommand = ${JSON.stringify(keys.build.command)}\nwatch_dir = ${JSON.stringify(keys.build.watch_dir)}`);
+        return false;
+    }
+    const exists = existsSync(configPath);
+    const original = exists ? readFileSync(configPath, "utf8") : JSON.stringify({ name: "your-worker-name", compatibility_date: compatibilityDate(configDir) }, null, 2) + "\n";
+    let text = original;
+    const errors = [];
+    const config = parse(text, errors, { allowTrailingComma: true });
+    if (errors.length || !config || typeof config !== "object" || Array.isArray(config))
+        throw new Error(`${configPath} must be a valid JSONC object.`);
+    const indent = text.match(/\n([ \t]+)"/)?.[1] ?? "  ";
+    const formattingOptions = { insertSpaces: !indent.includes("\t"), tabSize: indent.length, eol: text.includes("\r\n") ? "\r\n" : "\n" };
+    // Merge, never replace: the user's own module rules and build options survive.
+    const { rules: [rule], build: buildKeys, ...top } = keys;
+    const edit = (path, value) => {
+        if (!isDeepStrictEqual(path.reduce((v, k) => v?.[k], config), value))
+            text = applyEdits(text, modify(text, path, value, { formattingOptions }));
+    };
+    // Public routing is the default; an explicit private origin remains app-owned without OAuth/CIMD.
+    const ensureFlags = (path, flags) => {
+        if (flags !== undefined && (!Array.isArray(flags) || !flags.every(flag => typeof flag === "string")))
+            throw new Error(`${configPath}: ${path.join(".")} must be an array of strings.`);
+        const privateFetch = Array.isArray(flags) && flags.includes("global_fetch_private_origin");
+        if (privateFetch && (publicFetchRequired || flags.includes("global_fetch_strictly_public")))
+            throw new Error(`${configPath}: ${path.join(".")} includes global_fetch_private_origin, which conflicts with public OAuth/CIMD fetch routing. Remove it and use global_fetch_strictly_public.`);
+        const required = privateFetch ? ["nodejs_compat"] : requiredFlags;
+        if (flags === undefined)
+            edit(path, required);
+        else
+            for (const flag of required)
+                if (!flags.includes(flag))
+                    edit([...path, -1], flag);
+    };
+    ensureFlags(["compatibility_flags"], config.compatibility_flags);
+    // Wrangler environment arrays replace the top-level flags rather than inheriting them.
+    for (const [name, environment] of Object.entries(config.env ?? {})) {
+        if (environment?.compatibility_flags !== undefined)
+            ensureFlags(["env", name, "compatibility_flags"], environment.compatibility_flags);
+    }
+    for (const [key, value] of Object.entries(top))
+        edit([key], value);
+    for (const [key, value] of Object.entries(buildKeys))
+        edit(["build", key], value);
+    // Only the directory: the binding, run_worker_first and html_handling stay the application's.
+    if (assets !== undefined)
+        edit(["assets", "directory"], local(assets));
+    if (!(config.rules ?? []).some((r) => isDeepStrictEqual(r, rule)))
+        edit(config.rules === undefined ? ["rules"] : ["rules", -1], config.rules === undefined ? [rule] : rule);
+    const changed = !exists || text !== original;
+    if (changed && !check)
+        writeFileSync(configPath, text);
+    if (!exists && !check)
+        console.log(`Created ${configPath}. Set name and compatibility_date for your Worker, and add your D1/Hyperdrive bindings and other application settings.`);
+    return changed;
+}

package/dist/kernel/authorization.d.ts

@@ -0,0 +1,4 @@
+import { type Authorize, type Target, type Caller } from "./contracts.js";
+/** Rejections deny; synchronous application failures remain internal errors. */
+export declare function authorized(authorize: Authorize, target: Target, caller: Caller): Promise<boolean>;
+export declare function authorizeTarget(authorize: Authorize, target: Target, caller: Caller): Promise<void>;

package/dist/kernel/authorization.js

@@ -0,0 +1,16 @@
+import { ContractError } from "./contracts.js";
+/** Rejections deny; synchronous application failures remain internal errors. */
+export async function authorized(authorize, target, caller) {
+    let result;
+    try {
+        result = authorize(target, caller);
+    }
+    catch (cause) {
+        throw new Error("Authorization failed.", { cause });
+    }
+    return await Promise.resolve(result).catch(() => false) === true;
+}
+export async function authorizeTarget(authorize, target, caller) {
+    if (!await authorized(authorize, target, caller))
+        throw new ContractError("AUTH_DENIED", "Target is not authorized.", target.kind + "/" + target.name);
+}

package/dist/kernel/binds.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Core's bind recipes (`BindSpec` in the policy rewriter), evaluated for one call. Generated Views, generated
+ * Procedures and the Store all bind through this one function. Input recipes carry the authored field name; `version` reads the Store's lock from `input`.
+ */
+import { type Caller } from "./contracts.js";
+import type { Dialect } from "./dialect/common.js";
+export type Recipe = {
+    readonly k: "user";
+    readonly field: string;
+    readonly type: "string" | "number";
+    readonly multiple: boolean;
+    readonly scope?: true;
+} | {
+    readonly k: "uid" | "admin" | "now" | "version";
+} | {
+    readonly k: "cutoff";
+    readonly seconds: number;
+} | {
+    readonly k: "const";
+    readonly value: unknown;
+} | {
+    readonly k: "input";
+    readonly name: string; /** Only a date-time or a date is converted, so only those carry a type. */
+    readonly type?: "timestamptz" | "date";
+};
+/** One printed statement and how to bind it. `row`: it must affect exactly one row. */
+export interface Step {
+    readonly sql: string;
+    readonly binds: readonly Recipe[];
+    readonly row?: boolean;
+}
+export type Bound = {
+    readonly sql: string;
+    readonly binds: unknown[];
+    readonly row?: boolean;
+};
+/** The dialect functions the recipes in use call; generated code passes only those. */
+export type Values = Partial<Pick<Dialect, "now" | "cutoff" | "timestamp" | "date">> & {
+    readonly user?: (recipe: Extract<Recipe, {
+        k: "user";
+    }>, caller: Caller) => unknown;
+    readonly scopeInsert?: Dialect['scopeInsert'];
+    readonly userRefs?: (recipe: Recipe, caller: Caller) => unknown;
+    /** Present only in apps with user fields: keeps, per caller, one printed form of each Schema scope term. */
+    readonly scopedAll?: <T>(value: T, caller: Caller) => T;
+};
+/** A declared date-time or date as the engine stores it; any other value (and `null`) is bound as it is. */
+export declare const encode: (d: Values, type: string | undefined, v: unknown) => unknown;
+export declare function binds(d: Values, recipes: readonly Recipe[], caller: Caller, input?: Readonly<Record<string, unknown>>, ms?: number): unknown[];
+/** Every step's binds, evaluated for a Procedure. */
+export declare function bound(d: Values, steps: readonly Step[], caller: Caller, input?: Readonly<Record<string, unknown>>): Bound[];

package/dist/kernel/binds.js

@@ -0,0 +1,45 @@
+/**
+ * Core's bind recipes (`BindSpec` in the policy rewriter), evaluated for one call. Generated Views, generated
+ * Procedures and the Store all bind through this one function. Input recipes carry the authored field name; `version` reads the Store's lock from `input`.
+ */
+import { deny, isAdmin } from "./contracts.js";
+/** A declared date-time or date as the engine stores it; any other value (and `null`) is bound as it is. */
+export const encode = (d, type, v) => type === "timestamptz" ? (v == null ? null : d.timestamp(v)) : type === "date" ? (v == null ? null : d.date(v)) : v;
+export function binds(d, recipes, caller, input, ms = 0) {
+    const out = [];
+    for (const r of recipes) {
+        switch (r.k) {
+            case "uid":
+                if (caller.kind === "host")
+                    deny(caller, isAdmin(caller), "");
+                out.push("subject" in caller ? caller.subject : caller.kind === "system" ? `system:${caller.reason}` : null);
+                break;
+            case "admin":
+                out.push(isAdmin(caller) ? 1 : 0);
+                break;
+            case "now":
+                out.push(d.now(ms ||= Date.now()));
+                break;
+            case "cutoff":
+                out.push(d.cutoff(ms ||= Date.now(), r.seconds));
+                break;
+            case "const":
+                out.push(r.value);
+                break;
+            case "version":
+                out.push(input.version);
+                break;
+            case "input":
+                out.push(encode(d, r.type, input[r.name]));
+                break;
+            // Only apps whose plan uses caller values import the version-checked capability; it refuses an unknown recipe, and without it this throws before SQL.
+            default: out.push(d.userRefs(r, caller));
+        }
+    }
+    return out;
+}
+/** Every step's binds, evaluated for a Procedure. */
+export function bound(d, steps, caller, input) {
+    const ms = Date.now(); // one clock for the whole Procedure
+    return steps.map(s => ({ sql: s.sql, binds: binds(d, s.binds, caller, input, ms), row: s.row }));
+}

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

@@ -0,0 +1,24 @@
+import type { Caller } from "./contracts.js";
+import type { UserValue } from "./user-fields.js";
+type Identity = {
+    readonly roles: readonly string[];
+    readonly fields: Readonly<Record<string, UserValue>>;
+    readonly admin: boolean;
+    readonly impersonatedBy?: string;
+    readonly host?: true;
+};
+export declare const identities: WeakMap<Caller, Identity>;
+export declare const isHostCaller: (caller: Caller) => boolean;
+export declare const rolesOf: (caller: Caller) => readonly string[];
+export declare const fieldsOf: (caller: Caller) => Readonly<Record<string, UserValue>>;
+export declare const valueFor: (caller: Caller, field: string) => UserValue | undefined;
+export declare const hasRole: (caller: Caller, role: string) => boolean;
+export declare const isAdminCaller: (caller: Caller) => caller is Extract<Caller, {
+    kind: "user" | "host";
+}> & {
+    readonly admin: true;
+};
+export declare function modeOf(caller: Caller): "caller" | "trusted";
+/** Only branded host identities may carry freshness authority. */
+export declare function checkFresh(caller: Caller, readOnly: boolean, target?: string): void;
+export {};

package/dist/kernel/caller-identity.js

@@ -0,0 +1,22 @@
+import { ContractError } from "./contract-error.js";
+export const identities = /* @__PURE__ */ new WeakMap();
+export const isHostCaller = (caller) => identities.get(caller)?.host === true;
+export const rolesOf = (caller) => identities.get(caller)?.roles ?? [];
+// Unbranded callers get a fresh empty map; mutating it cannot grant authority.
+export const fieldsOf = (caller) => identities.get(caller)?.fields ?? {};
+export const valueFor = (caller, field) => identities.get(caller)?.fields[field];
+export const hasRole = (caller, role) => rolesOf(caller).includes(role);
+export const isAdminCaller = (caller) => !!identities.get(caller)?.admin;
+export function modeOf(caller) {
+    const kind = caller.kind;
+    if (kind === 'system')
+        return 'trusted';
+    if (kind === 'user' || kind === 'anonymous' || kind === 'host' && isHostCaller(caller))
+        return 'caller';
+    throw new ContractError('AUTH_DENIED', 'Unknown caller');
+}
+/** Only branded host identities may carry freshness authority. */
+export function checkFresh(caller, readOnly, target) {
+    if (!readOnly && isHostCaller(caller) && "authenticatedAs" in caller && caller.authenticatedAs === "snapshot")
+        throw new ContractError("STALE_CALLER", "Snapshot callers cannot write.", target, { status: 403 });
+}

package/dist/kernel/contract-error.d.ts

@@ -0,0 +1,12 @@
+export declare class ContractError extends Error {
+    readonly code: string;
+    readonly path: string;
+    /** HTTP status for codes outside the core set `statusOf` maps. */
+    readonly status?: number;
+    /** Extra wire fields, after `code`, `message` and `path`. */
+    readonly fields?: Record<string, unknown>;
+    constructor(code: string, message: string, path?: string, options?: ErrorOptions & {
+        status?: number;
+        fields?: Record<string, unknown>;
+    });
+}

package/dist/kernel/contract-error.js

@@ -0,0 +1,14 @@
+export class ContractError extends Error {
+    code;
+    path;
+    constructor(code, message, path = "", options) {
+        super(message, options);
+        this.code = code;
+        this.path = path;
+        this.name = "ContractError";
+        if (options?.status)
+            this.status = options.status;
+        if (options?.fields)
+            this.fields = options.fields;
+    }
+}