Say which codec chains each extension hook's context carries

`__datafusion_session_planner__` was documented as receiving a context that
carries the final codec chains, and `MyPlannerExtension` relies on exactly that
when it takes the host's codecs off `ctx` instead of minting its own. The other
side was never stated: `__datafusion_session_extension__` runs before anything
is installed, so its `ctx` is the same session with the chains the receiver
already had — missing this call's codecs, including the bundle's own.

Both hooks hand back a valid task-context provider, which is what components
actually need, so the difference only bites an author who reads codec chains off
the context. Recorded on `SessionExtensionExportable`, in the FFI guide's
two-phase section, and in Rule 2 of the capsule-protocol skill.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: timsaucer

.ai/skills/ffi-capsule-protocol/SKILL.md

@@ -70,6 +70,12 @@ Wrap `fallback` and delegate to it; returning a planner that ignores it discards
 every layer beneath, including one the session already had. It runs after every
 bundle's codecs are installed, so `ctx` carries the final chains.
 
+That is also the only hook where it does. `__datafusion_session_extension__`
+runs before anything is installed, so its `ctx` still carries the chains the
+receiver had — the same session, and the same task-context provider, but not
+this call's codecs, not even your own. Read the host's codec chains in the
+planner hook, never in the extension hook.
+
 A *codec* must always be handed over as an object implementing its getter, never
 as the bare capsule the getter returns; `with_extensions` refuses a capsule.
 A codec's wire id — the string a payload names on decode, which has to mean the

docs/source/contributor-guide/ffi.md

@@ -406,6 +406,15 @@ handing each the planner built so far. Two consequences worth holding onto:
   deep](#rebinding-a-planners-codecs-is-one-level-deep)), so a fallback captured before
   the codecs were complete would stay stale forever.
 
+The two hooks therefore see the same session through different chains. Both receive a
+handle on the one session, so the task-context provider taken off either is the same and
+stays valid — but the `ctx` in phase one still carries the chains the receiver had, since
+nothing is installed yet, while the `ctx` in phase two carries every bundle's codecs. A
+bundle that reads the host's codec chains — `MyPlannerExtension` does, to give its
+planner the host's codecs rather than minting its own — must do that in the planner hook.
+Reading them in phase one gets the chains from before the call, missing even the bundle's
+own codecs.
+
 An extension that ignores `fallback` and returns an unrelated planner replaces every
 layer beneath it, including any planner the session already had. That is legal — a
 library that must be the only planner does it deliberately — but it is not composable,

python/datafusion/extensions.py

@@ -231,6 +231,15 @@ class SessionExtensionExportable(Protocol):
     mutating the context they are handed — a registration made during binding
     is not rolled back if a later extension fails.
 
+    ``ctx`` is the right session but not yet the final codec chains: this hook
+    runs before anything is installed, so ``ctx`` still carries whatever chains
+    the receiver had. Take the task-context provider off it — that is bound to
+    the session and is what the components need — but do not read its codec
+    chains expecting to find this call's codecs, including your own.
+    :py:class:`SessionPlannerExportable` is the hook that sees the completed
+    chains, which is why a planner that wraps the host's codecs builds them
+    there rather than here.
+
     A bundle that also contributes a query planner implements
     :py:class:`SessionPlannerExportable` alongside this protocol. Planners are
     installed in a second phase, so they are not part of the components