@spec done_event(t()) :: String.t()

The done.state event a compound state raises when it enters a <final> child (ADR-0004 decision 2). This is the whole of what a parent needs to know about a child it did not compile.

iex> StatifierBlocks.Compiler.StateId.done_event("s_blk_SEQ")
"done.state.s_blk_SEQ"

@spec outcome_event(t(), role()) :: String.t()

The completion event one declared outcome raises (ADR-0004's outcome amendment, 2c): done.outcome.<state id>.<outcome>.

Spelled once, here, so the event a <final> raises and the event a parent wires on cannot drift apart.

iex> StatifierBlocks.Compiler.StateId.outcome_event("s_blk_AUTH", "error")
"done.outcome.s_blk_AUTH.error"

@spec outcome_prefix() :: String.t()

The reserved role prefix an outcome final's role carries (ADR-0004's outcome amendment, 2b).

iex> StatifierBlocks.Compiler.StateId.outcome_prefix()
"o_"

@spec role?(term()) :: boolean()

Whether role is a role this module will mint an id for.

iex> StatifierBlocks.Compiler.StateId.role?("lane_capture")
true

iex> StatifierBlocks.Compiler.StateId.role?("Done")
false

@spec state_id(StatifierBlocks.Block.id()) :: t()

The state id of the state block_id's block compiles to.

iex> StatifierBlocks.Compiler.StateId.state_id("blk_ROOT")
"s_blk_ROOT"

@spec state_id(StatifierBlocks.Block.id(), role()) ::
  {:ok, t()} | {:error, {:invalid_role, StatifierBlocks.Block.id(), role()}}

The state id of an auxiliary state block_id's block mints under role.

Returns {:error, {:invalid_role, block_id, role}} rather than raising for a role this module cannot invert - an ordinary Emit-stage finding, since emit/2 is a total function like every other callback.

iex> StatifierBlocks.Compiler.StateId.state_id("blk_SEQ", "done")
{:ok, "s_blk_SEQ__done"}

iex> StatifierBlocks.Compiler.StateId.state_id("blk_SEQ", "a__b")
{:error, {:invalid_role, "blk_SEQ", "a__b"}}

@spec undone_event(term()) ::
  {:ok, {StatifierBlocks.Block.id(), role() | nil}} | :error

Inverts done_event/1 and outcome_event/2 back to the block whose completion the event names, and the outcome it names, or :error for a string that is not unambiguously one of them.

It lives here for the reason unoutcome_id/1's own @doc gives about itself: the inversion belongs beside the derivation it inverts, not inside a caller that would have to rediscover why it is exact. The caller this exists for is ADR-0005 decision 10w - a summary chip whose text has the shape of a generated done-event name is drawn as the block's label rather than as the compiler's spelling of it.

nil comes back for the done.state form because that event carries no outcome name: ADR-0004 decision 2 makes it the block's completion signal and nothing more. Naming one here would invent a concept ADR-0004 does not have, so what to draw in its place is the caller's word, not this function's.

Why this is total rather than best-effort

StatifierBlocks.Validation admits any non-empty UTF-8 string as a block id, so the opacity this module's moduledoc argues from is a property of every id this package mints and not of every id it admits. A document arriving through from_json/1 may carry a block id containing "__", or a ".", and either gives a generated event name a second reading: done.outcome.s_a__b.error reads as block a__b and as block a under role b, and done.outcome.s_A.B.C reads as outcome B.C and as outcome C.

Every such string answers :error, which is the fail-safe ADR-0005 decision 10y requires: a chip drawn as its raw event name is a presentation defect, and a chip drawn as the wrong block's label is a card that says a different block completed.

iex> StatifierBlocks.Compiler.StateId.undone_event("done.outcome.s_blk_AUTH.error")
{:ok, {"blk_AUTH", "error"}}

iex> StatifierBlocks.Compiler.StateId.undone_event("done.state.s_blk_SEQ")
{:ok, {"blk_SEQ", nil}}

iex> StatifierBlocks.Compiler.StateId.undone_event("done.outcome.s_a__b.error")
:error

iex> StatifierBlocks.Compiler.StateId.undone_event("done.outcome.s_A.B.C")
:error

iex> StatifierBlocks.Compiler.StateId.undone_event("order.paid")
:error

@spec unoutcome_id(t()) :: {:ok, {t(), role()}} | :error

Inverts an outcome final's id back into the block's own state id and the outcome name, or :error for an id that is not one.

This is unstate_id/1 with the outcome namespace read off the role, and it lives here for that reason: the inversion belongs beside the derivation it inverts, not inside a caller that would have to rediscover why it is exact. It is exact because a generated id contains exactly one "__" - a block id carries none (ADR-0001 decision 3) and a role is refused if it does - so the role is unambiguous, and a role in the o_ namespace is minted only by StatifierBlocks.Compiler.Context.outcome_id/2.

The state id that comes back is state_id(block_id), which is what the outcome's completion event names.

iex> StatifierBlocks.Compiler.StateId.unoutcome_id("s_blk_AUTH__o_error")
{:ok, {"s_blk_AUTH", "error"}}

iex> StatifierBlocks.Compiler.StateId.unoutcome_id("s_blk_AUTH__done")
:error

iex> StatifierBlocks.Compiler.StateId.unoutcome_id("s_blk_AUTH")
:error

@spec unstate_id(t()) :: {:ok, {StatifierBlocks.Block.id(), role() | nil}} | :error

Inverts state_id/1 and state_id/2.

iex> StatifierBlocks.Compiler.StateId.unstate_id("s_blk_SEQ")
{:ok, {"blk_SEQ", nil}}

iex> StatifierBlocks.Compiler.StateId.unstate_id("s_blk_SEQ__done")
{:ok, {"blk_SEQ", "done"}}

iex> StatifierBlocks.Compiler.StateId.unstate_id("blk_SEQ")
:error