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

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 }); }
+  }
+}

package/docs/upgrade-0.1-to-0.2.md

@@ -1,9 +1,24 @@
 # Upgrading from 0.1.x to 0.2.0 (for AI agents)
 
+For **0.2.0-alpha.7 and later**, use the
+[native SDK migration](handbook/releases/index.md#native-sdk-migration-alpha7),
+[current CLI](handbook/start/project-and-cli.md) and
+[app shell](examples/app-shell/). The application owns routing,
+Auth, native handles and database migrations; the former `createMantle` runtime,
+host presets, boot-time convergence and CLI flags below have been replaced.
+Install the same exact version of `@aotter/mantle`, `@aotter/mantle-ui` and,
+when selecting Admin, `@aotter/mantle-admin`. Start with a new database for a
+0.1.x migration and preserve every authorization, scope and OCC requirement.
+The remainder describes the earlier alpha contract for historical reference.
+
 No codemod, and no in-place upgrade of a 0.1.x database. A coding agent moves
-one project by hand with this guide. When it and ADR-0032 to ADR-0035
-(`docs/adr/`), ADR-0036 (host and dialect) or ADR-0038 (Bun) disagree, the
-ADR wins.
+one project by hand with this guide. When it and
+[ADR-0032](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0032-store-centric-core-and-service-contract.md),
+[ADR-0033](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0033-storage-converges-to-the-plan.md),
+[ADR-0034](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0034-store-is-authored-as-sql.md),
+[ADR-0035](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0035-sql-dialects.md),
+[ADR-0036](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0036-host-and-dialect.md) or
+[ADR-0038](https://github.com/aotter/mantle/blob/v0.2.0-alpha.7/docs/adr/0038-bun-native-host.md) disagree, the ADR wins.
 
 ## Rules
 
@@ -50,7 +65,7 @@ command; it never installs anything.
 - `features` is a subset of `mcp`, `admin`, `web`, in that order. The 0.1.x
   features `spec`, `runtime` and `api` are dropped: REST is always mounted.
 - `dialect` is `sqlite` (alias `d1`, the default, left out) or `postgres`
-  (PostgreSQL through Hyperdrive on `cloudflare`; Bun.SQL on `bun`, where it
+  (PostgreSQL through Hyperdrive on `cloudflare`; node-postgres on `bun`, where it
   is the default). A 0.1.x project was SQLite: keep `sqlite` (with
   `--host bun`, pass `--dialect sqlite`) unless the data also moves to
   PostgreSQL.
@@ -70,10 +85,10 @@ camelCase names.)
 
 | 0.1.x | 0.2.0 |
 |---|---|
-| `scope: { owner: $ctx.user.id }` | `scope: { owner: auth.uid() }`. The field is a required string, the leftmost column of an index (`indexes: [[owner]]`), and the first column of every `uniqueIndexes` entry. Store fills it; a write never sets it |
+| `scope: { owner: $ctx.user.id }` | `scope: "owner = auth.uid()"`. The field is a required string, the leftmost column of an index (`indexes: [[owner]]`), and the first column of every `uniqueIndexes` entry. Store fills it; a write never sets it |
 | `x-mantle-bind: ctx.user` on a field only its owner may see | remove the bind; add `scope` as above |
 | any other `x-mantle-bind: ctx.user` | remove the bind; every write that sets the field sets it to `auth.uid()`, never to an input |
-| `x-mantle-bind: ctx.staff` | remove the bind; set it to `auth.uid()` in writes whose Procedure `requires` `ctx.staff` |
+| `x-mantle-bind: ctx.staff` | remove the bind; set it to `auth.uid()` in writes whose Procedure requires `ctx.admin` |
 | `x-mantle-bind: now` | remove the bind; set it to `now()` in every write that sets it |
 | `searchableFields` | unchanged, now trigram full-text search; date and date-time fields are refused |
 
@@ -158,11 +173,11 @@ The generated types list exactly the plan's refs.
 |---|---|
 | `ctx.user` present | `ctx.caller.kind === "user"`. Never test `!== "anonymous"`: a schedule runs as `system` |
 | `ctx.user.id` | `ctx.caller.subject` (after that check) |
-| `ctx.staff` | `ctx.caller.kind === "user" && ctx.caller.role !== null` |
+| `ctx.staff` | `isAdmin(ctx.caller)` from `@aotter/mantle/contracts` |
 | `ctx.event`, `ctx.schedule` | `ctx.cause` (`kind`: `http`, `mcp`, `internal`, `schedule`, `lifecycle`); `ctx.cause.cron` is POSIX, so shift any cron string the code compares |
 | `ctx.event.entry` | **a loop** over `ctx.cause.rows` (one statement can touch many rows; never `rows[0]`). Rows are flat: `entry.data.x` → `row.x` |
 | `ctx.store.view(name, { params, page, show, search, filters })` | `ctx.store.view(name, { input, limit, cursor, search, filters })`; `search` and `filters` match only the View's `uiSchema.list.searchFields` and `filterFields` |
-| `runtime.entries`, `runtime.executeView`, `ctx.writeAtomically` | `ctx.store.select`, `ctx.store.view`, `ctx.store.write([...ops])` (all or nothing), `ctx.store.id()` |
+| `runtime.entries`, `runtime.executeView`, `ctx.writeAtomically` | `ctx.db.<schema>.get / first / find`, `ctx.store.view`, `ctx.store.write([...ops])` (all or nothing), `ctx.store.id()` |
 | `runtime.store.as(ctx)` | `runtime.store.as(caller)` |
 | calling another Procedure through a `getRuntime` closure | `await ctx.invoke("procedure-name", input)` (keeps the caller, re-checks its auth) |
 
@@ -179,8 +194,9 @@ only in trusted host code.
    old Worker into the new files by hand.
 3. With `identity: mantle`, sign-in uses a console email sender locally;
    replace it with a real `EmailSender` before deploying.
-4. Staff MCP stays at `/mcp/staff`, behind an OAuth token with the `mcp`
-   scope and a staff role; MCP clients keep their URL.
+4. Admin MCP moves from `/mcp/staff` to `/mcp/admin`. Update MCP client URLs.
+   It admits only the admin layer classified by Better Auth’s admin plugin
+   `adminRoles` (default `["admin"]`), and requires the `mcp` scope for tokens.
 5. Import data into the new database through `runtime.store`. A scoped row
    goes through `runtime.store.as(<its owner's caller>)`, so the scope field is
    the owner. `status`, `created_at` and `author_id` cannot be imported:

package/package.json

@@ -1,146 +1,154 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.2.0-alpha.1",
-  "description": "Mantle: a manifest-driven service core. Store authored as SQL, surfaces as Fetch functions, and the mantle CLI.",
-  "license": "Apache-2.0",
-  "homepage": "https://mantle.tools/",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/aotter/mantle.git",
-    "directory": "packages/mantle"
-  },
+  "version": "0.2.0-alpha.10",
   "type": "module",
   "sideEffects": false,
-  "exports": {
-    ".": {
-      "types": "./dist/core/index.d.ts",
-      "import": "./dist/core/index.js"
-    },
-    "./spec": {
-      "types": "./dist/spec/index.d.ts",
-      "import": "./dist/spec/index.js"
-    },
-    "./d1": {
-      "types": "./dist/d1/index.d.ts",
-      "import": "./dist/d1/index.js"
-    },
-    "./d1/compile": {
-      "types": "./dist/d1/compile/index.d.ts",
-      "import": "./dist/d1/compile/index.js",
-      "default": "./dist/d1/compile/index.js"
-    },
-    "./postgres": {
-      "types": "./dist/postgres/index.d.ts",
-      "import": "./dist/postgres/index.js"
-    },
-    "./postgres/compile": {
-      "types": "./dist/postgres/compile/index.d.ts",
-      "import": "./dist/postgres/compile/index.js",
-      "default": "./dist/postgres/compile/index.js"
-    },
-    "./cloudflare": {
-      "types": "./dist/cloudflare/index.d.ts",
-      "import": "./dist/cloudflare/index.js"
-    },
-    "./auth": {
-      "types": "./dist/auth/index.d.ts",
-      "import": "./dist/auth/index.js"
-    },
-    "./admin": {
-      "types": "./dist/admin/index.d.ts",
-      "import": "./dist/admin/index.js"
-    },
-    "./mcp": {
-      "types": "./dist/mcp/index.d.ts",
-      "import": "./dist/mcp/index.js"
-    },
-    "./web": {
-      "types": "./dist/web/index.d.ts",
-      "import": "./dist/web/index.js"
-    },
-    "./testing": {
-      "types": "./dist/testing/index.d.ts",
-      "import": "./dist/testing/index.js"
-    },
-    "./package.json": "./package.json",
-    "./bun": {
-      "types": "./dist/bun/index.d.ts",
-      "import": "./dist/bun/index.js"
-    }
-  },
-  "bin": {
-    "mantle": "./dist/cli/main.js"
+  "engines": {
+    "node": ">=22.22.0"
   },
   "files": [
     "dist",
-    "docs"
+    "docs",
+    "skills",
+    "README.md"
   ],
-  "publishConfig": {
-    "access": "public",
-    "tag": "alpha",
-    "registry": "https://registry.npmjs.org"
+  "bin": {
+    "mantle": "./dist/infrastructure/cli.js"
   },
   "dependencies": {
+    "esbuild": "0.28.1",
+    "jsonc-parser": "3.3.1",
     "@pgsql/types": "18.0.0",
     "libpg-query": "18.1.5",
     "pgsql-deparser": "18.3.8",
-    "yaml": "^2.9.0",
-    "zod": "^4.5.4"
+    "yaml": "^2.9.1",
+    "zod": "^4.6.5"
   },
-  "devDependencies": {
-    "@better-auth/cimd": "1.7.2",
-    "@better-auth/core": "1.7.2",
-    "@better-auth/mcp": "1.7.2",
-    "@better-auth/oauth-provider": "1.7.2",
-    "@better-auth/utils": "0.4.2",
-    "@modelcontextprotocol/client": "2.1.0",
-    "@modelcontextprotocol/ext-apps": "2.0.0",
-    "@modelcontextprotocol/server": "2.1.0",
-    "@types/node": "^26",
-    "@types/pg": "8.23.1",
-    "better-auth": "1.7.2",
-    "bun-types": "1.3.14",
-    "pg": "8.23.1",
-    "typescript": "^6.0.3",
-    "vitest": "^4.1.11",
-    "wrangler": "4.126.0"
+  "exports": {
+    ".": "./dist/infrastructure/generate.js",
+    "./generate": "./dist/infrastructure/generate.js",
+    "./contracts": "./dist/kernel/contracts.js",
+    "./authorization": "./dist/kernel/authorization.js",
+    "./translations": "./dist/kernel/translations.js",
+    "./driver/transaction-context": "./dist/kernel/driver/transaction-context.js",
+    "./scalars": "./dist/kernel/scalars.js",
+    "./binds": "./dist/kernel/binds.js",
+    "./testing": "./dist/testing/index.js",
+    "./host-access": "./dist/kernel/host-access.js",
+    "./host-caller": "./dist/kernel/host-caller.js",
+    "./user-fields": "./dist/kernel/user-fields.js",
+    "./sweep": "./dist/kernel/sweep.js",
+    "./cron": "./dist/kernel/cron.js",
+    "./store": "./dist/kernel/store.js",
+    "./dialect/sqlite": "./dist/kernel/dialect/sqlite.js",
+    "./dialect/postgres": "./dist/kernel/dialect/postgres.js",
+    "./driver/bun-sqlite": "./dist/kernel/driver/bun-sqlite.js",
+    "./driver/d1": "./dist/kernel/driver/d1.js",
+    "./driver/postgres": "./dist/kernel/driver/postgres.js",
+    "./email": "./dist/kernel/email.js",
+    "./paging": "./dist/kernel/paging.js",
+    "./publishing": "./dist/kernel/publishing.js",
+    "./rest": "./dist/kernel/rest.js",
+    "./mcp": "./dist/kernel/mcp.js",
+    "./mcp-apps": "./dist/kernel/mcp-apps.js",
+    "./web": "./dist/kernel/web.js",
+    "./validation": "./dist/kernel/validation.js",
+    "./site": "./dist/kernel/site.js",
+    "./media": "./dist/kernel/media.js",
+    "./media/r2": "./dist/kernel/r2-media.js",
+    "./auth": "./dist/auth/caller.js",
+    "./auth/adapter": "./dist/auth/adapter.js",
+    "./auth/oauth": "./dist/auth/oauth.js",
+    "./auth/routes": "./dist/auth/routes.js",
+    "./auth/identity": "./dist/auth/identity.js",
+    "./auth/hardening": "./dist/auth/hardening.js",
+    "./auth/admin": "./dist/auth/admin.js",
+    "./bun/assets": "./dist/bun/assets.js",
+    "./surface": "./dist/kernel/surface.js",
+    "./json-body": "./dist/kernel/json-body.js",
+    "./generate/auth": "./dist/infrastructure/generateAuth.js",
+    "./package.json": "./package.json",
+    "./describe": "./dist/domain/describe/index.js",
+    "./target-hash": "./dist/domain/describe/target-hash.js"
   },
   "peerDependencies": {
-    "@better-auth/cimd": "1.7.2",
-    "@better-auth/mcp": "1.7.2",
-    "@better-auth/oauth-provider": "1.7.2",
-    "@modelcontextprotocol/ext-apps": "2.0.0",
-    "@modelcontextprotocol/server": "2.1.0",
-    "better-auth": "1.7.2"
+    "@modelcontextprotocol/server": "2.2.0",
+    "@better-auth/core": "1.7.7",
+    "@better-auth/oauth-provider": "1.7.7",
+    "better-auth": "1.7.7"
   },
   "peerDependenciesMeta": {
-    "@better-auth/cimd": {
+    "@modelcontextprotocol/server": {
       "optional": true
     },
-    "@better-auth/mcp": {
+    "@better-auth/core": {
       "optional": true
     },
     "@better-auth/oauth-provider": {
       "optional": true
     },
-    "@modelcontextprotocol/ext-apps": {
-      "optional": true
-    },
-    "@modelcontextprotocol/server": {
-      "optional": true
-    },
     "better-auth": {
       "optional": true
     }
   },
-  "engines": {
-    "node": ">=22"
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.2.0",
+    "@modelcontextprotocol/server": "2.2.0",
+    "@better-auth/core": "1.7.7",
+    "@better-auth/oauth-provider": "1.7.7",
+    "@better-auth/test-utils": "1.7.7",
+    "@cloudflare/workers-types": "^5.20261008.1",
+    "@types/node": "^26",
+    "better-auth": "1.7.7",
+    "bun-types": "1.4.2",
+    "postgres": "3.4.9",
+    "typescript": "^6.0.3",
+    "wrangler": "4.145.0",
+    "vitest": "^5.0.1"
+  },
+  "description": "Agent-native app SDK and backend compiler: YAML manifests to native SQL (SQLite, Cloudflare D1, PostgreSQL) and typed TypeScript; optional REST and MCP.",
+  "keywords": [
+    "mantle",
+    "agent-native",
+    "sdk",
+    "backend",
+    "yaml",
+    "code-generation",
+    "sql",
+    "sqlite",
+    "postgresql",
+    "cloudflare-d1",
+    "cloudflare-workers",
+    "bun",
+    "typescript",
+    "mcp",
+    "model-context-protocol"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://mantle.tools/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aotter/mantle.git",
+    "directory": "packages/mantle"
+  },
+  "bugs": {
+    "url": "https://github.com/aotter/mantle/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha",
+    "registry": "https://registry.npmjs.org"
   },
   "scripts": {
-    "prebuild": "rm -rf dist .tsbuildinfo",
-    "build": "tsc -b tsconfig.lib.json",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.lib.json && node scripts/bundle-compiler.mjs && node scripts/prune-declarations.mjs",
     "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "vitest run",
-    "test:bun": "bun test/bun/native.ts"
+    "test": "bun test tests/*.test.ts && bun run test:compiler",
+    "generate": "bun src/infrastructure/cli.ts",
+    "test:native": "bun scripts/verify-native.ts",
+    "bench": "bun scripts/verify-native.ts --bench",
+    "check:size": "bun run build && bun scripts/check-size.ts",
+    "check:package": "bun run build && bun scripts/check-package.ts",
+    "test:compiler": "tsc --noEmit -p tsconfig.compiler.json && vitest run --config vitest.compiler.config.ts",
+    "check:startup": "bun scripts/check-size.ts --startup-only"
   }
 }

package/skills/README.md

@@ -0,0 +1,67 @@
+# SKILL.md briefs (mantle)
+
+Agent-readable skills for consumers of `@aotter/mantle` 0.2. There are two
+distributions (ADR-0032 decision 13):
+
+- **The plugin** ships one OSS authoring skill, [`mantle`](mantle/SKILL.md),
+  without a hosted-service MCP connection or transport.
+- **The npm package** ships the workflow skills under `docs/skills/`. An agent
+  reads them from `node_modules/@aotter/mantle/docs/skills/`, matched to the
+  installed version. Nothing copies them into a project; 0.2 has no
+  `mantle skills` command.
+
+| Skill | When to invoke |
+|---|---|
+| [`mantle`](mantle/SKILL.md) | Create or continue a Mantle application and deploy to a user-owned host. |
+| [`develop`](../docs/skills/develop/SKILL.md) | Change manifests, SQL, handlers, the service entry or surfaces of an existing project. |
+| [`integrate`](../docs/skills/integrate/SKILL.md) | Add Mantle to an application that has its own code, users or data, or rebuild one and migrate. |
+| [`update`](../docs/skills/update/SKILL.md) | Upgrade `@aotter/mantle`, including from 0.1.x. |
+| [`provision`](../docs/skills/provision/SKILL.md) | Ship to Cloudflare Workers or ChatGPT Sites with production sign-in. |
+| [`media-gc`](../docs/skills/media-gc/SKILL.md) | Audit or remove stale, uncommitted R2 uploads. |
+
+## Install
+
+Use the [agent setup guide](../docs/handbook/guides/agent-setup.md) for Codex,
+Claude Code, Cursor and GitHub Copilot. Pin the plugin checkout to the same
+release tag as the application's SDK; alpha releases on `develop` can be newer
+than the default `main` branch. For a skill-only installation:
+
+```sh
+npx skills add https://github.com/aotter/mantle/tree/v0.2.0-alpha.10 --skill mantle
+```
+
+The explicit skill name excludes repository maintainer skills. The manifests
+are generated by `scripts/sync-plugin-manifests.mjs` and checked with `--check`.
+When upgrading, update the marketplace ref or local tagged checkout and refresh
+the plugin. Verify the loaded manifest version; Claude Code's plugin version
+is Core's, so packaged skill changes reach users through the next Core release.
+
+## Disclosure audit
+
+Every skill is one `SKILL.md`; the plugin skill carries local acceptance references.
+`scripts/check-skills.mjs` holds this table, the front matter and the links to
+each other: `metadata.projection` is `plugin` for `skills/mantle` and
+`package` for `docs/skills/*`, a reason in the last column must equal
+`metadata.projectionReason`, and a relative link must stay inside what ships
+(the skill's own directory for the plugin, `docs/` for the package).
+
+| Skill | Routes on | Entry constraints | Distribution | Restricted because |
+|---|---|---|---|---|
+| `mantle` | new project, existing project, self-host deployment | the installed package's docs win; never use the SDK checkout as the application; no deploy during a cold start | plugin | The plugin's authoring entry skill is installed from the repository; workflow documentation comes from the installed SDK package. |
+| `develop` | manifest, SQL, handler, service or surface work | read the installed version first; never edit generated files; writes through Store/Procedures, richer reads through internal Views | package | — |
+| `integrate` | an application with its own code, users or data | inspect before choosing; the application keeps its users; one writer per table | package | — |
+| `update` | an SDK upgrade | never overwrite application files; 0.1.x moves by the upgrade guide to a new database | package | — |
+| `provision` | ship to production | secrets never in source, chat or logs; a new database for 0.2; self-hosting is always an option | package | Creates remote resources and handles production secrets; opt-in only. |
+| `media-gc` | stale R2 uploads | audit by default; exact keys only, never a prefix delete; re-audit before applying | package | Destructive remote object deletion and Cloudflare-specific; opt-in only. |
+
+## Audience
+
+These are for **AI agents acting for consumers of Mantle**, not for
+contributors to the SDK, who read the repository's `CONTRIBUTING.md`.
+
+## Conventions
+
+Each SKILL.md has front matter (`name`, a trigger-complete `description`,
+`metadata.source`, `sourcePath`, `applies_to`, `projection`), the reads to do
+first, concrete commands, the rules an agent must not break, and what to report
+when done. Commands and prose match the package version that carries the skill.

package/skills/mantle/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: mantle
+description: Create, continue, test or deploy a Mantle application using installed @aotter/mantle docs, including manifests, SQL Views and Procedures, MCP tools, app-built Admin, mantle generate and Mantle upgrades.
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: skills/mantle/SKILL.md
+  applies_to: mantle 0.2
+  projection: plugin
+  projectionReason: The plugin's authoring entry skill is installed from the repository; workflow documentation comes from the installed SDK package.
+---
+
+# Mantle
+
+The Mantle plugin's one skill. It installs no SDK and creates nothing by
+itself. Once a project has `@aotter/mantle`, the installed package is the
+authority: `node_modules/@aotter/mantle/README.md` and
+`node_modules/@aotter/mantle/docs/`. Prefer them over this file, the SDK
+checkout, or any online copy.
+
+## Start with `mantle help`
+
+Run `mantle help` first (in a project: `npx mantle help`; before one exists:
+`npx @aotter/mantle@<exact version> help`). It prints the installed version's
+entry page and every topic; `mantle help <topic>` prints one page with the next
+and linked topics as commands. Follow it rather than browsing the SDK checkout
+or an online copy.
+
+## Find the project and its version
+
+Work in the user's application, outside the SDK checkout. Read package.json, the lockfile, installed SDK README and node_modules/@aotter/mantle/docs/. Those files define the exact version's contract. Preserve existing identity, handles, routes and resources.
+For existing older applications, use their installed docs until the user requests an upgrade; if an older version
+lacks a guide named here, record the missing guidance and keep that version's contract.
+
+## Choose the installed package skill
+
+- Read `node_modules/@aotter/mantle/docs/skills/develop/SKILL.md` to change an existing project's manifests, SQL, handlers, service entry or surfaces.
+- Read `node_modules/@aotter/mantle/docs/skills/integrate/SKILL.md` to add Mantle to an application with existing code, users or data.
+- Read `node_modules/@aotter/mantle/docs/skills/update/SKILL.md` to upgrade Mantle, including from 0.1.x.
+- Read `node_modules/@aotter/mantle/docs/skills/provision/SKILL.md` only for an authorized production deployment.
+- Read `node_modules/@aotter/mantle/docs/skills/media-gc/SKILL.md` only to audit or remove stale uncommitted media uploads.
+
+## New application
+
+Node must be 22.22 or newer. Create it with `npx @aotter/mantle@<exact version> init <directory>`, then follow
+`mantle help` ("Build from a product brief") and the app's `README.md`. Without the user listing them, a complete app
+includes:
+
+- Email OTP sign-in, the two roles `admin` and `user`, Admin for `admin`, MCP for both roles (`/mcp`, `/mcp/admin`)
+  and REST: the shell already wires them; keep them.
+- Real business rules in SQL Procedures (`mantle help sql-patterns`), not in handler code around separate writes.
+- For visitor pages, everything in `mantle help public-pages` (SEO, AEO, sitemap, robots, `llms.txt`), styled.
+- Local HTTP checks (`mantle help local-testing`), then independent acceptance with `pnpm accept`
+  (`mantle help agent-workflow-acceptance`).
+
+Take patterns from `mantle help examples` into the app's own manifests and `src/`; do not copy an example directory
+over the app. Resolve each `AGENT:` or name the ones you left. Generation only, inside an app you already have: skip
+`init` and use `mantle generate` (`mantle help project-and-cli`).
+
+## Accept before reporting done
+
+Before reporting any new app or feature as done, follow `mantle help agent-workflow-acceptance`: a private rubric,
+then one fresh agent per role given only its role and the URLs `pnpm accept` prints, at most three rounds. If it was
+not run, report the work as UNVERIFIED rather than done; if it could not run, BLOCKED.
+
+## Deployment
+
+Deploy only when the user requests it, following the installed `docs/skills/provision/SKILL.md` and the selected
+host's native workflow. Local project creation alone is not deployment authorization.
+
+## Existing project and handoff
+
+Preserve the user's manifests, `src/` files, identity, package versions and provider resources. Run the project's
+generate command with `--check` and its own tests before and after a change.
+
+Report the project path, the exact Mantle version, what you changed, the checks you ran with their results, the
+independent acceptance verdict (CONVERGED / BLOCKED / UNVERIFIED), and anything left for the user.

package/dist/admin/consent.d.ts

@@ -1,17 +0,0 @@
-/** What the consent screen and the connected-apps list need of an OAuth provider, and the member list's cursor (Admin's, used by the identity provider). */
-export interface OAuthConsentRequest {
-    readonly clientName: string;
-    readonly redirectUri: string;
-    readonly scopes: readonly string[];
-    /** Signed provider query returned unchanged with the consent decision. */
-    readonly oauthQuery: string;
-}
-export interface OAuthConsentInfo {
-    readonly id: string;
-    readonly clientId: string;
-    readonly clientName: string;
-    readonly scopes: readonly string[];
-}
-export declare function encodeMemberCursor(createdAt: string, id: string): string;
-export declare function decodeMemberCursor(cursor: string): readonly [string, string] | null;
-//# sourceMappingURL=consent.d.ts.map

package/dist/admin/consent.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"consent.d.ts","sourceRoot":"","sources":["../../src/admin/consent.ts"],"names":[],"mappings":"AAAA,4JAA4J;AAE5J,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAID,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAExE;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAQnF"}

package/dist/admin/consent.js

@@ -1,17 +0,0 @@
-/** What the consent screen and the connected-apps list need of an OAuth provider, and the member list's cursor (Admin's, used by the identity provider). */
-const PREFIX = "m:";
-export function encodeMemberCursor(createdAt, id) {
-    return `${PREFIX}${encodeURIComponent(JSON.stringify([createdAt, id]))}`;
-}
-export function decodeMemberCursor(cursor) {
-    if (!cursor.startsWith(PREFIX))
-        return null;
-    try {
-        const v = JSON.parse(decodeURIComponent(cursor.slice(PREFIX.length)));
-        return Array.isArray(v) && v.length === 2 && typeof v[0] === "string" && !Number.isNaN(Date.parse(v[0])) && typeof v[1] === "string" && v[1] ? [v[0], v[1]] : null;
-    }
-    catch {
-        return null;
-    }
-}
-//# sourceMappingURL=consent.js.map