quixos-protocol/proto/camino/api.proto

syntax = "proto3";

package camino;

import "camino/schema.proto";

service CaminoService {
  rpc InstallPersistencePlan(InstallPersistencePlanRequest) returns (InstallPersistencePlanResponse);
  rpc GetPersistencePlan(GetPersistencePlanRequest) returns (GetPersistencePlanResponse);
  rpc CreateObject(CreateObjectRequest) returns (CreateObjectResponse);
  rpc GetObject(GetObjectRequest) returns (GetObjectResponse);
  rpc ListObjects(ListObjectsRequest) returns (ListObjectsResponse);
  rpc ReadState(ReadStateRequest) returns (ReadStateResponse);
  rpc WriteState(WriteStateRequest) returns (WriteStateResponse);
  rpc ConnectEdge(ConnectEdgeRequest) returns (ConnectEdgeResponse);
  rpc ResolveEdge(ResolveEdgeRequest) returns (ResolveEdgeResponse);
  rpc DisconnectEdge(DisconnectEdgeRequest) returns (DisconnectEdgeResponse);
  rpc ReadCollection(ResolveEdgeRequest) returns (ReadCollectionResponse);
  rpc ReplaceCollection(ReplaceCollectionRequest) returns (ReadCollectionResponse);
  rpc ListOps(ListOpsRequest) returns (ListOpsResponse);
  rpc WatchObject(WatchObjectRequest) returns (stream WatchObjectEvent);
}

message NullValue {}
message ObjectValue { map<string, Value> fields = 1; }
message ListValue { repeated Value values = 1; }
message RefValue { string object_id = 1; }
message CrdtValue {
  string type = 1;
  string encoding = 2;
  bytes payload = 3;
}

message StateValueSource {
  string object_id = 1;
  string slot_id = 2;
  string value_type_json = 3;
  string storage_policy_json = 4;
  uint64 revision = 5;
  // CRDT-backed state is still read as its materialized Value. The snapshot
  // travels with the writable source identity so a client can retain and
  // advance a local replica without exposing the document to package code.
  CrdtValue crdt_snapshot = 6;
}

message ValueSource { StateValueSource state = 1; }

message Value {
  oneof kind {
    NullValue null_value = 1;
    bool bool_value = 2;
    double number_value = 3;
    string string_value = 4;
    string integer_value = 5;
    bytes bytes_value = 6;
    ObjectValue object_value = 7;
    ListValue list_value = 8;
    RefValue ref_value = 9;
    CrdtValue crdt_value = 10;
  }
  ValueSource source = 11;
}

message InstallPersistencePlanRequest { PersistencePlan plan = 1; }
message InstallPersistencePlanResponse { PersistencePlan plan = 1; }
message GetPersistencePlanRequest {}
message GetPersistencePlanResponse { PersistencePlan plan = 1; }

message CreateObjectRequest {
  string atom_id = 1;
  map<string, Value> initial_state = 2;
}
message CreateObjectResponse { CaminoObject object = 1; }
message GetObjectRequest { string object_id = 1; }
message GetObjectResponse { CaminoObject object = 1; }
message ListObjectsRequest { string atom_id = 1; }
message ListObjectsResponse { repeated CaminoObject objects = 1; }

message ReadStateRequest {
  string object_id = 1;
  string slot_id = 2;
}
message ReadStateResponse { Value value = 1; }
message WriteStateRequest {
  string object_id = 1;
  string slot_id = 2;
  Value value = 3;
  string client_mutation_id = 4;
}
message WriteStateResponse {
  Value value = 1;
  CaminoObject object = 2;
}

message ConnectEdgeRequest {
  string edge_type_id = 1;
  string projection_id = 2;
  string object_id = 3;
  string target_object_id = 4;
  optional int32 ordinal = 5;
  optional int32 target_ordinal = 6;
}
message ConnectEdgeResponse { CaminoEdge edge = 1; }
message ResolveEdgeRequest {
  string object_id = 1;
  string edge_type_id = 2;
  string projection_id = 3;
}
message ResolveEdgeResponse { repeated CaminoEdge edges = 1; }
message DisconnectEdgeRequest { string edge_id = 1; }
message DisconnectEdgeResponse { string edge_id = 1; }

message CollectionEntry {
  // Existing entry identity to preserve; empty allocates a new canonical edge.
  string edge_id = 1;
  string target_object_id = 2;
  Value key = 3;
}
message ReadCollectionResponse {
  uint64 revision = 1;
  repeated CollectionEntry entries = 2;
}
message ReplaceCollectionRequest {
  string object_id = 1;
  string edge_type_id = 2;
  string projection_id = 3;
  uint64 expected_revision = 4;
  repeated CollectionEntry entries = 5;
}

message ListOpsRequest { string object_id = 1; }
message ListOpsResponse { repeated CaminoOp ops = 1; }
message WatchObjectRequest {
  string object_id = 1;
  string after_op_id = 2;
  bool include_snapshot = 3;
  // Managed runtimes must watch only their injected attachments.
  repeated string attachment_ids = 4;
}
message WatchObjectEvent {
  string object_id = 1;
  CaminoObject snapshot = 2;
  CaminoOp op = 3;
}

message CaminoObject {
  string id = 1;
  string atom_id = 2;
  string workspace_revision_id = 3;
  string created_at = 4;
  string updated_at = 5;
  map<string, Value> state = 6;
  map<string, uint64> state_revisions = 7;
}

message CaminoEdge {
  string id = 1;
  string edge_type_id = 2;
  string first_object_id = 3;
  string second_object_id = 4;
  string first_projection_id = 5;
  string second_projection_id = 6;
  optional int32 first_ordinal = 7;
  optional int32 second_ordinal = 8;
  string created_at = 9;
  string first_key_json = 10;
  string second_key_json = 11;
}

message CaminoOp {
  string id = 1;
  string object_id = 2;
  string op_kind = 3;
  Value payload = 4;
  string actor = 5;
  string created_at = 6;
  string client_mutation_id = 7;
}