@spec children(t(), StatifierBlocks.Block.slot_name()) :: [child_summary()]

The ordered child summaries in slot, or [] for a slot with no children - including one the document never wrote.

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

The done.state event this block's state raises, for a block type that needs to name its own completion.

@spec done_id(t()) :: StatifierBlocks.Compiler.StateId.t()

The id of this block's conventional <final> child - the default outcome's final, outcome_id(ctx, "done") with the error arm discharged, since "done" is a literal outcome name this module knows is valid.

Under ADR-0004's outcome amendment (2b) that id is "s_" <> block_id <> "__o_done". It moved there from the ad-hoc role "done" the core vocabulary used before, which is what makes the amendment move compiled bytes for every document. The name and arity are unchanged, so no block type had to be edited to follow it.

@spec new(StatifierBlocks.Block.id(), StatifierBlocks.Document.id(), %{
  optional(StatifierBlocks.Block.slot_name()) => [child_summary()]
}) :: t()

Builds the context for block_id under document_id, with children keyed by slot name in the order slots/1 declared them.

@spec outcome_event(t(), String.t()) ::
  {:ok, String.t()}
  | {:error, {:invalid_outcome, StatifierBlocks.Block.id(), String.t()}}

The completion event a parent wires on for one outcome: done.outcome.<state id>.<outcome> (ADR-0004's outcome amendment, 2c).

The tag rides on an event rather than on the final's identity, because done.state.<state id> is generated whichever final is entered and a parent can therefore not see which one it was. A parent that does not care wires the prefix done.outcome.<state id> and matches every outcome of that child; one that discriminates names the full event. Refuses a malformed outcome name for the same reason outcome_id/2 does.

@spec outcome_id(t(), String.t()) ::
  {:ok, StatifierBlocks.Compiler.StateId.t()}
  | {:error, {:invalid_outcome, StatifierBlocks.Block.id(), String.t()}}

Mints the <final> id for one declared outcome (ADR-0004's outcome amendment, 2b):

outcome_id(block_id, outcome) = "s_" <> block_id <> "__o_" <> outcome

This is the only home for an outcome final's id. A block type with more than one way to finish emits one <final> per outcome it reaches and mints every one of them here rather than by string concatenation, for decision 3's reason: the ids stay injective, unstate_id/1 still inverts them, and provenance can still say which block a final came from.

outcome is a name in the role shape - ~r/\A[a-z][a-z0-9_]*\z/, no "__" - and one that is not is refused with {:error, {:invalid_outcome, block_id, outcome}} rather than raising.

@spec role_id(t(), StatifierBlocks.Compiler.StateId.role()) ::
  {:ok, StatifierBlocks.Compiler.StateId.t()}
  | {:error,
     {:invalid_role, StatifierBlocks.Block.id(),
      StatifierBlocks.Compiler.StateId.role()}}
  | {:error,
     {:reserved_role, StatifierBlocks.Block.id(),
      StatifierBlocks.Compiler.StateId.role()}}

Mints the id of an auxiliary state this block emits inside its own state, under role (decision 3).

Returns {:error, {:invalid_role, block_id, role}} for a role the compiler could not invert; a block type that passes a literal role never sees that arm, and one that builds a role from config handles it as the ordinary Emit finding it is.

A role beginning with "o_" is refused with {:error, {:reserved_role, block_id, role}}: that namespace belongs to outcome finals and outcome_id/2 is the only way into it.

@spec summary(StatifierBlocks.Block.id()) :: child_summary()

The summary of one compiled child, for a parent building a summary of its own or wiring a transition to a sibling.

summary/1 is the ordinary case: a child whose type declares no outcomes, which is the single default outcome named "done". The default lives in one place - this delegation - so a caller that does not know a child's module still produces a summary of the same shape.

@spec summary(StatifierBlocks.Block.id(), [String.t()]) :: child_summary()

The summary of one compiled child whose type declared outcome_names, in declaration order (ADR-0004's outcome amendment, 2e).

Order is preserved and never sorted: it is decision 6's byte determinism that depends on it. Every entry's state_id and done_event are computed against the child's block id through outcome_id/2 and outcome_event/2, so a summary can name only ids and events the child itself would mint.

A name that is not role-shaped is dropped rather than raising, which keeps this function total. It is unreachable in the compiler: the Emit stage refuses a malformed or duplicated outcome name with an :invalid_outcome finding on the misbehaving block's own pass, before any parent sees it in a summary.