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

package/dist/infrastructure/bundle.js

@@ -4,7 +4,6 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "nod
 import { pathToFileURL } from "node:url";
 import { build } from "esbuild";
 import { INPUTS_FILE, authTableSql, extraRoles, generatedTarget, staleInputs } from "./inputs.js";
-/** Only static imports run at startup; dynamic imports remain separate uploaded modules. */
 export function startupGraph(metafile, entry) {
     const visited = new Set();
     const visit = (name) => {
@@ -25,23 +24,19 @@ export function startupGraph(metafile, entry) {
 const refused = [
     [/(?:^|\/)node_modules\/(?:better-auth(?:\/|$)|@better-auth\/)/, "Load it through authLoader(() => import(...)) to keep Better Auth out of startup."],
     [/(?:^|\/)node_modules\/@modelcontextprotocol\//, "Load MCP through a request-time import(...)."],
-    // the compiler: the package's own generator layers (installed, or workspace dist/source) and its parser, YAML and SQL dependencies
     [/(?:^|\/)node_modules\/(?:@aotter\/mantle\/dist\/(?:build|infrastructure)\/|yaml\/|pgsql-deparser\/|libpg-query\/)|(?:^|\/)mantle\/(?:dist|src)\/(?:build|infrastructure)\//, "Generator code must not run in a Worker; import runtime entry points such as @aotter/mantle/rest."],
-    // Admin's UI is built into <assets>/admin by the app's admin.tsx; the Worker serves it, never runs it.
     [/(?:^|\/)node_modules\/@aotter\/mantle-admin\/dist\/admin-app\/|(?:^|\/)mantle-admin\/(?:dist\/admin-app|admin\/src)\//, "Admin's UI (@aotter/mantle-admin/app, /hooks) runs in the browser: import it only from src/admin.tsx, which `mantle bundle` builds into the assets directory."],
 ];
 export function guardStartup(metafile, entry) {
     for (const name of startupGraph(metafile, entry)) {
         const output = metafile.outputs[name];
         for (const input of Object.keys(output.inputs)) {
-            // shortcut: vendored auth outside node_modules is not recognized; use package metadata if vendoring is supported.
             const hit = refused.find(([pattern]) => pattern.test(input.replaceAll("\\", "/")));
             if (hit)
                 throw new Error(`Startup module ${name} contains ${input}. ${hit[1]}`);
         }
     }
 }
-/** The physical spelling of a path, including a nonexistent tail below its nearest existing ancestor. */
 const physical = (input) => {
     let found = resolve(input);
     const tail = [];
@@ -54,33 +49,23 @@ const physical = (input) => {
     }
     return resolve(realpathSync(found), ...tail);
 };
-/** Whether `inner` is `outer` or inside it. */
 const within = (outer, inner) => {
     const path = relative(physical(outer), physical(inner));
     return path === "" || (path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path));
 };
-/** A directory a build empties must not be the working directory or hold the source entry. */
 function assertCleanable(label, dir, entry) {
     if (physical(dir) === physical(process.cwd()))
         throw new Error(`${label} must not be the working directory: it is cleaned before building.`);
     if (within(dir, entry))
         throw new Error(`${label} must not contain the source entry: it is cleaned before building.`);
 }
-/** The app's own modules only (packages external): enough to find its generated output and what it imports. */
 export const ownModules = async (entry) => (await build({ entryPoints: [entry], bundle: true, write: false, metafile: true, packages: "external", format: "esm", platform: "neutral", logLevel: "silent", absWorkingDir: process.cwd() })).metafile;
-/**
- * `mantle bundle <entry> <outdir> [--assets <dir>]`: the Worker into `<outdir>/worker`, and Admin into `<assets>/admin`
- * (default `<outdir>/client`) when the Worker serves it (`@aotter/mantle-admin/server`; `/mcp` and the other subpaths alone do not).
- * A server whose generated output records a `bun-*` target runs as TypeScript, so only its Admin is built.
- */
 export async function bundleApp(entry, outdir, assets = join(outdir, "client")) {
     const source = realpathSync(entry);
-    // what is cleaned lies under these two, so neither may be the working directory or hold the source
     assertCleanable("Bundle outdir", outdir, source);
     assertCleanable("The assets directory", assets, source);
     const own = await ownModules(entry);
     if (generatedDirs(own).some(dir => generatedTarget(join(dir, "generated.ts"))?.startsWith("bun-"))) {
-        // Packages are external here, so only the app's own imports of the Admin server are seen; one reached through another package is not.
         if (Object.values(own.inputs).some(input => input.imports.some(imported => /^@aotter\/mantle-admin\/server(?:\/|$)/.test(imported.path))))
             await bundleAdmin(source, outdir, join(assets, "admin"));
         else
@@ -88,7 +73,6 @@ export async function bundleApp(entry, outdir, assets = join(outdir, "client"))
         return;
     }
     const worker = join(outdir, "worker");
-    // Wrangler uploads every module under the Worker directory and every file under the assets directory.
     if (within(worker, assets) || within(assets, worker))
         throw new Error(`The assets directory ${assets} must not overlap the Worker directory ${worker}.`);
     const metafile = await bundle(entry, worker);
@@ -96,12 +80,6 @@ export async function bundleApp(entry, outdir, assets = join(outdir, "client"))
         await bundleAdmin(source, outdir, join(assets, "admin"));
     }
 }
-/**
- * Admin from `<dirname(entry)>/admin.tsx`, or the built-in entry; an optional `admin.mcp.tsx` selects the host-safe graph.
- * Uses `@aotter/mantle-admin/build` as the app installed
- * it. The built-in entry is skipped when the installed Admin and its direct dependencies are unchanged since the last
- * build; an application entry always builds, because what it imports is only known by building it.
- */
 async function bundleAdmin(entry, outdir, out) {
     const source = join(dirname(entry), "admin.tsx"), custom = existsSync(source);
     const mcpSource = join(dirname(entry), "admin.mcp.tsx"), customMcp = existsSync(mcpSource);
@@ -115,7 +93,6 @@ async function bundleAdmin(entry, outdir, out) {
         throw new Error(`The Worker serves Admin, but @aotter/mantle-admin/build does not resolve from ${relative(process.cwd(), entry)}. Install @aotter/mantle-admin at the version of @aotter/mantle-admin/server.`);
     }
     const stamp = join(outdir, ".admin-inputs");
-    // the installed path too: a patched or linked Admin keeps its version but not its path
     const manifest = realpathSync(lookup(require, "@aotter/mantle-admin") ?? require.resolve("@aotter/mantle-admin/package.json"));
     const key = custom || customMcp ? undefined : JSON.stringify({ out: resolve(out), path: dirname(manifest), packages: installed(manifest) });
     if (key && existsSync(join(out, "index.html")) && existsSync(join(out, "mcp-app.html")) && existsSync(stamp) && readFileSync(stamp, "utf8") === key) {
@@ -128,9 +105,7 @@ async function bundleAdmin(entry, outdir, out) {
     if (key)
         writeFileSync(stamp, key);
 }
-/** The package.json a bare import of `name` finds, read from disk (`exports` may hide it, and require caches realpaths). */
 const lookup = (require, name) => require.resolve.paths(name)?.map(dir => join(dir, name, "package.json")).find(file => existsSync(file));
-/** The package's version and the installed version of each of its dependencies and peers (React comes from the application). */
 function installed(manifest) {
     const { name, version, dependencies = {}, peerDependencies = {} } = JSON.parse(readFileSync(manifest, "utf8"));
     const require = createRequire(manifest);
@@ -141,7 +116,6 @@ function installed(manifest) {
     }
     return versions;
 }
-/** The generated directories among a build's inputs, refusing stale ones. */
 function generatedDirs(metafile) {
     const dirs = [...new Set(Object.keys(metafile.inputs).map(input => resolve(input, "..")).filter(dir => existsSync(resolve(dir, INPUTS_FILE))))];
     for (const dir of dirs) {
@@ -164,15 +138,12 @@ export async function bundle(entry, outdir) {
                         if (args.pluginData?.optionalPeer)
                             return;
                         const resolved = await builder.resolve(args.path, { importer: args.importer, resolveDir: args.resolveDir, kind: args.kind, pluginData: { optionalPeer: true } });
-                        // Unselected request paths may reference absent peers; installed peers still bundle normally.
                         return resolved.errors.length ? { path: args.path, external: true } : resolved;
                     });
                 } }],
     });
     if (Object.keys(result.metafile.inputs).some(input => /(?:^|\/)mantle\/(?:src|dist)\/testing\//.test(resolve(input).replaceAll("\\", "/"))))
         throw new Error("@aotter/mantle/testing is only for tests and cannot be bundled for production.");
-    // A build is what `wrangler dev` and deploys run: generated code must match the manifests it came from.
-    // Any bundled module from a generated directory finds its fingerprint (type-only imports leave generated.ts out).
     generatedDirs(result.metafile);
     const appSources = Object.keys(result.metafile.inputs).filter(input => !/node_modules|(?:^|\/)generated\/|^\.\.\//.test(input) && /\.[cm]?[jt]s$/.test(input)).map(input => [input, readFileSync(input, "utf8")]);
     for (const [input, source] of appSources) {

package/dist/infrastructure/cli.js

@@ -7,7 +7,6 @@ import { parseArgs } from "node:util";
 import { configureWrangler } from "./wrangler.js";
 import { writeArtifacts } from "./artifacts.js";
 import { INPUTS_FILE, inputsFingerprint } from "./inputs.js";
-/** Option modules are often .ts, which older Node rejects with a bare "Unknown file extension". */
 async function load(path) {
     try {
         return await import(pathToFileURL(resolve(path)).href);
@@ -25,7 +24,6 @@ try {
             diff: { type: "string" }, check: { type: "boolean" }, admin: { type: "boolean" }, site: { type: "string" }, auth: { type: "string", multiple: true }, wrangler: { type: "string" }, entry: { type: "string", default: "src/worker.ts" }, outdir: { type: "string", default: "dist" }, assets: { type: "string" }, "dry-run": { type: "boolean" }, help: { type: "boolean", short: "h" },
         } });
     const named = ["bundle", "generate", "describe", "help", "init"].includes(positionals[0]) ? positionals.shift() : undefined;
-    // `-h` prints usage and never runs a command; bare `mantle` starts at help, but options with no positionals stay a usage error.
     const command = values.help ? "usage" : named ?? (process.argv.length > 2 ? "generate" : "help");
     if (command === "usage")
         console.log(`${usage}\n\nStart with mantle help: the installed docs, one topic at a time.`);
@@ -68,13 +66,10 @@ try {
         const [target, destination, ...paths] = positionals;
         if (!target || !targets.includes(target) || !destination || !paths.length)
             throw new Error(usage);
-        // A shell leaves an unmatched glob as is; say what is missing instead of ENOENT.
         for (const path of paths)
             if (/[*?]/.test(path) && !existsSync(path))
                 throw new Error(`No manifest matches ${path}. Add one (mantle help four-atoms, mantle help manifest), then run generate again.`);
         const sources = await Promise.all(paths.map(async (path) => ({ sourceId: path, text: await readFile(path, "utf8") })));
-        // Read plain options without constructing Better Auth, which can touch the database.
-        // One --auth per Better Auth instance; their tables are merged into one migration.
         const auth = await Promise.all((values.auth ?? []).map(async (path) => {
             const loaded = await load(path);
             const options = loaded.authOptions?.(new Proxy({}, { get: () => undefined })) ?? loaded.auth?.options;
@@ -93,7 +88,6 @@ try {
             console.warn(`warning: ${warning}`);
         const read = [...paths, ...(values.auth ?? []), ...(values.site ? [values.site] : [])];
         const changed = await writeArtifacts(destination, { ...result.files, [INPUTS_FILE]: inputsFingerprint(destination, read, target) }, values.check);
-        // After writing: the entry's imports of generated modules only resolve once they exist.
         for (const warning of await (await import("./mounts.js")).unmountedWarnings(values.entry, destination, result.files))
             console.warn(`warning: ${warning}`);
         if (target.startsWith("cloudflare-")) {
@@ -107,7 +101,6 @@ try {
             throw new Error(`Generated output is stale. Run mantle generate with the same options:\n${changed.join("\n")}`);
         if (!values.check)
             console.log(`Commit generated output and Wrangler config edits; keep dist/ untracked. Add to .gitattributes: ${JSON.stringify(relative(process.cwd(), resolve(destination)).replaceAll("\\", "/") + "/**")} linguist-generated=true`);
-        // A contract, not a to-do: the CLI does not read the app's handlers; tsc checks them against Handlers.
         if (!values.check && result.refProcedures.length)
             console.log(`Ref Procedures need these Handlers keys (tsc --noEmit checks them; pass them at store(db, caller, { handlers })): ${result.refProcedures.map(name => JSON.stringify(name)).join(", ")}`);
     }

package/dist/infrastructure/generate.js

@@ -1,5 +1,4 @@
 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";
@@ -12,12 +11,7 @@ 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;
@@ -32,23 +26,18 @@ function castInputs(statement, path, refusals) {
     }
     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) && property?.["x-mantle-ref"] != null);
-        // 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.${s.userScopes?.length ? ` That Procedure takes ${s.userScopes.map(u => `'${u.column}'`).join(', ')} as an optional input for callers holding { all: true } (field scope in the Schema reference).` : ''}`).concat(Object.values(plan.schemas)
-        // A create action's Procedure writes the field itself; only Admin's generic create needs the default.
         .filter(s => s.schema.readOnly !== true && !placed.has(s.name.toLowerCase()))
         .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's generic create cannot fill it. Give it a default (Admin stores it on create), or create the records through a Procedure with uiSchema.collectionAction: ${s.name}.`)));
 }
-/** Warn about SQL's case folding without changing the authored output names. */
 function outputNameWarnings(plan) {
     const warnings = [];
     const inspect = (kind, name, stmts) => {
@@ -116,8 +105,6 @@ export async function generateFromSources(request, schema) {
     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;
@@ -172,7 +159,6 @@ export async function generateFromSources(request, schema) {
             !["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] };
     }
-    // A Procedure the runtime cannot lower names only that; the lowering's own refusal says why.
     if (!result.ok)
         return { ...result, diagnostics: result.diagnostics.map(d => {
                 const why = d.message === "Both caller and trusted SQL must be lowered." ? warnings.find(w => w.includes(`${d.path} (caller)`) || w.includes(`${d.path} (admin)`)) : undefined;

package/dist/infrastructure/generateAuth.js

@@ -1,7 +1,6 @@
 import { generateFromSources as generate } from "./generate.js";
 import { admin, anonymous, jwt, phoneNumber, siwe, twoFactor } from "better-auth/plugins";
 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);
@@ -9,29 +8,23 @@ export function generateFromSources(request) {
 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 */)
+        if (ids.includes("oauth-provider") && !ids.includes("mantle-oauth-grant-revocation") )
             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.");
     }
     if (instances.length > 1)
         refuseSharedPluginMappings(instances);
     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;
 }
-// Plugins whose factory hands back one module-level schema object (mergeSchema writes `schema` options into it); no options leaves it untouched.
 const sharedSchema = {
     jwt: () => jwt().schema, admin: () => admin().schema, anonymous: () => anonymous().schema,
     "phone-number": () => phoneNumber({}).schema, siwe: () => siwe({}).schema, "two-factor": () => twoFactor().schema,
 };
-// Plugins that share field objects (device-authorization) or copy per call (oauth-provider, listed on request) are only checked for equal resolved names.
 const checkedPlugins = new Set([...Object.keys(sharedSchema), "device-authorization", "oauth-provider"]);
-/** Names a plugin's tables and fields resolve to, keyed `table` / `table.field`; only mappings that differ from the key are listed. */
 function mapped(schema) {
     const names = new Map();
     for (const [table, model] of Object.entries(schema)) {
@@ -45,7 +38,6 @@ function mapped(schema) {
     }
     return names;
 }
-/** Better Auth plugin factories share their schema object, so differing plugin field/model mappings across instances in one Worker override each other. */
 function refuseSharedPluginMappings(instances) {
     const byPlugin = new Map();
     instances.forEach((options, index) => (options.plugins ?? []).forEach(plugin => {

package/dist/infrastructure/help.js

@@ -1,9 +1,7 @@
-/** `mantle help [topic]`: a projection of the installed docs/handbook/navigation.json; the docs stay the only source. */
 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)), "../..");
-/** Packed: <package>/docs. Workspace: the repository's docs/, which prepack copies in. */
 export function docsRoot() {
     const root = [resolve(packageRoot, "docs"), resolve(packageRoot, "../../docs")].find(path => existsSync(resolve(path, "handbook/navigation.json")));
     if (!root)
@@ -13,7 +11,6 @@ export function docsRoot() {
 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 })));
-    // Pages the sidebar leaves out (acceptance, release notes) are still topics.
     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))
@@ -25,7 +22,6 @@ export function topics(root = docsRoot()) {
     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" }))];
 }
-/** A full topic name, or its last segment when only one topic ends with it. */
 function find(all, name) {
     const exact = all.find(topic => topic.name === name);
     if (exact)
@@ -41,7 +37,6 @@ export function help(name, root = docsRoot()) {
         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();
-    // Links to other topics become commands, so an agent can follow them without knowing the docs layout.
     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;

package/dist/infrastructure/init.js

@@ -1,8 +1,6 @@
-/** `mantle init`: copy the installed app shell once. The app owns every file afterwards; init never overwrites one. */
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, relative, resolve } from "node:path";
 import { docsRoot, packageRoot } from "./help.js";
-// Local state a docs checkout may hold after someone ran the shell in place; sync-package-docs excludes the same names.
 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) ? []
@@ -12,7 +10,6 @@ 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);
-    // A packed shell carries `gitignore` (npm drops .gitignore); a workspace checkout has .gitignore itself.
     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)));
@@ -21,7 +18,6 @@ export function init(destination, dryRun = false) {
     const notes = [];
     for (const file of all) {
         let text = readFileSync(source(file), "utf8");
-        // Pin the shell's Mantle packages to the installed SDK.
         if (file === "package.json") {
             const pkg = JSON.parse(text);
             for (const name of Object.keys(pkg.dependencies))

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

@@ -1,4 +1,3 @@
-/** Warn when a surface the manifests select is generated but the app entry never imports it, so it is never served. */
 import { existsSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import { ownModules } from "./bundle.js";
@@ -7,7 +6,6 @@ const SURFACES = [
     { 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" },
 ];
-/** Follows relative static and dynamic imports from the entry; packages stay external, so nothing needs to be installed. */
 export async function unmountedWarnings(entry, destination, files) {
     const selected = SURFACES.filter(surface => surface.selected(files));
     if (!selected.length || !existsSync(entry))
@@ -17,7 +15,6 @@ export async function unmountedWarnings(entry, destination, files) {
         inputs = Object.keys((await ownModules(entry)).inputs).map(path => resolve(path));
     }
     catch (error) {
-        // This probe has none of mantle bundle's loaders or conditions, so a failure here says nothing about the entry.
         const first = error.errors?.[0]?.text ?? String(error);
         return [`skipped checking which generated surfaces ${entry} serves: could not follow its imports (${first}).`];
     }

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("\\", "/") || ".";
@@ -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);
@@ -88,7 +83,6 @@ export function configureWrangler(configPath, entry, outdir, generated, check =
                 edit([...path, "binding"], "ASSETS");
             if (ownsDefaults && current?.run_worker_first === undefined)
                 edit([...path, "run_worker_first"], true);
-            // The shell fetches index.html itself; asset canonicalization would redirect it back to /admin/ forever.
             if (current?.html_handling === undefined && (current?.run_worker_first === true || (ownsDefaults && current?.run_worker_first === undefined)))
                 edit([...path, "html_handling"], "none");
         };

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.js

@@ -1,12 +1,4 @@
-/**
- * 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, 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 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) {
@@ -36,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, 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

@@ -132,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";