enhance: classify iceberg planning errors

[xiaofan-luan]

Depends on #597 — branched from it, since it introduces bridge_error.rs. The diff shown against main will include #597's commits until that lands. Review the top commit (9cf5ddc) only.

Problem

iceberg was the last unclassified producer reachable from the Rust bridges. iceberg_bridge.cpp already decodes the marker, but nothing on the Rust side ever emitted one, so every planning failure crossed as an untagged string and landed on StorageError/2044 — a throttle on manifest reads looked exactly like a malformed table.

Scope is narrower than it sounds. iceberg's Rust does planning only (iceberg_plan_files); the data files it returns are read by the C++ parquet reader on the C++ ArrowFileSystem, which already classifies. So this covers metadata/manifest access and snapshot resolution, not the read path.

Why the classification has to come from the source chain

iceberg-storage-opendal collapses every IO failure into a single kind:

// iceberg-storage-opendal-0.9.0/src/utils.rs
pub(crate) fn from_opendal_error(e: opendal::Error) -> iceberg::Error {
    iceberg::Error::new(iceberg::ErrorKind::Unexpected, "Failure in doing io operation")
        .with_source(e)
}

So iceberg::ErrorKind carries no IO signal at all — everything is Unexpected. What survives is the typed opendal::Error in the source chain. classify_anyhow_error walks the anyhow chain (anyhow keeps concrete types through ?) and downcasts iceberg::Error then opendal::Error; first positive identification wins.

opendal is the friendlier of the two IO backends to classify against — it has a typed ErrorKind and its own is_temporary() bit, so unlike the object_store path nothing has to be recovered from prose.

source	code	segcore
opendal::NotFound, iceberg::TableNotFound/NamespaceNotFound	104	2017 ObjectNotExist
opendal::PermissionDenied	105	2044
opendal::ConditionNotMatch, iceberg::PreconditionFailed	103	2044
opendal::RateLimited	109	2045 retriable
no specific kind but is_temporary()	110	2045 retriable
opendal::Unsupported, iceberg::FeatureUnsupported	1002	NotImplemented
iceberg::DataInvalid	1001	2024 DataFormatBroken

Deliberately left untagged

• opendal::ConfigInvalid — a caller/operator mistake, but there is no user-error code on this channel yet. Mislabelling it as a storage failure is worse than leaving it in the conservative bucket; revisit when the user/system axis lands (enhance: define storage error taxonomy and preserve diagnostics #603).
• iceberg's write-path conflicts (TableAlreadyExists, NamespaceAlreadyExists, CatalogCommitConflicts) — reusing the CAS-specific conflict code would dilute it, and plan_files is read-only anyway.

Entry point

iceberg_plan_files becomes a thin wrapper that calls the unchanged anyhow-based body and maps once through BridgeError::from, so ? stays ergonomic inside and classification happens at exactly one place.

Verification

• cargo test --lib bridge_error::tests → 12 passed (4 new).
• Full make build clean.
• The version pin is a runtime test, not a compile-time one: it reproduces from_opendal_error's exact shape and asserts the chain walk recovers the code. An opendal version skew between this crate and iceberg-storage-opendal would make the downcast silently return None and degrade every iceberg IO failure to untagged — this catches that. A compile-time pin is impossible here because with_source accepts any error type.
• The C++ iceberg integration tests all skip without cloud credentials, as they do on main.

Not covered

The iceberg read path needs nothing here (it is C++), and ConfigInvalid waits on the user/system axis. paimon remains the last unclassified stack (its own opendal, tracked with #602).

🤖 Generated with Claude Code

https://claude.ai/code/session_011HDgMok3nR8ZNugKWWQQK2

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[sre-ci-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: xiaofan-luan
To complete the pull request process, please assign tedxu after the PR has been reviewed.
You can assign the PR to them by writing /assign @tedxu in a comment when ready.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[codecov]

Codecov Report

❌ Patch coverage is 73.13433% with 18 lines in your changes missing coverage. Please review.
✅ Project coverage is 76.03%. Comparing base (d3eebb1) to head (9cf5ddc).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
cpp/src/format/lance/lance_table_reader.cpp	72.34%	13 Missing ⚠️
cpp/src/format/lance/lance_format.cpp	0.00%	3 Missing ⚠️
cpp/src/format/iceberg/iceberg_format.cpp	0.00%	1 Missing ⚠️
cpp/src/format/lance/lance_table_writer.cpp	93.75%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #608      +/-   ##
==========================================
+ Coverage   75.95%   76.03%   +0.07%     
==========================================
  Files         168      168              
  Lines       16672    16697      +25     
  Branches     2509     2519      +10     
==========================================
+ Hits        12664    12695      +31     
+ Misses       4008     4002       -6     

Flag	Coverage Δ
cpp	78.73% <73.13%> (+0.07%)	⬆️
python	44.45% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.