syntax = "proto3";

package artifact.v1alpha;

// Artifact definitions
import "artifact/v1alpha/knowledge_base.proto";

// KnowledgeBaseUpdateStatus represents the various states of a Knowledge Base
// update lifecycle
enum KnowledgeBaseUpdateStatus {
  // KNOWLEDGE_BASE_UPDATE_STATUS_UNSPECIFIED - Invalid/unknown state
  KNOWLEDGE_BASE_UPDATE_STATUS_UNSPECIFIED = 0;

  // KNOWLEDGE_BASE_UPDATE_STATUS_NONE - KB has never been updated (default
  // state for new KBs)
  KNOWLEDGE_BASE_UPDATE_STATUS_NONE = 1;

  // KNOWLEDGE_BASE_UPDATE_STATUS_UPDATING - Phase 1-2: Preparing and
  // reprocessing The staging KB is being created and populated by reprocessing
  // all files with new configuration
  KNOWLEDGE_BASE_UPDATE_STATUS_UPDATING = 2;

  // KNOWLEDGE_BASE_UPDATE_STATUS_SYNCING - Phase 3: Synchronization
  // Locking KB and waiting for all dual-processed files to complete
  KNOWLEDGE_BASE_UPDATE_STATUS_SYNCING = 3;

  // KNOWLEDGE_BASE_UPDATE_STATUS_VALIDATING - Phase 4: Validation
  // Validating data integrity (file counts, embeddings, chunks)
  KNOWLEDGE_BASE_UPDATE_STATUS_VALIDATING = 4;

  // KNOWLEDGE_BASE_UPDATE_STATUS_SWAPPING - Phase 5: Atomic Swap
  // Performing atomic pointer swap of collections and metadata
  KNOWLEDGE_BASE_UPDATE_STATUS_SWAPPING = 5;

  // KNOWLEDGE_BASE_UPDATE_STATUS_COMPLETED - Phase 6: Cleanup/Retention
  // Update completed successfully, rollback KB retained for configured period
  KNOWLEDGE_BASE_UPDATE_STATUS_COMPLETED = 6;

  // KNOWLEDGE_BASE_UPDATE_STATUS_FAILED - Update failed at some point
  // Production KB remains unchanged and can be used normally
  KNOWLEDGE_BASE_UPDATE_STATUS_FAILED = 7;

  // KNOWLEDGE_BASE_UPDATE_STATUS_ROLLED_BACK - Update was rolled back
  // Previous version has been restored from the rollback KB
  KNOWLEDGE_BASE_UPDATE_STATUS_ROLLED_BACK = 8;

  // KNOWLEDGE_BASE_UPDATE_STATUS_ABORTED - Update was manually aborted
  // Production KB remains unchanged and can be updated again
  KNOWLEDGE_BASE_UPDATE_STATUS_ABORTED = 9;
}

// KnowledgeBaseUpdateDetails provides detailed information about a knowledge
// base update
message KnowledgeBaseUpdateDetails {
  // The resource name of the knowledge base.
  // Format: `namespaces/{namespace}/knowledge-bases/{knowledge_base}`
  string knowledge_base = 1;
  // Status of the knowledge base update
  KnowledgeBaseUpdateStatus status = 2;
  // Workflow ID of the knowledge base update
  string workflow_id = 3;
  // Started at time of the knowledge base update
  string started_at = 4;
  // Completed at time of the knowledge base update
  string completed_at = 5;
  // Number of files processed
  int32 files_processed = 6;
  // Total number of files to process
  int32 total_files = 7;
  // Error message explaining why the update failed
  // Populated ONLY when status is KNOWLEDGE_BASE_UPDATE_STATUS_FAILED
  // Empty for all other statuses (NONE, UPDATING, SYNCING, VALIDATING,
  // SWAPPING, COMPLETED, ROLLED_BACK, ABORTED)
  string error_message = 8;
  // The resource name of the current system (e.g., "systems/openai",
  // "systems/gemini"). Format: `systems/{system}` The system configuration
  // currently active in the production KB.
  // - For UPDATING: The system being updated to (from staging KB - will become
  // current after swap)
  // - For COMPLETED/FAILED/ROLLED_BACK/ABORTED/NONE: The current production
  // system Always reflects the KB's current state.
  string current_system = 9;
  // The resource name of the previous system before the update.
  // Format: `systems/{system}`
  // Captured at update start for historical audit trail.
  // - For UPDATING: The system before update started
  // - For COMPLETED: The system before successful update (what was replaced)
  // - For FAILED/ABORTED: The system before failed attempt (same as current,
  // since update didn't complete)
  // - For ROLLED_BACK: The system that was rolled back FROM (before rollback)
  // - For NONE: Empty (never been updated)
  string previous_system = 10;
}

// Admin-only rollback operations

// RollbackAdminRequest (admin only)
message RollbackAdminRequest {
  // Format: users/{user}/knowledge-bases/{knowledge_base}
  string name = 1;
}

// RollbackAdminResponse (admin only)
message RollbackAdminResponse {
  // The rolled-back knowledge base
  KnowledgeBase knowledge_base = 1;
  // Status message
  string message = 2;
}

// PurgeRollbackAdminRequest (admin only)
message PurgeRollbackAdminRequest {
  // Format: users/{user}/knowledge-bases/{knowledge_base}
  string name = 1;
}

// PurgeRollbackAdminResponse (admin only)
message PurgeRollbackAdminResponse {
  // Whether the purge was successful
  bool success = 1;
  // The resource name of the purged knowledge base.
  // Format: `namespaces/{namespace}/knowledge-bases/{knowledge_base}`
  string purged_knowledge_base = 2;
  // Number of files deleted
  int32 deleted_files = 3;
  // Status message
  string message = 4;
}

// SetRollbackRetentionAdminRequest (admin only)
message SetRollbackRetentionAdminRequest {
  // TimeUnit specifies the unit of time for retention duration
  enum TimeUnit {
    // Unspecified
    TIME_UNIT_UNSPECIFIED = 0;
    // Seconds
    TIME_UNIT_SECOND = 1;
    // Minutes
    TIME_UNIT_MINUTE = 2;
    // Hours
    TIME_UNIT_HOUR = 3;
    // Days
    TIME_UNIT_DAY = 4;
  }

  // Format: users/{user}/knowledge-bases/{knowledge_base}
  string name = 1;
  // Duration value (e.g., 5, 30, 24, 7)
  int32 duration = 2;
  // Time unit (second, minute, hour, day)
  TimeUnit time_unit = 3;
}

// SetRollbackRetentionAdminResponse (admin only)
message SetRollbackRetentionAdminResponse {
  // Previous retention until date
  string previous_retention_until = 1;
  // New retention until date
  string new_retention_until = 2;
  // Total retention duration in seconds
  int64 total_retention_seconds = 3;
}

// GetKnowledgeBaseUpdateStatusAdminRequest (admin only)
message GetKnowledgeBaseUpdateStatusAdminRequest {
  // Empty - gets current system update status
}

// GetKnowledgeBaseUpdateStatusAdminResponse (admin only)
message GetKnowledgeBaseUpdateStatusAdminResponse {
  // Whether update is in progress
  bool update_in_progress = 1;
  // List of knowledge base update details
  repeated KnowledgeBaseUpdateDetails details = 2;
  // Status message
  string message = 3;
}

// ExecuteKnowledgeBaseUpdateAdminRequest (admin only)
message ExecuteKnowledgeBaseUpdateAdminRequest {
  // Optional: Specific knowledge base resource names to update. If empty,
  // updates all eligible knowledge bases. Format:
  // `namespaces/{namespace}/knowledge-bases/{knowledge_base}`
  repeated string knowledge_bases = 1;

  // Optional: System resource name containing configuration to apply.
  // Format: `systems/{system}`
  // If specified, uses config from the specified system.
  // If not specified, KBs keep their current config (useful for reprocessing).
  optional string system = 2;

  // Optional: Tags to filter which knowledge bases to update (OR logic - match
  // any tag).
  repeated string tags = 3;
}

// ExecuteKnowledgeBaseUpdateAdminResponse (admin only)
message ExecuteKnowledgeBaseUpdateAdminResponse {
  // Whether the workflow started successfully
  bool started = 1;
  // Human-readable status message explaining the result
  string message = 2;
  // List of knowledge base update details (populated when update already in
  // progress)
  repeated KnowledgeBaseUpdateDetails details = 3;
}

// AbortKnowledgeBaseUpdateAdminRequest (admin only)
message AbortKnowledgeBaseUpdateAdminRequest {
  // Optional: Specific knowledge base resource names to abort. If empty, aborts
  // all currently updating knowledge bases. Format:
  // `namespaces/{namespace}/knowledge-bases/{knowledge_base}`
  repeated string knowledge_bases = 1;
}

// AbortKnowledgeBaseUpdateAdminResponse (admin only)
message AbortKnowledgeBaseUpdateAdminResponse {
  // Whether the abort operation completed successfully
  bool success = 1;
  // Human-readable status message explaining the result
  string message = 2;
  // List of knowledge base update details that were aborted
  repeated KnowledgeBaseUpdateDetails details = 3;
}