refactor(core): share turn-state fragment registration adapter

Introduce a shared  adapter trait used by both developer and contextual-user fragment registries.

Both envelope registries now implement the same adapter contract and continue to register fragment types via .

Also document why an adapter trait is needed (TurnContextDiffFragment uses static Self-returning constructors) and update contributor docs to point to the shared adapter.

Co-authored-by: Codex <noreply@openai.com>

Author: charley-oai

AGENTS.md

@@ -32,7 +32,7 @@ In the codex-rs folder where the rust code lives:
 - Use `<environment_context>` specifically for environment facts derived from `TurnContext` that may need turn-to-turn diffs (`cwd`, `shell`, optional `current_date`, optional `timezone`, optional network allow/deny domain summaries). Do not put policy text, plugin/skill listings, or other guidance into `<environment_context>`; those should use dedicated fragments.
 - Fragments derived from durable/current turn state that should update/reinject via diff across resume/fork/compaction/backtracking should implement `TurnContextDiffFragment` so current-state extraction, diffing, and rendering live together.
 - Runtime/session-prefix one-off fragments can implement only `ModelVisibleContextFragment` when they are not turn-state diffs.
-- Register new turn-state fragments by type in the fragment registry lists used by both initial-context and settings-update assembly (`...FragmentRegistration::of::<YourType>()` in `context_manager/updates/*_fragments.rs`) so they are discovered by iteration, not ad hoc wiring.
+- Register new turn-state fragments by type in the fragment registry lists used by both initial-context and settings-update assembly (`...FragmentRegistration::of::<YourType>()` in `context_manager/updates/*_fragments.rs`). Both envelope registries use the shared `TurnStateFragmentRegistration` adapter trait.
 - Do not hand-construct model-visible `ResponseItem::Message` payloads in new code; use fragment conversion and shared envelope builders.
 - Do not inject raw strings directly into the initial-context or settings-update builders, and do not call fragment wrapping helpers ad hoc from new code.
 

codex-rs/core/src/context_manager/updates.rs

@@ -28,6 +28,27 @@ pub(crate) enum FragmentBuildPass {
     SettingsUpdate,
 }
 
+/// Shared adapter for turn-state fragment registries across both envelopes.
+///
+/// We need this adapter because `TurnContextDiffFragment` relies on static,
+/// `Self`-returning constructors (`from_turn_context` and
+/// `diff_from_turn_context_item`), which are not directly usable as a uniform
+/// registry interface. This trait gives both envelope registries one common
+/// "build for pass + context" shape while keeping fragment logic on the
+/// fragment types themselves.
+pub(crate) trait TurnStateFragmentRegistration {
+    type Role: ModelVisibleContextRole;
+    type Fragment: ModelVisibleContextFragment<Role = Self::Role>;
+
+    fn build(
+        &self,
+        pass: FragmentBuildPass,
+        previous: Option<&TurnContextItem>,
+        turn_context: &TurnContext,
+        params: &TurnContextDiffParams<'_>,
+    ) -> Option<Self::Fragment>;
+}
+
 pub(crate) struct TurnStateEnvelopeFragments {
     pub(crate) developer: Vec<DeveloperTextFragment>,
     pub(crate) contextual_user: Vec<ContextualUserTextFragment>,

codex-rs/core/src/context_manager/updates/contextual_user_update_fragments.rs

@@ -6,9 +6,11 @@
 //! canonical list.
 
 use super::FragmentBuildPass;
+use super::TurnStateFragmentRegistration;
 use crate::codex::TurnContext;
 use crate::environment_context::EnvironmentContext;
 use crate::instructions::AgentsMdInstructions;
+use crate::model_visible_context::ContextualUserContextRole;
 use crate::model_visible_context::ContextualUserTextFragment;
 use crate::model_visible_context::TurnContextDiffFragment;
 use crate::model_visible_context::TurnContextDiffParams;
@@ -51,23 +53,23 @@ impl ContextualUserFragmentRegistration {
             build: build_registered_contextual_user_fragment::<F>,
         }
     }
+}
+
+impl TurnStateFragmentRegistration for ContextualUserFragmentRegistration {
+    type Role = ContextualUserContextRole;
+    type Fragment = ContextualUserTextFragment;
 
     fn build(
         &self,
         pass: FragmentBuildPass,
         previous: Option<&TurnContextItem>,
         turn_context: &TurnContext,
         params: &TurnContextDiffParams<'_>,
-    ) -> Option<ContextualUserTextFragment> {
+    ) -> Option<Self::Fragment> {
         (self.build)(pass, previous, turn_context, params)
     }
 }
 
-// TurnContextDiffFragment uses static constructors returning `Self`, which are
-// not object-safe for `dyn` dispatch. This typed registration adapter preserves
-// "register a fragment type once" ergonomics while keeping fragment behavior in
-// the trait implementations.
-
 /// Canonical registry for turn-state contextual-user fragments.
 ///
 /// To add a new turn-state contextual-user model-visible fragment:
@@ -90,6 +92,8 @@ pub(super) fn build_registered_contextual_user_fragments(
 ) -> Vec<ContextualUserTextFragment> {
     REGISTERED_CONTEXTUAL_USER_FRAGMENT_BUILDERS
         .iter()
-        .filter_map(|registration| registration.build(pass, previous, next, params))
+        .filter_map(|registration| {
+            TurnStateFragmentRegistration::build(registration, pass, previous, next, params)
+        })
         .collect()
 }

codex-rs/core/src/context_manager/updates/developer_update_fragments.rs

@@ -7,6 +7,7 @@
 //! switch guidance).
 
 use super::FragmentBuildPass;
+use super::TurnStateFragmentRegistration;
 use crate::codex::TurnContext;
 use crate::features::Feature;
 use crate::model_visible_context::DeveloperContextRole;
@@ -399,14 +400,19 @@ impl DeveloperFragmentRegistration {
             build: build_registered_developer_fragment::<F>,
         }
     }
+}
+
+impl TurnStateFragmentRegistration for DeveloperFragmentRegistration {
+    type Role = DeveloperContextRole;
+    type Fragment = DeveloperTextFragment;
 
     fn build(
         &self,
         pass: FragmentBuildPass,
         previous: Option<&TurnContextItem>,
         turn_context: &TurnContext,
         params: &TurnContextDiffParams<'_>,
-    ) -> Option<DeveloperTextFragment> {
+    ) -> Option<Self::Fragment> {
         (self.build)(pass, previous, turn_context, params)
     }
 }
@@ -422,11 +428,6 @@ const REGISTERED_DEVELOPER_FRAGMENT_BUILDERS: &[DeveloperFragmentRegistration] =
     DeveloperFragmentRegistration::of::<PersonalityUpdateFragment>(),
 ];
 
-// TurnContextDiffFragment uses static constructors returning `Self`, which are
-// not object-safe for `dyn` dispatch. This typed registration adapter preserves
-// "register a fragment type once" ergonomics while keeping fragment behavior in
-// the trait implementations.
-
 pub(super) fn build_registered_developer_fragments(
     pass: FragmentBuildPass,
     previous: Option<&TurnContextItem>,
@@ -435,6 +436,8 @@ pub(super) fn build_registered_developer_fragments(
 ) -> Vec<DeveloperTextFragment> {
     REGISTERED_DEVELOPER_FRAGMENT_BUILDERS
         .iter()
-        .filter_map(|registration| registration.build(pass, previous, next, params))
+        .filter_map(|registration| {
+            TurnStateFragmentRegistration::build(registration, pass, previous, next, params)
+        })
         .collect()
 }

docs/model-visible-context.md

@@ -27,7 +27,7 @@ When adding new model-visible context:
 3. Set the fragment `type Role` to the correct developer or contextual-user role.
 4. If it is a contextual-user fragment, wrap content with shared marker helpers/constants from `model_visible_context`.
 5. If the fragment is derived from durable/current turn state and should be diffed/reinjected after history mutations, also implement `TurnContextDiffFragment`.
-6. Register the fragment type in the turn-state fragment registries (`...FragmentRegistration::of::<YourType>()` in `context_manager/updates/developer_update_fragments.rs` or `context_manager/updates/contextual_user_update_fragments.rs`) so both initial-context and settings-update paths iterate it.
+6. Register the fragment type in the turn-state fragment registries (`...FragmentRegistration::of::<YourType>()` in `context_manager/updates/developer_update_fragments.rs` or `context_manager/updates/contextual_user_update_fragments.rs`). Both registries use the same `TurnStateFragmentRegistration` adapter trait.
 7. Push the resulting fragments through the shared envelope builders.
 
 Do not hand-build developer or contextual-user model-visible `ResponseItem`s in new code.