@aotter/mantle 0.1.0-alpha.9 → 0.1.2-alpha.2

package/docs/adr/0023-port-failure-contract.md

@@ -0,0 +1,69 @@
+# ADR-0023: Storage and service failure contracts
+
+Status: Accepted for alpha.17 under #857 (amends ADR-0008 and media deletion behavior).
+
+This is the diagnostic grammar-revise record: add RESOURCE_EXHAUSTED (507),
+RESOURCE_UNAVAILABLE (503), RATE_LIMITED (429), OUTCOME_UNKNOWN (503),
+PARTIAL_FAILURE (503), PRECONDITION_FAILED (412), and optional safe `failure`
+facts to Diagnostic. No Manifest keys, new ports, or parallel wire format.
+Existing codes and envelopes remain compatible. DiagnosticError accepts internal
+ErrorOptions.cause; causes never enter Diagnostic. Unexpected exceptions must not
+be copied into public messages. Core owns no tenant, plan or provider quota policy.
+
+## Contract
+
+A port rejects with DiagnosticError for recognized failures. The diagnostic
+contains stable code, safe message and optional failure facts: outcome is
+not-applied/partial/unknown; retry is never/after-change/safe/reconcile; resource
+is an optional non-sensitive logical resource name, not credentials or SQL.
+A provider adapter or host policy owns classification. Unknown errors stay
+unexpected; never guess quota from arbitrary exception prose. Existing specific
+validation, not-found and atomic OCC diagnostics remain authoritative.
+
+`safe` requires idempotence of the same operation against the same resource.
+It does not request automatic retry. Timeouts after write/send default to unknown
+outcome and reconciliation, not unconditional retry. Do not downgrade unknown
+outcome to not-applied merely because no reply arrived. Not-found on an
+idempotent object delete is success. Read absence may be null per the port.
+
+## Operation matrix (public contracts)
+
+| Contract | Success | Failure / effect / retry |
+| --- | --- | --- |
+| EntryReader / ViewQueryExecutor | documented rows/null/page | denied/unavailable/rate limit; reads have no business mutation; explicit retry after transient failure |
+| EntryRepository | semantic mutation with atomic expectedVersion | existing NOT_FOUND/CONFLICT; host capacity/denial; unknown write requires readback by stable id/version, never latest-version substitution |
+| SiteConfigRepository | validated settings/locale | reads as above; writes same conditional and uncertain-effect rules as entries |
+| MediaAssetRepository / PendingUploadRepository | metadata persisted/deleted | capacity/availability/unknown write; reconcile by asset/upload id; removal of missing metadata is idempotent where specified |
+| MantleStorageAdapter.prepare / migrations | ready prepared storage | invalid plan/readiness; completed migration steps may persist; journal/readback before retry, no cross-provider rollback promise |
+| DatabaseDriver | driver rows/batch result | constraint/precondition or recognized provider failure; transaction guarantees remain driver-specific; ambiguous writes require readback, SQL is never public |
+| MediaStorage.createUpload | authorized capabilities, not uploaded bytes | policy/size/denied/unavailable; adapter must state any reservations created; no general single-use guarantee |
+| MediaStorage.commitUpload | verified asset, then use case stores metadata | missing/type/size/precondition or partial/unknown provider effect; reconcile same upload group and objects before retry |
+| MediaStorage.deleteObject | object absent | idempotent same-key retry; unavailable/unknown; use case retains metadata if any variant fails and returns PARTIAL_FAILURE |
+| EmailSender | provider accepted, not guaranteed recipient delivery | known rejection not-applied; lost acknowledgement unknown/reconcile; do not resend automatically without provider idempotency/readback |
+| DeferredHookDispatcher | accepted for at-least-once delivery | ambiguous enqueue may duplicate; existing fallback preserves eventId + trigger idempotency identity; consumers must deduplicate |
+| HandlerRegistry / custom handler | application output | DiagnosticError/InvokeFailure preserved; unknown exceptions internal only; handler owns side-effect semantics |
+| Clock / IdGenerator | timestamp / unpredictable unique id | unexpected environmental/programming errors; never silently substitute insecure ids |
+| selected Auth contract (outside Runtime) | authentication/session/admin operation | preserve supported validation/denial; provider/email/storage failure handled at Auth adapter boundary; no assumption that Procedure catches Auth errors |
+
+HTTP and Admin use the existing central mapping; MCP retains the diagnostic
+code/failure facts rather than deriving application recovery from HTTP status.
+Admin OCC recovery applies to structured CONFLICT only, not all 409 responses.
+Unknown provider bodies, SQL and causes remain internal. Host-supplied messages
+and resource labels are explicitly public and must not include sensitive data.
+
+## Media partial deletion change
+
+Previously object errors were logged and the asset row removed. Now every
+variant deletion is attempted; any failure retains the row and returns partial
+failure. A retry deletes the same keys (including already absent objects), then
+removes metadata. If metadata deletion itself has an uncertain result, reconcile
+by asset id; no new object identities are created. No cross-store transaction is
+implied. Remaining metadata may reference already removed bytes during recovery.
+
+## Compatibility / verification
+
+New failure fields are additive; old consumers still have code/message. Media
+partial-delete clients now receive failure rather than misleading success.
+Focused tests cover diagnostic serialization, transport redaction, host rejection
+and retry of partial deletion. Concrete adapter conformance must preserve
+provider constraints and no automatic retry of uncertain writes/sends.

package/docs/adr/0024-manifest-native-schema-tables.md

@@ -0,0 +1,260 @@
+# ADR-0024: Materialize each Schema as a native storage table
+
+**Status:** Accepted
+
+**Date:** 2026-09-18
+
+**Related:** ADR-0010, ADR-0011, ADR-0019, ADR-0020, ADR-0022, ADR-0023
+
+## Context
+
+The SQLite adapter currently stores every Schema row in one `entries` table.
+Business fields live in a JSON `data` column. Schema indexes add generated
+columns and partial indexes to that shared table, and Schema-shaped SQL views
+project JSON fields back into columns.
+
+That layout made the first dynamic runtime small, but it is now the wrong
+authority for a manifest-built system:
+
+- a successfully built Manifest already fixes every Schema and field type;
+- generated columns for every historical indexed field accumulate on one
+  table, while D1 allows at most 100 columns per table;
+- native SQL, inspection, export, and migration tooling see an implementation
+  envelope instead of the authored data model;
+- application migrations and Mantle's canonical `entries` migrations form two
+  persistence systems;
+- the compatibility layer is now larger than direct table CRUD.
+
+Mantle has not shipped a stable storage format. Keeping the generic table for
+downward compatibility would create the dual path this change is intended to
+remove.
+
+## Decision
+
+### One physical table per Schema
+
+The SQLite/D1 storage adapter materializes every compiled Schema as a quoted
+native table. The table contains:
+
+- Mantle columns: `_mantle_id`, `_mantle_status`, `_mantle_version`,
+  `_mantle_created_at`, `_mantle_updated_at`, and `_mantle_author_id`;
+- one column for every top-level Schema property;
+- native indexes for every `indexes` and `uniqueIndexes` tuple.
+
+Single scalar JSON Schema types map to SQLite affinities: string to `TEXT`,
+integer and boolean to `INTEGER`, and number to `REAL`. Objects, arrays, unions,
+and otherwise polymorphic values use `TEXT` containing canonical JSON so a
+round trip cannot change their JSON type. Nullable values use SQL `NULL`.
+
+Business columns remain nullable at the database layer. Mantle allows an
+incomplete authoring draft; Runtime validation enforces required fields when a
+record becomes complete or when an operational Schema is written. An optional
+nullable property reads as `null` when its column is null. This is the v0.1
+native-table contract; it intentionally does not preserve a distinction
+between an absent optional nullable field and an explicit null.
+
+Schema names and field names remain authored wire names and are always SQL
+identifier quoted. A Schema table uses its authored Schema name. SQLite
+preparation rejects collisions with selected infrastructure tables or views,
+including auth tables; this check belongs to the concrete deployment because
+the portable Manifest cannot know which optional infrastructure a host binds.
+Internal Mantle tables and columns use the reserved `_mantle_` prefix. The
+prefix prevents Mantle metadata from stealing ordinary authored names such as
+`id`, `status`, or `createdAt`.
+
+The SQLite adapter no longer creates `entries`, generated field columns, or
+Schema projection views. There is no dual write, compatibility view, or
+fallback JSON repository.
+
+### The compiled storage plan owns DDL
+
+SQLite preparation lowers the Schemas already present in the sealed
+`RuntimePlan` into quoted DDL and prepared queries. A persistence-only
+projection of those Schemas has a deterministic storage fingerprint; changes
+to Procedures, Views, or Triggers do not create a storage revision. No second
+physical-plan model mirrors `RuntimePlan`.
+
+Other adapters map the same Schema manifests into their own native storage.
+Runtime continues to consume semantic `EntryRepository`,
+`EntryReader`, and `ViewQueryExecutor` ports; SQL remains infrastructure.
+
+Repository operations that address one row carry its Schema collection.
+`get(id)` and `readById(id)` become collection-qualified operations. Generated
+bindings hide this argument behind Schema-specific APIs. Runtime operations
+already know the target Schema from their compiled handler, route, or row
+context; callers must not search every table for an unqualified id.
+
+Cross-Schema reads are compiled explicitly from the Runtime plan. There is no
+implicit union of all tables. A caller that needs several Schemas invokes the
+declared Views or Schema-specific readers and combines their results at the
+application layer.
+
+### Migrations are build artifacts
+
+The SQLite build compares a stored source Schema description with the target
+RuntimePlan and emits a versioned SQL migration artifact containing:
+
+- source and target storage fingerprints;
+- ordered SQLite SQL;
+- a checksum over the exact migration content;
+- whether the change is expand-only or destructive.
+
+Mantle deterministically emits initial tables and safe additive changes. Field
+renames, type conversions, data transforms, and narrowing constraints are
+destructive in the pre-beta contract. Cloud rejects them; operators rebuild the
+database and move required data manually outside Mantle and Control. Production
+neither generates nor accepts arbitrary migration SQL.
+
+Preparation records applied migration ids in the existing `_migrations` ledger.
+The enclosing immutable artifact checksum protects the ordered SQL,
+fingerprints, and target projections. Preparation rejects an unknown source
+fingerprint, changed artifact checksum, skipped revision, or target mismatch.
+Generated migrations are idempotent and retryable after partial application;
+activation and integrity verification run on every attempt instead of being
+treated as one-time ledger entries.
+
+Generated migrations quote all identifiers and never interpolate runtime
+input. Automatic deployments retain removed fields, indexes, and tables as a
+physical superset; logical reads follow the selected plan, while retained
+storage keeps the previous Worker rollback-compatible.
+
+### Builder support
+
+Builder keeps its in-memory or IndexedDB semantic adapter for interactive
+preview. It does not carry SQLite into portable Runtime.
+
+Each successful build can show a draft-to-draft storage delta for authoring
+feedback. It is not labeled as the deployment artifact: only Cloud knows the
+last successfully deployed source revision and produces the exact immutable
+artifact used by deployment. The publish result shows its source/target
+fingerprints, risk classification, ordered SQL, and checksum.
+The interactive preview continues to run the real Mantle Runtime over the
+existing IndexedDB semantic adapter; it does not carry a second SQLite runtime
+or copy preview data into one. Destructive changes remain previewable but are
+not deployable on the pre-beta Cloud path.
+
+CI executes generated SQL against SQLite. Mantle Cloud/D1 is authoritative at
+deployment: it checks the immutable artifact, migration ledger, source/target
+fingerprints, database integrity, and canary before restoring traffic. Running
+the same DDL in every Builder browser would duplicate those gates while adding
+WASM weight and a second Worker/browser compatibility surface.
+
+Unsaved invalid Manifest edits produce diagnostics and no storage revision.
+Intermediate Builder edits do not become production migrations. Deployment
+diffs the last deployed storage revision against the selected project revision.
+
+### Cloud runtime and Schema upgrades
+
+Every Cloud deployment pins these immutable identities:
+
+- Mantle runtime release;
+- project revision and compiled plan fingerprint;
+- source and target storage fingerprints;
+- migration checksum;
+- application artifact checksum.
+
+Automatic migrations are expand-only and therefore run online. The deployment
+sequence is:
+
+1. verify the current tenant D1 storage fingerprint;
+2. apply idempotent additive DDL and verify the ledger, marker, and integrity;
+3. upload an immutable Worker script named by project revision;
+4. run the canary directly against that script and the actual D1 marker;
+5. select that revision for the default and custom host routes;
+6. record the revision active.
+
+There is no KV maintenance gate: KV propagation cannot drain in-flight writes,
+and additive DDL does not need one. Destructive changes stop before deployment.
+The old revision script remains addressable, so route failure or operator
+rollback selects the previous script without rebuilding or replacing it.
+
+Automatic deployments retain old columns and tables needed by the previous
+active Worker. This keeps code rollback valid. Physical cleanup happens only
+during a later reset or rebuild. Mantle runtime upgrades use the same mechanism
+even when the authored Manifest does not change.
+
+Release and application objects are content-addressed. A retry validates and
+reads the same bytes selected by the original operation; mutable release names
+are not valid deployment input.
+
+## Consequences
+
+### Positive
+
+- D1, SQLite tools, generated types, and the Manifest describe the same tables.
+- Each Schema gets independent native limits, indexes, query plans, and schema
+  evolution.
+- The shared-table column ceiling and permanent generated-column buildup are
+  removed.
+- Application migrations and Mantle runtime upgrades use one revision model.
+- Removing the compatibility repository leaves less persistence code.
+
+### Negative
+
+- This is a storage-format break and requires coordinated changes across Spec,
+  Runtime, SQLite adapters, conformance tests, Builder, and Cloud deployment.
+- Unqualified global entry lookups and implicit cross-Schema lists disappear.
+- Optional nullable fields no longer distinguish absent from explicit null.
+- Destructive schema changes require a manual rebuild and data move outside
+  Mantle and Control.
+
+## Alternatives
+
+### Keep `entries` and improve its generated indexes
+
+Rejected. It preserves the shared table's column ceiling, JSON inspection
+surface, and a second schema representation after Manifest build already knows
+the physical model.
+
+### Keep `entries` as a registry beside native Schema tables
+
+Rejected. A registry adds dual-write atomicity and stale-index failure modes.
+Schema-qualified access removes the need for it.
+
+### Put SQLite WASM in the portable Runtime
+
+Rejected. Runtime already has a semantic storage boundary. Builder can verify
+the SQLite lowering as a build check without making every adapter or browser
+preview depend on SQLite.
+
+### Generate production migrations at deploy time
+
+Rejected. Deployment must execute an immutable reviewed artifact and remain
+deterministic when retried. AI generation belongs before review, not inside a
+production mutation.
+
+## How to apply
+
+1. Add the sealed physical storage plan and SQLite DDL lowering.
+2. Change semantic row operations to require collection identity and update all
+   first-party callers.
+3. Replace the shared SQLite repository and View compiler with native-table
+   implementations; delete shared-table DDL, views, index reconciliation, and
+   compatibility helpers.
+4. Update memory and IndexedDB adapters to the new semantic port shape.
+5. Add build-time migration diff/artifact inspection, plus SQLite execution in
+   CI and Cloud/D1 deployment verification.
+6. Pin content-addressed runtime, storage, migration, application, and Worker
+   revision identities in Cloud deploys; test initial deploy, additive Schema
+   change, runtime-only upgrade, partial migration retry, and route rollback.
+7. Update all public storage, Schema, Builder, deployment, and migration
+   documentation after the conformance and consumer checks pass.
+
+## Decision review
+
+Reviewed after implementation against ADR-0019, the semantic storage ports,
+Builder preview persistence, and Mantle Cloud's retryable deployment state.
+The review found and corrected three boundary mistakes before acceptance:
+
+- authored data may legitimately contain `id`, `status`, or `createdAt`, so
+  physical envelope columns require the `_mantle_` prefix;
+- Builder should expose draft storage risk without pretending it knows the
+  deployed baseline; Cloud shows the exact immutable artifact, while CI and
+  Cloud/D1 own executable DDL verification and preview stays on IndexedDB;
+- Cloud must pin the runtime release and storage artifact selected when the
+  operation starts; a mutable current release would make retry and rollback
+  nondeterministic.
+
+The native-table path is implemented without a compatibility `entries` table.
+Acceptance is gated by the repository consumer check and the Cloud upgrade,
+retry, and rollback checks in the ADR's final application step.

package/docs/adr/README.md

@@ -18,8 +18,12 @@ Records of *why* mantle ended up shaped this way. The numbering preserves POC AD
 | [0014](0014-auth-better-auth-and-multi-tenant-mcp.md) | The Cloudflare adapter owns one curated Better Auth 1.7 identity/OAuth/MCP authority with CIMD discovery. Verified callers are normalized into runtime context; mutable staff role and target authorization are re-evaluated per call. | Accepted + amended |
 | [0016](0016-site-semantic-layer.md) | Site semantic layer: `AGENTS.md` (cross-tool entry) + `.mantle/launch-state.json` (deterministic install context). The older `mantle/site.md` letter surface is suspended from first-run scaffolds. | Accepted (slimmed) |
 | [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. | Accepted for now |
+| [0018](0018-core-starters-repository-boundary.md) | Core produces published SDK artifacts; the separate starters repository validates them as an external consumer. Revisit after release-contract simplification. | Superseded by 0021 |
 | [0019](0019-sealed-manifest-runtime-pipeline.md) | One sealed source-to-runtime pipeline, semantic storage seam, and optional Web/Admin/platform dependency direction. | Accepted |
+| [0020](0020-builtin-handler-contracts-and-matched-upsert.md) | Static builtin handler contracts and natural-key matched upsert (`handler.match`). | Accepted + amended by 0022 |
+| [0021](0021-retire-starter-scaffolding.md) | Direct authoring; retire Starter scaffolding. | Accepted; supersedes 0018 |
+| [0022](0022-caller-observed-version-occ.md) | Caller-observed `expectedVersion` for Admin bind and builtin upsert OCC. | Accepted |
+| [0024](0024-manifest-native-schema-tables.md) | Materialize each Schema as a native storage table and deploy reviewed migration artifacts. | Accepted |
 
 ## Reading order
 
@@ -31,7 +35,7 @@ If you're new to the codebase:
 4. **0007** — what running the SDK feels like as an AI author (and as the operator agent).
 5. **0011** — the boundary between the runtime and the adapter.
 6. **0010** — how locale flows through the system.
-7. **0013** — historical install-session context; current first launch is landing provision bundles plus repo-local handoff.
+7. **0021** — current direct-authoring boundary; **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)
@@ -54,8 +58,20 @@ The rebuild's ADR-0011 (new) is the most load-bearing addition — the POC accum
 
 ## Contributing a new ADR
 
-1. Pick the next number (currently 0020).
+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 |

package/docs/adr/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/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/adr-lite-809-bounded-public-content.md

@@ -0,0 +1,71 @@
+# 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.