%%%-------------------------------------------------------------------
%%% HyperKitty Chromium :: shared entity schemas (data_model).
%%%
%%% These records are the canonical in-memory shape of every entity
%%% named in the specification's <data_model>. Each has a matching
%%% `to_map/1' clause in hk_schema.erl for JSON transport. Records
%%% (not maps) are used for these because entity shape is meant to
%%% be closed and compiler-checked at the points that construct
%%% them (agent runtime, browser controller, search harness); the
%%% *wire* representation is a map/JSON, produced only at the
%%% boundary, in hk_schema.
%%% -------------------------------------------------------------------

%% ---- Agent ---------------------------------------------------------
%% Mirrors HK-AGENT's <agent_state> enumeration exactly.
-record(agent, {
    agent_id            :: binary(),
    objective            :: #{} | undefined,      % #agent_objective{}
    state                :: created | ready | planning | executing
                           | waiting | completed | failed | terminated,
    capabilities         :: [atom()],              % explicitly granted tool names
    action_count = 0     :: non_neg_integer(),
    started_at_ms        :: integer(),
    updated_at_ms        :: integer(),
    limits               :: map(),                 % see hk_agent_fsm limits map
    result                :: term() | undefined,
    failure_reason        :: term() | undefined
}).

-record(agent_objective, {
    objective_id  :: binary(),
    agent_id      :: binary(),
    description   :: binary(),        % what the agent was asked to do
    success_criteria :: binary() | undefined,
    created_at_ms :: integer()
}).

%% ---- Browser --------------------------------------------------------
-record(browser_session, {
    session_id     :: binary(),
    owner_agent_id :: binary() | undefined,   % undefined = system/manual session
    profile        :: binary(),               % profile name, isolates cookies/storage
    pid            :: pid() | undefined,
    status         :: starting | ready | busy | closing | closed | crashed,
    tabs           :: [binary()],              % tab_ids
    created_at_ms  :: integer(),
    updated_at_ms  :: integer()
}).

-record(browser_tab, {
    tab_id        :: binary(),
    session_id    :: binary(),
    url           :: binary() | undefined,
    title         :: binary() | undefined,
    status        :: opening | loading | idle | closed,
    created_at_ms :: integer(),
    updated_at_ms :: integer()
}).

%% ---- Search -----------------------------------------------------------
-record(search_job, {
    job_id         :: binary(),
    owner_agent_id :: binary() | undefined,
    query          :: binary(),
    stage          :: user_query | query_normalization | search_planner
                     | search_provider | result_normalization | url_deduplication
                     | content_retrieval | content_extraction | source_ranking
                     | result_synthesis | frontend_visibility | done | failed,
    max_iterations :: pos_integer(),
    iteration      :: non_neg_integer(),
    results        :: [binary()],   % result_ids
    created_at_ms  :: integer(),
    updated_at_ms  :: integer()
}).

-record(search_result, {
    result_id     :: binary(),
    job_id        :: binary(),
    url           :: binary(),
    normalized_url:: binary(),
    title         :: binary() | undefined,
    snippet       :: binary() | undefined,
    rank          :: number() | undefined,
    source_document_id :: binary() | undefined,
    created_at_ms :: integer()
}).

-record(source_document, {
    document_id    :: binary(),
    url            :: binary(),
    fetched_at_ms  :: integer(),
    content_type   :: binary() | undefined,
    extracted_text :: binary() | undefined,
    citation_map   :: map()   % passage/anchor -> location within extracted_text
}).

%% ---- Messaging --------------------------------------------------------
-record(message, {
    message_id      :: binary(),
    sender          :: binary(),
    recipient       :: binary(),
    timestamp       :: integer(),
    conversation_id :: binary(),
    message_type    :: user_to_agent | agent_to_user | agent_to_agent | system,
    payload         :: map(),
    status          :: queued | delivered | read | failed
}).

%% ---- Operation ----------------------------------------------------------
%% Every mutating API call returns an #operation{}; see api spec
%% ("Every mutating operation should return an operation identifier").
-record(operation, {
    operation_id  :: binary(),
    request_id    :: binary(),
    kind          :: atom(),      % e.g. agent_create, browser_navigate, search_start
    status        :: accepted | in_progress | succeeded | failed,
    subject       :: {atom(), binary()} | undefined,
    error         :: map() | undefined,
    created_at_ms :: integer(),
    updated_at_ms :: integer()
}).