Skip to content

Commit cad7e55

Browse files
timsaucerclaude
andcommitted
docs: add tables to the commit-order contract
The resolve and commit steps in ffi-internals.md predate declared tables. Tables resolve alongside everything else, but their insert goes through a SchemaProvider, and a foreign one can still refuse what it reported as free — the one honest exception to "step 4 cannot raise", already stated in the bundle guide, now stated where the rule for the next field lives. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 parent a2c74e4 commit cad7e55

1 file changed

Lines changed: 11 additions & 5 deletions

File tree

docs/source/contributor-guide/ffi-internals.md

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -128,13 +128,19 @@ A call therefore splits into a part that may fail and a part that may not:
128128
live on that handle rather than on the session, so this step writes nothing
129129
even though it can fail on a bad capsule or a duplicate id.
130130
3. **Resolve.** Every declared function is wrapped and every name is checked,
131-
every declared physical optimizer rule has its capsule imported, and every
132-
`__datafusion_session_planner__` runs against the completed chains.
133-
4. **Commit.** The planner is bound, the functions are registered, and the
134-
optimizer rules are installed in a single `SessionState` rebuild.
131+
every declared table has its provider imported and its destination schema
132+
resolved, every declared physical optimizer rule has its capsule imported,
133+
and every `__datafusion_session_planner__` runs against the completed
134+
chains.
135+
4. **Commit.** The tables are inserted, the planner is bound, the functions
136+
are registered, and the optimizer rules are installed in a single
137+
`SessionState` rebuild.
135138

136139
Only step 4 touches the session, and every step that can fail happens before
137-
it. This is a rule for the next field added to
140+
it — with one honest exception: a table insert goes through a
141+
`SchemaProvider`, and a foreign one can still refuse what it reported as free
142+
during resolve. Tables commit first because of it, so nothing else has been
143+
written when that happens. This is a rule for the next field added to
138144
`SessionExtensionComponents`, not only a description of the current code: a new
139145
kind of component must do its fallible work — importing a capsule, resolving a
140146
name — in step 3, so that step 4 cannot raise part-way through.

0 commit comments

Comments
 (0)