An agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.
Rust
Implement LaneEvent schema extensions for event ordering, provenance, and dedupe (US-002)
Yeachan-Heo77fb62a9f1d6
diff --git a/rust/crates/runtime/src/lane_events.rs b/rust/crates/runtime/src/lane_events.rsindex 603a375d..03d8acec 100644--- a/rust/crates/runtime/src/lane_events.rs+++ b/rust/crates/runtime/src/lane_events.rs@@ -1,4 +1,4 @@-#![allow(clippy::similar_names)]+#![allow(clippy::similar_names, clippy::cast_possible_truncation)]use serde::{Deserialize, Serialize};use serde_json::Value;@@ -73,6 +73,316 @@ pub enum LaneFailureClass {Infra,}+/// Provenance labels for event source classification.+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]+#[serde(rename_all = "snake_case")]+pub enum EventProvenance {+ /// Event from a live, active lane+ LiveLane,+ /// Event from a synthetic test+ Test,+ /// Event from a healthcheck probe+ Healthcheck,+ /// Event from a replay/log replay+ Replay,+ /// Event from the transport layer itself+ Transport,+}++/// Session identity metadata captured at creation time.+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]+pub struct SessionIdentity {+ /// Stable title for the session+ pub title: String,+ /// Workspace/worktree path+ pub workspace: String,+ /// Lane/session purpose+ pub purpose: String,+ /// Placeholder reason if any field is unknown+ #[serde(skip_serializing_if = "Option::is_none")]+ pub placeholder_reason: Option<String>,+}++impl SessionIdentity {+ /// Create complete session identity+ #[must_use]+ pub fn new(+ title: impl Into<String>,+ workspace: impl Into<String>,+ purpose: impl Into<String>,+ ) -> Self {+ Self {+ title: title.into(),+ workspace: workspace.into(),+ purpose: purpose.into(),+ placeholder_reason: None,+ }+ }++ /// Create session identity with placeholder for missing fields+ #[must_use]+ pub fn with_placeholder(+ title: impl Into<String>,+ workspace: impl Into<String>,+ purpose: impl Into<String>,+ reason: impl Into<String>,+ ) -> Self {+ Self {+ title: title.into(),+ workspace: workspace.into(),+ purpose: purpose.into(),+ placeholder_reason: Some(reason.into()),+ }+ }+}++/// Lane ownership and workflow scope binding.+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]+pub struct LaneOwnership {+ /// Owner/assignee identity+ pub owner: String,+ /// Workflow scope (e.g., claw-code-dogfood, external-git-maintenance)+ pub workflow_scope: String,+ /// Whether the watcher is expected to act, observe, or ignore+ pub watcher_action: WatcherAction,+}++/// Watcher action expectation for a lane event.+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]+#[serde(rename_all = "snake_case")]+pub enum WatcherAction {+ /// Watcher should take action on this event+ Act,+ /// Watcher should only observe+ Observe,+ /// Watcher should ignore this event+ Ignore,+}++/// Event metadata for ordering, provenance, deduplication, and ownership.+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]+pub struct LaneEventMetadata {+ /// Monotonic sequence number for event ordering+ pub seq: u64,+ /// Event provenance source+ pub provenance: EventProvenance,+ /// Session identity at creation+ #[serde(skip_serializing_if = "Option::is_none")]+ pub session_identity: Option<SessionIdentity>,+ /// Lane ownership and scope+ #[serde(skip_serializing_if = "Option::is_none")]+ pub ownership: Option<LaneOwnership>,+ /// Nudge ID for deduplication cycles+ #[serde(skip_serializing_if = "Option::is_none")]+ pub nudge_id: Option<String>,+ /// Event fingerprint for terminal event deduplication+ #[serde(skip_serializing_if = "Option::is_none")]+ pub event_fingerprint: Option<String>,+ /// Timestamp when event was observed/created+ pub timestamp_ms: u64,+}++impl LaneEventMetadata {+ /// Create new event metadata+ #[must_use]+ pub fn new(seq: u64, provenance: EventProvenance) -> Self {+ Self {+ seq,+ provenance,+ session_identity: None,+ ownership: None,+ nudge_id: None,+ event_fingerprint: None,+ timestamp_ms: std::time::SystemTime::now()+ .duration_since(std::time::UNIX_EPOCH)+ .unwrap_or_default()+ .as_millis() as u64,+ }+ }++ /// Add session identity+ #[must_use]+ pub fn with_session_identity(mut self, identity: SessionIdentity) -> Self {+ self.session_identity = Some(identity);+ self+ }++ /// Add ownership info+ #[must_use]+ pub fn with_ownership(mut self, ownership: LaneOwnership) -> Self {+ self.ownership = Some(ownership);+ self+ }++ /// Add nudge ID for dedupe+ #[must_use]+ pub fn with_nudge_id(mut self, nudge_id: impl Into<String>) -> Self {+ self.nudge_id = Some(nudge_id.into());+ self+ }++ /// Compute and add event fingerprint for terminal events+ #[must_use]+ pub fn with_fingerprint(mut self, fingerprint: impl Into<String>) -> Self {+ self.event_fingerprint = Some(fingerprint.into());+ self+ }+}++/// Builder for constructing [`LaneEvent`]s with proper metadata.+#[derive(Debug, Clone)]+pub struct LaneEventBuilder {+ event: LaneEventName,+ status: LaneEventStatus,+ emitted_at: String,+ metadata: LaneEventMetadata,+ detail: Option<String>,+ failure_class: Option<LaneFailureClass>,+ data: Option<serde_json::Value>,+}++impl LaneEventBuilder {+ /// Start building a new lane event+ #[must_use]+ pub fn new(+ event: LaneEventName,+ status: LaneEventStatus,+ emitted_at: impl Into<String>,+ seq: u64,+ provenance: EventProvenance,+ ) -> Self {+ Self {+ event,+ status,+ emitted_at: emitted_at.into(),+ metadata: LaneEventMetadata::new(seq, provenance),+ detail: None,+ failure_class: None,+ data: None,+ }+ }++ /// Add session identity+ #[must_use]+ pub fn with_session_identity(mut self, identity: SessionIdentity) -> Self {+ self.metadata = self.metadata.with_session_identity(identity);+ self+ }++ /// Add ownership info+ #[must_use]+ pub fn with_ownership(mut self, ownership: LaneOwnership) -> Self {+ self.metadata = self.metadata.with_ownership(ownership);+ self+ }++ /// Add nudge ID+ #[must_use]+ pub fn with_nudge_id(mut self, nudge_id: impl Into<String>) -> Self {+ self.metadata = self.metadata.with_nudge_id(nudge_id);+ self+ }++ /// Add detail+ #[must_use]+ pub fn with_detail(mut self, detail: impl Into<String>) -> Self {+ self.detail = Some(detail.into());+ self+ }++ /// Add failure class+ #[must_use]+ pub fn with_failure_class(mut self, failure_class: LaneFailureClass) -> Self {+ self.failure_class = Some(failure_class);+ self+ }++ /// Add data payload+ #[must_use]+ pub fn with_data(mut self, data: serde_json::Value) -> Self {+ self.data = Some(data);+ self+ }++ /// Compute fingerprint and build terminal event+ #[must_use]+ pub fn build_terminal(mut self) -> LaneEvent {+ let fingerprint = compute_event_fingerprint(&self.event, &self.status, self.data.as_ref());+ self.metadata = self.metadata.with_fingerprint(fingerprint);+ self.build()+ }++ /// Build the event+ #[must_use]+ pub fn build(self) -> LaneEvent {+ LaneEvent {+ event: self.event,+ status: self.status,+ emitted_at: self.emitted_at,+ failure_class: self.failure_class,+ detail: self.detail,+ data: self.data,+ metadata: self.metadata,+ }+ }+}++/// Check if an event kind is terminal (completed, failed, superseded, closed).+#[must_use]+pub fn is_terminal_event(event: LaneEventName) -> bool {+ matches!(+ event,+ LaneEventName::Finished+ | LaneEventName::Failed+ | LaneEventName::Superseded+ | LaneEventName::Closed+ | LaneEventName::Merged+ )+}++/// Compute a fingerprint for terminal event deduplication.+#[must_use]+pub fn compute_event_fingerprint(+ event: &LaneEventName,+ status: &LaneEventStatus,+ data: Option<&serde_json::Value>,+) -> String {+ use std::collections::hash_map::DefaultHasher;+ use std::hash::{Hash, Hasher};++ let mut hasher = DefaultHasher::new();+ format!("{event:?}").hash(&mut hasher);+ format!("{status:?}").hash(&mut hasher);+ if let Some(d) = data {+ serde_json::to_string(d)+ .unwrap_or_default()+ .hash(&mut hasher);+ }+ format!("{:016x}", hasher.finish())+}++/// Deduplicate terminal events within a reconciliation window.+/// Returns only the first occurrence of each terminal fingerprint.+#[must_use]+pub fn dedupe_terminal_events(events: &[LaneEvent]) -> Vec<LaneEvent> {+ let mut seen_fingerprints = std::collections::HashSet::new();+ let mut result = Vec::new();++ for event in events {+ if is_terminal_event(event.event) {+ if let Some(fp) = &event.metadata.event_fingerprint {+ if seen_fingerprints.contains(fp) {+ continue; // Skip duplicate terminal event+ }+ seen_fingerprints.insert(fp.clone());+ }+ }+ result.push(event.clone());+ }++ result+}+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]pub struct LaneEventBlocker {#[serde(rename = "failureClass")]@@ -106,9 +416,13 @@ pub struct LaneEvent {pub detail: Option<String>,#[serde(skip_serializing_if = "Option::is_none")]pub data: Option<Value>,+ /// Event metadata for ordering, provenance, dedupe, and ownership+ pub metadata: LaneEventMetadata,}impl LaneEvent {+ /// Create a new lane event with minimal metadata (seq=0, provenance=LiveLane)+ /// Use `LaneEventBuilder` for events requiring full metadata.#[must_use]pub fn new(event: LaneEventName,@@ -122,6 +436,7 @@ impl LaneEvent {failure_class: None,detail: None,data: None,+ metadata: LaneEventMetadata::new(0, EventProvenance::LiveLane),}}@@ -254,8 +569,10 @@ mod tests {use serde_json::json;use super::{- dedupe_superseded_commit_events, LaneCommitProvenance, LaneEvent, LaneEventBlocker,- LaneEventName, LaneEventStatus, LaneFailureClass,+ compute_event_fingerprint, dedupe_superseded_commit_events, dedupe_terminal_events,+ is_terminal_event, EventProvenance, LaneCommitProvenance, LaneEvent, LaneEventBlocker,+ LaneEventBuilder, LaneEventMetadata, LaneEventName, LaneEventStatus, LaneFailureClass,+ LaneOwnership, SessionIdentity, WatcherAction,};#[test]@@ -420,4 +737,222 @@ mod tests {assert_eq!(retained.len(), 1);assert_eq!(retained[0].detail.as_deref(), Some("new"));}++ #[test]+ fn lane_event_metadata_includes_monotonic_sequence() {+ let meta1 = LaneEventMetadata::new(0, EventProvenance::LiveLane);+ let meta2 = LaneEventMetadata::new(1, EventProvenance::LiveLane);+ let meta3 = LaneEventMetadata::new(2, EventProvenance::Test);++ assert_eq!(meta1.seq, 0);+ assert_eq!(meta2.seq, 1);+ assert_eq!(meta3.seq, 2);+ assert!(meta1.timestamp_ms <= meta2.timestamp_ms);+ }++ #[test]+ fn event_provenance_round_trips_through_serialization() {+ let cases = [+ (EventProvenance::LiveLane, "live_lane"),+ (EventProvenance::Test, "test"),+ (EventProvenance::Healthcheck, "healthcheck"),+ (EventProvenance::Replay, "replay"),+ (EventProvenance::Transport, "transport"),+ ];++ for (provenance, expected) in cases {+ let json = serde_json::to_value(provenance).expect("should serialize");+ assert_eq!(json, serde_json::json!(expected));++ let round_trip: EventProvenance =+ serde_json::from_value(json).expect("should deserialize");+ assert_eq!(round_trip, provenance);+ }+ }++ #[test]+ fn session_identity_is_complete_at_creation() {+ let identity = SessionIdentity::new("my-lane", "/tmp/repo", "implement feature X");++ assert_eq!(identity.title, "my-lane");+ assert_eq!(identity.workspace, "/tmp/repo");+ assert_eq!(identity.purpose, "implement feature X");+ assert!(identity.placeholder_reason.is_none());++ // Test with placeholder+ let with_placeholder = SessionIdentity::with_placeholder(+ "untitled",+ "/tmp/unknown",+ "unknown",+ "session created before title was known",+ );+ assert_eq!(+ with_placeholder.placeholder_reason,+ Some("session created before title was known".to_string())+ );+ }++ #[test]+ fn lane_ownership_binding_includes_workflow_scope() {+ let ownership = LaneOwnership {+ owner: "claw-1".to_string(),+ workflow_scope: "claw-code-dogfood".to_string(),+ watcher_action: WatcherAction::Act,+ };++ assert_eq!(ownership.owner, "claw-1");+ assert_eq!(ownership.workflow_scope, "claw-code-dogfood");+ assert_eq!(ownership.watcher_action, WatcherAction::Act);+ }++ #[test]+ fn watcher_action_round_trips_through_serialization() {+ let cases = [+ (WatcherAction::Act, "act"),+ (WatcherAction::Observe, "observe"),+ (WatcherAction::Ignore, "ignore"),+ ];++ for (action, expected) in cases {+ let json = serde_json::to_value(action).expect("should serialize");+ assert_eq!(json, serde_json::json!(expected));++ let round_trip: WatcherAction =+ serde_json::from_value(json).expect("should deserialize");+ assert_eq!(round_trip, action);+ }+ }++ #[test]+ fn is_terminal_event_detects_terminal_states() {+ assert!(is_terminal_event(LaneEventName::Finished));+ assert!(is_terminal_event(LaneEventName::Failed));+ assert!(is_terminal_event(LaneEventName::Superseded));+ assert!(is_terminal_event(LaneEventName::Closed));+ assert!(is_terminal_event(LaneEventName::Merged));++ assert!(!is_terminal_event(LaneEventName::Started));+ assert!(!is_terminal_event(LaneEventName::Ready));+ assert!(!is_terminal_event(LaneEventName::Blocked));+ }++ #[test]+ fn compute_event_fingerprint_is_deterministic() {+ let fp1 = compute_event_fingerprint(+ &LaneEventName::Finished,+ &LaneEventStatus::Completed,+ Some(&json!({"commit": "abc123"})),+ );+ let fp2 = compute_event_fingerprint(+ &LaneEventName::Finished,+ &LaneEventStatus::Completed,+ Some(&json!({"commit": "abc123"})),+ );++ assert_eq!(fp1, fp2, "same inputs should produce same fingerprint");+ assert!(!fp1.is_empty());+ assert_eq!(fp1.len(), 16, "fingerprint should be 16 hex chars");+ }++ #[test]+ fn compute_event_fingerprint_differs_for_different_inputs() {+ let fp1 =+ compute_event_fingerprint(&LaneEventName::Finished, &LaneEventStatus::Completed, None);+ let fp2 = compute_event_fingerprint(&LaneEventName::Failed, &LaneEventStatus::Failed, None);+ let fp3 = compute_event_fingerprint(+ &LaneEventName::Finished,+ &LaneEventStatus::Completed,+ Some(&json!({"commit": "abc123"})),+ );++ assert_ne!(fp1, fp2, "different event/status should differ");+ assert_ne!(fp1, fp3, "different data should differ");+ }++ #[test]+ fn dedupe_terminal_events_suppresses_duplicates() {+ let event1 = LaneEventBuilder::new(+ LaneEventName::Finished,+ LaneEventStatus::Completed,+ "2026-04-04T00:00:00Z",+ 0,+ EventProvenance::LiveLane,+ )+ .build_terminal();++ let event2 = LaneEventBuilder::new(+ LaneEventName::Started,+ LaneEventStatus::Running,+ "2026-04-04T00:00:01Z",+ 1,+ EventProvenance::LiveLane,+ )+ .build();++ let event3 = LaneEventBuilder::new(+ LaneEventName::Finished,+ LaneEventStatus::Completed,+ "2026-04-04T00:00:02Z",+ 2,+ EventProvenance::LiveLane,+ )+ .build_terminal(); // Same fingerprint as event1++ let deduped = dedupe_terminal_events(&[event1.clone(), event2.clone(), event3.clone()]);++ assert_eq!(deduped.len(), 2, "should have 2 events after dedupe");+ assert_eq!(deduped[0].event, LaneEventName::Finished);+ assert_eq!(deduped[1].event, LaneEventName::Started);+ // event3 should be suppressed as duplicate of event1+ }++ #[test]+ fn lane_event_builder_constructs_event_with_metadata() {+ let event = LaneEventBuilder::new(+ LaneEventName::Started,+ LaneEventStatus::Running,+ "2026-04-04T00:00:00Z",+ 42,+ EventProvenance::Test,+ )+ .with_session_identity(SessionIdentity::new("test-lane", "/tmp", "test"))+ .with_ownership(LaneOwnership {+ owner: "bot-1".to_string(),+ workflow_scope: "test-suite".to_string(),+ watcher_action: WatcherAction::Observe,+ })+ .with_nudge_id("nudge-123")+ .with_detail("starting test run")+ .build();++ assert_eq!(event.event, LaneEventName::Started);+ assert_eq!(event.metadata.seq, 42);+ assert_eq!(event.metadata.provenance, EventProvenance::Test);+ assert_eq!(+ event.metadata.session_identity.as_ref().unwrap().title,+ "test-lane"+ );+ assert_eq!(event.metadata.ownership.as_ref().unwrap().owner, "bot-1");+ assert_eq!(event.metadata.nudge_id, Some("nudge-123".to_string()));+ assert_eq!(event.detail, Some("starting test run".to_string()));+ }++ #[test]+ fn lane_event_metadata_round_trips_through_serialization() {+ let meta = LaneEventMetadata::new(5, EventProvenance::Healthcheck)+ .with_session_identity(SessionIdentity::new("lane-1", "/tmp", "purpose"))+ .with_nudge_id("nudge-abc");++ let json = serde_json::to_value(&meta).expect("should serialize");+ assert_eq!(json["seq"], 5);+ assert_eq!(json["provenance"], "healthcheck");+ assert_eq!(json["nudge_id"], "nudge-abc");+ assert!(json["timestamp_ms"].as_u64().is_some());++ let round_trip: LaneEventMetadata =+ serde_json::from_value(json).expect("should deserialize");+ assert_eq!(round_trip.seq, 5);+ assert_eq!(round_trip.provenance, EventProvenance::Healthcheck);+ assert_eq!(round_trip.nudge_id, Some("nudge-abc".to_string()));+ }}diff --git a/rust/crates/runtime/src/lib.rs b/rust/crates/runtime/src/lib.rsindex e691df28..432e1c1e 100644--- a/rust/crates/runtime/src/lib.rs+++ b/rust/crates/runtime/src/lib.rs@@ -83,8 +83,10 @@ pub use hooks::{HookAbortSignal, HookEvent, HookProgressEvent, HookProgressReporter, HookRunResult, HookRunner,};pub use lane_events::{- dedupe_superseded_commit_events, LaneCommitProvenance, LaneEvent, LaneEventBlocker,- LaneEventName, LaneEventStatus, LaneFailureClass,+ compute_event_fingerprint, dedupe_superseded_commit_events, dedupe_terminal_events,+ is_terminal_event, EventProvenance, LaneCommitProvenance, LaneEvent, LaneEventBlocker,+ LaneEventBuilder, LaneEventMetadata, LaneEventName, LaneEventStatus, LaneFailureClass,+ LaneOwnership, SessionIdentity, WatcherAction,};pub use mcp::{mcp_server_signature, mcp_tool_name, mcp_tool_prefix, normalize_name_for_mcp,