quixos-protocol/proto/camino/schema.proto

syntax = "proto3";

package camino;

enum Cardinality {
  CARDINALITY_UNSPECIFIED = 0;
  OPTIONAL_ONE = 1;
  EXACTLY_ONE = 2;
  MANY = 3;
  MANY_UNIQUE = 4;
}

message AtomDefinition {
  string atom_id = 1;
  string display_name = 2;
}

message AtomConformance {
  string atom_id = 1;
  string interface_revision_id = 2;
  string conformance_id = 3;
}

message StateAttachment {
  string slot_id = 1;
  string attached_atom_id = 2;
  string display_name = 3;
  string value_type_json = 4;
  string storage_policy_json = 5;
  string default_value_json = 6;
  string owner_conformance_id = 7;
}

message EndpointConstraint {
  oneof kind {
    string atom_id = 1;
    string interface_revision_id = 2;
  }
}

message EdgeEndpoint {
  string projection_id = 1;
  string display_name = 2;
  EndpointConstraint constraint = 3;
  Cardinality cardinality = 4;
  bool ordered = 5;
  // Empty means restrict. Direction is the endpoint being deleted.
  string on_delete = 6;
  bool retain_other = 7;
  // Empty for sets/lists, otherwise string, boolean, or int64 map keys.
  string key_type = 8;
  // Explicit read-only dependency injection traversal, not mutation authority.
  bool public_traversal = 9;
}

message EdgeAttachment {
  string edge_type_id = 1;
  string display_name = 2;
  EdgeEndpoint first = 3;
  EdgeEndpoint second = 4;
  string owner_conformance_id = 5;
}

// Camino consumes this persistence-only projection of a checked workspace.
// Interfaces, operation bindings, packages, and constructors stay in orch.
message PersistencePlan {
  string workspace_id = 1;
  string workspace_revision_id = 2;
  repeated AtomDefinition atoms = 3;
  repeated AtomConformance conformances = 4;
  repeated StateAttachment states = 5;
  repeated EdgeAttachment edges = 6;
  repeated InstalledQuery queries = 7;
}

// Immutable checked query IR. Installed only with the checked persistence plan;
// query callers select its ID, never send or modify these definitions.
message QueryArgument {
  oneof value {
    string variable = 1;
    string literal_json = 2;
    QueryArgumentList list = 3;
    QueryArgumentObject object = 4;
  }
}
message QueryArgumentList {
  repeated QueryArgument values = 1;
}
message QueryArgumentObject {
  map<string, QueryArgument> fields = 1;
}
message QueryCondition {
  bool include = 1;
  QueryArgument value = 2;
}
message QuerySelection {
  string name = 1;
  string key = 2;
  string interface_revision_id = 3;
  string member_id = 4;
  string target_interface_revision_id = 5;
  repeated QueryCondition conditions = 6;
  map<string, QueryArgument> arguments = 7;
  repeated QuerySelection selection = 8;
  QueryRelationalPlan relational = 9;
  QueryPredicate predicate = 10;
  // Stable checked selection identity; empty for ordinary value projections.
  string live_selection_id = 11;
}
// Resolved IDs, not GraphQL names, determine execution. Response selections
// remain separate so aliases and fragments cannot change relational semantics.
message QueryPathStep {
  oneof step {
    bool source = 1;
    bool target = 2;
    QueryRelationPath relation = 3;
  }
}
message QueryRelationPath {
  string interface_revision_id = 1;
  string member_id = 2;
  string target_interface_revision_id = 3;
  bool optional = 4;
}
message QueryFieldOperand {
  string interface_revision_id = 1;
  string member_id = 2;
}
message QueryExpression {
  repeated QueryPathStep path = 1;
  oneof leaf {
    QueryFieldOperand field = 2;
    string ref = 3;
    bool entry = 4;
    bool map_key = 5;
  }
  string value_type_json = 6;
}
enum QueryAggregateOperator {
  QUERY_AGGREGATE_OPERATOR_UNSPECIFIED = 0;
  QUERY_AGGREGATE_OPERATOR_COUNT = 1;
  QUERY_AGGREGATE_OPERATOR_COUNT_PRESENT = 2;
  QUERY_AGGREGATE_OPERATOR_SUM = 3;
  QUERY_AGGREGATE_OPERATOR_AVG = 4;
  QUERY_AGGREGATE_OPERATOR_MIN = 5;
  QUERY_AGGREGATE_OPERATOR_MAX = 6;
}
message QueryReduction {
  QueryAggregateOperator operator = 1;
  QueryExpression operand = 2;
  string value_type_json = 3;
}
message QueryOperand {
  oneof operand {
    QueryExpression expression = 1;
    QueryReduction reduction = 2;
  }
}
enum QueryComparisonOperator {
  QUERY_COMPARISON_OPERATOR_UNSPECIFIED = 0;
  QUERY_COMPARISON_OPERATOR_EQ = 1;
  QUERY_COMPARISON_OPERATOR_IN = 2;
  QUERY_COMPARISON_OPERATOR_IS_NULL = 3;
  QUERY_COMPARISON_OPERATOR_LT = 4;
  QUERY_COMPARISON_OPERATOR_LTE = 5;
  QUERY_COMPARISON_OPERATOR_GT = 6;
  QUERY_COMPARISON_OPERATOR_GTE = 7;
}
message QueryComparison {
  QueryOperand operand = 1;
  QueryComparisonOperator operator = 2;
  QueryArgument value = 3;
}
message QueryPredicateList {
  repeated QueryPredicate children = 1;
}
enum QueryRelationPredicateOperator {
  QUERY_RELATION_PREDICATE_OPERATOR_UNSPECIFIED = 0;
  QUERY_RELATION_PREDICATE_OPERATOR_SOME = 1;
  QUERY_RELATION_PREDICATE_OPERATOR_NONE = 2;
  QUERY_RELATION_PREDICATE_OPERATOR_IS = 3;
  QUERY_RELATION_PREDICATE_OPERATOR_IS_NULL = 4;
}
message QueryRelationPredicate {
  repeated QueryPathStep path = 1;
  QueryRelationPath relation = 2;
  QueryRelationPredicateOperator operator = 3;
  QueryPredicate predicate = 4;
  QueryArgument value = 5;
}
message QueryReductionPredicate {
  repeated QueryPathStep path = 1;
  QueryRelationPath relation = 2;
  QueryPredicate where = 3;
  QueryPredicate having = 4;
}
message QueryPredicate {
  oneof predicate {
    QueryPredicateList and = 1;
    QueryPredicateList or = 2;
    QueryPredicate not = 3;
    QueryComparison compare = 4;
    QueryRelationPredicate relation = 5;
    QueryReductionPredicate reduce = 6;
  }
}
message QueryRow {
  oneof row {
    QueryObjectRow object = 1;
    QueryPairRow pair = 2;
  }
}
message QueryObjectRow {
  string interface_revision_id = 1;
  bool membership = 2;
  string key_type = 3;
}
message QueryPairRow {
  QueryRow source = 1;
  QueryRow target = 2;
}
message QueryKey {
  repeated string path = 1;
  QueryExpression expression = 2;
}
message QueryDistinct {
  repeated QueryKey keys = 1;
}
message QueryExpansion {
  repeated QueryPathStep path = 1;
  QueryRelationPath relation = 2;
}
message QueryRelationalStage {
  uint32 id = 1;
  optional uint32 input = 2;
  QueryRow row = 3;
  oneof operation {
    QueryRelationPath source = 4;
    QueryPredicate filter = 5;
    QueryExpansion expand = 6;
    QueryDistinct distinct = 7;
  }
}
message QueryReductionProjection {
  repeated string path = 1;
  QueryReduction reduction = 2;
}
message QueryAggregateOrder {
  QueryOperand operand = 1;
  bool descending = 2;
}
message QueryRelationalTerminal {
  uint32 stage = 1;
  repeated string path = 2;
  bool groups = 3;
  repeated QueryKey keys = 4;
  repeated QueryReductionProjection reductions = 5;
  QueryPredicate where = 6;
  QueryPredicate having = 7;
  repeated QueryAggregateOrder order = 8;
  QueryArgument first = 9;
  QueryArgument all = 10;
  QueryArgument after = 11;
  repeated QuerySelection selection = 12;
  bool residual = 13;
  // Internal ordinary-relationship residual: yields ordered membership IDs.
  bool rows = 14;
}
message QueryRelationalPlan {
  repeated QueryRelationalStage stages = 1;
  repeated QueryRelationalTerminal terminals = 2;
}
message QueryReadBinding {
  string atom_id = 1;
  string interface_revision_id = 2;
  string member_id = 3;
  string getter_operation_id = 4;
  string slot_id = 5;
  string edge_type_id = 6;
  string projection_id = 7;
  bool rpc = 8;
  string watch_start_operation_id = 9;
  string watch_stop_operation_id = 10;
  string field_name = 11;
  string value_type_json = 12;
  Cardinality cardinality = 13;
  string key_type = 14;
}
// Checked schema survives even when no atom currently implements an interface.
message QueryFieldContract {
  string interface_revision_id = 1;
  string member_id = 2;
  string field_name = 3;
  string value_type_json = 4;
  Cardinality cardinality = 5;
  string key_type = 6;
}
message QueryBudgets {
  uint32 rows = 1;
  uint32 depth = 2;
  uint32 result_bytes = 3;
  uint32 candidates = 4;
  uint32 rpc_calls = 5;
  uint32 concurrency = 6;
  uint32 deadline_ms = 7;
}
message InstalledQuery {
  string id = 1;
  string definition_digest = 2;
  string binding_digest = 3;
  oneof root {
    string object_interface = 4;
    string workspace_interface = 14;
  }
  repeated QuerySelection selection = 5;
  repeated QueryReadBinding bindings = 6;
  QueryBudgets budgets = 7;
  string variables_type_json = 8;
  string output_type_json = 9;
  map<string, QueryArgument> variable_defaults = 10;
  bool watch = 11;
  uint32 polling_interval_ms = 12;
  bool rpc_predicate_or_order = 13;
  repeated string root_atom_ids = 15;
  repeated QueryFieldContract fields = 16;
}