quixos-protocol/proto/quixos/orch.proto

syntax = "proto3";

package quixos.orch;

import "camino/api.proto";
import "camino/schema.proto";
import "quixos/package.proto";
import "quixos/refs.proto";
import "quixos/runtime.proto";

service OrchestratorRuntime {
  rpc ReadDefinitions(DefinitionRequest) returns (DefinitionPage);
  rpc WatchDefinitions(DefinitionRequest) returns (stream DefinitionPage);
  rpc ExecuteQuery(camino.QueryRequest) returns (camino.QueryResponse);
  rpc WatchQuery(camino.QueryRequest) returns (stream QueryEvent);
  rpc TryConform(TryConformRequest) returns (TryConformResponse);
  rpc InvokeCapability(InvokeCapabilityRequest) returns (InvokeCapabilityResponse);
  rpc EditCapabilityField(EditCapabilityFieldRequest) returns (InvokeCapabilityResponse);
  rpc InvokeClassCapability(InvokeClassCapabilityRequest) returns (InvokeCapabilityResponse);
  rpc WatchCapability(WatchCapabilityRequest) returns (stream WatchCapabilityEvent);
  rpc ConstructObject(ConstructObjectRequest) returns (ConstructObjectResponse);
  rpc ResolveOrConstructRelatedObject(ResolveOrConstructRelatedObjectRequest)
      returns (ResolveOrConstructRelatedObjectResponse);
  rpc GetWorkspace(GetWorkspaceRequest) returns (GetWorkspaceResponse);
  rpc ListPackageDescriptors(ListPackageDescriptorsRequest) returns (ListPackageDescriptorsResponse);
  rpc ListPackageRuntimes(ListPackageRuntimesRequest) returns (ListPackageRuntimesResponse);
  rpc ListActivations(ListActivationsRequest) returns (ListActivationsResponse);
  rpc CloseActivation(CloseActivationRequest) returns (CloseActivationResponse);
}

// Activated definitions, not runtime metrics or object data. Nested type JSON
// uses the compiler's canonical ValueType/InterfaceRevision public contracts.
message DefinitionSelector {
  string kind = 1;  // active | atoms | interfaces | conformances | queries | indexes
  repeated string ids = 2;
  string atom_id = 3;
  string interface_revision_id = 4;
  string package_revision_id = 5;
}
message DefinitionIdentity {
  string workspace_id = 1;
  string workspace_revision_id = 2;
  string source_root_commit = 3;
  string workspace_epoch = 4;
  string definition_digest = 5;
}
message DefinitionRequest {
  DefinitionSelector selector = 1;
  uint32 first = 2;  // 1..100; 0 uses 50
  string after = 3;
  string snapshot = 4;         // issued definition_digest; current serving snapshot only
  string workspace_id = 5;     // required for injected package authority
  string workspace_epoch = 6;  // required for invocation-bound package calls
}
message ReflectedAtom {
  string id = 1;
  string display_name = 2;
  string constructor_input_type_json = 3;
}
message ReflectedInterface {
  string id = 1;
  string interface_id = 2;
  string display_name = 3;
  string contract_json = 4;  // canonical interface contract, excluding source location
}
message ReflectedConformance {
  string id = 1;
  string atom_id = 2;
  string interface_revision_id = 3;
  string definition_id = 4;
  repeated string operation_ids = 5;
  repeated ClassCapability class_capabilities = 6;
  bool instance = 7;
}
message ReflectedQuery {
  string id = 1;
  string name = 2;
  string package_revision_id = 3;
  string definition_digest = 4;
  string binding_digest = 5;
  string root_kind = 6;
  string interface_revision_id = 7;
  string variables_type_json = 8;
  string output_type_json = 9;
  string effects_json = 10;
  bool watch = 11;
  WorkspaceQueryScope workspace_scope = 12;
}
message ReflectedIndex {
  string id = 1;
  string contract_json = 2;
}
message DefinitionRecord {
  oneof definition {
    ReflectedAtom atom = 1;
    ReflectedInterface interface = 2;
    ReflectedConformance conformance = 3;
    ReflectedQuery query = 4;
    ReflectedIndex index = 5;
  }
}
message DefinitionPage {
  DefinitionIdentity identity = 1;
  repeated DefinitionRecord records = 2;
  string next_cursor = 3;
}

message QueryEvent {
  string run_id = 1;
  uint64 sequence = 2;
  string kind = 3;
  camino.QueryResponse snapshot = 4;
  repeated camino.QueryPathPart path = 5;
  camino.Value value = 6;
  string error = 7;
}

// Exact closed interface lookup; no policy selection or competing conformances.
message TryConformRequest {
  string object_id = 1;
  string interface_revision_id = 2;
}
message TryConformResponse {
  // Absent only when this object lacks a known contract. Other failures are errors.
  quixos.ConformanceWitness conformance = 1;
}

message ConstructObjectRequest {
  string atom_id = 1;
  map<string, camino.Value> input = 2;
}
message ConstructObjectResponse {
  camino.CaminoObject object = 1;
}

message ResolveOrConstructRelatedObjectRequest {
  string object_id = 1;
  string interface_revision_id = 2;
  string member_id = 3;
}
message ResolveOrConstructRelatedObjectResponse {
  camino.CaminoObject object = 1;
  bool constructed = 2;
}

message InvokeCapabilityRequest {
  quixos.CapabilityRef capability = 1;
  string object_id = 2;
  map<string, camino.Value> input = 3;
  // Identifies one logical client mutation across the capability and Camino
  // layers so a live-value controller can recognize its own confirmation.
  string client_mutation_id = 4;
}
message InvokeClassCapabilityRequest {
  string conformance_id = 1;
  string operation_id = 2;
  map<string, camino.Value> input = 3;
}
message InvokeCapabilityResponse {
  string invocation_id = 1;
  Activation activation = 2;
  bool ok = 3;
  camino.Value result = 4;
  string error = 5;
  repeated quixos.runtime.DerivedDependency dependencies = 6;
  FieldEditing field_editing = 7;
}

message EditCapabilityFieldRequest {
  // The public getter; setter must belong to the same value member.
  quixos.CapabilityRef capability = 1;
  string object_id = 2;
  string setter_operation_id = 3;
  string binding_digest = 4;
  oneof edit {
    camino.CrdtValue update = 5;
    camino.Value replacement = 7;
  }
  string client_mutation_id = 6;
}

message WatchCapabilityRequest {
  quixos.CapabilityRef capability = 1;
  string object_id = 2;
  map<string, camino.Value> input = 3;
}
message WatchCapabilityEvent {
  string invocation_id = 1;
  Activation activation = 2;
  string watch_id = 3;
  camino.Value value = 4;
  repeated quixos.runtime.DerivedDependency dependencies = 5;
  string error = 6;
  bool initial = 7;
  FieldEditing field_editing = 8;
}

message GetWorkspaceRequest {
  // Revision polling must not download the entire interface graph.
  bool include_interface_contracts = 1;
  bool include_query_contracts = 2;
}
message GetWorkspaceResponse {
  string workspace_id = 1;
  string workspace_revision_id = 2;
  string source_root_commit = 3;
  // Checked constructors whose wire input can be empty. The create panel uses
  // class factory conformances instead of this constructor inventory.
  repeated string empty_input_constructible_atom_ids = 4;
  repeated CapabilityInputContract capability_inputs = 5;
  repeated ConstructorInputContract constructor_inputs = 6;
  // Exact closed interface contracts used by checked presentation consumers.
  string interfaces_json = 7;
  repeated ClassCapability class_capabilities = 8;
  repeated QueryDescription queries = 9;
  uint32 active_query_executions = 10;
}
message QueryDescription {
  string id = 1;
  string name = 2;
  string package_revision_id = 3;
  string document = 4;
  string schema = 5;
  repeated string source_files = 6;
  string effects_json = 7;
  camino.InstalledQuery plan = 8;
  WorkspaceQueryScope workspace_scope = 9;
}
message ClassCapability {
  string conformance_id = 1;
  string atom_id = 2;
  string interface_revision_id = 3;
  string definition_id = 4;
  string operation_id = 5;
  string input_type_json = 6;
  string output_type_json = 7;
}
message CapabilityInputContract {
  string interface_revision_id = 1;
  string operation_id = 2;
  string type_json = 3;
}
message ConstructorInputContract {
  string atom_id = 1;
  string type_json = 2;
}
message ListActivationsRequest {}
message ListPackageDescriptorsRequest {}
message ListPackageDescriptorsResponse {
  repeated quixos.PackageDescriptor descriptors = 1;
}
message ListPackageRuntimesRequest {}
message ListPackageRuntimesResponse {
  repeated PackageRuntimeStatus runtimes = 1;
}
message ListActivationsResponse {
  repeated Activation activations = 1;
}
message CloseActivationRequest {
  string activation_id = 1;
  string reason = 2;
}
message CloseActivationResponse {
  Activation activation = 1;
}

message Activation {
  string activation_id = 1;
  quixos.PackageExportRef export = 2;
  string object_id = 3;
  string state = 4;
  uint32 demand = 5;
  string opened_at = 6;
  string last_used_at = 7;
  string idle_deadline_at = 8;
  string closed_at = 9;
  string close_reason = 10;
}

message PackageRuntimeStatus {
  string runtime_key = 1;
  string package_revision_id = 2;
  string source_repository = 3;
  string source_commit = 4;
  string build_target = 5;
  string server_path = 6;
  uint32 pid = 7;
  string state = 8;
  string started_at = 9;
  string last_handshake_at = 10;
  string runtime_protocol_version = 11;
  uint32 advertised_export_count = 12;
}