@aotter/mantle 0.2.0-alpha.8 → 0.2.0

package/dist/infrastructure/help.js

@@ -0,0 +1,55 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+export const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+export function docsRoot() {
+    const root = [resolve(packageRoot, "docs"), resolve(packageRoot, "../../docs")].find(path => existsSync(resolve(path, "handbook/navigation.json")));
+    if (!root)
+        throw new Error(`Mantle docs are missing from ${packageRoot}; reinstall @aotter/mantle.`);
+    return root;
+}
+export function topics(root = docsRoot()) {
+    const nav = JSON.parse(readFileSync(resolve(root, "handbook/navigation.json"), "utf8"));
+    const pages = nav.groups.flatMap(group => group.items.map(item => ({ name: item.link.slice(1), title: item.text, file: resolve(root, `handbook${item.link}.md`), group: group.text })));
+    const listed = new Set(pages.map(page => page.file));
+    const unlisted = readdirSync(resolve(root, "handbook"), { recursive: true }).filter(path => path.endsWith(".md")).sort()
+        .map(path => resolve(root, "handbook", path)).filter(file => !listed.has(file))
+        .map(file => ({ name: relative(resolve(root, "handbook"), file).replaceAll("\\", "/").slice(0, -3), title: readFileSync(file, "utf8").match(/^# (.+)$/m)?.[1] ?? basename(file), file, group: "More pages" }));
+    const skills = (existsSync(resolve(root, "skills")) ? readdirSync(resolve(root, "skills")) : []).filter(name => existsSync(resolve(root, "skills", name, "SKILL.md")))
+        .map(name => ({ name: `skills/${name}`, title: `Package skill: ${name}`, file: resolve(root, "skills", name, "SKILL.md"), group: "Package skills" }));
+    const examples = resolve(root, "examples");
+    const shipped = readdirSync(examples, { withFileTypes: true }).filter(entry => entry.isDirectory() && existsSync(resolve(examples, entry.name, "README.md")));
+    return [...pages, ...unlisted, ...skills, { name: "examples", title: "Examples and how to combine them", file: resolve(examples, "README.md"), group: "Examples" },
+        ...shipped.map(entry => ({ name: `examples/${entry.name}`, title: `Example: ${entry.name}`, file: resolve(examples, entry.name, "README.md"), group: "Examples" }))];
+}
+function find(all, name) {
+    const exact = all.find(topic => topic.name === name);
+    if (exact)
+        return exact;
+    const tail = all.filter(topic => basename(topic.name) === name);
+    return tail.length === 1 ? tail[0] : undefined;
+}
+export function help(name, root = docsRoot()) {
+    const all = topics(root);
+    const topic = find(all, name ?? "start/agents");
+    if (!topic) {
+        const near = all.filter(t => name && t.name.includes(name)).map(t => `  mantle help ${t.name}`);
+        throw new Error(`No help topic ${JSON.stringify(name)}.${near.length ? `\nDid you mean:\n${near.join("\n")}` : ""}\nRun mantle help topics for the list.`);
+    }
+    const text = readFileSync(topic.file, "utf8").replace(/^---\n[\s\S]*?\n---\n/, "").trim();
+    const linked = [...new Set([...text.matchAll(/\]\(([^)#\s]+\.md)(?:#[^)]*)?\)/g)].map(match => resolve(dirname(topic.file), match[1])))]
+        .flatMap(file => all.filter(t => t.file === file && t !== topic));
+    const index = all.indexOf(topic), next = all[index + 1]?.group === topic.group ? all[index + 1] : undefined;
+    const lines = [text, "", `Source: ${relative(process.cwd(), topic.file) || topic.file}`];
+    if (next)
+        lines.push(`Next: mantle help ${next.name}  (${next.title})`);
+    if (linked.length)
+        lines.push("Linked:", ...linked.map(t => `  mantle help ${t.name}  (${t.title})`));
+    if (!name)
+        lines.push("", topicList(all));
+    return lines.join("\n");
+}
+export function topicList(all = topics()) {
+    const groups = [...new Set(all.map(topic => topic.group))];
+    return ["Topics:", ...groups.flatMap(group => [`  ${group}`, ...all.filter(t => t.group === group).map(t => `    ${t.name.padEnd(34)} ${t.title}`)])].join("\n");
+}

package/dist/infrastructure/init.js

@@ -0,0 +1,50 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { docsRoot, packageRoot } from "./help.js";
+const LOCAL = new Set(["node_modules", ".wrangler", ".dev.vars", "pnpm-lock.yaml", "generated", "dist"]);
+function files(directory) {
+    return readdirSync(directory, { withFileTypes: true }).flatMap(entry => LOCAL.has(entry.name) ? []
+        : entry.isDirectory() ? files(join(directory, entry.name)).map(file => join(entry.name, file)) : [entry.name]);
+}
+export function init(destination, dryRun = false) {
+    const shell = resolve(docsRoot(), "examples/app-shell");
+    const sdk = JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8"));
+    const target = resolve(destination);
+    const all = files(shell).map(file => file === "gitignore" ? ".gitignore" : file);
+    const source = (file) => file === ".gitignore" && !existsSync(join(shell, file)) ? join(shell, "gitignore") : join(shell, file);
+    const existing = all.filter(file => existsSync(join(target, file)));
+    if (existing.length)
+        throw new Error(`mantle init writes the app shell once and never overwrites. These files already exist in ${target}:\n${existing.map(f => `  ${f}`).join("\n")}\nMove them aside or run mantle init in an empty directory; to use generated code inside an existing app, skip init and run mantle help typed-queries.`);
+    const notes = [];
+    for (const file of all) {
+        let text = readFileSync(source(file), "utf8");
+        if (file === "package.json") {
+            const pkg = JSON.parse(text);
+            for (const name of Object.keys(pkg.dependencies))
+                if (name.startsWith("@aotter/mantle"))
+                    pkg.dependencies[name] = sdk.version;
+            text = JSON.stringify(pkg, null, 2) + "\n";
+        }
+        if (!file.endsWith(".md"))
+            text.split("\n").forEach((line, index) => { if (line.includes("AGENT:"))
+                notes.push(`  ${file}:${index + 1}: ${line.slice(line.indexOf("AGENT:") + 6).trim()}`); });
+        if (dryRun)
+            continue;
+        mkdirSync(dirname(join(target, file)), { recursive: true });
+        writeFileSync(join(target, file), text, { flag: "wx" });
+    }
+    if (!dryRun)
+        mkdirSync(join(target, "manifests"), { recursive: true });
+    const where = relative(process.cwd(), target) || ".";
+    return [
+        `${dryRun ? "Would write" : "Wrote"} the Mantle ${sdk.version} app shell to ${where}:`,
+        ...all.map(file => `  ${file}`), "  manifests/",
+        "",
+        "AGENT: the app must fill in these before it is done (each is marked in the file):",
+        "  manifests/*.yaml: the app's Schemas, Views, Procedures and Triggers (mantle help four-atoms)",
+        ...notes,
+        "",
+        `Next: cd ${where} && pnpm install; then follow README.md. mantle help explains each step;`,
+        "mantle help examples shows the patterns to take for each need. Accept with mantle help agent-workflow-acceptance before reporting done.",
+    ].join("\n");
+}

package/dist/infrastructure/inputs.js

@@ -1,23 +1,17 @@
-/** `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))
@@ -29,13 +23,10 @@ export function staleInputs(generatedModule) {
             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/mounts.js

@@ -0,0 +1,22 @@
+import { existsSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { ownModules } from "./bundle.js";
+const SURFACES = [
+    { module: "rest.ts", selected: files => files["rest.ts"]?.includes("pattern: new RegExp") ?? false, what: "REST routes", topic: "service-entry" },
+    { module: "mcp.ts", selected: files => "mcp.ts" in files, what: "MCP tools", topic: "service-entry" },
+    { module: "admin-bindings.ts", selected: files => "admin-bindings.ts" in files, what: "Admin bindings", topic: "native-admin" },
+];
+export async function unmountedWarnings(entry, destination, files) {
+    const selected = SURFACES.filter(surface => surface.selected(files));
+    if (!selected.length || !existsSync(entry))
+        return [];
+    let inputs;
+    try {
+        inputs = Object.keys((await ownModules(entry)).inputs).map(path => resolve(path));
+    }
+    catch (error) {
+        const first = error.errors?.[0]?.text ?? String(error);
+        return [`skipped checking which generated surfaces ${entry} serves: could not follow its imports (${first}).`];
+    }
+    return selected.filter(surface => !inputs.includes(resolve(destination, surface.module))).map(surface => `${surface.what} are generated in ${relative(process.cwd(), resolve(destination, surface.module))}, but ${entry} never imports it, so no request reaches them. Mount it in the entry (mantle help ${surface.topic}), or pass --entry if the app starts elsewhere.`);
+}

package/dist/infrastructure/wrangler.js

@@ -4,7 +4,6 @@ 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");
@@ -17,7 +16,6 @@ function compatibilityDate(dir) {
     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("\\", "/") || ".";
@@ -36,7 +34,7 @@ export function configureWrangler(configPath, entry, outdir, generated, 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`) +
+            (assets === undefined ? "" : `[assets]\ndirectory = ${JSON.stringify(local(assets))}\nbinding = "ASSETS"\nrun_worker_first = true\nhtml_handling = "none"\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;
     }
@@ -49,13 +47,11 @@ export function configureWrangler(configPath, entry, outdir, generated, check =
         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.`);
@@ -71,7 +67,6 @@ export function configureWrangler(configPath, entry, outdir, generated, check =
                     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);
@@ -80,9 +75,23 @@ export function configureWrangler(configPath, entry, outdir, generated, check =
         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 (assets !== undefined) {
+        const wireAssets = (path, current) => {
+            edit([...path, "directory"], local(assets));
+            const ownsDefaults = current === undefined || current?.binding === undefined;
+            if (ownsDefaults && current?.binding === undefined)
+                edit([...path, "binding"], "ASSETS");
+            if (ownsDefaults && current?.run_worker_first === undefined)
+                edit([...path, "run_worker_first"], true);
+            if (current?.html_handling === undefined && (current?.run_worker_first === true || (ownsDefaults && current?.run_worker_first === undefined)))
+                edit([...path, "html_handling"], "none");
+        };
+        wireAssets(["assets"], config.assets);
+        for (const [name, environment] of Object.entries(config.env ?? {})) {
+            if (environment?.assets !== undefined)
+                wireAssets(["env", name, "assets"], environment.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;

package/dist/kernel/authorization.js

@@ -1,5 +1,4 @@
 import { ContractError } from "./contracts.js";
-/** Rejections deny; synchronous application failures remain internal errors. */
 export async function authorized(authorize, target, caller) {
     let result;
     try {

package/dist/kernel/binds.d.ts

@@ -18,10 +18,19 @@ export type Recipe = {
 } | {
     readonly k: "const";
     readonly value: unknown;
+}
+/** A field-scoped Schema's scope column on an SQL INSERT: the Store's insert rule (autofill one value, refuse a value outside the caller's set). */
+ | {
+    readonly k: "scoped";
+    readonly column: string;
+    readonly field: string;
+    readonly type: "string" | "number";
+    readonly name?: string;
+    readonly value?: string | number;
 } | {
     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";
+    readonly name: string; /** Only a date-time, a date or JSON is converted, so only those carry a type. */
+    readonly type?: "timestamptz" | "date" | "json";
 };
 /** One printed statement and how to bind it. `row`: it must affect exactly one row. */
 export interface Step {
@@ -36,15 +45,15 @@ export type Bound = {
 };
 /** 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;
+    readonly userRefs?: (recipe: Recipe, caller: Caller, input?: Readonly<Record<string, unknown>>) => 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. */
+/**
+ * A declared date-time or date as the engine stores it, and a JSON value as its text (a string, such as a boundary's
+ * already converted value, is bound as it is); 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. */

package/dist/kernel/binds.js

@@ -1,10 +1,6 @@
-/**
- * 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 const encode = (d, type, v) => type === "timestamptz" ? (v == null ? null : d.timestamp(v)) : type === "date" ? (v == null ? null : d.date(v))
+    : type === "json" && v != null && typeof v !== "string" ? JSON.stringify(v) : v;
 export function binds(d, recipes, caller, input, ms = 0) {
     const out = [];
     for (const r of recipes) {
@@ -32,14 +28,12 @@ export function binds(d, recipes, caller, input, ms = 0) {
             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));
+            default: out.push(d.userRefs(r, caller, input));
         }
     }
     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
+    const ms = Date.now();
     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

@@ -18,7 +18,4 @@ export declare const isAdminCaller: (caller: Caller) => caller is Extract<Caller
 }> & {
     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

@@ -1,22 +1,7 @@
-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/caller-mode.d.ts

@@ -0,0 +1,4 @@
+import type { Caller } from "./contracts.js";
+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;

package/dist/kernel/caller-mode.js

@@ -0,0 +1,14 @@
+import { ContractError } from "./contract-error.js";
+import { isHostCaller } from "./caller-identity.js";
+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');
+}
+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/contracts.d.ts

@@ -108,10 +108,14 @@ export type Output = {
 };
 /** Deny unless `allowed`: a user is AUTH_DENIED, anyone else UNAUTHENTICATED. */
 export declare function deny(caller: Caller, allowed: boolean, path: string): void;
-/** CONFLICT for a write the database refused: a unique-index clash, or a row statement that did not change exactly one row. */
+/** A row statement that changed no row cannot tell why without leaking whether the row exists, so it says how to recover. */
+export declare const ROW_CONFLICT = "No row matched this change: it does not exist or is not visible to you, it changed since it was read, or its state no longer allows this change. Read it again before deciding whether to retry.";
+/** CONFLICT for a write the database refused: a unique-index clash (`fields.kind` "unique"), or a row statement that did not change exactly one row ("row"). */
 export declare const conflict: (path: string, unique: boolean, cause?: unknown) => ContractError;
 /** A Schema `checks` violation (Mantle's SQLite check trigger, or PostgreSQL SQLSTATE 23514) is a CONFLICT naming the check. */
-export declare const checkConflict: (path: string, error: unknown, violated?: boolean) => ContractError | undefined;
+export declare const checkConflict: (path: string, error: unknown) => ContractError | undefined;
+/** One message on every target, built from the parsed fields; the driver's own text stays in `cause`. */
+export declare const schemaCheckFailed: (path: string, cause: unknown, schema: string | undefined, check: string | undefined) => ContractError;
 /** One result of `unsafe`: the rows (typed by the generated function), plus the affected count. */
 export type PostgresResult = any[] & {
     readonly count: number | null;
@@ -128,12 +132,4 @@ export interface Postgres {
 }
 /** What a read or a single statement needs: a transaction handle suits it too. */
 export type Unsafe = Pick<Postgres, "unsafe">;
-/** A cookie is ambient authority; bearer credentials deliberately supplied by the app are not. */
-export declare function checkOrigin(request: Request, caller: Caller): void;
-/** A resolver's ContractError (e.g. UNAUTHENTICATED for an expired token) keeps its status; anything else is an application failure. */
-export declare function surfaceCaller<Env>(request: Request, env: Env, resolve: (request: Request, env: Env, authority: {
-    readonly readOnly: boolean;
-}) => Caller | Promise<Caller>, readOnly?: boolean): Promise<Caller>;
-/** The client sees the redacted wire form; the log gets the surface (a route or tool, never headers) and the original message, stack and cause. */
-export declare function surfaceError(error: unknown, where?: string): ReturnType<typeof wire>;
-export declare function surfaceFailure(error: unknown, challenge?: string, where?: string): Response;
+export { checkOrigin, surfaceCaller, surfaceError, surfaceFailure } from "./surface-failure.js";

package/dist/kernel/contracts.js

@@ -1,20 +1,14 @@
-/** Boundary primitives only. No plan, SQL interpreter or resource ownership. */
 import { ContractError } from "./contract-error.js";
 export { ContractError } from "./contract-error.js";
 import { hasRole, isAdminCaller as isAdmin } from "./caller-identity.js";
-/** Gateway mode or the one execution prop carrying forwarded authority. */
 export const forwarded = (ctx, gateway) => !!(gateway || ctx?.props && Object.hasOwn(ctx.props, "mantle"));
-/** Privilege never follows a member role name. Only the original verified identity carries the admin layer. */
 export { isAdmin };
-/** Both authenticated layers pass ctx.user; the host layer still needs its original brand. */
 export const isUser = (caller) => caller.kind === "user" || isAdmin(caller);
 export const hasAdminRole = (caller, name) => isAdmin(caller) && hasRole(caller, name);
-/** Only the core transport failures; other codes carry their own status, and unknown codes remain server errors. */
 export const statusOf = (code) => ({ __proto__: null,
     INPUT_VALIDATION_FAILED: 400, UNAUTHENTICATED: 401, AUTH_DENIED: 403, NOT_FOUND: 404,
     METHOD_NOT_ALLOWED: 405, CONFLICT: 409, OUTCOME_UNKNOWN: 503,
 }[code] ?? 500);
-/** Redact native errors at the selected boundary; the bare query preserves their identity. */
 export function wire(error) {
     const status = error instanceof ContractError ? error.status ?? statusOf(error.code) : 500;
     if (status !== 500) {
@@ -46,47 +40,17 @@ export function wireRows(rows, fields = []) {
         return result;
     });
 }
-/** Deny unless `allowed`: a user is AUTH_DENIED, anyone else UNAUTHENTICATED. */
 export function deny(caller, allowed, path) {
     if (!allowed)
         throw new ContractError("subject" in caller ? "AUTH_DENIED" : "UNAUTHENTICATED", "Authorization predicate not satisfied.", path);
 }
-/** CONFLICT for a write the database refused: a unique-index clash, or a row statement that did not change exactly one row. */
-export const conflict = (path, unique, cause) => new ContractError("CONFLICT", unique ? "A unique constraint of the Schema was violated." : "Expected one affected row.", path, { cause });
-/** A Schema `checks` violation (Mantle's SQLite check trigger, or PostgreSQL SQLSTATE 23514) is a CONFLICT naming the check. */
-export const checkConflict = (path, error, violated = /MANTLE_CHECK /.test(String(error?.message))) => {
-    if (!violated)
+export const ROW_CONFLICT = "No row matched this change: it does not exist or is not visible to you, it changed since it was read, or its state no longer allows this change. Read it again before deciding whether to retry.";
+export const conflict = (path, unique, cause) => new ContractError("CONFLICT", unique ? "A unique constraint of the Schema was violated." : ROW_CONFLICT, path, { cause, fields: { kind: unique ? "unique" : "row" } });
+export const checkConflict = (path, error) => {
+    const message = error?.message ?? "", marker = /MANTLE_CHECK ([^:\n]+): (.+)/.exec(message);
+    if (!/MANTLE_CHECK /.test(message))
         return undefined;
-    const message = String(error?.message ?? "");
-    return new ContractError("CONFLICT", `A check of the Schema failed: ${/MANTLE_CHECK [^\n'"]+/.exec(message)?.[0] ?? message}`, path, { cause: error });
+    return schemaCheckFailed(path, error, marker?.[1], marker?.[2]?.replace(/: SQLITE_CONSTRAINT.*$/, ""));
 };
-/** A cookie is ambient authority; bearer credentials deliberately supplied by the app are not. */
-export function checkOrigin(request, caller) {
-    if (!("credential" in caller) || caller.credential !== "session" || ["GET", "HEAD", "OPTIONS"].includes(request.method))
-        return;
-    const site = request.headers.get("sec-fetch-site"), origin = request.headers.get("origin");
-    if ((!site && !origin) || (site && site !== "same-origin" && site !== "none") || (origin && origin !== new URL(request.url).origin))
-        throw new ContractError("AUTH_DENIED", "Cross-origin session mutation rejected.", "request:origin");
-}
-/** A resolver's ContractError (e.g. UNAUTHENTICATED for an expired token) keeps its status; anything else is an application failure. */
-export async function surfaceCaller(request, env, resolve, readOnly = false) {
-    try {
-        return await resolve(request, env, { readOnly });
-    }
-    catch (cause) {
-        if (cause instanceof ContractError)
-            throw cause;
-        throw new Error("Caller resolution failed.", { cause });
-    }
-}
-/** The client sees the redacted wire form; the log gets the surface (a route or tool, never headers) and the original message, stack and cause. */
-export function surfaceError(error, where = "surface") {
-    const result = wire(error);
-    if (result.status === 500)
-        console.error(`[mantle ${where}] unhandled failure`, error);
-    return result;
-}
-export function surfaceFailure(error, challenge, where) {
-    const result = surfaceError(error, where);
-    return Response.json({ error: result.error }, { status: result.status, headers: { "cache-control": "private, no-store", ...(challenge && [401, 403].includes(result.status) && result.error.path !== "request:origin" ? { "www-authenticate": challenge } : {}) } });
-}
+export const schemaCheckFailed = (path, cause, schema, check) => new ContractError("CONFLICT", schema && check ? `A check of the Schema failed: ${schema}: ${check}` : "A check of the Schema failed.", path, { cause, fields: { kind: "check", schema, check } });
+export { checkOrigin, surfaceCaller, surfaceError, surfaceFailure } from "./surface-failure.js";

package/dist/kernel/cron.js

@@ -1,8 +1,6 @@
-/** SDK-owned POSIX to Cloudflare cron conversion, copied verbatim from Core's CloudflareCron so Workers don't pull Core's D1 driver; Core is retired with 0.2.0, so this copy becomes the only one. */
 const PART = /^(\*|\d+|[A-Za-z]{3})(?:-(\d+|[A-Za-z]{3}))?(?:\/(\d+))?$/;
 const MONTHS = ["JAN", "FEB", "MAR", "APR", "MAY", "JUN", "JUL", "AUG", "SEP", "OCT", "NOV", "DEC"];
 const DAYS = ["SUN", "MON", "TUE", "WED", "THU", "FRI", "SAT"];
-/** label, lowest, highest, names (by value from `lowest`) */
 const FIELDS = [["minute", 0, 59, null], ["hour", 0, 23, null], ["day of month", 1, 31, null], ["month", 1, 12, MONTHS], ["weekday", 0, 6, DAYS]];
 export function toCloudflareCron(cron) {
     const refuse = (why) => {
@@ -14,7 +12,6 @@ export function toCloudflareCron(cron) {
     const weekday = [];
     fields.forEach((field, i) => {
         const [label, min, max, names] = FIELDS[i];
-        // a value as a number: a name counts as its number, and a number must be written plainly (`01` and `1` are one value)
         const value = (token) => {
             if (/^\d+$/.test(token)) {
                 if (token.length > 1 && token.startsWith("0"))
@@ -51,7 +48,6 @@ export function toCloudflareCron(cron) {
         if (i === 4)
             weekday.push(...out);
     });
-    // POSIX runs on either day when both are restricted; Cloudflare does not document that rule, so only one may be
     if (fields[2] !== "*" && fields[4] !== "*")
         refuse("restrict the day of month or the weekday, not both");
     return [...fields.slice(0, 4), weekday.join(",")].join(" ");

package/dist/kernel/dialect/common.d.ts

@@ -10,7 +10,6 @@ export declare const likeEscape = " ESCAPE '\\'";
  */
 export interface Dialect {
     readonly userRefs?: import('../binds.js').Values['userRefs'];
-    readonly user?: import('../binds.js').Values['user'];
     readonly anyOf?: (column: string, placeholder: string, type: 'string' | 'number') => string;
     readonly scopeInsert?: (scopes: readonly {
         readonly column: string;

package/dist/kernel/dialect/common.js

@@ -1,6 +1,3 @@
-/** What SQLite and PostgreSQL spell identically, defined once; each dialect module re-exports it. */
-/** A (possibly schema-qualified) name, quoted. */
 export const ident = (name) => name.split(".").map(part => `"${part.replaceAll('"', '""')}"`).join(".");
-/** A literal piece of text for a LIKE pattern: `\`, `%` and `_` match themselves. Pair with `likeEscape`. */
 export const escapeLike = (value) => value.replace(/[\\%_]/g, "\\$&");
 export const likeEscape = " ESCAPE '\\'";

package/dist/kernel/dialect/postgres.js

@@ -1,4 +1,3 @@
-/** PostgreSQL: `$n` placeholders, time as timestamptz (ISO text keeps every microsecond). */
 import { isoDate, isoTimestamptz } from "../scalars.js";
 import { searchLike } from "../search.js";
 import { escapeLike, ident, likeEscape } from "./common.js";
@@ -13,6 +12,5 @@ export const cutoff = (ms, seconds) => new Date(ms - seconds * 1000);
 export const timestamp = isoTimestamptz;
 export const date = isoDate;
 export const cast = (placeholder, type) => type === "timestamptz" || type === "date" ? `CAST(CAST(${placeholder} AS text) AS ${type})` : type === "json" ? `CAST(CAST(${placeholder} AS text) AS jsonb)` : placeholder;
-// ponytail: preserve Core's ILIKE scan; add pg_trgm only when measured search latency needs it.
 export const search = (_table, fields, alias, query) => searchLike(fields.map(field => `${alias}.${ident(field)}`), query, "ILIKE");
 export const dialect = { param, ident, escapeLike, likeEscape, like, search, wireTimestamp, wireDate, now, cutoff, timestamp, date, cast, anyOf };

package/dist/kernel/dialect/sqlite.js

@@ -1,24 +1,19 @@
 import { ContractError } from "../contracts.js";
-/** SQLite and Cloudflare D1: `?n` placeholders, time as microseconds and dates as days since the epoch. */
 import { encodeDate, encodeTimestamptz } from "../scalars.js";
 import { searchLike } from "../search.js";
 import { escapeLike, ident, likeEscape } from "./common.js";
 export { ident, escapeLike, likeEscape };
 export const param = (n) => `?${n}`;
 export const anyOf = (column, placeholder) => `${column} IN (SELECT value FROM json_each(${placeholder}))`;
-export const like = () => "LIKE"; // SQLite's LIKE already ignores ASCII case
-/** A write that broke a UNIQUE index or the id's UNIQUE (bun:sqlite and D1 word it the same). */
+export const like = () => "LIKE";
 export const unique = (error) => /UNIQUE constraint failed/.test(String(error?.message));
-/** Positive rollback evidence only. Plain/network/I/O errors are deliberately uncertain. */
 export function definitive(error) {
     if (error instanceof ContractError)
         return error.code === "CONFLICT";
     const e = error;
-    // Bun before 1.4 omits `code` on statement errors; its SQLiteError still carries the native errno.
     const native = typeof e?.code === "string" ? e.code.startsWith("SQLITE_") : e?.name === "SQLiteError";
     return native && typeof e.errno === "number" && [1, 19, 20, 25].includes(e.errno & 255);
 }
-// floor, not SQLite's truncating `/` and `%`: a time before 1970 is a negative number of microseconds
 export const wireTimestamp = (v) => ["strftime('%Y-%m-%dT%H:%M:%S', ((", v, ") - ((", v, ") % 1000000 + 1000000) % 1000000) / 1000000, 'unixepoch') || '.' || substr('00000' || (((", v, ") % 1000000 + 1000000) % 1000000), -6) || 'Z'"];
 export const wireDate = (v) => ["date((", v, ") * 86400, 'unixepoch')"];
 export const now = (ms) => ms * 1000;

package/dist/kernel/drain.js

@@ -1,25 +1,19 @@
-/** Request-time only: no Worker startup path imports this. */
-/** Read and discard what is left of a request body, at most 1 MiB and 1 s. A response sent over an unread POST body makes local
- *  `wrangler dev` break the connection, and the next request fails with "Network connection lost". */
 async function drain(request) {
     let reader;
     const timer = setTimeout(() => reader?.cancel().catch(() => { }), 1000);
     try {
-        reader = request.body?.getReader(); // a body the app consumed is done; one it still holds is locked and throws
+        reader = request.body?.getReader();
         for (let read = 0, chunk; reader && !(chunk = await reader.read()).done;)
             if ((read += chunk.value.byteLength) > 1024 * 1024) {
                 await reader.cancel();
                 return;
             }
     }
-    catch { /* the client went away */ }
+    catch {  }
     finally {
         clearTimeout(timer);
     }
 }
-/** A request handler that drains the body once it has answered or thrown. `undefined` and `null` mean the request is not this
- *  handler's, so the next handler can still read it. A handler that answers and reads the request later (in `waitUntil`) must
- *  read or lock the body before answering. */
 export const draining = (handle) => async (...args) => {
     let response;
     try {