apps/libtmux_erlang/src/tmux_model.erl

Source at 4d73c9795adca3e49eea74d1d2cbbbbdcbea0b6c

SHA-256: 519cfeb36fa0ea3df6d742edc87ded1f9d4800fc4fe7c662f2e676e29a4ce0a9

%% Generated from schema/entities.json by tools/generate_schema.escript.
-module(tmux_model).
-moduledoc """
Validated native domain records. Constructors perform no tmux I/O.

Missing optional observations remain not_loaded; required identity fields
must be supplied. Unavailable capabilities remain
unavailable. Neither state means an empty relation or known absence.
Rows created by `new/2` and the entity constructors are detached.
Entity constructors accept generated input-map types such as
`t:pane_input/0`. Use `new/2` to validate dynamic maps; Dialyzer checks
known constructor shapes but does not replace runtime validation.
Use `tmux_server:bind/2` to register a fresh observed row for actions;
use `m:tmux_snapshot` for captured graph relationships.

Observed rows carry a private `t:observation/0` value. Actions compare it
with the row's origin, snapshot identity and target fields, rejecting
mismatched observations before I/O. Valid-shaped binding mismatches return
observation_mismatch; detached and malformed rows keep their validation
errors. Retarget through
`tmux_server:bind/2`; it reads current values. This protects ordinary API
use, not authority against trusted code in the Erlang VM.

Native model version 2 adds this association. Discard version-1 rows and
snapshots on upgrade and freshly observe them. `to_map/1` extracts domain
fields for explicit schema validation; maps carry no actionable origin.
""".
-export_record([session, window, window_link, pane]).
-export([new/2, validate/1, entity/1, get/2, to_map/1, origin/1,
         snapshot_id/1, model_version/1, bind/3, verify_observation/1]).
-export([session/1, window/1, window_link/1, pane/1]).
-export_type([row/0, observation/0, pane_id/0, window_id/0, session_id/0,
              session/0, window/0, window_link/0, pane/0,
              session_input/0, window_input/0, window_link_input/0, pane_input/0]).

-doc "A canonical pane ID binary in the percent namespace; nominal checking is by Dialyzer.".
-nominal pane_id() :: binary().
-doc "A canonical physical-window ID binary in the at-sign namespace.".
-nominal window_id() :: binary().
-doc "A canonical session ID binary in the dollar namespace.".
-nominal session_id() :: binary().

-record #observation{entity :: atom(), origin :: reference(),
    snapshot_id :: reference(), identity :: tuple()}.
-doc "Private captured target association, created by observation. Retain with its row; construction and field access are internal. It is not an authorization or serialization format.".
-opaque observation() :: #observation{}.

-record #session{
    id :: session_id(),
    name = not_loaded :: binary() | not_loaded | unavailable,
    attached_count = not_loaded :: non_neg_integer() | not_loaded | unavailable,
    attached = not_loaded :: boolean() | not_loaded | unavailable,
    created = not_loaded :: non_neg_integer() | not_loaded | unavailable,
    origin = none :: none | reference(),
    snapshot_id = none :: none | reference(),
    model_version = 2 :: pos_integer(),
    observation = none :: none | observation()
}.

-record #window{
    id :: window_id(),
    name = not_loaded :: binary() | not_loaded | unavailable,
    width = not_loaded :: non_neg_integer() | not_loaded | unavailable,
    height = not_loaded :: non_neg_integer() | not_loaded | unavailable,
    pane_count = not_loaded :: non_neg_integer() | not_loaded | unavailable,
    layout = not_loaded :: binary() | not_loaded | unavailable,
    origin = none :: none | reference(),
    snapshot_id = none :: none | reference(),
    model_version = 2 :: pos_integer(),
    observation = none :: none | observation()
}.

-record #window_link{
    session_id :: session_id(),
    window_id :: window_id(),
    index :: non_neg_integer(),
    active = not_loaded :: boolean() | not_loaded | unavailable,
    origin = none :: none | reference(),
    snapshot_id = none :: none | reference(),
    model_version = 2 :: pos_integer(),
    observation = none :: none | observation()
}.

-record #pane{
    id :: pane_id(),
    window_id = not_loaded :: window_id() | not_loaded | unavailable,
    index = not_loaded :: non_neg_integer() | not_loaded | unavailable,
    active = not_loaded :: boolean() | not_loaded | unavailable,
    current_command = not_loaded :: binary() | not_loaded | unavailable,
    current_path = not_loaded :: binary() | not_loaded | unavailable,
    width = not_loaded :: non_neg_integer() | not_loaded | unavailable,
    height = not_loaded :: non_neg_integer() | not_loaded | unavailable,
    pid = not_loaded :: pos_integer() | none | not_loaded | unavailable,
    title = not_loaded :: binary() | not_loaded | unavailable,
    dead = not_loaded :: boolean() | not_loaded | unavailable,
    exit_status = not_loaded :: integer() | none | not_loaded | unavailable,
    origin = none :: none | reference(),
    snapshot_id = none :: none | reference(),
    model_version = 2 :: pos_integer(),
    observation = none :: none | observation()
}.

-doc "One schema-defined native domain record, with separate origin and capture metadata.".
-type row() :: #session{} | #window{} | #window_link{} | #pane{}.
-doc "A validated session observation. Native records are experimental in OTP 29.".
-type session() :: #session{}.
-doc "A validated window observation. Native records are experimental in OTP 29.".
-type window() :: #window{}.
-doc "A validated window_link observation. Native records are experimental in OTP 29.".
-type window_link() :: #window_link{}.
-doc "A validated pane observation. Native records are experimental in OTP 29.".
-type pane() :: #pane{}.

-doc """
Trusted constructor fields for `session/1`. Required keys use :=;
optional observations may be not_loaded or unavailable. Integral floats
are normalized to integers. Runtime validation still checks ranges, IDs,
UTF-8 and derived values. Use `new/2` for dynamically validated maps.
""".
-type session_input() :: #{
    id := session_id(),
    name => binary() | not_loaded | unavailable,
    attached_count => non_neg_integer() | float() | not_loaded | unavailable,
    attached => boolean() | not_loaded | unavailable,
    created => non_neg_integer() | float() | not_loaded | unavailable
}.

-doc """
Trusted constructor fields for `window/1`. Required keys use :=;
optional observations may be not_loaded or unavailable. Integral floats
are normalized to integers. Runtime validation still checks ranges, IDs,
UTF-8 and derived values. Use `new/2` for dynamically validated maps.
""".
-type window_input() :: #{
    id := window_id(),
    name => binary() | not_loaded | unavailable,
    width => non_neg_integer() | float() | not_loaded | unavailable,
    height => non_neg_integer() | float() | not_loaded | unavailable,
    pane_count => non_neg_integer() | float() | not_loaded | unavailable,
    layout => binary() | not_loaded | unavailable
}.

-doc """
Trusted constructor fields for `window_link/1`. Required keys use :=;
optional observations may be not_loaded or unavailable. Integral floats
are normalized to integers. Runtime validation still checks ranges, IDs,
UTF-8 and derived values. Use `new/2` for dynamically validated maps.
""".
-type window_link_input() :: #{
    session_id := session_id(),
    window_id := window_id(),
    index := non_neg_integer() | float(),
    active => boolean() | not_loaded | unavailable
}.

-doc """
Trusted constructor fields for `pane/1`. Required keys use :=;
optional observations may be not_loaded or unavailable. Integral floats
are normalized to integers. Runtime validation still checks ranges, IDs,
UTF-8 and derived values. Use `new/2` for dynamically validated maps.
""".
-type pane_input() :: #{
    id := pane_id(),
    window_id => window_id() | not_loaded | unavailable,
    index => non_neg_integer() | float() | not_loaded | unavailable,
    active => boolean() | not_loaded | unavailable,
    current_command => binary() | not_loaded | unavailable,
    current_path => binary() | not_loaded | unavailable,
    width => non_neg_integer() | float() | not_loaded | unavailable,
    height => non_neg_integer() | float() | not_loaded | unavailable,
    pid => pos_integer() | float() | none | not_loaded | unavailable,
    title => binary() | not_loaded | unavailable,
    dead => boolean() | not_loaded | unavailable,
    exit_status => integer() | float() | none | not_loaded | unavailable
}.

-doc """
Construct a detached row from validated observations.

Accepts dynamic maps, including malformed input that returns a tagged
`t:tmux_schema:error_detail/0`. For trusted typed code, prefer the entity
constructors such as `pane/1` and `t:pane_input/0`.

```erlang
1> {ok, Pane} = tmux_model:new(pane, #{id => <<"%1">>, width => 120}), ok.
ok
2> tmux_model:get(width, Pane).
120
```
""".
-spec new(atom(), map()) -> {ok, row()} | {error, tmux_schema:error_detail()}.
new(Entity, Fields) ->
    maybe
        {ok, Normalized} ?= tmux_schema:normalize(Entity, Fields),
        {ok, build(Entity, Normalized)}
    end.

-doc "Construct a detached session row, validating required fields and scalar bounds without tmux I/O.".
-spec session(session_input()) -> {ok, session()} | {error, tmux_schema:error_detail()}.
session(Fields) -> new(session, Fields).

-doc "Construct a detached window row, validating required fields and scalar bounds without tmux I/O.".
-spec window(window_input()) -> {ok, window()} | {error, tmux_schema:error_detail()}.
window(Fields) -> new(window, Fields).

-doc "Construct a detached window_link row, validating required fields and scalar bounds without tmux I/O.".
-spec window_link(window_link_input()) -> {ok, window_link()} | {error, tmux_schema:error_detail()}.
window_link(Fields) -> new(window_link, Fields).

-doc "Construct a detached pane row, validating required fields and scalar bounds without tmux I/O.".
-spec pane(pane_input()) -> {ok, pane()} | {error, tmux_schema:error_detail()}.
pane(Fields) -> new(pane, Fields).

-doc "Validate native row shape, model version and normalized observations. Exported records do not enforce these invariants at construction. Performs no I/O.".
-spec validate(term()) -> {ok, row()} | {error, map()}.
validate(Row) ->
    case row_metadata(Row) of
        {Entity, 2, Origin, Snapshot, Observation}
          when (Origin =:= none orelse is_reference(Origin)),
               (Snapshot =:= none orelse is_reference(Snapshot)),
               (Observation =:= none orelse is_record(Observation, observation)) ->
            Fields = to_map(Row),
            case tmux_schema:normalize(Entity, Fields) of
                {ok, Fields} -> {ok, Row};
                {ok, _} -> {error, #{code => unnormalized_row, path => []}};
                {error, _} = Error -> Error
            end;
        _ -> {error, #{code => invalid_row, path => []}}
    end.

-doc "Return the built-in entity kind of a native row without I/O.".
-spec entity(row()) -> tmux_schema:entity().
entity(#session{}) -> session;
entity(#window{}) -> window;
entity(#window_link{}) -> window_link;
entity(#pane{}) -> pane.

-doc "Read the opaque origin token, or none for a detached row. This does not revalidate endpoint lifetime.".
-spec origin(row()) -> none | reference().
origin(#session{origin = Value}) -> Value;
origin(#window{origin = Value}) -> Value;
origin(#window_link{origin = Value}) -> Value;
origin(#pane{origin = Value}) -> Value.

-doc "Read the capture identity, or none when not associated with a snapshot. Performs no I/O.".
-spec snapshot_id(row()) -> none | reference().
snapshot_id(#session{snapshot_id = Value}) -> Value;
snapshot_id(#window{snapshot_id = Value}) -> Value;
snapshot_id(#window_link{snapshot_id = Value}) -> Value;
snapshot_id(#pane{snapshot_id = Value}) -> Value.

-doc "Read the native model version. Unknown versions fail validation; record internals are not a persistence format.".
-spec model_version(row()) -> pos_integer().
model_version(#session{model_version = Value}) -> Value;
model_version(#window{model_version = Value}) -> Value;
model_version(#window_link{model_version = Value}) -> Value;
model_version(#pane{model_version = Value}) -> Value.

-doc "Return domain field values without origin or capture metadata. This is not the portable filter wire representation. Performs no I/O.".
-spec to_map(row()) -> map().
to_map(Row = #session{}) -> #{id => Row#session.id, name => Row#session.name, attached_count => Row#session.attached_count, attached => Row#session.attached, created => Row#session.created};
to_map(Row = #window{}) -> #{id => Row#window.id, name => Row#window.name, width => Row#window.width, height => Row#window.height, pane_count => Row#window.pane_count, layout => Row#window.layout};
to_map(Row = #window_link{}) -> #{session_id => Row#window_link.session_id, window_id => Row#window_link.window_id, index => Row#window_link.index, active => Row#window_link.active};
to_map(Row = #pane{}) -> #{id => Row#pane.id, window_id => Row#pane.window_id, index => Row#pane.index, active => Row#pane.active, current_command => Row#pane.current_command, current_path => Row#pane.current_path, width => Row#pane.width, height => Row#pane.height, pid => Row#pane.pid, title => Row#pane.title, dead => Row#pane.dead, exit_status => Row#pane.exit_status}.

-doc "Read a permitted domain field without I/O. Unknown fields raise unknown_field; unloaded and unavailable values remain distinct.".
-spec get(atom(), row()) -> term().
get(id, #session{id = Value}) -> Value;
get(name, #session{name = Value}) -> Value;
get(attached_count, #session{attached_count = Value}) -> Value;
get(attached, #session{attached = Value}) -> Value;
get(created, #session{created = Value}) -> Value;
get(id, #window{id = Value}) -> Value;
get(name, #window{name = Value}) -> Value;
get(width, #window{width = Value}) -> Value;
get(height, #window{height = Value}) -> Value;
get(pane_count, #window{pane_count = Value}) -> Value;
get(layout, #window{layout = Value}) -> Value;
get(session_id, #window_link{session_id = Value}) -> Value;
get(window_id, #window_link{window_id = Value}) -> Value;
get(index, #window_link{index = Value}) -> Value;
get(active, #window_link{active = Value}) -> Value;
get(id, #pane{id = Value}) -> Value;
get(window_id, #pane{window_id = Value}) -> Value;
get(index, #pane{index = Value}) -> Value;
get(active, #pane{active = Value}) -> Value;
get(current_command, #pane{current_command = Value}) -> Value;
get(current_path, #pane{current_path = Value}) -> Value;
get(width, #pane{width = Value}) -> Value;
get(height, #pane{height = Value}) -> Value;
get(pid, #pane{pid = Value}) -> Value;
get(title, #pane{title = Value}) -> Value;
get(dead, #pane{dead = Value}) -> Value;
get(exit_status, #pane{exit_status = Value}) -> Value;
get(Field, Row) ->
    erlang:error({unknown_field, entity(Row), Field}, none,
        [{error_info, #{module => tmux_error}}]).

-doc false.
-spec bind(row(), reference(), reference()) -> row().
bind(Row = #session{}, Origin, Snapshot)
  when is_reference(Origin), is_reference(Snapshot) ->
    {ok, Row} = validate(Row),
    Row#session{origin = Origin, snapshot_id = Snapshot,
        observation = observation(Row, Origin, Snapshot)};
bind(Row = #window{}, Origin, Snapshot)
  when is_reference(Origin), is_reference(Snapshot) ->
    {ok, Row} = validate(Row),
    Row#window{origin = Origin, snapshot_id = Snapshot,
        observation = observation(Row, Origin, Snapshot)};
bind(Row = #window_link{}, Origin, Snapshot)
  when is_reference(Origin), is_reference(Snapshot) ->
    {ok, Row} = validate(Row),
    Row#window_link{origin = Origin, snapshot_id = Snapshot,
        observation = observation(Row, Origin, Snapshot)};
bind(Row = #pane{}, Origin, Snapshot)
  when is_reference(Origin), is_reference(Snapshot) ->
    {ok, Row} = validate(Row),
    Row#pane{origin = Origin, snapshot_id = Snapshot,
        observation = observation(Row, Origin, Snapshot)}.

-doc false.
-spec verify_observation(row()) -> ok | {error, map()}.
verify_observation(Row) ->
    case row_metadata(Row) of
        {_, 2, Origin, Snapshot, Captured}
          when is_reference(Origin), is_reference(Snapshot) ->
            case Captured =:= observation(Row, Origin, Snapshot) of
                true -> ok;
                false -> {error, #{code => observation_mismatch}}
            end;
        _ -> {error, #{code => observation_mismatch}}
    end.

observation(Row = #session{}, Origin, Snapshot) ->
    #observation{entity = session, origin = Origin,
        snapshot_id = Snapshot, identity = {Row#session.id}};
observation(Row = #window{}, Origin, Snapshot) ->
    #observation{entity = window, origin = Origin,
        snapshot_id = Snapshot, identity = {Row#window.id}};
observation(Row = #window_link{}, Origin, Snapshot) ->
    #observation{entity = window_link, origin = Origin,
        snapshot_id = Snapshot, identity = {Row#window_link.session_id, Row#window_link.window_id, Row#window_link.index}};
observation(Row = #pane{}, Origin, Snapshot) ->
    #observation{entity = pane, origin = Origin,
        snapshot_id = Snapshot, identity = {Row#pane.id, Row#pane.window_id, Row#pane.index}}.

row_metadata(#session{model_version = V, origin = O, snapshot_id = S,
        observation = B}) ->
    {session, V, O, S, B};
row_metadata(#window{model_version = V, origin = O, snapshot_id = S,
        observation = B}) ->
    {window, V, O, S, B};
row_metadata(#window_link{model_version = V, origin = O, snapshot_id = S,
        observation = B}) ->
    {window_link, V, O, S, B};
row_metadata(#pane{model_version = V, origin = O, snapshot_id = S,
        observation = B}) ->
    {pane, V, O, S, B};
row_metadata(_) -> invalid.

build(session, Fields) -> #session{
    id = maps:get(id, Fields),
    name = maps:get(name, Fields),
    attached_count = maps:get(attached_count, Fields),
    attached = maps:get(attached, Fields),
    created = maps:get(created, Fields)
};
build(window, Fields) -> #window{
    id = maps:get(id, Fields),
    name = maps:get(name, Fields),
    width = maps:get(width, Fields),
    height = maps:get(height, Fields),
    pane_count = maps:get(pane_count, Fields),
    layout = maps:get(layout, Fields)
};
build(window_link, Fields) -> #window_link{
    session_id = maps:get(session_id, Fields),
    window_id = maps:get(window_id, Fields),
    index = maps:get(index, Fields),
    active = maps:get(active, Fields)
};
build(pane, Fields) -> #pane{
    id = maps:get(id, Fields),
    window_id = maps:get(window_id, Fields),
    index = maps:get(index, Fields),
    active = maps:get(active, Fields),
    current_command = maps:get(current_command, Fields),
    current_path = maps:get(current_path, Fields),
    width = maps:get(width, Fields),
    height = maps:get(height, Fields),
    pid = maps:get(pid, Fields),
    title = maps:get(title, Fields),
    dead = maps:get(dead, Fields),
    exit_status = maps:get(exit_status, Fields)
}.