@aotter/mantle 0.1.0-alpha.13 → 0.1.0-alpha.15

package/docs/adapter-guide.md

@@ -106,6 +106,15 @@ optional `/libsql` subpath adapts a caller-owned remote Turso/libSQL client to
 the canonical SQLite chain; the default entry has no database-vendor policy.
 Vercel's read-only filesystem and writable `/tmp` are never durable state.
 
+### Browser IndexedDB embedding
+
+`@aotter/mantle-indexeddb` implements the same required semantic storage ports
+over one application-owned IndexedDB database. It keeps browser globals out of
+Runtime Core, supports declarative Views with a documented O(n) collection
+scan, and exposes `deleteDatabase()` only on the concrete adapter. The host owns
+database naming, `navigator.storage` persistence requests, active-runtime
+selection, UI invalidation, and any remote synchronization.
+
 ## HTTP and MCP surfaces
 
 The runtime is a library, not an HTTP server. A new adapter must mount equivalent framework routes:

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

@@ -2,10 +2,12 @@
 
 **Status:** Accepted
 
-**Date:** 2026-08-16; last amended 2026-08-31
+**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
 
@@ -106,6 +108,15 @@ 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
@@ -123,11 +134,18 @@ 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`, registers only public View
-capabilities, invokes the existing same-origin View REST route, and uses the
-registration `AbortSignal` for teardown. It does not add browser globals to
-runtime Core, expose staff/mutating capabilities, or introduce a second
-manifest/runtime path.
+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
 

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

@@ -0,0 +1,178 @@
+# ADR-0020: Builtin Handler Contracts and Matched Upsert
+
+**Status:** Accepted
+
+**Date:** 2026-09-01
+
+**Related:** [#765](https://github.com/aotter/mantle/issues/765),
+[#766](https://github.com/aotter/mantle/issues/766),
+ADR-0008, ADR-0010, ADR-0014, ADR-0019
+
+## 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`)**:
+  - If either `id` or `expectedVersion` is declared, both must be declared with strict string and number types respectively. Neither is in `required` because the create branch accepts new entries without IDs.
+
+### 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
+    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` or `expectedVersion` when using `match`.
+
+### 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.
+   - Use `existing.id` and `existing.version` for optimistic concurrency control (OCC).
+   - Pass caller's original input to lifecycle hooks (`before_update` / `after_update`).
+4. **If not found**: Execute create path (`opCreate`):
+   - 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 }
+     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/README.md

@@ -20,6 +20,7 @@ Records of *why* mantle ended up shaped this way. The numbering preserves POC AD
 | [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 |
 | [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 |
 
 ## Reading order
 

package/docs/design-atoms.md

@@ -690,24 +690,27 @@ spec:
     kind:   builtin
     op:     create | update | upsert | delete | archive
     schema: <Schema metadata.name>
+    match:  [ <field>, ... ] # optional; only valid for op: upsert
 ```
 
-| op | Behavior |
-|---|---|
-| `create` | INSERT a new row. Project `input ∩ Schema.spec.schema.properties`; stamp `x-mantle-bind` fields; generated id; status is `draft`, or immediately `published` for `lifecycle: operational`. |
-| `update` | UPDATE in place. `input.id` + `input.expectedVersion` (OCC) required. Bumps version. |
-| `upsert` | If `input.id` resolves, behaves as `update`; else as `create`. |
-| `delete` | Hard DELETE by id. |
-| `archive` | Soft-archive a publishing entry (`status='archived'`). |
+| op | Behavior | Input Contract Requirements |
+|---|---|---|
+| `create` | INSERT a new row. Project `input ∩ Schema.spec.schema.properties`; stamp `x-mantle-bind` fields; generated id; status is `draft`, or immediately `published` for `lifecycle: operational`. | `input` must be an object schema. |
+| `update` | UPDATE in place. Merges patch with existing data via `projectUpdateAndStamp`. Bumps version. | `input.id` (strict string) and `input.expectedVersion` (strict number) are required in `input.required`. |
+| `upsert` | If `match` is declared, queries by matched natural key fields: if found, updates the row via `projectUpdateAndStamp` using the row's existing version; if not found, creates a new row. If `match` is omitted (legacy), updates when `input.id` resolves, else creates. | If `match` is set, matched fields must match a declared unique index on the Schema, be declared in `input.properties`, and appear in `input.required`; `id` and `expectedVersion` must NOT be in `input`. If `match` is omitted and `id` or `expectedVersion` is declared, both must be declared with strict string/number types. |
+| `delete` | Hard DELETE by id. | `input.id` (strict string) is required in `input.required`. |
+| `archive` | Soft-archive a publishing entry (`status='archived'`). | Valid only on Schemas with `lifecycle: publishing`. `input.id` (strict string) is required in `input.required`. |
 
 The Procedure's `input` is the contract with the *caller*. It MAY
 declare fields the Schema does not (e.g. a Turnstile token). The
 builtin op silently projects `input ∩ Schema.properties` and ignores
 the rest; JSON Schema's default `additionalProperties: true` lets
 the side-channel fields pass validation. To act on those fields
-(read the token, call the vendor), declare a `before_create`
+(read the token, call the vendor), declare a `before_create` or `before_update`
 lifecycle Trigger — see below.
 
+Under concurrent execution, database-level unique constraints catch any race conditions where concurrent writers miss preflight lookup, surfacing as standard `CONFLICT` diagnostics (HTTP 409) without automatic retries.
+
 `request_publish` and `publish` are intentionally not in the builtin
 vocabulary. They are lifecycle operations, not CRUD primitives.
 

package/docs/release-process.md

@@ -121,17 +121,18 @@ gh api --method POST repos/aotter/mantle/releases/generate-notes \
   --jq .body
 ```
 
-The nine public packages publish in dependency order:
+The ten 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`
+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`
 
 The umbrella package must contain its version-matched `docs/` and `skills/`
 payload. No tarball may contain `workspace:*` dependencies, secrets, local
@@ -156,7 +157,7 @@ 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;
+- all ten 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.
@@ -194,7 +195,7 @@ Core repository secrets:
 
 | Secret | Minimum purpose |
 |---|---|
-| `NPM_TOKEN` | Publish the nine `@aotter/*` packages on npmjs. |
+| `NPM_TOKEN` | Publish the ten `@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
@@ -217,6 +218,7 @@ for p in \
   @aotter/mantle-spec \
   @aotter/mantle-admin-ui \
   @aotter/mantle-runtime \
+  @aotter/mantle-indexeddb \
   @aotter/mantle-web \
   @aotter/mantle-admin \
   @aotter/mantle-bun \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.1.0-alpha.13",
+  "version": "0.1.0-alpha.15",
   "description": "Embeddable Mantle Core umbrella with Spec and Runtime; Web, Admin, Bun, Vercel, Cloudflare, and Admin UI are optional peer packages.",
   "license": "Apache-2.0",
   "homepage": "https://mantle.tools/",
@@ -83,8 +83,8 @@
     "README.md"
   ],
   "dependencies": {
-    "@aotter/mantle-runtime": "0.1.0-alpha.13",
-    "@aotter/mantle-spec": "0.1.0-alpha.13"
+    "@aotter/mantle-runtime": "0.1.0-alpha.15",
+    "@aotter/mantle-spec": "0.1.0-alpha.15"
   },
   "peerDependencies": {
     "aws4fetch": "^1.0.20",
@@ -92,12 +92,12 @@
     "hono": "^4.12.0",
     "@libsql/client": "^0.17.4",
     "zod": "^4.5.0",
-    "@aotter/mantle-admin": "0.1.0-alpha.13",
-    "@aotter/mantle-admin-ui": "0.1.0-alpha.13",
-    "@aotter/mantle-bun": "0.1.0-alpha.13",
-    "@aotter/mantle-cloudflare": "0.1.0-alpha.13",
-    "@aotter/mantle-web": "0.1.0-alpha.13",
-    "@aotter/mantle-vercel": "0.1.0-alpha.13"
+    "@aotter/mantle-bun": "0.1.0-alpha.15",
+    "@aotter/mantle-admin-ui": "0.1.0-alpha.15",
+    "@aotter/mantle-cloudflare": "0.1.0-alpha.15",
+    "@aotter/mantle-admin": "0.1.0-alpha.15",
+    "@aotter/mantle-web": "0.1.0-alpha.15",
+    "@aotter/mantle-vercel": "0.1.0-alpha.15"
   },
   "peerDependenciesMeta": {
     "@aotter/mantle-admin": {
@@ -135,17 +135,17 @@
     "@types/node": "^26",
     "aws4fetch": "^1.0.20",
     "better-auth": "^1.7.1",
-    "hono": "^4.13.1",
+    "hono": "^4.13.3",
     "@libsql/client": "^0.17.4",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.10",
+    "vitest": "^4.1.11",
     "zod": "^4.5.4",
-    "@aotter/mantle-admin-ui": "0.1.0-alpha.13",
-    "@aotter/mantle-bun": "0.1.0-alpha.13",
-    "@aotter/mantle-cloudflare": "0.1.0-alpha.13",
-    "@aotter/mantle-admin": "0.1.0-alpha.13",
-    "@aotter/mantle-vercel": "0.1.0-alpha.13",
-    "@aotter/mantle-web": "0.1.0-alpha.13"
+    "@aotter/mantle-admin": "0.1.0-alpha.15",
+    "@aotter/mantle-admin-ui": "0.1.0-alpha.15",
+    "@aotter/mantle-cloudflare": "0.1.0-alpha.15",
+    "@aotter/mantle-bun": "0.1.0-alpha.15",
+    "@aotter/mantle-vercel": "0.1.0-alpha.15",
+    "@aotter/mantle-web": "0.1.0-alpha.15"
   },
   "engines": {
     "node": ">=22"