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

package/README.md

@@ -1,52 +1,187 @@
-# @aotter/mantle
-
-Mantle is a manifest-driven service core. A service declares Schemas, Views,
-Procedures and Triggers in YAML. Views and Procedures are SQL
-(PostgreSQL syntax). `mantle generate` compiles them into a sealed plan and a
-typed module. The runtime serves the plan through one Store, which adds each
-caller's scope, TTL, publishing state and optimistic locks to every statement.
-
-## Subpaths
-
-Each folder of `src/` is one subpath. `check:boundaries` enforces what each may
-import.
-
-| Subpath | Contents |
-|---|---|
-| `@aotter/mantle` | `createMantle`, `createMantleRuntime`, Store, `Caller`, the handler contract, `withCaller` |
-| `@aotter/mantle/spec` | The manifest grammar, validation and `compilePlan` (the CLI side) |
-| `@aotter/mantle/d1`, `/d1/compile` | The built-in SQLite dialect: runtime and compile sides (ADR-0035) |
-| `@aotter/mantle/postgres`, `/postgres/compile` | The PostgreSQL reference dialect: `postgresStorage`, `pgDatabaseDriver`, `pgPool`, and its compile side (ADR-0037) |
-| `@aotter/mantle/bun` | Native Bun.SQL PostgreSQL, bun:sqlite and Admin assets (ADR-0038) |
-| `@aotter/mantle/cloudflare` | `d1Storage`, `d1Driver`, `r2MediaStorage`, `toCloudflareCron` |
-| `@aotter/mantle/auth` | `createMantleAuth` (Better Auth), `createCallerResolver`, `createAuthRoutes` |
-| `@aotter/mantle/admin` | `createAdminSurface` |
-| `@aotter/mantle/mcp` | `createMcpSurface` |
-| `@aotter/mantle/web` | `createRestSurface` |
-| `@aotter/mantle/testing` | `runStorageConformance`, the dialect compliance suite |
-
-## CLI
+# Mantle
+
+Mantle is an agent-native application SDK and backend compiler. Declare Schemas, Views, Procedures and Triggers in
+YAML manifests; `mantle generate` compiles them at build time into native SQL and typed TypeScript for SQLite (Bun or
+Cloudflare D1) and PostgreSQL (Bun or Cloudflare Workers). The compiler adds row policy to every query, and the closed v2
+grammar reports actionable diagnostics. Your app keeps its own entry, routes and auth; Mantle adds only the surfaces
+you select: REST, MCP, a web module, Better Auth sign-in and the native Admin.
+
+**Start here:** `npx mantle help` prints the installed docs one topic at a time. `mantle init <directory>` writes a
+complete app shell once (email OTP, `admin` + `user`, Admin, MCP, REST); [examples](./docs/examples/README.md) show
+how to combine stock, own-records, approvals, callbacks, public pages and email into it.
+
+Three packages: `@aotter/mantle` is the SDK with bin `mantle`; `@aotter/mantle-ui` is pure UI without an SDK dependency; `@aotter/mantle-admin` is the optional product with the SDK as a peer. Use matching installed versions and their own docs.
+
+Select `--admin` / `admin: true` for [Native Admin](./docs/handbook/guides/native-admin.md).
+Its generated adapter mounts with `entries(bindings.schemas, bindings.adapter)`;
+shared read templates and generated Procedure fragments preserve the native
+row policy and checks without importing generic Store into initial Admin reads.
+
+Build and contributor checks: [CONTRIBUTING](https://github.com/aotter/mantle/blob/develop/CONTRIBUTING.md).
+
+Outputs include `generated.ts`, `schema.sql` and direct operation entries.
+Commit generated output and Wrangler edits; keep `dist/` untracked. Run the same
+generate command with `--check` in CI. Never hand-edit generated files; merge
+manifest/options changes and regenerate. See [service composition](./docs/handbook/cloudflare/service-entry.md)
+for app-owned routing, assets, scheduling, Bun and the generated-output workflow.
+Import `views/<encoded-name>.ts` or `procedures/<encoded-name>.ts` (default export
+and types) to exclude other operations. Apply initial DDL to an empty development
+database; it is not a production migration. Generation performs no database I/O.
+Call `views[name](db, caller, input)` or `procedures[name](db, caller, input)` with
+driver-ready inputs, a native handle (Bun.SQL, bun:sqlite Database or D1 binding)
+and a verified Caller.
+
+Validate untrusted input before calling queries and redact native errors at application
+transports. The [query contract](./docs/handbook/guides/native-execution.md#query-inputs-values-and-outcomes)
+defines driver-ready inputs, native results, date-time/date wire forms and failure handling.
+
+For transports, `paged/views/<name>.ts` returns `{ rows, nextCursor? }` with keyset paging and
+`validation/<kind>/<name>.ts` checks input against the declared JSON Schema subset; the
+[surface deltas](./docs/handbook/reference/surface.md) define the REST/MCP wire contract.
+Proved internal Views also get paging without a public route/tool: one SELECT
+per page, validated scalar cursor keys and hidden-key removal. Schema tuples
+need indexed order after fixed equality prefixes ([index prefixes](./docs/handbook/reference/schema.md#index-prefixes-for-paged-views)); complete groups and singleton
+joins are supported. Grouping still scans/aggregates its source: inspect EXPLAIN.
+Unsupported internal SQL retains its bare module.
+
+Every Schema is a typed **Store** collection:
+`store(db, caller).collection("purchase_requests")` with `findById`, `find` (AND-only `where`, `{ rows, cursor }` keyset pages), `first`,
+`count`, `insert(values)`, OCC `update(id, set, { lock })` and `delete(id, { lock })`. Rows, `where`, `set` and `orderBy` use the
+table's storage column names, lower-case (`requestnumber`, `created_at`), the keys a generated View returns; the generated types
+state column names, value types and the writable columns, and the Store enforces the Schema's row rules (scope, TTL, version) but
+**not** a View's or Procedure's `requires`: authorize before calling it. Design, limits and what the runtime still refuses are in
+[Store guide](./docs/handbook/guides/typed-queries.md).
+
+For simple creates and partial updates, prefer a declared Store-backed ref
+Procedure: await the caller-bound insert/update, return an allowlist with the
+actual returned `id`/`version`, and preserve omitted fields. Keep Procedure
+`requires` and boundary validation; Store row policy is not operation
+permission. Retain SQL Procedures for atomic conditional/multi-entity writes
+such as stock/order changes and additive upserts. D1 batches cannot consume a
+prior step's result and have no interactive transaction callback. See the
+[write design guidance](./docs/handbook/guides/typed-queries.md#prefer-store-backed-ref-procedures-for-simple-writes).
+
+Importing generated modules does not initialize the Store. The first `store()`
+call prepares its metadata factory once; every call binds its own database,
+Caller and handlers. Unused Stores still tree-shake out of direct operations.
+
+`find({ search: "text" })` and `first({ search: "text" })` match an exact id or
+the Schema's `searchableFields`. Search is trimmed, must be non-empty and cannot contain NUL; it
+combines with `where`, scope, TTL and publication rules. SQLite/D1 use the
+generated FTS5 trigram index with maintenance triggers (queries shorter than
+three characters use LIKE); PostgreSQL uses ILIKE without requiring an extension.
+`%`, `_`, quotes and FTS operators are literal text. Schemas without search fields
+match id only. Non-ASCII case folding follows the dialect: SQLite/D1 FTS5
+trigram folds searchable text for queries of three or more characters, while
+shorter SQLite/D1 LIKE queries fold ASCII only; PostgreSQL ILIKE follows the
+database locale/collation. These are the same native differences as 0.2.
+Generated Views reuse Core's `mantle.search(alias, input.q)` and
+`mantle.search_rank(alias)`; ranking requires search on the same alias/query.
+Rank-ordered exposed Views still need supported keyset ordering; use an internal
+View for arbitrary rank ordering. Applying changed search DDL remains the app's
+migration responsibility; no request runs DDL or rebuilds indexes.
+
+## Independently accept user-facing work
+
+Before reporting any user-facing deliverable as done, follow the version-matched
+[independent acceptance guide](./docs/handbook/guides/agent-workflow-acceptance.md)
+with a fresh agent on the surface its user uses. For MCP work, also run the
+guide's design audit before implementing tools; scripted checks remain separate
+evidence.
+
+## Publishing
+
+Schemas default to `lifecycle: operational`. Opt-in `lifecycle: publishing` adds status
+(`draft` default, `published`, `archived`), nullable `published_at` and a scope-aware
+`(published_at, id)` index; `published_at` is selectable in Views and orders Store `find`
+(`NULLS LAST`). Generated `<table>.publish`, `.unpublish` and `.archive` Procedures take
+`{ id, expectedVersion }`, gate admin/system callers and run one atomic UPDATE; a failed guard is
+`CONFLICT`. Store writes cannot set status or `published_at`. Public Views see published rows only;
+other reads expose drafts only to admin or system callers.
+
+## Ref Procedures
+
+A Procedure with a `ref` handler generates a typed `Handlers` interface. `mantle generate` lists the
+handlers to implement; pass them at `store(db, caller, { handlers })` (required by type when the
+manifest declares ref Procedures) and run `tsc --noEmit`. A handler receives `{ caller, db, store }`
+bound to the same caller and transaction; the exported `procedures` map holds SQL Procedures only.
+
+## Workers build
+
+In an application, run generation:
 
 ```sh
-mantle generate           # manifests + mantle.config.json -> .mantle/generated/, and the preset once
-mantle generate --check   # the gate: fails when anything generated is stale
+pnpm exec mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts
+pnpm exec wrangler deploy
+# or: pnpm exec wrangler dev --local
+```
+
+For `cloudflare-d1` and `cloudflare-postgres`, generation configures Wrangler to run
+`mantle bundle <entry> <outdir>` automatically. Node 22.22 or newer is required. Run from the project root;
+regenerate after manifest or auth option changes.
+
+`--entry` defaults to `src/worker.ts`, `--outdir` to `dist`; with `--admin`, `--assets` (Wrangler's `assets.directory`) defaults to `<outdir>/client`. `--wrangler` defaults to the
+existing `wrangler.jsonc`, `wrangler.json` or `wrangler.toml`, otherwise `wrangler.jsonc`.
+JSONC edits preserve comments and unrelated settings and are idempotent. A new config
+needs its `name`, `compatibility_date` and bindings filled in. TOML only prints instructions.
+
+esbuild emits minified split ESM into `<outdir>/worker`; Wrangler uploads it with `no_bundle`,
+`find_additional_modules`, `base_dir` and an ESModule rule. Generation ensures
+`nodejs_compat` and defaults to `global_fetch_strictly_public`, including explicit
+environment flag overrides; see [Workers deployment](./docs/handbook/cloudflare/deploy-and-operate.md).
+The metafile guard rejects `better-auth` / `@better-auth/*` in the static startup graph:
+use `authLoader(() => import(...))` ([Auth](./docs/handbook/cloudflare/authentication.md#worker-entry)).
+The Worker directory is cleaned first; keep source and generated code elsewhere. A Worker that imports
+`@aotter/mantle-admin/server` also gets Admin, built with Vite into `<assets>/admin` (default `<outdir>/client/admin`)
+from `admin.tsx` beside the entry or the built-in entry. The built-in entry is skipped while the installed
+Admin and its direct dependencies are unchanged; an `admin.tsx` entry builds every time.
+
+## D1 Sessions
+
+D1's session handle already satisfies generated Views/Procedures and the Store's structural `db` type:
+
+```ts
+const bookmark = request.headers.get("x-d1-bookmark");
+const session = env.DB.withSession(bookmark ?? "first-unconstrained");
+const rows = await views.catalog(session, caller, {});
+const data = store(session, caller); // use the same handle for Store operations
+return Response.json(rows, { headers: { "x-d1-bookmark": session.getBookmark() ?? "" } });
 ```
 
-While `src/service.ts` does not exist, `mantle generate` writes the service
-preset for the chosen host (ADR-0036): on `cloudflare`, the default,
-`src/service.ts`, `src/index.ts`, `src/handlers.ts`, `wrangler.jsonc`,
-`tsconfig.json`, `.gitignore`, and `.dev.vars.example` with identity `mantle`
-(`src/identity.ts` with `custom`); on `bun`, the same without
-`wrangler.jsonc`, with `.env.example`; on `none`, nothing. It never writes
-those files again, and it never installs packages. It names each missing
-package together with the install command.
+Return `session.getBookmark()` in a header or cookie and have the client pass it back on the next request.
+Keep `resolveCaller` and Better Auth on `env.DB`: revocation and roles must read the primary.
+Enable [read replication](https://developers.cloudflare.com/d1/best-practices/read-replication/)
+on the database (dashboard or REST); writes always go to the primary.
+
+## Store transactions
+
+Writes are lazy thenables: await `collection.insert/update/delete(...)` to execute once,
+or pass unused Writes from the same Store to `store.batch([...])` for atomic results in input order;
+a stale lock, excluded row or unique clash rolls back the whole batch with `CONFLICT`.
+A batch step cannot use a previous step's result. D1 supports only batch.
+On bun:sqlite and PostgreSQL, `store.transaction(async tx => { ... })` binds `collection`, `views`
+and `procedures` to one transaction: resolve commits, throw rolls back; nested transactions and `tx.batch` are refused.
+PostgreSQL defaults to serializable; `{ isolation: "read committed" }` selects another level. There is no automatic retry.
+SQLite uses BEGIN IMMEDIATE and queues all Store/generated driver calls on the same Database until COMMIT/ROLLBACK;
+Inside a transaction callback the outer Store or handle passed to a Mantle driver throws `INPUT_VALIDATION_FAILED`; use `tx`.
+
+Views return rows; Procedures return `{ results }`. See the [query contract](./docs/handbook/guides/native-execution.md#query-inputs-values-and-outcomes)
+for atomicity and uncertain writes.
+
+PostgreSQL handles (Bun.SQL, postgres.js) satisfy the two-method `Postgres` shape as they are; see the [contract](./docs/handbook/guides/native-execution.md).
+Unsupported declarations fail generation with diagnostics;
+see the [supported/refused list](./docs/handbook/reference/features.md) for current scope and planned features.
+
+Native contributor checks run all four hosts with independent SQL oracles and
+fresh PostgreSQL schemas; behavior follows each engine. Local Cloudflare checks
+create no cloud resources. Performance claims need a quiet machine and raw samples.
+The [size and startup gates](./docs/handbook/guides/size-and-startup.md) cover the
+bundle and package budgets. The private compiler ships in this SDK and stays outside request imports.
+
+## Data paths and migrations
 
-## Start
+Writes use Store or declared Procedures, never raw SQL writes that bypass scope, TTL, publishing and system columns. Internal Views are for joins, aggregates, OR and reusable reads. Store findById/find/first remain useful for simple handler lookups and partial adoption in existing TypeScript/Node apps using their own native handle and verified Caller.
 
-Read [the reference service](docs/examples/reference-service/README.md).
-It is a whole service with its smoke test. The installed docs are under
-`node_modules/@aotter/mantle/docs/`: the handbook (`handbook/start/overview.md`),
-the examples, the agent workflow skills (`skills/`), and
-`upgrade-0.1-to-0.2.md` for projects on 0.1.x.
+The runtime never creates, alters or checks tables; boot and requests run no DDL. Apply initial schema.sql plus selected auth/site DDL to an empty database. For each later change, the app's agent diffs regenerated SQL, writes a native migration, rehearses it on a copy and applies it before deploying code. Destructive/type changes need explicit data migration; Mantle drops nothing.
 
-The decisions behind the design are ADR-0032 to ADR-0038 in `docs/adr/`.
+[Drivers are open structural handles; dialects are exactly postgres and sqlite](./docs/handbook/concepts/runtime-and-adapters.md#drivers-and-dialects).

package/dist/auth/adapter.d.ts

@@ -0,0 +1,32 @@
+import type { BetterAuthOptions } from "@better-auth/core";
+import { type Postgres } from "../kernel/contracts.js";
+import * as bunSql from "../kernel/driver/postgres.js";
+import type { Reader } from "../kernel/driver/d1.js";
+/** Runs one statement; `changes` is the affected-row count. */
+type Exec = (text: string, values: unknown[], protectAdmin?: boolean) => ReturnType<typeof bunSql.run>;
+/** Selected auth queries share this adapter's handle, dialect and Better Auth's physical model/field mapping. */
+/** Better Auth's table and column names for these options (modelName/fieldName mapping); needs no database. */
+export declare function authNames(options: BetterAuthOptions): {
+    table: (model: string) => string;
+    column: (model: string, field: string) => string;
+    has: (model: string, field: string) => boolean;
+};
+export declare function nativeAuthRead(options: BetterAuthOptions): {
+    table: (model: string) => string;
+    column: (model: string, field: string) => string;
+    has: (model: string, field: string) => boolean;
+    exec: Exec;
+    param(n: number): string;
+    now(ms: number): Date | string;
+};
+/** The slice of D1 the adapter calls (a real `D1Database` satisfies it). */
+export type D1Like = Reader;
+/** Cloudflare D1 (SQLite). D1 has no interactive transactions, so `transaction` is off and the atomic operations are single statements. */
+export declare function d1Adapter(db: D1Like): (options: BetterAuthOptions) => import("better-auth").DBAdapter<BetterAuthOptions>;
+/**
+ * PostgreSQL through Bun.SQL or postgres.js (the `Postgres` contract the data layer uses). Transactions use `begin`,
+ * which pins every statement to one connection. On Workers, create the postgres.js client per request (or per isolate
+ * with `max: 1`), as for the data layer.
+ */
+export declare function postgresAdapter(sql: Postgres): (options: BetterAuthOptions) => import("better-auth").DBAdapter<BetterAuthOptions>;
+export {};

package/dist/auth/adapter.js

@@ -0,0 +1,288 @@
+/**
+ * Better Auth `database` adapters on the same native handle as the data layer: a Cloudflare D1 binding, or PostgreSQL through Bun.SQL or postgres.js.
+ * No Kysely. Rules (where semantics, joins, field/model mapping, value transforms) come from Better Auth's own
+ * `createAdapterFactory`; this file only turns its already-normalised calls into parameterised SQL.
+ * `consumeOne` and `incrementOne` are single statements: D1 has no transactions, and they guard OTP consumption and
+ * attempt counting.
+ */
+import { createAdapterFactory } from "@better-auth/core/db/adapter";
+import { APIError } from "@better-auth/core/error";
+import { getAuthTables } from "@better-auth/core/db";
+import { resourceSeeds } from "./resource-seeds.js";
+import { ContractError } from "../kernel/contracts.js";
+import { adminOptionsOf } from "./caller.js";
+import * as postgres from "../kernel/dialect/postgres.js";
+import * as sqlite from "../kernel/dialect/sqlite.js";
+import * as bunSql from "../kernel/driver/postgres.js";
+import { condition as spell } from "../kernel/where.js";
+const nativeReaders = new WeakMap();
+/** Selected auth queries share this adapter's handle, dialect and Better Auth's physical model/field mapping. */
+/** Better Auth's table and column names for these options (modelName/fieldName mapping); needs no database. */
+export function authNames(options) {
+    const schema = getAuthTables(options);
+    return {
+        table: (model) => postgres.ident(schema[model].modelName),
+        column: (model, field) => postgres.ident(schema[model]?.fields[field]?.fieldName ?? field),
+        has: (model, field) => field === "id" || !!schema[model]?.fields[field],
+    };
+}
+export function nativeAuthRead(options) {
+    const native = options.database && nativeReaders.get(options.database);
+    if (!native)
+        throw new ContractError("AUTH_CONFIGURATION_ERROR", "OAuth requires Mantle's native auth database adapter.", "auth:database");
+    return { ...native, ...authNames(options) };
+}
+function customAdapter(d, exec, seed, insertOnly = false, options) {
+    const { ident } = d;
+    return ({ getFieldName, schema, getDefaultModelName }) => {
+        const condition = (bind, modelKey, w) => {
+            const col = ident(getFieldName({ model: modelKey, field: w.field }));
+            const { value, operator } = w;
+            const fold = w.mode === "insensitive" && (typeof value === "string" || (Array.isArray(value) && value.every(v => typeof v === "string")));
+            if (operator === "contains" || operator === "starts_with" || operator === "ends_with") {
+                const text = d.escapeLike(String(value));
+                return spell(d, col, "like", operator === "contains" ? `%${text}%` : operator === "starts_with" ? `${text}%` : `%${text}`, bind, fold);
+            }
+            return spell(d, col, operator === "not_in" ? "notIn" : operator, value, bind, fold);
+        };
+        /** Builds one statement (its own parameters) and runs it. `where` is `WHERE (and...) AND (or...)`, the Kysely adapter's grouping; empty without conditions. */
+        const run = (build, protectAdmin = false) => {
+            const values = [];
+            const bind = (value) => (values.push(value === undefined ? null : value), d.param(values.length));
+            const where = (modelKey, conditions, extra) => {
+                const group = (connector) => {
+                    const parts = (conditions ?? []).filter(w => (w.connector === "OR" ? "OR" : "AND") === connector).map(w => condition(bind, modelKey, w));
+                    return parts.length ? `(${parts.join(` ${connector} `)})` : null;
+                };
+                const parts = [group("AND"), group("OR"), extra ?? null].filter(Boolean);
+                return parts.length ? ` WHERE ${parts.join(" AND ")}` : "";
+            };
+            return exec(build({ bind, where }), values, protectAdmin);
+        };
+        const idOf = (modelKey) => ident(getFieldName({ model: modelKey, field: "id" }));
+        /** The WHERE plus `<id> IN (SELECT <id> FROM t WHERE ... LIMIT 1)`: the statement touches at most one row. */
+        const oneRow = (s, table, modelKey, where) => s.where(modelKey, where, `${idOf(modelKey)} IN (SELECT ${idOf(modelKey)} FROM ${ident(table)}${s.where(modelKey, where)} LIMIT 1)`);
+        /** The one row a `RETURNING *` statement changed, else null. */
+        const one = async (build) => ((await run(s => `${build(s)} RETURNING *`)).rows[0] ?? null);
+        /** The columns a write gives (an `undefined` is no value). */
+        const cols = (values) => Object.entries(values).filter(([, v]) => v !== undefined);
+        const assign = (s, values, increment = {}) => [...cols(values).map(([c, v]) => `${ident(c)} = ${s.bind(v)}`), ...Object.entries(increment).map(([c, n]) => `${ident(c)} = ${ident(c)} + ${s.bind(n)}`)].join(", ");
+        const { adminRoles: roles, adminUserIds } = options ? adminOptionsOf({ options }) : { adminRoles: [], adminUserIds: [] };
+        const holdsAdmin = (role) => typeof role === "string" && role.split(",").some(role => roles.includes(role));
+        const field = (name) => getFieldName({ model: "user", field: name });
+        const protects = (modelKey, values) => modelKey === "user" && (roles.length > 0 || adminUserIds.length > 0) &&
+            (!values || values[field("banned")] === true || values[field("banned")] === 1 || Object.hasOwn(values, field("role")) && !holdsAdmin(values[field("role")]));
+        const membership = (s, alias) => '(' + [...roles.map(role => `${d === sqlite ? "instr" : "strpos"}(',' || COALESCE(${alias}.${ident(field("role"))}, '') || ',', ${s.bind(',' + role + ',')}) > 0`), d === sqlite ? "0" : "FALSE"].join(' OR ') + ')';
+        const allowlisted = (s, alias) => `(${[...adminUserIds.map(id => `${alias}.${idOf("user")} = ${s.bind(id)}`), d === sqlite ? "0" : "FALSE"].join(" OR ")})`;
+        const administrator = (s, alias) => `(${membership(s, alias)} OR ${allowlisted(s, alias)})`;
+        const lastAdminGuard = (s, model, keepsAllowlisted = false) => {
+            const table = ident(model), other = '"_mantle_other_admin"', no = d === sqlite ? '0' : 'FALSE';
+            return `(${keepsAllowlisted ? `${allowlisted(s, table)} OR ` : ""}NOT ${administrator(s, table)} OR EXISTS (SELECT 1 FROM ${table} ${other} WHERE ${administrator(s, other)} AND ${other}.${idOf("user")} <> ${table}.${idOf("user")} AND COALESCE(${other}.${ident(field("banned"))}, ${no}) = ${no}))`;
+        };
+        const mutation = async (model, modelKey, where, values) => {
+            const protect = protects(modelKey, values);
+            const keepsAllowlisted = protect && !!values && values[field("banned")] !== true && values[field("banned")] !== 1;
+            if (protect && (where.length !== 1 || where[0].field !== field("id") || where[0].operator && where[0].operator !== "eq"))
+                throw new APIError("FORBIDDEN", { code: "AUTH_DENIED", message: "Destructive admin identity writes require one user id." });
+            const result = await run(s => `${values ? `UPDATE ${ident(model)} SET ${assign(s, values)}` : `DELETE FROM ${ident(model)}`}${s.where(modelKey, where, protect ? lastAdminGuard(s, model, keepsAllowlisted) : undefined)} RETURNING *`, protect);
+            if (protect && !result.changes && (await run(s => `SELECT ${idOf(modelKey)} FROM ${ident(model)}${s.where(modelKey, where, `NOT ${lastAdminGuard(s, model, keepsAllowlisted)}`)} LIMIT 1`)).rows.length)
+                throw new APIError("CONFLICT", { code: "CONFLICT", message: "This is the last admin; promote another admin before removing or banning this one." });
+            return result;
+        };
+        const deleteMany = async ({ model, modelKey = model, where }) => (await mutation(model, modelKey, where)).changes;
+        /** Joined rows come back as flat `__j<i>__<column>` aliases; fold them into `row[joinModel]` (object or array). */
+        const joinColumns = (join) => Object.entries(join).map(([model, config]) => {
+            const fields = schema[config.modelKey ?? getDefaultModelName(model)]?.fields ?? {};
+            return [...new Set(["id", ...Object.entries(fields).map(([field, attr]) => attr.fieldName || field)])];
+        });
+        const foldJoins = (rows, join, idColumn) => {
+            const entries = Object.entries(join);
+            const grouped = new Map();
+            rows.forEach((raw, index) => {
+                const main = {};
+                const joined = entries.map(() => ({}));
+                for (const [key, value] of Object.entries(raw)) {
+                    const m = /^__j(\d+)__(.*)$/s.exec(key);
+                    if (m)
+                        joined[Number(m[1])][m[2]] = value;
+                    else
+                        main[key] = value;
+                }
+                const key = main[idColumn] ?? index;
+                let entry = grouped.get(key);
+                if (!entry) {
+                    entry = { ...main };
+                    entries.forEach(([model, config]) => (entry[model] = config.relation === "one-to-one" ? null : []));
+                    grouped.set(key, entry);
+                }
+                entries.forEach(([model, config], i) => {
+                    const obj = joined[i];
+                    if (!Object.values(obj).some(v => v !== null && v !== undefined))
+                        return;
+                    if (config.relation === "one-to-one")
+                        entry[model] = obj;
+                    else {
+                        const list = entry[model];
+                        if (!list.some(item => item.id !== undefined && item.id === obj.id))
+                            list.push(obj);
+                    }
+                });
+            });
+            return [...grouped.values()];
+        };
+        const select = async (model, modelKey, o) => {
+            const column = (field) => getFieldName({ model: modelKey, field });
+            const sortColumn = o.sortBy?.field ? ident(column(o.sortBy.field)) : null;
+            const order = (prefix = "") => (sortColumn ? ` ORDER BY ${prefix}${sortColumn} ${o.sortBy.direction === "desc" ? "DESC" : "ASC"}` : "");
+            // With a join the primary subquery also needs the id (rows fold by it), every join key and the sort column; they are dropped again below.
+            const wanted = o.select?.length ? o.select.map(column) : null;
+            const needed = o.join ? [column("id"), ...Object.values(o.join).map(c => c.on.from), ...(o.sortBy ? [column(o.sortBy.field)] : [])] : [];
+            const { rows } = await run(s => {
+                const list = wanted ? [...new Set([...wanted, ...needed])].map(ident).join(", ") : "*";
+                const paging = `${o.limit !== undefined ? ` LIMIT ${Math.trunc(o.limit)}` : ""}${o.offset ? ` OFFSET ${Math.trunc(o.offset)}` : ""}`;
+                const primary = `SELECT ${list} FROM ${ident(model)}${s.where(modelKey, o.where)}${order()}${paging}`;
+                if (!o.join)
+                    return primary;
+                const entries = Object.entries(o.join);
+                const names = joinColumns(o.join);
+                // The CTE is MATERIALIZED so an unordered LIMIT picks the same parents in both of its uses. One-to-many: number each parent's joined rows in SQL and keep the first `limit`, so only that many rows ever leave the database.
+                const joinSql = entries.map(([joined, c], i) => {
+                    const source = c.relation === "one-to-one" ? ident(joined)
+                        : `(SELECT *, ROW_NUMBER() OVER (PARTITION BY ${ident(c.on.to)} ORDER BY ${idOf(c.modelKey ?? getDefaultModelName(joined))}) AS "__rn" FROM ${ident(joined)} WHERE ${ident(c.on.to)} IN (SELECT ${ident(c.on.from)} FROM "primary"))`;
+                    return ` LEFT JOIN ${source} AS "j${i}" ON "j${i}".${ident(c.on.to)} = "primary".${ident(c.on.from)}${c.relation === "one-to-one" ? "" : ` AND "j${i}"."__rn" <= ${Math.trunc(c.limit ?? 100)}`}`;
+                }).join("");
+                const joinSelect = entries.flatMap((_, i) => names[i].map(c => `"j${i}".${ident(c)} AS ${ident(`__j${i}__${c}`)}`)).join(", ");
+                return `WITH "primary" AS MATERIALIZED (${primary}) SELECT "primary".*, ${joinSelect} FROM "primary"${joinSql}${order('"primary".')}`;
+            });
+            if (!o.join)
+                return rows;
+            const folded = foldJoins(rows, o.join, column("id"));
+            if (wanted)
+                for (const row of folded)
+                    for (const extra of needed)
+                        if (!wanted.includes(extra))
+                            delete row[extra];
+            return folded;
+        };
+        return {
+            async create({ data, model }) {
+                const given = cols(data);
+                const { rows } = await run(s => `INSERT INTO ${ident(model)}${given.length ? ` (${given.map(([c]) => ident(c)).join(", ")}) VALUES (${given.map(([, v]) => s.bind(v)).join(", ")})` : " DEFAULT VALUES"} ${insertOnly ? "ON CONFLICT DO NOTHING " : ""}RETURNING *`);
+                return rows[0];
+            },
+            async findOne({ model, modelKey = model, where, select: fields, join }) {
+                let row = (await select(model, modelKey, { where, select: fields, limit: 1, join }))[0] ?? null;
+                if (!row && modelKey === "oauthResource" && where?.length === 1 && where[0].field === getFieldName({ model: modelKey, field: "identifier" }) && (!where[0].operator || where[0].operator === "eq") && await seed(where[0].value)) {
+                    row = (await select(model, modelKey, { where, select: fields, limit: 1, join }))[0] ?? null;
+                }
+                return row;
+            },
+            async findMany({ model, modelKey = model, where, limit, select: fields, sortBy, offset, join }) {
+                return (await select(model, modelKey, { where, select: fields, limit, offset, sortBy, join }));
+            },
+            async update({ model, modelKey = model, where, update }) {
+                if (!where.length)
+                    return null;
+                return ((await mutation(model, modelKey, where, update)).rows[0] ?? null);
+            },
+            async updateMany({ model, modelKey = model, where, update }) {
+                return (await mutation(model, modelKey, where, update)).changes;
+            },
+            async delete(options) { await deleteMany(options); },
+            deleteMany,
+            async consumeOne({ model, modelKey = model, where }) {
+                return one(s => `DELETE FROM ${ident(model)}${oneRow(s, model, modelKey, where)}`);
+            },
+            async incrementOne({ model, modelKey = model, where, increment, set }) {
+                return one(s => `UPDATE ${ident(model)} SET ${assign(s, set ?? {}, increment)}${oneRow(s, model, modelKey, where)}`);
+            },
+            async count({ model, modelKey = model, where }) {
+                const { rows } = await run(s => `SELECT COUNT(*) AS "count" FROM ${ident(model)}${s.where(modelKey, where)}`);
+                return Number(rows[0].count);
+            },
+        };
+    };
+}
+function build(d, native, adapterId, adapterName, exec, transaction, options) {
+    const resources = new Map((options.plugins ?? []).flatMap(plugin => plugin.id === "oauth-provider" ? resourceSeeds(plugin.options).map(input => {
+        const resource = typeof input === "string" ? { identifier: input } : input;
+        return [resource.identifier, { resource, options: plugin.options }];
+    }) : []).reverse()); // first configured entry wins, as upstream insertOnly does
+    // ponytail: one seed per identifier per isolate (upstream seeds once per init); disable a configured resource rather than deleting it.
+    const seeded = new Set();
+    let writer;
+    const pending = new Map();
+    const seed = (identifier) => {
+        const configured = resources.get(identifier);
+        if (!configured || seeded.has(identifier))
+            return Promise.resolve(false);
+        let work = pending.get(identifier);
+        if (!work) {
+            work = (async () => {
+                const { resource, options: oauth } = configured;
+                // Match upstream identifier validation and seed row defaults.
+                let valid;
+                try {
+                    valid = oauth.identifierValidator ? !!(await oauth.identifierValidator(identifier)) : !new URL(identifier).hash;
+                }
+                catch {
+                    valid = false;
+                }
+                if (!valid)
+                    throw new APIError("INTERNAL_SERVER_ERROR", { code: "AUTH_CONFIGURATION_ERROR", message: "Configured OAuth resource identifier failed validation." });
+                const now = new Date();
+                const data = {
+                    identifier, name: resource.name ?? identifier,
+                    ...Object.fromEntries(["accessTokenTtl", "refreshTokenTtl", "signingKeyId", "allowedScopes", "customClaims", "metadata"].map(field => [field, resource[field] ?? null])),
+                    signingAlgorithm: resource.signingAlgorithm && ["EdDSA", "ES256", "ES512", "PS256", "RS256"].includes(resource.signingAlgorithm) ? resource.signingAlgorithm : null,
+                    dpopBoundAccessTokensRequired: resource.dpopBoundAccessTokensRequired ?? false, disabled: resource.disabled ?? false,
+                    policyVersion: 1, createdAt: now, updatedAt: now,
+                };
+                // The factory owns ID generation, field mapping and native date/JSON/boolean encoding, including for seeds.
+                writer ??= createAdapterFactory({ config, adapter: customAdapter(d, exec, async () => false, true) })(options);
+                await writer.create({ model: "oauthResource", data });
+                seeded.add(identifier);
+                return true;
+            })().finally(() => pending.delete(identifier));
+            pending.set(identifier, work);
+        }
+        return work;
+    };
+    const config = {
+        adapterId, adapterName, supportsBooleans: native, supportsDates: native, supportsJSON: native, supportsUUIDs: native, transaction,
+        // Bun.SQL returns int8/numeric as strings; a `number` field must reach Better Auth as a number (the rate limiter adds to `lastRequest`). Ids stay strings.
+        customTransformOutput: ({ data, fieldAttributes, field }) => (fieldAttributes.type === "number" && typeof data === "string" && field !== "id" && !fieldAttributes.references ? Number(data) : data),
+    };
+    const factory = createAdapterFactory({ config, adapter: customAdapter(d, exec, seed, false, options) });
+    // Both native adapters implement joins; Better Auth otherwise emulates each joined read with another statement.
+    return (options) => factory({ ...options, advanced: { ...options.advanced, database: { ...options.advanced?.database, joins: options.advanced?.database?.joins ?? true } } });
+}
+/** Cloudflare D1 (SQLite). D1 has no interactive transactions, so `transaction` is off and the atomic operations are single statements. */
+export function d1Adapter(db) {
+    const exec = async (text, values) => {
+        const { results, meta } = await db.prepare(text).bind(...values).all();
+        return { rows: results, changes: meta.changes };
+    };
+    const factory = (options) => build(sqlite, false, "d1", "Mantle D1 Adapter", exec, false, options)(options);
+    nativeReaders.set(factory, { exec, param: sqlite.param, now: ms => new Date(ms).toISOString() });
+    return factory;
+}
+/**
+ * PostgreSQL through Bun.SQL or postgres.js (the `Postgres` contract the data layer uses). Transactions use `begin`,
+ * which pins every statement to one connection. On Workers, create the postgres.js client per request (or per isolate
+ * with `max: 1`), as for the data layer.
+ */
+export function postgresAdapter(sql) {
+    const executor = (handle) => async (text, values, protectAdmin) => {
+        const run = async (tx) => {
+            if (protectAdmin)
+                await tx.unsafe("SELECT pg_advisory_xact_lock(1296125516,1)", []);
+            return bunSql.run(tx, text, values);
+        };
+        return protectAdmin && handle === sql ? sql.begin("read write", tx => run(tx)) : run(handle);
+    };
+    const make = (handle, transaction) => (options) => build(postgres, true, "postgres", "Mantle PostgreSQL Adapter", executor(handle), transaction, options)(options);
+    const factory = (options) => make(sql, async (cb) => sql.begin("read write", tx => cb(make(tx, false)(options))))(options);
+    nativeReaders.set(factory, { exec: executor(sql), param: postgres.param, now: postgres.now });
+    return factory;
+}

package/dist/auth/admin.d.ts

@@ -0,0 +1,3 @@
+import { type Caller } from "../kernel/contracts.js";
+/** Shared selected-boundary guard. Resolve fresh database authority only for Better Auth's raw admin endpoints. */
+export declare function guardAuthAdminRequest(request: Request, resolve: () => Caller | Promise<Caller>, basePath?: string): Promise<void>;

package/dist/auth/admin.js

@@ -0,0 +1,21 @@
+import { checkOrigin, isAdmin, deny, ContractError } from "../kernel/contracts.js";
+/** Shared selected-boundary guard. Resolve fresh database authority only for Better Auth's raw admin endpoints. */
+export async function guardAuthAdminRequest(request, resolve, basePath = "/api/auth") {
+    let path;
+    try {
+        path = decodeURIComponent(new URL(request.url).pathname).replace(/\/{2,}/g, "/");
+    }
+    catch { }
+    if (path === undefined || path.split("/").some(part => part === "." || part === ".."))
+        throw new ContractError("INPUT_VALIDATION_FAILED", "Malformed auth path.", "request:path");
+    const admin = `${basePath.replace(/\/+$/, "")}/admin`;
+    if (path !== admin && !path.startsWith(`${admin}/`))
+        return;
+    const caller = await resolve();
+    // Mantle policy: only the admin layer reaches Better Auth admin endpoints (oauth-provider's /admin/oauth2/* admits any
+    // session by default); Better Auth access control then decides each action.
+    // Any signed-in user may ask about their own permissions or end an impersonation.
+    const own = path === `${admin}/has-permission` || path === `${admin}/stop-impersonating`;
+    deny(caller, caller.kind === "user" && caller.credential === "session" && (own || isAdmin(caller)), "auth:admin");
+    checkOrigin(request, caller);
+}