[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6ACKZ12QZPH2YSN7ENQW13J":3,"skill-same:01M6ACKZ12QZPH2YSN7ENQW13J":68},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":25,"linkOnly":26,"markdownContent":27,"markdownBody":28,"frontMatter":29,"refName":31,"commitSha":32,"skillDirectory":33,"forksCount":34,"repositoryHtmlUrl":35,"repositoryHomepageUrl":36,"ownerHtmlUrl":37,"ownerBlogUrl":38,"ownerDescription":6,"updatedAt":39,"install":40,"resources":53},"01M6ACKZ12QZPH2YSN7ENQW13J","ffi-capsule-protocol",null,"TRIGGER — read before adding, changing, or reviewing any __datafusion_*__ capsule getter, any FFI_* export that asks for a TaskContextProvider or an extension codec, or any code that calls FFI_QueryPlanner::new \u002F FFI_TableProvider::new \u002F FFI_{Logical,Physical}ExtensionCodec::new. These methods are one protocol with a settled convention. Do not design it fresh; do not construct a SessionContext inside an extension library.","apache\u002Fdatafusion-python","apache","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F47359?v=4","01M6AC83E6K4FDKK7HZ8WNMQKE","The Apache Software Foundation","01M6ACKST0XJWJESE0ZMQG0W2M",613,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fapache\u002Fdatafusion-python\u002Fblob\u002Fmain\u002F.ai\u002Fskills\u002Fffi-capsule-protocol\u002FSKILL.md",[],[19,20,21,22,23,24],"protocol","ffi capsule protocol","design","review","code","datafusion","2026-11-10 10:12:30",false,"---\nname: ffi-capsule-protocol\ndescription: \"TRIGGER — read before adding, changing, or reviewing any __datafusion_*__ capsule getter, any FFI_* export that asks for a TaskContextProvider or an extension codec, or any code that calls FFI_QueryPlanner::new \u002F FFI_TableProvider::new \u002F FFI_{Logical,Physical}ExtensionCodec::new. These methods are one protocol with a settled convention. Do not design it fresh; do not construct a SessionContext inside an extension library.\"\nargument-hint: \"[getter name] (e.g., \\\"__datafusion_query_planner__\\\", \\\"table provider\\\", \\\"codec\\\", or omit to review the whole family)\"\n---\n\n\u003C!---\n  Licensed to the Apache Software Foundation (ASF) under one\n  or more contributor license agreements.  See the NOTICE file\n  distributed with this work for additional information\n  regarding copyright ownership.  The ASF licenses this file\n  to you under the Apache License, Version 2.0 (the\n  \"License\"); you may not use this file except in compliance\n  with the License.  You may obtain a copy of the License at\n\n    http:\u002F\u002Fwww.apache.org\u002Flicenses\u002FLICENSE-2.0\n\n  Unless required by applicable law or agreed to in writing,\n  software distributed under the License is distributed on an\n  \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n  KIND, either express or implied.  See the License for the\n  specific language governing permissions and limitations\n  under the License.\n-->\n\n# FFI Capsule Protocol\n\n`datafusion-python` shares Rust objects with extension libraries through\nPyCapsules. Every hook is a dunder method named `__datafusion_\u003Cthing>__` that\nreturns a capsule wrapping an FFI-safe struct. They are **one protocol**, not a\ncollection of unrelated methods, and they have a settled convention that has\nalready been migrated once (see `docs\u002Fsource\u002Fuser-guide\u002Fupgrade-guides.md`,\nDataFusion 52.0.0 and 55.0.0).\n\n## Rule 1 — enumerate the family before you change a member\n\nDo this first, every time. It takes one command and it is the whole point of\nthis skill:\n\n```bash\ngrep -rn \"__datafusion_[a-z_]*__\" --include=\"*.rs\" crates\u002F examples\u002F*\u002Fsrc\u002F\n```\n\nCompare the signature you are about to write against what the others already\ndo. If yours is shaped differently, that is a finding about your design, not\nabout theirs.\n\n## Rule 2 — a getter takes the session it is being installed on\n\n```rust\nfn __datafusion_physical_extension_codec__\u003C'py>(\n    &self,\n    py: Python\u003C'py>,\n    session: Bound\u003C'py, PyAny>,\n) -> PyResult\u003CBound\u003C'py, PyCapsule>> { ... }\n```\n\nThe host calls the getter and passes itself. That argument is how an extension\nlibrary reaches things only the session has.\n\n`SessionContext` implements the same getters and ignores the argument, so a\nsession satisfies the protocol too — `ctx.__datafusion_query_planner__()` and\n`ctx.__datafusion_query_planner__(ctx)` are both valid.\n\n`__datafusion_session_planner__(ctx, fallback)` is the exception to the shape\nabove: it takes a second argument, the planner assembled so far. A session has\none planner slot, so planners compose by nesting rather than by chaining, and\nthe host hands each bundle the previous layer instead of letting it capture one.\nWrap `fallback` and delegate to it; returning a planner that ignores it discards\nevery layer beneath, including one the session already had. It runs after every\nbundle's codecs are installed, so `ctx` carries the final chains.\n\nThat is also the only hook where it does. `__datafusion_session_components__`\nruns before anything is installed, so its `ctx` still carries the chains the\nreceiver had — the same session, and the same task-context provider, but not\nthis call's codecs, not even your own. Read the host's codec chains in the\nplanner hook, never in the extension hook.\n\nA *codec* must always be handed over as an object implementing its getter, never\nas the bare capsule the getter returns; `with_extensions` refuses a capsule.\nA codec's wire id — the string a payload names on decode, which has to mean the\nsame thing in whichever process decodes — is read off the object it arrives as,\nand a capsule has no type to read one from. Deriving the id from the bundle that\ncontributed the capsule is not the fix: the bundle is whatever object the caller\npassed, so an application packaging your library inside a bundle of its own\nwould re-tag your payloads and they would stop decoding where they are read. If\nthe object's class name is not the identity you want on the wire, declare\n`__datafusion_codec_id__` on it. `BundledLogicalCodec` in\n`examples\u002Fdatafusion-ffi-query-planner-example\u002Fsrc\u002Fextension.rs` is the shape.\nThis applies only to codecs — a query planner carries no wire id.\n\n## Rule 3 — never construct a `SessionContext` in an extension library\n\nThe FFI constructors ask for things a library does not have:\n\n| Constructor | Wants | Take it from |\n|---|---|---|\n| `FFI_{Logical,Physical}ExtensionCodec::new` | `TaskContextProvider` | `ffi_task_context_provider_from_pycapsule(&session)` |\n| `FFI_TableProvider::new_with_ffi_codec` | logical codec | `ffi_logical_codec_from_pycapsule(session, None)` |\n| `FFI_QueryPlanner::new_with_ffi_codecs` | both codecs | `ffi_{logical,physical}_codec_from_pycapsule(session, None)` |\n\n`Arc::new(SessionContext::new())` is the wrong answer to all three, for two\nindependent reasons:\n\n1. **It is the wrong registry.** Decode callbacks resolve names against\n   whatever provider the codec carries. An empty session resolves nothing, so a\n   function the host registered with `register_udf` is invisible to a node that\n   references it by name.\n2. **It dangles.** `FFI_TaskContextProvider` downgrades its provider to a\n   `Weak`. A context built inline in the getter is dropped before the capsule\n   is ever used, and every callback then fails with `TaskContextProvider went\n   out of scope over FFI boundary`.\n\nPrefer the `*_with_ffi_codec(s)` constructors when they exist. They take\nprebuilt codecs that already carry the host's provider, so there is no provider\nparameter to get wrong.\n\n## Rule 4 — the helpers live in `crates\u002Futil\u002Fsrc\u002Flib.rs`\n\n`ffi_logical_codec_from_pycapsule`, `ffi_physical_codec_from_pycapsule`,\n`ffi_query_planner_from_pycapsule`, `ffi_task_context_provider_from_pycapsule`,\n`table_provider_from_pycapsule`. Each takes the object and, where relevant, an\n`Option\u003C&Bound\u003CPyAny>>` session:\n\n- `Some(session)` — importing a *foreign* object; the getter needs the session.\n- `None` — the object already *is* a session and is being asked for what it\n  holds.\n\nAdding a getter means adding a helper here, not hand-rolling capsule\nextraction at the call site.\n\n## Rule 5 — changing a getter's signature is a breaking change\n\nExtension libraries implement these methods. A signature change breaks every\none of them, and the failure is a bare `TypeError` from a `call1`. So:\n\n- Add a section to `docs\u002Fsource\u002Fuser-guide\u002Fupgrade-guides.md` with before\u002Fafter\n  Rust, matching the 52.0.0 and 55.0.0 entries.\n- Add the `api change` label to the PR.\n- Map the `TypeError` to a diagnosable message. `call_capsule_getter` in\n  `crates\u002Futil\u002Fsrc\u002Flib.rs` already does this; reuse it.\n- Update `python\u002Fdatafusion\u002Fcontext.py` and\n  `python\u002Fdatafusion\u002Fuser_defined.py`, where the `Protocol` type hints for\n  these methods live.\n\nChanging what a codec puts *on the wire* is equally breaking, and easier to\nmiss because no signature moves and nothing fails to compile. Serialized plans\noutlive the process that wrote them, so the same checklist applies: upgrade\nguide, `api change` label, and a statement of exactly which sessions produce\ndifferent bytes.\n\n## Rule 6 — a session keeps one `Arc\u003CSessionContext>` for life\n\n`FFI_TaskContextProvider` holds its provider **weakly**, and every codec handed\nto a foreign object carries one. A registered catalog provider upgrades that\nhandle on every `supports_filters_pushdown` and every `scan`. The handle is\nbound to an `Arc\u003CSessionContext>` *allocation*, so anything that replaces the\nallocation orphans every handle bound to the old one:\n`TaskContextProvider went out of scope over FFI boundary`.\n\nSo mutate `SessionState` in place — `*self.ctx.state_ref().write() = ...`, the\nway `add_physical_optimizer_rule` and `set_session_query_planner` both do —\nrather than deriving a replacement `SessionContext`. Carry the session id\nacross the rewrite; `SessionStateBuilder::new_from_existing` drops it and\n`build` mints a fresh one, which desyncs `session_id()` from every\n`TaskContext` the session hands out.\n\nDo not try to repair it after the fact:\n\n- **You cannot rebind what you cannot reach.** A codec embedded in a registered\n  `FFI_CatalogProvider`, and in every `FFI_SchemaProvider` and\n  `FFI_TableProvider` minted from it, has no Python-side handle.\n- **A codec must not retain its session.** Codecs are routinely handed to a\n  provider that is registered straight back into the session that built them,\n  closing `SessionContext -> catalog -> FFI provider -> FFI codec ->\n  SessionContext`.\n\n`test_registered_providers_survive_a_planner_install` in\n`examples\u002Fdatafusion-ffi-query-planner-example\u002Fpython\u002Ftests\u002F_test_three_library_query_planner.py`\nguards this. Its `WHERE` clause is load-bearing: filter pushdown upgrades the\nweak handle during logical optimization, before plan serialization could fail\nfirst for an unrelated reason.\n\n`SessionContext.with_extensions` is where this rule is easiest to get wrong,\nbecause \"bind the components to the context you are about to return\" reads like\nan instruction to derive one first. It is not: the factories are handed the\nreceiver, and the returned handle shares its allocation. There is nothing to\nkeep alive separately and nothing to garbage-collect out from under a provider.\n\n`SessionContext.enable_url_table` is the one method that mints a second\nallocation for a session. Its result must not outlive the receiver, and it also\nforks the session's `SessionState` while keeping its id, so two handles report\none `session_id()` with divergent configuration. That is a bug rather than a\ndesign — tracked in\n[apache\u002Fdatafusion-python#1708](https:\u002F\u002Fgithub.com\u002Fapache\u002Fdatafusion-python\u002Fissues\u002F1708)\n— so do not cite it as precedent for deriving a replacement context.\n\n## Rule 7 — installing a planner mutates the session, and says so\n\n`set_query_planner` returns `None`, matching `add_physical_optimizer_rule`. The\nquery planner lives in `SessionState`, so it belongs to the session and not to\na handle on it; every context sharing that session plans through it. Do not\nreintroduce a `with_query_planner` that pretends otherwise — the only way to\ngive a handle its own planner is a fresh `Arc\u003CSessionContext>`, which is what\nRule 6 forbids.\n\nInstalling a codec rebuilds the installed planner against it, and that rebuild\nreaches exactly one layer. `FFI_QueryPlanner::new_with_ffi_codecs` unwraps one\n`ForeignQueryPlanner`; a fallback that planner resolved at install time sits in\nits library's private data with no handle on this side, and cannot re-derive\ncodecs itself because `FFI_QueryPlanner` holds them by value and `Session`\nexposes no accessor for the host's current ones. So do not promise that install\norder is free — for a layered planner it is not. The examples cannot show this:\ntheir fallback lives in the same cdylib as its wrapper, and `datafusion-ffi`\nshort-circuits a same-library hop rather than serializing. A fix has to come\nfrom upstream; tracked in\n[apache\u002Fdatafusion#24762](https:\u002F\u002Fgithub.com\u002Fapache\u002Fdatafusion\u002Fissues\u002F24762).\n\nThe session's planner also tracks whichever handle wrote it last, so\nre-installing a planner on the original handle rebinds the session back to that\nhandle's codecs. `test_reinstalling_a_planner_rebinds_the_session_to_that_handles_codecs`\npins that; changing it should be deliberate.\n\n## Where the truth is\n\n- `docs\u002Fsource\u002Fextension-guide\u002F` — the protocol, for the library author.\n  `capsule-protocol.md` has the hook convention and what the getter argument\n  actually is; `codecs.md`, `bundles.md`, and `query-planners.md` have the\n  per-component rules; `index.md` lists all 18 hooks.\n- `docs\u002Fsource\u002Fcontributor-guide\u002Fffi-internals.md` — why the framing is shaped\n  this way, including the weak-`Arc` scheme and the one-level rebind.\n- `docs\u002Fsource\u002Fuser-guide\u002Fupgrade-guides.md` — every past migration.\n- `crates\u002Fcore\u002Fsrc\u002Fcodec.rs` — the codec chain: the envelope, identity dispatch,\n  and the two unframed cases from Rule 8.\n- `examples\u002Fdatafusion-ffi-example\u002Fsrc\u002F` — provider, catalog, function, codec\n  getters, all in current form. `name_only_codec.rs` is the codec that encodes\n  nothing.\n- `examples\u002Fdatafusion-ffi-query-planner-example\u002Fsrc\u002Fplanner.rs` — planner\n  getter.\n- `examples\u002Fdatafusion-ffi-query-planner-example\u002Fpython\u002Ftests\u002F_test_three_library_query_planner.py`\n  — `require_udf_on_decode` proves which session a decode callback resolves\n  against. Extend these when touching the protocol.\n","\u003C!---\n  Licensed to the Apache Software Foundation (ASF) under one\n  or more contributor license agreements.  See the NOTICE file\n  distributed with this work for additional information\n  regarding copyright ownership.  The ASF licenses this file\n  to you under the Apache License, Version 2.0 (the\n  \"License\"); you may not use this file except in compliance\n  with the License.  You may obtain a copy of the License at\n\n    http:\u002F\u002Fwww.apache.org\u002Flicenses\u002FLICENSE-2.0\n\n  Unless required by applicable law or agreed to in writing,\n  software distributed under the License is distributed on an\n  \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n  KIND, either express or implied.  See the License for the\n  specific language governing permissions and limitations\n  under the License.\n-->\n\n# FFI Capsule Protocol\n\n`datafusion-python` shares Rust objects with extension libraries through\nPyCapsules. Every hook is a dunder method named `__datafusion_\u003Cthing>__` that\nreturns a capsule wrapping an FFI-safe struct. They are **one protocol**, not a\ncollection of unrelated methods, and they have a settled convention that has\nalready been migrated once (see `docs\u002Fsource\u002Fuser-guide\u002Fupgrade-guides.md`,\nDataFusion 52.0.0 and 55.0.0).\n\n## Rule 1 — enumerate the family before you change a member\n\nDo this first, every time. It takes one command and it is the whole point of\nthis skill:\n\n```bash\ngrep -rn \"__datafusion_[a-z_]*__\" --include=\"*.rs\" crates\u002F examples\u002F*\u002Fsrc\u002F\n```\n\nCompare the signature you are about to write against what the others already\ndo. If yours is shaped differently, that is a finding about your design, not\nabout theirs.\n\n## Rule 2 — a getter takes the session it is being installed on\n\n```rust\nfn __datafusion_physical_extension_codec__\u003C'py>(\n    &self,\n    py: Python\u003C'py>,\n    session: Bound\u003C'py, PyAny>,\n) -> PyResult\u003CBound\u003C'py, PyCapsule>> { ... }\n```\n\nThe host calls the getter and passes itself. That argument is how an extension\nlibrary reaches things only the session has.\n\n`SessionContext` implements the same getters and ignores the argument, so a\nsession satisfies the protocol too — `ctx.__datafusion_query_planner__()` and\n`ctx.__datafusion_query_planner__(ctx)` are both valid.\n\n`__datafusion_session_planner__(ctx, fallback)` is the exception to the shape\nabove: it takes a second argument, the planner assembled so far. A session has\none planner slot, so planners compose by nesting rather than by chaining, and\nthe host hands each bundle the previous layer instead of letting it capture one.\nWrap `fallback` and delegate to it; returning a planner that ignores it discards\nevery layer beneath, including one the session already had. It runs after every\nbundle's codecs are installed, so `ctx` carries the final chains.\n\nThat is also the only hook where it does. `__datafusion_session_components__`\nruns before anything is installed, so its `ctx` still carries the chains the\nreceiver had — the same session, and the same task-context provider, but not\nthis call's codecs, not even your own. Read the host's codec chains in the\nplanner hook, never in the extension hook.\n\nA *codec* must always be handed over as an object implementing its getter, never\nas the bare capsule the getter returns; `with_extensions` refuses a capsule.\nA codec's wire id — the string a payload names on decode, which has to mean the\nsame thing in whichever process decodes — is read off the object it arrives as,\nand a capsule has no type to read one from. Deriving the id from the bundle that\ncontributed the capsule is not the fix: the bundle is whatever object the caller\npassed, so an application packaging your library inside a bundle of its own\nwould re-tag your payloads and they would stop decoding where they are read. If\nthe object's class name is not the identity you want on the wire, declare\n`__datafusion_codec_id__` on it. `BundledLogicalCodec` in\n`examples\u002Fdatafusion-ffi-query-planner-example\u002Fsrc\u002Fextension.rs` is the shape.\nThis applies only to codecs — a query planner carries no wire id.\n\n## Rule 3 — never construct a `SessionContext` in an extension library\n\nThe FFI constructors ask for things a library does not have:\n\n| Constructor | Wants | Take it from |\n|---|---|---|\n| `FFI_{Logical,Physical}ExtensionCodec::new` | `TaskContextProvider` | `ffi_task_context_provider_from_pycapsule(&session)` |\n| `FFI_TableProvider::new_with_ffi_codec` | logical codec | `ffi_logical_codec_from_pycapsule(session, None)` |\n| `FFI_QueryPlanner::new_with_ffi_codecs` | both codecs | `ffi_{logical,physical}_codec_from_pycapsule(session, None)` |\n\n`Arc::new(SessionContext::new())` is the wrong answer to all three, for two\nindependent reasons:\n\n1. **It is the wrong registry.** Decode callbacks resolve names against\n   whatever provider the codec carries. An empty session resolves nothing, so a\n   function the host registered with `register_udf` is invisible to a node that\n   references it by name.\n2. **It dangles.** `FFI_TaskContextProvider` downgrades its provider to a\n   `Weak`. A context built inline in the getter is dropped before the capsule\n   is ever used, and every callback then fails with `TaskContextProvider went\n   out of scope over FFI boundary`.\n\nPrefer the `*_with_ffi_codec(s)` constructors when they exist. They take\nprebuilt codecs that already carry the host's provider, so there is no provider\nparameter to get wrong.\n\n## Rule 4 — the helpers live in `crates\u002Futil\u002Fsrc\u002Flib.rs`\n\n`ffi_logical_codec_from_pycapsule`, `ffi_physical_codec_from_pycapsule`,\n`ffi_query_planner_from_pycapsule`, `ffi_task_context_provider_from_pycapsule`,\n`table_provider_from_pycapsule`. Each takes the object and, where relevant, an\n`Option\u003C&Bound\u003CPyAny>>` session:\n\n- `Some(session)` — importing a *foreign* object; the getter needs the session.\n- `None` — the object already *is* a session and is being asked for what it\n  holds.\n\nAdding a getter means adding a helper here, not hand-rolling capsule\nextraction at the call site.\n\n## Rule 5 — changing a getter's signature is a breaking change\n\nExtension libraries implement these methods. A signature change breaks every\none of them, and the failure is a bare `TypeError` from a `call1`. So:\n\n- Add a section to `docs\u002Fsource\u002Fuser-guide\u002Fupgrade-guides.md` with before\u002Fafter\n  Rust, matching the 52.0.0 and 55.0.0 entries.\n- Add the `api change` label to the PR.\n- Map the `TypeError` to a diagnosable message. `call_capsule_getter` in\n  `crates\u002Futil\u002Fsrc\u002Flib.rs` already does this; reuse it.\n- Update `python\u002Fdatafusion\u002Fcontext.py` and\n  `python\u002Fdatafusion\u002Fuser_defined.py`, where the `Protocol` type hints for\n  these methods live.\n\nChanging what a codec puts *on the wire* is equally breaking, and easier to\nmiss because no signature moves and nothing fails to compile. Serialized plans\noutlive the process that wrote them, so the same checklist applies: upgrade\nguide, `api change` label, and a statement of exactly which sessions produce\ndifferent bytes.\n\n## Rule 6 — a session keeps one `Arc\u003CSessionContext>` for life\n\n`FFI_TaskContextProvider` holds its provider **weakly**, and every codec handed\nto a foreign object carries one. A registered catalog provider upgrades that\nhandle on every `supports_filters_pushdown` and every `scan`. The handle is\nbound to an `Arc\u003CSessionContext>` *allocation*, so anything that replaces the\nallocation orphans every handle bound to the old one:\n`TaskContextProvider went out of scope over FFI boundary`.\n\nSo mutate `SessionState` in place — `*self.ctx.state_ref().write() = ...`, the\nway `add_physical_optimizer_rule` and `set_session_query_planner` both do —\nrather than deriving a replacement `SessionContext`. Carry the session id\nacross the rewrite; `SessionStateBuilder::new_from_existing` drops it and\n`build` mints a fresh one, which desyncs `session_id()` from every\n`TaskContext` the session hands out.\n\nDo not try to repair it after the fact:\n\n- **You cannot rebind what you cannot reach.** A codec embedded in a registered\n  `FFI_CatalogProvider`, and in every `FFI_SchemaProvider` and\n  `FFI_TableProvider` minted from it, has no Python-side handle.\n- **A codec must not retain its session.** Codecs are routinely handed to a\n  provider that is registered straight back into the session that built them,\n  closing `SessionContext -> catalog -> FFI provider -> FFI codec ->\n  SessionContext`.\n\n`test_registered_providers_survive_a_planner_install` in\n`examples\u002Fdatafusion-ffi-query-planner-example\u002Fpython\u002Ftests\u002F_test_three_library_query_planner.py`\nguards this. Its `WHERE` clause is load-bearing: filter pushdown upgrades the\nweak handle during logical optimization, before plan serialization could fail\nfirst for an unrelated reason.\n\n`SessionContext.with_extensions` is where this rule is easiest to get wrong,\nbecause \"bind the components to the context you are about to return\" reads like\nan instruction to derive one first. It is not: the factories are handed the\nreceiver, and the returned handle shares its allocation. There is nothing to\nkeep alive separately and nothing to garbage-collect out from under a provider.\n\n`SessionContext.enable_url_table` is the one method that mints a second\nallocation for a session. Its result must not outlive the receiver, and it also\nforks the session's `SessionState` while keeping its id, so two handles report\none `session_id()` with divergent configuration. That is a bug rather than a\ndesign — tracked in\n[apache\u002Fdatafusion-python#1708](https:\u002F\u002Fgithub.com\u002Fapache\u002Fdatafusion-python\u002Fissues\u002F1708)\n— so do not cite it as precedent for deriving a replacement context.\n\n## Rule 7 — installing a planner mutates the session, and says so\n\n`set_query_planner` returns `None`, matching `add_physical_optimizer_rule`. The\nquery planner lives in `SessionState`, so it belongs to the session and not to\na handle on it; every context sharing that session plans through it. Do not\nreintroduce a `with_query_planner` that pretends otherwise — the only way to\ngive a handle its own planner is a fresh `Arc\u003CSessionContext>`, which is what\nRule 6 forbids.\n\nInstalling a codec rebuilds the installed planner against it, and that rebuild\nreaches exactly one layer. `FFI_QueryPlanner::new_with_ffi_codecs` unwraps one\n`ForeignQueryPlanner`; a fallback that planner resolved at install time sits in\nits library's private data with no handle on this side, and cannot re-derive\ncodecs itself because `FFI_QueryPlanner` holds them by value and `Session`\nexposes no accessor for the host's current ones. So do not promise that install\norder is free — for a layered planner it is not. The examples cannot show this:\ntheir fallback lives in the same cdylib as its wrapper, and `datafusion-ffi`\nshort-circuits a same-library hop rather than serializing. A fix has to come\nfrom upstream; tracked in\n[apache\u002Fdatafusion#24762](https:\u002F\u002Fgithub.com\u002Fapache\u002Fdatafusion\u002Fissues\u002F24762).\n\nThe session's planner also tracks whichever handle wrote it last, so\nre-installing a planner on the original handle rebinds the session back to that\nhandle's codecs. `test_reinstalling_a_planner_rebinds_the_session_to_that_handles_codecs`\npins that; changing it should be deliberate.\n\n## Where the truth is\n\n- `docs\u002Fsource\u002Fextension-guide\u002F` — the protocol, for the library author.\n  `capsule-protocol.md` has the hook convention and what the getter argument\n  actually is; `codecs.md`, `bundles.md`, and `query-planners.md` have the\n  per-component rules; `index.md` lists all 18 hooks.\n- `docs\u002Fsource\u002Fcontributor-guide\u002Fffi-internals.md` — why the framing is shaped\n  this way, including the weak-`Arc` scheme and the one-level rebind.\n- `docs\u002Fsource\u002Fuser-guide\u002Fupgrade-guides.md` — every past migration.\n- `crates\u002Fcore\u002Fsrc\u002Fcodec.rs` — the codec chain: the envelope, identity dispatch,\n  and the two unframed cases from Rule 8.\n- `examples\u002Fdatafusion-ffi-example\u002Fsrc\u002F` — provider, catalog, function, codec\n  getters, all in current form. `name_only_codec.rs` is the codec that encodes\n  nothing.\n- `examples\u002Fdatafusion-ffi-query-planner-example\u002Fsrc\u002Fplanner.rs` — planner\n  getter.\n- `examples\u002Fdatafusion-ffi-query-planner-example\u002Fpython\u002Ftests\u002F_test_three_library_query_planner.py`\n  — `require_udf_on_decode` proves which session a decode callback resolves\n  against. Extend these when touching the protocol.\n",{"name":5,"description":7,"argument-hint":30},"[getter name] (e.g., \"__datafusion_query_planner__\", \"table provider\", \"codec\", or omit to review the whole family)","main","878e5d3b8d373bca19671af43e49dfb1890f8da2",".ai\u002Fskills\u002Fffi-capsule-protocol",184,"https:\u002F\u002Fgithub.com\u002Fapache\u002Fdatafusion-python","https:\u002F\u002Fdatafusion.apache.org\u002Fpython","https:\u002F\u002Fgithub.com\u002Fapache","https:\u002F\u002Fwww.apache.org\u002F","2026-11-09 03:42:43",{"source":8,"skillName":5,"commands":41,"prompt":51,"zipAvailable":52},[42,45,48],{"tool":43,"command":44},"npx","npx skills add apache\u002Fdatafusion-python --skill ffi-capsule-protocol",{"tool":46,"command":47},"bunx","bunx skills add apache\u002Fdatafusion-python --skill ffi-capsule-protocol",{"tool":49,"command":50},"pnpm","pnpm dlx skills add apache\u002Fdatafusion-python --skill ffi-capsule-protocol","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fapache\u002Fdatafusion-python\u002Fblob\u002Fmain\u002F.ai\u002Fskills\u002Fffi-capsule-protocol\u002FSKILL.md",true,[54,60,64],{"path":55,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":58,"sourceHtmlUrl":59},"references\u002Fcontext-file-template.md","REFERENCE","参考文档",3294,"https:\u002F\u002Fgithub.com\u002Fgithub\u002Fawesome-copilot\u002Fblob\u002Fmain\u002Fskills\u002Freact18-legacy-context\u002Freferences\u002Fcontext-file-template.md",{"path":61,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":62,"sourceHtmlUrl":63},"references\u002Fmulti-context.md",5770,"https:\u002F\u002Fgithub.com\u002Fgithub\u002Fawesome-copilot\u002Fblob\u002Fmain\u002Fskills\u002Freact18-legacy-context\u002Freferences\u002Fmulti-context.md",{"path":65,"resourceType":56,"resourceTypeDesc":57,"sizeBytes":66,"sourceHtmlUrl":67},"references\u002Fsingle-context.md",5205,"https:\u002F\u002Fgithub.com\u002Fgithub\u002Fawesome-copilot\u002Fblob\u002Fmain\u002Fskills\u002Freact18-legacy-context\u002Freferences\u002Fsingle-context.md",[69,98,105,112],{"skillNo":70,"name":71,"nameZh":6,"description":72,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":73,"categories":74,"keywords":91,"publishedAt":25},"01M6ACM3GXZHMNHNE4DHDBBXVK","datafusion-python","Use when the user is writing datafusion-python (Apache DataFusion Python bindings) DataFrame or SQL code. Covers imports, data loading, DataFrame operations, expression building, SQL-to-DataFrame mappings, idiomatic patterns, and common pitfalls.","https:\u002F\u002Fgithub.com\u002Fapache\u002Fdatafusion-python\u002Fblob\u002Fmain\u002Fskills\u002Fdatafusion_python\u002FSKILL.md",[75,80,83,88],{"categoryNo":76,"categoryName":77,"taxonomyType":78,"taxonomyTypeDesc":79},"01JBSEEDCAT000000000000010","后端与接口","SCENARIO","使用场景",{"categoryNo":81,"categoryName":82,"taxonomyType":78,"taxonomyTypeDesc":79},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":84,"categoryName":85,"taxonomyType":86,"taxonomyTypeDesc":87},"01JBSEEDCAT000000000000033","数据分析师","PROFESSION","适用职业",{"categoryNo":89,"categoryName":90,"taxonomyType":86,"taxonomyTypeDesc":87},"01JBSEEDCAT000000000000036","内容创作者",[92,24,93,94,95,23,96,9,97],"python","datafusion python","writing","sql","data loading","dataframe",{"skillNo":99,"name":100,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":101,"categories":102,"keywords":103,"publishedAt":25},"01M6ACM17FMWAHVBVMWQZ816NF","make-pythonic","https:\u002F\u002Fgithub.com\u002Fapache\u002Fdatafusion-python\u002Fblob\u002Fmain\u002F.ai\u002Fskills\u002Fmake-pythonic\u002FSKILL.md",[],[104],"make pythonic",{"skillNo":106,"name":107,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":108,"categories":109,"keywords":110,"publishedAt":25},"01M6ACKX5JQ505Q8YX7BJTGQBM","check-upstream","https:\u002F\u002Fgithub.com\u002Fapache\u002Fdatafusion-python\u002Fblob\u002Fmain\u002F.ai\u002Fskills\u002Fcheck-upstream\u002FSKILL.md",[],[111],"check upstream",{"skillNo":113,"name":114,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":115,"categories":116,"keywords":120,"publishedAt":25},"01M6ACKVJSNMT7YDTXEFJNZMY3","audit-skill-md","https:\u002F\u002Fgithub.com\u002Fapache\u002Fdatafusion-python\u002Fblob\u002Fmain\u002F.ai\u002Fskills\u002Faudit-skill-md\u002FSKILL.md",[117],{"categoryNo":118,"categoryName":119,"taxonomyType":78,"taxonomyTypeDesc":79},"01JBSEEDCAT000000000000023","Skill与智能体开发",[121],"audit skill md"]