@fulcrum_io/sdk 0.1.0

package/proto/fulcrum/eventstore/v1/eventstore.proto

@@ -0,0 +1,254 @@
+syntax = "proto3";
+
+package fulcrum.eventstore.v1;
+
+option go_package = "github.com/fulcrum-io/fulcrum/pkg/eventstore/v1;eventstorev1";
+
+import "google/protobuf/timestamp.proto";
+import "google/protobuf/struct.proto";
+
+// EventStore service for persisting and querying execution events
+service EventStoreService {
+  // Publish a single event to the event store
+  rpc PublishEvent(PublishEventRequest) returns (PublishEventResponse);
+  
+  // Publish multiple events in batch
+  rpc PublishEventBatch(PublishEventBatchRequest) returns (PublishEventBatchResponse);
+  
+  // Query events by various filters
+  rpc QueryEvents(QueryEventsRequest) returns (QueryEventsResponse);
+  
+  // Get events for a specific execution
+  rpc GetExecutionEvents(GetExecutionEventsRequest) returns (GetExecutionEventsResponse);
+  
+  // Stream events in real-time
+  rpc StreamEvents(StreamEventsRequest) returns (stream StoredEvent);
+  
+  // Get event store statistics
+  rpc GetEventStoreStats(GetEventStoreStatsRequest) returns (GetEventStoreStatsResponse);
+}
+
+// StoredEvent represents a persisted event in the event store
+message StoredEvent {
+  // Unique event ID (generated by event store)
+  string event_id = 1;
+  
+  // Execution context
+  string execution_id = 2;
+  string envelope_id = 3;
+  string tenant_id = 4;
+  string workflow_id = 5;
+  
+  // Event metadata
+  string event_type = 6; // execution_started, llm_call, tool_call, checkpoint_saved, etc.
+  google.protobuf.Timestamp timestamp = 7;
+  int64 sequence_number = 8; // Sequential number within execution
+  
+  // Event payload
+  google.protobuf.Struct payload = 9;
+  
+  // Trace context
+  string trace_id = 10;
+  string span_id = 11;
+  
+  // Labels for filtering
+  map<string, string> labels = 12;
+  
+  // Storage metadata
+  string stream_name = 13; // NATS stream name
+  int64 stream_sequence = 14; // NATS sequence number
+  google.protobuf.Timestamp stored_at = 15;
+}
+
+// PublishEventRequest publishes a single event
+message PublishEventRequest {
+  // Event to publish
+  EventPayload event = 1;
+}
+
+message PublishEventResponse {
+  // Event ID assigned by the store
+  string event_id = 1;
+  
+  // Stream sequence number
+  int64 stream_sequence = 2;
+  
+  // Timestamp when stored
+  google.protobuf.Timestamp stored_at = 3;
+}
+
+// PublishEventBatchRequest publishes multiple events
+message PublishEventBatchRequest {
+  repeated EventPayload events = 1;
+}
+
+message PublishEventBatchResponse {
+  // Number of events published
+  int32 published_count = 1;
+  
+  // Event IDs assigned
+  repeated string event_ids = 2;
+  
+  // First and last sequence numbers
+  int64 first_sequence = 3;
+  int64 last_sequence = 4;
+}
+
+// EventPayload is the input event before storage
+message EventPayload {
+  // Execution context
+  string execution_id = 1;
+  string envelope_id = 2;
+  string tenant_id = 3;
+  string workflow_id = 4;
+  
+  // Event metadata
+  string event_type = 5;
+  google.protobuf.Timestamp timestamp = 6;
+  
+  // Event payload
+  google.protobuf.Struct payload = 7;
+  
+  // Trace context
+  string trace_id = 8;
+  string span_id = 9;
+  
+  // Labels for filtering
+  map<string, string> labels = 10;
+}
+
+// QueryEventsRequest queries events with filters
+message QueryEventsRequest {
+  // Filters (AND logic)
+  string tenant_id = 1;
+  string execution_id = 2;
+  string workflow_id = 3;
+  string event_type = 4;
+  
+  // Time range
+  google.protobuf.Timestamp start_time = 5;
+  google.protobuf.Timestamp end_time = 6;
+  
+  // Label filters
+  map<string, string> labels = 7;
+  
+  // Pagination
+  int32 limit = 8; // Max events to return (default: 100, max: 1000)
+  string page_token = 9; // For pagination
+  
+  // Ordering
+  OrderDirection order = 10;
+  
+  enum OrderDirection {
+    ORDER_DIRECTION_UNSPECIFIED = 0;
+    ASCENDING = 1;
+    DESCENDING = 2;
+  }
+}
+
+message QueryEventsResponse {
+  repeated StoredEvent events = 1;
+  string next_page_token = 2;
+  int32 total_count = 3; // Approximate total (if available)
+}
+
+// GetExecutionEventsRequest gets all events for an execution
+message GetExecutionEventsRequest {
+  string execution_id = 1;
+  
+  // Optional filters
+  string event_type = 2;
+  google.protobuf.Timestamp start_time = 3;
+  google.protobuf.Timestamp end_time = 4;
+  
+  // Pagination
+  int32 limit = 5;
+  string page_token = 6;
+}
+
+message GetExecutionEventsResponse {
+  repeated StoredEvent events = 1;
+  string next_page_token = 2;
+  
+  // Execution summary
+  google.protobuf.Timestamp execution_started_at = 3;
+  google.protobuf.Timestamp execution_ended_at = 4;
+  int32 total_event_count = 5;
+}
+
+// StreamEventsRequest streams events in real-time
+message StreamEventsRequest {
+  // Filters (same as QueryEventsRequest)
+  string tenant_id = 1;
+  string execution_id = 2;
+  string workflow_id = 3;
+  string event_type = 4;
+  
+  // Start from specific sequence or time
+  oneof start_position {
+    int64 start_sequence = 5;
+    google.protobuf.Timestamp start_time = 6;
+  }
+  
+  // Label filters
+  map<string, string> labels = 7;
+}
+
+// GetEventStoreStatsRequest gets statistics
+message GetEventStoreStatsRequest {
+  // Optional tenant filter
+  string tenant_id = 1;
+}
+
+message GetEventStoreStatsResponse {
+  // Total events stored
+  int64 total_events = 1;
+  
+  // Events by type
+  map<string, int64> events_by_type = 2;
+  
+  // Storage size
+  int64 storage_bytes = 3;
+  
+  // Retention info
+  google.protobuf.Timestamp oldest_event = 4;
+  google.protobuf.Timestamp newest_event = 5;
+  
+  // Stream info
+  repeated StreamInfo streams = 6;
+  
+  message StreamInfo {
+    string stream_name = 1;
+    int64 message_count = 2;
+    int64 bytes = 3;
+    google.protobuf.Timestamp first_timestamp = 4;
+    google.protobuf.Timestamp last_timestamp = 5;
+  }
+}
+
+// EventFilter defines retention and storage policies
+message EventFilter {
+  string filter_id = 1;
+  string name = 2;
+  string description = 3;
+  
+  // Match criteria
+  repeated string event_types = 4;
+  repeated string tenant_ids = 5;
+  map<string, string> labels = 6;
+  
+  // Retention policy
+  RetentionPolicy retention = 7;
+  
+  message RetentionPolicy {
+    // Retention duration (e.g., "7d", "30d", "90d")
+    string duration = 1;
+    
+    // Max storage size (bytes)
+    int64 max_bytes = 2;
+    
+    // Max message count
+    int64 max_messages = 3;
+  }
+}
+