docs(rfc): propose platform error classification

Summary:
Define shared semantic error markers and platform-level retry classification, beginning with optimistic concurrency conflicts. Keep domain error identities while letting the generic classifier handle ErrVersionMismatch consistently across SubmitQueue and Stovepipe.

Test Plan:
- make fmt
- make lint
- make check-tidy
- make check-gazelle

Revert Plan:
Revert this commit.

API Changes:
N/A

Monitoring and Alerts:
N/A

Author: albertywu

doc/rfc/error-classification.md

@@ -0,0 +1,104 @@
+# Platform Error Classification
+
+Define shared semantic markers for errors whose default retry policy is stable across domains, beginning with optimistic concurrency conflicts.
+
+## Problem
+
+Queue error handling is already mostly centralized. Controllers return errors, `platform/errs` classifies them, and `platform/consumer` converts the resulting classification into ack, nack, or reject behavior. Platform classifiers already cover backend-independent failures such as cancellation and backend-specific failures such as transient MySQL errors.
+
+The remaining gap is semantic errors defined by domain extensions. SubmitQueue and Stovepipe each expose `storage.ErrVersionMismatch`, but the platform cannot identify either sentinel without importing a domain package. That leaves three undesirable choices: every controller explicitly marks the error retryable, every domain introduces and wires its own classifier, or the error remains unclassified and is rejected instead of retried.
+
+| Concern | Current behavior | Proposed behavior |
+|---|---|---|
+| Error meaning | Each domain defines an unrelated `ErrVersionMismatch` sentinel | Each sentinel also implements a shared optimistic-conflict marker |
+| Retry classification | Controllers or domain-specific classifiers must recognize the sentinel | The platform generic classifier maps the marker to `InfraRetryable` |
+| Controller responsibility | A controller may need to understand transport retry behavior | A controller handles only workflow-specific convergence and otherwise preserves the error chain |
+| Service wiring | A semantic rule may require another domain classifier | Primary consumers keep the standard platform generic and backend classifiers |
+
+## Goals
+
+- Define retry policy once when an error has the same recovery semantics across domains.
+- Keep domain error identities and existing `errors.Is` behavior.
+- Keep controllers responsible for workflow meaning, not nack and redelivery mechanics.
+- Preserve controller overrides when local state proves that a conflict is already resolved.
+- Avoid dependencies from `platform/` into SubmitQueue, Stovepipe, or future domains.
+
+This RFC does not define queue retry limits or backoff, add automatic retries to RPC controllers, provide exactly-once execution, or create a shared storage interface.
+
+## Proposal
+
+Error handling is divided into three layers:
+
+| Layer | Responsibility |
+|---|---|
+| Domain extension | Return a domain error that describes what happened |
+| Platform classifier | Map recognized error semantics to a `Verdict` |
+| Consumer and transport | Apply the verdict through ack, nack, reject, retry limits, and DLQ policy |
+
+This separation puts retry classification in the common runtime because that runtime sees every returned error and already owns the transport action. Controllers remain free to interpret a conflict in workflow terms without duplicating transport policy.
+
+### Optimistic-conflict marker
+
+`platform/errs` defines a semantic marker:
+
+```go
+type OptimisticConflict interface {
+    error
+    OptimisticConflict()
+}
+```
+
+`OptimisticConflict` is a classification marker, not an error that controllers construct. A storage implementation detects a failed conditional write and returns its domain's `storage.ErrVersionMismatch`, whose concrete type implements the marker.
+
+The marker describes the cause, not the action. It does not itself mean nack, choose a delay, or configure a retry limit. The platform classifier owns the policy that an unhandled optimistic conflict should be retried from fresh state.
+
+SubmitQueue and Stovepipe retain their own `storage.ErrVersionMismatch` values. Storage callers can continue using `errors.Is(err, storage.ErrVersionMismatch)`, and platform code does not import either storage package.
+
+### Generic classification
+
+The existing `genericerrs.Classifier` recognizes the marker while continuing to classify backend-independent errors such as `context.Canceled`:
+
+```text
+OptimisticConflict -> InfraRetryable
+context.Canceled   -> InfraRetryable
+anything else      -> Unknown
+```
+
+Not every domain sentinel receives a platform classification. Errors such as `storage.ErrNotFound` and `storage.ErrAlreadyExists` remain context-specific because their meaning depends on the operation. Controllers classify them only when they have context unavailable to the platform classifiers.
+
+The classifier examines one error-chain node at a time. `NewClassifierProcessor` remains responsible for walking wrapped errors, so domain and controller code must preserve causes with `%w`.
+
+`mysqlerrs.Classifier` remains unchanged. It classifies raw MySQL driver, connection, and server errors; optimistic conflict is a semantic result produced by a conditional write and is not specific to MySQL.
+
+The standard primary-consumer wiring remains entirely platform-owned:
+
+```go
+errs.NewClassifierProcessor(
+    genericerrs.Classifier,
+    mysqlerrs.Classifier,
+)
+```
+
+### Controller behavior
+
+Controllers use their extension's documented sentinel, such as `storage.ErrVersionMismatch`, for workflow-specific handling. The `OptimisticConflict` marker is for cross-domain platform classification rather than normal controller matching.
+
+When an optimistic conflict means another writer may have changed relevant state, the default controller behavior is to return the error unchanged apart from contextual wrapping:
+
+```go
+if err := store.Update(...); err != nil {
+    return fmt.Errorf("update batch %s: %w", batch.ID, err)
+}
+```
+
+The classifier marks the conflict retryable, the consumer nacks the delivery, and redelivery reloads durable state before making another decision.
+
+A controller may still handle the conflict locally when it has workflow knowledge the platform lacks. For example, if another writer already committed the desired terminal transition, the controller can acknowledge successful convergence:
+
+```go
+if errors.Is(err, storage.ErrVersionMismatch) && desiredStateAlreadyCommitted {
+    return nil
+}
+```
+
+The platform rule is therefore a fallback for conflicts that escape the controller, not a requirement that every conflict produce redelivery. Existing local reconciliation loops may remain where they recompute from freshly loaded state and are part of the workflow operation rather than transport retry choreography.

doc/rfc/index.md

@@ -8,6 +8,7 @@ Design documents and technical proposals, grouped by scope. Shared/cross-cutting
 - [Message Queue Contract](messagequeue-contract.md) - How queue payloads are defined (Protobuf, serialized as protobuf JSON), located by audience (external in `api/{domain}/messagequeue/`, internal in `{domain}/core/messagequeue/`), bound to topics (the `topics` proto option), and enforced by Bazel visibility
 - [Consumer Gate](consumer-gate.md) - Stopping and starting individual queue controllers at runtime via consumer middleware: parked deliveries held in-flight with visibility extension, gate state as a separate extension with a file-based first implementation shared by tests and operators
 - [Change URIs](change-uri.md) - Identity of a code change: `scheme://{host[:port]}/{path}` per provider (GitHub PR, Phabricator Diff, git ref/commit) and canonical-form rules
+- [Platform Error Classification](error-classification.md) - Shared semantic error markers and platform retry classification, beginning with optimistic concurrency conflicts
 
 ## SubmitQueue