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

package/docs/handbook/concepts/lifecycle-and-locales.md

@@ -1,90 +1,19 @@
----
-description: Publishing and operational Schemas, the draft-publish-archive rules Store enforces, TTL expiry, and localized Schemas in Mantle 0.2.0.
----
 # Lifecycle and locales
 
-## Two lifecycles
+Schemas default to `operational`: rows are live immediately and edit in place. Opt-in `publishing` adds `status` (draft/published/archived), nullable `published_at` and a scope-aware `(published_at, id)` index.
 
-A Schema's `lifecycle` decides how its rows move. The default is
-`publishing`.
+Generated `<table>.publish`, `.unpublish` and `.archive` Procedures take `{ id, expectedVersion }`, require admin/system and perform one atomic UPDATE. Publish checks required fields, visibility, TTL, source state and OCC. A failed guard is `CONFLICT`. Store cannot write status/published_at directly. Admin permits generic publishing edits only on drafts; Store does not add that separate Admin editing rule.
 
-| | `publishing` | `operational` |
-|---|---|---|
-| For | authored content: posts, products, legal text | records written by Procedures: orders, requests, audit rows |
-| A new row | is a `draft`, saved even when incomplete | is live at once, validated in full |
-| Editing | only drafts are editable; a published row is protected | rows edit in place |
-| Statuses | `draft` → `published` → `archived`, `published` → `draft` (unpublish), `archived` → `draft` | none: no `status` column; a row is live once written |
-| Public Views | see published rows only | see every row |
-| Set ops | refused (every write pins one row) | allowed |
+Public Views see published rows only. Other reads expose drafts only to admin/system. This policy applies to joins and nested queries too.
 
-One domain service, the lifecycle state machine inside Store, enforces these
-rules for every path: SQL Procedures, `ctx.store`, Admin and imports.
-Publishing a row needs its required fields complete, and publishing a
-translation needs its parent published first.
+## Translations
 
-**SQL cannot set `status`.** A write that names it is refused. Status moves
-through:
+`localized: true` declares a locale string. `translates: { parent, on }` declares a localized child sharing a join key with its parent. A scoped parent needs the same child scope column. A publishing translation can publish only when its caller-visible parent is published (or operational); the parent guard is inside the atomic UPDATE. Unpublishing a parent hides translations without changing their status.
 
-- Admin's API: `POST /admin/api/entries/{id}/publish` and `/unpublish`;
-- a `ref` handler: `ctx.store.write([{ update: "posts", set: { status: "archived" }, where: { id }, lock }])`.
+Store translation reads merge visible parent fields, with child fields taking precedence. Authored Views return only their SELECT outputs. Generated `translations.ts` exports `translationLocales(db, caller, parent, rows)` for a parent page (up to 500 storage-named rows); it uses batched authorized child reads rather than one query per parent. Stored locale values remain plain strings; site locales do not rewrite or validate them automatically.
 
-## TTL
+SQLite/PostgreSQL interactive Store transactions refuse to combine translation publication and a parent status change in either order. D1 has no interactive Store transactions. The app owns consistency for native transactions outside Store.
 
-```yaml
-spec:
-  ttl: { field: expiresAt, expireAfterSeconds: 0 }
-  schema:
-    properties:
-      expiresAt: { type: string, format: date-time }
-```
+## Expiry
 
-A row expires `expireAfterSeconds` after the time in `field`, a top-level
-`date-time` field. Expiry is logical: every read and write, `runtime.store`
-included, treats an expired row as absent. Removing the rows is a separate,
-host-only step:
-
-```ts
-await runtime.store.sweepExpired({ collection: "sessions", limit: 500 }); // { scanned, removed, nextCursor? }
-```
-
-Run it from a schedule Trigger's `ref` handler, where the system caller's
-`ctx.store` has it (`await ctx.store.sweepExpired?.({ collection: "sessions" })`;
-a member's `ctx.store` does not), or from your own maintenance code.
-`delete: false` counts without deleting. Until it runs, an expired row still
-holds its unique keys: an insert that reuses one is `CONFLICT` (`unique`). A translation Schema may not
-declare `ttl`.
-
-## Localized Schemas
-
-`localized: true` marks a Schema whose rows carry a `locale` field; a
-non-localized Schema may not declare a field named `locale`.
-
-```yaml
-kind: Schema
-metadata: { name: post-translations }
-spec:
-  localized: true
-  translates: { parent: posts, on: slug }
-  uniqueIndexes: [[slug, locale]]
-```
-
-`translates` makes the Schema the localized child of a non-localized parent,
-joined on a field both declare. It needs `localized: true`, at least one
-content field besides the join field and `locale`, and a parent that exists
-and is not localized. Admin groups translations under their parent, and
-publishing a translation needs its parent published.
-
-In 0.2.0, `locale` is a plain string field: Store does not check it against the
-site's locales, and no surface resolves a request's locale or falls back to a
-default one. A View takes the locale as `input` (see
-[Publication](../../examples/publication.md)); fallback is the reader's code.
-
-Manifest text (`title`, `description`) may be a locale map,
-`{ en: Products, zh-TW: 商品 }`. Admin picks the viewer's locale and MCP the surface's `locale` option (default `en`), then
-`en`, then the first entry.
-
-## Further reading
-
-- [Schema reference](../reference/schema.md)
-- [Site defaults and site_config](../reference/site-config.md): the site's
-  `locales` list
+TTL hides expired rows but does not delete them. Use generated system-only `<schema>.sweepExpired` from an application scheduler; [TTL maintenance](../guides/native-execution.md#ttl-maintenance) defines limits and cursors. Until removed, expired rows still occupy unique keys.

package/docs/handbook/concepts/mcp-and-agents.md

@@ -1,129 +1,37 @@
----
-description: The public and staff MCP surfaces, which tools a plan lists, how agents authenticate with OAuth, MCP Apps resources, and Admin's WebMCP catalog.
----
 # MCP and agents
 
-`createMcpSurface(runtime, { basePath, surface })` from `@aotter/mantle/mcp`
-serves a plan's tools over MCP's Streamable HTTP transport. The generated
-preset mounts two:
+Mount generated `mcp()` with the app's native handle and verified Caller resolver. The official MCP SDK loads only on a matching request. Optional auth stays behind the application's dynamic auth import.
 
-| Mount | Surface | Who | Authenticates with |
-|---|---|---|---|
-| `/mcp` | `public` | anyone; each tool's `requires` still applies | an OAuth bearer token (identity `mantle`), or whatever your resolver accepts |
-| `/mcp/staff` | `staff` | staff only | the same OAuth bearer token as `/mcp` (with identity `mantle`; any identity but `none`) |
+| Endpoint | Tools |
+| --- | --- |
+| `/mcp` | Public Views and Procedures exposed by public MCP Triggers |
+| `/mcp/admin` | Admin Views, admin Trigger Procedures, generated publishing transitions and selected product tools |
 
-Both run behind `withCaller(resolver, …)`, so a tool sees the same
-[Caller](./authorization.md) as a REST call.
+Names are snake-case; a View named `my-orders` becomes `my_orders`. Each call retains declared authorization, scoped/TTL/publication SQL and input checks. Admin tools require admin authority. Tool visibility and UI hints grant no authority. Cookie-session mutations retain origin checks.
 
-## Which tools
+Views return structured `{ rows, nextCursor? }`. SQL Procedures retain native `{ results }`; application ref results remain app-owned. Selected boundaries redact native errors. Never retry an uncertain write automatically.
 
-A surface lists exactly:
+The app owns OAuth configuration, discovery and consent; follow [OAuth](../guides/oauth.md) and [authentication](../cloudflare/authentication.md). Public anonymous reads can avoid auth entirely; invalid supplied credentials cannot become anonymous. Authority-sensitive endpoints retain fresh primary checks.
 
-- each Procedure bound by a Trigger `{ kind: mcp, surface: <this surface> }`,
-  named after the Procedure in snake case (`place-order` is `place_order`);
-- each View whose `surface` is this one, as a read-only tool with the View's
-  `input` plus `limit` and `cursor`.
+[MCP Apps](../guides/mcp-apps.md) add static UI resources through the public contributor hook. Admin uses the same hook from its separate package. Credentials never go in App HTML. WebMCP catalogues are generated display/tool metadata for the mounted Admin product; server checks remain authoritative.
 
-A Schema is never a tool: there are no generated create, update or publish
-record tools. To let an agent change rows, declare a Procedure and an `mcp`
-Trigger for it.
+See [surface contracts](../reference/surface.md) for tool schemas, challenges and scalar conversion.
 
-- **Description.** A Procedure's or View's `description` is the tool's
-  description. Write it for an agent deciding what to call.
-  `MCP_TOOL_DESCRIPTION_MISSING` warns when an exposed Procedure has none.
-- **Annotations.** A View is `readOnlyHint: true`. A Procedure may declare
-  `mcp: { readOnlyHint, destructiveHint, openWorldHint }`, which the tool
-  carries as written.
-- **Output.** An object `output` becomes the tool's `outputSchema`, and the
-  result is returned as structured content.
-- **Errors.** A refused call is a tool error result carrying the diagnostic
-  code (`AUTH_DENIED`, `CONFLICT`, …). An anonymous call to a tool that
-  `requires` a caller is HTTP 401 with a `WWW-Authenticate` challenge, so an
-  MCP client starts OAuth. When no tool on the surface may be called
-  anonymously, every anonymous request is answered that way, `initialize`
-  included, so a client asks for sign-in as soon as it connects.
+## When a host shows old tools
 
-Listing is not permission: every `tools/call` checks `requires` and the guard
-again.
+A fresh `tools/list` always returns the deployed tools, but many hosts keep their own copy and do not ask again after a deploy. Mantle sends no list-changed notifications: tools change only at deploy, and the hosts that keep copies do not act on them. Instead each generated tool's description ends with its own version, and the results of a call that reaches the tool carry the deployed version, so a model holding an older definition can see it, correct its call or ask the user to refresh. Failures also state the input schema the tool is listed with now, except authorization refusals. A call naming a tool the catalogue no longer has gets the protocol's unknown-tool error, whose message gives `serverInfo.version`: unless the application sets it, a hash of every tool the endpoint serves, before per-caller filtering. Refusals before a call reaches its tool, such as authentication challenges, carry neither.
 
-## OAuth for agents (identity `mantle`)
+In Admin, WebMCP results from the tool route carry the version, and refusals add it with the input schema, except authorization refusals; a tool removed since the page loaded is refused as not found, without a catalogue version. Admin's two navigation tools, `admin_get_context` and `admin_navigate`, carry no version: the page defines and runs them without a server call, so it cannot list one definition and run another, and a reload after a deploy replaces both. The exact shapes are in [surface contracts](../reference/surface.md#tool-versions).
 
-`createMantleAuth` runs Better Auth's OAuth provider with `mcpResource:
-{PUBLIC_ORIGIN}/mcp`. An MCP client discovers it from the 401 challenge's
-`resource_metadata` (`/.well-known/oauth-protected-resource/mcp`), registers,
-sends the user through sign-in and consent (`/oauth/consent`), and calls `/mcp`
-with the token. The resolver (`createCallerResolver(auth, { jwtBearer: { audience, scopes: ["mcp"] } })`)
-verifies it on every request and reads the user's current role; nothing is
-cached. Every MCP surface also keeps the scope floor (ADR-0014): a credential
-other than a cookie session (an OAuth token, an API key, a personal token)
-must carry `mcp` before any tool is listed or called, or the request is HTTP
-403 `insufficient_scope`; `createMcpSurface`'s `requiredScopes` changes the
-floor. When an OAuth token lacks a scope a tool's `requires` names, the call
-is HTTP 403 with an `insufficient_scope` challenge naming the scopes to ask
-for.
+How each client refreshes its copy (as of 2026-10):
 
-## Staff tools
-
-The preset mounts the staff surface at `/mcp/staff` whenever it mounts `/mcp`
-and has an identity. It shares the `/mcp` audience, so one token with the `mcp`
-scope reaches both:
-
-```ts
-const staffMcp = withCaller(resolver,
-  createMcpSurface(runtime, { basePath: "/mcp/staff", surface: "staff", resourceMetadata }),
-  { resourceMetadata });
-```
-
-`resourceMetadata` is the `/mcp` metadata URL. The staff surface admits only
-callers with a staff role, and the role is read on every request.
-
-## WebMCP in Admin
-
-`GET /admin/api/webmcp` returns `{ tools, routes }`: the staff tools (what
-`/mcp/staff` lists, in its default locale) and, for each tool, the Admin page
-it belongs to (a Procedure with a `target` maps to its collection, a View to its
-report). A browser agent in the console registers these tools and calls one
-with `POST /admin/api/webmcp/<tool>` and the input as the JSON body. Admin runs
-it as `/mcp/staff` would, with the same input, an `mcp` cause and the signed-in
-session, and answers `{ output }` or the refusal. Admin itself answers no MCP.
-An MCP App's `appOnly` tools are hidden from MCP clients only; in Admin the
-agent acts as the signed-in person, who can run every staff tool by hand.
-
-## MCP Apps
-
-`createMcpSurface(runtime, { …, apps: { resources: [...] } })` serves `ui://`
-resources beside the tools. Each resource names the tools whose results it
-`renders`, and may name `appOnly` View tools that only the App can call. A
-client without MCP Apps support never sees app-only tools. The HTML is a static
-asset; caller data travels only in tool results.
-
-The preset serves Mantle's App on `/mcp/staff`:
-
-```ts
-import { planApp } from "@aotter/mantle/mcp";
-import { mantleAppHtml } from "@aotter/mantle-ui/mcp-app";
-
-createMcpSurface(runtime, { basePath: "/mcp/staff", surface: "staff", apps: { resources: [planApp(runtime.plan, { surface: "staff", html: mantleAppHtml })] }, resourceMetadata });
-```
-
-`planApp` renders every View tool of the surface and embeds the plan's catalog
-in the HTML once: each View's columns as the Schema fields they read (so a
-value is labelled and formatted as Admin shows it), and, for a View that reads
-one table and outputs its `id`, the Procedure tools whose `target` is that
-Schema. A host that renders MCP Apps shows a View's rows in the chat; a row
-with an `id` (and a `version`, for an operation that locks one) offers those
-operations through the same review-and-submit panel Admin uses. The row as
-listed is what the person reviews: a version that moved since is the server's
-`CONFLICT`. The catalog is the plan's, not the caller's, so an operation the
-caller's role cannot run is offered and then refused. Every read and write is a
-tool call under the caller's own token. A rendered result names its tool in
-`_meta["net.aotter.mantle/tool"]`.
-
-On the public surface, a member-facing App is the application's to build; the
-SDK attaches none. The `develop` skill's
-[MCP App recipe](../../skills/develop/mcp-app.md) lists the pieces.
-
-## Further reading
-
-- [Reads: Views, REST and MCP](./views.md)
-- [HTTP, MCP, CLI and packages](../reference/surface.md)
+| Client | Refresh |
+| --- | --- |
+| claude.ai connectors | A server-side copy keyed by URL, kept about an hour (users report up to 24 hours). Only adding the connector again under a new URL, such as `?v=2`, forces a refresh, and that needs authorization again. |
+| Claude Code | `/mcp` reconnect, or a new session |
+| ChatGPT developer mode | Refresh the connection, then start a new chat |
+| Published ChatGPT apps | A daily scan, or Rescan, followed by review; keep tools compatible meanwhile |
+| Cursor | Quit fully and reopen |
+| VS Code | Run "MCP: Reset Cached Tools", or restart the server |
+| Gemini CLI | `/mcp reload` |
+| MCP Inspector | The refresh button |

package/docs/handbook/concepts/procedures-and-triggers.md

@@ -1,166 +1,9 @@
----
-description: Procedures as SQL programs or ref handlers, atomic writes and optimistic locks, guards, lifecycle hooks, schedules, and how every source becomes one Invocation.
----
-# Writes: Procedures, Triggers and lifecycle hooks
+# Writes: Procedures and Triggers
 
-A Procedure is a write with a typed `input`, a typed `output` and a handler.
-A Trigger says when it runs.
+Writes use Store or declared Procedures. Raw SQL writes bypass scope, TTL, publishing and system-column rules.
 
-## Two kinds of handler
+SQL Procedures compile to native statements and return `{ results }`, one row array per statement. Row operations must affect exactly one row; a stale explicit version lock or unique clash is `CONFLICT`. Multi-statement Procedures run atomically; single-statement writes use native autocommit. See [native execution](../guides/native-execution.md) for uncertain outcomes. Never retry an `OUTCOME_UNKNOWN` write automatically.
 
-**SQL.** One or more `INSERT`, `UPDATE` or `DELETE` statements, separated by
-`;`, applied as one batch: all of them or none.
+A ref Procedure generates a typed `Handlers` key. Its handler receives `(ctx, input)` with `{ caller, db, store }` bound to the same Caller and transaction. Generated `requires` runs first. Handlers own side effects and their transaction boundaries.
 
-```yaml
-handler:
-  sql: |
-    INSERT INTO orders (itemId, qty, orderStatus, placedAt)
-    SELECT id, input.qty, 'placed', now() FROM items WHERE id = input.itemId
-    RETURNING id, qty;
-    UPDATE items SET stock = stock - input.qty WHERE id = input.itemId
-```
-
-The result is `{ "results": [...] }`, one array of `RETURNING` rows per
-statement. Statements pass values to each other only through tables. If the
-second statement fails a `check` (`stock >= 0`), the first is rolled back too.
-
-**`ref`.** A TypeScript function in the service's `handlers` map, for anything
-SQL cannot do: calling another service, reading before writing, setting
-`status`, branching on what it read.
-
-```yaml
-handler: { ref: cancelOrder }
-```
-
-```ts
-export const handlers: MantleHandlers = {
-  cancelOrder: async ({ orderId, expectedVersion }, ctx) => {
-    await ctx.store.write([{ update: "orders", set: { orderStatus: "cancelled" }, where: { id: orderId }, lock: expectedVersion }]);
-    return { id: orderId };
-  },
-};
-```
-
-A handler receives `(input, ctx)`. `input` is already validated against
-`input`, and the return value is validated against `output`.
-
-| `ctx.` | Is |
-|---|---|
-| `caller` | the [Caller](./authorization.md): `anonymous`, `user` or `system` |
-| `cause` | why it runs: `{ kind: "http" \| "mcp" \| "internal" \| "schedule" \| "lifecycle", id, parent? }`, plus `cron` and `scheduledTime` for a schedule, `hook`, `schema` and `rows` for a hook. `id` is stable across retries |
-| `store` | the typed Store, bound to the caller |
-| `invoke(name, input)` | runs another Procedure with the same caller, re-checking its `requires` and guard |
-| `env`, `waitUntil` | the host's environment and background-task hook |
-
-Invocations nest at most 8 deep (`INVOCATION_DEPTH_EXCEEDED`), counting hooks
-and `ctx.invoke`.
-
-## What a write may not do
-
-- Name the scope field or a native column (`id` on update, `version`,
-  `status`, `created_at`, `updated_at`, `author_id`). Store fills them.
-- Name an `id` in an `INSERT` on a scoped Schema: the compiler generates it.
-- Use `last_insert_rowid()`, `OFFSET`, DDL, or a table that is not a Schema.
-
-Set a timestamp field from `now()` and an owner field from `auth.uid()` in
-the SQL, never from an input.
-
-## Row ops, set ops and locks
-
-A statement is a **row op** when its `WHERE` pins `id` to one value
-(`WHERE id = input.id AND …`), or it is an `INSERT … VALUES` of one row
-without `ON CONFLICT`. Everything else (`INSERT … SELECT`, `ON CONFLICT`, an
-`UPDATE` by another column) is a **set op**.
-
-- A row op that writes no row fails with `CONFLICT`, and the batch is rolled
-  back. A set op that writes nothing is a normal result.
-- `AND version = input.expectedVersion` makes a row op an optimistic lock: the
-  caller sends the version it read, and a stale one is `CONFLICT` (HTTP 409).
-- A Procedure with exactly one row op that pins `id` (and optionally
-  `version`) to inputs gets its `target` inferred, which Admin uses to bind an
-  operation to a row.
-
-## Triggers
-
-| `source.kind` | Fields | Runs the Procedure |
-|---|---|---|
-| `http` | `method` (`POST`, `PUT`, `PATCH`, `DELETE`), `path` | at that route on the REST surface. `path` starts with `/api/`; `{param}` segments bind to inputs of the same name |
-| `mcp` | `surface: public \| staff` | as a tool on that MCP surface. `staff` also lists it as an Admin operation |
-| `lifecycle` | `schema`, `on: [hooks]` | around writes to that Schema |
-| `schedule` | `cron`, `enabled?` | on a five-field POSIX cron, UTC, weekday 0 = Sunday |
-
-A Procedure with no Trigger can still be run by `ctx.invoke` or from service
-code with `runtime.invokeProcedure`. Every source becomes the same
-`Invocation` (`{ procedure, input, caller, cause }`), so `requires`, the
-guard, input and output validation run the same way for all of them.
-
-## Guards
-
-`requires.guard.procedure` names a `ref` Procedure that runs after
-`requires.auth` and input validation, before the target. It receives the
-target's validated input and caller, gets a read-only Store, cannot invoke,
-and rejects by throwing. Use it for a check that belongs to one action: an
-entitlement, a bot token, a business rule. See
-[Guarded API access](../../examples/guarded-api.md).
-
-## Lifecycle hooks
-
-```yaml
-kind: Trigger
-spec:
-  source: { kind: lifecycle, schema: orders, on: [after_create, after_update] }
-  target: { procedure: record-orders }
-```
-
-Hooks are `before_create`, `after_create`, `before_update`, `after_update`,
-`before_delete`, `after_delete`, `before_publish` and `after_publish`. The
-target is always a `ref` handler.
-
-**Before hooks** are read-only checks for rules every path must obey, Admin and
-imports included. A hook receives the one row in `ctx.cause.rows` (for an
-insert, the row about to be written), reads with a read-only Store, and
-rejects by throwing; nothing in the batch is applied. The write then carries
-the version the hook saw, so a change in between is `CONFLICT`. A set op on a
-Schema with a before hook for that operation is refused. Hooks run in op order,
-and for one op in Trigger-name order.
-
-**After hooks** run only after a commit, once per statement and Trigger, with
-every row the statement wrote in `ctx.cause.rows`. Each row is the whole entry
-as `ctx.store.select` returns it (`id`, `version`, `createdAt`, `updatedAt`,
-`authorId`, every declared field), whatever the statement's own `RETURNING`
-asked for: that only shapes the Procedure's result. Loop over them; never read
-only `rows[0]`. A failure is logged and never undoes the commit, and a write
-the hook makes is a new transaction. Delivery is best effort: a handler that
-must not act twice deduplicates on `ctx.cause.id`.
-
-## Schedules
-
-```yaml
-kind: Trigger
-spec:
-  source: { kind: schedule, cron: "0 3 * * 0" }   # Sundays 03:00 UTC
-  target: { procedure: weekly-digest }
-```
-
-The target runs as the system caller: no caller scope, and no `requires.auth`
-predicate holds for it, so it declares none. `ctx.cause.id` is
-`<trigger>:<scheduledTime>`, the same for a replay. The service must pass
-`schedules: true` to `createMantle` (the preset does); without it boot refuses
-an enabled schedule with `SCHEDULE_NOT_WIRED`. The generated Cloudflare entry
-maps Cloudflare's cron spelling back to the plan's; see
-[The service and its entry](../cloudflare/service-entry.md). The Bun preset
-has no cron dispatcher: `mantle generate --host bun` refuses an enabled
-schedule Trigger, and a service with its own scheduler uses `host: none` and
-calls `mantle.invokeSchedule`.
-
-## Webhooks
-
-An HTTP Trigger receives parsed JSON, never the raw body. For a signed
-webhook, add a route to the service's own `fetch`: verify the signature over
-the raw body, then call `runtime.invokeProcedure` with a system caller. See
-[Commerce inventory](../../examples/commerce-inventory.md).
-
-## Further reading
-
-- [Procedure reference](../reference/procedure.md)
-- [Trigger reference](../reference/trigger.md)
+HTTP and MCP Triggers expose a declared Procedure with its existing authorization. Lifecycle and schedule Triggers are rejected by generation. Put side effects in app-owned handlers, and wire scheduled system maintenance with the host's scheduler. See [Procedure](../reference/procedure.md), [Trigger](../reference/trigger.md) and [Store](../guides/typed-queries.md).