docs(rfc): define typed storage failures

[ragnorc]

Summary

• define a closed typed storage-failure taxonomy without generic retry semantics
• preserve exact operator-facing storage diagnostics and keep HTTP/OpenAPI unchanged
• repair RFC-034/035/036 references so classification is not treated as replay authority

Context

This is the design replacement requested in the maintainer review of #491. The original plan called this RFC-034, but current main already reserves 0034–0036 and open PR #507 reserves 0037, so the next available public-contribution number is RFC-038.

This PR contains RFC documents only. Implementation will start from the accepted main state in a fresh branch; none of #491's obsolete code or conflicts are carried forward.

Validation

• git diff --check
• scripts/check-agents-md.sh

Related: #491

---

Note

Low Risk
Documentation-only RFC and cross-reference edits; no runtime, API, or persisted format changes in this PR.

Overview
Adds RFC-038, the accepted design that replaces the obsolete PR #491 prototype: storage errors become OmniError::Storage(StorageFailure) with a closed StorageFailureKind taxonomy, bounded typed-source mapping for object-store, I/O, Lance, and Lance Namespace, and no generic should_retry or wire/OpenAPI exposure. Operator-facing storage message text and HTTP behavior stay unchanged at the API boundary.

RFC-034, RFC-035, and RFC-036 are updated to point at RFC-038 instead of PR #491 and to state explicitly that substrate failure classification is separate from durable recovery progress, lifecycle outcomes, and replay/retry authority (including that Transient backoff in supervision requires operation-local authorization first).

^{Reviewed by Cursor Bugbot for commit 29d42a1. Bugbot is set up for automated code reviews on this repo. Configure here.}

Greptile Summary

RFC-038 defines a closed typed taxonomy for storage failures while keeping replay authority operation-local and preserving existing wire and persistence contracts.

• Replaces the proposed string-based Lance error representation with typed storage failure kinds.
• Assigns classification ownership across object-store, I/O, Lance, and Lance Namespace boundaries.
• Updates RFC-034, RFC-035, and RFC-036 to distinguish failure classification from recovery and replay authority.

Confidence Score: 5/5

The documentation-only PR appears safe to merge because no blocking failure remains.

No blocking failure remains.

Important Files Changed

Filename	Overview
docs/rfcs/0038-typed-storage-failures.md	Defines the typed storage-failure taxonomy, source mappings, compatibility boundaries, and acceptance evidence.
docs/rfcs/0034-durable-recovery-authority.md	Clarifies that storage classification and durable recovery progress do not independently authorize replay.
docs/rfcs/0035-served-operation-ownership.md	Replaces obsolete prototype references and keeps lifecycle outcomes separate from substrate classification.
docs/rfcs/0036-atomic-runtime-activation.md	Requires operation-local recovery authorization before supervision considers transient storage conditions.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    Sources[object_store / I-O / Lance / Lance Namespace] --> Classifier[RFC-038 typed classification]
    Classifier --> Kind[StorageFailureKind]
    Kind --> Policy[Operation-local effect and recovery policy]
    Policy -->|authorizes another attempt| Retry[Retry or supervision scheduling]
    Policy -->|does not authorize| Block[Block or require operator/state change]
    Classifier -. no replay authority .-> Retry

Loading

_{Reviews (2): Last reviewed commit: "docs(rfc): accept typed storage failures" | Re-trigger Greptile}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: db5cfba49d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Resolve the conflicting HTTP compatibility contract

The summary says HTTP behavior does not change, but the compatibility section explicitly allows reclassified errors to change operation-specific HTTP statuses (for example, the server currently maps DataFusion to 400 and Lance to 500). This leaves the implementation and acceptance tests without a definitive contract for whether those status changes are regressions or intentional; narrow this statement to HTTP/OpenAPI schemas or enumerate the permitted status changes. HTTP statuses are observable behavior and must be treated as part of the contract.

AGENTS.md reference: AGENTS.md:L193-L194

Useful? React with 👍 / 👎.