syntax = "proto3";

package archive_control.v1;

import "archive_control/v1/common.proto";
import "archive_control/v1/inventory.proto";
import "archive_control/v1/job.proto";
import "archive_control/v1/resource.proto";
import "archive_control/v1/route.proto";
import "google/protobuf/timestamp.proto";

message AssignJobCommand {
  JobDefinition job = 1;
  uint64 expected_job_revision = 2;
  uint64 expected_last_event_sequence = 3;
}

message ExecuteStepCommand {
  string job_id = 1;
  uint64 expected_job_revision = 2;
  JobStepKind step = 3;
  uint32 attempt = 4;
  uint64 expected_last_event_sequence = 5;
}

message CancelJobCommand {
  string job_id = 1;
  uint64 expected_job_revision = 2;
  string reason = 3;
  uint64 expected_last_event_sequence = 4;
}

message EnsureRouteCommand {
  EnsureRouteSpec route = 1;
}

message RequestJobSnapshotCommand {
  repeated string job_ids = 1;
}

// ReconcileJobCommand makes control's durable cursor authoritative after a
// reconnect conflict, local database restore, or rejected stale event. The
// client must durably adopt this cursor before acknowledging the command and
// must never emit output for superseded_command_ids afterwards.
message ReconcileJobCommand {
  JobRecord authoritative_job = 1;
  uint64 authoritative_last_event_sequence = 2;
  repeated string superseded_command_ids = 3;
  string reason = 4;
}

message Command {
  string command_id = 1;
  google.protobuf.Timestamp created_at = 2;
  oneof payload {
    AssignJobCommand assign_job = 10;
    ExecuteStepCommand execute_step = 11;
    CancelJobCommand cancel_job = 12;
    EnsureRouteCommand ensure_route = 13;
    InventoryQuery inventory_query = 14;
    RequestJobSnapshotCommand request_job_snapshot = 15;
    ReconcileJobCommand reconcile_job = 16;
  }
}

enum CommandAckStatus {
  COMMAND_ACK_STATUS_UNSPECIFIED = 0;
  COMMAND_ACK_STATUS_ACCEPTED = 1;
  COMMAND_ACK_STATUS_DUPLICATE = 2;
  COMMAND_ACK_STATUS_REJECTED = 3;
}

// CommandAck confirms durable acceptance/rejection, not completion. Completion
// is reported by JobEvent, InventoryChunk, RouteUpdate, or JobSnapshot.
message CommandAck {
  string command_id = 1;
  CommandAckStatus status = 2;
  Error error = 3;
}

enum JobEventType {
  JOB_EVENT_TYPE_UNSPECIFIED = 0;
  JOB_EVENT_TYPE_ASSIGNED = 1;
  JOB_EVENT_TYPE_STEP_STARTED = 2;
  JOB_EVENT_TYPE_PROGRESS = 3;
  JOB_EVENT_TYPE_WAITING = 4;
  JOB_EVENT_TYPE_STALLED = 5;
  JOB_EVENT_TYPE_STEP_SUCCEEDED = 6;
  JOB_EVENT_TYPE_COMMITTED = 7;
  JOB_EVENT_TYPE_CANCELLING = 8;
  JOB_EVENT_TYPE_ROLLBACK_STARTED = 9;
  JOB_EVENT_TYPE_ROLLBACK_SUCCEEDED = 10;
  JOB_EVENT_TYPE_CLEANUP_REQUIRED = 11;
  JOB_EVENT_TYPE_SUCCEEDED = 12;
  JOB_EVENT_TYPE_FAILED = 13;
  JOB_EVENT_TYPE_CANCELLED = 14;
}

message JobEvent {
  string event_id = 1;
  string job_id = 2;
  uint64 sequence = 3;
  uint64 job_revision = 4;
  JobEventType type = 5;
  JobState state = 6;
  bool committed = 7;
  JobProgress progress = 8;
  Error error = 9;
  ResourceStateFingerprint observed_resource = 10;
  Placement observed_placement = 11;
  google.protobuf.Timestamp occurred_at = 12;
  // The durable ExecuteStepCommand or CancelJobCommand that owns this event.
  // Control verifies this ID, the reporting client, the command's expected
  // cursor, and the permitted step/state transition before appending it.
  string command_id = 13;
}

message JobSnapshot {
  JobRecord job = 1;
  uint64 last_event_sequence = 2;
  repeated string in_flight_command_ids = 3;
}

message ClientStateSnapshot {
  string snapshot_id = 1;
  repeated JobSnapshot active_jobs = 2;
  repeated LocalRoute routes = 3;
  repeated ServiceHealth services = 4;
  google.protobuf.Timestamp observed_at = 5;
}

message RouteUpdate {
  string command_id = 1;
  LocalRoute route = 2;
  RouteVerification verification = 3;
  Error error = 4;
  string update_id = 5;
  // Monotonic for this command_id; duplicate sequences must have identical
  // content and gaps are reconciled through ClientStateSnapshot.
  uint64 sequence = 6;
}

message ProtocolError {
  Error error = 1;
  string offending_message_id = 2;
}