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

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

@@ -1,264 +0,0 @@
-# ADR-0024: Materialize each Schema as a native storage table
-
-**Status:** Accepted; the clauses allowing authored data to use `id`, `status` or `createdAt` are superseded by [ADR-0025](0025-reserved-native-columns-and-published-only-public-views.md) (2026-09-22)
-
-**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, so
-Mantle metadata never collides with authored column names. *Superseded in
-part by ADR-0025:* authored data may no longer use the six native column
-names (`id`, `status`, `version`, `createdAt`, `updatedAt`, `authorId`); the
-prefix remains for every other authored name.
-
-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, narrowing constraints, and any
-`uniqueIndexes` tuple change 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 was allowed to contain `id`, `status`, or `createdAt`, so
-  physical envelope columns require the `_mantle_` prefix (the prefix stays;
-  ADR-0025 later reserved those names for authored data as well);
-- 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/0025-reserved-native-columns-and-published-only-public-views.md

@@ -1,105 +0,0 @@
-# ADR-0025: Reserved native column names and published-only public Views
-
-**Status:** Accepted
-
-**Date:** 2026-09-22
-
-**Related:** [#962](https://github.com/aotter/mantle/issues/962),
-[#1007](https://github.com/aotter/mantle/issues/1007),
-[#1008](https://github.com/aotter/mantle/issues/1008),
-[#1009](https://github.com/aotter/mantle/issues/1009),
-[#1010](https://github.com/aotter/mantle/issues/1010),
-[ADR-0022](0022-caller-observed-version-occ.md),
-[ADR-0024](0024-manifest-native-schema-tables.md) (partially superseded: its clauses allowing authored `id`, `status`, `createdAt`)
-
-## Context
-
-Every entry carries six native columns outside `data`: `id`, `status`,
-`version`, `createdAt`, `updatedAt`, `authorId`. Before this decision the
-grammar treated their names inconsistently:
-
-- A Schema data property could reuse one of the names. The SQLite dialect then
-  resolved the name to the data column first; IndexedDB resolved it to the
-  native field first. The same View read different columns on different
-  storage.
-- `Schema.spec.indexes` could not reference the names at all
-  (`SCHEMA_INDEX_INVALID`), while the runtime's own indexes lead with
-  `_mantle_status`.
-- A public View over a `publishing` Schema hid drafts only when the author
-  wrote `filter: eq status published`. The handbook promised drafts are
-  unreadable until published; nothing enforced it on REST, MCP
-  `query_view_*` or WebMCP, which share one compiled plan.
-
-The #962 soak measured the consequence of the second point: the list View
-read 14,940 rows per request on a 10,991-row D1 table. Without planner
-statistics, which production SQLite-family storage never has, SQLite chose
-the runtime's `(_mantle_status, _mantle_updated_at, _mantle_id)` index for the
-status equality and sorted every published row in a temporary B-tree; the
-declared `[publishedAt]` index was never used, and the grammar refused the
-`(status, publishedAt)` index that would have served the query.
-
-Two alternatives were considered and rejected during review (#1008):
-
-- **Core derives indexes from Views.** Rejected: the manifest is a deployment
-  spec; Mantle Core is not a query optimizer, and a derived index has no
-  owner when a View is deleted.
-- **Explicit object references** such as `{ meta: status }` /
-  `{ field: publishedAt, direction: desc }`. Deferred: it adds a grammar shape
-  to solve an ambiguity that reserving the names removes, and no shipped View
-  needs mixed-direction ordering. It remains the upgrade path.
-
-A data-first resolution rule with only `status` reserved was also rejected: an
-index declared as `[[createdAt]]` would silently change meaning when a data
-property `createdAt` is added later, while the index identity (field-name
-hex) kept the old physical index.
-
-## Decision
-
-1. **The six native column names are reserved.** A Schema data property may
-   not use them; `mantle validate` fails closed with
-   `INVALID_MANIFEST_ENVELOPE` at `/spec/schema/properties/<name>`, the same
-   mechanism ADR-0022 uses for `expectedVersion`. Domain names replace them
-   (`submittedAt`, `orderStatus`, `submittedBy`).
-2. **Every storage resolves a native name to the native column, first.** With
-   shadowing rejected this is a no-op for valid manifests; it is stated so the
-   SQLite dialect, IndexedDB and the index DDL cannot drift apart again.
-3. **`Schema.spec.indexes` may reference native names**; the SQLite dialect
-   maps them to `_mantle_*` columns in `CREATE INDEX`. `uniqueIndexes` may not:
-   native columns carry no domain uniqueness. Tuples stay `string[][]`; no
-   direction, no object form.
-4. **The author declares the access path; Mantle measures it.** A public View
-   over a `publishing` Schema always carries `status = published`, so its
-   index leads with `status` (`indexes: [[status, publishedAt]]`). Core does
-   not synthesize that index. The harness and the D1 inspector (#1010) report
-   whether the declared index is used.
-5. **Public Views over `publishing` Schemas read published rows only, fail
-   closed.** The linker injects `status = published` into the compiled plan
-   whether or not the manifest writes it; an authored identical predicate is
-   redundant and kept; any other `status` comparison on such a View is
-   `VIEW_PUBLIC_STATUS_INVALID`. Staff Views, `operational` Schemas and SQL
-   Views are untouched.
-
-## Consequences
-
-- ADR-0024's statement that authored data may legitimately use `id`, `status`
-  or `createdAt` no longer holds; its `_mantle_` physical prefix is unchanged
-  and still guards every other authored name.
-
-- Breaking for manifests that declared a data property with one of the six
-  names; the official examples and tests were renamed (#1009). Storage is
-  additive: the renamed property is a new column and the old one stays until
-  an explicit migration. The 0.1.3 release entry carries the upgrade note.
-- The semantic fingerprint of any plan with a public publishing View changes
-  once (the injected predicate); `mantle generate` regenerates it.
-- Index identities of existing declarations are unchanged; native-name tuples
-  get new identities. Stale indexes left behind by redeclaration are tracked
-  separately (#1011).
-- Verified on real D1 without `ANALYZE`: the list View reads 50 rows per
-  request with `[status, publishedAt]` and 10,000 without it (#1014).
-
-## Where this lives
-
-The handbook is the single source: [`reference/schema.md`](../handbook/reference/schema.md)
-(reserved columns, index rules), [`reference/view.md`](../handbook/reference/view.md)
-(surfaces). Skills and CLI diagnostics point there; they do not restate the
-rules.

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

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

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

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

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

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

package/docs/adr/README.md

@@ -1,81 +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.
-
-## v0.1.0 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. | Accepted (new) |
-| [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 |
-| [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 |
-| [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 |
-| [0024](0024-manifest-native-schema-tables.md) | Materialize each Schema as a native storage table and deploy reviewed migration artifacts. | Accepted; authored-native-name clauses superseded by 0025 |
-| [0025](0025-reserved-native-columns-and-published-only-public-views.md) | Reserve the six native column names, let `indexes` reference them, and compile public publishing Views published-only. | Accepted |
-| [0026](0026-progressive-generate.md) | Progressive `mantle generate` with a full default, positive features, saved host selection, and user-owned source. | Accepted; supersedes part of 0021 |
-| [0027](0027-scheduled-procedure-triggers.md) | Schedule Triggers in the sealed plan with Cloudflare-hosted invocation and system identity. | Accepted for 0.1.5 |
-| [0028](0028-schema-ttl-expiry.md) | Logical TTL on Schema reads with preview-first, explicit bounded cleanup. | Accepted for 0.1.5 |
-
-## Reading order
-
-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 |

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.