// file: kb_lib/src/upstream_registry_types.rs

//! Shared DTOs and static-entry types for the upstream Git registry.
//!
//! The registry is a discovery index. It must not be interpreted as local
//! business proof that a DEX, instruction, event, trade, metric or candle has
//! been validated against the current SQLite corpus.

/// Registry entry kind for an instruction discriminator.
pub const ENTRY_KIND_INSTRUCTION: &str = "instruction";
/// Registry entry kind for an emitted event discriminator.
pub const ENTRY_KIND_EVENT: &str = "event";
/// Registry entry kind for an account discriminator or account layout.
pub const ENTRY_KIND_ACCOUNT: &str = "account";
/// Registry entry kind for a program-level seed row.
pub const ENTRY_KIND_PROGRAM: &str = "program";

/// Generic protocol name used for upstream registry matches that are not business-materialized.
pub const UPSTREAM_REGISTRY_PROTOCOL_NAME: &str = "upstream_git";
/// Generic event kind used for instruction-level upstream registry matches.
pub const UPSTREAM_REGISTRY_INSTRUCTION_MATCH_EVENT_KIND: &str = "upstream_git.instruction_match";

/// Generic upstream Git status for an entry that has not been observed locally.
pub const PROOF_STATUS_UPSTREAM_GIT_UNVERIFIED: &str = "upstream_git_unverified";
/// Generic upstream Git status for an entry wired into a decoder but not observed locally.
pub const PROOF_STATUS_UPSTREAM_GIT_MAPPED_UNVERIFIED: &str = "upstream_git_mapped_unverified";
/// Generic upstream Git status for an entry observed in the local corpus.
pub const PROOF_STATUS_UPSTREAM_GIT_LOCAL_CORPUS_OBSERVED: &str =
    "upstream_git_local_corpus_observed";
/// Generic upstream Git status for an entry materialized in local business tables.
pub const PROOF_STATUS_UPSTREAM_GIT_LOCAL_CORPUS_MATERIALIZED: &str =
    "upstream_git_local_corpus_materialized";
/// Generic upstream Git status for a known layout that is not yet locally validated.
pub const PROOF_STATUS_UPSTREAM_GIT_LAYOUT_UNVERIFIED: &str = "upstream_git_layout_unverified";

/// Static registry entry used by generated or hand-curated bootstrap data.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct UpstreamRegistryEntry {
    /// Repository name or bootstrap locator that produced the entry.
    pub source_repo: std::option::Option<&'static str>,
    /// Repository-relative path or bootstrap path that produced the entry.
    pub source_path: std::option::Option<&'static str>,
    /// Stable decoder code used by the registry.
    pub decoder_code: &'static str,
    /// Optional Solana program id when already known by the source entry.
    pub program_id: std::option::Option<&'static str>,
    /// Program family used to group related programs.
    pub program_family: &'static str,
    /// Surface kind such as AMM, CLMM, launch, aggregator or core Solana.
    pub surface_kind: &'static str,
    /// Entry kind: instruction, event, account or program.
    pub entry_kind: &'static str,
    /// Source-level entry name.
    pub entry_name: &'static str,
    /// Optional discriminator bytes encoded as lowercase hexadecimal.
    pub discriminator_hex: std::option::Option<&'static str>,
    /// Optional discriminator byte length.
    pub discriminator_len: std::option::Option<u16>,
    /// Current proof status.
    pub proof_status: &'static str,
    /// Notes that preserve uncertainty and validation requirements.
    pub notes: &'static str,
}

impl UpstreamRegistryEntry {
    /// Converts a static entry into an owned DTO for application/UI boundaries.
    pub fn to_dto(&self) -> crate::UpstreamRegistryEntryDto {
        return crate::UpstreamRegistryEntryDto {
            source_repo: self.source_repo.map(std::string::ToString::to_string),
            source_path: self.source_path.map(std::string::ToString::to_string),
            decoder_code: self.decoder_code.to_string(),
            program_id: self.program_id.map(std::string::ToString::to_string),
            program_family: self.program_family.to_string(),
            surface_kind: self.surface_kind.to_string(),
            entry_kind: self.entry_kind.to_string(),
            entry_name: self.entry_name.to_string(),
            discriminator_hex: self.discriminator_hex.map(std::string::ToString::to_string),
            discriminator_len: self.discriminator_len,
            proof_status: self.proof_status.to_string(),
            notes: self.notes.to_string(),
        };
    }
}

/// Owned registry entry DTO exposed at crate and UI boundaries.
#[derive(Clone, Debug, Eq, PartialEq, serde::Serialize)]
#[serde(rename_all = "camelCase")]
pub struct UpstreamRegistryEntryDto {
    /// Repository name or bootstrap locator that produced the entry.
    pub source_repo: std::option::Option<std::string::String>,
    /// Repository-relative path or bootstrap path that produced the entry.
    pub source_path: std::option::Option<std::string::String>,
    /// Stable decoder code used by the registry.
    pub decoder_code: std::string::String,
    /// Optional Solana program id when already known by the source entry.
    pub program_id: std::option::Option<std::string::String>,
    /// Program family used to group related programs.
    pub program_family: std::string::String,
    /// Surface kind such as AMM, CLMM, launch, aggregator or core Solana.
    pub surface_kind: std::string::String,
    /// Entry kind: instruction, event, account or program.
    pub entry_kind: std::string::String,
    /// Source-level entry name.
    pub entry_name: std::string::String,
    /// Optional discriminator bytes encoded as lowercase hexadecimal.
    pub discriminator_hex: std::option::Option<std::string::String>,
    /// Optional discriminator byte length.
    pub discriminator_len: std::option::Option<u16>,
    /// Current proof status.
    pub proof_status: std::string::String,
    /// Notes that preserve uncertainty and validation requirements.
    pub notes: std::string::String,
}

/// Search/filter request for registry entries.
#[derive(Clone, Debug, Default, Eq, PartialEq, serde::Serialize, serde::Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct UpstreamRegistrySearchRequestDto {
    /// Optional decoder-code filter.
    pub decoder_code: std::option::Option<std::string::String>,
    /// Optional program-id filter.
    pub program_id: std::option::Option<std::string::String>,
    /// Optional program-family filter.
    pub program_family: std::option::Option<std::string::String>,
    /// Optional surface-kind filter.
    pub surface_kind: std::option::Option<std::string::String>,
    /// Optional entry-kind filter.
    pub entry_kind: std::option::Option<std::string::String>,
    /// Optional proof-status filter.
    pub proof_status: std::option::Option<std::string::String>,
    /// Optional maximum number of returned entries.
    pub limit: std::option::Option<usize>,
}

/// Summary of the current registry snapshot.
#[derive(Clone, Debug, Eq, PartialEq, serde::Serialize)]
#[serde(rename_all = "camelCase")]
pub struct UpstreamRegistrySummaryDto {
    /// Total static registry entry count before filtering.
    pub total_entry_count: usize,
    /// Returned entry count after filtering.
    pub returned_entry_count: usize,
    /// Number of entries that have a program id.
    pub entries_with_program_id_count: usize,
    /// Number of entries that have a discriminator.
    pub entries_with_discriminator_count: usize,
    /// Number of program-level seed entries.
    pub program_entry_count: usize,
    /// Number of instruction entries.
    pub instruction_entry_count: usize,
    /// Number of event entries.
    pub event_entry_count: usize,
    /// Number of account entries.
    pub account_entry_count: usize,
    /// Number of entries still unverified from upstream Git or seed data.
    pub upstream_git_unverified_count: usize,
    /// Number of entries mapped into decoders but not locally observed.
    pub upstream_git_mapped_unverified_count: usize,
    /// Number of entries observed in the local corpus.
    pub upstream_git_local_corpus_observed_count: usize,
    /// Number of entries materialized in local business tables.
    pub upstream_git_local_corpus_materialized_count: usize,
    /// Number of layout entries still unverified locally.
    pub upstream_git_layout_unverified_count: usize,
}

/// Search result returned by the upstream registry service.
#[derive(Clone, Debug, Eq, PartialEq, serde::Serialize)]
#[serde(rename_all = "camelCase")]
pub struct UpstreamRegistrySearchResultDto {
    /// Normalized request used for the search.
    pub request: crate::UpstreamRegistrySearchRequestDto,
    /// Registry summary.
    pub summary: crate::UpstreamRegistrySummaryDto,
    /// Matching entries.
    pub entries: std::vec::Vec<crate::UpstreamRegistryEntryDto>,
}
