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

package/docs/adr/0014-auth-better-auth-and-multi-tenant-mcp.md

@@ -625,3 +625,103 @@ OAuth store and is not renamed by this decision.
 This amendment adopts the 2026-07-28 CIMD authorization profile only. Updating
 Mantle's JSON-RPC dispatcher to the complete MCP 2026-07-28 transport revision
 is a separate decision.
+
+## 2026-09-07 amendment — shared OAuth surfaces and revocation
+
+OAuth product UI is not owned by a runtime adapter. `@aotter/mantle-admin`
+owns `MantleOAuthAuth`, the consent/connected-app view models, and
+`handleMantleOAuth(Request) -> Response | null`; `mountMantleOAuth` is a thin
+Hono bridge. The Cloudflare adapter implements protocol actions using the
+same Better Auth instance and D1. Future adapters reuse this contract, not
+Cloudflare-specific UI glue. The old `mountAuthorize` export remains an alias.
+
+`@aotter/mantle-admin-ui` owns the React/shadcn sign-in, consent and connected
+apps surfaces, including i18n, theme and submit state. Auth pages initially
+follow the system theme; the light/dark toggle persists an explicit override.
+Connected apps has an Admin page, but managing one's own grants requires only
+a session, never a staff role. The no-assets HTML fallback uses native forms
+without JavaScript or a second implementation of the Admin design system.
+Both mounts retain same-origin mutation checks and private/no-store responses.
+The consent document's CSP permits only the provider-validated callback
+origin for the browser's form redirect; it never trusts an unsigned query.
+
+MCP authorization remains session-bound: the JWT's original Better Auth
+session must still exist and be unexpired. Admin sign-out/session expiration
+therefore also ends that session's MCP access. A refresh token is not an
+independent authorization to bypass this check. Staff roles are still read
+fresh on every protected request.
+
+Disconnect is scoped to the authenticated user and the selected client. It
+revokes refresh/opaque access tokens, removes pending authorization codes and
+consent rows, and prevents existing JWTs from becoming valid when the client
+is connected again. The verification-create hook captures the consent row ID
+in Better Auth's existing authorization `referenceId`; Better Auth carries it
+through the authorization code and every refresh rotation. MCP JWTs copy that
+reference into `mantle_consent_id`, which must match the active consent row.
+Never look up a new consent at token mint time: doing so could revive a refresh
+lineage whose insertion raced the revoke batch. Same-second reconnect and a
+delayed old refresh row are required regression cases, not clock delays.
+
+MCP mode reserves authorization `referenceId` for this grant identity; future
+curated configuration must not also expose Better Auth's `postLogin` reference
+hooks. MCP access requires a persisted user consent, so `skipConsent` and
+`cachedTrustedClients` must not bypass consent for MCP clients.
+
+This alpha hotfix requires existing MCP clients to reconnect once: pre-hotfix
+JWTs without the grant claim are rejected immediately. No account/session reset
+is required. The unshipped watermark migration 0008 is removed; its unused
+table in the phsu development database is harmless and is not queried or
+deleted during deployment.
+
+## 2026-09-08 amendment — request security boundaries
+
+All Admin session mutations use the existing same-origin guard, including
+same-site sibling origins. Admin HTML forbids framing and is private/no-store.
+The SPA also refuses to render in frames, covering direct static-asset URLs
+that bypass the server mount.
+The Admin/auth mounts cap request bodies at 1 MiB using Hono's body limiter;
+HTTP trigger and MCP dispatchers count streamed JSON bytes before parsing and
+return 413 above the same limit. Media bytes continue through direct uploads.
+This intentionally rejects previously accepted larger control-plane payloads.
+
+Cloudflare `createAuth` explicitly enables Better Auth rate limits regardless
+of `NODE_ENV`, including the OAuth provider's anonymous registration limit of
+five requests per minute. Only `CF-Connecting-IP` supplies the client key.
+The upstream memory store limits each isolate; deployments needing a shared
+abuse quota must additionally enforce it at ingress. No D1 migration or new
+runtime platform dependency is introduced.
+
+Workers must retain initialization work through `ExecutionContext.waitUntil`
+even when the initial challenge finishes or its client disconnects. Schema
+boot precedes OAuth handling. The adapter's static AsyncLocalStorage seeding
+is a version-pinned Better Auth 1.7.2 integration, with accessor-identity
+regression coverage; it does not replace Better Auth's request context.
+Failed Auth initialization evicts only the failed Worker assembly so a later
+request can retry. Non-HTTP callers await Auth initialization with runtime boot;
+HTTP requests anchor it without making public responses depend on Auth health.
+
+The conventional `/favicon.ico` reflects the configured site icon, but is a
+fallback after consumer routes, not a newly reserved namespace. Existing
+consumer icon routes must continue to work after a package update.
+
+## Amendment — 2026-09-14: Host-only control-plane cookies
+
+`CreateAuthConfig.hostOnlyCookies` is an opt-in, curated auth field for a
+control plane on a parent domain shared with tenants. It uses native `__Host-`
+cookie names, `Secure`, `Path=/` and no `Domain`; HTTPS is required and enabling
+cross-subdomain sharing at the same time is rejected. Existing defaults and
+Apple's `SameSite=None` requirement remain unchanged. Consumers must treat
+switching cookie names as an explicit sign-in migration, not rewrite request
+or response cookies. This keeps cookie semantics in the auth adapter rather
+than requiring each consumer to wrap Admin, member and OAuth routes.
+
+## Amendment — 2026-09-16: deployment KV session reads
+
+Cloudflare deployments may pass their deployment-owned KV namespace as
+`CreateAuthConfig.sessionCacheKv`. Better Auth reads sessions from KV while
+keeping the canonical session row in D1. OTP verification remains D1-backed
+and rate limiting remains isolate-local because Workers KV does not provide
+the atomic consume or increment operations those paths require. Auth keys use
+the `better-auth:` prefix so the namespace can also hold Mantle projections.
+Session revocation and user updates use Better Auth's cache invalidation and
+therefore follow Workers KV's propagation model.

package/docs/adr/0018-core-starters-repository-boundary.md

@@ -1,5 +1,8 @@
 # ADR-0018: Keep Core and public starters in separate repositories
 
+> Superseded for 0.1.2 by [ADR-0021](0021-retire-starter-scaffolding.md).
+> The contract below is retained as alpha.17 history, not current launch/release guidance.
+
 **Status:** Accepted for now; revisit only under the triggers below
 
 **Date:** 2026-08-02

package/docs/adr/0019-sealed-manifest-runtime-pipeline.md

@@ -2,10 +2,12 @@
 
 **Status:** Accepted
 
-**Date:** 2026-08-16
+**Date:** 2026-08-16; last amended 2026-09-01
 
 **Related:** [#656](https://github.com/aotter/mantle/issues/656),
 [#662](https://github.com/aotter/mantle/issues/662),
+[#759](https://github.com/aotter/mantle/issues/759),
+[#760](https://github.com/aotter/mantle/issues/760),
 [#546](https://github.com/aotter/mantle/issues/546), ADR-0008, ADR-0009,
 ADR-0011, ADR-0018
 
@@ -67,7 +69,7 @@ semantic fingerprint.
 | Parse + normalize | YAML syntax/alias limits, closed four-atom shape, primitive and atom-local rules, behavior-affecting defaults, source metadata | Cross-atom references, handlers, storage, optional routes |
 | Link | Duplicate symbols, cross-atom references, guard graphs, translations, manifest-owned route/tool collisions | I/O, selected modules, handler availability |
 | Compile | Immutable lookup records, authorization plans, Trigger indices, Procedure descriptors, logical View plans, semantic fingerprint | Connections, repositories, handlers, requests, templates, assets |
-| Prepare | Selected storage migrations/indexes/native Views, handler availability, selected capability/route checks, readiness revision | YAML interpretation or request execution |
+| Prepare | Selected storage migrations/native Schema tables and indexes/prepared Views, handler availability, selected capability/route checks, readiness revision | YAML interpretation or request execution |
 | Bind/invoke | Semantic ports, handler dispatch, parameter binding, centralized authorization, content/View/Procedure/Trigger/lifecycle operations | DDL, route mounting, assets, HTTP/session/cache policy |
 | Optional modules/adapters | Web/Admin composition and request/session/cache/platform translation | Re-parsing, re-linking, or a second authorization/runtime stack |
 
@@ -106,11 +108,45 @@ Concrete D1/SQLite drivers and SQL repositories remain implementation details.
 An existing application may either pass its already-owned database/client to
 an official adapter or implement the semantic ports over its own tables.
 
+`@aotter/mantle-indexeddb` is the optional browser storage implementation of
+the same semantic ports. One adapter exclusively owns one application-selected
+database name, uses structured-clone persistence and IndexedDB transaction
+completion as its write boundary, and exposes database deletion only on the
+concrete adapter. Runtime Core gains no browser global, browser facade,
+namespace, persistence request, reactive binding, or synchronization port.
+Declarative browser Views use a documented O(n) scan until measured use proves
+an IndexedDB query planner necessary.
+
 Declarative Views compile to logical plans once. Storage preparation lowers
 those plans to native queries. The v0.1 `View.spec.sql` form remains explicitly
 SQLite-only and is rejected by unsupported storage during preparation; Mantle
 does not guess a translation and does not add a universal query driver.
 
+### Callable capability projection
+
+Optional callable transports consume `projectCallableCapabilities(RuntimePlan)`.
+Each Procedure capability retains the owning MCP Trigger name while its
+input/output/title/description remain owned by the target Procedure; View
+capabilities retain their read-only View contract. Discovery and invocation use
+the same projected descriptor, and invocation routes through `invokeTrigger`
+rather than bypassing Trigger identity with a direct Procedure call. Hosts may
+select a surface and bind transport or browser lifecycle, but do not rescan raw
+manifests or maintain a second registry.
+
+`@aotter/mantle-web/webmcp` is an opt-in host binding over that projection. It
+feature-detects `document.modelContext`, adds public capabilities without
+replacing existing host tools, and uses the registration `AbortSignal` only for
+teardown. A browser-local host supplies the projected capabilities and a
+late-bound invoker; Procedure calls retain their explicit MCP Trigger identity.
+For a server-backed host, the Cloudflare adapter publishes a minimal public View
+catalog at `GET /api/views`; the binding validates that wire catalog and invokes
+the existing same-origin `GET /api/views/<name>` route. The catalog contains no
+raw manifest or staff capability.
+Invocation hooks may drive host UI effects but cannot replace Runtime
+validation, authorization, dispatch, or domain results. The binding does not
+add browser globals to Runtime Core, expose staff capabilities, or introduce a
+second manifest/runtime path.
+
 ### Naming and code generation
 
 The Core execution unit is `MantleRuntime`, not a site. Optional TypeScript

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.