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

package/README.md

@@ -1,319 +1,187 @@
-# @aotter/mantle
-
-Umbrella entry for the embeddable Mantle SDK — a manifest-driven application
-engine built around a 4-atom YAML model (Schema / View / Procedure / Trigger)
-where agents write config and the runtime carries the complexity.
-
-> Mantle's first stable release is `0.1.2`. Use this package's `package.json`
-> as the exact installed version.
-
-## Install
-
-An agent can install the small bootstrap skill:
+# 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
-npx skills add aotter/mantle
-```
-
-For a new application, resolve one published stable version and install it
-exactly. `mantle generate` will declare matching selected packages:
-
-```bash
-MANTLE_VERSION=$(npm view @aotter/mantle@latest version)
-npm install --save-exact "@aotter/mantle@$MANTLE_VERSION"
-```
-
-## What's inside
-
-The umbrella provides Spec and Runtime by default. Install an optional package
-before importing its matching Web, Admin, Auth, Bun, Vercel, Cloudflare, or Admin UI
-subpath. Every sub-package also remains directly installable.
-
-| Subpath | Re-exports |
-|---|---|
-| `@aotter/mantle/spec` (or root) | Manifest grammar, validators, JSON-Schema→Zod, diagnostic catalog (no env / no IO) |
-| `@aotter/mantle/runtime` | Hexagonal runtime: domain ports, use cases, infrastructure helpers (no adapter deps) |
-| `@aotter/mantle/runtime/testing` | Node-only crowded SQLite planner and HTTP sampling helpers |
-| `@aotter/mantle/codegen` | Pure linked manifests or compiled plan → typed runtime module emitter (no IO) |
-| `@aotter/mantle/web` | Optional HTML, Markdown, `llms.txt`, sitemap, SEO, and preview composition (no routes or platform deps) |
-| `@aotter/mantle/admin` | Optional Admin API, auth routes, and static-asset composition |
-| `@aotter/mantle/auth` | Optional host-neutral Better Auth identity; adapters own IP headers and storage bindings |
-| `@aotter/mantle/bun` | Bun adapter — caller-owned `bun:sqlite` and Web-standard View/Trigger transport |
-| `@aotter/mantle/vercel` | Vercel Functions adapter — injected durable storage and platform `waitUntil` |
-| `@aotter/mantle/vercel/libsql` | Optional application-owned Turso/libSQL driver |
-| `@aotter/mantle/cloudflare` | Cloudflare Workers adapter — D1, Workers Cache, R2, and Better Auth 1.7 MCP/CIMD |
-| `@aotter/mantle/admin-ui` | Pre-built React 19 admin SPA bundle |
-
-```ts
-import { linkManifestSet, parseManifestSources } from "@aotter/mantle/spec";
-import { bootMantleRuntime, compileRuntimePlan } from "@aotter/mantle/runtime";
-import { createMantleWeb } from "@aotter/mantle/web";
-import { mountRuntimeEndpoints } from "@aotter/mantle/cloudflare";
-```
-
-The umbrella installs only Spec and Runtime. Web, Admin, Auth, Admin UI, Bun,
-Vercel, and Cloudflare are optional peers; install only the subpaths selected
-by the application.
-
-The package also installs `mantle` and `mantle-harness`:
-
-```bash
-pnpm exec mantle generate
-pnpm exec mantle generate --check
-pnpm exec mantle skills
-pnpm exec mantle skills --check
-pnpm exec mantle-harness indexes --require-public
-pnpm exec mantle-harness http --base-url http://127.0.0.1:8787 --route page=/en/example
-```
-
-`mantle generate --host cf` or `--host chatgpt-sites` assembles a new blank
-app with Spec, Runtime, API, MCP, Admin and Web by default. Use `--features`
-to select a smaller set, including host-free Spec-only. The first run declares
-matching optional dependencies; install them, then rerun. In an existing
-direct-authored app, `generate` keeps its compile behavior: validate
-`./manifests/` and write `.mantle/generated/mantle.ts`. Selected Admin syncs
-its prebuilt SPA to `public/_mantle/admin/`. Generation does not deploy.
-The same pure emitter is available from `@aotter/mantle/codegen` when a host
-wants to own parsing and filesystem IO. TypeScript-authored manifests can pass
-their already-compiled `plan` directly:
-
-```ts
-import { emitMantleModule } from "@aotter/mantle/codegen";
-
-const emitted = emitMantleModule({ plan });
-if (!emitted.ok) throw new Error(emitted.diagnostics.map(({ message }) => message).join("\n"));
-```
-
-```ts
-import { createMantle } from "../.mantle/generated/mantle.js";
-
-const mantle = await createMantle({ storage, handlers, ports });
-const notes = await mantle.views.publishedNotes();
-const result = await mantle.procedures.expireOrder(
-  { orderId },
-  { user: null, staff: null, env },
-);
-await mantle.entries.orders.createDraft({ data, authorId: user.id });
-
-// The typed projection never hides the underlying Core runtime.
-await mantle.runtime.archive.execute({ id: noteId, ctx });
+pnpm exec mantle generate cloudflare-d1 generated manifests/*.yaml --auth src/auth.ts
+pnpm exec wrangler deploy
+# or: pnpm exec wrangler dev --local
 ```
 
-Generated property names are deterministic lower-camel identifiers; calls keep
-the authored wire names internally. `createMantle()` eagerly prepares once and
-does not cache or retry. Dynamic and platform hosts can keep their own lifecycle,
-use generated `bindMantle(runtime)`, or skip code generation and call
-`runtime.executeView({ view: "published-notes" })` directly.
-
-Start with [Project layout and CLI](docs/handbook/start/project-and-cli.md).
-The [local Admin OTP](docs/handbook/start/quickstart-admin.md) tutorial remains
-for apps that own their Worker entry. Generated apps start with an editable
-blank home and no invented business Schema.
+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.
 
-`mantle skills` copies every skill the installed package marks
-`projection: project` in its front matter into matching
-`.agents/skills/mantle-*` and `.claude/skills/mantle-*` paths — no list of
-skill names is maintained anywhere else. Skills that act destructively or
-target one platform stay out of that set and are opt-in. Both tool layouts
-receive identical bytes; `--check` detects drift without writing. An older
-project may also carry `.agent/skills/`, which is left untouched. Manifest
-generation never rewrites agent instructions.
+`--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.
 
-SDK upgrades use the package manager and the version-matched update skill.
-For npm peer-resolution troubleshooting, see [the authoring guide](docs/handbook/start/project-and-cli.md).
-See [Releases](docs/handbook/releases/index.md) for what each stable version
-contains and what it requires.
+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.
 
-## Conventional Cloudflare Worker
+## D1 Sessions
 
-The normal Worker entry delegates Core-owned assembly to the SDK:
+D1's session handle already satisfies generated Views/Procedures and the Store's structural `db` type:
 
 ```ts
-import { createMantleWorker } from "@aotter/mantle/cloudflare";
-import { plan } from "../.mantle/generated/mantle.js";
-
-export default createMantleWorker({ plan });
-```
-
-`createMantleWorker` owns conventional D1/assets bindings, Auth, Admin,
-manifest REST/HTTP routes, OAuth, MCP, cache safety, and rejection-safe
-per-isolate boot. Use its single `extend` seam for application handlers and
-new Hono routes; use the public low-level exports when the deployment does not
-fit the conventional binding or lifecycle contract.
-
-Conventional Auth requires an explicit `MANTLE_AUTH_MODE`: `self-managed`
-uses the site's GitHub OAuth credentials, while `hosted` uses a same-origin
-Mantle Hosted Auth PKCE client. Missing, invalid, partial, or mixed-mode
-configuration keeps public routes available but returns `503 setup_incomplete`
-from Auth-owned private routes. Pass `auth: (env) => Auth` only when the site
-needs to replace this conventional factory; Core still owns the Auth routes.
-The exact bindings and validation rules are in the
-`node_modules/@aotter/mantle-cloudflare/README.md`, under “Conventional Auth”
-(path relative to the application root).
-
-Extensions may add routes but may not replace Core surfaces. These paths are
-reserved:
-
-- `/admin` and `/admin/*`
-- `/_mantle` and `/_mantle/*`
-- `/api/auth` and `/api/auth/*`
-- `/api/views` and `/api/views/*`
-- `/oauth` and `/oauth/*`
-- `/mcp` and `/mcp/*`
-- `/.well-known/oauth*`
-- global `*` and `/*` handlers
-
-A custom Auth factory's `basePath` and exact manifest-owned method/path pairs
-are also reserved at assembly. Static literal conflicts fail TypeScript during
-the consumer build. Computed paths cannot be proven statically, so the facade
-checks Hono's assembled route table and fails closed before serving requests.
-There is no standard-route override option.
-
-Cloudflare projects may expose an independently installed Admin bundle and the
-application's own frontend assets through one native binding:
-
-```toml
-[assets]
-directory = "./public"
-binding = "ASSETS"
-```
-
-Declare browser, Admin, and MCP identity once. Multiple renditions are allowed;
-keep SVG as the source and add PNG renditions when a target MCP client requires
-the baseline raster formats:
-
-```ts
-siteDefaults: {
-  icons: [
-    { src: "/site-icon.png", mimeType: "image/png", sizes: ["64x64"] },
-    { src: "/site-icon.svg", mimeType: "image/svg+xml", sizes: ["any"] },
-  ],
-}
-```
-
-Keep both files in the project's `public/` directory. They are one site
-identity reused by browser favicons, Admin chrome, and MCP `serverInfo.icons`;
-PNG is the compatibility rendition and SVG remains the editable source.
-
-For an uncommon deployment that must own the top-level assembly, use the
-embedded [`docs/handbook/cloudflare/low-level-composition.md`](docs/handbook/cloudflare/low-level-composition.md)
-fixture. It composes the same public primitives without importing package
-internals or rebuilding Mantle's adapters.
-
-## Getting started
-
-Cold start from GitHub or a marketplace host:
-
-```sh
-npx skills add aotter/mantle
+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() ?? "" } });
 ```
 
-That skill interviews, pins this package, then uses the CLI and the
-[direct-authoring guide](docs/handbook/start/project-and-cli.md).
-The owner or agent writes the application's manifests, entry and configuration;
-`generate` compiles them and `skills` projects the version-matched instructions.
-The [minimal Worker reference](docs/examples/host-minimal-worker/README.md) is
-the embed / adapter path without Admin. The
-[local Admin OTP reference](docs/examples/host-local-admin-otp/README.md) is the
-opt-in Dev UI path. Neither is a scaffold command. Admin is optional.
+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.
 
-## Agent marketplace install
+## Store transactions
 
-Install the Mantle Core skill bundle before authoring or maintaining a
-consumer application. The canonical command is:
+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`.
 
-```sh
-npx skills add aotter/mantle
-```
-
-Claude Code and Codex can install the plugin, then run that skill:
+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.
 
-```bash
-# Claude Code
-/plugin marketplace add aotter/mantle
-/plugin install mantle@mantle
+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.
 
-# Codex
-codex plugin marketplace add aotter/mantle
-codex plugin add mantle@mantle
-```
+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.
 
-Cursor and VS Code Copilot can auto-discover the GitHub repo through
-`.cursor-plugin/plugin.json` and `.copilot-plugin/plugin.json` after the repo
-is cloned or opened. Still start from the `npx skills add` sentence (or open
-`skills/install/SKILL.md`). Untagged `aotter/mantle` resolves to `main`, which
-can contain a source-only hotfix ahead of the latest npm release. Add
-`@vX.Y.Z` only to reproduce an older project; never point a consumer at
-`develop` or another moving branch.
+## Data paths and migrations
 
-## Marketplace capability installs
+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.
 
-In a consumer application, tell your coding agent:
-
-```txt
-Use repo-local mantle:plugin to install <plugin slug or recipe URL> in this repo.
-Use repo-local mantle:plugin to update <plugin id> in this repo.
-Use repo-local mantle:plugin to remove <plugin id> from this repo.
-```
+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.
 
-Mantle marketplace entries are agent-installable recipes. They declare the
-plugin source, Mantle version range, files/atoms/routes/tools, adapter
-requirements, secrets, and checks. The agent applies the recipe through the
-Core-owned `mantle:plugin` skill and records it in `.mantle/plugins.json` plus
-`.mantle/plugins.lock.json`. There is no `mantle plugin add` CLI yet.
-
-## Adapter targets
-
-| Adapter | Status |
-|---|---|
-| Bun | ✅ shipping |
-| Vercel Functions (Node.js) | ✅ shipping |
-| Cloudflare Workers | ✅ shipping |
-
-The `mantle-runtime` package never imports platform-specific types — adapters
-bind concrete storage and lifecycle primitives to Core ports, so adding a new
-adapter is a port-implementation exercise, not a runtime refactor.
-
-## Documentation
-
-- The handbook is the user documentation and ships inside this npm package:
-  `node_modules/@aotter/mantle/docs/handbook/` (start, concepts, Cloudflare
-  guides, example redirects, reference; `navigation.json` lists every page in order).
-  Worked Manifests live in `node_modules/@aotter/mantle/docs/examples/`
-  ([index](docs/examples/README.md)).
-  The copy in `node_modules` describes the installed release.
-- Embedded docs and agent skills ship inside this npm package for
-  agents working from the installed package:
-  - `node_modules/@aotter/mantle/docs/handbook/reference/manifest.md`
-  - `node_modules/@aotter/mantle/docs/examples/cf-primitives-guarded-api.md` (anonymous,
-    API-key, paid guard, personal-token, OAuth, REST, and MCP examples)
-  - `node_modules/@aotter/mantle/docs/handbook/cloudflare/media-r2.md` (Cloudflare R2 adapter recipe)
-  - `node_modules/@aotter/mantle/docs/handbook/cloudflare/deferred-hooks-queues.md` (versioned
-    Queue wiring, retry/DLQ, idempotency, and delivery guarantees)
-  - `node_modules/@aotter/mantle/docs/handbook/reference/schema.md` (Schema grammar,
-    ordered composite JSON-field indexes and the safe Procedure SQL helper)
-  - `node_modules/@aotter/mantle/docs/performance-harness.md` (crowded SQLite,
-    Wrangler-local D1 origin paths and coding-agent guardrails)
-  - `node_modules/@aotter/mantle/docs/adr/`
-  - `node_modules/@aotter/mantle/skills/develop/SKILL.md`
-  - `node_modules/@aotter/mantle/skills/plugin/SKILL.md`
-  - `node_modules/@aotter/mantle/skills/theme/SKILL.md`
-  - `node_modules/@aotter/mantle/skills/update/SKILL.md`
-  - `node_modules/@aotter/mantle/skills/install/SKILL.md`
-  - `node_modules/@aotter/mantle/skills/provision/SKILL.md`
-- [4-atom manifest model (ADR-0001)](docs/adr/0001-four-atom-manifest-model.md)
-- [API and MCP authorization](docs/examples/cf-primitives-guarded-api.md)
-- [Deferred lifecycle Queues](docs/handbook/cloudflare/deferred-hooks-queues.md)
-- [Schema indexes on D1](docs/handbook/reference/schema.md)
-- [Release process](docs/release-process.md)
-- [Source repository](https://github.com/aotter/mantle)
-- [Issues](https://github.com/aotter/mantle/issues)
-
-## License
-
-Apache-2.0
-
-Pure extension routes do not await content preparation. Before an extension
-uses Mantle data or database-backed Auth, await its supplied `getRuntime()`
-(or `ref.get()`). Standard protected routes establish this readiness themselves;
-queue/scheduled handlers continue to use `worker.getRuntime(env)`.
+[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 {};