@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.2

package/docs/handbook/cloudflare/site-chrome.md

@@ -1,75 +0,0 @@
----
-description: Host-owned site chrome — Cloudflare-first analytics, verification, robots, and what still belongs in mantle-web.
----
-# Site chrome
-
-Core `siteConfig` is deployment identity: locales, brand, title, description, origin, icons and media. Visitor analytics, pixels, search-engine verification tokens, `ads.txt` and similar chrome are **host responsibility**. Admin Settings does not accept tracking IDs, and `@aotter/mantle-web` does not inject vendor snippets from `siteConfig`.
-
-Cloudflare-native platform capabilities are the first-class place for chrome that the zone already covers. Do not invent a parallel “CDN settings center” inside Mantle.
-
-## Why Core does not inject
-
-A headless runtime that rewrites the first `</head>` (or prepends to `<body>`) on a composed HTML string assumes one frontend shape: a complete SSR document that Core is allowed to mutate after the fact. Hosts are not one shape.
-
-Frontends are plural. A Mantle consumer may serve SSR full HTML documents, a Vite/React (or other) SPA, a Worker plus static assets, Cloudflare Pages, or a custom wrapper that already owns `<html>`. Only the first of those even has a complete document string a runtime could splice into — and even then the attach point is the host template, not Core.
-
-SPA, client-routed and hydration hosts attach analytics in **their own entry**: GTM or Zaraz, the app bootstrap, or Cloudflare Web Analytics. They do not expect Runtime or `mantle-web` to parse an HTML string and splice tags into it.
-
-Silent injection from `siteConfig` would be a surprising side effect for any host that did not opt into “I emit a full document and you may rewrite it.” Core must not pretend to know every frontend’s attach point.
-
-Therefore tracking and verification stay **host chrome**. Core `siteConfig` is not a tag-manager. The tables below say where to put chrome.
-
-## Two layers
-
-| Concern | Prefer | Usually still app / mantle-web |
-|---|---|---|
-| `robots.txt`, simple redirects, some `/.well-known` files, Cloudflare Web Analytics | **Cloudflare-native** | — |
-| Dynamic sitemap (grows with content), `llms.txt`, SEO `.md` mirrors | — | Application mount or `@aotter/mantle-web` composition, then serve publicly |
-
-Turning on Cloudflare Web Analytics is **not** the same as having an indexable sitemap or `llms.txt`. Analytics answers “who visited”; discovery files answer “what can a crawler or agent list”. Keep those jobs on the layer that owns the data.
-
-Cloud tenant UX for ads.txt / robots / sitemap tools lives on the host product. Core stays injection-free.
-
-## Cloudflare-first install
-
-Use the dashboard, Wrangler, or an agent that can edit Worker / Pages config. None of these paths write Core Admin fields.
-
-### Analytics
-
-Prefer **Cloudflare Web Analytics** (and Zaraz when you need a tag manager) for first-party traffic measurement. Enable it on the zone; no Core `siteConfig` key is required.
-
-To add GA4 or Meta Pixel:
-
-1. Add the provider through **Cloudflare Zaraz** (recommended on a CF zone), or
-2. Emit the vendor snippet from **your** entry/list templates in `@aotter/mantle-web`, or from a host HTML wrapper.
-
-Do not put Measurement IDs or Pixel IDs in `siteDefaults`. Core does not persist or inject them.
-
-### Search Console and Bing verification
-
-Verify ownership with a host-owned method. On Cloudflare, prefer in this order:
-
-1. **DNS TXT** at the zone apex (Search Console and Bing Webmaster both accept this).
-2. **Cloudflare-managed HTML** via Zaraz or a small Worker / Pages header rewrite that adds `<meta name="google-site-verification">` / Bing equivalent.
-3. A **static verification file** at `/` or `/.well-known/` served from `public/` / the `ASSETS` binding.
-
-HTML-tag verification belongs in the host template `<head>`, not in Core Settings.
-
-### robots.txt, redirects, well-known
-
-Serve a static `robots.txt` from assets, or use Cloudflare Redirect Rules / Transform Rules / a tiny Worker route. `mountPublicRoutes` also emits `GET /robots.txt` (`Allow: /` plus the sitemap URL) when you opt into public pages — that is an application mount, not a Core Admin setting. See [Public web](./public-web.md).
-
-Simple path redirects and most `/.well-known` files (including verification and `security.txt`) belong on the same Cloudflare-native layer.
-
-## What still belongs in the app
-
-Dynamic **sitemap** and **`llms.txt`** grow with published content. Compose them with `@aotter/mantle-web` (`composeSitemap`, `composeLlmsTxt`) and mount the public URLs, or implement the same contract in the application. Cloudflare Web Analytics does not generate those files.
-
-SEO `.md` mirrors are likewise application / `mantle-web` composition. Details: [Public web](./public-web.md) and [Site config](../reference/site-config.md).
-
-## Source
-
-- [`packages/mantle-spec/src/domain/model/SiteConfig.ts`](../../../packages/mantle-spec/src/domain/model/SiteConfig.ts)
-- [`packages/mantle-web/src/service/HtmlRenderer.ts`](../../../packages/mantle-web/src/service/HtmlRenderer.ts)
-- [`docs/handbook/reference/site-config.md`](../reference/site-config.md)
-- [`docs/handbook/cloudflare/public-web.md`](./public-web.md)

package/docs/handbook/examples/commerce-transaction.md

@@ -1,11 +0,0 @@
----
-description: Redirects to the Cloudflare primitives commerce inventory example in the Examples hub.
----
-# Commerce: catalog, orders, inventory authority and asynchronous settlement
-
-This example lives in the Examples hub: [`docs/examples/cf-primitives-commerce-inventory.md`](../../examples/cf-primitives-commerce-inventory.md). The Builder-safe catalog is [`docs/examples/builtin-commerce.md`](../../examples/builtin-commerce.md).
-
-## Source
-
-- [`docs/examples/cf-primitives-commerce-inventory.md`](../../examples/cf-primitives-commerce-inventory.md)
-- [`docs/examples/builtin-commerce.md`](../../examples/builtin-commerce.md)

package/docs/handbook/examples/commerce.md

@@ -1,11 +0,0 @@
----
-description: Redirects to the builtin commerce catalog example in the Examples hub.
----
-# Commerce catalog and orders
-
-This example lives in the Examples hub: [`docs/examples/builtin-commerce.md`](../../examples/builtin-commerce.md). Stock authority and settlement are [`docs/examples/cf-primitives-commerce-inventory.md`](../../examples/cf-primitives-commerce-inventory.md).
-
-## Source
-
-- [`docs/examples/builtin-commerce.md`](../../examples/builtin-commerce.md)
-- [`docs/examples/cf-primitives-commerce-inventory.md`](../../examples/cf-primitives-commerce-inventory.md)

package/docs/handbook/examples/guarded-api.md

@@ -1,10 +0,0 @@
----
-description: Redirects to the guarded API example in the Examples hub.
----
-# Guarded API access: API keys, scopes and entitlement
-
-This example lives in the Examples hub: [`docs/examples/cf-primitives-guarded-api.md`](../../examples/cf-primitives-guarded-api.md).
-
-## Source
-
-- [`docs/examples/cf-primitives-guarded-api.md`](../../examples/cf-primitives-guarded-api.md)

package/docs/handbook/examples/intake-form.md

@@ -1,12 +0,0 @@
----
-description: Redirects to the builtin public intake form in the Examples hub.
----
-# Intake form
-
-This example lives in the Examples hub: [`docs/examples/builtin-intake.md`](../../examples/builtin-intake.md). Turnstile and email hooks are [`docs/examples/cf-primitives-intake-hooks.md`](../../examples/cf-primitives-intake-hooks.md).
-
-## Source
-
-- [`docs/examples/builtin-intake.md`](../../examples/builtin-intake.md)
-- [`docs/examples/cf-primitives-intake-hooks.md`](../../examples/cf-primitives-intake-hooks.md)
-- [`docs/examples/README.md`](../../examples/README.md)

package/docs/handbook/examples/intake-hooks.md

@@ -1,11 +0,0 @@
----
-description: Redirects to the Turnstile and email intake hooks in the Examples hub.
----
-# Intake form with bot check and notification
-
-This example lives in the Examples hub: [`docs/examples/cf-primitives-intake-hooks.md`](../../examples/cf-primitives-intake-hooks.md). The Builder-safe Manifest is [`docs/examples/builtin-intake.md`](../../examples/builtin-intake.md).
-
-## Source
-
-- [`docs/examples/cf-primitives-intake-hooks.md`](../../examples/cf-primitives-intake-hooks.md)
-- [`docs/examples/builtin-intake.md`](../../examples/builtin-intake.md)

package/docs/handbook/examples/legal-documents.md

@@ -1,10 +0,0 @@
----
-description: Redirects to the builtin legal documents example in the Examples hub.
----
-# Legal documents and consent
-
-This example lives in the Examples hub: [`docs/examples/builtin-legal-documents.md`](../../examples/builtin-legal-documents.md).
-
-## Source
-
-- [`docs/examples/builtin-legal-documents.md`](../../examples/builtin-legal-documents.md)

package/docs/handbook/examples/procurement-approvals.md

@@ -1,10 +0,0 @@
----
-description: Redirects to the builtin procurement example in the Examples hub.
----
-# Procurement approvals with member and staff roles
-
-This example lives in the Examples hub: [`docs/examples/builtin-procurement.md`](../../examples/builtin-procurement.md).
-
-## Source
-
-- [`docs/examples/builtin-procurement.md`](../../examples/builtin-procurement.md)

package/docs/handbook/examples/publication.md

@@ -1,10 +0,0 @@
----
-description: Redirects to the builtin publication example in the Examples hub.
----
-# Publication: localized posts with a public list
-
-This example lives in the Examples hub: [`docs/examples/builtin-publication.md`](../../examples/builtin-publication.md).
-
-## Source
-
-- [`docs/examples/builtin-publication.md`](../../examples/builtin-publication.md)

package/docs/handbook/examples/reservation.md

@@ -1,10 +0,0 @@
----
-description: Redirects to the builtin reservation example in the Examples hub.
----
-# Reservation requests
-
-This example lives in the Examples hub: [`docs/examples/builtin-reservation.md`](../../examples/builtin-reservation.md).
-
-## Source
-
-- [`docs/examples/builtin-reservation.md`](../../examples/builtin-reservation.md)

package/docs/handbook/start/quickstart-admin.md

@@ -1,52 +0,0 @@
----
-description: "Open local Admin in one shot: follow the official OTP example, bind ASSETS, sign in with email OTP from wrangler logs, land in the Dev UI."
----
-# Quickstart: local Admin
-
-New generated CF and Sites apps include Admin by default. To leave it out,
-select smaller features explicitly. This tutorial shows the existing
-direct-authored Worker integration with local email OTP; use it when you own
-the Worker entry. [Project layout and CLI](./project-and-cli.md) describes the
-new generated path.
-
-The procedural source of truth is the official example:
-
-**[`docs/examples/host-local-admin-otp/README.md`](../../examples/host-local-admin-otp/README.md)**
-
-Copy that directory outside the SDK checkout (or author the same files from
-it). Interview the human for one value before writing files: the bootstrap
-owner email. The example uses `owner@example.com`. Then:
-
-```sh
-pnpm install && pnpm generate && pnpm dev
-```
-
-Open the wrangler Ready-on URL (`http://127.0.0.1:8787/admin/sign-in`), submit
-the owner email, and read the OTP from wrangler logs. `mantle generate` syncs
-the prebuilt Admin SPA; do not Vite-build Admin.
-
-Traps (documented on the example):
-
-- Prefer `127.0.0.1` over `localhost` (`INVALID_ORIGIN`).
-- `pnpm check` / smoke rewrites `.dev.vars` to a smoke-only port — restore it
-  from `.dev.vars.example` before `pnpm dev`.
-
-Pin every selected `@aotter/mantle*` package to the same exact version; see
-[Versions](../reference/surface.md#versions). Admin needs both
-`@aotter/mantle-admin` and `@aotter/mantle-admin-ui`, wrangler `ASSETS` on
-`./public`, and `createAuth` email-otp + `ConsoleEmailSender`.
-
-## Next steps
-
-- [Project layout and the CLI loop](./project-and-cli.md) — the files you own, every CLI flag, the daily check loop, ASSETS as a hard Admin requirement.
-- [Authentication](../cloudflare/authentication.md) — production senders, GitHub / hosted modes, roles.
-- [The conventional Worker](../cloudflare/conventional-worker.md) — handlers and extra routes.
-- [Quickstart: a minimal Worker](./quickstart-worker.md) — API-only embed without Admin.
-
-## Source
-- [`docs/examples/host-local-admin-otp/README.md`](../../../docs/examples/host-local-admin-otp/README.md)
-- [`docs/examples/host-local-admin-otp/package.json`](../../../docs/examples/host-local-admin-otp/package.json)
-- [`docs/examples/host-local-admin-otp/src/index.ts`](../../../docs/examples/host-local-admin-otp/src/index.ts)
-- [`docs/examples/host-local-admin-otp/wrangler.jsonc`](../../../docs/examples/host-local-admin-otp/wrangler.jsonc)
-- [`docs/examples/host-local-admin-otp/.dev.vars.example`](../../../docs/examples/host-local-admin-otp/.dev.vars.example)
-- [`docs/examples/host-local-admin-otp/smoke.mjs`](../../../docs/examples/host-local-admin-otp/smoke.mjs)

package/docs/labels.md

@@ -1,71 +0,0 @@
-# GitHub labels
-
-Labels keep issues and PRs sortable for humans and cold-start AI agents. Apply the smallest useful set: one kind label, one or more area labels, and any gate labels that change review requirements.
-
-## Kind and status
-
-| Label | Meaning | Who applies | Remove when |
-|---|---|---|---|
-| `bug` | Broken, surprising, unsafe, or regressed behavior. | Reporter or triager. | The issue is reclassified. |
-| `enhancement` | New capability, behavior, or process improvement. | Reporter or triager. | The issue is reclassified. |
-| `documentation` | Docs-only change or docs gap. | Reporter, triager, or PR author. | The issue is reclassified. |
-| `question` | Needs an answer or convergence before action. | Reporter or triager. | The answer is captured or the issue is converted. |
-| `good first issue` | Suitable for a new contributor with repo docs only. | Maintainer. | Scope grows or hidden context is required. |
-| `help wanted` | Maintainers want external help. | Maintainer. | No longer seeking help. |
-| `duplicate` | Same work exists elsewhere. | Triager. | Usually never; close with link. |
-| `invalid` | Not actionable for this repo. | Triager. | Usually never; close with reason. |
-| `wontfix` | Valid but intentionally not planned. | Maintainer. | Usually never; close with reason. |
-| `epic` | Tracks a multi-issue initiative. | Maintainer. | The epic closes. |
-| `spike` | Exploratory work, not guaranteed to land. | Triager or maintainer. | The work becomes a concrete proposal or implementation issue. |
-
-## Area
-
-Use at least one `area:*` label when the affected surface is known.
-
-For package README or package-local docs changes, prefer the package area label (`area:spec`, `area:runtime`, `area:cf`, or `area:admin-ui`). Use `area:docs` for repo-wide docs, governance, ADRs, release docs, root README content, and cross-cutting documentation work.
-
-| Label | Meaning |
-|---|---|
-| `area:runtime` | `packages/mantle-runtime` behavior, ports, use cases, dispatcher, and MCP runtime. |
-| `area:spec` | `packages/mantle-spec`, manifest parsing, validation, diagnostics, CLI, spec types. |
-| `area:cf` | `packages/adapters/cloudflare`, Workers adapter, D1/KV/ASSETS wiring, Cloudflare deploy behavior. |
-| `area:skills` | `skills/*` agent briefs and install/extend/provision workflows. |
-| `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. |
-| `area:starters` | **Legacy only.** Retired `aotter/mantle-starters` source and migration notes. Do not use for new Core work. |
-
-## Release and review gates
-
-| Label | Meaning | Review consequence | Remove when |
-|---|---|---|---|
-| `release-gate` | Blocks a public release or release-quality claim. | Must be resolved or explicitly deferred before release. | The gate is closed or deferred by maintainer decision. |
-| `v0.1.0` | Required for the v0.1.0 release gate. | Track in the v0.1.0 release pass. | The item lands or is moved out of v0.1.0. |
-| `breaking-change` | Semver-relevant breaking change. | Generated release notes must call it out. | The change is redesigned to be non-breaking. |
-| `skip-release-notes` | Release bookkeeping with no user-facing change. | Excluded from generated GitHub Release notes. | The PR contains a user-facing change. |
-| `needs-adr` | Architecture, trust boundary, package boundary, or long-lived decision needs an ADR or ADR-lite proposal. | Do not merge implementation until the decision is captured. | ADR/proposal lands or maintainer confirms an existing ADR covers it. |
-| `needs-grammar-revise` | Manifest grammar or closed-enum change. | Requires grammar-revise round before code/types change. | Grammar decision lands or the change no longer affects grammar. |
-| `needs-discussion` | Not converged enough for implementation. | Do not start coding from this issue. | Closing criteria are met and scope is concrete. |
-
-## Creating missing labels
-
-Use these commands from a checked-out repo:
-
-```bash
-gh label create "area:runtime" --description "Runtime package, ports, use cases, dispatcher, render, MCP runtime" --color "1d76db"
-gh label create "area:spec" --description "Spec package, manifest parsing, validation, diagnostics, CLI, types" --color "1d76db"
-gh label create "area:cf" --description "Cloudflare Workers adapter and bindings" --color "1d76db"
-gh label create "area:skills" --description "Agent Skills and install/extend/provision workflows" --color "1d76db"
-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 "area:starters" --description "Legacy only: retired mantle-starters source and migration" --color "cfd3d7"
-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"
-gh label create "needs-grammar-revise" --description "Requires manifest grammar review before implementation" --color "d93f0b"
-gh label create "needs-discussion" --description "Not converged enough for implementation" --color "fbca04"
-gh label create "spike" --description "Exploratory work, not guaranteed to land" --color "bfdadc"
-```

package/docs/media-uploads.md

@@ -1,5 +0,0 @@
-# Media uploads
-
-This guide moved into the handbook: [`docs/handbook/cloudflare/media-r2.md`](handbook/cloudflare/media-r2.md).
-
-The handbook ships inside the `@aotter/mantle` package under `node_modules/@aotter/mantle/docs/handbook/` and describes the installed release.

package/docs/migration-0.1.2.md

@@ -1,13 +0,0 @@
-# Upgrading to 0.1.2
-
-0.1.2 is the first stable release and the first public one. There is no earlier
-stable to upgrade from and no migration to perform.
-
-What it contains, what it requires and what it does not yet cover is in
-[Releases](handbook/releases/index.md).
-
-Every version before 0.1.2 was an internal prerelease. If you are holding a
-database created by one of those, `LEGACY_STORAGE_RESET_REQUIRED` means it
-predates native Schema tables: rebuild it rather than migrating it. Move any
-data you need out of Mantle by hand first — there is no product migration for
-that unreleased storage format.

package/docs/performance-harness.md

@@ -1,228 +0,0 @@
-# Data access, cache policy, and performance harness
-
-Mantle site code declares intent; Core owns the shared storage layout and the
-Cloudflare adapter owns provider bindings. A site-building agent should not
-need Mantle table names, generated-column names, KV prefixes, or D1 APIs to
-make a normal content/API/page change.
-
-## Ownership
-
-| Read or state | Owner | Notes |
-|---|---|---|
-| Entry get/list and public slug/data-field/published reads | `DatabaseEntryRepository` through `EntryRepository` / `EntryReader` | Schema-aware field resolution is shared here. |
-| Manifest View execution | `ExecuteViewUseCase` + prepared `ViewQueryExecutor` | Core owns authorization and request validation; selected storage lowers queries once and resolves declared Schema indexes. |
-| Editable settings and code-owned locale/media policy | `DatabaseSiteConfigRepository` | Editable values and dynamic media tool policy are read fresh; boot-seeded locale policy may be memoized within the runtime instance. |
-| Pending media uploads | `DatabasePendingUploadRepository` | Canonical, read-after-write D1 state; never publish-cache state. |
-| Rendered HTML, Markdown, and `llms.txt` | Request-time render use cases plus the Cloudflare public-route cache policy | D1 is canonical; version-local Workers Cache stores anonymous HTTP responses. |
-| D1 transport and optional query metrics | Cloudflare bindings | Bindings stay thin. Query/cache policy does not belong in a generic provider `BaseRepository`. |
-
-The runtime exposes no raw database handle. Application and adapter code uses
-the sealed plan, runtime use cases, `entries`, and `siteConfig`. An application may own
-additional tables behind its own repository at the composition root, but it
-must not query Mantle-owned tables outside the selected storage adapter.
-
-## Cache contract
-
-- D1 is canonical for entries, site settings, media metadata, and pending
-  uploads. Core stores no rendered artifact copies.
-- Public routes render canonical state and return
-  `Cache-Control: public, max-age=0, s-maxage=300`.
-- Cloudflare Workers Cache checks eligible anonymous responses before invoking
-  the Worker. Cache keys are version-local, so a deploy starts with no stale
-  response from the previous Worker version.
-- Successful publishing-content and site-setting writes purge the shared
-  deployment-scoped public Cache-Tag through Cloudflare's native cache API. Operational
-  records and immutable assets stay outside that invalidation boundary.
-- Do not cache every repository read. Cross-isolate correctness for editable
-  data wins unless a read has a measured hot-path contract and explicit
-  invalidation.
-
-## Index coverage
-
-The Node harness uses the real canonical migrations, generated Schema DDL,
-real View compiler, deterministic skewed rows, and SQLite
-`EXPLAIN QUERY PLAN`:
-
-```bash
-pnpm exec mantle-harness indexes --manifests ./manifests --format text
-pnpm exec mantle-harness indexes --require-public --format json
-pnpm exec mantle-harness indexes --require account-members --format json
-```
-
-Without `--require-public` or `--require`, findings are advisory. A required
-path fails on a required Schema-table scan, a temporary ORDER BY B-tree, or a
-data-field predicate/order that does not use a declared Schema index.
-Projection alone does not require an index. `mantle validate` remains a pure
-correctness check; no performance grammar or manifest atom was added.
-
-The fixture follows each Schema lifecycle: operational rows are immediately
-published, while publishing Schemas contain both draft and published rows. The
-harness deliberately does not run `ANALYZE` or `PRAGMA optimize`, so it cannot
-turn an unprepared production plan into a local pass. This is a conservative
-SQLite preflight, not proof of D1 rows-read, Worker CPU, or IndexedDB behavior;
-measure those on the target backend before making a performance claim.
-
-Use the machine report in CI. It includes the compiled SQL and parameters,
-query-plan details, named indexes, scan/sort flags, result count, SQLite
-version, fixture row count, and required-failure summary.
-
-## Worker/API/page sampling
-
-Sample any running environment with the public HTTP helper:
-
-```bash
-pnpm exec mantle-harness http \
-  --base-url http://127.0.0.1:8787 \
-  --route recent=/api/views/recent-posts \
-  --route page=/en/posts/hello \
-  --rounds 20 --warmup 2 --format json
-```
-
-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.
-
-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
-
-Measured on the deterministic 2026-08-01 Wrangler-local fixture; timings are
-diagnostic, while query/row counts are the stable assertions.
-
-| Finding | Disposition |
-|---|---|
-| 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 Schema indexes | Fixed by the shared schema-aware entry-read boundary over native columns. A 10,000-row page MISS measured 2 queries / 5 rows read. |
-| 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. |
-| Benchmark stops at fake in-process dispatch | Fixed by the Node planner and Wrangler-local Worker/API/page layers. The old dispatch microbenchmark remains a narrow CPU signal only. |
-
-The retained OFFSET and substring-search trade-offs are visible exceptions,
-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/adr-lite-812-native-parity.md).