yatm/entity/file.proto

syntax = "proto3";
package yatm.v1;
option go_package = "github.com/samuelncui/yatm/entity;entity";

enum FileKind {
    FILE_KIND_UNSPECIFIED = 0;
    FILE_KIND_REGULAR = 1;
    FILE_KIND_DIRECTORY = 2;
}

enum FileScope {
    FILE_SCOPE_UNSPECIFIED = 0;
    FILE_SCOPE_DEFAULT = 1;
    FILE_SCOPE_ALL = 2;
    FILE_SCOPE_SAVED = 3;
}

message LocationSelection {
    int64 location_id = 1;
    string path = 2;
}

// Facts identify an observed filesystem object, not immutable content.
message LocationFileFacts {
    int64 size_bytes = 1;
    uint32 mode = 2;
    int64 mtime_ns = 3;
}

message LocationEntryRef {
    int64 location_id = 1;
    string path = 2;
    LocationFileFacts facts = 4;
}

// Selections retain the browser source and scope until bounded Job indexing freezes leaves.
message FileSelection {
    oneof target {
        LibrarySelection library = 1;
        LocationSelection location = 2;
    }
    FileScope scope = 3;
}

message LibrarySelection {
    int64 file_id = 1;
}

message File {
    int64 id = 1;
    int64 parent_id = 2;
    string name = 3;

    int64 mode = 17;
    int64 mtime_ns = 18;
    int64 size_bytes = 19;
    bytes sha256 = 20;
    repeated string tags = 21;
    string note = 22;
    FileKind kind = 24;
    int64 created_at_ns = 25;
    int64 updated_at_ns = 26;
    // Catalog coverage and explicitly timed original observations, never a health guarantee.
    FileContentSummary content_summary = 27;
}

enum OriginalAvailability {
    ORIGINAL_AVAILABILITY_UNSPECIFIED = 0;
    ORIGINAL_AVAILABILITY_UNCHECKED = 1;
    ORIGINAL_AVAILABILITY_PRESENT = 2;
    ORIGINAL_AVAILABILITY_MISSING = 3;
    ORIGINAL_AVAILABILITY_UNLINKED = 4;
    ORIGINAL_AVAILABILITY_UNAVAILABLE = 5;
}

message FileContentSummary {
    bool has_original = 1;
    bool has_versions = 2;
    bool signature_known = 3;
    int64 archived_copy_count = 4;
    int64 healthy_copy_count = 5;
    int64 unchecked_copy_count = 6;
    int64 unhealthy_copy_count = 7;
    OriginalAvailability original_availability = 8;
    int64 observed_at_ns = 9;
    // Signature-linked history counts deduplicate physical Positions across versions.
    int64 version_copy_count = 10;
    int64 restorable_version_copy_count = 11;
    int64 unhealthy_version_copy_count = 12;
    int64 latest_version_id = 13;
    int64 latest_version_restorable_copy_count = 14;
    // Current content counts require a valid binding and matching live object facts.
  bool current_observation_valid = 15;
  int64 restorable_current_copy_count = 16;
}

// An immutable archived content state owned by one independently organized File.
message FileVersion {
    int64 id = 1;
    int64 file_id = 2;
    bytes signature = 3;
    bytes sha256 = 4;
    int64 size_bytes = 5;
    uint32 mode = 6;
    int64 mtime_ns = 7;
    optional int64 first_archived_at_ns = 8;
    optional int64 last_archived_at_ns = 9;
}