@aotter/mantle 0.1.4 → 0.2.0-alpha.1

package/docs/migration-0.1.2.md

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

package/docs/performance-harness.md

@@ -1,228 +0,0 @@
-# Data access, cache policy, and performance harness
-
-Mantle site code declares intent; Core owns the shared storage layout and the
-Cloudflare adapter owns provider bindings. A site-building agent should not
-need Mantle table names, generated-column names, KV prefixes, or D1 APIs to
-make a normal content/API/page change.
-
-## Ownership
-
-| Read or state | Owner | Notes |
-|---|---|---|
-| Entry get/list and public slug/data-field/published reads | `DatabaseEntryRepository` through `EntryRepository` / `EntryReader` | Schema-aware field resolution is shared here. |
-| Manifest View execution | `ExecuteViewUseCase` + prepared `ViewQueryExecutor` | Core owns authorization and request validation; selected storage lowers queries once and resolves declared Schema indexes. |
-| Editable settings and code-owned locale/media policy | `DatabaseSiteConfigRepository` | Editable values and dynamic media tool policy are read fresh; boot-seeded locale policy may be memoized within the runtime instance. |
-| Pending media uploads | `DatabasePendingUploadRepository` | Canonical, read-after-write D1 state; never publish-cache state. |
-| Rendered HTML, Markdown, and `llms.txt` | Request-time render use cases plus the Cloudflare public-route cache policy | D1 is canonical; version-local Workers Cache stores anonymous HTTP responses. |
-| D1 transport and optional query metrics | Cloudflare bindings | Bindings stay thin. Query/cache policy does not belong in a generic provider `BaseRepository`. |
-
-The runtime exposes no raw database handle. Application and adapter code uses
-the sealed plan, runtime use cases, `entries`, and `siteConfig`. An application may own
-additional tables behind its own repository at the composition root, but it
-must not query Mantle-owned tables outside the selected storage adapter.
-
-## Cache contract
-
-- D1 is canonical for entries, site settings, media metadata, and pending
-  uploads. Core stores no rendered artifact copies.
-- Public routes render canonical state and return
-  `Cache-Control: public, max-age=0, s-maxage=300`.
-- Cloudflare Workers Cache checks eligible anonymous responses before invoking
-  the Worker. Cache keys are version-local, so a deploy starts with no stale
-  response from the previous Worker version.
-- Successful publishing-content and site-setting writes purge the shared
-  deployment-scoped public Cache-Tag through Cloudflare's native cache API. Operational
-  records and immutable assets stay outside that invalidation boundary.
-- Do not cache every repository read. Cross-isolate correctness for editable
-  data wins unless a read has a measured hot-path contract and explicit
-  invalidation.
-
-## Index coverage
-
-The Node harness uses the real canonical migrations, generated Schema DDL,
-real View compiler, deterministic skewed rows, and SQLite
-`EXPLAIN QUERY PLAN`:
-
-```bash
-pnpm exec mantle-harness indexes --manifests ./manifests --format text
-pnpm exec mantle-harness indexes --require-public --format json
-pnpm exec mantle-harness indexes --require account-members --format json
-```
-
-Without `--require-public` or `--require`, findings are advisory. A required
-path fails on a required Schema-table scan, a temporary ORDER BY B-tree, or a
-data-field predicate/order that does not use a declared Schema index.
-Projection alone does not require an index. `mantle validate` remains a pure
-correctness check; no performance grammar or manifest atom was added.
-
-The fixture follows each Schema lifecycle: operational rows are immediately
-published, while publishing Schemas contain both draft and published rows. The
-harness deliberately does not run `ANALYZE` or `PRAGMA optimize`, so it cannot
-turn an unprepared production plan into a local pass. This is a conservative
-SQLite preflight, not proof of D1 rows-read, Worker CPU, or IndexedDB behavior;
-measure those on the target backend before making a performance claim.
-
-Use the machine report in CI. It includes the compiled SQL and parameters,
-query-plan details, named indexes, scan/sort flags, result count, SQLite
-version, fixture row count, and required-failure summary.
-
-## Worker/API/page sampling
-
-Sample any running environment with the public HTTP helper:
-
-```bash
-pnpm exec mantle-harness http \
-  --base-url http://127.0.0.1:8787 \
-  --route recent=/api/views/recent-posts \
-  --route page=/en/posts/hello \
-  --rounds 20 --warmup 2 --format json
-```
-
-Timing always reports p50/p95/max. A test-only Worker wrapper may also return
-`x-mantle-query-count` and `x-mantle-rows-read`; those become distributions in
-the same report. Do not expose these diagnostic headers in production.
-
-The path-scoped Cloudflare benchmark workflow runs `pnpm bench:wrangler`
-against real Wrangler-local D1, Worker HTTP routing, View execution, and origin
-page rendering. It compares 100 and 10,000 row fixtures and gates row-read
-scaling plus endpoint query budgets, not absolute milliseconds. It is separate
-from the required repository checks so an unrelated dependency or docs PR does
-not fail on the platform harness. Wrangler-local does not emulate the new
-entrypoint Workers Cache, so cache hits are a deployment-level smoke check
-rather than a fabricated local metric.
-
-## Seven findings: measured disposition
-
-Measured on the deterministic 2026-08-01 Wrangler-local fixture; timings are
-diagnostic, while query/row counts are the stable assertions.
-
-| Finding | Disposition |
-|---|---|
-| Public cache hits read D1 first | Removed from Worker code. Cloudflare's entrypoint Workers Cache runs before the Worker; Core has no inner render cache. |
-| Slug/locale reads bypass Schema indexes | Fixed by the shared schema-aware entry-read boundary over native columns. A 10,000-row page MISS measured 2 queries / 5 rows read. |
-| OFFSET pagination | Retained only where the View/Admin contract explicitly uses it, with a 500-row response cap. Public content lists and discovery now use forward keyset pages; they are not covered by the old 500-row claim. |
-| Admin substring search scans | Accepted only for the authenticated Admin collection browser, with a 500-row response cap. Large/search-heavy sites should add a purpose-shaped indexed View or dedicated search service; do not expose this scan publicly. |
-| Published list/sitemap/llms paths lack system indexes | Fixed with measured partial indexes for published global, locale, collection, and collection+locale ordering. The 100-row and 10,000-row API runs both measured 1 query / 20 rows read. |
-| Page MISS waits for cache write-back | Removed. Origin rendering returns directly; Workers Cache owns response storage outside the Worker. |
-| Benchmark stops at fake in-process dispatch | Fixed by the Node planner and Wrangler-local Worker/API/page layers. The old dispatch microbenchmark remains a narrow CPU signal only. |
-
-The retained OFFSET and substring-search trade-offs are visible exceptions,
-not patterns for new public APIs. Re-measure before widening either scope.
-
-See also [Schema indexes](./schema-indexes.md) and the official Cloudflare
-[D1 index guidance](https://developers.cloudflare.com/d1/best-practices/use-indexes/).
-
-### Prepared database, new Worker state
-
-The Wrangler fixture resets its in-isolate runtime after seeding while retaining
-D1. The first public page has a four-statement budget (fingerprint, lazy locale,
-site settings, entry); subsequent origin pages have a two-statement budget.
-This is a new application state in the same workerd isolate, not a measurement
-of module startup CPU or an entrypoint cache HIT. Locale caching is enabled by
-a successful preparation fingerprint; editable settings and media policy still
-read the canonical database on every call.
-
-### HTTP Trigger routing
-
-The portable request handler indexes Trigger paths by method and segments once.
-Literal and wildcard branches retain sealed-plan order, including encoded literal
-collisions that an outer router may select differently. Each request decodes its
-segments once and invokes the original Trigger identity through the same runtime.
-The 1/10/100/1,000-route regression uses four segment lookups at every size;
-overlapping wildcard shapes can visit multiple branches, pruned by route rank.
-The HTTP microbench and workerd harness include the same route-count axis.
-Workerd wall times include I/O and are not CPU measurements or a fixed-ms CI gate.
-
-### Public content pages and discovery (#809)
-
-| Surface | Canonical read / continuation |
-|---|---|
-| Collection HTML and collection Markdown | 50 entries by default, forward `cursor`; visible Next link plus HTTP `Link: rel="next"`. |
-| Locale and root llms.txt | One canonical page, default 50 entries; root expands that page across configured locales in memory. Shared entries are not reread once per locale. Follow the body/HTTP continuation link. |
-| Sitemap part | Up to 2,000 entries, with only declared path fields (built-in resolver: `slug`). A small site returns a urlset directly; a larger site returns a sitemap index linking every part. |
-| Sitemap index | Walks metadata pages to derive exact part cursors; O(N) metadata work on an index MISS, with one page resident at a time. It is not a constant-work list endpoint. |
-
-`EntryReader.readPublishedPage` caps returned data JSON at 1 MiB and 2,000 rows.
-One oversized entry is returned alone to make progress. SQLite applies the byte
-budget before transferring/parsing JSON in the Worker; one extra candidate
-identifies continuation. A localized + shared page merges two indexed ranges
-inside the same statement. The original `readPublished` remains an explicit
-unbounded read unless its caller supplies a limit.
-
-Translation lists resolve at most one newest published parent per join value,
-then resolve media once for the bounded list. Parent payloads and media metadata
-are additional input; the 1 MiB budget describes the canonical child page, not
-arbitrary template output or total Worker heap. Custom renderers own their output
-size. IndexedDB keeps identical page semantics but currently scans its local
-collection; this is not a claim of bounded IndexedDB storage I/O.
-
-The real SQLite fixture matrix covers 100/10,000/50,000 published rows, 64 B/4 KiB
-bodies, and 1/3/10 locales. At limit 20, every case transfers 21 candidate rows;
-4 KiB body data occupies 87,003–87,129 bytes, independent of collection size.
-Complete llms traversal uses 2/200/1,000 statements at the default 50-row page
-size, independent of locale count. Sitemap and llms URL sets match, including
-275,000 URLs for 50,000 mixed localized/shared rows across 10 locales.
-
-Run `pnpm --filter @aotter/mantle-cloudflare exec vitest run
-test/public-content-scaling.test.ts` to emit JSON transfer sizes and traversal
-CPU/wall/RSS diagnostics. These are Node + SQLite + assertions, including the
-fixture database and URL-validation set; RSS is a process high-water mark, not
-per-request Worker peak memory. Worker CPU, true cache HIT/MISS and placement
-measurements belong to the matched native/full-stack harness (#812).
-
-The workerd smoke also measures public list, llms and sitemap. The first two
-use two warm statements (settings + page) and bounded D1 work. Sitemap index
-queries and rows-read scale with the number of metadata parts; this explicit
-cost preserves complete discovery instead of silently dropping URLs.
-
-### Request diagnostics (version 1, test/performance only)
-
-Import `runWithRequestDiagnostics`, `instrumentD1`, `instrumentKv` and
-`instrumentR2` from `@aotter/mantle-cloudflare/testing`. Wrap native bindings once
-before handing the same D1 object to Auth and Runtime. Open the request context
-outside the complete facade fetch, and pass binding-presence flags matching the
-instrumented fixture. The observer receives one response-time record; it never
-receives request headers, tokens, proofs, user IDs, SQL, parameters, tool arguments,
-object keys or response content. Sync/async observer failure cannot change the
-original response or exception. The library emits no diagnostic headers or logs.
-
-Records distinguish HTTP outcome from JSON-RPC result/error/tool-error. They
-include actual in-isolate arrivals, inclusive OAuth/DPoP, role, runtime, catalog,
-dispatcher construction and dispatch wall spans. Unreached phases are null.
-Shared KV loads charge native I/O once to the initiating request; waiters record
-wait duration and the same hit/miss/repair/error source. Boot publication has a
-separate counter. The original rejected shared load remains retryable.
-
-D1 statements and binding calls are separate: a batch is one call and N attempted
-statements. Failed attempts count. `exec` uses the provider's count; unavailable
-counts stay in `unknownStatementCalls`, never a semicolon parser. `first(column)`
-and `raw` preserve native behavior and do not silently execute `all` to manufacture
-metadata. Their absent metadata is null. Rows/duration are sums of available
-metadata, and `metadataStatements` identifies coverage; incomplete coverage is
-not a full-workload total. Serialized binding results are measured bytes, not a
-claim about bytes on the provider's wire. Existing D1DatabaseDriver observers can
-request metadata for first-row reads when a fixture explicitly chooses that mode.
-
-KV bytes identify UTF-8, buffer or reserialized JSON sources. R2 payload bytes
-remain unknown for an unconsumed/partly consumed GET. A successful PUT of that exact
-native GET stream confirms the transferred body size on both operations. Streams
-are never wrapped or buffered for diagnostics, preserving R2's native known-length
-contract. `byteSamples` distinguishes known payload samples from the operation
-count. Metadata/list response serialization is labeled separately from object
-payload. R2 coverage is head/get/put/delete/list, not multipart-upload instrumentation.
-
-Snapshots freeze at response creation; outstanding/deferred operations remain
-visible through `inFlight` and metadata coverage and cannot rewrite a published
-record. `totalMs` excludes the subsequent test-only JSON-RPC response inspection,
-delivery and deferred work. CPU, TTFB, full-body duration and heap must be measured
-separately. Worker wall clocks advance on I/O and are not a CPU timer; use the
-[official CPU profiler](https://developers.cloudflare.com/workers/observability/dev-tools/cpu-usage/).
-Measure diagnostics off/on overhead with the same workload before interpreting
-small latency differences.
-
-### Matched native facade controls (#812)
-
-`pnpm bench:wrangler` now also runs the native parity smoke. The full
-`pnpm bench:parity` matrix adds real Auth/MCP, cold workerd processes, R2,
-TTFB/full-body timing and CPU/heap evidence. See
-[the controls, gates and reproducible commands](./adr/adr-lite-812-native-parity.md).

package/docs/release-process.md

@@ -1,244 +0,0 @@
-# Release process
-
-How a version reaches npm. What each shipped stable contains is
-[Releases](handbook/releases/index.md); this document is the procedure only.
-A release has no Starter/Landing checkout, tag, dispatch, credential or
-deployment dependency.
-
-## Authority and state transitions
-
-`.github/workflows/release.yml` is the only release controller. Humans merge
-a reviewed same-repository release PR, then explicitly dispatch that merge.
-No task implicitly authorizes publication; no manual package/tag writer exists.
-
-| State | Sole next writer | Retry / invariant |
-|---|---|---|
-| Reviewed source; unused version | Core source/packed-consumer gates, then immutable Core tag | Exact canonical merged PR SHA and version required |
-| Tag exists; registry candidates partial | Existing npm/GPR publication steps | Verify existing artifact identity; publish missing versions only |
-| Tag exists and all eleven npmjs packages already exist | Metadata verify, then channel promote and the GitHub release | Skip pack and immutable tarball compare. The controller tip must not rebuild published artifact identity. npm integrity metadata still has to be `sha512`. The public-registry Worker gate stays skipped |
-| Tag exists on an ancestor of the dispatched tip; tip package versions still match | Resolve binds release identity to the tag SHA; later steps stay the existing writers | Controller-only recovery. Do not retag. The canonical merged-PR check uses the tag SHA. Fail when the tip version differs or the tag commit is not an ancestor |
-| Registry candidates verified | Public-registry reference consumer gate | No mutation; failure leaves public channels and `mantle-release` unchanged |
-| Consumer passes | That registry's promote step: monotonic channel add for every package | Same version is a no-op; older runs cannot move a channel backward. Public channels are only `alpha`, `beta`, `rc`, and `latest`. `mantle-release` is never removed |
-| Channels promoted or preserved | GitHub release step | Existing release identity or fail. Leftover `mantle-release` pointing at the last published candidate is expected |
-
-The public-registry gate uses a disposable copy of the directly authored
-`docs/examples/host-minimal-worker` reference, installs the exact candidate, then
-checks generation, skill projection, TypeScript and real Worker HTTP behavior.
-The same reference is gated against exact tarballs before Core tagging. It is
-a test/example, not a scaffold product or another repository release.
-
-## Changing release automation
-
-Before editing a release workflow, put a finite state table plus its
-invariants and non-goals in a Draft PR. Name the single mutation boundary for
-each external resource; recovery must return through that boundary rather than
-introduce a second writer.
-
-Freeze one commit SHA for review. Every finding must name the affected state
-row, a concrete event interleaving, and the wrong mutation it permits. A clean
-verdict expires when that SHA changes. After two patch rounds, a new
-foundational blocker returns to the state table and the user for a scope
-decision instead of starting another local redesign loop.
-
-Invariants: immutable versions/tags retain their identity; registry integrity
-and the published-consumer gate precede public channel promotion; retries
-cannot move channels backward. No downstream mutation, unpublish, dist-tag
-removal, or rollback is introduced. The runnable release-order check guards
-these transitions.
-
-Mutation boundaries during a release: `Publish to npmjs` and `Mirror to
-GitHub Packages` attach the internal candidate dist-tag `mantle-release`
-while publishing a version. `Promote npmjs channel tags` is the only
-release step that moves npmjs public channels. `Promote GitHub Packages
-channel tags` is the only release step that moves GitHub Packages public
-channels. Neither step removes `mantle-release`. Recovery of a partial
-release reruns that same controller and version.
-
-`mantle-release` is not a public channel. It stays forever as an internal
-candidate tag pointing at the last published candidate. Official channels
-are only `alpha`, `beta`, `rc`, and `latest`. Consumers must not install
-`mantle-release`. Deleting it after promotion is not part of the release:
-dist-tag DELETE only added failure and re-run state, and Actions
-`NPM_TOKEN` 403s on that DELETE.
-
-## Branches and channels
-
-| Version | Source branch | npm dist-tag | GitHub release |
-|---|---|---|---|
-| `X.Y.Z-alpha.N` | `develop` | `alpha` | prerelease |
-| `X.Y.Z-beta.N` | `main` | `beta` | prerelease |
-| `X.Y.Z-rc.N` | `main` | `rc` | prerelease |
-| `X.Y.Z` | `main` | `latest` | release |
-
-- The controller derives the source branch from the version: `-alpha` means
-  `develop`, anything else means `main`. An untagged dispatch must be that
-  branch's tip and the merge commit of exactly one PR into that branch.
-  When the version tag already exists on an ancestor of the tip, Resolve
-  recovers from that tag SHA; see Recovery.
-  `scripts/release-tag-order.mjs` rejects any other prerelease identifier.
-- `develop` is where every change integrates first, so it is the base for all
-  work despite `main` being the repository's default branch on GitHub. `main`
-  changes only through promotion PRs and hotfix PRs (below); it is never pushed
-  directly, rebased or force-updated. Both branches share one ruleset: PR, one
-  approval, resolved threads and a current-base `Typecheck + tests` check.
-- Stable is the only release that moves `latest`. A prerelease channel keeps
-  its last version when a later stable publishes.
-- Publish uses `--tag mantle-release`. `mantle-release` is an internal
-  candidate dist-tag, not a public channel. Consumers must not install it.
-  Official channels are only `alpha`, `beta`, `rc`, and `latest`.
-  Publication does not move those channels. After the public-registry
-  consumer gate, each registry's promote step moves every package's real
-  channel and leaves `mantle-release` pointing at the last published
-  candidate.
-
-## Prepare and run
-
-1. Fetch Core refs, prove the version and tag unused. Preview GitHub generated
-   notes since the previous tag; correct PR metadata and label release-only
-   PRs skip-release-notes. Do not duplicate release entries in CHANGELOG.md.
-2. Align every workspace package, plugin and marketplace ref to the version.
-   The controller checks package.json files and plugin manifests only; docs
-   pins and the admin-ui registry dependency are hand-edited, so grep for the
-   old version until only lockfiles and registry-pinned examples remain:
-
-   ```sh
-   OLD=<previous version> NEW=<version>
-   git grep -l "\"version\": \"$OLD\"" -- '*.json' ':!**/package-lock.json' \
-     | xargs perl -pi -e "s/\"version\": \"\Q$OLD\E\"/\"version\": \"$NEW\"/"
-   node scripts/sync-plugin-manifests.mjs
-   git grep -n "$OLD" -- ':!pnpm-lock.yaml' ':!**/package-lock.json'
-   ```
-
-   Leave the consumer cold-start entry **untagged**: `npx skills add
-   aotter/mantle`, `/plugin marketplace add aotter/mantle`,
-   `codex plugin marketplace add aotter/mantle` and the plugin-manifest
-   descriptions carry no `@v…` / `--ref`. Untagged resolves to `main`, which
-   normally moves at a release but may contain a source-only hotfix; the
-   installed npm package remains the version authority
-   (#995, #998). Only "installed version" statements such as
-   `(currently \`X.Y.Z\`)` are bumped.
-
-3. Review API compatibility and migration instructions for actual consumers.
-   Frozen legacy consumers stay on their pinned version; do not make them
-   follow new Core.
-4. Run `pnpm check`, including exact packed Worker, optional products, Bun,
-   Vercel, skills, release invariants, types and tests. Inspect the umbrella
-   docs/skills payload: no workspace dependencies, secrets or local state.
-5. Freeze the PR head for self review; CI must pass before merge. Merge into
-   `develop` with a merge commit for every version. For an alpha, dispatch
-   release.yml from that merge with `version` (without v). For beta, RC and
-   stable, continue with the promotion below. The controller refuses an
-   untagged source that is no longer the expected branch tip.
-
-The eleven public packages remain in dependency order:
-
-1. @aotter/mantle-spec
-2. @aotter/mantle-admin-ui
-3. @aotter/mantle-runtime
-4. @aotter/mantle-indexeddb
-5. @aotter/mantle-web
-6. @aotter/mantle-admin
-7. @aotter/mantle-auth
-8. @aotter/mantle-bun
-9. @aotter/mantle-vercel
-10. @aotter/mantle-cloudflare
-11. @aotter/mantle
-
-## Promote to main (beta, RC, stable)
-
-Every non-alpha release is the version PR above, one promotion PR and one
-dispatch. The version PR still merges into `develop`, so `develop` always
-contains what `main` publishes and promotions never conflict.
-
-1. Stable only: the version's release-gate issue records owner acceptance.
-   Every gate item passes with linked evidence or is explicitly deferred
-   there, and no `release-gate` issue stays open against the version.
-   Beta and RC need the gate defined, not passed.
-2. Merge the version PR into `develop` with a merge commit; note its SHA.
-3. Pin the promotion head at that SHA so later `develop` merges cannot ride
-   along, then open the promotion PR against `main`:
-
-   ```sh
-   git fetch origin
-   git push origin <develop merge SHA>:refs/heads/promote/<version>
-   gh pr create --base main --head promote/<version> \
-     --title "release: promote <version> to main" --label skip-release-notes
-   ```
-
-   The body names the version PR, the pinned SHA and the gate evidence. The
-   usual review and checks apply. An organization-admin bypass merge must be
-   recorded on the PR (see CONTRIBUTING).
-4. Merge with a merge commit, never rebase: the controller needs `main`'s tip
-   to be the PR's merge commit. `main`'s tree now equals the pinned commit.
-5. Dispatch from `main` and watch every gate exactly as for an alpha:
-
-   ```sh
-   gh workflow run release.yml --ref main -f version=<version>
-   ```
-
-6. RC to stable repeats 2–5 with the next version. `rc` keeps pointing at
-   the last RC; stable moves only `latest`.
-
-Hotfix on `main` is for a published non-alpha version that cannot wait for
-the next promotion. Branch from `main`, include the version bump, PR into
-`main`, dispatch as in step 5, then immediately PR `main` back into `develop`
-and resolve version files in favour of `develop`. Until that lands, the next
-promotion conflicts on the version files.
-
-GitHub generates notes from the immediately previous tag, which for a stable
-is usually its own last RC. To cover the whole line instead, regenerate from
-the previous stable and edit the release body after the run. The body is not
-an immutable artifact; the tag and packages are.
-
-```sh
-gh api repos/aotter/mantle/releases/generate-notes \
-  -f tag_name=v<version> -f previous_tag_name=v<previous stable> --jq .body > notes.md
-gh release edit v<version> --notes-file notes.md
-```
-
-Add the version's entry to [Releases](handbook/releases/index.md) in the same
-pass, so the handbook and the GitHub release describe the same thing.
-
-After publication, move docs/examples that were pinned to a packed checkout
-back to registry installation with an updated lockfile, and close the gate
-issue with the run link and completion evidence.
-
-## Credentials and verification
-
-Core needs NPM_TOKEN for npmjs. Its job-scoped GITHUB_TOKEN creates the Core
-tag/release and mirrors GitHub Packages. No cross-repository fanout token is
-needed. Before tagging, verify credentials and new-version absence on both
-registries. Existing artifacts on retry must have matching integrity.
-
-Completion requires the Core tag SHA, all eleven npmjs/GPR packages, exact
-integrity, no workspace dependencies, a passing public-registry Worker gate,
-correct channel tags, and the GitHub release. Leftover `mantle-release`
-pointing at the last published candidate is expected. Retain run links and
-gate evidence.
-This does not prove stable production soak or upgrade safety; the version's
-release-gate issue owns those acceptance requirements. An agent acceptance run
-uses only the version-matched authoring instructions, not an SDK checkout or
-generated site.
-
-## Recovery
-
-Rerun the same controller commit/version for a transient or verified partial
-transition. Existing tags/artifacts must match; newer channels stay put. Fail
-on identity disagreement instead of guessing. A wrong public artifact needs
-a new version; never force-retag, overwrite or reuse a published version.
-
-After a controller-only fix lands on the tip, re-dispatch the same version
-from the source branch. Resolve recovers using the existing tag SHA when
-that commit is an ancestor of the tip and package versions on the tip still
-match. The tag owns the release SHA; the tip only carries controller fixes.
-Tagged recovery skips the Core source check because that tree was already
-released from the immutable tag. When `tag_exists` and all eleven npmjs
-packages already exist at that version, that same existence check skips
-packing, immutable tarball comparison, and the public-registry Worker gate.
-The controller tip must not rebuild an artifact whose identity is already
-published. Verify npm metadata still runs. The Worker gate stays skipped
-because the first run already passed it before promotion.
-
-Unpublish is reserved for actual secret/private-file exposure, never routine
-fixes. Infrastructure renames require their explicit config diff and live
-smoke; CI alone cannot prove provider identity.

package/docs/schema-indexes.md

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

package/docs/sealed-pipeline-ownership.md

@@ -1,101 +0,0 @@
-# Sealed pipeline ownership ledger
-
-This is the migration evidence for ADR-0019 and epic #656. It records the
-`v0.1.0-alpha.7` owners before code moves, the single target owner, and the
-issue that must delete or delegate the old path.
-
-## Rule ownership
-
-| Behavior | Current owner(s) | Target owner | Migration |
-|---|---|---|---|
-| YAML document decode, empty documents, syntax errors, alias cap | `ManifestParser.parseOneStream` | Parse/decode in `mantle-spec` | #663 |
-| Four-atom discrimination, envelope keys, primitive/enum shape | `ManifestParser` | Parse/normalize | #663 |
-| Source identity and document location | Synthetic parser doc index plus `loadManifests`/`ManifestPathDiagnoser` reconstruction | `ManifestSourceSet` authored metadata | #663 |
-| Schema atom-local shape, index/search/UI shape | Parser plus `ValidateManifestsUseCase` checkers | Parse/normalize | #663; old checks deleted in #673 |
-| Defaults for localized/lifecycle/indexes/search/order | `IntrospectManifestsUseCase`, runtime lifecycle checks, and callers using `??` | Parse/normalize exactly once | #663, #667 |
-| Duplicate names | `ValidateManifestsUseCase` | Link | #664 |
-| Schema/View/Procedure/Trigger cross-references | `ValidateManifestsUseCase` and repeated boot checks | Link | #664 |
-| Guard existence, self-reference, builtin/chain rules | Validate plus `ValidateBootUseCase` | Link | #664 |
-| Locale/translates graph | `checkLocaleAndTranslates` in validate and boot | Link for manifest graph; Prepare for selected deployment locales | #664, #666 |
-| Manifest-owned HTTP/MCP collisions | Validate plus boot | Link | #664 |
-| Handler source/registry availability | Optional CLI source scan plus boot registry scan | Prepare | #666 |
-| Optional Web/Admin/Auth path reservations | Fixed boot/Cloudflare prefix lists | Prepare selected capabilities only | #666, #669, #670 |
-| Kind/name lookup maps | `ValidateManifestsUseCase`, `ValidateBootUseCase`, `createCmsRuntime`, adapters | Compile once into `RuntimePlan` | #665 |
-| Authorization/guard descriptors | Raw manifests interpreted by validators, runtime use cases, and mounts | Compile plan; evaluate in Core invocation | #665, #667 |
-| Trigger indices and Procedure descriptors | Runtime construction/use cases | Compile plan | #665 |
-| Semantic fingerprint | Runtime boot from raw manifests | Compile plan | #665 |
-| Declarative View resolution | `ViewSqlCompiler` during each `ExecuteViewUseCase` call | Compile logical plan once | #665 |
-| SQLite/JSON1 View lowering and native `spec.sql` | `ViewSqlCompiler` plus `DatabaseDriver` invocation | Selected storage preparation | #666 |
-| Canonical SQL migrations, native Schema tables/indexes, readiness | `createCmsRuntime.bootInit` and runtime infrastructure | Prepare | #666 |
-| Entry/media/site repositories | Runtime constructs `Database*Repository` from `DatabaseDriver` | Prepared semantic storage ports; media/config move with final owner | #666, #669, #670 |
-| Content, View, Procedure, Trigger, lifecycle invocation | Runtime use cases over raw maps/driver | `MantleRuntime` over plan + semantic ports | #667 |
-| Target authorization/admin bypass | Runtime plus adapter entry points | One Core invocation policy; adapter resolves caller only | #667 |
-| Generated manifest module and TypeScript names | `packages/mantle/src/cli/generate.ts` + `EmitTypesUseCase` | Pure linked/plan projection and `bindMantle` | #668 |
-| Admin asset copy during generation | `packages/mantle/src/cli/generate.ts` | Removed; Admin install/composition owns assets | #668, #670 |
-| HTML/templates/public paths/Markdown/SEO/preview/`llms.txt`/sitemap | Runtime render services plus Cloudflare public routes | Optional `mantle-web` | #669 |
-| Public request mapping and cache policy | `mountPublicRoutes` | Platform adapter using selected Web projection | #669 |
-| Admin API/application/static assets | Optional `mantle-admin`; Cloudflare only binds auth/request context/assets | Optional `mantle-admin` + existing UI artifact | #670 |
-| View/HTTP Trigger route transport | Combined Cloudflare mounts | Platform adapters over the same Core descriptors | #669–#672 |
-| Bun SQLite/process lifecycle | `mantle-bun`; host owns server/database | `mantle-bun`; host owns server/database | #671 |
-| Vercel function/durable-storage lifecycle | `mantle-vercel`; host owns handler/client | `mantle-vercel`; host owns handler/client | #672 |
-| Legacy overloads, aliases, combined mounts, duplicate tests | Current public API plus temporary migration delegates | Deleted | #673 |
-| Contributor/agent/release guidance | `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, two release skill copies | One tool-neutral authority and one release skill | #674 |
-
-## Deletion evidence
-
-All baseline production callers now consume `ParsedManifestSet`,
-`LinkedManifestSet`, or `RuntimePlan` according to their pipeline stage.
-`scripts/check-boundaries.mjs` fails if the removed runtime facade, generated
-site API, raw parser facade, or combined Cloudflare route owner returns.
-Parser-focused tests may inspect parser output, but runtime and platform tests
-must compile and prepare the same sealed plan used by production.
-
-## Consumer manifest corpus
-
-The Core repository does not vendor every downstream manifest. That would
-create a second source of truth. The reusable golden fixture under
-`packages/mantle-spec/test/fixtures/pipeline-v0.1/` covers every shipped atom,
-auth/guard references, all Trigger surfaces, multi-document YAML, empty
-documents, aliases, unknown keys, malformed YAML, and deterministic
-diagnostics.
-
-The following pins record the historical sealed-pipeline migration gates.
-ADR-0021 supersedes the Starter/Landing release coupling: current Core CI and
-release use `docs/examples/host-minimal-worker` from the same reviewed commit.
-Private consumers can still run the exact-tarball checker in their own repos;
-public Core PRs receive no cross-repository credentials:
-
-| Historical consumer | Revision | Gate at the time | Manifest paths |
-|---|---|---|---|
-| `aotter/mantle-starters` | `157e8f49e1e25ae1c52c0115f0dd9e8b6017ef0e` | Core CI + release | `blank/manifests/site.yaml`; `overlays/{community,intake,presence,publication,reservation,transaction}/manifests/site.yaml`; `recipes/typed-web/manifests/site.yaml` |
-| `aotter/mantle-landing` | `4381354dd25d5d94f4096cf3e55a4cb9eecbf3ad` | Landing CI + Core release | `manifests/site.yaml` |
-| `aotter/mantle-platform` (Remote Mantle/control plane) | `3cc0d9ad6ee47b15f06c915c12f56fc4b9143f32` | Platform `exact-packed-core` | `manifests/platform.yaml` |
-| Core i18n fixture | this repository | Core CI | `packages/mantle-spec/test/fixtures/i18n-parent-child/manifests/site.yaml` |
-
-## Baseline gates
-
-The alpha.7 baseline was captured from tag `v0.1.0-alpha.7` on 2026-08-16
-with Node 22, pnpm 9, Wrangler local mode, and datasets of 100/10,000 rows:
-
-| Route | p95 queries | p95 rows read | local p95 timing |
-|---|---:|---:|---:|
-| public View, 10k rows | 1 | 20 | 3.01 ms |
-| public page miss, 10k rows | 2 | 5 | 3.92 ms |
-| Admin list, 10k rows | 1 | 21–22 | 2.49–3.24 ms |
-| Admin related detail, dense | 4 | 151 | 5.23 ms |
-| public builtin create | 1 | 0 | 2.55 ms |
-
-Wall-clock values are evidence, not a cross-machine budget. The normative
-baseline is the existing `pnpm bench:wrangler` query/row gate: every gate must
-remain true, unchanged revisions must perform no repeated preparation, and any
-intentional budget change needs its own reviewed evidence.
-
-Existing full-facade behavior is covered by Cloudflare authorization, Admin,
-public-route/cache, View REST, HTTP Trigger, media, form, and facade tests.
-Issues #669–#673 move those assertions to selected modules and exact packed
-consumers; they do not duplicate the suite under new names.
-
-Issue #674 leaves `CONTRIBUTING.md` plus accepted ADRs as the contributor
-authority. `AGENTS.md`, `CLAUDE.md`, and the Claude release-skill entry are
-small routers; `.agents/skills/mantle-release/SKILL.md` is the only maintainer
-release procedure. Shipped `skills/*` remain separate consumer artifacts.