@aotter/mantle 0.2.0-alpha.6 → 0.2.0-alpha.7

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

@@ -1,199 +0,0 @@
-# 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

@@ -1,30 +0,0 @@
-# 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. Its no-initialization clause is superseded by [ADR-0026](0026-progressive-generate.md) for 0.1.5.
-
-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

@@ -1,212 +0,0 @@
-# ADR-0022: Caller-observed `expectedVersion` for Admin and builtin upsert
-
-**Status:** Accepted; the Admin binding rules are superseded by [ADR-0029](0029-mcp-apps-interaction-contracts.md) (Admin binds `expectedVersion` only from a declared interaction and infers no OCC target). The caller-observed version contract itself stands.
-
-**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

@@ -1,69 +0,0 @@
-# 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.