@aotter/mantle 0.1.4 → 0.1.5-alpha.1

package/dist/cli/main.js

@@ -25,15 +25,16 @@ async function main() {
             return 2;
     }
 }
-export const MANTLE_OVERVIEW = `mantle — compile manifests into a RuntimePlan and typed binding
+export const MANTLE_OVERVIEW = `mantle — compile manifests and assemble selected application features
 
 Overview
-  Optional surfaces — take only what you need. Admin is opt-in. You can ship a
-  complete service with no Dev UI, no visitor frontend, and no extra packages.
+  New applications default to Spec, Runtime, API, MCP, Admin, and a blank Web
+  home. Pass --host cf or --host chatgpt-sites, or use --features for a smaller
+  positive selection. Existing authored applications keep compile-only mode.
 
-  Minimal — Spec + generate
-    validate + generate compile manifests into a sealed plan and typed binding.
-    Embed that binding in an existing host. No Admin, no visitor UI.
+  Host-free — Spec only
+    mantle generate --features spec compiles a sealed plan and typed binding
+    without Runtime, Admin, visitor UI, or a host.
 
   Runtime / adapter
     Bind Runtime through an adapter (Cloudflare Worker, Bun, Vercel, or yours).
@@ -41,10 +42,9 @@ Overview
     See docs/examples/host-minimal-worker or
     node_modules/@aotter/mantle/docs/examples/host-minimal-worker.
 
-  Opt-in — Admin / Dev UI
-    Add @aotter/mantle-admin and @aotter/mantle-admin-ui only when humans need
-    a console. Then re-run generate, bind wrangler ASSETS, and open
-    /admin/sign-in (local email OTP via ConsoleEmailSender).
+  Selected Admin / Dev UI
+    New full applications include the prebuilt UI. Reduced applications can
+    omit it; selected packages must be installed before generation completes.
     See docs/examples/host-local-admin-otp or
     node_modules/@aotter/mantle/docs/examples/host-local-admin-otp.
 

package/docs/adr/0021-retire-starter-scaffolding.md

@@ -1,6 +1,6 @@
 # ADR-0021: Author applications directly; retire Starter scaffolding
 
-Status: Accepted by owner, 2026-09-08 (#786). Supersedes ADR-0018 for the 0.1.2 line.
+Status: Accepted by owner, 2026-09-08 (#786). Supersedes ADR-0018 for the 0.1.2 line. Its no-initialization clause is superseded by [ADR-0026](0026-progressive-generate.md) for 0.1.5.
 
 Core is an embeddable manifest engine. Applications own package manifests,
 Worker entries, provider configuration, business manifests and visitor UI.

package/docs/adr/0026-progressive-generate.md

@@ -0,0 +1,36 @@
+# ADR-0026: Progressive application generation
+
+**Status:** Accepted by owner for the 0.1.5 line (#1081–#1086). Supersedes the no-initialization clause of ADR-0021; direct authorship and optional package boundaries remain.
+
+Mantle is progressive. A new application defaults to Spec, Runtime, API, MCP, Admin, and an editable blank Web home so an agent does not forget the optional Admin composition. `--features` is a positive replacement list over `spec,runtime,api,mcp,admin,web`; dependencies are closed automatically. `spec` alone is host-free. The first generated hosts are `cf` and `chatgpt-sites`. Only host-dependent selections require `--host`; a TTY may prompt, while headless use must pass it explicitly.
+
+| Feature | Required features | Direct package additions |
+| --- | --- | --- |
+| `spec` | — | `@aotter/mantle`, `zod` peer |
+| `runtime` | `spec` | Host adapter; current CF adapter also brings Admin/Auth/Web transitively |
+| `api` | `runtime` | Host route composition and `hono` peer |
+| `mcp` | `runtime` | Host MCP route composition |
+| `admin` | `runtime,api,mcp` | `@aotter/mantle-admin`, `@aotter/mantle-admin-ui`; CF owner auth also uses `@aotter/mantle-auth` |
+| `web` | `runtime` | `@aotter/mantle-web` and a user-owned blank home |
+
+The host adapter's declared peers (`better-auth`, `hono`, `zod`, `aws4fetch`) are installed for host-dependent selections until its package dependency graph is split. A reduced selection still omits unselected routes and assets; it does not claim smaller transitive installation today.
+
+An application with only Git, installed skills, package metadata, a lockfile, README, and installed dependencies is new. Existing manifests or application code remain in direct-authoring compile mode. A saved `mantle.config.json` decides subsequent runs before that heuristic. V1 refuses host changes and feature-list changes after selection; application owners can make an explicit migration rather than have generation delete routes or data. An explicitly named missing manifest path is an error. A new default manifest directory may be absent or empty, yielding a valid empty plan without a fake business Schema.
+
+Generation preflights selection, manifest validity, package/script conflicts, file ownership, and symlink escapes before writing. It saves the selection and adds only absent package declarations and scripts; it does not run a package manager. Selected Mantle packages use the running CLI's exact version. Missing selected packages produce an incomplete, nonzero result and an explicit install-and-rerun instruction. `--check` never writes, installs, prompts, or provisions. Generated code and assets remain CLI-owned; the editable frontend, host config, identity, secrets, handlers, and historical migrations are application-owned. A later SDK upgrade does not overwrite them. Clean builds remove only copied output.
+
+Cloudflare currently has a facade with transitive Admin/Auth/Web dependencies and mounts OAuth/MCP unconditionally. Host generation must use a lower-level composition for reduced selections or change that facade; omitting dependencies from a manifest does not prove route omission. Cloudflare D1 remains runtime-managed. ChatGPT Sites uses reviewed, append-only managed migrations with applied-state checks (owned by #1086). Neither host generator provisions resources or deploys.
+
+This decision restores a convenient default while keeping the sealed Manifest-to-RuntimePlan pipeline and user-owned application source. It does not reintroduce a remote Starter catalog or a `mantle create` command.
+
+## 2026-09-25 amendment — existing application integration
+
+The original implementation added `--adopt` to convert an existing authored
+application into the generated-project layout. This amendment removes that
+mode. Applications with their own host shape continue direct authoring;
+integrating Mantle is guided by the version-matched `integrate` consumer skill.
+The agent may embed selected capabilities, replace one part at a time, or
+build a fresh Mantle application and migrate frontend and data. The CLI owns
+only deterministic generation and its declared checks; it does not certify
+arbitrary user-owned host wiring. A saved generated project still reruns from
+its own configuration, with file ownership and migration safeguards intact.

package/docs/adr/0027-scheduled-procedure-triggers.md

@@ -0,0 +1,31 @@
+# ADR-0027: Scheduled Procedure Triggers
+
+**Status:** Accepted for 0.1.5 (#1087). Revises the closed Trigger-source grammar from ADR-0001 and the host-only cron guidance of #322.
+
+**Date:** 2026-09-25
+
+## Context
+
+The earlier contract kept cron outside the Manifest graph. That forced an application Worker to invoke a Procedure by name with its own caller context, leaving scheduling invisible to validation and the compiled plan. A portable declaration is needed without pretending that every host can register a cron event.
+
+## Decision
+
+`Trigger.spec.source` gains `kind: schedule`, a five-field Cloudflare UTC `cron` (weekday 1=Sunday), and optional `enabled` (default true). It targets one Procedure whose input accepts `{}` and requires no user or staff authorization. The compiled plan carries Trigger identity, expression, target, enabled state, and the required `cloudflare` host. No HTTP route or user identity is granted.
+
+Cloudflare's `scheduled` entry finds enabled plan entries with the exact incoming expression and invokes them in Trigger-name order through the existing Procedure pipeline, continuing after individual failures and reporting them together. The system context has null user and staff, no credential, and `ctx.schedule` with stable `${trigger}:${scheduledTime}` identity. The application registers exact expressions with Wrangler. Cloudflare Cron Triggers do not document automatic retries; handlers still use the identity for possible duplicate/manual replay. Other hosts reject enabled schedules rather than silently omit them.
+
+## Consequences
+
+The grammar and sealed plan version advance. Applications must rerun `mantle generate` after upgrading. A Procedure needing staff authorization cannot run from a schedule. Cron provisioning, retries, retention and exactly-once execution remain host/operator responsibilities; the runtime does not claim them.
+
+## Alternatives
+
+Keeping host-only calls would preserve the old grammar but fail static validation and omit the feature from introspection. A general background-job framework would add storage and scheduling responsibilities without a second host implementation.
+
+## How to apply
+
+Declare a schedule Trigger, export `worker.scheduled`, and register its expression in `wrangler.jsonc`. Use `ctx.schedule.id` to deduplicate writes. See [Trigger reference](../handbook/reference/trigger.md#schedule-source).
+
+## Implementation status
+
+Implemented in the 0.1.5 scheduled Procedure PR, with parser, linker, compiler, runtime and Cloudflare adapter tests.

package/docs/adr/0028-schema-ttl-expiry.md

@@ -0,0 +1,33 @@
+# ADR-0028: Logical Schema TTL before explicit physical cleanup
+
+**Status:** Accepted for 0.1.5 (#1088).
+
+**Date:** 2026-09-25
+
+## Context
+
+An application needs a portable expiry rule across D1 and Bun SQLite. A cron-only delete task cannot guarantee that readers stop seeing expired data if it runs late or fails. Applying a new policy to a populated table must not silently bulk-delete rows.
+
+## Decision
+
+`Schema.spec.ttl` names one top-level date-time field and a nonnegative `expireAfterSeconds`. At `timestamp + duration <= now`, semantic reads exclude the row. Missing, null and unparseable legacy dates never expire. Declarative Views include the same predicate. Native SQL Views are rejected while any TTL Schema exists, and shared caching of a TTL View is rejected. The compiled plan and introspection expose the policy. Public Cloudflare pages derived from TTL collections use `no-store` rather than shared caching.
+
+SQLite storage implements an optional bounded `ExpirySweeper`. A sweep previews by default; `delete: true` is required for physical removal. It returns counts and a cursor, selects at most 100 expired IDs in stable order, and rechecks expiry in one bounded delete statement. A failed page can be retried with the previous cursor. Ref Procedures can call the semantic capability, including from a scheduled Trigger. No host automatically invokes it.
+
+Physical TTL removal does not fire before/after entry lifecycle hooks. Expiry already changed logical visibility; cleanup reclaims storage rather than representing an editorial deletion. Consumers needing business actions at expiry must implement them in an idempotent scheduled Procedure before calling the sweep.
+
+## Consequences
+
+Adding or shortening TTL changes read visibility immediately but never starts physical deletion. Owners preview counts and choose when to sweep; expired rows can still occupy unique indexes until removal. Other adapters must implement equivalent read filtering and a sweep or fail closed for TTL plans. The runtime does not promise an exact deletion time.
+
+## Alternatives
+
+Scheduler-driven deletion alone leaves a visibility gap. Implicit migration-time cleanup risks irreversible bulk deletion. Firing ordinary deletion hooks during storage reclamation would cause delayed, retry-sensitive business effects after the row was already logically gone.
+
+## How to apply
+
+Declare `ttl` on a Schema, use declarative Views, preview with `runtime.sweepExpired`, then explicitly request deletion page by page. See [Schema TTL](../handbook/reference/schema.md#ttl).
+
+## Implementation status
+
+Implemented in the 0.1.5 TTL PR for the SQLite family, with Bun and local D1 conformance checks.

package/docs/adr/README.md

@@ -21,10 +21,13 @@ Records of *why* mantle ended up shaped this way. The numbering preserves POC AD
 | [0018](0018-core-starters-repository-boundary.md) | Core produces published SDK artifacts; the separate starters repository validates them as an external consumer. Revisit after release-contract simplification. | Superseded by 0021 |
 | [0019](0019-sealed-manifest-runtime-pipeline.md) | One sealed source-to-runtime pipeline, semantic storage seam, and optional Web/Admin/platform dependency direction. | Accepted |
 | [0020](0020-builtin-handler-contracts-and-matched-upsert.md) | Static builtin handler contracts and natural-key matched upsert (`handler.match`). | Accepted + amended by 0022 |
-| [0021](0021-retire-starter-scaffolding.md) | Direct authoring; retire Starter scaffolding. | Accepted; supersedes 0018 |
+| [0021](0021-retire-starter-scaffolding.md) | Direct authoring; retire Starter scaffolding. | Accepted; no-initialization clause superseded by 0026 |
 | [0022](0022-caller-observed-version-occ.md) | Caller-observed `expectedVersion` for Admin bind and builtin upsert OCC. | Accepted |
 | [0024](0024-manifest-native-schema-tables.md) | Materialize each Schema as a native storage table and deploy reviewed migration artifacts. | Accepted; authored-native-name clauses superseded by 0025 |
 | [0025](0025-reserved-native-columns-and-published-only-public-views.md) | Reserve the six native column names, let `indexes` reference them, and compile public publishing Views published-only. | Accepted |
+| [0026](0026-progressive-generate.md) | Progressive `mantle generate` with a full default, positive features, saved host selection, and user-owned source. | Accepted; supersedes part of 0021 |
+| [0027](0027-scheduled-procedure-triggers.md) | Schedule Triggers in the sealed plan with Cloudflare-hosted invocation and system identity. | Accepted for 0.1.5 |
+| [0028](0028-schema-ttl-expiry.md) | Logical TTL on Schema reads with preview-first, explicit bounded cleanup. | Accepted for 0.1.5 |
 
 ## Reading order
 
@@ -36,7 +39,7 @@ If you're new to the codebase:
 4. **0007** — what running the SDK feels like as an AI author (and as the operator agent).
 5. **0011** — the boundary between the runtime and the adapter.
 6. **0010** — how locale flows through the system.
-7. **0021** — current direct-authoring boundary; **0013** is historical install-session context.
+7. **0026** — current progressive generation boundary; **0021** retains the direct-authoring history and **0013** is historical install-session context.
 8. **0002, 0008** — the two ADRs that touch every diagnostic and every binding.
 
 ## What's NOT here (and why)

package/docs/agent-prompts.md

@@ -1,102 +1,64 @@
 # Task-specific agent prompts
 
-Cold start from GitHub or a marketplace host is the install skill:
+First install the small bootstrap skill:
 
 ```sh
 npx skills add aotter/mantle
 ```
 
-Copy one block into a coding agent after that skill is present. Paths below
-are relative to the Mantle docs root: `node_modules/@aotter/mantle/docs/`
-after `@aotter/mantle` is installed. A standalone `skills add` installation
-contains only the selected skill, not these docs.
-`npx --no-install mantle --help` is the layered CLI overview; it mirrors the
-authoring docs. A live `/mcp` catalog mirrors the Manifest → RuntimePlan, not
-the CLI. Resolve only missing requirements first; do not assume a host. There is no `mantle create`. Empty `generate` fails until
-manifests exist. Admin is opt-in.
+The installed skill locates the target project, resolves its actual SDK
+version, and sends the agent to that package's CLI and docs. A GitHub skill
+may be newer than npm: published 0.1.4 uses the direct-authoring path;
+0.1.5-alpha.1 adds full generated projects. Never assume a new flag exists without
+checking the installed CLI.
 
-### Interview then build
+## New full Cloudflare app
 
 ```text
-Interview me about the service: host, who uses it, whether humans need a
-Dev UI, and whether we only embed Spec/Runtime. If the install skill is
-missing, run npx skills add aotter/mantle. Read the
-installer-reported skill, choose and install an exact SDK version, then read
-its embedded skills/install/SKILL.md,
-run npx --no-install mantle --help, and
-read handbook/start/overview.md.
-Use examples/README.md as the examples index; copy builtin-* Manifests only
-(not cf-primitives-*). Implement locally first. Take only the surfaces we
-chose. For Spec-only use, skip Runtime and code generation. For a Worker
-without Admin, follow examples/host-minimal-worker/. For a Worker with
-Dev UI, follow examples/host-local-admin-otp/README.md. ChatGPT Sites only
-if I name that host. No mantle create. Pin all @aotter/mantle* packages
-to one exact version.
+Build a Mantle app on Cloudflare. Follow the installed mantle skill, pin one
+exact stable SDK version, and use its project-generation path if supported.
+Select the full default Spec, Runtime, API, MCP, Admin and blank home. Install
+the CLI-declared dependencies and rerun generation. Ask for my actual data and
+workflow before adding Manifests. For local Admin, copy .dev.vars.example,
+set the real owner email and a random secret, and verify OTP, Admin assets,
+unauthorized access, public API and MCP. Do not claim production Auth is set
+up from a local OTP test.
 ```
 
-### Embed Runtime with typed APIs
+## Small API or Spec-only app
 
 ```text
-Read handbook/start/project-and-cli.md and npx --no-install mantle --help.
-Pin @aotter/mantle at the exact version we agree, author manifests for
-this existing host, then run mantle generate. Embed
-the typed binding from .mantle/generated/mantle.ts into the current
-system. Do not add Admin, mantle-admin-ui, a visitor frontend, or a
-Cloudflare adapter unless I ask. Do not invent a default Schema.
+Use the installed Mantle CLI and version-matched docs. For a Cloudflare API,
+select --host cf --features spec,api if that CLI supports project generation.
+For manifest parsing only, use --features spec without a host. Keep unselected
+Admin, Web and MCP packages out. Author the Schema and View I request, then
+run generate, validate, typecheck and a real route probe when a host exists.
+Preserve an existing direct-authored application instead of regenerating it.
 ```
 
-### Minimal API service locally
+## ChatGPT Sites
 
 ```text
-Read handbook/start/quickstart-worker.md and examples/host-minimal-worker/.
-Author a Cloudflare Worker from that official example or from scratch:
-one Schema, one public View (copy the contract, not the tree wholesale).
-Pin every @aotter/mantle* package to the same exact version. Run
-pnpm install && pnpm generate && pnpm dev (or wrangler dev --local).
-Probe GET /api/views/<name> with curl. GET / may 404. Do not install
-Admin or wrangler ASSETS unless I ask.
+Build with ChatGPT Sites and Mantle. Start from the installed SDK's generated
+blank app when supported; otherwise follow that version's Sites reference.
+Pin all selected Mantle packages exactly, install declared dependencies,
+review and apply the initial local D1 migration, then add my Manifests and
+review each appended migration. Configure OWNER_EMAIL and PUBLIC_ORIGIN. The
+local owner smoke simulates Sites identity; deployed ChatGPT sign-in needs a
+separate check. Show how I will maintain content through Admin, browser
+WebMCP, public MCP and Sites-session staff MCP. Add R2 only if my workflow
+requires uploads. Never deploy the Worker directly or claim remote staff OAuth
+MCP from a Sites browser session.
 ```
 
-### Full local Dev UI (opt-in)
+## Existing project with typed queries
 
 ```text
-I want the optional Admin / Dev UI. Read examples/host-local-admin-otp/README.md
-(the procedural SSOT) and the thin pointer at handbook/start/quickstart-admin.md.
-Interview me for a bootstrap owner email, then follow that example locally.
-Prefer 127.0.0.1 over localhost. After pnpm check / smoke, restore .dev.vars
-from .dev.vars.example before pnpm dev.
+Read this project's package.json, lockfile, installed Mantle package and
+projected develop skill. Keep its host and selected surfaces. Use the installed
+CLI's help and handbook to add the requested Schema/View/Procedure, then run
+its generate/check, validation, TypeScript and host smoke. Do not use another
+checkout's SDK docs or overwrite user-owned files.
 ```
 
-### Later layer: MCP or public web (opt-in)
-
-```text
-Do not add Admin unless it is already in this project. Read
-handbook/concepts/mcp-and-agents.md and/or
-handbook/cloudflare/public-web.md. Add only the surface I name: MCP
-Triggers at /mcp or /mcp/staff, or optional @aotter/mantle-web
-composition. Keep Core adapter-neutral. Probe the new route; do not
-claim Auth or Admin works from a public 200.
-```
-
-### Mantle on ChatGPT Sites, including media
-
-Use only when the user names ChatGPT Sites as the host.
-
-```text
-Build with ChatGPT Sites; use Mantle for content management and publishing.
-Read handbook/chatgpt-sites/index.md and examples/host-chatgpt-sites/README.md.
-Use that runnable host as a reference and install its pinned
-dependencies from the registry. Derive Schema, View,
-Procedure and Trigger from my requirements and check the Admin editor/picker and public
-projections against them. Request both Sites D1 and R2 when my workflow
-includes uploads. Bind the R2 media port, declare media.purposes, and keep
-the same-origin PUT and committed-only public GET checks. Pin every
-@aotter/mantle* dependency to one exact version. Run the local smoke,
-show a draft-to-publish walkthrough, then save and deploy through Sites when
-requested. Verify the deployed owner/member role, R2 upload, published page, and anonymous draft 404. Treat public read-only
-MCP, Admin WebMCP, and staff OAuth MCP as separate acceptance gates; never
-claim staff MCP from a working browser session or connector URL alone.
-```
-
-
-[Back to the Core README](../README.md#for-engineers-and-agents).
+[Back to the Core README](../README.md).

package/docs/examples/host-chatgpt-sites/README.md

@@ -49,7 +49,7 @@ Keep `.openai/hosting.json`; do not copy an existing Site's `project_id`. To use
 
 Review the entire [smoke script](./scripts/check.mjs) before adapting it. It covers D1 CRUD/version conflict, owner/member/role revocation, R2 read/write/delete, media create → PUT → commit → public read, both advertised MCP URLs, public MCP `initialize`/`tools/list`/View call, staff MCP authentication/catalog, draft isolation, published article HTML/Markdown/SEO, and negative auth/Origin/size checks. It creates and deletes only its own test records and objects.
 
-The checked-in `drizzle/` migrations and `src/storage-fingerprint.json` match the example manifest and runtime. Apply all pending D1 migrations before deploying updated code; managed storage does not apply runtime infrastructure migrations at boot, and a missing column can make every route return 500. `scripts/migration.mjs` shows the one-time generation mechanism; do **not** run it against a deployed database or overwrite an applied migration. For a new business manifest, generate/review an initial migration before the first deployment; for a later change, generate an additive migration from the previous schema state.
+The checked-in `drizzle/` migrations and `src/storage-fingerprint.json` match the example manifest and runtime. Apply all pending D1 migrations before deploying updated code; managed storage refuses to boot against an older database. After changing a Schema, first apply the current migrations to local D1, then run `npm run generate` and `npm run migrate:generate`. Review the newly appended SQL and apply it with `wrangler d1 migrations apply mantle-sites-reference-local --local`. Commit the new migration, `drizzle/meta/mantle-state.json`, journal, and fingerprint together. The generator checks the local database fingerprint before appending; it never changes an applied SQL file or applies D1 migrations itself. Deploy the reviewed migration before deploying code that expects its fingerprint.
 
 ## Publish with Sites
 

package/docs/examples/host-chatgpt-sites/drizzle/0004_mantle.sql

@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS _mantle_managed_runtime_state (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  canonical_version TEXT NOT NULL
+);
+--> statement-breakpoint
+INSERT INTO _mantle_schema_tables(name,projection) VALUES ('articles','{"columns":[["body","TEXT","string",false],["coverAssetId","TEXT","string",false],["summary","TEXT","string",false],["title","TEXT","string",false]],"indexes":[]}') ON CONFLICT(name) DO UPDATE SET projection=excluded.projection;
+--> statement-breakpoint
+INSERT INTO _mantle_managed_runtime_state(id,canonical_version) VALUES (1,'0006-managed-runtime-version') ON CONFLICT(id) DO UPDATE SET canonical_version=excluded.canonical_version;
+--> statement-breakpoint
+INSERT INTO _mantle_storage_state(id,fingerprint) VALUES (1,(SELECT CASE WHEN fingerprint='9ef85f9933e22328140e924045820af6be2a6985ed8ecc19b63a4f2a37826618' THEN '9ef85f9933e22328140e924045820af6be2a6985ed8ecc19b63a4f2a37826618' ELSE NULL END FROM _mantle_storage_state WHERE id=1)) ON CONFLICT(id) DO UPDATE SET fingerprint=excluded.fingerprint;

package/docs/examples/host-chatgpt-sites/drizzle/0005_mantle.sql

@@ -0,0 +1,24 @@
+CREATE TABLE IF NOT EXISTS _mantle_schedule_runs (
+      run_id TEXT NOT NULL,
+      attempt INTEGER NOT NULL,
+      schedule_id TEXT NOT NULL,
+      scheduled_at INTEGER NOT NULL,
+      started_at INTEGER NOT NULL,
+      finished_at INTEGER,
+      status TEXT NOT NULL,
+      error_summary TEXT,
+      counts TEXT,
+      PRIMARY KEY (run_id, attempt)
+    );
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS _mantle_schedule_runs_recent
+      ON _mantle_schedule_runs (started_at DESC);
+--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS _mantle_schedule_runs_schedule_recent
+      ON _mantle_schedule_runs (schedule_id, started_at DESC);
+--> statement-breakpoint
+INSERT INTO _mantle_schema_tables(name,projection) VALUES ('articles','{"columns":[["body","TEXT","string",false],["coverAssetId","TEXT","string",false],["summary","TEXT","string",false],["title","TEXT","string",false]],"indexes":[]}') ON CONFLICT(name) DO UPDATE SET projection=excluded.projection;
+--> statement-breakpoint
+INSERT INTO _mantle_managed_runtime_state(id,canonical_version) VALUES (1,(SELECT CASE WHEN canonical_version='0006-managed-runtime-version' THEN '0007-schedule-run-observations' ELSE NULL END FROM _mantle_managed_runtime_state WHERE id=1)) ON CONFLICT(id) DO UPDATE SET canonical_version=excluded.canonical_version;
+--> statement-breakpoint
+INSERT INTO _mantle_storage_state(id,fingerprint) VALUES (1,(SELECT CASE WHEN fingerprint='9ef85f9933e22328140e924045820af6be2a6985ed8ecc19b63a4f2a37826618' THEN '9ef85f9933e22328140e924045820af6be2a6985ed8ecc19b63a4f2a37826618' ELSE NULL END FROM _mantle_storage_state WHERE id=1)) ON CONFLICT(id) DO UPDATE SET fingerprint=excluded.fingerprint;

package/docs/examples/host-chatgpt-sites/drizzle/meta/_journal.json

@@ -1 +1 @@
-{"version":"7","dialect":"sqlite","entries":[{"idx":0,"version":"6","when":1790000000000,"tag":"0000_sites_users","breakpoints":true},{"idx":1,"version":"6","when":1790000000001,"tag":"0001_mantle","breakpoints":true},{"idx":2,"version":"6","when":1790000000002,"tag":"0002_article_cover","breakpoints":true},{"idx":3,"version":"6","when":1790000000003,"tag":"0003_store_instance_id","breakpoints":true}]}
+{"version":"7","dialect":"sqlite","entries":[{"idx":0,"version":"6","when":1790000000000,"tag":"0000_sites_users","breakpoints":true},{"idx":1,"version":"6","when":1790000000001,"tag":"0001_mantle","breakpoints":true},{"idx":2,"version":"6","when":1790000000002,"tag":"0002_article_cover","breakpoints":true},{"idx":3,"version":"6","when":1790000000003,"tag":"0003_store_instance_id","breakpoints":true},{"idx":4,"version":"6","when":1790000000004,"tag":"0004_mantle","breakpoints":true},{"idx":5,"version":"6","when":1790300000000,"tag":"0005_mantle","breakpoints":true}]}

package/docs/examples/host-chatgpt-sites/drizzle/meta/mantle-state.json

@@ -0,0 +1,60 @@
+{
+  "fingerprint": "9ef85f9933e22328140e924045820af6be2a6985ed8ecc19b63a4f2a37826618",
+  "schemas": [
+    {
+      "apiVersion": "cms.mantle.aotter.net/v1",
+      "kind": "Schema",
+      "metadata": {
+        "name": "articles"
+      },
+      "spec": {
+        "title": "文章",
+        "schema": {
+          "type": "object",
+          "required": [
+            "title"
+          ],
+          "properties": {
+            "title": {
+              "type": "string",
+              "title": "標題",
+              "maxLength": 160
+            },
+            "summary": {
+              "type": "string",
+              "title": "摘要",
+              "maxLength": 1000
+            },
+            "body": {
+              "type": "string",
+              "title": "內容",
+              "x-mcp-hint": "markdown"
+            },
+            "coverAssetId": {
+              "type": "string",
+              "title": "封面圖片",
+              "x-mantle-ref": "media_assets",
+              "x-mcp-hint": "media-image"
+            }
+          }
+        },
+        "lifecycle": "publishing",
+        "uniqueIndexes": [],
+        "indexes": [],
+        "searchableFields": [],
+        "localized": false
+      }
+    }
+  ],
+  "appliedMigrationIds": [
+    "0001-init",
+    "0002-media-assets",
+    "0003-pending-media-uploads",
+    "0004-native-schema-storage",
+    "0005-store-instance-id",
+    "0006-managed-runtime-version",
+    "0007-schedule-run-observations"
+  ],
+  "lastIndex": 5,
+  "canonicalVersion": "0007-schedule-run-observations"
+}

package/docs/examples/host-chatgpt-sites/package.json

@@ -1 +1 @@
-{"name":"mantle-sites-reference","version":"0.0.1","private":true,"type":"module","scripts":{"build":"node scripts/build.mjs","dev":"wrangler dev","generate":"mantle generate","check":"tsc --noEmit","test":"node --experimental-strip-types scripts/check.mjs"},"dependencies":{"@aotter/mantle":"latest","@aotter/mantle-admin":"latest","@aotter/mantle-admin-ui":"latest","@aotter/mantle-cloudflare":"latest","@aotter/mantle-web":"latest","hono":"^4.9.0","micromark":"4.0.2","zod":"^4.0.0"},"devDependencies":{"@cloudflare/workers-types":"*","esbuild":"^0.28.0","typescript":"^5.9.0","wrangler":"^4.0.0"}}
+{"name":"mantle-sites-reference","version":"0.0.1","private":true,"type":"module","scripts":{"build":"node scripts/build.mjs","dev":"wrangler dev","generate":"mantle generate","check":"tsc --noEmit","test":"node --experimental-strip-types scripts/check.mjs","migrate:generate":"node scripts/migration.mjs","migrate:check":"node scripts/migration.mjs --check"},"dependencies":{"@aotter/mantle":"latest","@aotter/mantle-admin":"latest","@aotter/mantle-admin-ui":"latest","@aotter/mantle-cloudflare":"latest","@aotter/mantle-web":"latest","hono":"^4.9.0","micromark":"4.0.2","zod":"^4.0.0"},"devDependencies":{"@cloudflare/workers-types":"*","esbuild":"^0.28.0","typescript":"^5.9.0","wrangler":"^4.0.0"}}

package/docs/examples/host-chatgpt-sites/scripts/migration.mjs

@@ -1,9 +1,43 @@
-// One-time, reviewable initial migration from Mantle's public migration planner.
-import { buildSqliteMigrationArtifact, splitSqlStatements } from '@aotter/mantle/runtime';
-import { plan } from '../.mantle/generated/mantle.ts';
-import { writeFile } from 'node:fs/promises';
-const artifact=await buildSqliteMigrationArtifact([],Object.values(plan.schemas).map(s=>s.manifest));
-const quote=value=>`'${value.replaceAll("'","''")}'`;
-const sql=[...artifact.migrations.flatMap(m=>splitSqlStatements(m.sql).map(s=>s+';')),...artifact.projections.map(p=>`INSERT INTO _mantle_schema_tables(name,projection) VALUES (${quote(p.name)},${quote(p.projection)});`),`INSERT INTO _mantle_storage_state(id,fingerprint) VALUES (1,${quote(artifact.targetFingerprint)});`].join('\n--> statement-breakpoint\n');
-await writeFile('drizzle/0001_mantle.sql',sql);
+// Append a reviewed D1 migration only after the previous one is applied locally.
+import { buildSqliteMigrationArtifact, renderSqliteManagedMigration } from '@aotter/mantle/runtime';
+import { parseManifestSources, ValidateManifestsUseCase } from '@aotter/mantle/spec';
+import { execFileSync } from 'node:child_process';
+import { readFile, readdir, writeFile } from 'node:fs/promises';
+const statePath='drizzle/meta/mantle-state.json';
+const state=JSON.parse(await readFile(statePath,'utf8'));
+const files=(await readdir('manifests')).filter(name=>/\.ya?ml$/i.test(name)).sort();
+const parsed=parseManifestSources({sources:await Promise.all(files.map(async name=>({sourceId:name,text:await readFile(`manifests/${name}`,'utf8')})))});
+if(!parsed.ok)throw Error(`Invalid manifest: ${parsed.diagnostics.map(d=>d.message).join('; ')}`);
+const validated=ValidateManifestsUseCase.run({parsed:parsed.value});
+if(validated.errorCount)throw Error(`Invalid manifest: ${validated.diagnostics.filter(d=>d.severity==='error').map(d=>d.message).join('; ')}`);
+const target=parsed.value.entries.map(entry=>entry.manifest).filter(manifest=>manifest.kind==='Schema');
+const artifact=await buildSqliteMigrationArtifact(state.schemas,target,{appliedMigrationIds:state.appliedMigrationIds});
+if(artifact.sourceFingerprint!==state.fingerprint)throw Error('The saved migration source fingerprint is invalid. Restore the applied state before generating.');
+if(artifact.destructive)throw Error('Destructive Schema change needs a reviewed migration; no D1 file was written.');
+const unchanged=artifact.sourceFingerprint===artifact.targetFingerprint&&artifact.migrations.length===0;
+const fingerprint=JSON.parse(await readFile('src/storage-fingerprint.json','utf8'));
+if(fingerprint!==state.fingerprint)throw Error('Generated fingerprint and migration source disagree. Restore the reviewed migration state.');
+if(process.argv.includes('--check')){
+  if(!unchanged)throw Error('Pending Schema or runtime migration. Run node scripts/migration.mjs and review the new D1 file.');
+  process.exit(0);
+}
+const output=execFileSync('node',['node_modules/wrangler/bin/wrangler.js','d1','execute','mantle-sites-reference-local','--local','--command','SELECT fingerprint FROM _mantle_storage_state WHERE id = 1','--json'],{encoding:'utf8'});
+const active=JSON.parse(output)[0]?.results?.[0]?.fingerprint;
+if(active!==state.fingerprint)throw Error(`Local D1 fingerprint ${active??'(missing)'} does not match the last migration ${state.fingerprint}. Apply pending D1 migrations first.`);
+const versionOutput=execFileSync('node',['node_modules/wrangler/bin/wrangler.js','d1','execute','mantle-sites-reference-local','--local','--command',"SELECT name FROM sqlite_schema WHERE type='table' AND name='_mantle_managed_runtime_state'",'--json'],{encoding:'utf8'});
+const versionTable=JSON.parse(versionOutput)[0]?.results?.[0]?.name;
+const version=versionTable?(JSON.parse(execFileSync('node',['node_modules/wrangler/bin/wrangler.js','d1','execute','mantle-sites-reference-local','--local','--command','SELECT canonical_version FROM _mantle_managed_runtime_state WHERE id = 1','--json'],{encoding:'utf8'}))[0]?.results?.[0]?.canonical_version??null):null;
+if(version!==null&&version!==state.canonicalVersion)throw Error(`Local D1 runtime version ${version} does not match migration source ${state.canonicalVersion}.`);
+if(version===null&&state.canonicalVersion!=='0005-store-instance-id')throw Error('Local D1 is missing the managed runtime version marker. Apply pending migrations first.');
+if(unchanged){console.log('D1 migrations are current.');process.exit(0);}
+const sql=renderSqliteManagedMigration(artifact,{canonicalVersion:state.canonicalVersion});
+const index=state.lastIndex+1;
+const path=`drizzle/${String(index).padStart(4,'0')}_mantle.sql`;
+const journalPath='drizzle/meta/_journal.json';
+const journal=JSON.parse(await readFile(journalPath,'utf8'));
+if(journal.entries.at(-1)?.idx!==state.lastIndex)throw Error('Drizzle journal does not match the saved migration state.');
+await writeFile(path,sql,{flag:'wx'});
+await writeFile(journalPath,JSON.stringify({...journal,entries:[...journal.entries,{idx:index,version:'6',when:Date.now(),tag:`${String(index).padStart(4,'0')}_mantle`,breakpoints:true}]})+'\n');
+await writeFile(statePath,JSON.stringify({fingerprint:artifact.targetFingerprint,canonicalVersion:artifact.targetCanonicalVersion,schemas:target,appliedMigrationIds:[...new Set([...state.appliedMigrationIds,...artifact.migrations.map(m=>m.id)])],lastIndex:index},null,2)+'\n');
 await writeFile('src/storage-fingerprint.json',JSON.stringify(artifact.targetFingerprint)+'\n');
+console.log(`Review ${path}, then apply it with wrangler d1 migrations apply mantle-sites-reference-local --local.`);

package/docs/examples/host-chatgpt-sites/src/chatgpt-auth.ts

@@ -24,13 +24,16 @@ export function createChatGPTAuth(env: Env): AdminAuth {
     basePath:'/api/auth', methods:[],
     async getSession(request) {
       const who=readIdentity(request); if(!who)return null;
-      // Only the configured owner can bootstrap privilege; a later role revocation persists.
-      await db.prepare('INSERT OR IGNORE INTO sites_users (id,email,name,role,signed_in) VALUES (?,?,?,?,1)')
-        .bind(who.id,who.email,who.name,who.email===env.OWNER_EMAIL?.trim().toLowerCase()?'owner':null).run();
-      await db.prepare('UPDATE sites_users SET id=?,name=?,signed_in=1 WHERE email=? AND signed_in=0').bind(who.id,who.name,who.email).run();
-      const row=await db.prepare('SELECT * FROM sites_users WHERE id=?').bind(who.id).first<UserRow>();
+      let row=await db.prepare('SELECT * FROM sites_users WHERE id=?').bind(who.id).first<UserRow>();
+      if(!row){
+        // Claim an invitation before inserting; a stable identity keeps its existing role if its email later changes.
+        await db.prepare('UPDATE sites_users SET id=?,name=?,signed_in=1 WHERE email=? AND signed_in=0').bind(who.id,who.name,who.email).run();
+        await db.prepare('INSERT OR IGNORE INTO sites_users (id,email,name,role,signed_in) VALUES (?,?,?,?,1)')
+          .bind(who.id,who.email,who.name,who.email===env.OWNER_EMAIL?.trim().toLowerCase()?'owner':null).run();
+        row=await db.prepare('SELECT * FROM sites_users WHERE id=?').bind(who.id).first<UserRow>();
+      }
       if(!row)return null;
-      return {session:{id:`sites:${who.id}`},user:{...who,role:row.role,roleCurrent:true}};
+      return {session:{id:`sites:${who.id}`},user:{id:row.id,email:row.email,name:row.name,role:row.role,roleCurrent:true}};
     },
     getUserRole:roleFor,
     async handler(request) {

package/docs/examples/host-local-admin-otp/package.json

@@ -21,9 +21,9 @@
     "aws4fetch": "^1.0.20"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^5.20260907.1",
+    "@cloudflare/workers-types": "5.20260904.1",
     "typescript": "^6.0.3",
-    "wrangler": "^4.125.0"
+    "wrangler": "4.129.0"
   },
   "packageManager": "pnpm@9.15.0"
 }

package/docs/examples/host-minimal-worker/package.json

@@ -18,9 +18,9 @@
     "aws4fetch": "^1.0.20"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^5.20260907.1",
+    "@cloudflare/workers-types": "5.20260904.1",
     "typescript": "^6.0.3",
-    "wrangler": "^4.125.0"
+    "wrangler": "4.129.0"
   },
   "packageManager": "pnpm@9.15.0"
 }