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

package/docs/release-process.md

@@ -1,39 +1,29 @@
 # Release process
 
-Mantle remains prerelease software until the stable v0.1.0 gate closes.
-Published package versions, Git tags, GitHub releases, and Starter tags are
-immutable: repair a bad release with the next version, never by replacing
-public state.
-
-## Authority
-
-`.github/workflows/release.yml` is the single release controller. Humans merge
-a reviewed release PR and dispatch that workflow from the merge commit. Humans
-do not push release tags or start downstream release workers directly.
-
-The controller owns this order:
-
-```text
-Core source + exact-packed Starter gates
-  -> Core tag
-  -> npmjs + GitHub Packages candidate packages (`mantle-release`)
-  -> Starter release worker
-  -> immutable Starter tag
-  -> public-registry Starter gate
-  -> clean-create + reviewed Landing compatibility gates
-  -> npmjs + GitHub Packages public channel promotion
-  -> Core GitHub Release
-  -> optional Landing worker
-```
-
-The Starter worker owns only its repository transition: it prepares a release
-PR from the exact gated `develop` commit, waits for the named checks, merges
-that checked head atomically into `develop`, and tags the recorded merge
-commit. It does not promote `main`, backport, infer releases from commit text,
-or dispatch Landing.
-
-Landing is an explicit controller input and defaults off. A release that keeps
-`deploy_landing=false` does not mutate or deploy Landing.
+First stable targets 0.1.2 (#826). The last legacy Landing/Starter release is
+0.1.0-alpha.17. Its immutable artifacts and repositories remain available;
+recover that version with its tagged controller/docs. New releases have 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 |
+| Registry candidates verified | Public-registry reference consumer gate | No mutation; failure leaves public channels unchanged |
+| Consumer passes | Monotonic npm/GPR channel promotion | Same version is a no-op; older runs cannot move a channel backward |
+| Channels promoted/preserved newer | GitHub release step | Existing release identity or fail |
+
+The public-registry gate uses a disposable copy of the directly authored
+`docs/examples/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
 
@@ -48,203 +38,67 @@ 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.
 
-For the candidate-to-channel transition, the controller follows this finite
-state table:
-
-| Durable state | Permitted next mutation | Re-run behavior | Public channel |
-|---|---|---|---|
-| Source gated; version unused | Create the immutable Core tag | Existing tag must match or the run fails | Unchanged |
-| Core tag exists; candidate packages incomplete | Publish and verify missing exact versions under `mantle-release` through each registry's sole publish step | Existing versions are verified and skipped | Unchanged |
-| Candidate packages verified; Starter tag absent | Dispatch the pinned Starter release and wait | The Starter worker resumes or reports its matching no-op | Unchanged |
-| Matching Starter tag exists | Validate its Core/base provenance; run the frozen Starter, clean-create, and Landing compatibility gates | Validation and gates repeat without mutation | Unchanged |
-| All downstream consumer gates pass | Promote npmjs and GitHub Packages channel tags monotonically | Same version is a no-op; an older run preserves a newer tag | Candidate or newer version |
-| Channels promoted or preserved newer | Create the Core GitHub Release | Existing matching release is a no-op | Candidate or newer version |
-| Core GitHub Release exists | Dispatch Landing only when explicitly enabled | Landing remains untouched by default | Candidate or newer version |
-
-Invariants:
-
-- immutable package versions and Core/Starter tags must keep the requested
-  version, Core SHA, and pinned Starter SHA identity;
-- public channel tags cannot move until the released Starter, clean-create, and
-  reviewed Landing compatibility gates pass;
-- channel updates use the controller's monotonic promotion boundary, so an
-  older re-run cannot move a channel backward;
-- the candidate version may be fetched explicitly or through the temporary
-  `mantle-release` tag before promotion, but is not the public channel default.
-
-Non-goals: this transition does not change Starter worker ownership, add
-rollback or unpublish behavior, or deploy Landing unless
-`deploy_landing=true`.
+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 or rollback
+is introduced. The runnable release-order check guards these transitions.
 
 ## Branches and channels
 
-- Feature and release PRs target `develop`.
-- Alpha prereleases before stable v0.1.0 release directly from the merged
-  `develop` release commit.
-- Beta, RC, and stable promotion to `main` remains a deliberate human decision;
-  it is not part of the alpha controller.
-- Alpha, beta, and RC GitHub releases are prereleases.
-- npm dist-tags follow the suffix: `alpha`, `beta`, `rc`, or `latest` for
-  stable versions.
-- During the legacy `0.0.x-alpha` cadence, `latest` follows the current alpha.
-  The final `0.1.0-alpha.N` candidates advance only `alpha`; `latest` moves to
-  `0.1.0` after the stable gate passes.
-
-## Release PR
-
-1. Fetch Core and Starter remotes and choose the next unused version.
-2. Preview GitHub's generated notes for the merged commits since the previous
-   tag. Correct PR titles and labels before release; do not duplicate the notes
-   in `CHANGELOG.md`. Label the release-only PR `skip-release-notes`.
-3. Set that exact version in every workspace package and in all four agent
-   plugin manifests. Set `.agents/plugins/marketplace.json` to the immutable
-   `v<version>` ref.
-4. Pin both the controller and Core CI to the exact reviewed
-   `mantle-starters/develop` commit intended for this release. Do not use a
-   branch, latest tag, or inferred fallback.
-5. If an SDK type changed, audit downstream literal constructors and exhaustive
-   switches before publication. CI in Core cannot prove downstream source
-   compatibility by itself.
-6. Run `pnpm check`, inspect the packed umbrella package, and run the exact
-   packed-consumer gate. Review and merge a same-repository PR into `develop`;
-   the controller rejects a direct-push release commit.
-
-Preview the native notes before merging the release PR:
-
-```bash
-gh api --method POST repos/aotter/mantle/releases/generate-notes \
-  -f tag_name=vX.Y.Z \
-  -f target_commitish="$(git rev-parse origin/develop)" \
-  -f previous_tag_name=vPREVIOUS \
-  --jq .body
-```
-
-The nine public packages publish in dependency order:
-
-1. `@aotter/mantle-spec`
-2. `@aotter/mantle-admin-ui`
-3. `@aotter/mantle-runtime`
-4. `@aotter/mantle-web`
-5. `@aotter/mantle-admin`
-6. `@aotter/mantle-bun`
-7. `@aotter/mantle-vercel`
-8. `@aotter/mantle-cloudflare`
-9. `@aotter/mantle`
-
-The umbrella package must contain its version-matched `docs/` and `skills/`
-payload. No tarball may contain `workspace:*` dependencies, secrets, local
-state, or workspace-only files. Starter content is still authored and released
-from the versioned `mantle-starters` repository — Core owns no starter source.
-Core's umbrella CLI is the canonical consumer of that release: `mantle create`
-resolves the official immutable `v${packageVersion}` starter tag and renders it
-through Core's shared provision module. A published Core version
-therefore requires the matching starter tag to exist; see
-[ADR-0018](adr/0018-core-starters-repository-boundary.md).
-
-## Run the controller
-
-Dispatch `.github/workflows/release.yml` from the merged release commit with:
-
-- `version`: the version without the leading `v`.
-- `deploy_landing`: `false` unless Landing was separately reviewed and is
-  intentionally part of this release.
-
-Before creating the Core tag, the controller proves:
-
-- the requested version matches every package, plugin, and marketplace ref;
-- `pnpm check` passes;
-- packed Core passes in the exact pinned Starter source;
-- all nine release tarballs exist;
-- npm and cross-repository credentials are present and readable;
-- a fresh version is unused across npmjs, GitHub Packages, and Starter tags;
-- the pinned Starter commit is still the remote `develop` tip.
-
-After candidate publication under `mantle-release`, it compares each public
-registry integrity value with the locally packed tarball, rejects leaked
-`workspace:*` dependencies, waits for the Starter tag, checks that tag's exact
-Core/base provenance, installs its frozen locks from the public registry, and
-reruns the Starter bundle gates. It then creates clean Blank and multilingual
-Transaction projects through the registry candidate, frozen-installs and checks
-both, and runs the reviewed Landing consumer against the exact packed candidate.
-Only then does it promote the public npmjs and GitHub Packages channel tags and
-create the Core GitHub Release.
-
-## Idempotency and recovery
-
-The global controller lock serializes releases. Re-running the same release is
-supported:
-
-- an existing Core tag must resolve to the same controller commit;
-- existing npm and GitHub Packages versions are verified and skipped;
-- channel dist-tags are never moved backward by an older rerun;
-- a duplicate Starter dispatch resumes its open/merged state or reports a
-  tagged no-op;
-- an existing GitHub Release is a no-op.
-
-If source or immutable state disagrees, the workflow fails instead of guessing.
-Fix source and publish the next version when public state is wrong. Re-run the
-same controller only for a transient failure or a verified partial transition.
-Never force-retag or republish an existing version.
-
-## Credentials
-
-Core repository secrets:
-
-| Secret | Minimum purpose |
-|---|---|
-| `NPM_TOKEN` | Publish the nine `@aotter/*` packages on npmjs. |
-| `RELEASE_FANOUT_TOKEN` | Read and dispatch `aotter/mantle-starters`; also read and dispatch `aotter/mantle-landing` only when Landing is enabled. |
-
-Core's job-scoped `GITHUB_TOKEN` creates the Core tag and release and mirrors
-packages to GitHub Packages. Starter's job-scoped token pushes its generated
-branch, checked merge, and tag; its `RELEASE_FANOUT_TOKEN` is used only to
-create the canonical same-repository PR. Prefer separate fine-grained tokens
-or a GitHub App when practical; do not grant organization-wide repository
-access for this flow.
-
-## Post-release verification
-
-Completion requires evidence for both repositories, not only a green publish
-step:
-
-```bash
-gh -R aotter/mantle release view vX.Y.Z
-gh api repos/aotter/mantle-starters/git/ref/tags/vX.Y.Z
-
-for p in \
-  @aotter/mantle-spec \
-  @aotter/mantle-admin-ui \
-  @aotter/mantle-runtime \
-  @aotter/mantle-web \
-  @aotter/mantle-admin \
-  @aotter/mantle-bun \
-  @aotter/mantle-vercel \
-  @aotter/mantle-cloudflare \
-  @aotter/mantle; do
-  npm view "$p@X.Y.Z" version dist.integrity dependencies --json
-done
-```
-
-The controller already creates and checks clean Blank and multilingual
-Transaction projects. For 0.1.2 release acceptance, give a coding agent with no
-Mantle checkout or repository knowledge only the generated instructions and
-confirm it reaches a running Worker. This is one manual clean-room acceptance,
-not a nondeterministic CI framework. Confirm the generated project contains
-version-matched repo-local Mantle skills and the expected typed runtime surface.
-`blank` remains headless and contains no Kiwa; a typed Starter revision may
-retain its replaceable offline UI palette, but runtime code must not import it.
-
-If `deploy_landing=false`, also verify that no Landing release dispatch or
-deployment was started.
-
-## Fix-forward policy
-
-- Broken public package or Starter bundle: publish the next alpha and explain
-  the re-spin in the fix PR and generated GitHub Release notes.
-- Use `npm deprecate` to steer consumers away from a broken version.
-- Unpublish only for secrets, private files, or similarly severe exposure;
-  npm versions cannot be reused and registry metadata may remain unavailable
-  during the unpublish cooldown.
-- A cross-cutting rename must include an explicit infrastructure-config diff
-  and live smoke test. CI success does not prove renamed Worker, D1, KV, route,
-  or secret bindings are correct.
+- Alpha releases use the reviewed develop merge. Beta/RC/stable use main after
+  explicit promotion; first stable acceptance is tracked by #826.
+- Alpha/beta/RC GitHub releases are prereleases; their npm tags match suffixes.
+- Stable publishes latest. Final 0.1.0 alphas only advance alpha, preserving
+  existing legacy latest. Historic 0.0 alpha behavior remains recoverable.
+
+## 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.
+3. Review API compatibility and migration instructions for actual consumers.
+   Frozen legacy consumers stay on alpha.17; 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. Dispatch
+   release.yml from that merge with `version` (without v). It refuses an
+   untagged source that is no longer the expected branch tip.
+
+The ten 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-bun
+8. @aotter/mantle-vercel
+9. @aotter/mantle-cloudflare
+10. @aotter/mantle
+
+## 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 ten npmjs/GPR packages, exact
+integrity, no workspace dependencies, a passing public-registry Worker gate,
+correct channel tags and the GitHub release. Retain run links and gate evidence.
+This does not prove stable production soak or upgrade safety; #826 owns those
+acceptance requirements. A first-stable agent acceptance 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.
+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,182 +1,5 @@
-# Schema indexes on D1
+# Schema indexes
 
-Mantle stores every authored Schema property inside the shared `entries.data`
-JSON `TEXT` column. Declare `indexes` for measured, hot access paths that need
-an ordered non-unique B-tree index. Use `uniqueIndexes` when the same ordered
-fields are a data-integrity constraint.
+This guide moved into the handbook: [`docs/handbook/reference/schema.md`](handbook/reference/schema.md).
 
-```yaml
-apiVersion: cms.mantle.aotter.net/v1
-kind: Schema
-metadata: { name: account-members }
-spec:
-  title: Account members
-  lifecycle: operational
-  schema:
-    type: object
-    properties:
-      userId:    { type: string }
-      state:     { type: string }
-      accountId: { type: string }
-      email:     { type: [string, "null"] }
-  indexes:
-    - [userId, state, accountId]
-    - [accountId, state, userId]
-  uniqueIndexes:
-    - [accountId, userId]
-    - [accountId, email]
-```
-
-Each inner array is one index. Field order is significant. A one-field array
-is valid; a bare string or the retired `indexedFields` spelling is not.
-Invalid matrix shapes report `INVALID_MANIFEST_ENVELOPE`; invalid index
-semantics report `SCHEMA_INDEX_INVALID`, and unknown fields report
-`SCHEMA_INDEX_FIELD_UNKNOWN` (`uniqueIndexes` keeps its existing
-`UNIQUE_INDEX_FIELD_UNKNOWN` code).
-
-## Leftmost-prefix behavior
-
-For `[userId, state, accountId]`, SQLite can use the index for:
-
-```sql
-WHERE userId = ?
-WHERE userId = ? AND state = ?
-WHERE userId = ? AND state = ? AND accountId = ?
-```
-
-It does not provide the same guarantee when the leftmost field is skipped:
-
-```sql
-WHERE state = ? AND accountId = ?
-```
-
-The second declaration, `[accountId, state, userId]`, supports the other hot
-path and supplies the requested order without a temporary sort:
-
-```sql
-WHERE accountId = ? AND state = ?
-ORDER BY userId
-```
-
-Do not declare every possible permutation. Each index consumes storage and
-adds work to inserts and updates. Start from an observed query plan or hot
-endpoint and declare only the access paths it needs.
-
-## Supported fields
-
-Indexed fields are exact, own, top-level keys of
-`spec.schema.properties`. `a.b` means a literal top-level key named `a.b`; it
-does not traverse `{ a: { b: ... } }`.
-
-An index-bearing Schema name and every indexed field must match
-`^[A-Za-z][A-Za-z0-9_.-]*$`.
-
-The property must declare exactly one non-null scalar type. It may also allow
-`null` with a type array or `nullable: true`.
-
-| JSON Schema type | generated-column affinity |
-|---|---|
-| `string` | `TEXT` |
-| `integer`, `boolean` | `INTEGER` |
-| `number` | `REAL` |
-
-Objects, arrays, enum-only properties, and mixed non-null unions are not
-indexable. Reserved native View fields (`id`, `status`, `version`,
-`createdAt`, `updatedAt`, `authorId`) also cannot be index declarations.
-
-Missing and `null` leftmost values are omitted from the partial index. SQLite
-UNIQUE semantics still allow more than one composite containing `NULL`.
-
-## Core-compiled queries
-
-Mantle creates collection-gated VIRTUAL generated columns during `bootInit`.
-Core-compiled View projections, filters, and ordering automatically reference
-a generated column when their field is declared by `indexes` or
-`uniqueIndexes`; undeclared fields keep using `json_extract`.
-
-D1 stores the original JSON as `TEXT`, not PostgreSQL JSONB. The generated
-scalar columns and their B-tree indexes are the supported indexed-path
-mechanism. Their physical identifiers are private, versioned, and encoded;
-never copy one from `sqlite_schema` into site code.
-
-## Site-owned Procedure SQL
-
-Use the pure helper when a business query remains site-owned. It returns a
-fully quoted reference for a declared field or `null` when that field has no
-declared index. Pass a table alias for joins so the generated column is not
-ambiguous.
-
-```ts
-import {
-  schemaIndexedFieldSql,
-  type SchemaManifest,
-} from "@aotter/mantle/spec";
-import { loadManifests } from "../mantle/manifests.js";
-
-const accountMembers = loadManifests().find(
-  (manifest): manifest is SchemaManifest =>
-    manifest.kind === "Schema" && manifest.metadata.name === "account-members",
-);
-if (!accountMembers) throw new Error("account-members Schema is missing");
-
-const userId = schemaIndexedFieldSql(accountMembers, "userId", "member");
-const state = schemaIndexedFieldSql(accountMembers, "state", "member");
-if (!userId || !state) {
-  throw new Error("account-members actor lookup requires its declared index");
-}
-
-const rows = await env.DB.prepare(
-  `SELECT member.id, member.data
-     FROM entries AS member
-    WHERE member.collection = ?
-      AND ${userId} = ?
-      AND ${state} = ?`,
-)
-  .bind("account-members", actorId, "active")
-  .all();
-```
-
-The helper does not authorize the query or define its business response. The
-site still owns actor resolution, account rules, aggregation, and output.
-
-## Verify a plan
-
-Prefer the shipped crowded-data harness for a manifest View:
-
-```bash
-pnpm exec mantle-harness indexes --require-public --format text
-```
-
-It applies Mantle's real canonical migrations and generated DDL, seeds skewed
-rows, compiles and executes the real View SQL, then records
-`EXPLAIN QUERY PLAN`. By default findings are advisory; use `--require-public`
-or repeat `--require <view-name>` only for paths whose performance is part of
-the contract. See [the performance harness](./performance-harness.md).
-
-For site-owned SQL that cannot be represented by a View, inspect the real
-database directly when adding or changing a hot path:
-
-```sql
-PRAGMA index_list("entries");
-PRAGMA index_xinfo("<index returned above>");
-
-EXPLAIN QUERY PLAN
-SELECT id FROM entries
-WHERE collection = 'account-members'
-  AND "<reference emitted by Core>" = 'user-1';
-```
-
-The plan should contain `SEARCH entries USING INDEX ...`, and an indexed
-filter/order path should not contain `USE TEMP B-TREE FOR ORDER BY`.
-
-Existing databases upgrade by adding new affinity-correct VIRTUAL columns and
-versioned indexes; populated `entries` rows do not need a rewrite. Unused
-generated columns may remain because dropping them is not safe across every D1
-version Mantle supports. Compatible alpha.59 unique indexes remain during a
-rolling upgrade; ambiguous legacy flattened names and indexes removed from
-manifests are reconciled away at boot.
-
-References: [D1 JSON](https://developers.cloudflare.com/d1/sql-api/query-json/),
-[D1 generated columns](https://developers.cloudflare.com/d1/reference/generated-columns/),
-[D1 indexes](https://developers.cloudflare.com/d1/best-practices/use-indexes/),
-[SQLite partial indexes](https://www.sqlite.org/partialindex.html).
+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

@@ -26,7 +26,7 @@ issue that must delete or delegate the old path.
 | 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, indexes, schema SQL Views, readiness | `createCmsRuntime.bootInit` and runtime infrastructure | Prepare | #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 |
@@ -59,10 +59,11 @@ auth/guard references, all Trigger surfaces, multi-document YAML, empty
 documents, aliases, unknown keys, malformed YAML, and deterministic
 diagnostics.
 
-Exact downstream sources and their gate authorities are pinned here. The public
-Starter runs in Core CI and release preflight. Private consumers run the same
-exact-tarball checker in their own repositories, so public Core PRs never
-receive cross-repository credentials:
+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/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:
 
 | Consumer | Revision | Gate authority | Manifest paths |
 |---|---|---|---|