@aotter/mantle 0.1.0-alpha.8 → 0.1.2-alpha.1

package/docs/adr/0020-builtin-handler-contracts-and-matched-upsert.md

@@ -0,0 +1,199 @@
+# ADR-0020: Builtin Handler Contracts and Matched Upsert
+
+**Status:** Accepted + amended by [ADR-0022](0022-caller-observed-version-occ.md)
+
+**Date:** 2026-09-01
+
+**Related:** [#765](https://github.com/aotter/mantle/issues/765),
+[#766](https://github.com/aotter/mantle/issues/766),
+[#850](https://github.com/aotter/mantle/issues/850),
+ADR-0008, ADR-0010, ADR-0014, ADR-0019, ADR-0022
+
+> **Amendment (ADR-0022):** matched-upsert OCC no longer forbids caller
+> `expectedVersion` or substitutes `preloaded.version`. Keep this ADR for
+> builtin static contracts, `handler.match` / uniqueIndexes, `CONFLICT`
+> without auto-retry, and natural-key lookup without system `id`. Read
+> ADR-0022 for caller-observed version on the update branch, create vs
+> update, reserved wire names, and first-party Admin bind.
+
+## Context
+
+Mantle Procedures can bind to standard entry-mutation operations using `handler.kind: builtin` (e.g. `create`, `update`, `delete`, `archive`, `upsert`).
+
+Before this ADR:
+1. **No static contract validation**: Procedure input JSON Schema contracts were not statically verified against the requirements of their builtin operations during manifest linking (`ValidateManifestsUseCase`). Invalid contracts (e.g. `update` missing `id` or `expectedVersion`, nullable union types like `type: ["string", "null"]`, or `archive` on operational Schemas) were only caught at runtime via `requireField` or runtime assertions, causing valid-looking manifests to fail during invocation.
+2. **Missing natural key upsert (`handler.match`)**: Built-in `upsert` only supported legacy ID-based lookup (`id` + `expectedVersion`), requiring client knowledge of internal system IDs. Real-world domains require idempotent upserts matching natural keys (such as `slug`, `siteKey`, or composite unique keys like `[slug, locale]`).
+3. **Concurrency and race conditions**: Matched upsert must handle concurrent writers safely. When two concurrent writers miss preflight lookup, storage-level unique constraints must catch the conflict and surface structured `CONFLICT` diagnostics without retrying or corrupting entries.
+
+## Decision
+
+### 1. Static Contract Validation for Builtin Handlers
+
+Manifest linking (`ManifestGraphValidator.ts`) now validates Procedure `input` schemas against the requirements of their builtin `op`:
+
+- **Diagnostic Code**: `BUILTIN_HANDLER_CONTRACT_INVALID` (phase: `validate`).
+- **Common rule**: `input` must be an `object` schema (`type: "object"`).
+- **`update`**:
+  - `properties.id` must be strict, non-nullable `string` (`type: "string"`, not union array, not `nullable: true`).
+  - `properties.expectedVersion` must be strict, non-nullable `number` (`type: "number"`, not union array, not `nullable: true`).
+  - `required` must include both `"id"` and `"expectedVersion"`.
+- **`delete`**:
+  - `properties.id` must be strict, non-nullable `string`.
+  - `required` must include `"id"`.
+- **`archive`**:
+  - Target Schema must have `lifecycle: "publishing"` (operational Schemas have no lifecycle transitions and cannot be archived).
+  - `properties.id` must be strict, non-nullable `string`.
+  - `required` must include `"id"`.
+- **`upsert` (legacy mode without `match`)** (ADR-0022):
+  - `properties.expectedVersion` must be declared as strict `number`.
+  - If `id` is declared it must be strict `string`. Neither is in `required`
+    because the create branch accepts new entries without IDs or versions.
+
+### 2. Matched Upsert Grammar and Static Contract (`handler.match`)
+
+Procedures with `op: "upsert"` may declare `match`:
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Procedure
+metadata:
+  name: upsertArticleBySlug
+spec:
+  input:
+    type: object
+    properties:
+      slug:
+        type: string
+      title:
+        type: string
+      body:
+        type: string
+      expectedVersion:
+        type: number
+    required:
+      - slug
+      - title
+  output:
+    type: object
+  handler:
+    kind: builtin
+    op: upsert
+    schema: articles
+    match:
+      - slug
+```
+
+**Grammar and parser validation rules (`ManifestParser.ts`)**:
+- `match` is allowed in `spec.handler` only when `handler.kind === "builtin"` and `op === "upsert"`.
+- `match` must be a non-empty array of unique, non-empty field names.
+
+**Static manifest validation rules (`ManifestGraphValidator.ts`)**:
+- `handler.match` must exactly match one declared unique index in the target Schema's `spec.uniqueIndexes` (matching length, field names, and order).
+- Every field in `handler.match` must be declared in the target Schema's `spec.schema.properties`.
+- Every field in `handler.match` must be declared in Procedure `input.properties` and listed in `input.required`.
+- Procedure `input` must NOT declare `id` when using `match`.
+- Procedure `input` **must** declare `expectedVersion` as strict `number`
+  (ADR-0022). It is not globally required: create has no version; update
+  requires the caller token at runtime. Do not overwrite that token with
+  `preloaded.version`.
+
+### 3. Runtime Semantics and Atomic Conflict Handling (`InvokeBuiltinUseCase.ts`)
+
+When executing matched upsert:
+1. Extract matching field values from `input`.
+2. Query existing entry using `entries.findByDataFields({ collection, fields })`.
+3. **If found**: Execute update path (`opUpdate`):
+   - Merge input into existing data using `projectUpdateAndStamp`, preserving omitted fields and system bindings.
+   - Require the caller's `expectedVersion` and pass **that** token to the
+     atomic repository OCC check. Do not use `existing.version` as the token
+     (ADR-0022). Missing token → `INPUT_VALIDATION_FAILED` (do not overwrite).
+   - Pass caller's original input to lifecycle hooks (`before_update` / `after_update`).
+4. **If not found**: Execute create path (`opCreate`) only when the caller
+   omitted `expectedVersion`. A versioned write for a missing row is
+   `NOT_FOUND` (do not recreate).
+   - Project and stamp data using `projectAndStamp`.
+   - Set status to `"published"` (if `lifecycle: "operational"`) or `"draft"` (if `lifecycle: "publishing"`).
+   - Pass caller's original input to lifecycle hooks (`before_create` / `after_create`).
+5. **Concurrency & Race Conditions**:
+   - Both update and create operations are wrapped in `withConflictDiagnostic`.
+   - Storage-level unique constraint violations (e.g. SQLite `SQLITE_CONSTRAINT_UNIQUE`, Postgres `23505`) and version/status mismatches are converted into structured `CONFLICT` diagnostics (HTTP 409).
+   - The runtime does not automatically retry matched upsert on conflict, providing deterministic failure semantics under race conditions.
+
+## Consequences
+
+- **Fail-fast authoring**: Schema and Procedure mismatches are detected during `mantle validate` or test time rather than failing unpredictably at runtime.
+- **Strict type safety**: Nullable union types cannot bypass static contract validation.
+- **Natural key idempotency**: Clients can author natural-key upsert procedures for ingestion and sync pipelines without managing internal mantle IDs.
+- **Safe concurrency across all adapters**: Concurrent writes are guarded by storage-level unique constraints (SQLite/D1 unique indexes, IndexedDB readwrite transaction assertions) and translated to standard `CONFLICT` diagnostics via typed `EntryUniqueConflict`.
+
+## Alternatives considered
+
+1. **Automatic retry loops on conflict**: Considered having `InvokeBuiltinUseCase` automatically re-query and retry upon catching unique collisions. Rejected because repeated attempts could fire lifecycle hooks (`before_create` / `before_update`) multiple times with unintended side effects (e.g. duplicate webhook notifications or rate limits) and mask true contention. Failing fast with a structured `CONFLICT` diagnostic gives caller control.
+2. **Arbitrary field matching without Schema unique indexes**: Considered allowing `handler.match` on arbitrary Schema properties. Rejected because storage engines cannot enforce uniqueness without dedicated unique constraints/indexes, which would result in race conditions and duplicate entries under concurrent traffic.
+3. **Permissive nullable unions**: Considered allowing `type: ["string", "null"]` in Procedure input schemas for `id`. Rejected because runtime entry mutations strictly require non-null scalar identifiers; allowing nullable schemas would let schema-valid requests crash inside builtin handlers.
+
+## How to apply
+
+1. **Declare Schema Unique Indexes**:
+   ```yaml
+   apiVersion: cms.mantle.aotter.net/v1
+   kind: Schema
+   metadata:
+     name: site-settings
+   spec:
+     title: Site Settings
+     lifecycle: publishing
+     schema:
+       type: object
+       required: [siteKey, theme]
+       properties:
+         siteKey: { type: string }
+         theme: { type: string }
+     uniqueIndexes:
+       - [siteKey]
+   ```
+
+2. **Author a Matched Upsert Procedure**:
+   ```yaml
+   apiVersion: cms.mantle.aotter.net/v1
+   kind: Procedure
+   metadata:
+     name: setSiteSetting
+   spec:
+     input:
+       type: object
+       required: [siteKey, theme]
+       properties:
+         siteKey: { type: string }
+         theme: { type: string }
+         expectedVersion: { type: number }
+     output:
+       type: object
+     handler:
+       kind: builtin
+       op: upsert
+       schema: site-settings
+       match: [siteKey]
+   ```
+
+3. **Validate**:
+   Run `mantle validate` to verify input contracts against the declared unique indexes and schema properties.
+
+## Implementation status
+
+- **`@aotter/mantle-spec`**:
+  - `ManifestGrammar.ts`: Added `match?: readonly string[]` to `HandlerBuiltinBinding`.
+  - `diagnostic.ts`: Added `BUILTIN_HANDLER_CONTRACT_INVALID` to `DIAGNOSTIC_CODES`.
+  - `ManifestParser.ts`: Parser-level validation for `handler.match`.
+  - `ManifestGraphValidator.ts`: Static input contract validation in `checkBuiltinHandler`.
+- **`@aotter/mantle-runtime`**:
+  - `EntryRow.ts`: Added `EntryUniqueConflict` domain error.
+  - `EntryMutationDiagnostics.ts`: `withConflictDiagnostic` converts `EntryUniqueConflict` to `CONFLICT` diagnostic (HTTP 409).
+  - `DatabaseEntryRepository.ts`: SQLite/Postgres unique constraint violation translation to `EntryUniqueConflict`.
+  - `InvokeBuiltinUseCase.ts`: Matched upsert execution via `findByDataFields` and `projectUpdateAndStamp`.
+- **`@aotter/mantle-indexeddb`**:
+  - `IndexedDbEntryRepository.ts`: Atomic transaction-level unique index enforcement and `EntryUniqueConflict` emission.
+- **Documentation**:
+  - `docs/adr/0020-builtin-handler-contracts-and-matched-upsert.md` (this document).
+  - `docs/adr/README.md`.
+  - `docs/design-atoms.md`.

package/docs/adr/0021-retire-starter-scaffolding.md

@@ -0,0 +1,30 @@
+# ADR-0021: Author applications directly; retire Starter scaffolding
+
+Status: Accepted by owner, 2026-09-08 (#786). Supersedes ADR-0018 for the 0.1.2 line.
+
+Core is an embeddable manifest engine. Applications own package manifests,
+Worker entries, provider configuration, business manifests and visitor UI.
+Core no longer creates those files from a Starter bundle. Remove `create` and
+the Starter three-way `update` CLI, their bundle renderer/export, and the
+cross-repository Starter/Landing release gates. Legacy consumers retain the
+immutable 0.1.0-alpha.17 packages, tags and URLs.
+
+`generate` remains an explicit compiler for existing manifests and optional
+installed Admin UI assets. It must not initialize a missing project or invent
+a default Schema, frontend or home route. Web remains optional runtime
+composition, with consumer-provided templates and routes.
+
+Version-matched install/update skills describe direct authoring and reviewed
+SDK dependency upgrades. Existing project source, provider identity, secrets
+and legacy metadata remain user-owned. No replacement init/template command,
+new preset registry or Builder/Platform implementation belongs to this change.
+
+A small Core-owned reference consumer proves generation and a running Worker
+against exact packed packages and public registry candidates. It is a test and
+worked example, not a downloadable scaffolder or another launch product.
+Useful transaction Queue/DO patterns remain documented with immutable sources.
+
+Release ownership stays in the existing Core controller: source and packed
+consumer gates → immutable tag → verified registry candidates → public-registry
+consumer gate → monotonic channels → GitHub release. No downstream repo writer
+is required. Wrong public artifacts still require fixing forward; no retagging.

package/docs/adr/0022-caller-observed-version-occ.md

@@ -0,0 +1,212 @@
+# ADR-0022: Caller-observed `expectedVersion` for Admin and builtin upsert
+
+**Status:** Accepted
+
+**Date:** 2026-09-14
+
+**Related:** [#850](https://github.com/aotter/mantle/issues/850),
+[ADR-0020](0020-builtin-handler-contracts-and-matched-upsert.md)
+
+## Context
+
+ADR-0020 remains the authority for builtin static contracts, `handler.match`
+matching a declared unique index, natural-key lookup without a system `id`,
+and `CONFLICT` without automatic retry.
+
+Its **matched-upsert OCC** rule is outdated. Matched upsert forbade
+`expectedVersion` on the Procedure input and, at runtime, substituted the
+preloaded row's `version` for the caller's token. ID-based upsert did the same
+whenever a preloaded row was supplied. The repository still rejected races
+*after* the handler read, but a change made since the **client** read the row
+was overwritten.
+
+Admin rendered `expectedVersion` as an editable number. Operators had to type
+a technical version, or a handler that re-read at submit time quietly dropped
+read-time protection. Downstream (mantle-home organization quota) reproduced
+this.
+
+The intended contract: callers POST the **observed** native `entry.version`
+from read time. Mantle enforces that token atomically. A successful write
+still bumps storage to `expectedVersion + 1`. The token is **not**
+`version + 1`.
+
+## Decision
+
+### 1. Wire semantics
+
+`expectedVersion` is the observed native `entry.version` at read time.
+
+- Successful repository writes still persist `expectedVersion + 1`.
+- Callers must not send the next version.
+- Core does **not** auto-inject `expectedVersion` into Manifests. Authors
+  declare it. Omit → fail-closed `BUILTIN_HANDLER_CONTRACT_INVALID`.
+
+### 2. Closed reserved wire names
+
+The reserved Procedure input wire name for OCC is `expectedVersion`. Business
+fields must not collide with it. Schema `spec.schema.properties` must not
+declare `expectedVersion`; validate fails closed (`INVALID_MANIFEST_ENVELOPE`)
+so `projectUpdateAndStamp` cannot copy the OCC token into `data`. New reserved
+wire names require an ADR. OCC behaviour must not depend on `x-mcp-hint`. The
+magic word is the property name only.
+
+### 3. Static contracts (amends ADR-0020 §2 matched upsert)
+
+Keep ADR-0020 for `update` (`id` + `expectedVersion` both strict and
+required), `delete`/`archive` (`id` required), `handler.match` vs
+`uniqueIndexes`, and forbidding `id` on matched upsert.
+
+**Matched upsert (`op: upsert` + `match`):**
+
+- `input.properties.expectedVersion` **must** be a strict, non-nullable
+  `number`.
+- `expectedVersion` is **not** globally required: the create branch has no
+  version. Authors may list it in `required` only when the Procedure is
+  update-only.
+- `input` must still **not** declare `id`.
+
+**ID-based upsert (`op: upsert` without `match`):**
+
+- `input.properties.expectedVersion` **must** be a strict `number` (fail-closed
+  if omitted). It is not in `required`.
+- If `id` is declared, it must be a strict `string`. Neither `id` nor
+  `expectedVersion` is required, so create can omit both.
+
+### 4. Runtime (amends ADR-0020 §3)
+
+Intent is the presence of a finite numeric `expectedVersion`, not the
+presence of an id or a preload hit.
+
+| Branch | Caller token | Existing row | Result |
+|---|---|---|---|
+| Create | absent | none | `create` (no version) |
+| Create race | absent | unique collision after miss | `CONFLICT`; no silent overwrite |
+| Update | present | found | atomic OCC with **caller** token; never `preloaded.version` |
+| Update, stale | present | found, version ≠ token | `CONFLICT`; no retry |
+| Update, missing | present | none (deleted / unknown) | `NOT_FOUND`; do **not** create |
+| Create-intent vs existing | absent | found | `INPUT_VALIDATION_FAILED`; do **not** overwrite |
+
+`opUpdate` always reads `expectedVersion` from caller input when a versioned
+write is attempted. Preload supplies identity (`id`) and PATCH base data only.
+
+There is still **no automatic retry**.
+
+### 5. First-party Admin / SDK bind (not grammar)
+
+When Procedure `input` declares `expectedVersion`, first-party Admin (and any
+first-party SDK helper) treats the name as magic:
+
+- Auto-bind the OCC target row's current `version` captured at read.
+- Hide the field from the editable form (same UX idea as
+  `x-mcp-hint: idempotency-key`, keyed by reserved **name**).
+- A resolvable OCC target (row menu, `id` in the form, or
+  `targetCollection` binding) **must** be bound before submit is enabled,
+  including matched upsert where `expectedVersion` is declared but not
+  globally required (opening from a row is update-path intent).
+- If `expectedVersion` is in `input.required` and no OCC target can be
+  resolved, submit stays disabled (do not invent a version).
+- Collection create / no-row dialogs may omit the token when it is not
+  required (create branch).
+- Rebind when the selected target changes. An organization row must not
+  supply `expectedVersion` for a membership mutation.
+- On `CONFLICT` / HTTP 409: keep operator business inputs; require an
+  explicit re-read; **no** auto-retry with the latest version.
+- Background refetches of the same target must not replace a captured
+  token while the form still holds older values.
+
+Other callers (HTTP Trigger, MCP, custom clients) supply the observed
+version themselves. Magic bind/hide is first-party only.
+
+OCC target for Admin bind:
+
+1. If `input` declares `id`, the target is `form.id` (the membership / row
+   being mutated), never a merely contextual parent ref.
+2. Else if the Procedure is builtin, prefer the `rowBindings` entry whose
+   `collection` equals `handler.schema`.
+3. Else if another row binding (not the launch collection) identifies an
+   entry id, use that once filled.
+4. Else use the launch row (quota-style actions bound only to that row).
+
+A not-yet-existing target has no version: omit `expectedVersion` so upsert
+takes the create branch.
+
+### 6. Compatibility
+
+This is a **breaking** change for:
+
+- Matched-upsert Manifests that omitted `expectedVersion` (now fail
+  validate).
+- Callers that updated via matched or ID-based upsert without sending an
+  observed version (preload OCC). Those writes now fail closed instead of
+  overwriting with the version read inside the handler.
+- Matched-upsert Manifests that declared `expectedVersion` (previously
+  rejected; now required as a property).
+
+Callers that already sent the observed version on `op: update` are
+unchanged. HTTP and MCP share the Procedure input contract; only Admin/SDK
+auto-fill the reserved name.
+
+## Consequences
+
+- Read-time OCC works through Admin forms, HTTP Triggers, and MCP for both
+  `update` and version-checked upsert.
+- Create remains possible without a version; a versioned write cannot
+  silently recreate a deleted row.
+- AI authors must declare `expectedVersion` as a strict number on OCC
+  builtins. Tool descriptions state **observed** version, not `+1`.
+
+## Alternatives considered
+
+1. **`x-mcp-hint: entry-version`.** Rejected. OCC must not depend on hints;
+   the reserved property name is the contract.
+2. **Keep preload OCC for matched upsert.** Rejected. Accepting
+   `expectedVersion` and ignoring it is worse than forbidding it.
+3. **Require `expectedVersion` in `input.required` for every upsert.**
+   Rejected: that makes create impossible at validate time.
+4. **Auto-retry upsert on `CONFLICT`.** Rejected in ADR-0020; unchanged.
+5. **Auto-inject the property into Manifests.** Rejected: fail-closed
+   grammar; authors (often agents) must see the field.
+
+## How to apply
+
+```yaml
+apiVersion: cms.mantle.aotter.net/v1
+kind: Procedure
+metadata:
+  name: upsert-membership
+spec:
+  input:
+    type: object
+    required: [organizationId, userId, role]
+    properties:
+      organizationId: { type: string, x-mantle-ref: organizations }
+      userId: { type: string }
+      role: { type: string }
+      expectedVersion: { type: number }
+  output:
+    type: object
+  handler:
+    kind: builtin
+    op: upsert
+    schema: organization-members
+    match: [organizationId, userId]
+```
+
+- Create: `{ organizationId, userId, role }` — no version.
+- Update: the same fields plus `expectedVersion` equal to the membership
+  row's current `version`.
+- Stale token → `CONFLICT` (409). Deleted membership + token → `NOT_FOUND`.
+
+## Implementation status
+
+- `@aotter/mantle-spec`: `ManifestGraphValidator` / parser fail-closed
+  `expectedVersion` on upsert; Schema `spec.schema.properties` must not
+  declare reserved Procedure input names; `EXPECTED_VERSION_PROPERTY`
+  reserved name.
+- `@aotter/mantle-runtime`: `InvokeBuiltinUseCase` uses the caller token;
+  MCP catalog copy states observed version.
+- `@aotter/mantle-admin` / `@aotter/mantle-admin-ui`: operations expose
+  builtin `targetCollection`; Admin binds and hides `expectedVersion`,
+  and does not enable submit on a resolvable OCC target until the
+  observed version is captured.
+- Docs: this ADR, ADR-0020 amendment pointer, design-atoms, handbook.

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

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

package/docs/adr/README.md

@@ -18,8 +18,11 @@ Records of *why* mantle ended up shaped this way. The numbering preserves POC AD
 | [0014](0014-auth-better-auth-and-multi-tenant-mcp.md) | The Cloudflare adapter owns one curated Better Auth 1.7 identity/OAuth/MCP authority with CIMD discovery. Verified callers are normalized into runtime context; mutable staff role and target authorization are re-evaluated per call. | Accepted + amended |
 | [0016](0016-site-semantic-layer.md) | Site semantic layer: `AGENTS.md` (cross-tool entry) + `.mantle/launch-state.json` (deterministic install context). The older `mantle/site.md` letter surface is suspended from first-run scaffolds. | Accepted (slimmed) |
 | [0017](0017-media-multi-variant-agent-side-optimization.md) | Multi-variant media assets with agent-side optimization and asset-id entry references. | Accepted |
-| [0018](0018-core-starters-repository-boundary.md) | Core produces published SDK artifacts; the separate starters repository validates them as an external consumer. Revisit after release-contract simplification. | Accepted for now |
+| [0018](0018-core-starters-repository-boundary.md) | Core produces published SDK artifacts; the separate starters repository validates them as an external consumer. Revisit after release-contract simplification. | Superseded by 0021 |
 | [0019](0019-sealed-manifest-runtime-pipeline.md) | One sealed source-to-runtime pipeline, semantic storage seam, and optional Web/Admin/platform dependency direction. | Accepted |
+| [0020](0020-builtin-handler-contracts-and-matched-upsert.md) | Static builtin handler contracts and natural-key matched upsert (`handler.match`). | Accepted + amended by 0022 |
+| [0021](0021-retire-starter-scaffolding.md) | Direct authoring; retire Starter scaffolding. | Accepted; supersedes 0018 |
+| [0022](0022-caller-observed-version-occ.md) | Caller-observed `expectedVersion` for Admin bind and builtin upsert OCC. | Accepted |
 
 ## Reading order
 
@@ -31,7 +34,7 @@ If you're new to the codebase:
 4. **0007** — what running the SDK feels like as an AI author (and as the operator agent).
 5. **0011** — the boundary between the runtime and the adapter.
 6. **0010** — how locale flows through the system.
-7. **0013** — historical install-session context; current first launch is landing provision bundles plus repo-local handoff.
+7. **0021** — current direct-authoring boundary; **0013** is historical install-session context.
 8. **0002, 0008** — the two ADRs that touch every diagnostic and every binding.
 
 ## What's NOT here (and why)
@@ -54,8 +57,20 @@ The rebuild's ADR-0011 (new) is the most load-bearing addition — the POC accum
 
 ## Contributing a new ADR
 
-1. Pick the next number (currently 0020).
+1. Pick the next unused number after the highest existing ADR.
 2. File: `docs/adr/<NNNN>-<kebab-title>.md`.
 3. Sections: Status, Date, Context, Decision, Consequences, Alternatives, How to apply, Implementation status.
 4. Link from this README's table.
 5. Land it in a PR alongside (or before) the implementation it documents — ADR-as-design-artifact, not ADR-as-archaeology.
+
+## ADR-lite records
+
+These retain their issue-based filenames and original decision status.
+
+| Record | Status |
+|---|---|
+| [#803 Request diagnostics](adr-lite-803-request-diagnostics.md) | Implemented |
+| [#808 Route readiness](adr-lite-808-route-readiness.md) | Accepted |
+| [#809 Bounded public content](adr-lite-809-bounded-public-content.md) | Implemented |
+| [#812 Native parity](adr-lite-812-native-parity.md) | Implemented; deployment evidence linked in record |
+| [#823 Home statistics](adr-lite-823-home-statistics.md) | Proposed; unmerged demo |

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

@@ -0,0 +1,38 @@
+# ADR-lite: request-scoped Cloudflare diagnostics
+
+Status: implemented diagnostic record for #803; real-auth controls and measured
+comparison acceptance belong to the #812 harness. This does not close the
+separate starter provisioning/Smart Placement portion of #803.
+
+Use native AsyncLocalStorage and a small versioned testing entry point instead of
+a global current-request counter or a configurable production telemetry system.
+Production mounts only check for an existing test context. With none, there are
+no diagnostic clock reads, binding wrappers, records, observers or response headers.
+Runtime, auth, role, catalog, dispatcher-build and dispatch retain their ownership
+and authorization order. The ordinary runtime-ready promise keeps its identity.
+
+Native D1 instrumentation sits beneath both Auth and Runtime and is idempotent.
+It preserves receivers, bind chains, first-column behavior and native objects in
+batches; no second driver observer is added for counting. Provider failures and
+unknown metadata remain visible. Request context is captured when an operation
+starts, so shared work belongs to its initiator. Catalog waiters inherit source
+classification and wait time without inheriting the owner's binding counts.
+
+The record freezes at response creation. Inclusive spans can overlap, and partial
+metadata or deferred work must not be presented as a full total. A test-only cloned
+MCP response supplies the JSON-RPC outcome without exposing its content; that
+inspection is outside totalMs but remains instrumentation overhead for HTTP timing.
+Observer errors never replace application results. D1/KV/R2 operations emit only
+counts, sizes with their source/coverage, and durations; object keys, SQL, caller
+identities and credentials never enter the record.
+
+R2 GET bodies stay native. Successful direct stream-to-PUT completion confirms
+payload bytes; canceled, incomplete and unconsumed reads remain unknown. This
+avoids losing R2's known-length stream property or hiding buffering overhead.
+
+Checks deliberately overlap MCP requests and share KV hit/failure loads, then
+retry after failure. Native I/O is counted once per owner, and denied requests
+leave unreached phases null. Additional checks preserve native D1 private receiver
+and batch semantics, sync/async observer failure, immutable deferred snapshots,
+R2 stream identity and partial-transfer uncertainty. The collector fixture labels
+its deterministic auth explicitly; it is not evidence of native-auth parity.

package/docs/adr/adr-lite-808-route-readiness.md

@@ -0,0 +1,47 @@
+# Route-owned Cloudflare readiness (#808)
+
+Status: accepted for the unreleased #806–812 implementation. Follows ADR-0019
+(preparation owns migrations) and amends ADR-0014's unconditional HTTP boot rule.
+
+The facade assembles immutable route projections once, then prepares only for
+routes that consume canonical storage. It retains one retryable preparation
+promise, the sealed plan and Better Auth's existing global AsyncLocalStorage,
+`ready` observation, failed-assembly eviction and HTTP `waitUntil` ownership.
+
+| Surface | Readiness, including an empty database |
+| --- | --- |
+| Consumer constant health, `/api/views` catalog | No content preparation. |
+| Static Admin shell and assets | No content preparation; incomplete Auth still fails closed as before. |
+| Manifest View/Trigger | Prepare before credential resolution, then use the same runtime invocation. |
+| Admin API, configured Auth base path, OAuth UI/discovery | Prepare before session/provider work. Auth tables share canonical migrations. |
+| MCP, including missing-token challenge | Prepare before the selected Auth verifier. A custom Auth implementation may require D1 even for a denied request; the facade cannot assume otherwise. |
+| Public page/list/discovery and favicon fallback | Their existing `ref.get()` starts preparation when content is needed. |
+| Consumer extension handlers | Call the supplied `getRuntime()` or `ref.get()` before using Mantle content or database-backed Auth. Pure handlers need neither. |
+| Queue/scheduled `getRuntime(env)` | Await both runtime preparation and Auth initialization, unchanged. |
+
+No deployment-time migration flag or KV readiness authority is introduced. A
+current database's first protected route needs one fingerprint SELECT; an empty
+or changed database performs canonical setup there. Concurrent first uses share
+that work. A failed preparation returns the facade's redacted 500, and later
+requests retry. Static availability is not a promise that data is ready.
+
+The pre-change full-facade fixture recorded 106 SQL operations for its empty-DB
+health request (its four Schemas include indexes), then 1 fingerprint operation
+for each new-state health/catalog/shell/challenge. These are statement counts,
+not network round trips. Its dry-run bundle was 3,921.40 KiB / 690.43 KiB gzip
+with Wrangler 4.124.0 and compatibility date 2026-07-08. Esbuild attributed
+1,342,428 emitted bytes to Better Auth, 76,078 to Admin, 24,624 to Web and
+203,130 to Runtime; the rest includes transitive libraries and adapter code.
+Byte attribution does not measure startup CPU. We retain static imports and
+immutable mount-time projections: deferring those modules has not yet been
+justified by a startup profile. The final #812 report owns the separate startup,
+preparation-wall and warm-dispatch measurements.
+
+Post-change full-facade workerd checks pass all 13 operation gates: empty-DB
+health and fresh-state health/catalog/shell perform zero **content** queries;
+the challenge retains its one fingerprint query. The fixture Auth is a stated
+stub. A separate real Better Auth regression records one eager oauthResource
+lookup while `ready` initializes; Better Auth 1.7.2 defers missing-table resource
+seeding to first access. Subsequent static requests perform no additional Auth
+queries. This background initialization is retained, not counted as eliminated
+content preparation or hidden behind a zero-total-SQL claim.