docs: add catalogs to the commit-order contract Catalogs resolve alongside everything else and commit with the rest; register_catalog replaces rather than refuses, so their commit step cannot fail and needs no exception of its own. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
diff --git a/docs/source/contributor-guide/ffi-internals.md b/docs/source/contributor-guide/ffi-internals.md index a225f53..da003fa 100644 --- a/docs/source/contributor-guide/ffi-internals.md +++ b/docs/source/contributor-guide/ffi-internals.md
@@ -129,12 +129,13 @@ even though it can fail on a bad capsule or a duplicate id. 3. **Resolve.** Every declared function is wrapped and every name is checked, every declared table has its provider imported and its destination schema - resolved, every declared physical optimizer rule has its capsule imported, - and every `__datafusion_session_planner__` runs against the completed - chains. + resolved, every declared catalog has its provider imported, every declared + physical optimizer rule has its capsule imported, and every + `__datafusion_session_planner__` runs against the completed chains. 4. **Commit.** The tables are inserted, the planner is bound, the functions - are registered, and the optimizer rules are installed in a single - `SessionState` rebuild. + are registered, the catalogs are registered — `register_catalog` replaces + rather than refuses, so it cannot fail — and the optimizer rules are + installed in a single `SessionState` rebuild. Only step 4 touches the session, and every step that can fail happens before it — with one honest exception: a table insert goes through a