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

package/docs/adr/0038-bun-native-host.md

@@ -1,63 +0,0 @@
-# ADR-0038: Bun is a native host
-
-**Status:** Accepted for 0.2.0. Amends ADR-0036's reserved Bun host.
-
-## Decision
-
-`@aotter/mantle/bun` owns native drivers and Admin files. Core remains host-neutral;
-PostgreSQL retains policy, convergence, SQL printing, SERIALIZABLE retries, timeout
-and error mapping. `host: bun` defaults to `dialect: postgres` on first selection.
-The CLI writes an application-owned Bun.serve entry and service once. Both native
-PostgreSQL and bun:sqlite presets exist; neither imports Cloudflare or pg.
-
-The PostgreSQL host takes a Bun.SQL pool configured with `prepare: false`.
-Bun's prepared JSON parameter encoding serializes an already encoded JSON string
-again. Refuse another configuration rather than silently changing stored values.
-Pool reserve/release binds every operation to one connection. The host closes
-its pool after the server and retained background work stop.
-
-Bun exposes raw results without OIDs/typmods. Obtain exact result metadata from
-`CREATE TEMP TABLE ... AS <query> WITH NO DATA`, read pg_attribute and drop the
-temporary table, then execute the original statement once with raw text results.
-A DML description is a data-modifying CTE under WITH NO DATA, which does not
-execute its body. PostgreSQL owns all type inference, including numeric scale,
-CASE, COALESCE and CTEs. Each descriptor runs in the statement's existing pinned
-transaction. Views use a regular transaction because temporary DDL is forbidden
-in READ ONLY: a read describes first, then runs `SET TRANSACTION READ ONLY` before
-the statement, so the engine still refuses a write as it does on every other
-PostgreSQL host. Creating the temporary table needs the TEMPORARY privilege on the
-database (`GRANT TEMPORARY ON DATABASE ... TO <role>`); without it every read fails
-with 42501 naming this requirement, and a read replica cannot serve this host.
-Every transaction appends `pg_temp` to its search_path, on every PostgreSQL host,
-so a temporary table on a pooled session never stands in for a Schema table (unless
-the role's own search_path already names pg_temp earlier, which it should not).
-A connection whose ROLLBACK failed is closed, never released to the pool.
-This costs three metadata round trips per result. Replace it only when Bun
-provides public RowDescription metadata; do not approximate money or time values.
-
-The entry overwrites the trusted IP header from the socket; behind a reverse proxy
-listed in TRUSTED_PROXIES, the client is the address that proxy appended last to
-X-Forwarded-For (one trusted hop; an IPv4-mapped socket address is matched as
-IPv4), so each client keeps its own sign-in rate limit. Bun.serve runs
-with `development: false` and an error handler that answers Core's 500 envelope: Bun's
-development page would show the exception, stack and paths. Admin assets reject
-traversal, control characters and symlinks outside the installed bundle.
-bun:sqlite runs with foreign keys on, as D1 does, and a Mantle batch waits for a
-Better Auth transaction open on the same handle instead of becoming its savepoint.
-Local OTP requires an explicit loopback PUBLIC_ORIGIN, a secret and bootstrap
-email, as Cloudflare does.
-
-Bun has no built-in cron scheduler in this preset. Enabled schedule Triggers are
-refused before files are written; an application that supplies a scheduler uses
-host none and invokes Mantle's schedule ingress explicitly. No polling scheduler,
-workflow engine or new manifest grammar is introduced.
-
-## Verification
-
-Native PostgreSQL and SQLite run the same storage conformance suite. Native
-regressions cover result names, JSON scalar/array values, exact numeric typmods,
-microsecond timestamps, CTE/comment queries, star targets, connection
-reservation, read-only reads, statement_timeout, pg_temp ordering, foreign keys,
-transactions on a shared bun:sqlite handle and actual Better Auth
-OTP/bootstrap-owner login on both engines. Both generated presets typecheck
-against bun-types. CI installs pinned Bun and runs these on every PR.

package/docs/adr/README.md

@@ -1,96 +0,0 @@
-# Architecture Decision Records
-
-Records of *why* mantle ended up shaped this way. The numbering preserves POC ADR numbers where carried over (so cross-references in code comments and external docs stay valid); new ADRs continue from the highest used number.
-
-## ADRs
-
-| # | Title | Status |
-|---|---|---|
-| [0001](0001-four-atom-manifest-model.md) | Four-atom manifest model (Schema / View / Procedure / Trigger). Folds POC ADR-0005 (grammar discipline) and POC ADR-0006 (multi-doc YAML). | Accepted; fixed-file contract superseded |
-| [0002](0002-closed-enums-for-bindings.md) | Closed enums for `x-mantle-bind` and `ctx.*` predicates. | Accepted (refreshed) |
-| [0007](0007-ai-as-primary-author.md) | AI is the primary author of consumer projects; SDK contract is three pre-serve feedback loops, runtime diagnostics, and coder/operator role surfaces. | Accepted + amended |
-| [0008](0008-structured-diagnostic-shape.md) | Diagnostic shape for validate/boot/runtime failures, with a reserved consumer-test phase; measured harnesses keep purpose-shaped reports. | Accepted + amended |
-| [0009](0009-consumer-supplied-manifests.md) | Historical generated-array workflow; consumer source ownership continues in ADR-0019. | Superseded by 0019 |
-| [0010](0010-locale-and-translates.md) | Locale 3-layer (manifest / D1 site_config / data field) + translates pattern. Boot decoupled from `site_config` (issue #60 fix). | Accepted (refreshed) |
-| [0011](0011-adapter-port-spec.md) | Adapter port spec. Required runtime ports plus optional feature ports. | Superseded by 0019 (Core storage, Admin composition) and 0024 (SQLite/D1 storage); retained as the alpha.7 Cloudflare adapter record |
-| [0012](0012-views-as-public-rest.md) | Views auto-expose matching REST and `query_view_*` MCP reads on their declared `public` or `staff` surface. Schemas never get a public REST endpoint. | Accepted + amended |
-| [0013](0013-agent-provisioned-consumer-projects.md) | Historical agent-provisioned consumer projects path. | Superseded by 0021 |
-| [0014](0014-auth-better-auth-and-multi-tenant-mcp.md) | The Cloudflare adapter owns one Better Auth 1.7 identity/OAuth/MCP authority with native method options and CIMD discovery. Verified callers are normalized into runtime context; mutable staff role and target authorization are re-evaluated per call. | Accepted + amended; auth ownership amended by 0032 |
-| [0016](0016-site-semantic-layer.md) | Historical Starter/Landing `AGENTS.md` and launch-state contract. | Superseded by 0021 |
-| [0017](0017-media-multi-variant-agent-side-optimization.md) | Multi-variant media assets with agent-side optimization and asset-id entry references. | Accepted |
-| [0018](0018-core-starters-repository-boundary.md) | Core produces published SDK artifacts; the separate starters repository validates them as an external consumer. Revisit after release-contract simplification. | Superseded by 0021 |
-| [0019](0019-sealed-manifest-runtime-pipeline.md) | One sealed source-to-runtime pipeline, semantic storage seam, and optional Web/Admin/platform dependency direction. | Accepted; optional boundaries become subpaths of two packages per 0032 |
-| [0020](0020-builtin-handler-contracts-and-matched-upsert.md) | Static builtin handler contracts and natural-key matched upsert (`handler.match`). | Accepted + amended by 0022 |
-| [0021](0021-retire-starter-scaffolding.md) | Direct authoring; retire Starter scaffolding. | Accepted; no-initialization clause superseded by 0026 |
-| [0022](0022-caller-observed-version-occ.md) | Caller-observed `expectedVersion` for Admin bind and builtin upsert OCC. | Accepted; Admin binding rules superseded by 0029 |
-| [0023](0023-port-failure-contract.md) | Storage and service failure contracts: resource, rate, outcome-unknown, partial-failure and precondition diagnostics with safe `failure` facts. | Accepted for alpha.17 (#857); amends 0008 |
-| [0024](0024-manifest-native-schema-tables.md) | Materialize each Schema as a native storage table and deploy reviewed migration artifacts. | Accepted; authored-native-name clauses superseded by 0025; migration workflow superseded by 0033 |
-| [0025](0025-reserved-native-columns-and-published-only-public-views.md) | Reserve the six native column names, let `indexes` reference them, and compile public publishing Views published-only. | Accepted |
-| [0026](0026-progressive-generate.md) | Progressive `mantle generate` with a full default, positive features, saved host selection, and user-owned source. | Accepted; supersedes part of 0021; dependency closure, identity and `--host` amended by 0032 |
-| [0027](0027-scheduled-procedure-triggers.md) | Schedule Triggers in the sealed plan with Cloudflare-hosted invocation and system identity. | Accepted for 0.1.5; cron dialect and host requirement amended by 0032 |
-| [0028](0028-schema-ttl-expiry.md) | Logical TTL on Schema reads with preview-first, explicit bounded cleanup. | Accepted for 0.1.5 |
-| [0029](0029-mcp-apps-interaction-contracts.md) | Official MCP SDK for all MCP wire handling; transport-neutral capability catalog with validate-once invocation; `@aotter/mantle-mcp` and `@aotter/mantle-ui`; Manifest-declared interaction contracts and MCP Apps (#1110). | Accepted; amends ADR-lite 909 |
-| [0030](0030-store.md) | Store: one persistence object (`ctx.store` / `runtime.store`) over one relational JSON query AST compiled by each adapter; first slice `select`, `view`, `id`, then `write`, then manifest grammar (#1151). | Accepted; completed for 0.2.0 by 0032; authoring amended by 0034 |
-| [0031](0031-host-cloud-core-contract.md) | Cloud supplies the Core pin before host artifact hashing; protocol 2 checks the pin through grants/kit; protocol 4 requires a verified source receipt before save. | Accepted |
-| [0032](0032-store-centric-core-and-service-contract.md) | 0.2.0: Store is the only entry persistence path; an application-owned service behind one host-neutral `createMantle`; one `Caller` identity and no Core-owned user or auth; `_mantle_` marks system tables only; two npm packages and one plugin. | Accepted for 0.2.0; decisions 1–5, 10 and 13 amended by 0034; decisions 6 and 12 by 0035 |
-| [0033](0033-storage-converges-to-the-plan.md) | Schema storage converges to the plan by introspection: Mantle applies safe additions, blocks the rest, and verifies author-made changes; no Mantle-written migration files. | Accepted for 0.2.0; amended by 0034 and 0035 |
-| [0034](0034-store-is-authored-as-sql.md) | Store is authored as SQL in the D1 dialect and compiled to IR by the CLI with `libpg-query`; no Worker parses SQL. The IR is the parser's AST under an exact allowlist, printed by `pgsql-deparser`; a chosen SQL subset with policy wrapped around every Schema reference; FTS5 search and R*Tree places; after hooks take row arrays; one SQLite executor; exact encodings for time and decimals. | Accepted for 0.2.0 (spike #1203); amended by 0035 and 0037 |
-| [0035](0035-sql-dialects.md) | Mantle SQL is PostgreSQL syntax and meaning; a dialect module runs it on one engine. D1 and PostgreSQL ship built in, and both pass the compliance suite. | Accepted for 0.2.0; amended by the PostgreSQL dialect (#1293), 0036 and 0037 |
-| [0036](0036-host-and-dialect.md) | A project picks a host (`cloudflare`, `none`) and a dialect (`sqlite`, `postgres`, a package) once; `mantle generate` writes the pair's preset; the host never enters the plan. | Accepted for 0.2.0; reserved Bun host amended by 0038 |
-| [0037](0037-postgresql-is-the-reference-dialect.md) | PostgreSQL is the reference dialect: one closed allowlist in Core (base and reference profiles), D1 runs the base subset; a View reads an internal View; `restrict` narrows at runtime; a statement timeout on PostgreSQL; Cloud's PostgreSQL connection stays with the platform. | Accepted for 0.2.0 |
-| [0038](0038-bun-native-host.md) | Bun is a native host: `@aotter/mantle/bun` owns the native SQLite and PostgreSQL drivers and Admin files; `host: bun` defaults to `dialect: postgres`; the CLI writes a `Bun.serve` entry once. | Accepted for 0.2.0 |
-
-## Reading order
-
-If you're new to the codebase:
-
-1. **0001** — what the 4 atoms are.
-2. **0019** — the sealed source-to-runtime pipeline and optional product boundaries.
-3. **0009** — historical context for consumer-owned manifests.
-4. **0007** — what running the SDK feels like as an AI author (and as the operator agent).
-5. **0011** — the boundary between the runtime and the adapter.
-6. **0010** — how locale flows through the system.
-7. **0026** — current progressive generation boundary; **0021** retains the direct-authoring history and **0013** is historical install-session context.
-8. **0002, 0008** — the two ADRs that touch every diagnostic and every binding.
-
-## What's NOT here (and why)
-
-POC had 16 ADRs. The rebuild ports the durable ones, writes fresh ADRs
-for new v0.1.0 boundaries, and folds / drops the rest:
-
-- **POC ADR-0003** OpenAPI emission → folded into `mantle-spec` README (the *what* is implementation; the *why* was already captured by ADR-0001's grammar lock).
-- **POC ADR-0004** D1 today, Hyperdrive PG tomorrow → folded into `mantle-cloudflare` README (now a v0.2 roadmap item, not an architectural decision).
-- **POC ADR-0005** v0.1 minimum grammar → folded into ADR-0001's fail-closed grammar policy.
-- **POC ADR-0006** multi-doc YAML → folded into ADR-0001 §"Authoring shape: multi-doc YAML."
-- **POC ADR-0011** lifecycle binary opt-in → distilled to a §"Lifecycle" subsection in `docs/design-atoms.md`. v0.1.0 ships `publishing` and `operational`.
-- **POC ADR-0012** strategic posture vs adjacent CMS designs → strategic / marketing material, lives in `README.md` if anywhere.
-- **POC ADR-0013** role-split surfaces (coder agent vs operator agent) → folded into ADR-0007 (Part B).
-- **POC ADR-0014** builtin handlers and lifecycle Triggers → promoted to v0.1.0 and implemented in the rebuild via `LifecycleHookingEntryRepository` and `InvokeBuiltinUseCase`. Full shape spec lives in `docs/design-atoms.md`.
-- **POC ADR-0015** cms-astro internal seam discipline → POC-specific to a package that no longer exists; replaced by ADR-0011 (adapter port spec).
-- **POC ADR-0029** drop Astro from cms-cloudflare → POC-specific historical record; the rebuild starts post-Astro.
-
-The rebuild's ADR-0011 (new) is the most load-bearing addition — the POC accumulated multiple *aspirational* boundaries (POC ADR-0015 was one; references in CLAUDE.md were another) without a single normative spec. ADR-0011 makes the boundary explicit and reviewable. ADR-0012 and ADR-0013 capture newer v0.1.0 product/runtime seams that were not present in the POC.
-
-## Contributing a new ADR
-
-1. Pick the next unused number after the highest existing ADR.
-2. File: `docs/adr/<NNNN>-<kebab-title>.md`.
-3. Sections: Status, Date, Context, Decision, Consequences, Alternatives, How to apply, Implementation status.
-4. Link from this README's table.
-5. Land it in a PR alongside (or before) the implementation it documents — ADR-as-design-artifact, not ADR-as-archaeology.
-
-## ADR-lite records
-
-These retain their issue-based filenames and original decision status.
-
-| Record | Status |
-|---|---|
-| [#803 Request diagnostics](adr-lite-803-request-diagnostics.md) | Implemented |
-| [#808 Route readiness](adr-lite-808-route-readiness.md) | Accepted |
-| [#809 Bounded public content](adr-lite-809-bounded-public-content.md) | Implemented |
-| [#812 Native parity](adr-lite-812-native-parity.md) | Implemented; deployment evidence linked in record |
-| [#823 Home statistics](adr-lite-823-home-statistics.md) | Proposed; unmerged demo |
-| [#842 MCP authoring](adr-lite-842-mcp-authoring.md) | Accepted |
-| [#845 Frontend client](adr-lite-845-frontend-client.md) | Accepted |
-| [#861 Admin WebMCP](adr-lite-861-admin-webmcp.md) | Accepted |
-| [909 Admin UI kit](adr-lite-909-admin-ui-kit.md) | Accepted; amended by 0029 |

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

@@ -1,38 +0,0 @@
-# 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/adr-lite-808-route-readiness.md

@@ -1,47 +0,0 @@
-# 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/adr-lite-809-bounded-public-content.md

@@ -1,71 +0,0 @@
-# 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 `Link: rel="next"` and map cursors to URLs. Web passes `nextPageUrl` to
-the list template; the host renders accessible navigation with its own language
-and design. The adapter does not rewrite template HTML. Existing templates must
-adopt this field to retain visible continuation. Web-owned llms composition
-retains its body link. 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/adr-lite-812-native-parity.md

@@ -1,150 +0,0 @@
-# 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. Each Schema is a
-native table, so the axis is not a claim that 1,000 simultaneous Schema tables
-are an advisable production design. 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/adr-lite-823-home-statistics.md

@@ -1,64 +0,0 @@
-# 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. Each native Schema table carries `_mantle_created_at` and its own
-creation index. The range branch searches that index, and the total branch
-counts index entries. Other field columns stay 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/adr/adr-lite-842-mcp-authoring.md

@@ -1,30 +0,0 @@
-# ADR-lite #842: Applicable generic MCP authoring
-
-Status: Accepted for implementation following maintainer approval.
-
-The staff catalog and dispatcher remain shared by remote MCP and Admin
-WebMCP (ADR-0014, ADR-0019, ADR-lite-861). No new manifest switch or tool
-registry is introduced. Adapters retain current staff-role verification;
-declared Procedures and Views retain their own authorization and guards.
-
-Generic lifecycle tools are offered only when at least one writable content
-Schema exists. Delete is offered only when a writable Schema exists. Read
-tools list actual collection names, lifecycle, searchable and sortable fields.
-Root readOnly remains the existing way to require Procedure-owned writes;
-declaring a Procedure alone does not disable normal authoring.
-
-Discovery is not enforcement: the dispatcher rejects absent catalog names,
-checks the target row for readOnly and lifecycle suitability, and binds
-per-collection updates to their declared collection before mutation. Unsupported
-lifecycle calls return CONFLICT with an explicit reason; wrong-collection IDs
-return NOT_FOUND. Existing status/OCC checks remain in the use cases.
-Generic staff tools also apply Admin's rank table at `tools/call`:
-contributor may create/update drafts; editor+ is required for lifecycle,
-delete, media, and operational record tools. Declared Procedures keep their
-own `requires` predicates. `tools/list` may still show editor tools to
-contributors; a guessed call is `AUTH_DENIED`.
-
-Compatibility: operational-only and read-only sites lose unusable generic
-tools. Clients must rediscover tools rather than retaining a global tool list.
-Mixed sites must choose a collection listed in the tool description. Public
-catalogs remain only declared capabilities and gain no collection metadata.

package/docs/adr/adr-lite-845-frontend-client.md

@@ -1,38 +0,0 @@
-# ADR-lite #845: frontend calls use the existing HTTP Trigger contract
-
-Status: Accepted for implementation under #845 and mantle-home #86.
-
-`mantle-web/client` is a browser-safe fetch client for declared public Views and
-HTTP Triggers. `mantle-web/client-runtime` projects that contract from the sealed
-RuntimePlan and binds the same client to `createMantleRequestHandler`, with a
-request-local principal. Local SSR makes no network call and invokes no internal
-EntryReader. Calls retain Trigger identity. No manifest grammar changes.
-
-The public contract uses wire names, input/output schemas and the plan fingerprint.
-View rows remain records: the existing View API does not promise a generated row
-schema. The generic response shape includes rows/page/show/hasMore. This is not a
-new generator or validation engine; Runtime still validates and authorizes.
-
-Remote callers inject fetch and a request-local token resolver. Clients never
-retry a mutation or follow redirects with credentials. Business diagnostics and
-OAuth challenge remain available in MantleClientError; network and abort errors
-remain native errors. The browser export imports no runtime or storage module.
-
-Cloudflare's opt-in frontendOrigins accepts exact origins for API CORS, exposes
-WWW-Authenticate and permits Authorization/Content-Type preflights. Cross-origin
-responses use no-store and do not enable cookie credentials. Cookie CSRF checks
-and configured bearer issuer/audience/scope checks remain the same. Host-owned
-OAuth/connection policy is independent of application revision. Existing Better
-Auth PKCE registration, consent and revocation remain the authority.
-
-In a provider composed with MCP, user grants for additional configured resources
-carry the same consent lineage and session binding as MCP grants. Verification
-reuses the current-consent/session check for those resources too; API JWTs cannot
-outlive revocation or become valid again on reconnect. OAuth discovery responses
-also receive the configured exact-origin CORS policy for public browser clients.
-
-Existing native public cache tags and purge handle same-Worker invalidation.
-External consumers start with private/no-store, or explicitly bound TTL; durable
-remote invalidation delivery remains the parent #792 contract and must be proven
-before advertising a stronger freshness guarantee. Cloud's integration includes
-the actual external consumer and browser evidence, not only this package change.