app-server: document thread and turn IDs are UUID7

codex-rs/app-server-protocol/src/protocol/v2/thread_data.rs

@@ -133,6 +133,7 @@ pub struct GitInfo {
 #[serde(rename_all = "camelCase")]
 #[ts(export_to = "v2/")]
 pub struct Thread {
+    /// Identifier for this thread. Codex-generated thread IDs are UUIDv7.
     pub id: String,
     /// Session id shared by threads that belong to the same session tree.
     pub session_id: String,
@@ -186,6 +187,7 @@ pub struct Thread {
 #[serde(rename_all = "camelCase")]
 #[ts(export_to = "v2/")]
 pub struct Turn {
+    /// Identifier for this turn. Codex-generated turn IDs are UUIDv7.
     pub id: String,
     /// Thread items currently included in this turn payload.
     pub items: Vec<ThreadItem>,

codex-rs/core/src/session/mod.rs

@@ -719,7 +719,7 @@ impl Codex {
         op: Op,
         trace: Option<W3cTraceContext>,
     ) -> CodexResult<String> {
-        let id = Uuid::now_v7().to_string();
+        let id = new_submission_id();
         let sub = Submission {
             id: id.clone(),
             op,
@@ -737,7 +737,7 @@ impl Codex {
         client_user_message_id: Option<String>,
     ) -> CodexResult<String> {
         debug_assert!(matches!(op, Op::UserInput { .. }));
-        let id = Uuid::now_v7().to_string();
+        let id = new_submission_id();
         let sub = Submission {
             id: id.clone(),
             op,
@@ -864,6 +864,15 @@ impl Codex {
     }
 }
 
+/// Generate a core submission ID. App-server exposes submission IDs that
+/// create turns as a public-facing turn ID.
+///
+/// Some use cases take advantage of the fact that these are UUID7 which
+/// encodes a timestamp, so think carefully before changing this.
+fn new_submission_id() -> String {
+    Uuid::now_v7().to_string()
+}
+
 fn get_service_tier(
     configured_service_tier: Option<String>,
     fast_mode_enabled: bool,

codex-rs/protocol/src/thread_id.rs

@@ -10,6 +10,9 @@ use uuid::Uuid;
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, TS, Hash)]
 #[ts(type = "string")]
+/// Identifier for a Codex thread.
+///
+/// Codex-generated thread IDs are UUIDv7, and some use cases rely on that.
 pub struct ThreadId {
     pub(crate) uuid: Uuid,
 }