ExecutionPlane.Contracts (execution_plane v0.1.0)

Copy Markdown View Source

Canonical helpers for the Execution Plane contract packet.

Wave 1 freezes the contract names, versions, lineage keys, and failure taxonomy. Family-specific payload interiors stay intentionally narrow and provisional until Wave 3 prove-out.

Summary

Types

handoff_status()
lineage_key()
lineage_t()
local_spool_mode()

Functions

canonical_lineage_keys()
contract_modules()
contract_version!(key)
contract_versions()
dump_lineage(lineage)
ensure_map!(value, field_name)
failure_classes()
fetch_optional_boolean!(attrs, key, default \\ false)
fetch_optional_list!(attrs, key, default \\ [], validator \\ & &1)
fetch_optional_map!(attrs, key, default \\ %{})
fetch_optional_stringish!(attrs, key, default \\ nil)
fetch_required_actor_refs!(attrs)
fetch_required_list!(attrs, key, validator \\ & &1)
fetch_required_map!(attrs, key)
fetch_required_non_neg_integer!(attrs, key)
fetch_required_stringish!(attrs, key)
fetch_value(attrs, key)
handoff_receipt_id(route_id, handoff_ref)
handoff_statuses()
lane_churn_fact_id(route_id, lane_ref, seq)
local_spool_modes()
maybe_match_lineage!(value, lineage, key, field_name)
normalize_attrs(attrs)
normalize_extensions!(attrs)
normalize_lineage!(lineage, required_keys \\ [])
pressure_fact_id(route_id, lane_ref, seq)
reconnect_fact_id(route_id, lane_ref, seq)
stringify_keys(struct)
validate_contract_version!(attrs, expected_version)
validate_iso8601!(value, field_name)
validate_non_empty_string!(value, field_name)
validate_opaque_handle_ref!(value, field_name)
validate_string!(value, field_name)

Types

handoff_status()

@type handoff_status() :: :accepted | :rejected | :unknown

lineage_key()

@type lineage_key() ::
  :tenant_id
  | :trace_id
  | :request_id
  | :decision_id
  | :boundary_session_id
  | :attempt_ref
  | :route_id
  | :event_id
  | :idempotency_key

lineage_t()

@type lineage_t() :: %{
  optional(lineage_key()) => String.t(),
  optional(:extensions) => map()
}

local_spool_mode()

@type local_spool_mode() :: :disabled | :emergency_only

Functions

canonical_lineage_keys()

@spec canonical_lineage_keys() :: [lineage_key(), ...]

contract_modules()

@spec contract_modules() :: [module(), ...]

contract_version!(key)

@spec contract_version!(atom()) :: String.t()

contract_versions()

@spec contract_versions() :: %{required(atom()) => String.t()}

dump_lineage(lineage)

@spec dump_lineage(lineage_t()) :: map()

ensure_map!(value, field_name)

@spec ensure_map!(term(), String.t()) :: map()

failure_classes()

@spec failure_classes() :: [
  ExecutionPlane.Contracts.FailureClass.failure_class(),
  ...
]

fetch_optional_boolean!(attrs, key, default \\ false)

@spec fetch_optional_boolean!(map() | keyword(), atom(), boolean()) :: boolean()

fetch_optional_list!(attrs, key, default \\ [], validator \\ & &1)

@spec fetch_optional_list!(map() | keyword(), atom(), [term()], (term() -> term())) ::
  [term()]

fetch_optional_map!(attrs, key, default \\ %{})

@spec fetch_optional_map!(map() | keyword(), atom(), map()) :: map()

fetch_optional_stringish!(attrs, key, default \\ nil)

@spec fetch_optional_stringish!(map() | keyword(), atom(), String.t() | nil) ::
  String.t() | nil

fetch_required_actor_refs!(attrs)

@spec fetch_required_actor_refs!(map() | keyword()) ::
  {String.t() | nil, String.t() | nil}

fetch_required_list!(attrs, key, validator \\ & &1)

@spec fetch_required_list!(map() | keyword(), atom(), (term() -> term())) :: [term()]

fetch_required_map!(attrs, key)

@spec fetch_required_map!(map() | keyword(), atom()) :: map()

fetch_required_non_neg_integer!(attrs, key)

@spec fetch_required_non_neg_integer!(map() | keyword(), atom()) :: non_neg_integer()

fetch_required_stringish!(attrs, key)

@spec fetch_required_stringish!(map() | keyword(), atom()) :: String.t()

fetch_value(attrs, key)

@spec fetch_value(map() | keyword(), atom()) :: term()

handoff_receipt_id(route_id, handoff_ref)

@spec handoff_receipt_id(String.t(), String.t()) :: String.t()

handoff_statuses()

@spec handoff_statuses() :: [handoff_status(), ...]

lane_churn_fact_id(route_id, lane_ref, seq)

@spec lane_churn_fact_id(String.t(), String.t(), non_neg_integer()) :: String.t()

local_spool_modes()

@spec local_spool_modes() :: [local_spool_mode(), ...]

maybe_match_lineage!(value, lineage, key, field_name)

@spec maybe_match_lineage!(String.t(), lineage_t(), lineage_key(), String.t()) :: :ok

normalize_attrs(attrs)

@spec normalize_attrs(map() | keyword()) :: map()

normalize_extensions!(attrs)

@spec normalize_extensions!(map() | keyword()) :: map()

normalize_lineage!(lineage, required_keys \\ [])

@spec normalize_lineage!(map() | keyword(), [lineage_key()]) :: lineage_t()

pressure_fact_id(route_id, lane_ref, seq)

@spec pressure_fact_id(String.t(), String.t(), non_neg_integer()) :: String.t()

reconnect_fact_id(route_id, lane_ref, seq)

@spec reconnect_fact_id(String.t(), String.t(), non_neg_integer()) :: String.t()

stringify_keys(struct)

@spec stringify_keys(term()) :: term()

validate_contract_version!(attrs, expected_version)

@spec validate_contract_version!(map() | keyword(), String.t()) :: String.t()

validate_iso8601!(value, field_name)

@spec validate_iso8601!(atom() | String.t(), String.t()) :: String.t()

validate_non_empty_string!(value, field_name)

@spec validate_non_empty_string!(term(), String.t()) :: String.t()

validate_opaque_handle_ref!(value, field_name)

@spec validate_opaque_handle_ref!(atom() | String.t(), String.t()) :: String.t()

validate_string!(value, field_name)

@spec validate_string!(term(), String.t()) :: String.t()