laser-sdk 0.9.0.dev2__tar.gz → 0.9.0.dev3__tar.gz

{laser_sdk-0.9.0.dev2 → laser_sdk-0.9.0.dev3}/Cargo.toml

@@ -8,7 +8,7 @@ edition = "2024"
 license = "Apache-2.0"
 repository = "https://github.com/laserdata/laser-sdk"
 rust-version = "1.98.0"
-version = "0.9.0-dev.2"
+version = "0.9.0-dev.3"
 
 [workspace.dependencies]
 apache-avro = { version = "0.22.0" }
@@ -30,7 +30,7 @@ json-patch = { version = "4.2.0" }
 jsonschema = { version = "0.60.1", default-features = false }
 laser-sdk = { path = "sdk" }
 laser-test-support = { path = "test-support" }
-laser-wire = { path = "wire", version = "0.9.0-dev.2" }
+laser-wire = { path = "wire", version = "0.9.0-dev.3" }
 memchr = { version = "2.8.3" }
 ouroboros = { version = "0.18.5" }
 prost = { version = "0.14.4" }

{laser_sdk-0.9.0.dev2 → laser_sdk-0.9.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: laser-sdk
-Version: 0.9.0.dev2
+Version: 0.9.0.dev3
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -32,7 +32,7 @@ This package provides the Python Laser SDK for Apache Iggy. [LaserData, Inc.](ht
 
 Rust and Python share the data contract and Rust implementation. The bindings expose Python forms of the SDK operations, configuration, and errors. Shared examples and behavior scenarios cover language-neutral behavior.
 
-> This source tree targets `0.9.0-dev.2`. The wire contract and public API use semantic versioning. Before `1.0.0`, minor releases can contain breaking changes.
+> This source tree targets `0.9.0-dev.3`. The wire contract and public API use semantic versioning. Before `1.0.0`, minor releases can contain breaking changes.
 
 `spawn_agent(agent_id, ..., consumer_group=None)` separates agent identity from its consumer group. The default group uses the agent ID spelling. Set `consumer_group` when the deployment needs a different group.
 

{laser_sdk-0.9.0.dev2 → laser_sdk-0.9.0.dev3}/README.md

@@ -4,7 +4,7 @@ This package provides the Python Laser SDK for Apache Iggy. [LaserData, Inc.](ht
 
 Rust and Python share the data contract and Rust implementation. The bindings expose Python forms of the SDK operations, configuration, and errors. Shared examples and behavior scenarios cover language-neutral behavior.
 
-> This source tree targets `0.9.0-dev.2`. The wire contract and public API use semantic versioning. Before `1.0.0`, minor releases can contain breaking changes.
+> This source tree targets `0.9.0-dev.3`. The wire contract and public API use semantic versioning. Before `1.0.0`, minor releases can contain breaking changes.
 
 `spawn_agent(agent_id, ..., consumer_group=None)` separates agent identity from its consumer group. The default group uses the agent ID spelling. Set `consumer_group` when the deployment needs a different group.
 

{laser_sdk-0.9.0.dev2 → laser_sdk-0.9.0.dev3}/foreign/python/Cargo.lock

@@ -2043,7 +2043,7 @@ checksum = "507460a910eb7b32ee961886ff48539633b788a36b65692b95f225b844c82553"
 
 [[package]]
 name = "laser-sdk"
-version = "0.9.0-dev.2"
+version = "0.9.0-dev.3"
 dependencies = [
  "apache-avro",
  "async-trait",
@@ -2072,7 +2072,7 @@ dependencies = [
 
 [[package]]
 name = "laser-sdk-python"
-version = "0.9.0-dev.2"
+version = "0.9.0-dev.3"
 dependencies = [
  "async-trait",
  "bytes",
@@ -2091,7 +2091,7 @@ dependencies = [
 
 [[package]]
 name = "laser-wire"
-version = "0.9.0-dev.2"
+version = "0.9.0-dev.3"
 dependencies = [
  "apache-avro",
  "bon",

{laser_sdk-0.9.0.dev2 → laser_sdk-0.9.0.dev3}/foreign/python/Cargo.toml

@@ -6,7 +6,7 @@ name = "laser-sdk-python"
 # The Python package version tracks the Rust workspace release train (one
 # version across laser-wire, laser-sdk, and the Python SDK), and the dependency
 # below tracks the Rust laser-sdk it wraps.
-version = "0.9.0-dev.2"
+version = "0.9.0-dev.3"
 edition = "2024"
 license = "Apache-2.0"
 repository = "https://github.com/laserdata/laser-sdk"
@@ -38,7 +38,7 @@ iggy = { version = "0.11.1-edge.9" }
 # Path wins for the in-monorepo wheel build. The version lets a source build (an
 # sdist on a platform with no prebuilt wheel) fetch laser-sdk from crates.io once
 # it is published. Wheels carry it compiled in and pull nothing at install.
-laser-sdk = { path = "../../sdk", version = "0.9.0-dev.2", features = ["a2a-bridge", "agent", "agui", "managed", "mcp-bridge", "provenance", "schema-codecs", "sign", "streaming"] }
+laser-sdk = { path = "../../sdk", version = "0.9.0-dev.3", features = ["a2a-bridge", "agent", "agui", "managed", "mcp-bridge", "provenance", "schema-codecs", "sign", "streaming"] }
 log = "0.4"
 pyo3 = { version = "0.29.3", features = ["abi3-py310", "experimental-async", "multiple-pymethods"] }
 pyo3-async-runtimes = { version = "0.29.0", features = ["attributes", "tokio-runtime"] }

{laser_sdk-0.9.0.dev2 → laser_sdk-0.9.0.dev3}/foreign/python/README.md

@@ -4,7 +4,7 @@ This package provides the Python Laser SDK for Apache Iggy. [LaserData, Inc.](ht
 
 Rust and Python share the data contract and Rust implementation. The bindings expose Python forms of the SDK operations, configuration, and errors. Shared examples and behavior scenarios cover language-neutral behavior.
 
-> This source tree targets `0.9.0-dev.2`. The wire contract and public API use semantic versioning. Before `1.0.0`, minor releases can contain breaking changes.
+> This source tree targets `0.9.0-dev.3`. The wire contract and public API use semantic versioning. Before `1.0.0`, minor releases can contain breaking changes.
 
 `spawn_agent(agent_id, ..., consumer_group=None)` separates agent identity from its consumer group. The default group uses the agent ID spelling. Set `consumer_group` when the deployment needs a different group.
 

{laser_sdk-0.9.0.dev2 → laser_sdk-0.9.0.dev3}/sdk/README.md

@@ -21,9 +21,9 @@ The [`laser-wire`](https://crates.io/crates/laser-wire) crate defines encoded me
 
 ```toml
 [dependencies]
-laser-sdk = "0.9.0-dev.2" # typed streaming plus provenance
+laser-sdk = "0.9.0-dev.3" # typed streaming plus provenance
 # Add only the layers the application uses:
-laser-sdk = { version = "0.9.0-dev.2", features = ["agent", "managed"] }
+laser-sdk = { version = "0.9.0-dev.3", features = ["agent", "managed"] }
 ```
 
 ## Quick example

{laser_sdk-0.9.0.dev2 → laser_sdk-0.9.0.dev3}/sdk/tests/integration/pause.rs

@@ -2,6 +2,7 @@ use crate::harness;
 use crate::test_iggy::TestIggyCluster;
 use async_trait::async_trait;
 use iggy::prelude::{Identifier, StreamClient, TopicClient};
+use iggy_common::calculate_32;
 use laser_sdk::agent::{ParkedRecords, SessionControl};
 use laser_sdk::govern::{ActionDecision, ActionGovernor, ActionKind, GovernedAction, GovernorMode};
 use laser_sdk::prelude::full::*;
@@ -240,9 +241,7 @@ async fn pauses_across_nodes(cluster: &mut TestIggyCluster, stream: &str) {
 // and resume each one. Every acknowledgment arrives within `bound` of its
 // request. Returns the control partition of each pause.
 async fn pause_round(laser: &Laser, seen: &Seen, body: &str, bound: Duration) -> Vec<u32> {
-    let sessions: Vec<ConversationId> = (0..CLUSTER_SESSIONS)
-        .map(|_| ConversationId::new())
-        .collect();
+    let sessions = spread_sessions();
     for session in &sessions {
         send_work(laser, *session, body).await;
     }
@@ -261,6 +260,23 @@ async fn pause_round(laser: &Laser, seen: &Seen, body: &str, bound: Duration) ->
     partitions
 }
 
+// Sessions over every control partition, the same number on each, by the key
+// rule Iggy routes a conversation id with. Random ids can all land on one
+// partition, which would leave one primary to pause through.
+fn spread_sessions() -> Vec<ConversationId> {
+    let per_partition = CLUSTER_SESSIONS / CLUSTER_PARTITIONS as usize;
+    let mut buckets: Vec<Vec<ConversationId>> = vec![Vec::new(); CLUSTER_PARTITIONS as usize];
+    while buckets.iter().any(|bucket| bucket.len() < per_partition) {
+        let session = ConversationId::new();
+        let partition = calculate_32(session.to_string().as_bytes()) % CLUSTER_PARTITIONS;
+        let bucket = &mut buckets[partition as usize];
+        if bucket.len() < per_partition {
+            bucket.push(session);
+        }
+    }
+    buckets.into_iter().flatten().collect()
+}
+
 async fn wait_acknowledged_within(
     laser: &Laser,
     session: ConversationId,

{laser_sdk-0.9.0.dev2 → laser_sdk-0.9.0.dev3}/wire/README.md

@@ -53,7 +53,7 @@ Modules group related types and operations. Features select optional dependencie
 | `session` | the seven session read requests (each naming its stream first), `SessionReply` with `SessionInfo`, `SessionPage` (whose `rebuilding` says the index is rebuilding or catching up, so the page can be incomplete), `SessionEventsPage`, `SessionStateView`, `SessionLinksView`, `SessionSources`, and `SessionChanges`, the frontier and gap types, `SessionError`, and the process heartbeat body `SessionHeartbeat` |
 | `dispatch` | the timeline `display_type` mapping, the reliable-consumer `classify` and `classify_generic` dispatch classification, the control operation names, and the addressee filters `addressee_filter(me)` and `broadcast_filter()` with `ADDRESSEE_FILTER_NAME`, the name an agent runtime saves its addressee policy under, pinned by `fixtures/dispatch_cases.json` |
 | `snapshot` | `FoldSnapshot` names one stream and fold. Sorted `SnapshotOffset` entries pin each topic creation time, partition, and last folded offset. |
-| `forward` | the forwarded managed-request frames (`ForwardedQuery`/`ForwardedCommand`, the command carrying the optional stable `operation_id` a mutation forwards under) and the server-stamped `ForwardedScope { stream_id, stream, stream_created_at_micros }` a session command needs |
+| `forward` | the forwarded managed-request frames (`ForwardedQuery`/`ForwardedCommand`, the command carrying the optional stable `operation_id` a mutation forwards under and the agent the calling connection declared, a claim nothing verifies), the server-stamped `ForwardedScope { stream_id, stream, stream_created_at_micros }` a session command needs, and `Caller { user_id, agent, on_behalf_of }`, which control stamps and mutation envelopes carry when a client asked |
 | `mutation` | the managed mutation identity contract: `ManagedRequestEnvelope` (the client wrapper carrying one nonzero `operation_id` per logical mutation) and `MutationCommandEnvelope` (the durable record a deployment appends and folds, carrying the trusted `scope` into replay). Which codes must carry the identity is the `codes` module's shared `is_idempotent_managed_request` classifier |
 | `keys` | the versioned managed key record (`KeyRecord`, `KeyKind`, `KEY_RECORD_VERSION`): the one storage representation every port's managed key registry reads and writes |
 | `commands` | the `Command` trait pairing each code with its request/reply types |

{laser_sdk-0.9.0.dev2 → laser_sdk-0.9.0.dev3}/wire/src/control.rs

@@ -981,6 +981,11 @@ pub struct ControlStamp {
     pub stream_generation: Option<ControlStreamGeneration>,
     /// Identifies the sealing key without revealing it.
     pub key_id: u64,
+    /// The client that asked for the record. Absent on a record the backend or
+    /// the streaming server issues on its own, so it tells the root user, id
+    /// zero, apart from them.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub caller: Option<crate::forward::Caller>,
 }
 
 /// One incarnation of a stream: a deleted and recreated stream has a new
@@ -1532,6 +1537,7 @@ mod wire_tests {
                     created_at_micros: 1_700_000_000_000_000,
                 }),
                 key_id: u64::MAX,
+                caller: None,
             }),
         };
         let back: ControlEnvelope =

{laser_sdk-0.9.0.dev2 → laser_sdk-0.9.0.dev3}/wire/src/fixtures.rs

@@ -128,6 +128,7 @@ corpus!(
     "control_register_schema_protobuf.bin",
     "control_accept_gap.bin",
     "control_skip_record.bin",
+    "control_stamped_caller.bin",
     "control_stamped_remove_binding.bin",
     "control_register_session_source_all.bin",
     "control_register_session_source_named.bin",
@@ -181,6 +182,8 @@ corpus!(
     "fork_put.bin",
     "fork_reply_created.bin",
     "forwarded_command.bin",
+    "forwarded_command_agent.bin",
+    "forwarded_command_on_behalf_of.bin",
     "forwarded_command_positioned.bin",
     "forwarded_command_scoped.bin",
     "forwarded_query.bin",
@@ -238,6 +241,7 @@ corpus!(
     "memory_forget_scoped.bin",
     "memory_item_origin.bin",
     "mutation_command.bin",
+    "mutation_command_caller.bin",
     "mutation_command_scoped.bin",
     "query_envelope.bin",
     "query_envelope_aggregate.bin",

{laser_sdk-0.9.0.dev2 → laser_sdk-0.9.0.dev3}/wire/src/forward.rs

@@ -4,6 +4,24 @@
 
 use serde::{Deserialize, Serialize};
 
+/// Who asked for a request the managed backend records, present only when a
+/// client asked. A record the backend or the streaming server issues on its own
+/// carries none.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Caller {
+    /// The authenticated user. The root user is id zero.
+    pub user_id: u32,
+    /// The agent the caller's connection declared in its presence. A claim the
+    /// client makes, never verified.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub agent: Option<crate::agent::AgentId>,
+    /// The end user an intermediary wrote for, as it named that user in
+    /// [`ON_BEHALF_OF_HEADER`](crate::http::ON_BEHALF_OF_HEADER). A claim the
+    /// backend records, never verified.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub on_behalf_of: Option<String>,
+}
+
 /// Trusted stream identity stamped by the server before forwarding a session request.
 #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
 pub struct ForwardedScope {
@@ -19,7 +37,8 @@ pub struct ForwardedQuery {
     /// Authenticated identity. Audit today, per-user stream scoping later.
     /// Trusted: set by the server, not the client.
     pub user_id: u32,
-    /// Originating client id, for logging and audit only.
+    /// Originating client id, for logging and audit only. Never zero for a
+    /// client, zero on a request the server issues itself.
     pub client_id: u128,
     /// `gen_ai.conversation.id` echoed for the audit log, never used to route.
     pub correlation: Option<String>,
@@ -50,7 +69,8 @@ pub struct ForwardedCommand {
     /// Authenticated identity, set by the server. The key-value store scopes its
     /// rows by this `user_id`, and the SDK cannot set it.
     pub user_id: u32,
-    /// Originating client id, for logging and audit only.
+    /// The caller's consensus client id, for logging and audit only. Never zero
+    /// for a client, zero on a request the server issues itself.
     pub client_id: u128,
     /// `gen_ai.conversation.id` echoed for the audit log, never used to route.
     pub correlation: Option<String>,
@@ -101,6 +121,17 @@ pub struct ForwardedCommand {
     /// backend refuses a frame whose tenancy differs from its own.
     #[serde(default, skip_serializing_if = "crate::authz::Tenancy::is_deployment")]
     pub tenancy: crate::authz::Tenancy,
+    /// Set by the server on a mutation a client sent over the binary protocol:
+    /// the agent the calling connection declared in its presence. A claim the
+    /// client makes, never verified. Absent over HTTP and on the server's own
+    /// requests.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub agent: Option<crate::agent::AgentId>,
+    /// Set by the server from [`ON_BEHALF_OF_HEADER`](crate::http::ON_BEHALF_OF_HEADER)
+    /// on an HTTP write: the end user an intermediary wrote for. A claim, never
+    /// verified.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub on_behalf_of: Option<String>,
 }
 
 #[expect(clippy::trivially_copy_pass_by_ref, reason = "serde skip predicate")]
@@ -159,6 +190,8 @@ mod tests {
             command_code: 1_000_000,
             payload: vec![0x90; 5],
             grants: Vec::new(),
+            agent: None,
+            on_behalf_of: None,
         })
         .expect("encodes");
         assert!(
@@ -201,9 +234,93 @@ mod tests {
             command_code: 42,
             payload: vec![0xde, 0xad, 0xbe, 0xef],
             grants: Vec::new(),
+            agent: None,
+            on_behalf_of: None,
         };
         let back: ForwardedCommand =
             decode_named(&encode_named(&command).expect("encodes")).expect("decodes");
         assert_eq!(back, command);
     }
+
+    #[test]
+    fn given_a_root_caller_with_an_agent_when_round_tripped_then_should_keep_both() {
+        let caller = Caller {
+            user_id: 0,
+            agent: Some("orbit-planner".parse().expect("agent id")),
+            on_behalf_of: None,
+        };
+
+        let back: Caller = decode_named(&encode_named(&caller).expect("encodes")).expect("decodes");
+
+        assert_eq!(back, caller);
+    }
+
+    #[test]
+    fn given_a_caller_written_for_an_end_user_when_round_tripped_then_should_keep_who_it_was_for() {
+        let caller = Caller {
+            user_id: 3,
+            agent: None,
+            on_behalf_of: Some("1793690355287073".to_owned()),
+        };
+
+        let back: Caller = decode_named(&encode_named(&caller).expect("encodes")).expect("decodes");
+
+        assert_eq!(back, caller);
+    }
+
+    #[test]
+    fn given_a_caller_with_an_empty_agent_when_decoded_then_should_be_refused() {
+        #[derive(serde::Serialize)]
+        struct Unchecked<'a> {
+            user_id: u32,
+            agent: &'a str,
+        }
+        let frame = encode_named(&Unchecked {
+            user_id: 3,
+            agent: "",
+        })
+        .expect("encodes");
+
+        assert!(decode_named::<Caller>(&frame).is_err());
+    }
+
+    #[test]
+    fn given_a_forwarded_command_with_an_agent_when_read_without_the_field_then_should_ignore_it() {
+        #[derive(Debug, PartialEq, serde::Deserialize)]
+        struct BeforeAgent {
+            user_id: u32,
+            client_id: u128,
+            command_code: u32,
+        }
+        let command = ForwardedCommand {
+            read_barrier: false,
+            min_position: None,
+            positioned_reply: false,
+            min_sessions: Vec::new(),
+            tenancy: Default::default(),
+            user_id: 0,
+            client_id: 9,
+            correlation: None,
+            operation_id: Some(9),
+            read_all: false,
+            scope: None,
+            command_code: 42,
+            payload: vec![1],
+            grants: Vec::new(),
+            agent: Some("orbit-planner".parse().expect("agent id")),
+            on_behalf_of: None,
+        };
+
+        let before: BeforeAgent =
+            decode_named(&encode_named(&command).expect("encodes")).expect("decodes");
+
+        assert_eq!(
+            before,
+            BeforeAgent {
+                user_id: 0,
+                client_id: 9,
+                command_code: 42,
+            }
+        );
+    }
 }

{laser_sdk-0.9.0.dev2 → laser_sdk-0.9.0.dev3}/wire/src/http.rs

@@ -1318,6 +1318,11 @@ pub const PARAM_EXPECT_ABSENT: &str = "expect_absent";
 /// wire constant rather than an unscoped string. Absent means no expiry.
 pub const KV_EXPIRES_AT_MICROS_HEADER: &str = "agdx-expires-at-micros";
 
+/// Request header an intermediary sets on a managed HTTP write to name the end
+/// user it writes for. The streaming server forwards it to the backend, which
+/// records it beside the authenticated user and never trusts it.
+pub const ON_BEHALF_OF_HEADER: &str = "agdx-on-behalf-of";
+
 /// `GET /agdx/projections` filters. Every field is optional, and an absent field is
 /// omitted from the query string (no empty `topic=`). Field names are the
 /// `PARAM_*` consts verbatim, so the client serializer and the server parser

{laser_sdk-0.9.0.dev2 → laser_sdk-0.9.0.dev3}/wire/src/mutation.rs

@@ -191,6 +191,10 @@ pub struct MutationCommandEnvelope {
     pub scope: Option<crate::forward::ForwardedScope>,
     #[serde(with = "crate::encoding::bin_bytes")]
     pub payload: Vec<u8>,
+    /// The client that asked for the command. Absent on a command the backend
+    /// issues on its own.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub caller: Option<crate::forward::Caller>,
 }
 
 impl MutationCommandEnvelope {
@@ -318,6 +322,7 @@ mod tests {
             command_code: AGDX_KV_SET_CODE,
             scope: None,
             payload: vec![0, 1, 2, 255],
+            caller: None,
         };
         let bytes = encode_named(&envelope).expect("encodes");
         let back: MutationCommandEnvelope = decode_named(&bytes).expect("decodes");
@@ -362,6 +367,7 @@ mod tests {
             command_code: AGDX_KV_SET_CODE,
             scope: None,
             payload: Vec::new(),
+            caller: None,
         };
 
         assert!(request.validate().is_err());

{laser_sdk-0.9.0.dev2 → laser_sdk-0.9.0.dev3}/wire/tests/wire_fixtures.rs

@@ -33,9 +33,10 @@ use laser_wire::checkpoint::{
 };
 use laser_wire::clients::{ClientMetadata, ClientMetadataList, ClientMetadataQuery};
 use laser_wire::codes::{
-    AGDX_KV_SET_CODE, AGENT_OP_VERSION, AUTHZ_OP_VERSION, BATCH_OP_VERSION, CHANGE_OP_VERSION,
-    CHECKPOINT_OP_VERSION, CLIENT_METADATA_OP_VERSION, CONTROL_OP_VERSION, FORK_OP_VERSION,
-    GRAPH_OP_VERSION, KV_LEASE_OP_VERSION, KV_OP_VERSION, QUERY_OP_VERSION,
+    AGDX_CONTROL_PUBLISH_CODE, AGDX_KV_SET_CODE, AGENT_OP_VERSION, AUTHZ_OP_VERSION,
+    BATCH_OP_VERSION, CHANGE_OP_VERSION, CHECKPOINT_OP_VERSION, CLIENT_METADATA_OP_VERSION,
+    CONTROL_OP_VERSION, FORK_OP_VERSION, GRAPH_OP_VERSION, KV_LEASE_OP_VERSION, KV_OP_VERSION,
+    QUERY_OP_VERSION,
 };
 use laser_wire::content::ContentType;
 use laser_wire::control::{
@@ -63,7 +64,7 @@ use laser_wire::filter::{
 use laser_wire::fork::{
     ForkCreate, ForkInfo, ForkKind, ForkOutcome, ForkPut, ForkReply, ForkStatus,
 };
-use laser_wire::forward::{ForwardedCommand, ForwardedQuery, ForwardedScope};
+use laser_wire::forward::{Caller, ForwardedCommand, ForwardedQuery, ForwardedScope};
 use laser_wire::framing::{decode_named, encode_named};
 use laser_wire::graph::{
     EdgeDir, GraphEdge, GraphNeighbors, GraphNode, GraphQuery, GraphReply, GraphResult,
@@ -117,6 +118,9 @@ use laser_wire::topology::WireTopology;
 use laser_wire::validate::Validate;
 use serde::de::DeserializeOwned;
 use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+use std::io::Read;
+use std::path::{Path as FilePath, PathBuf};
 
 #[test]
 fn given_session_read_requests_when_encoded_then_should_match_golden_fixtures() {
@@ -202,8 +206,6 @@ fn given_session_read_requests_when_encoded_then_should_match_golden_fixtures()
         laser_wire::framing::decode_named::<session_request::SessionGet>(&missing_stream).is_err()
     );
 }
-use std::collections::BTreeMap;
-use std::path::PathBuf;
 
 const REGEN_ENV: &str = "AGDX_WIRE_FIXTURES_REGEN";
 const TIMESTAMP_MICROS: u64 = 1_717_171_717_000_000;
@@ -445,6 +447,33 @@ fn fixture_path(name: &str) -> PathBuf {
         .join(name)
 }
 
+fn write_fixture(path: &FilePath, encoded: impl AsRef<[u8]>) {
+    let mut temporary = path.as_os_str().to_os_string();
+    temporary.push(format!(".{}.tmp", std::process::id()));
+    let temporary = PathBuf::from(temporary);
+    std::fs::write(&temporary, encoded).expect("write fixture");
+    std::fs::rename(&temporary, path).expect("replace fixture");
+}
+
+#[test]
+fn given_an_open_fixture_when_regenerated_then_should_keep_the_reader_on_a_complete_snapshot() {
+    let path = std::env::temp_dir().join(format!("laser-wire-fixture-{}.bin", std::process::id()));
+    std::fs::write(&path, b"original fixture").expect("initial fixture");
+    let mut reader = std::fs::File::open(&path).expect("open fixture");
+
+    write_fixture(&path, b"replacement fixture");
+
+    let mut snapshot = Vec::new();
+    reader
+        .read_to_end(&mut snapshot)
+        .expect("read open fixture");
+    let replacement = std::fs::read(&path).expect("read replacement");
+    drop(reader);
+    std::fs::remove_file(&path).expect("remove fixture");
+    assert_eq!(snapshot, b"original fixture");
+    assert_eq!(replacement, b"replacement fixture");
+}
+
 fn assert_frame<T>(name: &str, value: &T)
 where
     T: Serialize + DeserializeOwned,
@@ -452,7 +481,7 @@ where
     let encoded = encode_named(value).expect("fixture value serializes");
     let path = fixture_path(name);
     if std::env::var(REGEN_ENV).is_ok() {
-        std::fs::write(&path, &encoded).expect("write fixture");
+        write_fixture(&path, &encoded);
     }
     let golden = std::fs::read(&path)
         .unwrap_or_else(|error| panic!("read fixture {name}: {error} (regen with {REGEN_ENV}=1)"));
@@ -473,7 +502,7 @@ where
     let encoded = serde_json::to_string_pretty(value).expect("fixture value serializes");
     let path = fixture_path(name);
     if std::env::var(REGEN_ENV).is_ok() {
-        std::fs::write(&path, &encoded).expect("write fixture");
+        write_fixture(&path, &encoded);
     }
     let golden = std::fs::read_to_string(&path)
         .unwrap_or_else(|error| panic!("read fixture {name}: {error} (regen with {REGEN_ENV}=1)"));
@@ -1567,6 +1596,27 @@ fn given_control_frames_when_encoded_then_should_match_golden_fixtures() {
                 created_at_micros: 1_700_000_000_000_000,
             }),
             key_id: 11,
+            caller: None,
+        });
+        stamped
+    });
+    assert_frame("control_stamped_caller.bin", &{
+        let mut stamped = envelope(ControlCommand::DropSchema(4));
+        stamped.stream = Some("fleet".to_owned());
+        stamped.stamp = Some(ControlStamp {
+            deployment_id: 7,
+            actor_user_id: 3,
+            operation_id: 0x0123_4567_89ab_cdef_0123_4567_89ab_cdf0,
+            stream_generation: Some(ControlStreamGeneration {
+                stream_id: 3,
+                created_at_micros: 1_700_000_000_000_000,
+            }),
+            key_id: 11,
+            caller: Some(Caller {
+                user_id: 3,
+                agent: None,
+                on_behalf_of: Some("1793690355287073".to_owned()),
+            }),
         });
         stamped
     });
@@ -2315,6 +2365,50 @@ fn given_forwarded_frames_when_encoded_then_should_match_golden_fixtures() {
             command_code: AGDX_KV_SET_CODE,
             payload: vec![9, 9, 9],
             grants: Vec::new(),
+            agent: None,
+            on_behalf_of: None,
+        },
+    );
+    assert_frame(
+        "forwarded_command_agent.bin",
+        &ForwardedCommand {
+            read_barrier: false,
+            min_position: None,
+            positioned_reply: true,
+            min_sessions: Vec::new(),
+            tenancy: Default::default(),
+            user_id: 0,
+            client_id: 42,
+            correlation: None,
+            operation_id: Some(17),
+            read_all: false,
+            scope: None,
+            command_code: laser_wire::codes::AGDX_FORK_CREATE_CODE,
+            payload: vec![9, 9, 9],
+            grants: Vec::new(),
+            agent: Some("orbit-planner".parse().expect("agent id")),
+            on_behalf_of: None,
+        },
+    );
+    assert_frame(
+        "forwarded_command_on_behalf_of.bin",
+        &ForwardedCommand {
+            read_barrier: false,
+            min_position: None,
+            positioned_reply: false,
+            min_sessions: Vec::new(),
+            tenancy: Default::default(),
+            user_id: 3,
+            client_id: 42,
+            correlation: None,
+            operation_id: Some(18),
+            read_all: false,
+            scope: None,
+            command_code: AGDX_CONTROL_PUBLISH_CODE,
+            payload: vec![9, 9, 9],
+            grants: Vec::new(),
+            agent: None,
+            on_behalf_of: Some("1793690355287073".to_owned()),
         },
     );
     let scope = ForwardedScope {
@@ -2339,6 +2433,8 @@ fn given_forwarded_frames_when_encoded_then_should_match_golden_fixtures() {
             command_code: AGDX_KV_SET_CODE,
             payload: vec![9, 9, 9],
             grants: Vec::new(),
+            agent: None,
+            on_behalf_of: None,
         },
     );
     assert_frame(
@@ -2369,6 +2465,8 @@ fn given_forwarded_frames_when_encoded_then_should_match_golden_fixtures() {
             command_code: laser_wire::codes::AGDX_KV_GET_CODE,
             payload: vec![9, 9, 9],
             grants: Vec::new(),
+            agent: None,
+            on_behalf_of: None,
         },
     );
     assert_frame(
@@ -2569,6 +2667,25 @@ fn given_hello_reply_frame_when_encoded_then_should_match_golden_fixture() {
                 expires_at_micros: Some(1_700_000_000_000_000),
             })
             .expect("kv set encodes"),
+            caller: None,
+        },
+    );
+    assert_frame(
+        "mutation_command_caller.bin",
+        &MutationCommandEnvelope {
+            v: FORK_OP_VERSION,
+            operation_id: 44,
+            actor_user_id: 0,
+            deployment_id: 7,
+            timestamp_micros: 1_700_000_000_000_000,
+            command_code: laser_wire::codes::AGDX_FORK_CREATE_CODE,
+            scope: None,
+            payload: vec![9, 9, 9],
+            caller: Some(Caller {
+                user_id: 0,
+                agent: Some("orbit-planner".parse().expect("agent id")),
+                on_behalf_of: None,
+            }),
         },
     );
     assert_frame(
@@ -2586,6 +2703,7 @@ fn given_hello_reply_frame_when_encoded_then_should_match_golden_fixture() {
                 stream_created_at_micros: 1_700_000_000_000_000,
             }),
             payload: vec![9, 9, 9],
+            caller: None,
         },
     );
 }