Source at 4d73c9795adca3e49eea74d1d2cbbbbdcbea0b6c
SHA-256: 570e30612017e0a80be44fcae0ad5aaf44968588244916efc93516751dc58f81
-module(tmux_snapshot). -moduledoc """ Read an immutable captured graph without performing tmux I/O. Server-wide lists use numeric ID order. Window links retain every membership, including multiple indexes for the same window in one session. Session windows are unique in first-link order; panes within a window use pane index order. `related/3` accepts a row from this snapshot and returns a tagged result. A row from another observation cannot silently select a relationship in this one. `metadata/1` records source calls, the capture interval, endpoint generation and the observed server incarnation. Captures span commands and are not atomic. Values remain readable after their endpoint closes; actions still validate the row's registered origin. Coverage distinguishes unloaded data from an empty collection and unavailable fields from known absence. See the [graph guide](graph.md) for physical windows and session memberships. """. -export([sessions/1, windows/1, window_links/1, panes/1, rows/2, get/3, related/3, metadata/1, coverage/1, require/2, build/2]). -export_type([t/0, requirement/0, metadata/0, source_call/0, entity_coverage/0, coverage/0, query_metadata/0]). -doc """ An immutable captured graph with identity, indexes, coverage and source intervals. """. -opaque t() :: #{rows := map(), indexes := map(), edges := map(), metadata := metadata(), coverage := coverage()}. -doc """ A collection, field or complete relationship needed for faithful local evaluation. """. -type requirement() :: {collection, tmux_schema:entity()} | {field | relation, tmux_schema:entity(), atom()}. -doc """ One completed capture command and its stdout byte count. started and finished are local monotonic microseconds, not wall-clock timestamps. The interval includes identity preflight and command completion; it is not an atomic read. """. -type source_call() :: #{command := binary(), args := [binary()], started := integer(), finished := integer(), stdout_bytes := non_neg_integer()}. -doc """ Collection completeness, field availability and relationship completeness. A loaded field can hold a known value or known absence; inspect the row to distinguish them. not_loaded never means empty, and unavailable never means known absence. Completeness is relative to the captured source collection. """. -type entity_coverage() :: #{collection := complete | not_loaded, fields := #{atom() => loaded | not_loaded | unavailable}, relations := #{atom() => complete | not_loaded}}. -doc "Per-entity coverage. Use `require/2` to check requirements before evaluation.". -type coverage() :: #{tmux_schema:entity() => entity_coverage()}. -doc """ Source-query capture diagnostics. candidate_count is the deduplicated candidate identity count before local residuals and limits. pushed_down records a nontrivial native condition in the plan, not proof that its command ran: empty collections can skip it. source_calls records actual capture commands. The flag does not mean the full predicate was translated. attempt starts at one and increases only for an explicitly requested retry. """. -type query_metadata() :: #{candidate_count := non_neg_integer(), pushed_down := boolean(), attempt := 1 | 2, consistency := observed}. -doc """ Capture identity and provenance. id identifies this snapshot, origin its registered endpoint and generation the endpoint lifetime. model_version names the row representation. graph describes relationship coverage, not atomicity. Live captures include endpoint, observed server_instance, tmux_version, monotonic capture bounds in time_unit, source_calls, observed stdout bytes and capabilities. Those fields can be absent in internally constructed partial captures. Query captures also include `t:query_metadata/0`. Opaque references and process identities are local values, not portable wire identifiers. hydration records the requested `t:tmux_server:hydration/0` strategy; source_calls shows which commands actually ran, including any schema-driven fallback. """. -type metadata() :: #{id := reference(), origin := reference(), model_version := 2, graph := complete | partial, generation => reference(), endpoint => #{socket_path := binary()}, server_instance => tmux_identity:t(), tmux_version => tmux_version:t(), capture_started => integer(), capture_finished => integer(), time_unit => microsecond, source_calls => [source_call()], observed_bytes => non_neg_integer(), consistency => observed, hydration => tmux_server:hydration(), capabilities => #{field_schema := 1, identity := observed, capture := observed}, query => query_metadata(), atom() => term()}. -doc """ Return captured sessions in numeric ID order. Performs no I/O and raises incomplete_snapshot when that collection was not captured. """. -spec sessions(t()) -> [tmux_model:session()]. sessions(Snapshot) -> rows(session, Snapshot). -doc """ Return unique captured physical windows in numeric ID order. Performs no I/O. Use `window_links/1` for session-relative membership and indexes. """. -spec windows(t()) -> [tmux_model:window()]. windows(Snapshot) -> rows(window, Snapshot). -doc """ Return every captured membership, ordered by numeric session ID, index and window ID. Multiple links to the same physical window are preserved. Performs no I/O; link identity belongs to this snapshot. """. -spec window_links(t()) -> [tmux_model:window_link()]. window_links(Snapshot) -> rows(window_link, Snapshot). -doc """ Return unique captured physical panes in numeric ID order without I/O. `related/3` orders panes within a window by pane index. """. -spec panes(t()) -> [tmux_model:pane()]. panes(Snapshot) -> rows(pane, Snapshot). -doc """ Return a captured collection by schema entity. Performs no I/O. An unloaded collection raises incomplete_snapshot rather than appearing empty. """. -spec rows(tmux_schema:entity(), t()) -> [tmux_model:row()]. rows(Entity, #{rows := Rows} = Snapshot) -> case require([{collection, Entity}], Snapshot) of ok -> maps:get(Entity, Rows); {error, Detail} -> erlang:error({incomplete_snapshot, Detail}, none, [{error_info, #{module => tmux_error}}]) end. -doc """ Look up a row in this capture by ID, or a session/index/window tuple for a window link. Returns none for a known missing identity and a tagged coverage error for an unloaded collection. Performs no I/O. """. -spec get(tmux_schema:entity(), term(), t()) -> {ok, tmux_model:row()} | none | {error, map()}. get(Entity, Key, #{indexes := Indexes} = Snapshot) -> maybe ok ?= require([{collection, Entity}], Snapshot), case maps:find(Key, maps:get(Entity, Indexes)) of {ok, Row} -> {ok, Row}; error -> none end end. -doc """ Traverse a complete captured relationship without I/O. To-many relations return lists; to-one relations return a row or known absence. The input row must belong to this snapshot. Unloaded relations and mismatched rows return tagged errors. """. -spec related(atom(), tmux_model:row(), t()) -> {ok, [tmux_model:row()] | tmux_model:row() | none} | {error, map()}. related(Relation, Row, #{indexes := Indexes, edges := Edges} = Snapshot) -> maybe {ok, _} ?= tmux_model:validate(Row), Entity = tmux_model:entity(Row), ok ?= require([{relation, Entity, Relation}], Snapshot), ok ?= case get(Entity, key(Row), Snapshot) of {ok, Row} -> ok; _ -> {error, #{code => snapshot_row_mismatch}} end, {ok, Relations} = tmux_schema:relations(Entity), #{kind := Kind, target := Target} = maps:get(Relation, Relations), Keys = maps:get({Entity, key(Row), Relation}, Edges), Values = [maps:get(K, maps:get(Target, Indexes)) || K <- Keys], {ok, case {Kind, Values} of {many, _} -> Values; {one, []} -> none; {one, [Value]} -> Value end} end. -doc """ Return capture identity, server generation, source calls, capabilities and read interval metadata. Does not refresh the graph or imply atomic capture. """. -spec metadata(t()) -> metadata(). metadata(#{metadata := Metadata}) -> Metadata. -doc """ Return per-collection, field and relationship coverage. Loaded values, known absence, not_loaded and unavailable capabilities have distinct meanings. Performs no I/O. """. -spec coverage(t()) -> coverage(). coverage(#{coverage := Coverage}) -> Coverage. -doc """ Check every declared collection/field/relationship requirement before local evaluation. Returns an incomplete_snapshot error with missing requirements when the capture cannot answer faithfully. Performs no I/O, even on empty data. """. -spec require([requirement()], t()) -> ok | {error, map()}. require(Requirements, #{coverage := Coverage}) when is_list(Requirements) -> requirements(Requirements, Coverage, []); require(_, _) -> {error, #{code => invalid_requirements}}. %% Internal construction boundary for validated source observations. Partial %% input never establishes relationship completeness, even when it is empty. -doc false. -spec build(map(), map()) -> {ok, t()} | {error, map()}. build(Input, #{origin := Origin, id := Id, graph := Mode} = Metadata) when is_map(Input), is_reference(Origin), is_reference(Id), (Mode =:= complete orelse Mode =:= partial) -> Entities = tmux_schema_data:entities(), maybe ok ?= case maps:keys(maps:without(Entities, Input)) of [] -> ok; _ -> {error, #{code => unknown_entity}} end, {ok, Indexes} ?= index_entities(Entities, Input, Origin, Id, #{}), Rows = maps:map(fun(_, Index) -> sort_rows(maps:values(Index)) end, Indexes), ok ?= case Mode of complete -> validate_graph(Input, Rows, Indexes); partial -> ok end, Edges = case Mode of complete -> edges(Rows); partial -> #{} end, Coverage = maps:from_list([{Entity, entity_coverage(Entity, Input, Rows, Mode)} || Entity <- Entities]), {ok, #{rows => Rows, indexes => Indexes, edges => Edges, coverage => Coverage, metadata => Metadata#{model_version => 2}}} end; build(_, _) -> {error, #{code => invalid_snapshot_metadata}}. index_entities([], _, _, _, Acc) -> {ok, Acc}; index_entities([Entity | Rest], Input, Origin, Id, Acc) -> maybe {ok, Index} ?= index_rows(maps:get(Entity, Input, []), Entity, Origin, Id, #{}), index_entities(Rest, Input, Origin, Id, Acc#{Entity => Index}) end. index_rows([], _, _, _, Acc) -> {ok, Acc}; index_rows([Row | Rest], Entity, Origin, Id, Acc) -> maybe {ok, _} ?= tmux_model:validate(Row), ok ?= case {tmux_model:entity(Row), tmux_model:origin(Row)} of {Entity, O} when O =:= none; O =:= Origin -> ok; _ -> inconsistent(#{reason => wrong_row_context, entity => Entity}) end, Bound = tmux_model:bind(Row, Origin, Id), Key = key(Bound), ok ?= case maps:find(Key, Acc) of error -> ok; {ok, Bound} -> ok; {ok, Previous} -> inconsistent(#{reason => conflicting_observations, entity => Entity, identity => Key, fields => [F || {F, V} <- maps:to_list(tmux_model:to_map(Bound)), V =/= tmux_model:get(F, Previous)]}) end, index_rows(Rest, Entity, Origin, Id, Acc#{Key => Bound}) end; index_rows(_, Entity, _, _, _) -> {error, #{code => invalid_rows, entity => Entity}}. key(Row) -> case tmux_model:entity(Row) of window_link -> {tmux_model:get(session_id, Row), tmux_model:get(index, Row), tmux_model:get(window_id, Row)}; _ -> tmux_model:get(id, Row) end. sort_rows(Rows) -> lists:sort(fun(A, B) -> order(A) =< order(B) end, Rows). order(Row) -> case key(Row) of {Session, Index, Window} -> {number(Session), Index, number(Window)}; Id -> number(Id) end. number(<<_, Digits/binary>>) -> binary_to_integer(Digits). validate_graph(Input, Rows, Indexes) -> maybe ok ?= case lists:all(fun(E) -> maps:is_key(E, Input) end, tmux_schema_data:entities()) of true -> ok; false -> inconsistent(#{reason => missing_collection}) end, Links = maps:get(window_link, Rows), Panes = maps:get(pane, Rows), ok ?= references(Links, [{session_id, session}, {window_id, window}], Indexes), ok ?= references(Panes, [{window_id, window}], Indexes), ok ?= unique_slots(Links, [session_id, index]), ok ?= unique_slots(Panes, [window_id, index]), counts(maps:get(window, Rows), group(window_id, Panes)) end. references([], _, _) -> ok; references([Row | Rest], Fields, Indexes) -> Missing = [F || {F, E} <- Fields, not maps:is_key(tmux_model:get(F, Row), maps:get(E, Indexes))], case Missing of [] -> references(Rest, Fields, Indexes); _ -> inconsistent(#{reason => missing_parent, entity => tmux_model:entity(Row), identity => key(Row), fields => Missing}) end. unique_slots(Rows, Fields) -> Slots = [[tmux_model:get(F, R) || F <- Fields] || R <- Rows], case length(Slots) =:= length(lists:usort(Slots)) of true -> ok; false -> inconsistent(#{reason => conflicting_positions, fields => Fields}) end. counts([], _) -> ok; counts([Window | Rest], Panes) -> Count = length(maps:get(key(Window), Panes, [])), case tmux_model:get(pane_count, Window) of Count -> counts(Rest, Panes); not_loaded -> counts(Rest, Panes); unavailable -> counts(Rest, Panes); _ -> inconsistent(#{reason => pane_count, identity => key(Window)}) end. group(Field, Rows) -> Reversed = lists:foldl(fun(Row, Acc) -> Key = tmux_model:get(Field, Row), Acc#{Key => [Row | maps:get(Key, Acc, [])]} end, #{}, Rows), maps:map(fun(_, Values) -> lists:reverse(Values) end, Reversed). edges(Rows) -> Links = maps:get(window_link, Rows), BySession = group(session_id, Links), ByWindow = group(window_id, Links), Panes = group(window_id, maps:get(pane, Rows)), SessionEdges = lists:append([begin Memberships = maps:get(key(S), BySession, []), [{{session, key(S), window_links}, [key(L) || L <- Memberships]}, {{session, key(S), windows}, unique([tmux_model:get(window_id, L) || L <- Memberships])}] end || S <- maps:get(session, Rows)]), WindowEdges = lists:append([begin Children = lists:sort(fun(A, B) -> {tmux_model:get(index, A), order(A)} =< {tmux_model:get(index, B), order(B)} end, maps:get(key(W), Panes, [])), [{{window, key(W), panes}, [key(P) || P <- Children]}, {{window, key(W), window_links}, [key(L) || L <- maps:get(key(W), ByWindow, [])]}] end || W <- maps:get(window, Rows)]), LinkEdges = lists:append([[{{window_link, key(L), session}, [tmux_model:get(session_id, L)]}, {{window_link, key(L), window}, [tmux_model:get(window_id, L)]}] || L <- Links]), PaneEdges = [{{pane, key(P), window}, [tmux_model:get(window_id, P)]} || P <- maps:get(pane, Rows)], maps:from_list(SessionEdges ++ WindowEdges ++ LinkEdges ++ PaneEdges). unique(Values) -> {_, Reversed} = lists:foldl(fun(Value, {Seen, Acc}) -> case is_map_key(Value, Seen) of true -> {Seen, Acc}; false -> {Seen#{Value => true}, [Value | Acc]} end end, {#{}, []}, Values), lists:reverse(Reversed). entity_coverage(Entity, Input, Rows, Mode) -> {ok, Fields} = tmux_schema:fields(Entity), {ok, Relations} = tmux_schema:relations(Entity), Present = maps:is_key(Entity, Input), FieldCoverage = maps:map(fun(Field, _) -> Values = [tmux_model:get(Field, Row) || Row <- maps:get(Entity, Rows)], Observed = Present andalso (Mode =:= complete orelse Values =/= []), case {Observed, lists:member(unavailable, Values), lists:member(not_loaded, Values)} of {_, true, _} -> unavailable; {false, _, _} -> not_loaded; {_, _, true} -> not_loaded; _ -> loaded end end, Fields), #{collection => case Present of true -> complete; false -> not_loaded end, fields => FieldCoverage, relations => maps:map(fun(_, _) -> case Mode of complete -> complete; partial -> not_loaded end end, Relations)}. requirements([], _, []) -> ok; requirements([], _, Missing) -> {error, #{code => incomplete_snapshot, requirements => lists:reverse(Missing)}}; requirements([Requirement | Rest], Coverage, Missing) -> case requirement(Requirement, Coverage) of {ok, loaded} -> requirements(Rest, Coverage, Missing); {ok, complete} -> requirements(Rest, Coverage, Missing); {ok, State} -> requirements(Rest, Coverage, [#{requirement => Requirement, state => State} | Missing]); error -> {error, #{code => invalid_requirement, requirement => Requirement}} end. requirement({collection, Entity}, Coverage) -> case maps:find(Entity, Coverage) of {ok, Item} -> maps:find(collection, Item); error -> error end; requirement({Kind, Entity, Name}, Coverage) when Kind =:= field; Kind =:= relation -> case maps:find(Entity, Coverage) of {ok, Item} -> Key = case Kind of field -> fields; relation -> relations end, maps:find(Name, maps:get(Key, Item)); error -> error end; requirement(_, _) -> error. inconsistent(Details) -> {error, Details#{code => inconsistent_capture}}.