Pin Epiphany-Codex bridge boundary

epiphany-codex-bridge/src/lib.rs

@@ -1,3 +1,20 @@
+//! Compatibility bridge between Epiphany's typed CultNet/CultCache-shaped
+//! contracts and the vendored Codex JSON-RPC/app-server shell.
+//!
+//! This crate is a bridge, not an authority organ. Its job is to translate
+//! Codex `ThreadEpiphany*` DTOs into Epiphany core documents, project typed
+//! Epiphany surfaces back into legacy Codex responses, and call the narrow
+//! host trait needed while Codex still owns thread persistence. Verdicts,
+//! launch policy, reorientation policy, acceptance rules, runtime-spine
+//! lifecycle semantics, and durable state invariants belong in `epiphany-core`
+//! or `epiphany-state-model`.
+//!
+//! Host facts and side effects that still pass through this crate are
+//! quarantine scaffolding for the current Codex shell. Do not let them become
+//! a second policy throne. The long cut is to replace these adapters with
+//! native CultNet intents and receipts, leaving Codex only as the OpenAI
+//! subscription auth/model transport reliquary.
+
 pub mod checkpoint;
 pub mod context;
 pub mod context_protocol;

epiphany-codex-bridge/src/mutation_service.rs

@@ -59,13 +59,23 @@ use uuid::Uuid;
 
 #[allow(async_fn_in_trait)]
 pub trait EpiphanyMutationHost {
+    /// Read the Codex-hosted compatibility snapshot.
+    ///
+    /// The bridge may request host state so core can evaluate typed policy. The
+    /// host snapshot is an input fact, not a bridge-owned source of truth.
     async fn epiphany_state(&self) -> Option<EpiphanyThreadState>;
     async fn epiphany_reference_turn_id(&self) -> Option<String>;
+    /// Persist a state document already validated by Epiphany core policy.
+    ///
+    /// This is the Codex JSON-RPC shell's current persistence hook. It must not
+    /// grow mutation policy of its own.
     async fn epiphany_persist_state(
         &self,
         next_state: EpiphanyThreadState,
     ) -> BridgeResult<EpiphanyThreadState>;
+    /// Locate the native runtime-spine store while Codex still hosts the turn.
     async fn epiphany_runtime_spine_store_path(&self) -> PathBuf;
+    /// Project the already-typed state into Codex's current client-visible view.
     async fn client_visible_epiphany_state(
         &self,
         fallback: EpiphanyThreadState,
@@ -190,6 +200,9 @@ pub async fn launch_epiphany_job_on_thread(
     thread: &impl EpiphanyMutationHost,
     request: EpiphanyJobLaunchRequest,
 ) -> BridgeResult<EpiphanyJobLaunchResult> {
+    // Compatibility choreography only: core validates the launch plan and
+    // runtime-spine opens the typed job. The bridge stitches those typed
+    // documents into Codex's JSON-RPC thread shell until CultNet owns the route.
     let current_state = thread.epiphany_state().await.unwrap_or_default();
     validate_expected_revision(request.expected_revision, current_state.revision)?;
 

epiphany-core/src/runtime_spine.rs

@@ -1387,8 +1387,8 @@ fn epiphany_mutation_contracts() -> Vec<CultNetDocumentMutationContract> {
             vec![RUNTIME_JOB_TYPE],
             vec![
                 "Worker launch requests are typed task-intent documents; runtime jobs are lifecycle receipts, not the source of work intent.",
-                "Core/coordinator policy owns the launch yes/no; transport bridges translate and carry orders/receipts only.",
-                "Host executors gather host facts and perform side effects after the verdict, with readable receipts.",
+                "Core/coordinator policy owns the launch yes/no; the Epiphany-Codex bridge translates between CultNet-shaped intent and Codex JSON only.",
+                "Codex-hosted executors may gather host facts and perform side effects after the verdict, with readable receipts.",
             ],
         ),
         mutation_contract(

schemas/cultnet/epiphany.swarm-control-receipt.schema.json

@@ -24,7 +24,7 @@
     },
     "transportRole": {
       "type": "string",
-      "description": "What the transport bridge did for this action. Expected values are translate, carryOrder, carryReceipt, or a '+' joined combination. It must not make the launch/reorient verdict, gather host facts, or execute side effects."
+      "description": "What the Epiphany-Codex transport bridge did for this action. Expected values are translateCultNetToCodexJson, translateCodexJsonToCultNet, carryOrder, carryReceipt, or a '+' joined combination. It must not make the launch/reorient verdict, gather host facts, or execute side effects."
     },
     "hostExecutorRole": {
       "type": [