@aotter/mantle 0.2.0-alpha.5 → 0.2.0-alpha.7

package/docs/skills/develop/mcp-app.md

@@ -1,79 +1,39 @@
 # Recipe: an MCP App for members
 
-The preset serves Mantle's App on `/mcp/staff` only. A member-facing App, on
-`/mcp`, is the application's: the SDK attaches none, because what a member
-should see in a chat (one order, a booking form, a status card) is a product
-decision. Build it case by case from these pieces.
-
-## Pieces
-
-| Piece | From | What it gives |
-|---|---|---|
-| `apps: { resources: [...] }` | `createMcpSurface` (`@aotter/mantle/mcp`) | a `ui://` resource beside the tools; `renders` names the tools whose results it shows, `appOnly` the View tools only the App may call |
-| `appCatalog(plan, "public")`, `withCatalog(html, catalog)` | `@aotter/mantle/mcp` | each public View tool's columns as the fields they read, and the row operations, embedded in your HTML as `#mantle-catalog` |
-| `planApp(plan, { surface: "public", html: mantleAppHtml })` | `@aotter/mantle/mcp`, `@aotter/mantle-ui/mcp-app` | the staff App as is, for every public View: the quickest start when a list is what you want |
-| `App` | `@modelcontextprotocol/ext-apps` | the host bridge: `ontoolresult`, `ontoolinput`, `callServerTool`, the host's locale and theme |
-| `readCatalog`, `toolOf`, `outputOf`, `rowsOf`, `invokeTool`, `actionsFor` | `@aotter/mantle-ui` | the catalog, a result's tool, its output and rows, and a tool call as the controller reads it, so the App never parses the wire itself |
-| `renderDataValue`, `propertyLabel`, `optionLabel`, `OperationPanel` | `@aotter/mantle-ui` | a value as Admin shows it (money, dates, option titles, in the host's locale), and Admin's review-and-submit panel |
-| `createInteractionController` | `@aotter/mantle-ui/controller` | one operation on one row: review, submit once, a refusal or `CONFLICT` kept, never retried |
-| `SchemaFields` and the primitives | `@aotter/mantle-ui/kit`, styled by `@aotter/mantle-ui/kit.css` | Admin's form controls |
-
-The App's own build installs what it imports: `@modelcontextprotocol/ext-apps`
-at the exact version in the installed Core's `peerDependencies`, React and the kit's peers
-(`@aotter/mantle-ui`'s README lists them). `docs/handbook/concepts/mcp-and-agents.md`
-(MCP Apps) describes the catalog and the staff App these share.
-
-## Steps
-
-1. Decide what the App shows and which tool's result opens it. It renders a
-   tool the surface already serves: a public View, or a Procedure with an
-   `mcp` Trigger on `public`. Add that Trigger or View first; an App never
-   reaches data a tool does not.
-2. Build one self-contained HTML file, for example `app/dist/member.html`:
-   Vite with `vite-plugin-singlefile` (and React, if you use the components).
-   A host loads the App in a sandbox that fetches nothing else unless the
-   resource's `csp` allows it. The build runs before `wrangler dev` and
-   deploy: add it to the project's scripts.
-3. Serve it. Wrangler imports `.html` as text; declare it for TypeScript in
-   `src/env.d.ts` (`declare module "*.html" { const html: string; export default html; }`),
-   then in `src/service.ts` (identity `mantle`, whose preset defines
-   `resourceMetadata`; with `custom`, pass the surface to your own `guard`):
-
-   ```ts
-   import memberHtml from "../app/dist/member.html";
-   import { appCatalog, withCatalog } from "@aotter/mantle/mcp";
-
-   const html = withCatalog(memberHtml, appCatalog(runtime.plan, "public"));
-   const mcp = guard(createMcpSurface(runtime, { basePath: "/mcp", surface: "public", resourceMetadata,
-     apps: { resources: [{ uri: "ui://shop/my-orders", name: "my-orders", html, renders: ["my_orders"] }] } }), { resourceMetadata });
-   ```
-
-4. In the App, `readCatalog()` once; in `ontoolresult`, `toolOf(result)` names
-   the tool and `outputOf(result)` (or `rowsOf` for a View) is its data. A
-   success is `structuredContent` when the output is an object and the JSON
-   text otherwise; a failure of a tool with an output schema is the text
-   alone, which `outputOf` reads either way. Call tools through
-   `invokeTool(app.callServerTool…)`: a refusal is `{ ok: false, diagnostics }`
-   (`AUTH_DENIED`, `CONFLICT`, ...), and a thrown call (a 401 or 403 from a
-   missing scope or sign-in, a lost connection) is an unknown outcome to
-   re-read, never to retry blindly.
-
-## Rules
-
-- The HTML is a static asset: no caller data, no secrets, the same for every
-  member. Caller data arrives only in tool results.
-- Every read and write is a tool call under the member's own token; `requires`
-  and `scope` apply exactly as they do to the model's calls.
-- `appOnly` hides a read from the model; only a View can be app-only, never a
-  write.
-- A public View over a `publishing` Schema shows published rows only; over a
-  `scope`d Schema it shows the caller's own rows, without a `WHERE` of yours.
-
-## Verify
-
-Add the App's build to the develop loop, then: `tools/list` from a client that
-declares the MCP Apps extension shows the rendered tool with
-`_meta.ui.resourceUri`; `resources/read` of that URI returns your HTML with
-`#mantle-catalog`; a call to the tool returns its result with
-`_meta["net.aotter.mantle/tool"]`. Then open it in a host that renders MCP
-Apps, signed in as a member.
+## Native applications
+
+Read the installed MCP App contract. The SDK's generic hook attaches only the resources the app selects;
+only selected modules enter the service.
+
+```ts
+import type { McpApps } from '@aotter/mantle/mcp';
+import { mcp } from '../generated/mcp.js';
+const memberApp: McpApps = { resources: [{
+  uri: 'ui://shop/my-orders',
+  name: 'my-orders-app',
+  renders: ['my_orders'], // the tool for the declared public View my-orders
+  html: async () => (await import('./member-app.js')).memberHtml,
+}] };
+const tools = mcp({ db, caller, handlers, apps: { public: memberApp } });
+```
+
+Each endpoint accepts one contributor or an array. The separate
+`@aotter/mantle-admin` package contributes its admin App through this same
+`apps.admin` hook; it owns `ui://mantle-admin/…`. App resources use their own
+`ui://<app>/…` namespace. Duplicate resource URI/name, conflicting `renders`,
+or `renders`/`appOnly` naming an unavailable endpoint tool (or a Procedure for
+`appOnly`) fail when `mcp(...)` is built; with a request-bound tool table, the
+tool names are checked on the first matching request. Only clients that
+declare no MCP Apps support see no UI resources; a request that advertises no
+capabilities at all is treated as supported.
+
+Use `renders` for a declared tool; `appOnly` optionally hides it from non-UI
+clients. Import HTML lazily; it carries no secrets or caller data. Tool results
+use the caller's SQL policy, and an App cannot authorize a hidden admin tool.
+Generic interaction components and controllers remain in `@aotter/mantle-ui`;
+Admin-specific controllers/catalogues belong to `@aotter/mantle-admin`.
+
+Verify tools/list metadata, resources/read, actual tool calls and a host-rendered
+member App. Test anonymous/member isolation and resource conflicts. Never retry
+unknown writes blindly; retain OCC and re-read state after an uncertain outcome.
+Commit generated output and run generation with `--check` before deployment.

package/docs/skills/integrate/SKILL.md

@@ -10,87 +10,45 @@ metadata:
 
 # Integrate Mantle into an existing application
 
-Mantle is added to a running service; it does not replace it. The service
-keeps its entry, users, auth, tables, routes and frontend. Mantle adds its own
-`_mantle_*` tables, the Schemas it declares, and the surfaces the service
-chooses to mount. Read the installed package's
-`docs/handbook/start/overview.md` and
-`docs/handbook/concepts/authorization.md` first.
-
-## Inspect and decide
-
-Map the application before installing anything: its entry and router, frontend,
-users and sign-in, database and data volume, deployment, background jobs and
-tests. Ask which behavior the owner wants Mantle to own. Then choose:
-
-1. **Embed.** Keep the application's entry. Compose Mantle into its existing
-   `fetch` (`createMantle(service, { plan, storage })`, the surfaces you want,
-   behind a `CallerResolver` over the application's own sessions). Best when
-   the application already runs on Workers with D1.
-2. **Move one capability at a time.** Give one bounded set of data (a form, a
-   catalog) a Schema, then its Views and Procedures; the rest stays. At every
-   step, each table has exactly one writer.
-3. **Rebuild and migrate.** Generate a new Mantle service in a separate
-   directory, port the frontend and business rules, and import the data. Best
-   when adapting the old structure costs more than rebuilding.
-
-Explain the choice and its tradeoffs to the owner before changing code.
-
-## Identity
-
-The application keeps its users. Pick `identity`:
-
-- `custom`: write `src/identity.ts` as a `CallerResolver` over the existing
-  sessions or tokens. `subject` is the application's stable user id,
-  namespaced when there are several issuers, never an email. Map existing
-  admin roles to `owner` / `editor` / `contributor`, or leave `role` null.
-- `mantle`: only when the application has no sign-in and wants Better Auth's.
-- `none`: a public service with no signed-in callers.
-
-Switching identity later is refused; choose deliberately.
-
-## Embedding into an existing entry
-
-`mantle generate` writes the preset only where `src/service.ts` does not
-exist; `--host none` writes no preset at all, only the plan and its types.
-For an application with its own entry, generate in a scratch
-directory with the same manifests and config, then copy the composition you
-need from the generated `src/service.ts` into the application's own entry:
-
-- the `createMantle(service, { plan, storage: (env) => d1Storage(env.DB), schedules: true })` call;
-- `withCaller(resolver, createRestSurface(runtime, { basePath: "/api" }))`
-  and any other surface, mounted on paths the application does not use;
-- the `scheduled` mapping from `src/index.ts`, if the plan has schedules.
-
-Put that composition in the application's `src/service.ts` before the first
-`mantle generate` inside the application: while `src/service.ts` is missing,
-generate writes every missing preset file (`src/service.ts`, `src/index.ts`,
-`src/handlers.ts`, `src/identity.ts` for `custom`, `tsconfig.json`,
-`.gitignore`, `.dev.vars.example` for `mantle`, and `wrangler.jsonc` unless a
-`wrangler.*` exists; on Bun `.env.example` and no `wrangler.jsonc`) beside the
-application's own.
-Commit `.mantle/generated/` and run `mantle generate --check` in CI.
-
-## Moving data into a Schema
-
-- Mantle never reads or writes a table it did not create. A table with a
-  Schema's name that Mantle does not own stops boot
-  (`STORAGE_TABLE_NOT_OWNED`); give the Schema a new name.
-- Import through `runtime.store` in trusted code. A scoped row goes through
-  `runtime.store.as(<its owner's caller>)`, so the owner field is right.
-  `status`, timestamps and `author_id` cannot be imported: publish with a
-  second update that sets `status`.
-- Rehearse on a copy, compare row counts, and keep the old table until the
-  owner confirms. Never touch live data before the cutover is agreed.
-
-## Verify
-
-Run the application's own build and tests, then `mantle generate --check`,
-the typecheck, and real requests against the routes Mantle now serves, as the
-right callers (owner, member, anonymous). `--check` proves the generated files;
-it does not prove the integration.
-
-## When you are done
-
-Report which capabilities Mantle now owns, the identity mapping, what moved and
-how it was verified, and what remains for cutover or deployment.
+## Workflow
+
+Read the installed SDK README and version-matched handbook before editing.
+
+Follow the installed [native generation and service workflow](../../handbook/cloudflare/service-entry.md)
+with its [native contract](../../handbook/guides/native-execution.md) and [supported declarations](../../handbook/reference/features.md). Commit
+all generated output, run the same generation command with `--check`, and keep
+bundle `dist/` untracked. The app owns its verified Caller, handlers and native
+resources; Better Auth’s admin plugin `adminRoles` defines the admin layer (default `["admin"]`); `ctx.admin` accepts open role names.
+
+Keep the application router, database/pool, identity and frontend. Replace
+Core consumers explicitly and compose only selected generated entries. Resolve
+one Caller per request with the shared cookie-session origin check. Rehearse
+data-preserving schema/auth/role migrations on a copy and retain rollback artifacts.
+Initial schema.sql is for an empty database, not an in-place upgrade. Requests run
+no DDL or storage checks; the only request-time write outside app operations is
+the configured OAuth resource row (see [OAuth](../../handbook/guides/oauth.md)).
+Verify cutover with actual app tests.
+
+Preserve the app router, verified identity and native resources. For selected
+Admin use the [native guide](../../handbook/guides/native-admin.md): three matching
+packages, generated checks and `entries(bindings.schemas, bindings.adapter)`.
+Do not import old `/spec`, `/core` or runtime surface APIs. Review data/role
+migrations explicitly; full cross-target int64 parity and automated transfer
+are not this release's upgrade contract.
+
+## Partial adoption in TypeScript/Node
+
+Keep the app's router, pool/handle, identity and frontend. Declare only the Schemas and operations being adopted; import selected `views/<encoded-name>.ts` or `procedures/<encoded-name>.ts`, then call `(appHandle, verifiedCaller, validatedInput)`. Bun.SQL and postgres.js fit directly; [node-postgres can adapt](../../handbook/guides/postgres-adapters.md). No Admin/auth/surface module is required for direct queries.
+
+Existing tables need explicit migration into the declared storage shape, including system columns and constraints. Initial schema.sql must not be applied over an occupied database. Rehearse on a copy and test scope, TTL, publication, OCC and persisted state with the app's own identity.
+
+Writes use Store or declared Procedures; never raw SQL writes to adopted collections. Use internal Views for joins, aggregates, OR and reusable reads. Store findById/find/first remain useful for simple AND lookups in existing handlers.
+
+Direct declared Schema-column outputs in Views and SQL Procedure `RETURNING`
+keep their authored field names; explicit aliases keep SQL casing rules. Store
+rows and nested SQL relations use storage names. Boundary validators support a
+permissive `format: email` check (one `@`, non-empty parts, no whitespace). For
+LEFT JOIN paging, join on the joined Schema's id or single-field unique key and
+keep the base indexed, non-null order/id tuple. Generation always emits `Handlers`
+(empty without ref Procedures); pass `handlers` at `adminBindings()`, generated REST/MCP options and
+`webmcpRoutes(catalogue, tools, handlers)`, as the app shell does.

package/docs/skills/media-gc/SKILL.md

@@ -11,14 +11,25 @@ metadata:
 
 # Mantle Media GC
 
+## Generated native applications (alpha.7 and later)
+
+If the installed README describes generated native queries, read
+`docs/handbook/cloudflare/media-r2.md` and app-owned site/media wiring instead of Core storage
+options. Resolve the exact configured bucket and declared purposes. The
+`uploads/` candidate audit below still applies. Committed copies live under
+`committed/` and must never be candidates. Attempt-isolated committed copies
+retained after an uncertain DB outcome require reconciliation with live DB
+references before any separately authorized cleanup.
+
 Use the connected Cloudflare API. Audit by default; delete only the exact
 objects approved by the user.
 
 ## Preflight
 
-1. Read `wrangler.jsonc` and `src/service.ts`. Resolve the R2 bucket that
-   `r2MediaStorage` uses and the media purpose names in the site defaults
-   passed to `d1Storage(db, { site })`.
+1. Read `wrangler.jsonc`, the app-owned entry (`src/worker.ts` by default,
+   or the generation command's `--entry`) and its media wiring. Resolve the R2
+   bucket that `r2MediaStorage` uses and the media purpose names in
+   `siteDefaults.media.purposes` selected by `--site`.
 2. Confirm the exact Cloudflare account and bucket. If either is ambiguous,
    ask; never choose by name similarity.
 3. Use the Cloudflare OpenAPI search before execution to resolve the current

package/docs/skills/provision/SKILL.md

@@ -11,91 +11,28 @@ metadata:
 
 # Provision a Mantle project
 
-Provision only after the user asks to create remote resources or ship. Read the
-installed `docs/handbook/cloudflare/deploy-and-operate.md` and
-`docs/handbook/cloudflare/authentication.md` first.
-
-## Choose the target
-
-Ask which target, unless the project already shows one.
-
-| Target | Config | Follow |
-|---|---|---|
-| Cloudflare Workers | `wrangler.jsonc` | the rest of this skill |
-| ChatGPT Sites | the Site's hosting config | installed `docs/handbook/cloudflare/chatgpt-sites.md`; publish through Sites, never `wrangler deploy` |
-| Mantle Cloud | Cloud project link | the plugin's `mantle` skill and its Cloud workflow; connect Cloud MCP and use its exact host contract, not `wrangler deploy` |
-| Bun (host `bun`) | `.env` | self-hosted; installed `docs/handbook/start/project-and-cli.md` (Bun), not this skill |
-
-Self-hosting is always an option; never present a hosted target as required.
-
-## Local gate
-
-```bash
-pnpm install --frozen-lockfile
-pnpm exec mantle generate --check
-pnpm exec tsc --noEmit
-git status --short
-```
-
-Confirm the active Cloudflare account with the user before creating anything.
-
-## Cloudflare
-
-1. **Database.** `pnpm exec wrangler d1 create <name>` and put the
-   `database_id` into `wrangler.jsonc`'s `d1_databases[0]`, keeping the
-   binding `DB`. With dialect `postgres`, instead run
-   `pnpm exec wrangler hyperdrive create <name> --caching-disabled --connection-string=...`
-   (the connection string by hidden input) and replace the placeholder id in
-   `hyperdrive[0]`, keeping the binding `HYPERDRIVE`. An existing 0.1.x
-   database is never reused: 0.2 starts on a new one.
-2. **Origin.** Set `PUBLIC_ORIGIN` in `vars` to the deployed HTTPS origin.
-   Update it together with any OAuth callback when a custom domain is added.
-3. **Sign-in (identity `mantle`).** Choose one production method and edit
-   `src/service.ts`; never deploy `ConsoleEmailSender`:
-   - **Email OTP or magic link** with the application's own `EmailSender`
-     over its email provider, `bootstrapOwner: { match: "email", value }`.
-   - **GitHub**: `{ kind: "social", provider: "github", options: { clientId, clientSecret } }`
-     and `bootstrapOwner: { match: "github-login", value }`. The user creates a
-     GitHub OAuth App with callback `<PUBLIC_ORIGIN>/api/auth/callback/github`.
-   Remove the preset's loopback-only check once the method is real.
-4. **Secrets.** Never commit them or put them in chat, logs or `wrangler.jsonc`
-   `vars`. Store production values in the deployment's secret store. Use a
-   connector, or hidden input:
-
-```bash
-openssl rand -hex 32 | pnpm exec wrangler secret put BETTER_AUTH_SECRET
-read -rsp "GitHub client secret: " S && printf '%s' "$S" | pnpm exec wrangler secret put GITHUB_CLIENT_SECRET; unset S
-```
-
-   Set `BETTER_AUTH_SECRET` once; rotating it signs everyone out.
-5. **Optional bindings.** R2 for media only when asked
-   (`docs/handbook/cloudflare/media-r2.md`).
-6. **Deploy.** `pnpm exec wrangler deploy`. The first request creates the
-   tables. Later Schema changes on D1: run
-   `mantle generate --check --database <local SQLite file>` (local D1 under
-   `.wrangler/state/v3/d1/`, which must have run the plan now deployed) before
-   each deploy and resolve any blocked change by hand.
-
-Commit and push only non-secret changes.
-
-## Verify the deployed service
-
-- A public View and an HTTP Trigger answer.
-- Sign-in works with the production method; the owner gets
-  `GET /admin/api/me` → `owner`, a second account gets 403.
-- `/mcp` answers `tools/list`, and an anonymous call to a protected tool is
-  401 with a `WWW-Authenticate` challenge. When every public tool `requires` a
-  caller, anonymous `initialize` and `tools/list` are already that 401.
-- Every enabled schedule appears in the Worker's cron triggers.
-
-## Handoff
-
-Return the public origin, the sign-in method and who the owner is, the MCP
-URL (`<origin>/mcp`), the resources created or reused, and anything deferred.
-
-## Don't
-
-- Don't create remote resources before the user asks to ship.
-- Don't commit secrets or put them in `wrangler.jsonc` `vars`.
-- Don't point a 0.2 service at a 0.1.x database.
-- Don't patch `site_config` or `_mantle_*` tables; boot owns them.
+## Workflow
+
+Read the installed SDK README and version-matched handbook before editing.
+
+Follow the installed [native generation and service workflow](../../handbook/cloudflare/service-entry.md)
+with its [native contract](../../handbook/guides/native-execution.md) and [supported declarations](../../handbook/reference/features.md). Commit
+all generated output, run the same generation command with `--check`, and keep
+bundle `dist/` untracked. The app owns its verified Caller, handlers and native
+resources; Better Auth’s admin plugin `adminRoles` defines the admin layer (default `["admin"]`); `ctx.admin` accepts open role names.
+
+Deploy/create resources only within the user's authorization; reuse configured
+host resources. Apply reviewed and rehearsed migrations before routing traffic;
+imports/first requests perform no DDL or schema checks. Keep auth dynamic, production
+secrets in the host store, trusted HTTPS origin and verified bootstrap rule,
+production email and selected media wiring. Configure Admin ASSETS worker-first
+as in [Workers assets and secrets](../../handbook/cloudflare/service-entry.md#workers-assets-and-secrets). Hyperdrive caching stays off; PG settings are deployment-owned.
+Bun uses native Database/SQL, an app server and scheduler. Verify admin sign-in
+(role admin), denied access, public reads, a persisted write, MCP and selected UI.
+Report artifact/resources/checks and keep rollback artifacts.
+
+Use the installed [Native Admin](../../handbook/guides/native-admin.md) asset
+contract and `entries(bindings.schemas, bindings.adapter)`. Admin SPA assets
+belong to `@aotter/mantle-admin`, while UI supplies the shared kit. Verify both
+member and admin OTP/UI flows. Deployment of an authorized application does
+not authorize SDK publication; a workspace preview remains a preview.

package/docs/skills/update/SKILL.md

@@ -10,47 +10,26 @@ metadata:
 
 # Mantle Update
 
-Upgrade deliberately; never overwrite application-owned code.
+## Workflow
 
-1. Inspect `git status`, `package.json`, the lockfile and the installed
-   `@aotter/mantle` version. Keep unrelated local changes. Work on a branch.
-2. Choose an explicit target version (`npm view @aotter/mantle dist-tags`).
-   Read its release notes on GitHub and, after installing, its own
-   `node_modules/@aotter/mantle/docs/`. The old version's docs are not the new
-   contract.
-3. **From 0.1.x to 0.2:** stop here and follow
-   `node_modules/@aotter/mantle/docs/upgrade-0.1-to-0.2.md` after installing
-   the target. There is no codemod and no in-place database upgrade: the
-   project moves by hand, to a new database.
-4. Set `@aotter/mantle`, and `@aotter/mantle-ui` where present, to the same
-   exact version (`@aotter/mantle-admin-ui` is gone: the console is
-   `@aotter/mantle-ui/admin`), and update the lockfile with the
-   package manager. Review the dependency diff and any peer changes
-   `mantle generate` names.
-   With identity `mantle`, inspect auth database upgrade requirements in
-   `docs/handbook/cloudflare/authentication.md` before starting the new service.
-   Better Auth 1.7.0–1.7.2's required legacy `account.issuer` needs a
-   data-preserving host-specific constraint migration when moving to 1.7.7;
-   fresh-database success alone does not verify an upgrade. Back up the service's
-   own database and retain existing users, sessions, roles and content.
-5. Regenerate and check:
+Read the installed SDK README and version-matched handbook before editing.
 
-```sh
-pnpm exec mantle generate
-pnpm exec mantle generate --check
-pnpm exec tsc --noEmit
-```
+Follow the installed [native generation and service workflow](../../handbook/cloudflare/service-entry.md)
+with its [native contract](../../handbook/guides/native-execution.md) and [supported declarations](../../handbook/reference/features.md). Commit
+all generated output, run the same generation command with `--check`, and keep
+bundle `dist/` untracked. The app owns its verified Caller, handlers and native
+resources; Better Auth’s admin plugin `adminRoles` defines the admin layer (default `["admin"]`); `ctx.admin` accepts open role names.
 
-6. The preset (`src/service.ts`, `src/index.ts`, `src/handlers.ts`,
-   `wrangler.jsonc`) is never
-   rewritten. Generate into a scratch directory with the same manifests and
-   `mantle.config.json`, diff it against the project's files, and apply the
-   changes that matter by hand.
-7. Run the service locally and test its real routes and sign-in. Before
-   deploying a SQLite project, run
-   `mantle generate --check --database <local SQLite file>` to see what boot
-   will change.
+Pin exact target SDK/peer versions and read its release notes and Admin asset
+installation instructions. Core-to-native replaces app imports/wiring; it is not
+a package-only update. Preserve users, sessions, content and application code.
+Review emitted SQL/policy diffs and rehearse explicit data-preserving schema/auth/role
+migrations on a copy. Initial schema.sql never authorizes rebuilding production
+tables. Verify auth/Admin/MCP/REST, locks and persistence before authorized cutover.
 
-Report the old and new versions, the checks and their results, what changed
-in the service files, and what remains. A dependency update does not
-authorize a deploy. Never commit secrets.
+Follow [Native Admin](../../handbook/guides/native-admin.md) for the three-package
+SDK/Admin/shared-kit split and asset/extension/MCP App subpath moves; old UI
+subpaths have no compatibility aliases. Pin only actually published versions,
+or explicitly use a matching workspace preview. Recheck member and Admin OTP,
+all affected native routes, private field visibility, OCC and unknown outcomes.
+Do not publish a package as part of an application dependency update.

package/docs/source/scripts/postgres-adapter.ts

@@ -0,0 +1,101 @@
+/** Reusable application-owned adapter check. The factory must open an isolated, disposable database/schema. */
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { unstable_splitSqlQuery } from "wrangler";
+import type { Postgres } from "../src/kernel/contracts.js";
+import { procedure, transaction } from "../src/kernel/driver/postgres.js";
+import { generateOrThrow, writeGenerated } from "../tests/apps/link.js";
+
+export type PostgresAdapterFactory = () => Promise<{ db: Postgres; close(): Promise<void>; interactive?: boolean }>;
+
+const atom = (kind: string, name: string, spec: object) => JSON.stringify({ apiVersion: "cms.mantle.aotter.net/v2", kind, metadata: { name }, spec });
+const properties = { key: { type: "string" }, at: { type: "string", format: "date-time" }, day: { type: "string", format: "date" }, payload: { type: "object" }, units: { type: "integer" }, enabled: { type: "boolean" }, amount: { type: "number" } };
+const source = [
+  atom("Schema", "adapter_items", { title: "Adapter conformance", schema: { type: "object", properties, required: Object.keys(properties) }, uniqueIndexes: [["key"]] }),
+  atom("View", "adapter-items", { surface: "internal", sql: "SELECT id, key, at, day, payload, units, enabled, amount, created_at, CAST(at AS timestamptz) AS computed_at FROM adapter_items ORDER BY id" }),
+  atom("View", "adapter-wire", { surface: "public", sql: `SELECT units AS "quantityAlias", enabled, amount, version AS "versionAlias" FROM adapter_items ORDER BY id` }),
+  atom("Procedure", "adapter-create", { input: { type: "object", properties, required: Object.keys(properties) }, output: { type: "object" }, handler: { sql: "INSERT INTO adapter_items(key, at, day, payload, units, enabled, amount) VALUES(input.key, input.at, input.day, input.payload, input.units, input.enabled, input.amount) RETURNING id, at, day, payload, units, enabled, amount" } }),
+].join("\n---\n");
+
+/** Returns only a check count; assertions retain the exact failing contract. No latency or benchmark data. */
+export async function verifyPostgresAdapter(factory: PostgresAdapterFactory): Promise<{ checks: number }> {
+  const files = await generateOrThrow("bun-postgres", [{ sourceId: "adapter-conformance.yaml", text: source }]);
+  await mkdir(resolve(import.meta.dir, "../tests/apps/.generated"), { recursive: true });
+  const directory = await mkdtemp(resolve(import.meta.dir, "../tests/apps/.generated/adapter-"));
+  let client: Awaited<ReturnType<PostgresAdapterFactory>> | undefined;
+  let checks = 0;
+  try {
+    await writeGenerated(directory, files);
+    const app = await import(pathToFileURL(resolve(directory, "generated.ts")).href);
+    client = await factory();
+    const { db, interactive = true } = client;
+    for (const sql of unstable_splitSqlQuery(files["schema.sql"]!)) await db.unsafe(sql, []);
+    const caller = { kind: "system", reason: "adapter conformance" } as const;
+    const input = { key: "first", at: "2026-10-12T08:00:00.123456+08:00", day: "2024-02-29", payload: JSON.stringify({ text: "'\\", nested: [false, null] }), units: Number.MAX_SAFE_INTEGER, enabled: true, amount: 0.1 };
+    const output = await app.procedures["adapter-create"](db, caller, input);
+    const created = output.results[0][0];
+    assert.equal(created.at, "2026-10-12T00:00:00.123456Z", "declared RETURNING date-time retains microseconds");
+    assert.equal(created.day, input.day, "declared RETURNING date retains calendar day");
+    assert.deepEqual(created.payload, JSON.parse(input.payload), "JSON text is bound verbatim, not JSON-encoded twice");
+    assert.equal(String(created.units), String(input.units), "int8 retains a safe integer exactly");
+    assert.equal(created.enabled, true, "PostgreSQL boolean native output"); assert.equal(created.amount, input.amount, "declared number native output"); checks += 6;
+    const rows = await app.views["adapter-items"](db, caller, {});
+    const count = rows.count;
+    assert.ok(Array.isArray(rows), "unsafe returns a row array");
+    assert.equal(count, 1, "unsafe array carries affected count");
+    assert.equal(rows[0].at, created.at, "declared SELECT date-time retains microseconds");
+    assert.equal(rows[0].day, input.day);
+    assert.match(rows[0].created_at, /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{6}Z$/, "system timestamps have the same wire form");
+    // Computed outputs are native: the driver may return Date (milliseconds) or text (microseconds).
+    assert.ok(rows[0].computed_at instanceof Date || typeof rows[0].computed_at === "string"); checks += 6;
+    await assert.rejects(() => app.procedures["adapter-create"](db, caller, input), { code: "CONFLICT" }); checks++;
+    const step = { sql: "UPDATE adapter_items SET key = $1 WHERE id = $2 RETURNING id", binds: ["changed", "missing"], row: true };
+    await assert.rejects(() => procedure(db, [step], "adapter/zero"), { code: "CONFLICT" }); checks++;
+    const integer = await db.unsafe("SELECT CAST($1 AS bigint) AS positive, CAST($2 AS bigint) AS negative, CAST($3 AS numeric(15,2)) AS decimal", ["9007199254740993", "-9007199254740993", "1234567890123.45"]);
+    assert.equal(String(integer[0].positive), "9007199254740993", "unsafe int8 must not be rounded by an adapter");
+    assert.equal(String(integer[0].negative), "-9007199254740993");
+    assert.equal(integer[0].decimal, "1234567890123.45", "numeric text retains declared scale and precision"); checks += 3;
+    const { default: page } = await import(pathToFileURL(resolve(directory, "paged/wire/views/adapter-wire.ts")).href);
+    for (const value of ["9007199254740991", "9007199254740993", "-9007199254740993", "9223372036854775807", "-9223372036854775808"]) {
+      await db.unsafe("UPDATE adapter_items SET units=CAST($1 AS bigint), version=CAST($1 AS bigint)", [value]);
+      const wire = (await page(db, caller, {})).rows[0];
+      // The selected-boundary module returns exact integer text; REST/MCP turn safe values into numbers.
+      assert.equal(String(wire.quantityAlias), value); assert.equal(String(wire.versionAlias), value);
+      assert.equal(wire.enabled, true); assert.equal(wire.amount, input.amount); checks += 4;
+    }
+    await db.unsafe("UPDATE adapter_items SET version=1", []);
+    const store = app.store(db, caller), collection = store.collection("adapter_items");
+    const changed = { sql: "UPDATE adapter_items SET key = $1 WHERE id = $2 RETURNING id", binds: ["transaction", created.id], row: true };
+    if (!interactive) {
+      let calls = 0;
+      const tapped = { unsafe: (sql: string, values: any[]) => { calls++; return db.unsafe(sql, values); }, begin: db.begin.bind(db) };
+      const limitedStore = app.store(tapped, caller);
+      for (const run of [() => procedure(tapped, [changed, changed], "adapter/multi"), () => limitedStore.transaction(async () => { throw Error("callback must not run"); }), () => limitedStore.batch([limitedStore.collection("adapter_items").update(created.id, { key: "no-write" }, { lock: 1 }), limitedStore.collection("adapter_items").update(created.id, { key: "also-no-write" }, { lock: 1 })])]) {
+        await assert.rejects(run, (error: unknown) => {
+          const e = error as Error & { code?: string; status?: number };
+          return e instanceof Error && e.name === "ContractError" && e.code === "TRANSACTION_UNSUPPORTED" && e.status === 400 && /transaction/i.test(e.message);
+        });
+        assert.equal(calls, 0, "unsupported interactive transaction refuses before any statement"); checks += 2;
+      }
+    } else {
+      await transaction(db, async tx => {
+        await procedure(tx, [changed, changed], "adapter/nested-handle");
+        assert.equal((await tx.unsafe("SELECT key FROM adapter_items WHERE id = $1", [created.id]))[0].key, "transaction");
+        await assert.rejects(() => transaction(tx, async () => {}), /Nested transactions/);
+      }); checks += 2;
+      assert.equal((await db.unsafe("SELECT key FROM adapter_items WHERE id = $1", [created.id]))[0].key, "transaction", "begin commits after callback"); checks++;
+      const rollback = new Error("rollback sentinel");
+      await assert.rejects(() => transaction(db, async tx => { await tx.unsafe("UPDATE adapter_items SET key = $1 WHERE id = $2", ["rolled-back", created.id]); throw rollback; }), error => error === rollback);
+      assert.equal((await db.unsafe("SELECT key FROM adapter_items WHERE id = $1", [created.id]))[0].key, "transaction", "begin rolls back callback failure"); checks += 2;
+      await store.batch([collection.update(created.id, { key: "batch" }, { lock: 1 })]); checks++;
+    }
+    const uncertain = { unsafe: db.unsafe.bind(db), begin: async <T>(_options: string, callback: (tx: Postgres) => Promise<T>) => { await callback(db); throw new Error("socket lost at COMMIT"); } };
+    await assert.rejects(() => transaction(uncertain, async () => {}), { code: "OUTCOME_UNKNOWN" }); checks++;
+    return { checks };
+  } finally {
+    try { if (client) await client.close(); }
+    finally { await rm(directory, { recursive: true, force: true }); }
+  }
+}