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

package/docs/handbook/concepts/runtime-and-adapters.md

@@ -1,198 +1,30 @@
 ---
-description: How createMantle boots the runtime from a storage adapter, how storage converges to the plan, the D1 and PostgreSQL dialects, and the fingerprint handshake.
+description: Native execution, database handles, two SQL dialects and application-owned migrations.
 ---
-# Runtime, Store and dialects
+# Runtime and databases
 
-```
-src/index.ts (host entry) ─▶ mantle = createMantle(service, { plan, storage, schedules })
-                                 │ first request: createMantleRuntime → storage.prepare(plan)
-                                 ▼
-service.fetch(request, env, { runtime, waitUntil })
-  └ surfaces / your routes ─▶ runtime.invokeProcedure · runtime.store
-                                 └ Store: policy rewrite → dialect check → StoreExecutor
-```
+`mantle generate` compiles manifest SQL and row policy into ordinary TypeScript and SQL. Generated Views and Procedures call the target's native driver. The app owns routing, authentication, handles, connection lifetime and deployment. Import only the operations and surfaces you use.
 
-## `createMantle`
+## Schema installation and migrations
 
-```ts
-createMantle(service, { plan, storage: (env) => MantleStorageAdapter, schedules?, expectedFingerprint? })
-// → { fetch(request, env, ctx?), invokeSchedule(cron, scheduledTime, env, ctx?), runDeferredHook(message, env, ctx?) }
-// runDeferredHook replays an after-hook Invocation from your own queue; nothing in Mantle emits one
-```
+The runtime never creates, alters or checks tables. Boot and requests run no DDL, introspection or schema checks.
 
-- `service` is `{ handlers, fetch(request, env, { runtime, waitUntil }) }`, a
-  WinterTC fetch the application owns. Mantle owns no route of its own: the
-  service decides what is mounted where.
-- The runtime boots lazily on the first call, once per isolate. A failed boot
-  is retried by the next request.
-- Each entry call binds its own `ctx.waitUntil` to the runtime facade handed
-  to the service. Handler calls, nested invocations and Store lifecycle hooks
-  retain work on that entry's context, including concurrent requests. Calls
-  without a context do not borrow another request's retainer.
-- `invokeSchedule` runs every enabled schedule Trigger whose cron is exactly
-  the given POSIX expression, as the system caller.
-- The host entry is a few lines the generator writes once
-  ([The service and its entry](../cloudflare/service-entry.md)); Core handles
-  no platform event types.
+For the first install, apply generated `schema.sql`, including selected auth/site DDL, to an empty database. Apply selected seed SQL explicitly.
 
-`createMantleRuntime(args)` is the same boot without the service, for tests
-and custom hosts. The runtime exposes `plan`, `store`, `invokeProcedure`,
-`bootReport()` (`{ fingerprint, coreVersion }`) and, with site defaults,
-`site`.
+For every later schema change, the application's coding agent diffs the regenerated `schema.sql`, writes a migration with the host's native tool (`wrangler d1 migrations` or the app's PostgreSQL migration tool), rehearses it on a copy, and applies it before deploying the new code.
 
-## Boot checks
+Destructive changes and type changes need explicit data migration. Mantle drops nothing. Initial `schema.sql` is not an upgrade script.
 
-Boot refuses to serve when:
+## Drivers and dialects
 
-- a plan `ref` has no handler (`HANDLER_NOT_REGISTERED`), or a handler is not
-  in the plan (`HANDLER_NOT_DECLARED`);
-- the plan was compiled for another dialect, or does not match
-  `expectedFingerprint` (`PLAN_FINGERPRINT_MISMATCH`);
-- an enabled schedule exists without `schedules: true` (`SCHEDULE_NOT_WIRED`);
-- storage has a change it cannot make (`STORAGE_CHANGE_BLOCKED`), or a table
-  Mantle would create already exists without being Mantle's
-  (`STORAGE_TABLE_NOT_OWNED`).
+The driver layer is open: handles are structural contracts, not a registration API. PostgreSQL needs `unsafe(text, values)` and `begin(options, fn)` from `@aotter/mantle/contracts`; SQLite uses D1's prepare/bind/all/batch shape or bun:sqlite's query/transaction shape. Bun.SQL and postgres.js fit directly. See [adapting a driver](../guides/postgres-adapters.md).
 
-## Storage converges to the plan
+Users may supply anything that executes the emitted SQL, including WASM SQLite persisted to IndexedDB, at their own risk. Mantle promises behavior only on supported drivers: bun:sqlite, D1, Bun.SQL and postgres.js. A structural match alone does not prove transaction, result or error semantics.
 
-There are no migration files for Schema tables. When the plan's fingerprint
-differs from the one the database last booted, boot reads the database's
-actual tables and indexes, compares them with the plan, and:
+The dialect layer is closed in 0.2.0: exactly `postgres` and `sqlite`, selected by the generation target. SQL is rendered at generation time. A third engine requires forking the compiler and Store runtime; it is not a dialect plugin.
 
-| Difference | Boot |
-|---|---|
-| a missing table, field column, index, or unique index that builds | creates it (on SQLite, `STRICT` tables with their check and FTS triggers) |
-| a unique index that fails on existing rows, a column with another type, a changed index, a missing native column | refuses with `STORAGE_CHANGE_BLOCKED`, naming the change and a SQL hint |
-| a column or non-unique index the plan no longer declares | keeps it and warns; nothing is ever dropped |
+## Store and queries
 
-A renamed field is a new empty column beside the old one: copy the data
-yourself. A blocked change is the author's to make (SQL through the host's own
-tool, a data-copy Procedure, a dedupe), then boot checks again. With the same
-fingerprint boot reads nothing. `mantle generate --check --database <file>`
-prints the same diff against a local database without applying it.
+Use the [Store for writes and simple lookups, internal Views for richer reads](../guides/typed-queries.md). Store metadata initializes once on first `store()` use without SQL. Each call binds a fresh handle, verified Caller and handlers; never reuse a caller-bound Store across requests.
 
-Mantle's own tables (`_mantle_*`) and its product tables (`site_config`,
-`media_assets`, `pending_media_uploads`) keep versioned migrations of their
-own. Identity `mantle` migrates Better Auth's tables through Better Auth.
-
-## The D1 dialect
-
-The SQL language is PostgreSQL syntax, pinned to PostgreSQL 18's parser. A
-**dialect** decides which of it an engine runs and how. The built-in dialect,
-`@aotter/mantle/d1`, runs on SQLite as D1 does: its compile side refuses what
-D1 cannot compute exactly, and its runtime side prints SQLite, encodes types
-and converges storage.
-
-- `date-time` (and `created_at` / `updated_at`) is stored as microseconds,
-  `date` as days, `numeric(p, s)` as an integer of the smallest unit, so
-  arithmetic is exact on D1. On the wire a date-time is an ISO string.
-- `checks` are enforced by triggers. `x-mantle-ref` is checked by
-  `mantle generate` and used by Admin; storage does not enforce it in 0.2.0.
-  `searchableFields` uses
-  an FTS5 trigram index; `format: geo` uses an R*Tree.
-- `date_trunc` and `extract` compute in the site time zone
-  (`d1Storage(db, { timeZone })`, default UTC).
-
-`mantle.config.json` names the dialect (`sqlite`, `postgres`, or another dialect package, which must pass
-`runStorageConformance` from `@aotter/mantle/testing`). A plan records its
-dialect, and boot refuses a plan compiled for another one.
-
-## The PostgreSQL dialect
-
-`"dialect": "postgres"` in `mantle.config.json` compiles the plan for
-PostgreSQL (13 or later). On Cloudflare, `mantle generate --dialect postgres`
-writes the preset over Hyperdrive; on any other platform, add `"host": "none"`
-and compose `createMantle` with `postgresStorage` yourself (ADR-0036). PostgreSQL
-is Mantle SQL's reference dialect (ADR-0037): it accepts D1's subset without
-SQLite's own `typeof`, `hex`, `json_extract`, `json_set`, `json_insert` and
-`json_remove` (write `x ->> '$.path'`), plus `WITH`, set operations, `LATERAL`,
-window frames, `FILTER`, jsonb operators and the rest of the
-[View reference](../reference/view.md)'s PostgreSQL table. A manifest that uses
-them no longer compiles for D1; one that does not moves between engines with a
-recompile.
-
-- Columns have native types: `timestamptz`, `date`, `numeric(p, s)`, `boolean`,
-  `jsonb`, `bigint` and `double precision`. Values are decoded by the type
-  PostgreSQL reports, so computed outputs (`now()`, `date_trunc`, a `CAST`) come
-  back as wire values too: ISO date-times, booleans, parsed JSON.
-- Every write batch is one `SERIALIZABLE` transaction, retried on a
-  serialization failure, so a guard such as `WHERE NOT EXISTS` holds under
-  concurrent writers as it does on SQLite's single writer.
-- `checks` are `CHECK` constraints added `NOT VALID`: they bind every later
-  write and leave older rows alone, like D1's triggers.
-- `json_each`, `->>` and `CAST(x AS bool)` read as they do on D1 through small
-  SQL functions Mantle creates (`_mantle_json_each`, `_mantle_jget`,
-  `_mantle_bool`). `json_group_array` and `json_group_object` order by value.
-- Results match D1 where Mantle decides them. Text columns use `COLLATE "C"`,
-  so they compare by code point. An `ORDER BY` key without `NULLS FIRST/LAST`
-  puts NULL first ascending, as Core pages every View. Values never depend on
-  the server's `DateStyle`, `IntervalStyle` or `TimeZone`. Elsewhere the meaning
-  is PostgreSQL's, where D1 differs:
-  - `LIKE` is case-sensitive.
-  - Division by zero is an error.
-  - `->>` returns text.
-  - `||` prints booleans and floats as PostgreSQL does.
-- `searchableFields` and `mantle.near()` scan without an index in 0.2.0, and
-  `mantle.search_rank()` counts occurrences rather than computing bm25.
-  Site settings and media are SQLite-only (D1, bun:sqlite).
-- `date_trunc` and `extract` compute in the site time zone
-  (`postgresStorage({ connect, timeZone })`, default UTC).
-- Every statement has a `statement_timeout` of 10 seconds, pinned in each
-  transaction (`statementTimeoutMs`; 0 is none). Storage convergence has none.
-  A statement past it fails with `RESOURCE_UNAVAILABLE` and writes nothing.
-- Connect as a role that owns the service's tables but is not a superuser and
-  holds no file or server privilege (`pg_read_server_files`,
-  `pg_execute_server_program`). Mantle's allowlist refuses such functions; the
-  role is the second line.
-
-## Storage adapters
-
-| Adapter | From | Driver |
-|---|---|---|
-| `d1Storage(env.DB, { timeZone?, site? })` | `@aotter/mantle/cloudflare` | Cloudflare D1, the one the preset uses |
-| `sqliteStorage(driver, { timeZone?, maxBindings?, site?, restrict? })` | `@aotter/mantle/d1` | any `DatabaseDriver`: `{ batch(statements) }`, all or nothing |
-| `postgresStorage({ connect, timeZone?, statementTimeoutMs?, restrict? })` | `@aotter/mantle/postgres` | `connect` opens one node-postgres (`pg`) client; Hyperdrive on Workers |
-| `bunPostgresStorage(sql, { timeZone?, statementTimeoutMs?, restrict? })` | `@aotter/mantle/bun` | a Bun.SQL pool with `prepare: false`; its role needs TEMPORARY (ADR-0038) |
-| `bunSqliteStorage(db, { timeZone?, site?, restrict? })` | `@aotter/mantle/bun` | a bun:sqlite `Database`; foreign keys are turned on |
-
-`restrict(plan, context)` returns refusals of its own, run after the dialect's
-on every program at runtime. It only narrows what runs, for an operator that
-runs other people's plans; a self-hosted service leaves it out (ADR-0037).
-
-On Workers, PostgreSQL goes through Hyperdrive, which pools the connections, so
-`connect` opens a client per operation (a socket must not outlive its request):
-
-```ts
-import pg from "pg";
-import { pgDatabaseDriver, pgPool, postgresStorage } from "@aotter/mantle/postgres";
-
-const connect = (env: Env) => async () => {
-  const client = new pg.Client({ connectionString: env.HYPERDRIVE.connectionString });
-  await client.connect();
-  return client;
-};
-// storage: (env) => postgresStorage({ connect: connect(env) })
-// identity: createMantleAuth({ database: pgPool(connect(env)), driver: pgDatabaseDriver(connect(env)), ... })
-```
-
-The Worker needs `compatibility_flags: ["nodejs_compat"]` for `pg`. Mantle runs
-every read in a transaction, which Hyperdrive never answers from its cache.
-Better Auth's reads (sessions, roles) do not, so create the Hyperdrive config
-with caching disabled (`wrangler hyperdrive create … --caching-disabled`), or a
-revoked session can be accepted until the cache expires. `timeZone` must be an
-IANA name: PostgreSQL reads an offset such as `+08:00` with the opposite sign.
-
-Bun has a generated preset for both engines (`mantle generate --host bun`,
-ADR-0038); `bunDatabaseDriver` / `bunAuthDatabase` and `bunSqliteDriver` give
-Better Auth the same store. A `DatabaseDriver` is one method, so another engine
-(libSQL, for example) is a few lines of application code on `host: none`: the
-entry calls `createMantle` and its own server.
-
-`site` turns on the site capability (site settings and media); see
-[Site defaults and site_config](../reference/site-config.md).
-
-## Testing a service
-
-Run the service under `wrangler dev` against a fresh local D1 and drive it over
-HTTP, as the [reference service](../../examples/reference-service/README.md)'s
-`smoke.mjs` does.
+[Native execution](../guides/native-execution.md) defines input ownership, native result values, atomicity and uncertain write outcomes.

package/docs/handbook/concepts/views.md

@@ -1,116 +1,17 @@
----
-description: How a View's SQL SELECT is compiled, which policies the runtime injects, and how REST, MCP, Admin and Store serve it with limit and cursor paging.
----
 # Reads: Views, REST and MCP
 
-A View is one SQL `SELECT` in PostgreSQL syntax over declared Schemas.
+A View declares one PostgreSQL-syntax SELECT over declared Schemas or reusable internal Views. Generation parses, checks and lowers it for postgres or sqlite, adds row policy, and emits a typed function. Requests bind values and execute SQL; they do not parse or compile manifests.
 
-```yaml
-apiVersion: cms.mantle.aotter.net/v2
-kind: View
-metadata: { name: my-orders }
-spec:
-  surface: public
-  requires: { auth: { all: [ctx.user] } }
-  sql: |
-    SELECT o.id, o.qty, o.orderStatus, i.name AS item, o.version
-    FROM orders o JOIN items i ON i.id = o.itemId
-    ORDER BY o.created_at DESC
-```
+Use internal Views for joins, aggregates, OR and reusable reads. Simple handler id lookups and AND filters can use Store. See [query from TypeScript](../guides/typed-queries.md) for a complete example.
 
-## Compiled once, checked at every run
+| Surface | Exposure when mounted |
+| --- | --- |
+| public | REST `/api/views/<name>` and public MCP |
+| admin | Admin View API and admin MCP |
+| internal | Generated operation only; no public route/tool |
 
-`mantle generate` parses the SQL with PostgreSQL's own parser, refuses what the
-dialect does not support (with the position in the statement), and stores the
-parse tree as the View's IR in the plan. No running service parses SQL. At run time the
-runtime validates the IR against the same allowlist, injects policy, and the
-dialect prints its engine's SQL (SQLite for D1).
+Every generated invocation retains its `requires`. SQL row policy limits scope, TTL and publishing visibility at every relation. The app supplies a verified Caller.
 
-What the D1 dialect accepts, in short (the [View reference](../reference/view.md)
-has the full table):
+Bare Views return native row arrays. Declared date/date-time columns are formatted by SQL; other values retain driver behavior. Proved pageable Views also get `paged/views/<encoded-name>.ts`, returning `{ rows, nextCursor? }`. Internal paging creates no exposure. Keyset paging requires generate-time order/cardinality proofs; it does not avoid the source scan for an aggregate. Inspect native EXPLAIN and indexes.
 
-- columns, literals, arithmetic, `CASE`, `COALESCE`, `CAST` (to `int` only for
-  integer literals: use `round(x)`), JSON `->>`;
-- `WHERE` with comparisons, `BETWEEN`, `IN (list | subquery)`, `EXISTS`,
-  `LIKE` (case-insensitive, as in SQLite), `IS DISTINCT FROM`;
-- `INNER` and `LEFT JOIN`, subqueries, `json_each(…)`;
-- `GROUP BY`, `HAVING`, `count`, `sum`, `min`, `max`, `avg`,
-  `json_group_array`, `json_group_object`; `row_number()`, `rank()` and running
-  aggregates;
-- `ORDER BY … NULLS FIRST | LAST`, `LIMIT` (it needs an `ORDER BY`),
-  `DISTINCT`;
-- `now()`, `date_trunc`, `extract`, `ts ± interval '<n> seconds|minutes|hours'`;
-- `mantle.search`, `mantle.search_rank`, `mantle.near`, `mantle.distance`.
-
-Refused: `OFFSET` (page with cursors), `RIGHT`/`FULL`/`CROSS JOIN`, any table
-that is not a declared Schema, and SQLite's own clock (`CURRENT_TIMESTAMP`,
-`'now'`).
-
-PostgreSQL is the reference dialect (ADR-0037): on it a View may also use `WITH`
-(recursive too), `UNION` and `DISTINCT ON` inside a `WITH` or subquery,
-`LATERAL`, window frames, `FILTER`, jsonb operators, `ILIKE` and regular
-expressions. D1 refuses them as needing the PostgreSQL dialect. On every
-dialect a View may read an internal View in `FROM`, which is inlined; that is
-how a rule many Views share is written once.
-
-## Policies the runtime injects
-
-Every Schema reference, in `FROM`, joins and subqueries, is replaced by a
-subquery that keeps only visible rows:
-
-- **scope**: on a scoped Schema, a user caller's own rows (an anonymous caller
-  sees none);
-- **TTL**: unexpired rows;
-- **published-only**: on a `public` View, published rows of `publishing`
-  Schemas.
-
-So the join in `my-orders` sees only the caller's orders, and the View never
-says so. A public View that joins a Schema without `publishing` to one with it
-must join them by an explicit condition, or validation refuses it.
-
-## Output names and types
-
-- A column that reads a Schema field unchanged comes back under the field's
-  declared name and type (`o.orderStatus` is `orderStatus`).
-- Anything else keeps its alias. SQL folds unquoted names to lower case, so
-  `count(o.id) AS orderCount` comes back as `ordercount`; write
-  `AS "orderCount"` to keep the case.
-- `*` expands to the declared fields, never the scope field or native columns.
-- The generated `ViewRow_<name>` types each column the same way; an expression
-  is `unknown`.
-
-## Surfaces
-
-| `surface` | Served at |
-|---|---|
-| `public` | `GET /api/views/<name>` (REST) and a tool on the public MCP surface (`/mcp`) |
-| `staff` | `GET /admin/api/views/<name>`, with CSV at `/export`, and a tool on the staff MCP surface (`/mcp/staff`) |
-| `internal` | no surface: `ctx.store.view(...)` and `runtime.store` only |
-
-`requires` gates every path: an anonymous caller is 401 `UNAUTHENTICATED`, a
-signed-in one who fails a predicate is 403 `AUTH_DENIED`. A staff View still
-needs its own `requires` to limit roles beyond Admin's gate.
-
-## Input and paging
-
-`input` is a JSON Schema object; the SQL reads `input.<name>`. Over REST the
-properties are query parameters, coerced to their declared types; a missing
-required one is 400 `INPUT_VALIDATION_FAILED`. `limit` and `cursor` are
-reserved names.
-
-Every surface pages the same way: `limit` (default 50, at most 500) and an
-opaque `cursor`. The response is `{ "rows": [...], "nextCursor": "…" }`, with
-`nextCursor` only when more rows exist. The compiler appends `id` to the
-`ORDER BY` so the order is total. A View's own `LIMIT` caps the whole result.
-
-## MCP
-
-Each View of a surface is a read-only tool named after it in snake case
-(`my-orders` is `my_orders`), whose input is the View's `input` plus `limit`
-and `cursor`. `description` becomes the tool's description. See
-[MCP and agents](./mcp-and-agents.md).
-
-## Further reading
-
-- [View reference](../reference/view.md)
-- [Query from TypeScript](../guides/typed-queries.md)
+See the [View reference](../reference/view.md), [surface contracts](../reference/surface.md) and [native value contract](../guides/native-execution.md).

package/docs/handbook/examples/hub.md

@@ -1,21 +1,5 @@
----
-description: Index of the Mantle 0.2.0 examples — whole services in the v2 grammar, each compiled by mantle generate, and the runnable reference service.
----
 # Examples
 
-Each example is a whole service whose manifests compile with `mantle generate`;
-its handlers are written against the generated types. They live beside this
-handbook in [`docs/examples/`](../../examples/README.md).
+Use the [Worker quickstart](../start/quickstart-worker.md) for a complete native manifest and entry, [typed queries](../guides/typed-queries.md) for embedding, and [service composition](../cloudflare/service-entry.md) for optional surfaces.
 
-| Example | Shows |
-|---|---|
-| [Reference service](../../examples/reference-service/README.md) | a runnable service with its smoke test: scope, SQL Views and Procedures, hooks, a cron, REST, both MCP surfaces, Admin's API and sign-in |
-| [Intake form](../../examples/intake.md) | an anonymous form: one SQL `INSERT` and a staff View |
-| [Intake with bot check and notification](../../examples/intake-hooks.md) | a guard and an after hook |
-| [Reservation requests](../../examples/reservation.md) | a request queue with a `check` |
-| [Publication](../../examples/publication.md) | localized posts, per-locale Views and `mantle.search` |
-| [Legal documents and consent](../../examples/legal-documents.md) | immutable revisions and a conditional insert |
-| [Procurement approvals](../../examples/procurement.md) | own rows through `auth.uid()`, a locked staff review |
-| [Commerce catalog and orders](../../examples/commerce.md) | a published catalog and guest orders |
-| [Commerce inventory](../../examples/commerce-inventory.md) | atomic stock reservation, a scheduled expiry, a verified payment callback |
-| [Guarded API access](../../examples/guarded-api.md) | API keys, scopes and an entitlement guard |
+The runnable [reference service](https://github.com/aotter/mantle/tree/v0.2.0-alpha.11/docs/examples/reference-service) exercises the native package integration. See the [generated public website](../../examples/generated-web/README.md) for a native Worker example.

package/docs/handbook/guides/adapter-guide.md

@@ -0,0 +1,11 @@
+# Another host or database handle
+
+Mantle has an open driver boundary and exactly two closed dialects in 0.2.0, postgres and sqlite. Choose the generation target whose emitted SQL and handle calls match your host. The app owns its router, resources, lifetime and scheduler.
+
+PostgreSQL's `Postgres` in `kernel/contracts.ts` needs `unsafe(text, values)` and `begin(options, fn)`. Bun.SQL and postgres.js fit without wrappers. [The node-postgres example](postgres-adapters.md) shows the transaction and result-count contract. SQLite handle contracts are exported by `@aotter/mantle/driver/d1` and `/driver/bun-sqlite`: D1 prepare/bind/all/batch, or SQLite query/exec/transaction. Reads may need only the narrower reader shape.
+
+A third-party driver must preserve result, binding, atomicity and uncertain-outcome semantics. A handle that cannot transact must reject before invoking the callback. Never emulate an atomic Procedure with unrelated autocommit HTTP calls.
+
+Users may choose another SQL executor, including WASM SQLite persisted to IndexedDB, at their own risk. Mantle supports bun:sqlite, D1, Bun.SQL and postgres.js; there is no bundled Durable Object adapter. The app owns any custom adapter and its tests. A third SQL engine requires forking the compiler and Store runtime, not installing a dialect plugin.
+
+No runtime performs DDL, introspection or schema checks. Install initial SQL and rehearse migrations explicitly; see [database ownership](../concepts/runtime-and-adapters.md).