@aotter/mantle 0.1.0-alpha.15 → 0.1.0-alpha.17

package/README.md

@@ -60,7 +60,9 @@ pnpm exec mantle-harness http --base-url http://127.0.0.1:8787 --route page=/en/
 ```
 
 `mantle generate` validates and compiles `./manifests/`, then writes one typed
-`.mantle/generated/mantle.ts` module. It performs no Admin asset installation,
+`.mantle/generated/mantle.ts` module. When `@aotter/mantle-admin-ui` is
+installed, it also syncs the Admin SPA to `public/_mantle/admin/` (excluding
+`server.*` package exports). Core-only installs skip that copy. It performs no
 skill sync, package update, styling, provisioning, or deployment.
 The same pure emitter is available from `@aotter/mantle/codegen` when a host
 wants to own parsing and filesystem IO.
@@ -279,3 +281,8 @@ adapter is a port-implementation exercise, not a runtime refactor.
 ## License
 
 Apache-2.0
+
+Pure extension routes do not await content preparation. Before an extension
+uses Mantle data or database-backed Auth, await its supplied `getRuntime()`
+(or `ref.get()`). Standard protected routes establish this readiness themselves;
+queue/scheduled handlers continue to use `worker.getRuntime(env)`.

package/dist/cli/generate.d.ts

@@ -1,2 +1,11 @@
-export declare function runGenerate(rawArgs: readonly string[]): Promise<number>;
+/** Test seam for Core-only vs Admin-present installs. */
+export interface GenerateDeps {
+    readonly resolveAdminUiIndexHtml?: () => string | null;
+}
+/**
+ * Locate the optional Admin SPA. A Core-only install does not have
+ * `@aotter/mantle-admin-ui`, so resolution failure is not an error.
+ */
+export declare function resolveAdminUiIndexHtml(): string | null;
+export declare function runGenerate(rawArgs: readonly string[], deps?: GenerateDeps): Promise<number>;
 //# sourceMappingURL=generate.d.ts.map

package/dist/cli/generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/cli/generate.ts"],"names":[],"mappings":"AAeA,wBAAsB,WAAW,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAyC7E"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../src/cli/generate.ts"],"names":[],"mappings":"AAiBA,yDAAyD;AACzD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;CACxD;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,IAAI,MAAM,GAAG,IAAI,CAOvD;AAED,wBAAsB,WAAW,CAC/B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC,MAAM,CAAC,CA+CjB"}

package/dist/cli/generate.js

@@ -1,11 +1,26 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { cwd, stderr, stdout } from "node:process";
+import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { ValidateManifestsUseCase } from "@aotter/mantle-spec";
 import { loadManifestsFromRoot } from "@aotter/mantle-spec/cli";
 import { assertMantleNamespace, emitMantleModule } from "../codegen/emitMantleModule.js";
-export async function runGenerate(rawArgs) {
+/**
+ * Locate the optional Admin SPA. A Core-only install does not have
+ * `@aotter/mantle-admin-ui`, so resolution failure is not an error.
+ */
+export function resolveAdminUiIndexHtml() {
+    try {
+        const path = fileURLToPath(import.meta.resolve("@aotter/mantle-admin-ui/index.html"));
+        return existsSync(path) ? path : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function runGenerate(rawArgs, deps = {}) {
     let options;
     try {
         const parsed = parseGenerateArgs(rawArgs);
@@ -38,7 +53,13 @@ export async function runGenerate(rawArgs) {
         return 1;
     }
     const output = resolve(cwd(), options.output);
-    const stale = !(await syncText(join(output, "mantle.ts"), emitted.source, options.check));
+    let stale = !(await syncText(join(output, "mantle.ts"), emitted.source, options.check));
+    const adminIndex = (deps.resolveAdminUiIndexHtml ?? resolveAdminUiIndexHtml)();
+    if (adminIndex !== null) {
+        const adminSource = dirname(adminIndex);
+        const adminTarget = resolve(cwd(), "public/_mantle/admin");
+        stale = !(await syncAdminAssets(adminSource, adminTarget, options.check)) || stale;
+    }
     if (stale && options.check) {
         stderr.write("Mantle generated files are stale; run `mantle generate`.\n");
         return 1;
@@ -76,7 +97,7 @@ Options:
   --manifests <dir>   Manifest directory (default: ./manifests)
   -o, --output <dir>  Generated root (default: .mantle/generated)
   --namespace <name>  Generated type namespace (default: Mantle)
-  --check             Fail without writing when generated code is stale
+  --check             Fail without writing when generated code or Admin assets are stale
   -h, --help          This help
 `);
 }
@@ -95,6 +116,30 @@ async function syncText(path, expected, check) {
     await writeFile(path, expected, "utf8");
     return true;
 }
+async function syncAdminAssets(source, target, check) {
+    const sourceFiles = (await listFiles(source)).filter((path) => !path.startsWith("server."));
+    const targetFiles = await listFiles(target).catch(() => []);
+    const current = sourceFiles.length === targetFiles.length
+        && sourceFiles.every((path, index) => path === targetFiles[index])
+        && (await Promise.all(sourceFiles.map(async (path) => (await readFile(join(source, path))).equals(await readFile(join(target, path)))))).every(Boolean);
+    if (current || check)
+        return current;
+    await rm(target, { recursive: true, force: true });
+    for (const path of sourceFiles) {
+        const destination = join(target, path);
+        await mkdir(dirname(destination), { recursive: true });
+        await writeFile(destination, await readFile(join(source, path)));
+    }
+    return true;
+}
+async function listFiles(root, prefix = "") {
+    const entries = await readdir(join(root, prefix), { withFileTypes: true });
+    const files = await Promise.all(entries.map((entry) => {
+        const path = join(prefix, entry.name);
+        return entry.isDirectory() ? listFiles(root, path) : [path];
+    }));
+    return files.flat().sort();
+}
 function message(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/dist/cli/generate.js.map

@@ -1 +1 @@
-{"version":3,"file":"generate.js","sourceRoot":"","sources":["../../src/cli/generate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"generate.js","sourceRoot":"","sources":["../../src/cli/generate.ts"],"names":[],"mappings":"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"}

package/docs/adapter-guide.md

@@ -204,6 +204,10 @@ storage preparation and binding do not accept or require a static asset port.
 
 ## Implementation checklist
 
+- [ ] Run `runStorageConformance` from `@aotter/mantle-runtime/testing/storage`
+      against a disposable prepared-storage factory. See the
+      [Runtime conformance guide](../packages/mantle-runtime/README.md#storage-adapter-conformance)
+      for coverage, cleanup, locale setup, and remaining adapter-specific tests.
 - [ ] Implement `MantleStorageAdapter` returning existing semantic ports, or reuse `SqliteMantleStorageAdapter` with an already-owned handle.
 - [ ] Call `bootMantleRuntime()` once per semantic revision, or explicitly prepare before binding.
 - [ ] Mount HTTP Trigger and View REST surfaces.

package/docs/adr/0014-auth-better-auth-and-multi-tenant-mcp.md

@@ -625,3 +625,81 @@ OAuth store and is not renamed by this decision.
 This amendment adopts the 2026-07-28 CIMD authorization profile only. Updating
 Mantle's JSON-RPC dispatcher to the complete MCP 2026-07-28 transport revision
 is a separate decision.
+
+## 2026-09-07 amendment — shared OAuth surfaces and revocation
+
+OAuth product UI is not owned by a runtime adapter. `@aotter/mantle-admin`
+owns `MantleOAuthAuth`, the consent/connected-app view models, and
+`handleMantleOAuth(Request) -> Response | null`; `mountMantleOAuth` is a thin
+Hono bridge. The Cloudflare adapter implements protocol actions using the
+same Better Auth instance and D1. Future adapters reuse this contract, not
+Cloudflare-specific UI glue. The old `mountAuthorize` export remains an alias.
+
+`@aotter/mantle-admin-ui` owns the React/shadcn sign-in, consent and connected
+apps surfaces, including i18n, theme and submit state. Auth pages initially
+follow the system theme; the light/dark toggle persists an explicit override.
+Connected apps has an Admin page, but managing one's own grants requires only
+a session, never a staff role. The no-assets HTML fallback uses native forms
+without JavaScript or a second implementation of the Admin design system.
+Both mounts retain same-origin mutation checks and private/no-store responses.
+The consent document's CSP permits only the provider-validated callback
+origin for the browser's form redirect; it never trusts an unsigned query.
+
+MCP authorization remains session-bound: the JWT's original Better Auth
+session must still exist and be unexpired. Admin sign-out/session expiration
+therefore also ends that session's MCP access. A refresh token is not an
+independent authorization to bypass this check. Staff roles are still read
+fresh on every protected request.
+
+Disconnect is scoped to the authenticated user and the selected client. It
+revokes refresh/opaque access tokens, removes pending authorization codes and
+consent rows, and prevents existing JWTs from becoming valid when the client
+is connected again. The verification-create hook captures the consent row ID
+in Better Auth's existing authorization `referenceId`; Better Auth carries it
+through the authorization code and every refresh rotation. MCP JWTs copy that
+reference into `mantle_consent_id`, which must match the active consent row.
+Never look up a new consent at token mint time: doing so could revive a refresh
+lineage whose insertion raced the revoke batch. Same-second reconnect and a
+delayed old refresh row are required regression cases, not clock delays.
+
+MCP mode reserves authorization `referenceId` for this grant identity; future
+curated configuration must not also expose Better Auth's `postLogin` reference
+hooks. MCP access requires a persisted user consent, so `skipConsent` and
+`cachedTrustedClients` must not bypass consent for MCP clients.
+
+This alpha hotfix requires existing MCP clients to reconnect once: pre-hotfix
+JWTs without the grant claim are rejected immediately. No account/session reset
+is required. The unshipped watermark migration 0008 is removed; its unused
+table in the phsu development database is harmless and is not queried or
+deleted during deployment.
+
+## 2026-09-08 amendment — request security boundaries
+
+All Admin session mutations use the existing same-origin guard, including
+same-site sibling origins. Admin HTML forbids framing and is private/no-store.
+The SPA also refuses to render in frames, covering direct static-asset URLs
+that bypass the server mount.
+The Admin/auth mounts cap request bodies at 1 MiB using Hono's body limiter;
+HTTP trigger and MCP dispatchers count streamed JSON bytes before parsing and
+return 413 above the same limit. Media bytes continue through direct uploads.
+This intentionally rejects previously accepted larger control-plane payloads.
+
+Cloudflare `createAuth` explicitly enables Better Auth rate limits regardless
+of `NODE_ENV`, including the OAuth provider's anonymous registration limit of
+five requests per minute. Only `CF-Connecting-IP` supplies the client key.
+The upstream memory store limits each isolate; deployments needing a shared
+abuse quota must additionally enforce it at ingress. No D1 migration or new
+runtime platform dependency is introduced.
+
+Workers must retain initialization work through `ExecutionContext.waitUntil`
+even when the initial challenge finishes or its client disconnects. Schema
+boot precedes OAuth handling. The adapter's static AsyncLocalStorage seeding
+is a version-pinned Better Auth 1.7.2 integration, with accessor-identity
+regression coverage; it does not replace Better Auth's request context.
+Failed Auth initialization evicts only the failed Worker assembly so a later
+request can retry. Non-HTTP callers await Auth initialization with runtime boot;
+HTTP requests anchor it without making public responses depend on Auth health.
+
+The conventional `/favicon.ico` reflects the configured site icon, but is a
+fallback after consumer routes, not a newly reserved namespace. Existing
+consumer icon routes must continue to work after a package update.

package/docs/adr-lite-803-request-diagnostics.md

@@ -0,0 +1,38 @@
+# ADR-lite: request-scoped Cloudflare diagnostics
+
+Status: implemented diagnostic record for #803; real-auth controls and measured
+comparison acceptance belong to the #812 harness. This does not close the
+separate starter provisioning/Smart Placement portion of #803.
+
+Use native AsyncLocalStorage and a small versioned testing entry point instead of
+a global current-request counter or a configurable production telemetry system.
+Production mounts only check for an existing test context. With none, there are
+no diagnostic clock reads, binding wrappers, records, observers or response headers.
+Runtime, auth, role, catalog, dispatcher-build and dispatch retain their ownership
+and authorization order. The ordinary runtime-ready promise keeps its identity.
+
+Native D1 instrumentation sits beneath both Auth and Runtime and is idempotent.
+It preserves receivers, bind chains, first-column behavior and native objects in
+batches; no second driver observer is added for counting. Provider failures and
+unknown metadata remain visible. Request context is captured when an operation
+starts, so shared work belongs to its initiator. Catalog waiters inherit source
+classification and wait time without inheriting the owner's binding counts.
+
+The record freezes at response creation. Inclusive spans can overlap, and partial
+metadata or deferred work must not be presented as a full total. A test-only cloned
+MCP response supplies the JSON-RPC outcome without exposing its content; that
+inspection is outside totalMs but remains instrumentation overhead for HTTP timing.
+Observer errors never replace application results. D1/KV/R2 operations emit only
+counts, sizes with their source/coverage, and durations; object keys, SQL, caller
+identities and credentials never enter the record.
+
+R2 GET bodies stay native. Successful direct stream-to-PUT completion confirms
+payload bytes; canceled, incomplete and unconsumed reads remain unknown. This
+avoids losing R2's known-length stream property or hiding buffering overhead.
+
+Checks deliberately overlap MCP requests and share KV hit/failure loads, then
+retry after failure. Native I/O is counted once per owner, and denied requests
+leave unreached phases null. Additional checks preserve native D1 private receiver
+and batch semantics, sync/async observer failure, immutable deferred snapshots,
+R2 stream identity and partial-transfer uncertainty. The collector fixture labels
+its deterministic auth explicitly; it is not evidence of native-auth parity.

package/docs/adr-lite-808-route-readiness.md

@@ -0,0 +1,47 @@
+# Route-owned Cloudflare readiness (#808)
+
+Status: accepted for the unreleased #806–812 implementation. Follows ADR-0019
+(preparation owns migrations) and amends ADR-0014's unconditional HTTP boot rule.
+
+The facade assembles immutable route projections once, then prepares only for
+routes that consume canonical storage. It retains one retryable preparation
+promise, the sealed plan and Better Auth's existing global AsyncLocalStorage,
+`ready` observation, failed-assembly eviction and HTTP `waitUntil` ownership.
+
+| Surface | Readiness, including an empty database |
+| --- | --- |
+| Consumer constant health, `/api/views` catalog | No content preparation. |
+| Static Admin shell and assets | No content preparation; incomplete Auth still fails closed as before. |
+| Manifest View/Trigger | Prepare before credential resolution, then use the same runtime invocation. |
+| Admin API, configured Auth base path, OAuth UI/discovery | Prepare before session/provider work. Auth tables share canonical migrations. |
+| MCP, including missing-token challenge | Prepare before the selected Auth verifier. A custom Auth implementation may require D1 even for a denied request; the facade cannot assume otherwise. |
+| Public page/list/discovery and favicon fallback | Their existing `ref.get()` starts preparation when content is needed. |
+| Consumer extension handlers | Call the supplied `getRuntime()` or `ref.get()` before using Mantle content or database-backed Auth. Pure handlers need neither. |
+| Queue/scheduled `getRuntime(env)` | Await both runtime preparation and Auth initialization, unchanged. |
+
+No deployment-time migration flag or KV readiness authority is introduced. A
+current database's first protected route needs one fingerprint SELECT; an empty
+or changed database performs canonical setup there. Concurrent first uses share
+that work. A failed preparation returns the facade's redacted 500, and later
+requests retry. Static availability is not a promise that data is ready.
+
+The pre-change full-facade fixture recorded 106 SQL operations for its empty-DB
+health request (its four Schemas include indexes), then 1 fingerprint operation
+for each new-state health/catalog/shell/challenge. These are statement counts,
+not network round trips. Its dry-run bundle was 3,921.40 KiB / 690.43 KiB gzip
+with Wrangler 4.124.0 and compatibility date 2026-07-08. Esbuild attributed
+1,342,428 emitted bytes to Better Auth, 76,078 to Admin, 24,624 to Web and
+203,130 to Runtime; the rest includes transitive libraries and adapter code.
+Byte attribution does not measure startup CPU. We retain static imports and
+immutable mount-time projections: deferring those modules has not yet been
+justified by a startup profile. The final #812 report owns the separate startup,
+preparation-wall and warm-dispatch measurements.
+
+Post-change full-facade workerd checks pass all 13 operation gates: empty-DB
+health and fresh-state health/catalog/shell perform zero **content** queries;
+the challenge retains its one fingerprint query. The fixture Auth is a stated
+stub. A separate real Better Auth regression records one eager oauthResource
+lookup while `ready` initializes; Better Auth 1.7.2 defers missing-table resource
+seeding to first access. Subsequent static requests perform no additional Auth
+queries. This background initialization is retained, not counted as eliminated
+content preparation or hidden behind a zero-total-SQL claim.

package/docs/adr-lite-809-bounded-public-content.md

@@ -0,0 +1,68 @@
+# ADR-lite: bounded public content and complete discovery
+
+Status: implemented for #809; combined deployment measurements tracked in #812.
+Context: ADR-0010 translation joins, ADR-0019 sealed semantic storage, #792 Web
+transport/cache ownership. No manifest keys or remote Web SDK are introduced.
+
+## Decision
+
+Add the semantic `EntryReader.readPublishedPage` operation instead of silently
+capping generic `readPublished`. Forward pages sort by updatedAt and id descending,
+with default 50 / maximum 2,000 rows and a 1-MiB data-JSON budget. A single larger
+entry remains readable and advances the cursor. This budget covers the selected
+canonical data, excluding envelope bytes, joined parents, media and consumer HTML.
+SQLite uses indexed, bounded candidates, a running byte sum and lookahead before
+transfer to Worker memory. Exact locale plus shared entries are merged in SQL.
+Selected data fields retain JSON types and use one bound JSON field list, including
+for projections larger than D1's ordinary bind or SQL-function argument limits.
+
+The optional Web use cases return an explicit page object. Cloudflare mounts
+publish its continuation in a body link and `Link: rel="next"`. HTML lists include
+accessible navigation. An empty intermediate/final llms page remains traversable.
+Root llms reads each canonical page once and expands shared entries per locale
+without repeated canonical reads. Unknown/unmapped/no-content rows consume their
+place in the page; they do not prevent reaching later eligible rows.
+
+Sitemap parts project path metadata and default to 2,000 entries, expanding shared
+routes per locale. The index walks the same metadata-page boundaries as the parts,
+so a byte-limited part cannot cause skipped URLs. Small sites keep a single urlset.
+Additional routes appear only in the first part. A custom path resolver must declare
+its required data fields to obtain projection; otherwise full bounded data remains
+available. Protocol limits fail explicitly instead of silently truncating URLs.
+
+Translation lists request only the newest published parent per join value. Storage
+ranks matching IDs before loading their bodies, preventing duplicate historical
+parents from multiplying transferred rows. Missing/draft parents leave the child
+unchanged. Child data still wins and media resolution remains one batch per page.
+
+## Limits and alternatives
+
+Sitemap index generation is O(N) metadata work on an origin MISS. It retains one
+page and the index's URL list rather than all entry bodies; the protocol permits
+at most 50,000 parts. Persisted generation/part boundaries would require an explicit
+publication/invalidation owner and are deferred until index traffic justifies it.
+A hard `LIMIT 500` would lose discovery URLs and is rejected. Offset pages would
+make deep traversal grow with depth and are rejected. Entry caching would leave
+the cold materialization spike and stale-state questions unresolved.
+
+Pages reflect live canonical state, not a cross-request snapshot: publishing or
+changing sort keys during a crawl can move entries between pages. Browser-local
+IndexedDB shares the semantic cursor and output budget but still scans a local
+collection. Parent/media data and consumer template expansion have separate costs;
+there is no promise that arbitrary consumer rendering fits 1 MiB.
+
+## Verification
+
+Real SQLite tests walk the 18 combinations of 100/10,000/50,000 rows, 64 B/4 KiB
+body and 1/3/10 locales, comparing complete llms/sitemap URL sets. List transfer is
+21 rows at limit 20 in every case; 50,000 mixed rows and 10 locales retain all
+275,000 URLs. Tests cover tied sort keys, >1-MiB entries, JSON projection types,
+missing projected keys, parent duplicates/missing/drafts, child overrides, media
+batching and persistence-field privacy. HTTP tests walk visible continuations,
+empty final pages, sitemap indexes and staff-only preview behavior. The portable
+storage conformance suite checks new semantics across adapters.
+
+Wrangler-local records native D1 query/row work for list, llms and sitemap alongside
+existing readiness, View, Procedure and Admin gates. Node traversal CPU/RSS includes
+fixture/assertion costs and is not reported as Worker CPU. Combined #812 evidence
+will supply Worker CPU, heap, cache HIT/MISS, remote controls and placement results.

package/docs/adr-lite-812-native-parity.md

@@ -0,0 +1,149 @@
+# ADR-lite: native and full-facade performance evidence (#812)
+
+Status: implemented; local gates passed. The deployment report and per-block
+budget verdicts are maintained in [PR #821](https://github.com/aotter/mantle/pull/821).
+
+The existing HTTP harness now records TTFB and full-body timing separately,
+response bytes, and bounded concurrent arrivals. `pnpm bench:wrangler` keeps the
+old row/query regressions and adds a native smoke matrix. `pnpm bench:parity`
+runs the larger matrix, real Better Auth PKCE/OTP/consent/JWT/DPoP issuance,
+revocation/role/replay denials, prepared D1 across fresh workerd processes, and
+R2 transfers. No token, cookie, proof, user ID, SQL, argument or object key enters
+the diagnostic record. Only the secret-protected synthetic fixture has control
+endpoints; never bind it to a consumer database or bucket.
+
+## Controls and boundaries
+
+| Layer | Work |
+|---|---|
+| F0 | Fixed fetch response; standalone `floor-worker.ts` measures module/bundle floor. R2 F0 performs HEAD only. |
+| F1 | Hono + native SQL and the same public payload; no authentication. |
+| F2 | Native Worker, shared real Auth/session/consent/fresh-role/DPoP checks, SQL compiler and validators, response envelope. MCP shares protocol dispatch and View execution; unmeasured mutations fail closed. |
+| M | Full `createMantleWorker`, same sealed plan, bindings, data and security policy. R2 uses the production storage commit adapter directly. |
+
+Protected parity is F2/M. The View and catalog response bodies must match, drafts
+stay private, and auth/protocol errors must fail correctly. Procedure input errors
+compare status/code, not complete diagnostic wording. Admin/Web are facade coverage,
+not a matched-native claim. R2 measures native stream metadata commits and failure/
+retry; D1 MediaAsset publication is covered by the separate #810 integration test.
+The shared comparison bundle intentionally keeps dependencies/configuration equal;
+it cannot measure the difference between standalone application bundle sizes.
+
+The planner runs outside workerd. Route/Schema/View axes each use 1/10/100/1,000;
+extra Schemas are unindexed to keep the index-count axis fixed. D1 has a 100-column
+limit, including generated index columns, so this is not a claim that 1,000 indexed
+Schemas fit one entries table. Body/row axes use 64 B/4 KiB and 100/10,000/50,000;
+locales use 1/3/10, MCP client concurrency uses 1/4/8, R2 uses 1/3/12 variants at
+1/64/256 KiB. Actual simultaneous arrivals can be below client concurrency. The remote fleet
+can add isolates during a batch. A request is repeat-in-isolate only after that
+exact workload previously completed there; overlapping first arrivals stay in
+the first-for-workload cohort. Two global warmups alone cannot prove a warm fleet.
+First requests retain their raw records and a bounded extra-six-statement setup
+allowance; repeat MCP requests must meet the exact two/three/four-statement gate.
+Parity summaries use repeat cohorts; first-for-workload does not necessarily mean
+cold module startup (another workload may already have used that isolate).
+
+## Stable gates and measured signals
+
+- Indexed public View: one statement and at most 100 available rows read at every
+  tested data size. MCP catalog: two statements (grant + fresh role), one KV GET;
+  View: three statements with Bearer, four with native DPoP replay reservation.
+- Selected Trigger: four segment lookups at every route count in the portable
+  regression; native last-route requests retain one statement at 1,000 routes.
+- Public HTML/llms: two warm statements and less than 1 MiB selected JSON. Sitemap
+  index remains explicit O(N) metadata work to enumerate complete part links.
+- R2: exactly N GET + N PUT, known full-body bytes, at most three transfers in
+  flight; a first-batch failure starts no later batch and a retry succeeds.
+- Fixture HTTP bodies at most 2 MiB; inspector heap after each batch at most
+  96 MiB. This is an observed JS heap ceiling, not instantaneous peak memory or
+  retained-after-GC heap. Custom application templates retain their own limits.
+
+The default fixture bundle gate is 4,500 KiB raw / 800 KiB gzip (measured
+3,699.93 / 647.98 KiB). The standalone F0 is 0.52 / 0.34 KiB; a 1,000-route
+fixture is 4,051.18 / 668.60 KiB. Larger manifest-axis builds are reported
+separately. Module startup profiles are a local diagnostic; actual deployed
+startup must remain below the provider limit and is recorded during acceptance.
+
+No cross-machine latency gate is used. CDP batch samples estimate local active JS
+(including warmup); they are not per-request or billing CPU. Native Tail CPU/wall
+are correlated by random request ID only in remote runs; unavailable timing stays
+null. D1 metadata sums cover only `metadataStatements`; native Auth `.first()` does
+not return rows/duration, and zero cannot substitute for that missing coverage.
+
+The 2026-09-08 full local run contained 2,697 measured requests / 144 cases, no
+unexpected HTTP status, max response 84,185 B, and max observed heap 67,103,480 B.
+The observed F2/M p50 full-body delta for the 50k-row/4KiB View was -0.347 ms
+(95% within-run bootstrap interval [-0.727, 0.128]); MCP catalog +0.903 ms
+[0.470, 1.070]; Bearer MCP View -0.578 ms [-1.235, 0.329]. These are localhost
+measurements, not a remote parity conclusion. Ten orthogonal route/Schema/View
+runs and both extra locale runs also passed. Self-review corrected a fixture that
+accidentally scaled indexes with Schemas, an English-only page assertion in the
+multilingual fixture, and missing D1 metadata incorrectly summarized as zero.
+
+## Remote difference budget (calibrated 2026-09-08)
+
+The first complete off-a block (05:44:20–05:57:16 UTC, SDK 1798e78) contains
+1,385 requests with 100% native CPU coverage, 46 first-for-workload arrivals and
+no unexpected status failures. Public cache returned MISS then HIT; the HIT
+had no invocation record. Warm F2/M CPU medians match at 0 ms health, 2 ms View,
+1 ms Procedure, 2 ms MCP catalog and 3 ms Bearer MCP View. DPoP medians differ
+by 0–1 ms; the largest within-run CPU delta upper interval is 2 ms. One hundred
+requests per layer/diagnostics mode measure roughly +1 ms median CPU for the
+collector itself on both layers. This is native millisecond-resolution telemetry.
+
+Freeze this initial budget before evaluating the on-a/off-b/on-b blocks:
+
+- At least 20 repeat-in-isolate samples per layer, equivalent successful payloads
+  and current authorization checks; expected denial cases are functional gates.
+- Upper 95% bootstrap interval for M minus F2 median platform CPU: at most 2 ms.
+- Upper 95% bootstrap interval for M minus F2 median full-body latency: at most
+  max(15 ms, 5% of the paired F2 median). Compare consistent placement contexts;
+  report changes in ingress/execution placement separately.
+- Exact warm statement/binding budgets and zero unexpected outcomes still apply.
+  Latency/CPU differences are a matched deployment acceptance budget, not an
+  absolute cross-machine CI timer gate. First-for-workload records stay visible;
+  the budget makes no blanket claim about cold setup or all native workloads.
+
+## Reproduction and remote acceptance
+
+Run from the repository root with built workspace dependencies:
+
+```sh
+pnpm bench:wrangler
+pnpm bench:parity
+BENCH_ROUTES=1000 BENCH_CASES=scaling pnpm bench:parity
+BENCH_SCHEMAS=1000 BENCH_CASES=scaling pnpm bench:parity
+BENCH_VIEWS=1000 BENCH_CASES=scaling pnpm bench:parity
+BENCH_LOCALES=en,fr,de BENCH_QUICK=1 pnpm bench:parity
+node scripts/summarize-wrangler-parity.mjs /path/to/report.json
+```
+
+For remote acceptance, provision dedicated synthetic D1/KV (R2 when enabled),
+put a random 32+ character BENCHMARK_KEY secret, and deploy the fixture with
+BENCH_REMOTE_RECORDS=1. Run with BENCH_ORIGIN, BENCHMARK_KEY, BENCH_ACCOUNT_ID,
+BENCH_PROFILE_NAME, BENCH_BLOCK and BENCH_PLACEMENT in the process environment.
+The runner uses Wrangler's existing named-profile authentication to open the
+same native trace-v1 API used by `wrangler tail`. It retains only the nonce-
+correlated diagnostic fields and native CPU/wall timing in memory, never request
+headers/body/URL, credentials or unrelated logs. The tail session is deleted at
+completion. No paid Tail Worker, sink database writes or elevated log API token
+is needed. Off-mode records also correlate platform CPU to measure overhead.
+
+PHSU has no R2 subscription; its remote run uses BENCH_SKIP_R2=1. R2 coverage
+comes from native workerd, with no remote R2 latency claim. A paid Tail Worker
+attempt was rejected by the provider, then replaced by the verified real-time API.
+
+Alternate off/on/off/on deployment blocks and BENCH_ORDER=reverse for the second
+pair. Record actual placement status, request `cf-placement` when supplied,
+ingress colo, deployment version, SDK/Wrangler/compatibility date, sampling window
+and errors. Origin timings force private/no-store; a separate probe requires a
+real public MISS followed by HIT with no invocation record. Local runs never
+invent HITs. A deployed Worker with existing D1 is labeled deployment-first.
+
+Use `wrangler deploy --dry-run --outfile <bundle>` followed by
+`wrangler check startup --worker <bundle> --outfile <profile>` for module startup.
+Record standalone F0, the full fixture and the actual packed consumer separately.
+Set the remote F2/M CPU/latency difference budget after collecting the baseline,
+then evaluate repeated blocks with bootstrap intervals, explaining shared-host
+and cross-request correlation. Smart Placement provisioning belongs to #803;
+INSUFFICIENT_INVOCATIONS is not evidence of a placement latency improvement.

package/docs/adr-lite-823-home-statistics.md

@@ -0,0 +1,63 @@
+# ADR-lite: collection creation statistics on Admin home
+
+Status: proposed with #823; implementation stays in an unmerged demo PR.
+Context: ADR-0019 semantic storage and optional Admin composition.
+
+Add one optional `EntryReader.readCreationStatistics` read. SQLite/D1 implements
+it; custom adapters without it return an explicit unavailable state in Admin.
+The staff guard runs before storage access, and successful responses are private,
+no-store. The endpoint accepts only primary, visible collections and four range
+presets. No manifest keys, generic aggregation language or new cache port.
+
+Each card independently persists its range and interval/cumulative mode in
+`cms.preference.collection-statistics.<collection>`. Only preferences enter
+localStorage. The chart and CSV describe current retained rows by native
+`createdAt`, all statuses, with current `uiSchema.list.filterField` classification.
+Unknown values share an Other series. Deleted rows are absent: these are creation
+cohorts of retained rows, not an event log or historical inventory. Cumulative
+means a prefix sum inside the selected range, starting from zero.
+
+Ranges are 1h/5m, 24h/1h, 7d/6h and 20d/1d. Every interval is half-open; the last
+ends at the observation time. CSV uses ISO UTC bounds while chart labels use the
+browser's timezone. SVG steps preserve exact bucket extents without interpolation.
+The toolbar download exports the current card's mode, current total and series;
+CSV cells are quoted and formula-shaped headers are neutralized.
+
+## Aggregation and freshness
+
+A single SQL statement returns a total and sparse grouped counts from one SQLite
+snapshot. `entries(collection, created_at)` is prepared by canonical migration
+0008. The range branch searches the index, and the total branch counts index
+entries. Payload JSON stays in the database; only count rows reach the Worker.
+
+The existing Cloudflare KV decorator caches MCP site configuration, not entry
+queries. Reusing that key/projection would mix unrelated data and mutation
+ownership. Direct aggregation is sufficient for this demo: Wrangler-local with
+10,000 rows returned 897 bytes with one statement, 30,002 engine rows read and
+p50/p95 of 4.26/5.80 ms (10 samples). A real SQLite test also aggregates 50,000
+4-KiB rows into at most 40 count rows / 4 KiB and verifies immediate updates and
+deletes. These are local measurements, not remote latency guarantees.
+
+There is no server statistics cache to evict or repopulate after a racing write.
+Every Admin/MCP/Procedure committed write is visible on the next read, including
+subtype updates and deletes. React Query data stays in memory, becomes stale
+immediately, and refetches on mount/focus and every 60 seconds while the home is
+active. Successful UI mutations invalidate its common statistics query prefix.
+Changing only cumulative mode reuses the same count data without another query.
+
+`ponytail:` exact totals still take O(N) index work and filtered time ranges may
+read JSON for subtype grouping; returned bytes are bounded by bucket/enum count,
+not row count. If measured production read volume makes this expensive, add a
+transactionally maintained collection revision/projection and revision-keyed KV
+snapshots. Plain KV delete-after-write is insufficient because eventual
+consistency and racing miss fills can serve old aggregates. No cron, event store,
+generic cache framework or eager write-through aggregate is justified here.
+
+## Verification
+
+Runtime SQLite tests cover lower/upper edges, unknown subtype, collection
+isolation, zero rows, edits/deletes, invalid windows, range index use and 50k rows.
+Admin tests cover 401/403 before storage, invalid collection/range (including
+prototype names), all presets, no-store, and unsupported adapters. UI tests cover
+all preference combinations, zero filling, stacking, prefix sums and CSV safety.
+Browser QA covers independent per-card preferences, reload, both themes and CSV.

package/docs/api-mcp-authorization.md

@@ -664,3 +664,10 @@ pnpm --filter @aotter/mantle-cloudflare exec vitest run \
 contains all four scenarios and the exact public API names used by the fixture.
 The package typecheck catches changes to those APIs; the integration test
 catches changes to REST/MCP enforcement and mutable guard behavior.
+
+The canonical MCP grant check joins the JWT's exact consent and original
+session in one indexed D1 statement. Both identities, their user/client
+bindings, session expiration, resource and the complete token scope set must
+still match. The adapter then reads the user's role on every protected request;
+no grant or role result is cached. With warm JWKS, this is one grant binding
+call plus one role binding call, excluding DPoP replay, catalog and tool work.

package/docs/cloudflare-low-level-composition.md

@@ -14,13 +14,13 @@ import {
   createConventionalAuth,
   createConventionalBindings,
   createMcpApiHandler,
-  mountAuthorize,
   mountAdmin,
   mountRuntimeEndpoints,
   runMantleWorkerRequest,
   setupIncompleteAuthResponse,
   type MantleCloudflareEnv,
 } from "@aotter/mantle/cloudflare";
+import { mountMantleOAuth } from "@aotter/mantle/admin";
 import { plan } from "../.mantle/generated/mantle.js";
 
 interface Env extends MantleCloudflareEnv {
@@ -36,9 +36,13 @@ let assembled: ReturnType<typeof assemble> | undefined;
 export default {
   fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
     return runMantleWorkerRequest(async () => {
-      assembled ??= assemble(env);
-      const incomplete = await setupIncompleteAuthResponse(request, assembled.auth);
-      const response = incomplete ?? await assembled.fetch(request, env, ctx);
+      const worker = assembled ??= assemble(env);
+      if (worker.auth.ready) ctx.waitUntil(worker.auth.ready.catch((error) => {
+        if (assembled === worker) assembled = undefined;
+        throw error;
+      }));
+      const incomplete = await setupIncompleteAuthResponse(request, worker.auth);
+      const response = incomplete ?? await worker.fetch(request, env, ctx);
       ctx.waitUntil(env.AUDIT_QUEUE.send({
         kind: "request-complete",
         path: new URL(request.url).pathname,
@@ -57,7 +61,7 @@ function assemble(env: Env) {
 
   mountRuntimeEndpoints(app, ref);
   if (bindings.adminAssets) mountAdmin(app, ref, bindings.adminAssets);
-  mountAuthorize(app, { auth });
+  mountMantleOAuth(app, { auth, assets: bindings.adminAssets });
   app.get("/cache-probe", () => new Response("public", {
     headers: { "cache-control": "public, s-maxage=60" },
   }));
@@ -83,9 +87,11 @@ function assemble(env: Env) {
 }
 ```
 
-Keep the conventional `DB` binding and `nodejs_compat`. CIMD metadata fetches
-also require `global_fetch_strictly_public`; add the Queue producer in
-`wrangler.jsonc`:
+Keep the conventional `DB` binding and `nodejs_compat`. An optional
+deployment-owned `MANTLE_KV` binding lets `createConventionalBindings` maintain
+the MCP catalog's site-settings projection at write time while D1 remains
+canonical. CIMD metadata fetches also require `global_fetch_strictly_public`;
+add the Queue producer in `wrangler.jsonc`:
 
 ```jsonc
 {

package/docs/labels.md

@@ -34,6 +34,7 @@ For package README or package-local docs changes, prefer the package area label
 | `area:admin-ui` | `packages/mantle-admin-ui` React admin SPA. |
 | `area:docs` | Repo-wide human docs, governance docs, ADR text, release docs, root README content, and cross-cutting documentation work. |
 | `area:adapter` | Adapter boundary work spanning Cloudflare or future adapters. |
+| `area:ci` | GitHub Actions, dependency automation, and repository checks. |
 
 ## Release and review gates
 
@@ -60,6 +61,7 @@ gh label create "area:skills" --description "Agent Skills and install/extend/pro
 gh label create "area:admin-ui" --description "React admin UI" --color "1d76db"
 gh label create "area:docs" --description "Documentation and governance" --color "1d76db"
 gh label create "area:adapter" --description "Adapter boundary and future adapter work" --color "1d76db"
+gh label create "area:ci" --description "CI, dependency automation, and repository checks" --color "1d76db"
 gh label create "breaking-change" --description "Semver-relevant breaking change" --color "b60205"
 gh label create "skip-release-notes" --description "Release bookkeeping only; omit from generated GitHub notes" --color "ededed"
 gh label create "needs-adr" --description "Requires an ADR or ADR-lite decision before merge" --color "d93f0b"

package/docs/media-uploads.md

@@ -184,3 +184,28 @@ Run the version-matched `media-gc` skill when an upload reached R2 but was
 never committed. It audits first and removes only stale objects without
 `committedAt` metadata after explicit operator confirmation. Do not use an R2
 lifecycle rule: committed and uncommitted media share the same purpose prefix.
+
+### R2 commit cost and recovery
+
+R2 has no metadata-only patch. Mantle retains the existing `committedAt`,
+`role`, `uploadGroupId` and filename markers by streaming each uploaded object
+through GET → PUT. Commits validate the bundle shape before I/O and process
+batches of at most three variants. A batch settles before another starts or an
+error returns. MIME/size failures cancel the unused GET stream; failed PUTs also
+attempt cancellation while preserving the original error.
+
+A successful N-variant commit still uses N GETs, N PUTs and rewrites the sum of
+variant sizes. Parallelism reduces serial waiting, not operation count or
+bytes. Streaming-fake checks cover 1 × 1 KiB, 3 × 64 KiB and 12 × 256 KiB, with
+maximum in-flight variants 1/3/3 and exact rewrite budgets; these are not remote
+R2 latency measurements. Native R2 measurements and the complete media use case's separate D1 costs
+are tracked by the shared #812 performance harness.
+
+The asset row is saved only after every variant succeeds. Partial R2 failure
+keeps the pending D1 record for retry before expiry. Already stamped objects
+remain stamped and old/new committed media remains protected by the existing
+GC rule. After pending expiry, partially stamped orphan objects require an
+operator audit against D1 references; the ordinary GC must not remove their
+markers or assume that a missing pending record means an object is unused.
+This retains the existing conservative recovery contract without moving commit
+or GC authority into KV.

package/docs/performance-harness.md

@@ -75,12 +75,14 @@ Timing always reports p50/p95/max. A test-only Worker wrapper may also return
 `x-mantle-query-count` and `x-mantle-rows-read`; those become distributions in
 the same report. Do not expose these diagnostic headers in production.
 
-Core CI runs `pnpm bench:wrangler` against real Wrangler-local D1, Worker HTTP
-routing, View execution, and origin page rendering. It compares 100 and 10,000
-row fixtures and gates row-read scaling plus endpoint query budgets, not
-absolute milliseconds. Wrangler-local does not emulate the new entrypoint
-Workers Cache, so cache hits are a deployment-level smoke check rather than a
-fabricated local metric.
+The path-scoped Cloudflare benchmark workflow runs `pnpm bench:wrangler`
+against real Wrangler-local D1, Worker HTTP routing, View execution, and origin
+page rendering. It compares 100 and 10,000 row fixtures and gates row-read
+scaling plus endpoint query budgets, not absolute milliseconds. It is separate
+from the required repository checks so an unrelated dependency or docs PR does
+not fail on the platform harness. Wrangler-local does not emulate the new
+entrypoint Workers Cache, so cache hits are a deployment-level smoke check
+rather than a fabricated local metric.
 
 ## Seven findings: measured disposition
 
@@ -91,7 +93,7 @@ diagnostic, while query/row counts are the stable assertions.
 |---|---|
 | Public cache hits read D1 first | Removed from Worker code. Cloudflare's entrypoint Workers Cache runs before the Worker; Core has no inner render cache. |
 | Slug/locale reads bypass generated indexes | Fixed by the shared schema-aware entry-read boundary. A 10,000-row page MISS measured 2 queries / 5 rows read. |
-| OFFSET pagination | Accepted for the v0.1 bounded-result surfaces: every response is capped at 500 rows and public hot paths must stay shallow. Deep/export workloads require a purpose-shaped cursor API before they are declared hot. |
+| OFFSET pagination | Retained only where the View/Admin contract explicitly uses it, with a 500-row response cap. Public content lists and discovery now use forward keyset pages; they are not covered by the old 500-row claim. |
 | Admin substring search scans | Accepted only for the authenticated Admin collection browser, with a 500-row response cap. Large/search-heavy sites should add a purpose-shaped indexed View or dedicated search service; do not expose this scan publicly. |
 | Published list/sitemap/llms paths lack system indexes | Fixed with measured partial indexes for published global, locale, collection, and collection+locale ordering. The 100-row and 10,000-row API runs both measured 1 query / 20 rows read. |
 | Page MISS waits for cache write-back | Removed. Origin rendering returns directly; Workers Cache owns response storage outside the Worker. |
@@ -102,3 +104,118 @@ not patterns for new public APIs. Re-measure before widening either scope.
 
 See also [Schema indexes](./schema-indexes.md) and the official Cloudflare
 [D1 index guidance](https://developers.cloudflare.com/d1/best-practices/use-indexes/).
+
+### Prepared database, new Worker state
+
+The Wrangler fixture resets its in-isolate runtime after seeding while retaining
+D1. The first public page has a four-statement budget (fingerprint, lazy locale,
+site settings, entry); subsequent origin pages have a two-statement budget.
+This is a new application state in the same workerd isolate, not a measurement
+of module startup CPU or an entrypoint cache HIT. Locale caching is enabled by
+a successful preparation fingerprint; editable settings and media policy still
+read the canonical database on every call.
+
+### HTTP Trigger routing
+
+The portable request handler indexes Trigger paths by method and segments once.
+Literal and wildcard branches retain sealed-plan order, including encoded literal
+collisions that an outer router may select differently. Each request decodes its
+segments once and invokes the original Trigger identity through the same runtime.
+The 1/10/100/1,000-route regression uses four segment lookups at every size;
+overlapping wildcard shapes can visit multiple branches, pruned by route rank.
+The HTTP microbench and workerd harness include the same route-count axis.
+Workerd wall times include I/O and are not CPU measurements or a fixed-ms CI gate.
+
+### Public content pages and discovery (#809)
+
+| Surface | Canonical read / continuation |
+|---|---|
+| Collection HTML and collection Markdown | 50 entries by default, forward `cursor`; visible Next link plus HTTP `Link: rel="next"`. |
+| Locale and root llms.txt | One canonical page, default 50 entries; root expands that page across configured locales in memory. Shared entries are not reread once per locale. Follow the body/HTTP continuation link. |
+| Sitemap part | Up to 2,000 entries, with only declared path fields (built-in resolver: `slug`). A small site returns a urlset directly; a larger site returns a sitemap index linking every part. |
+| Sitemap index | Walks metadata pages to derive exact part cursors; O(N) metadata work on an index MISS, with one page resident at a time. It is not a constant-work list endpoint. |
+
+`EntryReader.readPublishedPage` caps returned data JSON at 1 MiB and 2,000 rows.
+One oversized entry is returned alone to make progress. SQLite applies the byte
+budget before transferring/parsing JSON in the Worker; one extra candidate
+identifies continuation. A localized + shared page merges two indexed ranges
+inside the same statement. The original `readPublished` remains an explicit
+unbounded read unless its caller supplies a limit.
+
+Translation lists resolve at most one newest published parent per join value,
+then resolve media once for the bounded list. Parent payloads and media metadata
+are additional input; the 1 MiB budget describes the canonical child page, not
+arbitrary template output or total Worker heap. Custom renderers own their output
+size. IndexedDB keeps identical page semantics but currently scans its local
+collection; this is not a claim of bounded IndexedDB storage I/O.
+
+The real SQLite fixture matrix covers 100/10,000/50,000 published rows, 64 B/4 KiB
+bodies, and 1/3/10 locales. At limit 20, every case transfers 21 candidate rows;
+4 KiB body data occupies 87,003–87,129 bytes, independent of collection size.
+Complete llms traversal uses 2/200/1,000 statements at the default 50-row page
+size, independent of locale count. Sitemap and llms URL sets match, including
+275,000 URLs for 50,000 mixed localized/shared rows across 10 locales.
+
+Run `pnpm --filter @aotter/mantle-cloudflare exec vitest run
+test/public-content-scaling.test.ts` to emit JSON transfer sizes and traversal
+CPU/wall/RSS diagnostics. These are Node + SQLite + assertions, including the
+fixture database and URL-validation set; RSS is a process high-water mark, not
+per-request Worker peak memory. Worker CPU, true cache HIT/MISS and placement
+measurements belong to the matched native/full-stack harness (#812).
+
+The workerd smoke also measures public list, llms and sitemap. The first two
+use two warm statements (settings + page) and bounded D1 work. Sitemap index
+queries and rows-read scale with the number of metadata parts; this explicit
+cost preserves complete discovery instead of silently dropping URLs.
+
+### Request diagnostics (version 1, test/performance only)
+
+Import `runWithRequestDiagnostics`, `instrumentD1`, `instrumentKv` and
+`instrumentR2` from `@aotter/mantle-cloudflare/testing`. Wrap native bindings once
+before handing the same D1 object to Auth and Runtime. Open the request context
+outside the complete facade fetch, and pass binding-presence flags matching the
+instrumented fixture. The observer receives one response-time record; it never
+receives request headers, tokens, proofs, user IDs, SQL, parameters, tool arguments,
+object keys or response content. Sync/async observer failure cannot change the
+original response or exception. The library emits no diagnostic headers or logs.
+
+Records distinguish HTTP outcome from JSON-RPC result/error/tool-error. They
+include actual in-isolate arrivals, inclusive OAuth/DPoP, role, runtime, catalog,
+dispatcher construction and dispatch wall spans. Unreached phases are null.
+Shared KV loads charge native I/O once to the initiating request; waiters record
+wait duration and the same hit/miss/repair/error source. Boot publication has a
+separate counter. The original rejected shared load remains retryable.
+
+D1 statements and binding calls are separate: a batch is one call and N attempted
+statements. Failed attempts count. `exec` uses the provider's count; unavailable
+counts stay in `unknownStatementCalls`, never a semicolon parser. `first(column)`
+and `raw` preserve native behavior and do not silently execute `all` to manufacture
+metadata. Their absent metadata is null. Rows/duration are sums of available
+metadata, and `metadataStatements` identifies coverage; incomplete coverage is
+not a full-workload total. Serialized binding results are measured bytes, not a
+claim about bytes on the provider's wire. Existing D1DatabaseDriver observers can
+request metadata for first-row reads when a fixture explicitly chooses that mode.
+
+KV bytes identify UTF-8, buffer or reserialized JSON sources. R2 payload bytes
+remain unknown for an unconsumed/partly consumed GET. A successful PUT of that exact
+native GET stream confirms the transferred body size on both operations. Streams
+are never wrapped or buffered for diagnostics, preserving R2's native known-length
+contract. `byteSamples` distinguishes known payload samples from the operation
+count. Metadata/list response serialization is labeled separately from object
+payload. R2 coverage is head/get/put/delete/list, not multipart-upload instrumentation.
+
+Snapshots freeze at response creation; outstanding/deferred operations remain
+visible through `inFlight` and metadata coverage and cannot rewrite a published
+record. `totalMs` excludes the subsequent test-only JSON-RPC response inspection,
+delivery and deferred work. CPU, TTFB, full-body duration and heap must be measured
+separately. Worker wall clocks advance on I/O and are not a CPU timer; use the
+[official CPU profiler](https://developers.cloudflare.com/workers/observability/dev-tools/cpu-usage/).
+Measure diagnostics off/on overhead with the same workload before interpreting
+small latency differences.
+
+### Matched native facade controls (#812)
+
+`pnpm bench:wrangler` now also runs the native parity smoke. The full
+`pnpm bench:parity` matrix adds real Auth/MCP, cold workerd processes, R2,
+TTFB/full-body timing and CPU/heap evidence. See
+[the controls, gates and reproducible commands](./adr-lite-812-native-parity.md).

package/docs/release-process.md

@@ -1,6 +1,6 @@
 # Release process
 
-Mantle remains prerelease software until the stable v0.1.0 gate closes.
+Mantle remains prerelease software until the first stable v0.1.2 gate closes.
 Published package versions, Git tags, GitHub releases, and Starter tags are
 immutable: repair a bad release with the next version, never by replacing
 public state.
@@ -87,8 +87,8 @@ rollback or unpublish behavior, or deploy Landing unless
 - npm dist-tags follow the suffix: `alpha`, `beta`, `rc`, or `latest` for
   stable versions.
 - During the legacy `0.0.x-alpha` cadence, `latest` follows the current alpha.
-  The final `0.1.0-alpha.N` candidates advance only `alpha`; `latest` moves to
-  `0.1.0` after the stable gate passes.
+  The final `0.1.0-alpha.N` candidates advance only `alpha`; `latest` advances to the first stable `0.1.2` after its gate passes.
+  Do not roll back an existing legacy `latest` value.
 
 ## Release PR
 
@@ -252,3 +252,14 @@ deployment was started.
 - A cross-cutting rename must include an explicit infrastructure-config diff
   and live smoke test. CI success does not prove renamed Worker, D1, KV, route,
   or secret bindings are correct.
+
+## Final legacy release and next stable target
+
+Owner decision (2026-09-08): `0.1.0-alpha.17` closes the legacy Landing/Starter
+product line. Pin the existing Landing packages, Core deployment SHA and Starter
+refs to that release, and retain immutable Starter tags for existing consumers.
+No stable `0.1.0` release is planned. Issue #621 is superseded, not a claim that
+its former production soak passed. First stable targets milestone `0.1.2`, with
+new acceptance covering identity isolation, safe updates and retained production
+stability after the breaking architecture is settled. Retiring Starter launch
+is tracked by #786; the separate landing-next repository is out of this release.

package/docs/spec-only-host-adoption.md

@@ -0,0 +1,184 @@
+# Spec-only adoption in an existing host
+
+An existing application can reuse Mantle's Schema grammar and validation by
+consuming the published `@aotter/mantle-spec` package, without running Mantle
+Runtime. This Spec-only path is allowed by
+[ADR-0019](adr/0019-sealed-manifest-runtime-pipeline.md), not a new adapter,
+manifest grammar, or fork of Core.
+
+This recipe targets `0.1.0-alpha.16`. Its public APIs and peer requirements are
+prerelease contracts: pin the package, record the tested version, and rerun
+compatibility checks when upgrading.
+
+## What stays with the host
+
+| Concern | Spec reuse | Host responsibility |
+|---|---|---|
+| Model definitions | Schema grammar, parse/link diagnostics | Project existing definitions into supported JSON Schema |
+| Input | `EntryDataValidator` and structured errors | Authentication, authorization, normalization, write orchestration |
+| Model browser | Parsed/linked Schema metadata | UI, metadata visibility, field display, graph layout |
+| Relationships | Translation declaration/link validation | Existing slug joins, record integrity, locale policy |
+| Storage and publishing | None in this recipe | Files, database, transactions, revisions, release/recovery |
+| Operations and tools | None in this recipe | No automatic View, Procedure, Trigger, REST or MCP execution |
+
+Mantle's Web, Admin UI and platform adapters remain optional. A Vue host does
+not have to embed the React Admin SPA to reuse Spec. Avoid importing SDK
+internals or maintaining a second manifest interpreter.
+
+## One definition, several projections
+
+The motivating Aotter official-website implementation keeps its existing
+Nuxt/Nitro host and Git/D1 storage. Shared content definitions drive the site's
+content layer, admin write validation, a responsive model/ER browser, and
+Schema export. That website implementation was validated locally; this SDK
+contribution does not deploy it or claim a production rollout.
+
+```text
+Host-owned content definitions
+  ├─ existing CMS/content queries
+  └─ JSON Schema in Mantle Schema manifests
+       ├─ parse + link → model browser / metadata export
+       └─ EntryDataValidator → host-authorized write path
+```
+
+Use the existing definitions as the source of truth. If the host starts with
+Zod or another schema language, conversion is a host concern: verify that the
+result uses supported JSON Schema keywords and preserves the intended
+validation semantics. Do not hand-maintain a second field list for the graph.
+
+## Minimal public-API recipe
+
+Install the exact Spec package and its supported peer, without Runtime:
+
+```sh
+npm install --save-exact @aotter/mantle-spec@0.1.0-alpha.16 zod@4.5.4
+```
+
+The [synthetic fixture](../packages/mantle-spec/test/fixtures/spec-only-host.yaml)
+contains categories, articles and article translations. It contains no real
+website records, account configuration or credentials. Given that fixture as
+`manifestYaml`, the application can prepare its validated model once:
+
+```ts
+import {
+  EntryDataValidator,
+  parseManifestSources,
+  ValidateManifestsUseCase,
+} from "@aotter/mantle-spec";
+
+const parsed = parseManifestSources({
+  sources: [{ sourceId: "host:content-model", text: manifestYaml }],
+});
+if (!parsed.ok) throw new Error(JSON.stringify(parsed.diagnostics));
+
+const checked = ValidateManifestsUseCase.run({
+  parsed: parsed.value,
+  siteLocales: ["zh-TW", "en-US"],
+});
+if (checked.errorCount || !checked.linked) {
+  throw new Error(JSON.stringify(checked.diagnostics));
+}
+
+const article = checked.linked.schemas.find(
+  ({ manifest }) => manifest.metadata.name === "articles",
+)!.manifest;
+const validator = new EntryDataValidator();
+const diagnostics = validator.validate(article, { category: 42 }, { partial: true });
+// INPUT_VALIDATION_FAILED at /category. The host must reject the write.
+```
+
+The non-null assertion is specific to this known fixture. A dynamic host must
+handle an unknown collection explicitly and fail closed. Do not fabricate
+sealed parser/linker values or re-parse the same revision in each request.
+
+`EntryDataValidator` returns diagnostics, not a sanitized payload. It does not
+persist, authorize, coerce the original object, or enforce storage integrity.
+Normalize explicitly in the host before validation and write only after
+successful validation and authorization. An `additionalProperties: true`
+compatibility policy accepts legacy fields; it is not a reason to expose those
+fields publicly.
+
+`partial: true` relaxes top-level required fields for drafts, while still
+checking supplied types and nested required fields. Validate without `partial`
+when the host needs a complete record, alongside its own publication rules.
+Create a fresh validator for each model revision: its compiled cache is keyed
+by manifest name (and partial/full mode), not by a changing schema body.
+
+## Honest ER diagrams and metadata export
+
+- Derive model nodes and field details from Schema properties. Use a small
+  host-owned relationship registry for relations not represented by Mantle
+  grammar; show logical joins distinctly from actual database foreign keys.
+- The fixture's `x-example-source` and `x-example-relations` live inside JSON
+  Schema. They are illustrative vendor annotations, **not new Mantle keys or
+  executable relationship definitions**. Core may preserve them without
+  interpreting them. The host must validate their shape and endpoint fields.
+- Do not label a filename/slug join as `x-mantle-ref`: that keyword represents
+  Mantle entry-ID references. A category slug matching a key inside a YAML
+  array remains a host-specific relation, not a generated SQL foreign key.
+- `translates` validates the parent and join-field declarations, not whether
+  actual translation records exist. A Spec-only host still owns allowed
+  locales, uniqueness, fallback, and orphan handling. See
+  [ADR-0010](adr/0010-locale-and-translates.md); Runtime locale/storage gates
+  are not installed by this recipe.
+- A read-only inventory can add derived fields such as filename `slug` or
+  directory `locale` without changing stored files. Document that projection;
+  it is not evidence that existing data is ready for Runtime import.
+- The fixture uses JSON Schema `readOnly` as an inventory annotation. It is
+  not a security boundary: entry validation does not enforce host write
+  permissions. Export only after applying the host's metadata access policy.
+- Exclude credential/account models and private data. Export schemas, not
+  records. Where appropriate, require an administrator and use
+  `Cache-Control: private, no-store` for model and export endpoints.
+- Keep the graph usable on narrow screens: searchable model selection,
+  focused relationships, zoom/scroll, keyboard controls and a field-table
+  alternative. A graph must not be the only accessible representation.
+
+## Reproducible evidence
+
+From this SDK checkout:
+
+```sh
+pnpm --filter @aotter/mantle-spec test -- test/spec-only-host.test.ts
+pnpm --filter @aotter/mantle-spec typecheck
+```
+
+The [regression test](../packages/mantle-spec/test/spec-only-host.test.ts)
+exercises the public export surface, manifest round trips, translation linking,
+and strict/partial entry validation without Runtime. It is an SDK regression
+fixture, not a new Starter workspace or a certification test suite.
+
+An adopting host must also test its own installed package, real content
+compatibility, HTTP authorization/invalid-input paths, metadata exclusions and
+responsive UI. Existing data need not be published or uploaded to prove this.
+Keep sensitive evidence internal and expose only an agreed verification report.
+
+## Maintainer decision requested: ecosystem identity and recognition
+
+The Aotter website is offered as a first **candidate** for a maintainer-designed
+recognition process. This section asks for that design; it does not establish
+an official certification, new compatibility tier or permission to use a badge.
+
+Decisions requested from Mantle maintainers:
+
+1. **Presentation:** how should a host show its relationship to Mantle in its
+   admin/about UI? Define approved terminology, visual mark and link target,
+   including how Spec-only adoption differs from Runtime/module adoption.
+2. **Criteria and evidence:** which capabilities are being attested, against
+   which exact SDK version, and which checks must be reproducible? Distinguish
+   schema validation from runtime interoperability and security review.
+3. **Authority and lifecycle:** who can grant recognition, where can a badge
+   be independently verified, and when must it be renewed or withdrawn after
+   package or application changes? Prevent self-issued marks from implying
+   maintainer approval.
+4. **Pilot:** what additional evidence should this existing-host candidate
+   provide before receiving a mark, without exposing content or credentials?
+
+Until that decision exists, an accurate technical status is **"Spec validation
+passed against <exact version>"**, with a tested-capabilities list. It must not
+be presented as **"Mantle certified"** or as a guarantee of data migration,
+release reliability, security, shared UI components or full Runtime support.
+
+This proposal uses the optional composition in ADR-0019 and respects
+[ADR-0018](adr/0018-core-starters-repository-boundary.md): the website remains
+an external consumer; the SDK receives only documentation and synthetic tests.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.1.0-alpha.15",
+  "version": "0.1.0-alpha.17",
   "description": "Embeddable Mantle Core umbrella with Spec and Runtime; Web, Admin, Bun, Vercel, Cloudflare, and Admin UI are optional peer packages.",
   "license": "Apache-2.0",
   "homepage": "https://mantle.tools/",
@@ -83,21 +83,21 @@
     "README.md"
   ],
   "dependencies": {
-    "@aotter/mantle-runtime": "0.1.0-alpha.15",
-    "@aotter/mantle-spec": "0.1.0-alpha.15"
+    "@aotter/mantle-spec": "0.1.0-alpha.17",
+    "@aotter/mantle-runtime": "0.1.0-alpha.17"
   },
   "peerDependencies": {
     "aws4fetch": "^1.0.20",
-    "better-auth": "^1.7.1",
+    "better-auth": "1.7.2",
     "hono": "^4.12.0",
     "@libsql/client": "^0.17.4",
     "zod": "^4.5.0",
-    "@aotter/mantle-bun": "0.1.0-alpha.15",
-    "@aotter/mantle-admin-ui": "0.1.0-alpha.15",
-    "@aotter/mantle-cloudflare": "0.1.0-alpha.15",
-    "@aotter/mantle-admin": "0.1.0-alpha.15",
-    "@aotter/mantle-web": "0.1.0-alpha.15",
-    "@aotter/mantle-vercel": "0.1.0-alpha.15"
+    "@aotter/mantle-admin": "0.1.0-alpha.17",
+    "@aotter/mantle-admin-ui": "0.1.0-alpha.17",
+    "@aotter/mantle-bun": "0.1.0-alpha.17",
+    "@aotter/mantle-vercel": "0.1.0-alpha.17",
+    "@aotter/mantle-cloudflare": "0.1.0-alpha.17",
+    "@aotter/mantle-web": "0.1.0-alpha.17"
   },
   "peerDependenciesMeta": {
     "@aotter/mantle-admin": {
@@ -134,18 +134,18 @@
   "devDependencies": {
     "@types/node": "^26",
     "aws4fetch": "^1.0.20",
-    "better-auth": "^1.7.1",
+    "better-auth": "1.7.2",
     "hono": "^4.13.3",
     "@libsql/client": "^0.17.4",
     "typescript": "^6.0.3",
     "vitest": "^4.1.11",
     "zod": "^4.5.4",
-    "@aotter/mantle-admin": "0.1.0-alpha.15",
-    "@aotter/mantle-admin-ui": "0.1.0-alpha.15",
-    "@aotter/mantle-cloudflare": "0.1.0-alpha.15",
-    "@aotter/mantle-bun": "0.1.0-alpha.15",
-    "@aotter/mantle-vercel": "0.1.0-alpha.15",
-    "@aotter/mantle-web": "0.1.0-alpha.15"
+    "@aotter/mantle-admin-ui": "0.1.0-alpha.17",
+    "@aotter/mantle-admin": "0.1.0-alpha.17",
+    "@aotter/mantle-bun": "0.1.0-alpha.17",
+    "@aotter/mantle-cloudflare": "0.1.0-alpha.17",
+    "@aotter/mantle-vercel": "0.1.0-alpha.17",
+    "@aotter/mantle-web": "0.1.0-alpha.17"
   },
   "engines": {
     "node": ">=22"