syntax = "proto3";

package artifact.v1alpha;

// Google API
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
// Protocol Buffers Well-Known Types
import "google/protobuf/field_mask.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/timestamp.proto";

// file embedding process status
enum FileProcessStatus {
  // UNSPECIFIED
  FILE_PROCESS_STATUS_UNSPECIFIED = 0;
  // NOTSTARTED
  FILE_PROCESS_STATUS_NOTSTARTED = 1;
  // file is being processed (parallel architecture: conversion + summarization)
  FILE_PROCESS_STATUS_PROCESSING = 2;
  // file is chunking
  FILE_PROCESS_STATUS_CHUNKING = 3;
  // file is embedding
  FILE_PROCESS_STATUS_EMBEDDING = 4;
  // completed
  FILE_PROCESS_STATUS_COMPLETED = 5;
  // failed
  FILE_PROCESS_STATUS_FAILED = 6;
}

// converted file type
enum ConvertedFileType {
  // unspecified
  CONVERTED_FILE_TYPE_UNSPECIFIED = 0;
  // content
  CONVERTED_FILE_TYPE_CONTENT = 1;
  // summary
  CONVERTED_FILE_TYPE_SUMMARY = 2;
  // document (standardized to PDF)
  CONVERTED_FILE_TYPE_DOCUMENT = 3;
  // image (standardized to PNG)
  CONVERTED_FILE_TYPE_IMAGE = 4;
  // audio (standardized to OGG)
  CONVERTED_FILE_TYPE_AUDIO = 5;
  // video (standardized to MP4)
  CONVERTED_FILE_TYPE_VIDEO = 6;
  // thumbnail (1024px WebP preview generated by `GenerateThumbnailActivity`).
  // One row per original file, persisted alongside the other
  // `converted_file` rows. The corresponding MinIO object is exposed to
  // clients via `File.thumbnail_uri` as a stable
  // `/v1alpha/blob-urls/{object_uid}` URL — see
  // `artifact-backend/docs/blob-storage-architecture.md`.
  CONVERTED_FILE_TYPE_THUMBNAIL = 7;
}

// File represents a file in a knowledge base.
// Field ordering follows AIP standard: name(1), id(2), display_name(3),
// slug(4), aliases(5), description(6)
message File {
  option (google.api.resource) = {
    type: "api.instill.tech/File"
    pattern:
      "namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/"
      "{file}"
  };

  // View defines how a file is presented.
  enum View {
    // Unspecified, equivalent to BASIC.
    VIEW_UNSPECIFIED = 0;
    // Default view, only includes basic metadata.
    VIEW_BASIC = 1;
    // Full representation with all metadata.
    VIEW_FULL = 2;
    // Returns MinIO pre-signed URL to converted summary content.
    VIEW_SUMMARY = 3;
    // Returns MinIO pre-signed URL to converted markdown content.
    VIEW_CONTENT = 4;
    // Returns MinIO pre-signed URL to standardized file:
    // - Documents → PDF
    // - Images → PNG
    // - Audio → OGG
    // - Video → MP4
    VIEW_STANDARD_FILE_TYPE = 5;
    // Returns MinIO pre-signed URL to the original uploaded file.
    VIEW_ORIGINAL_FILE_TYPE = 6;
    // Returns Gemini cache resource name.
    VIEW_CACHE = 7;
    // Returns MinIO pre-signed URL to patch.md (user-submitted content patches).
    VIEW_PATCH = 8;
  }

  // Storage provider for file resources
  enum StorageProvider {
    // Unspecified, defaults to MinIO for backward compatibility
    STORAGE_PROVIDER_UNSPECIFIED = 0;
    // Use MinIO as the storage backend (default)
    STORAGE_PROVIDER_MINIO = 1;
    // Use Google Cloud Storage as the storage backend
    STORAGE_PROVIDER_GCS = 2;
  }

  // Supported file types
  enum Type {
    // unspecified
    TYPE_UNSPECIFIED = 0;

    // Text-based document types
    // text
    TYPE_TEXT = 1;
    // MARKDOWN
    TYPE_MARKDOWN = 2;
    // HTML
    TYPE_HTML = 3;
    // CSV
    TYPE_CSV = 4;
    // JSON
    TYPE_JSON = 39;

    // Container-based document types
    // PDF
    TYPE_PDF = 5;
    // DOC
    TYPE_DOC = 6;
    // DOCX
    TYPE_DOCX = 7;
    // PPT
    TYPE_PPT = 8;
    // PPTX
    TYPE_PPTX = 9;
    // XLS
    TYPE_XLS = 10;
    // XLSX
    TYPE_XLSX = 11;

    // Image types
    // PNG
    TYPE_PNG = 12;
    // JPEG
    TYPE_JPEG = 13;
    // GIF
    TYPE_GIF = 14;
    // WEBP
    TYPE_WEBP = 15;
    // TIFF
    TYPE_TIFF = 16;
    // BMP
    TYPE_BMP = 17;
    // HEIC
    TYPE_HEIC = 18;
    // HEIF
    TYPE_HEIF = 19;
    // AVIF
    TYPE_AVIF = 20;
    // SVG
    TYPE_SVG = 38;

    // Audio types
    // MP3
    TYPE_MP3 = 21;
    // WAV
    TYPE_WAV = 22;
    // AAC
    TYPE_AAC = 23;
    // OGG
    TYPE_OGG = 24;
    // FLAC
    TYPE_FLAC = 25;
    // M4A
    TYPE_M4A = 26;
    // WMA
    TYPE_WMA = 27;
    // AIFF
    TYPE_AIFF = 28;
    // WEBM (audio)
    TYPE_WEBM_AUDIO = 29;

    // Video types
    // MP4
    TYPE_MP4 = 30;
    // AVI
    TYPE_AVI = 31;
    // MOV
    TYPE_MOV = 32;
    // MKV
    TYPE_MKV = 33;
    // FLV
    TYPE_FLV = 34;
    // WMV
    TYPE_WMV = 35;
    // MPEG
    TYPE_MPEG = 36;
    // WEBM (video)
    TYPE_WEBM_VIDEO = 37;
  }

  // FileMediaType describes the media category of a knowledge base file.
  enum FileMediaType {
    // Unspecified.
    FILE_MEDIA_TYPE_UNSPECIFIED = 0;
    // Document.
    FILE_MEDIA_TYPE_DOCUMENT = 1;
    // Image.
    FILE_MEDIA_TYPE_IMAGE = 2;
    // Audio.
    FILE_MEDIA_TYPE_AUDIO = 3;
    // Video.
    FILE_MEDIA_TYPE_VIDEO = 4;
  }

  // Position within a file, as coordinates in a specific unit. The
  // number of dimensions of the coordinate depends on the unit type.
  message Position {
    // Unit of measurement for a position within a file.
    enum Unit {
      // Unspecified.
      UNIT_UNSPECIFIED = 0;
      // Character positions (for Markdown and other text files).
      UNIT_CHARACTER = 1;
      // Page positions (for documents). For pages, positions are 1-indexed
      // (e.g., page 4 of 4) to align with document visualization standards.
      UNIT_PAGE = 2;
      // Time positions in milliseconds (for audio/video files).
      UNIT_TIME_MS = 3;
      // Pixel positions (for images and other 2D content).
      UNIT_PIXEL = 4;
    }

    // Unit of measurement for the position.
    Unit unit = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Position value.
    repeated uint32 coordinates = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // ===== Standard AIP fields 1-6 (ALL resources must follow this order) =====

  // Field 1: Canonical resource name.
  // Format:
  // `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`.
  string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Field 2: Immutable canonical resource ID (80-96 bits entropy, base62).
  // Example: "file-8f3a2k9E7c1"
  string id = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Field 3: Human-readable display name (filename) for UI.
  // This is typically the original filename of the uploaded file.
  string display_name = 3 [(google.api.field_behavior) = REQUIRED];

  // Field 4: URL-friendly slug (NO prefix).
  // If omitted, server generates from display_name.
  // If provided, server validates and persists it.
  // Slug is NOT part of resource identity.
  // Example: "my-research-file-pdf"
  string slug = 4 [(google.api.field_behavior) = OPTIONAL];

  // Field 5: Previous slugs for backward compatibility.
  // When display_name changes, a new slug is generated and old slugs are stored
  // here.
  repeated string aliases = 5 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Field 6: Optional description.
  string description = 6 [(google.api.field_behavior) = OPTIONAL];

  // ===== Timestamps (common to all resources) =====

  // Field 7: Creation time.
  google.protobuf.Timestamp create_time = 7 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Field 8: Last update time.
  google.protobuf.Timestamp update_time = 8 [(google.api.field_behavior) = OUTPUT_ONLY];

  // ===== Resource-specific fields start from field 9+ =====

  // File type.
  Type type = 9 [(google.api.field_behavior) = OPTIONAL];

  // File process status.
  FileProcessStatus process_status = 10 [(google.api.field_behavior) = OUTPUT_ONLY];

  // File process outcome message.
  string process_outcome = 11 [(google.api.field_behavior) = OUTPUT_ONLY];

  // File size in bytes.
  int64 size = 12 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Total number of chunks created from this file.
  int32 total_chunks = 13 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Total number of tokens in this file.
  int32 total_tokens = 14 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Array of tags associated with the file.
  repeated string tags = 15 [(google.api.field_behavior) = OPTIONAL];

  // Custom metadata provided by the user during file upload.
  optional google.protobuf.Struct external_metadata = 16 [(google.api.field_behavior) = OPTIONAL];

  // ===== Knowledge base associations =====

  // Knowledge base resource names that this file is associated with.
  // Format: `namespaces/{namespace}/knowledge-bases/{knowledge_base}`
  // A file can belong to multiple knowledge bases within the same namespace.
  // This field is populated from the file_knowledge_base junction table.
  // Follows AIP-122 for resource name references.
  repeated string knowledge_bases = 17 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.resource_reference) = {type: "api.instill.tech/KnowledgeBase"}
  ];

  // ===== Owner and creator references =====

  // Resource name of the owner namespace.
  // Example: "namespaces/usr-7k2m9p4w1n3" or "namespaces/org-3t8f5q2x6b1"
  string owner_name = 18 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Reserved: previously embedded full Owner/User objects which leaked
  // internal data (email, metadata, permissions) to cross-workspace callers.
  // Replaced by denormalized display fields (32-35).
  reserved 19, 21;
  reserved "owner", "creator";

  // Full resource name of the user who created this file.
  // Format: `users/{user}`
  string creator_name = 20 [(google.api.field_behavior) = OUTPUT_ONLY];

  // ===== Upload and content fields =====

  // Base64-encoded file content for inline upload.
  // Alternative to object field for smaller files.
  string content = 22 [(google.api.field_behavior) = INPUT_ONLY];

  // Pre-signed download URL for the file.
  string download_url = 24 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Pipeline used for converting the file to Markdown if the file is a
  // document (i.e., a file with pdf, doc[x] or ppt[x] extension).
  optional string converting_pipeline = 25 [(google.api.field_behavior) = OPTIONAL];

  // Length of the file in the specified unit type.
  Position length = 26 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Collection resource names that this file belongs to.
  // Format: `namespaces/{namespace}/collections/{collection}`
  // This field is system-managed and populated from collection membership.
  // Follows AIP-122 for resource name references.
  repeated string collections = 27 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.resource_reference) = {type: "api.instill.tech/Collection"}
  ];

  // Soft delete timestamp.
  google.protobuf.Timestamp delete_time = 28 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Object resource name reference for blob storage upload.
  // Format: `namespaces/{namespace}/objects/{object}`
  // Two upload approaches are supported:
  // 1. Direct upload: Upload file directly to MinIO via GetObjectUploadURL,
  //    then provide the object resource name here.
  //    This avoids base64 encoding overhead and is preferred for large files.
  // 2. Inline content: Provide base64-encoded file content in the 'content'
  //    field. When object is provided, the 'content' field is ignored.
  // Follows AIP-122 for resource name references.
  string object = 29 [
    (google.api.field_behavior) = OPTIONAL,
    (google.api.resource_reference) = {type: "api.instill.tech/Object"}
  ];

  // Whether the document contains a native text layer (true) or is
  // image-based / scanned (false). Determined during file processing by
  // attempting PDF text extraction. Used for visual grounding: text-based
  // documents get precise text highlighting while image-based documents
  // get bounding-box overlays.
  // Only meaningful for document file types (PDF, DOCX, PPTX, etc.).
  bool is_text_based = 30 [(google.api.field_behavior) = OUTPUT_ONLY];

  // SHA256 hash of the file content for content-based deduplication.
  // Computed at ingestion time for both inline content uploads and object
  // reference uploads.
  string content_sha256 = 31 [(google.api.field_behavior) = OUTPUT_ONLY];

  // ===== Denormalized display fields =====
  // These replace the removed embedded owner/creator objects (fields 19, 21)
  // to avoid leaking internal user data to cross-workspace callers.
  // Same pattern as Collection (collection.proto fields 23-26).

  // Human-readable display name of the owner namespace.
  // Populated server-side to avoid an extra frontend API call.
  // Example: "Instill AI" (for an org) or "John Doe" (for a user).
  string owner_display_name = 32 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Avatar URL of the owner namespace.
  // Populated server-side alongside owner_display_name.
  optional string owner_avatar = 33 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Human-readable display name of the user who created this file.
  // Populated server-side to avoid an extra frontend API call.
  string creator_display_name = 34 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Avatar URL of the user who created this file.
  // Populated server-side alongside creator_display_name.
  optional string creator_avatar = 35 [(google.api.field_behavior) = OUTPUT_ONLY];

  // ===== Visibility =====

  // Visibility defines who can discover and access the file.
  enum Visibility {
    // Unspecified, treated as WORKSPACE.
    VISIBILITY_UNSPECIFIED = 0;
    // Reserved for future: truly private (only creator + invited users).
    VISIBILITY_PRIVATE = 1;
    // Discoverable by anyone, including anonymous visitors.
    VISIBILITY_PUBLIC = 2;
    // Org members can access via all-members grant. Default for files.
    VISIBILITY_WORKSPACE = 3;
    // Anyone with the share link (/r/{token}) can access via capability token.
    VISIBILITY_LINK_SHARED = 4;
  }

  // Visibility of the file.
  Visibility visibility = 36 [(google.api.field_behavior) = OPTIONAL];

  // Derived resource URI populated on `ListFiles` / `GetFile` responses when
  // the caller requested an explicit `File.View` (SUMMARY, CONTENT,
  // STANDARD_FILE_TYPE, ORIGINAL_FILE_TYPE, CACHE, PATCH). Mirrors the
  // long-standing `GetFileResponse.derived_resource_uri` slot so
  // list-shaped responses can carry per-row URIs without an extra per-file
  // `GetFile` round trip. Empty when no view was requested. Subject to the
  // short-lived MinIO/GCS presign TTL — treat as ephemeral and do not
  // cross-cache.
  optional string derived_resource_uri = 37 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Stable, cache-friendly URL to a small (~1024px WebP) thumbnail of the
  // file, populated whenever a `CONVERTED_FILE_TYPE_THUMBNAIL` row exists
  // for this file. Resolved through the gateway's
  // `/v1alpha/blob-urls/{object_uid}` route so the URL itself is stable
  // across presign rotations and CDN-cacheable. Empty for files whose
  // thumbnail has not yet been generated (backfill workflow covers
  // historical rows; ingest covers new ones). Clients should treat this as
  // the preferred card-tile source and fall back to `derived_resource_uri`
  // / mime-type icon when absent.
  optional string thumbnail_uri = 38 [(google.api.field_behavior) = OUTPUT_ONLY];

  // The folder that this file belongs to (single parent).
  // File permissions cascade from this folder — the file inherits
  // viewer/editor/commenter/resource_owner from its parent folder.
  // Format: `namespaces/{namespace}/folders/{folder}`
  // Populated server-side from the file's parent_folder_uid DB column.
  // Files without an explicit parent folder default to the namespace's
  // root folder ("Workspace").
  optional string parent_folder = 39 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.resource_reference) = {type: "agent.instill.tech/Folder"}
  ];
}

// CreateFileRequest represents a request to create a file in a knowledge base.
// Follows AIP-133: https://google.aip.dev/133
message CreateFileRequest {
  // The parent resource name (knowledge base).
  // Format: `namespaces/{namespace}/knowledge-bases/{knowledge_base}`
  string parent = 1 [(google.api.field_behavior) = REQUIRED];
  // The file to create.
  File file = 2 [(google.api.field_behavior) = OPTIONAL];
}

// CreateFileResponse represents a response for creating a file.
message CreateFileResponse {
  // file
  File file = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// DeleteFileRequest represents a request to delete a file.
// Follows AIP-135: https://google.aip.dev/135
message DeleteFileRequest {
  // The resource name of the file to delete.
  // Format:
  // `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.instill.tech/File"}
  ];
}

// DeleteFileResponse represents a response for deleting a file.
message DeleteFileResponse {
  // The resource name of the deleted file.
  // Format:
  // `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
  string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Admin-only file operations

// DeleteFileAdminRequest represents a request to delete a file (admin only).
message DeleteFileAdminRequest {
  // The resource name of the file to delete.
  // Format:
  // `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.instill.tech/File"}
  ];
}

// DeleteFileAdminResponse represents a response for deleting a file (admin
// only).
message DeleteFileAdminResponse {
  // The resource name of the deleted file.
  // Format:
  // `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
  string name = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// ReprocessFileAdminRequest represents a request to reprocess a file (admin
// only). This bypasses ACL checks and triggers the ProcessFileWorkflow
// directly.
message ReprocessFileAdminRequest {
  // The file UID to reprocess.
  string file_uid = 1 [(google.api.field_behavior) = REQUIRED];
}

// ReprocessFileAdminResponse represents a response for reprocessing a file
// (admin only).
message ReprocessFileAdminResponse {
  // The reprocessed file.
  File file = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// IntegrityState classifies the cross-datastore consistency of a knowledge-base
// file's derived RAG state (PostgreSQL chunk rows, Milvus vectors, MinIO
// converted-file) against its declared `process_status`. Values that are NOT
// `INTEGRITY_STATE_HEALTHY` indicate drift that the caller MUST recover from
// before dispatching downstream work that depends on the file's chunks.
//
// Boundary by gRPC code (per `CheckFileChunkIntegrityAdmin` semantics):
//   - `INTEGRITY_STATE_FILE_NOT_FOUND` is reported only when the file row is
//     soft-deleted or never existed; in that case the RPC still returns OK
//     with this enum value rather than `NotFound`, so the caller can read the
//     `recommended_action` and decide whether to surface the absence to the
//     end user or skip the gate entirely.
//   - All other "drift" classes report `IntegrityState != HEALTHY` while the
//     file row itself is intact.
enum IntegrityState {
  // Default; never returned by a successful probe.
  INTEGRITY_STATE_UNSPECIFIED = 0;
  // The file's `process_status` is `COMPLETED`, the chunk row count, Milvus
  // vector count, and the file row's `total_chunks` agree, and the converted
  // markdown object exists in MinIO. Safe to dispatch.
  INTEGRITY_STATE_HEALTHY = 1;
  // The file's `process_status` is anything except `COMPLETED` (e.g. still
  // processing, failed, not started). Drift detection is not meaningful in
  // this state — the upstream `process_status` gate handles it.
  INTEGRITY_STATE_NOT_COMPLETED = 2;
  // PG row says COMPLETED but the chunk inventory in the `chunk` table is
  // empty (or non-zero but does not match the file row's `total_chunks`
  // under strict equality). Indicates the chunks were hard-deleted or never
  // persisted. Recoverable via `ReprocessFileAdmin`.
  INTEGRITY_STATE_EMPTY_PG = 3;
  // PG row says COMPLETED, chunk rows exist, but the Milvus collection for
  // the parent knowledge base is missing entirely OR the per-file vector
  // count in Milvus does not match the PG chunk count under strict equality.
  // Indicates Milvus collection was dropped, never created, or partially
  // ingested. Recoverable via `ReprocessFileAdmin`.
  INTEGRITY_STATE_MISSING_MILVUS = 4;
  // PG row says COMPLETED, chunks + vectors agree, but the converted-file
  // object is missing from MinIO. The LLM's `get-file-content` tool will
  // 404. Recoverable via `ReprocessFileAdmin`.
  INTEGRITY_STATE_MISSING_CONVERTED_FILE = 5;
  // The file row itself does not exist (or is soft-deleted). The caller
  // should treat this as a tombstone; reprocess is not the right recovery.
  INTEGRITY_STATE_FILE_NOT_FOUND = 6;
}

// RecommendedAction tells the caller what to do with the probe result. Kept
// separate from `IntegrityState` so the caller does not have to enumerate
// state values to decide on behavior, and so future drift classes can map to
// the same recovery path without breaking callers.
enum RecommendedAction {
  // Default; never returned by a successful probe.
  RECOMMENDED_ACTION_UNSPECIFIED = 0;
  // No action needed. The file is healthy; safe to dispatch downstream work.
  RECOMMENDED_ACTION_NONE = 1;
  // The caller should kick `ReprocessFileAdmin(file_uid)` to re-derive the
  // missing chunks / vectors / converted-file, and defer the dependent work
  // until the file's `process_status` returns to `COMPLETED`. Idempotent —
  // safe to send concurrently for the same file UID; `ReprocessFileAdmin`
  // already short-circuits in-flight reprocesses.
  RECOMMENDED_ACTION_REPROCESS_FILE = 2;
  // The file row is gone. The caller should NOT reprocess; instead it should
  // surface the absence to the end user (e.g. mark the dependent record as
  // referencing a deleted file) or skip the gate entirely so downstream
  // tools handle the missing-file at their own granularity.
  RECOMMENDED_ACTION_SKIP_FILE_NOT_FOUND = 3;
  // The file's `process_status` is not COMPLETED yet (still processing,
  // failed, etc.). The caller should defer and let the upstream
  // `process_status` gate retry once processing finishes.
  RECOMMENDED_ACTION_DEFER_PROCESSING = 4;
}

// CheckFileChunkIntegrityAdminRequest represents a request to probe the
// cross-datastore consistency of a knowledge-base file (admin only).
message CheckFileChunkIntegrityAdminRequest {
  // The file UID to probe.
  string file_uid = 1 [(google.api.field_behavior) = REQUIRED];
}

// CheckFileChunkIntegrityAdminResponse reports the integrity probe result.
// All count fields are populated when reachable; the absence of a count is
// reflected in `state` and is not separately signalled.
message CheckFileChunkIntegrityAdminResponse {
  // The drift classification.
  IntegrityState state = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
  // The recovery recommendation derived from `state`.
  RecommendedAction recommended_action = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
  // The file's current `process_status` from the `file` table at probe time.
  // Repeating this here lets a caller short-circuit additional lookups.
  FileProcessStatus process_status = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
  // The `file.total_chunks` advertised on the file row. May be zero when
  // `state = INTEGRITY_STATE_FILE_NOT_FOUND` or when chunk count tracking
  // was not yet populated.
  int64 total_chunks_declared = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
  // The number of non-deleted rows in the `chunk` table for this file_uid
  // at probe time. Always populated when the file row exists.
  int64 chunk_rows_in_pg = 5 [(google.api.field_behavior) = OUTPUT_ONLY];
  // The number of vectors found in the Milvus collection (`kb_<kb_uid>`)
  // matching this file_uid at probe time. -1 when the Milvus collection
  // does not exist; non-negative otherwise.
  int64 vectors_in_milvus = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
  // True iff the converted-file MinIO object for this file is present.
  bool converted_file_present = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Free-form human-readable diagnostic message for ops/log purposes. Not
  // intended for parsing by callers.
  string message = 8 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// CopyFileToKnowledgeBaseAdminRequest represents a request to copy a file to
// a different knowledge base (admin only). This performs a lightweight copy:
// copies the MinIO object, file record, and converted files (markdown/summary)
// without re-running the processing pipeline (no chunking/embedding).
// Used by agent-backend for DeepCopyCollection.
message CopyFileToKnowledgeBaseAdminRequest {
  // The resource name of the source file to copy.
  // Format:
  // `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
  string source_file = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.instill.tech/File"}
  ];
  // The resource name of the target knowledge base to copy the file into.
  // Format: `namespaces/{namespace}/knowledge-bases/{knowledge_base}`
  string target_knowledge_base = 2 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.instill.tech/KnowledgeBase"}
  ];
}

// CopyFileToKnowledgeBaseAdminResponse represents a response for copying a
// file (admin only).
message CopyFileToKnowledgeBaseAdminResponse {
  // The newly created file in the target knowledge base.
  File file = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// ListFilesRequest represents a request to list files in a knowledge base.
// Follows AIP-132: https://google.aip.dev/132
message ListFilesRequest {
  // The parent resource name (knowledge base).
  // Format: `namespaces/{namespace}/knowledge-bases/{knowledge_base}`
  string parent = 1 [(google.api.field_behavior) = REQUIRED];
  // The page size (default:10; max 100).
  optional int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL];
  // The next page token(default from first file's token).
  optional string page_token = 3 [(google.api.field_behavior) = OPTIONAL];
  // Filter can hold an [AIP-160](https://google.aip.dev/160)-compliant filter
  // expression.
  // - `id="<uuid>"` or `uid="<uuid>"` - Filter by specific file ID/UID
  // (supports multiple IDs separated by OR)
  // - `process_status="FILE_PROCESS_STATUS_COMPLETED"` - Filter by processing
  // status
  // - `q="<text>"` - Fuzzy search on file display name, ID, and description
  //
  // **Examples**:
  // - List specific files: `id="uuid1" OR id="uuid2"`
  // - List completed files: `process_status="FILE_PROCESS_STATUS_COMPLETED"`
  // - Search files: `q="aws"`
  optional string filter = 4 [(google.api.field_behavior) = OPTIONAL];

  // View allows clients to specify the desired file view in the response.
  // When set, each returned `File` carries a populated
  // `derived_resource_uri` (see `File.derived_resource_uri`), so the list
  // call subsumes the per-file `GetFile(view=…)` fan-out that the Files
  // page previously performed. Server-side the resolver fans out presign
  // work across a bounded worker pool; unset leaves `derived_resource_uri`
  // empty for every row. `thumbnail_uri` is always populated when a
  // thumbnail exists and is unaffected by this flag.
  optional File.View view = 5 [(google.api.field_behavior) = OPTIONAL];
}

// ListFilesResponse represents a response for listing files.
message ListFilesResponse {
  // The list of files.
  repeated File files = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
  // The total number of files.
  int32 total_size = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
  // The requested page size.
  int32 page_size = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
  // next page token
  string next_page_token = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// GetFileRequest represents a request to get a file.
// Follows AIP-131: https://google.aip.dev/131
message GetFileRequest {
  // The resource name of the file to retrieve.
  // Format:
  // `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.instill.tech/File"}
  ];
  // View allows clients to specify the desired file view in the response.
  optional File.View view = 2 [(google.api.field_behavior) = OPTIONAL];
  // Storage provider specifies which storage backend to use for the file
  // resource. This field is only applicable for views that return file content:
  // VIEW_SUMMARY, VIEW_CONTENT, VIEW_STANDARD_FILE_TYPE,
  // VIEW_ORIGINAL_FILE_TYPE.
  // - STORAGE_PROVIDER_UNSPECIFIED or STORAGE_PROVIDER_MINIO: Returns MinIO
  // pre-signed URL (default)
  // - STORAGE_PROVIDER_GCS: Uploads file to GCS if not present (with cache
  // check), returns GCS signed URL GCS requires proper configuration in system
  // settings.
  optional File.StorageProvider storage_provider = 3 [(google.api.field_behavior) = OPTIONAL];
}

// GetFileResponse represents a response for getting a file.
message GetFileResponse {
  // The file metadata (always included).
  File file = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Derived resource URI based on view and storage provider:
  // - VIEW_SUMMARY/CONTENT/STANDARD_FILE_TYPE/ORIGINAL_FILE_TYPE:
  //   * STORAGE_PROVIDER_MINIO (default): MinIO pre-signed URL
  //   * STORAGE_PROVIDER_GCS: GCS signed URL (file uploaded to GCS if needed)
  // - VIEW_CACHE: Gemini/VertexAI cache resource name (format:
  // cacheContent/<cacheId>) Only populated for views that return file content.
  optional string derived_resource_uri = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// UpdateFileRequest represents a request to update a file.
// Follows AIP-134: https://google.aip.dev/134
message UpdateFileRequest {
  // The file resource to update. The file's `name` field identifies the
  // resource. Format:
  // `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
  File file = 1 [(google.api.field_behavior) = REQUIRED];
  // The update mask specifies the subset of fields that should be modified.
  google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = REQUIRED];
}

// UpdateFileResponse represents a response for updating a file.
message UpdateFileResponse {
  // Updated file.
  File file = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// ReprocessFileRequest represents a request to reprocess a file.
message ReprocessFileRequest {
  // The resource name of the file to reprocess.
  // Format:
  // `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {type: "api.instill.tech/File"}
  ];
}

// ReprocessFileResponse represents a response for reprocessing a file.
message ReprocessFileResponse {
  // The file being reprocessed.
  File file = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
  // Status message.
  string message = 2 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// UpdateFileAdminRequest represents a request to update a file with
// system-reserved tags (admin only). Used by internal services like
// agent-backend to set tags with reserved prefixes (e.g.,
// "agent:collection:{id}" where {id} is hash-based like col-xxx).
// Follows AIP-134: https://google.aip.dev/134
message UpdateFileAdminRequest {
  // The file resource to update. The file's `name` field identifies the
  // resource. Format:
  // `namespaces/{namespace}/knowledge-bases/{knowledge_base}/files/{file}`
  File file = 1 [(google.api.field_behavior) = REQUIRED];
  // The update mask specifies the subset of fields that should be modified.
  google.protobuf.FieldMask update_mask = 2 [(google.api.field_behavior) = REQUIRED];
}

// UpdateFileAdminResponse represents a response for updating a file.
message UpdateFileAdminResponse {
  // Updated file.
  File file = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// EntityHopAdminRequest represents a request to find files linked through
// shared KB entities (admin only). Given seed file IDs, returns other file IDs
// that share at least one entity in the kb_entity_file graph.
message EntityHopAdminRequest {
  // Seed file IDs (hash-based, e.g. "file-xxx") to hop from.
  repeated string file_ids = 1 [(google.api.field_behavior) = REQUIRED];
}

// EntityHopAdminResponse represents the result of an entity hop query.
message EntityHopAdminResponse {
  // File IDs (hash-based) that share entities with the seed files,
  // excluding the seed files themselves.
  repeated string file_ids = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}