Declares the behaviour and injects the overridable defaults ADR-0007 decision 1 names. See the moduledoc section above for what they are and why emit/2 is not one of them.

@spec badge(palette_entry() | map()) :: String.t() | nil

The chip a palette entry declares for its block type's card header, or nil when it declared none or declared one this package will not draw (ADR-0002 amendment B's badge).

Total, under B3's refuse-do-not-truncate discipline. Refused: a non-string, an empty or all-whitespace string, one carrying a newline, carriage return or tab, and one longer than 24 characters. An over-long badge is dropped, not clipped, and one carrying a newline is dropped rather than collapsed to a space: a truncated chip reads as a rendering bug a host files against the editor, where a missing chip reads as the declaration it is.

nil means no chip, which is the card every block type had before the declaration existed. A malformed declaration in one host's registry produces the ordinary card, never a broken one and never an exception - decision 3's totality, arriving at presentation.

iex> StatifierBlocks.BlockType.badge(%{badge: "calls the host"})
"calls the host"

iex> StatifierBlocks.BlockType.badge(%{badge: "a chip that says altogether too much"})
nil

iex> StatifierBlocks.BlockType.badge(%{})
nil

@spec datamodel_path?(field_decl()) :: boolean()

Whether a field declaration says its value is a datamodel path (ADR-0002 decision 7's optional datamodel_path? key, amended 2026-08-29).

Total, and true only for the literal true that the amendment admits. Absence means what it meant before the key existed, and any other value

• a string, nil, a map - reads as absence rather than as truthiness, on the same normalizer discipline value_path/1 and StatifierBlocks.ViewModel.accent_token/1 are under: a typo in a host's registry degrades to the behaviour that predates the key.

  iex> StatifierBlocks.BlockType.datamodel_path?(%{key: "path", datamodel_path?: true}) true

  iex> StatifierBlocks.BlockType.datamodel_path?(%{key: "path"}) false

  iex> StatifierBlocks.BlockType.datamodel_path?(%{key: "path", datamodel_path?: "yes"}) false

@spec fetch_value(StatifierBlocks.Block.json(), value_path()) ::
  {:ok, StatifierBlocks.Block.json()} | :error

The config value at path, or :error when the path does not resolve.

:error is a real answer, not a failure: an arm that carries no cond yet has no value at ["arms", 0, "cond"], and the form renders that field at its default. Total over any config and any path.

@spec join_label(palette_entry() | map(), StatifierBlocks.Block.config()) ::
  String.t() | nil

What the join marker under this block type's side-by-side arrangement says for config, or nil when the entry declares none and the editor should use its own word (ADR-0002 amendment B's join_label).

The declaration is a one-argument function of the block's config - join_label/0 - and it is host code on the editor's layout path, so two rules from amendment B2 and B3 apply and are implemented here:

• It is a pure function of its argument. That is decision 4, and it is enforced by convention rather than by the gate, exactly as it is for every other callback. A host needing external data to phrase a marker resolves it before the operation and threads it through config.
• A raise degrades to the default. The call happens inside a rescue, so a host type with a bug in its join_label gets an ordinary join marker rather than taking the canvas down. A throw and an exit are caught on the same grounds - B3's own heading names the throw. This is a deliberate, bounded exception to this package's "nothing rescued to a default" rule: the value being defaulted is one word of chrome and the alternative is a blank editor. validate_config/1, slots/1, emit/2 and every other callback keep the rule unweakened.

The return is then held to badge/1's refusal set, so a callback that answers with a sentence, a newline, or something that is not a string at all reads as no declaration rather than as a broken marker. A declaration that is not a one-argument function is refused without being called.

iex> StatifierBlocks.BlockType.join_label(%{join_label: fn _config -> "all lanes" end}, %{})
"all lanes"

iex> StatifierBlocks.BlockType.join_label(%{join_label: fn _config -> raise "boom" end}, %{})
nil

iex> StatifierBlocks.BlockType.join_label(%{join_label: "not a function"}, %{})
nil

@spec outcome_name(StatifierBlocks.Block.config(), String.t() | nil) ::
  String.t() | nil

The outcome config declares at key, or nil.

The other half of slot_outcome_key/2: the container says where to look, this reads it out of one block's config. The value is an outcome name in ADR-0002 amendment A1's alphabet, so a config that holds something else there - a number, a sentence, a key that was never filled in - reads as no declared outcome rather than as a route nobody can render. nil for key is the no-declaration case, so a caller threads the pair without branching on it.

@spec outcome_names(module(), StatifierBlocks.Block.config()) :: [String.t()]

The names outcomes/2 declares, in declaration order.

What the compiler mints ids and events from; the labels are the editor's.

Total over any return value, including one the outcome_decl/0 spec does not describe: a declaration that is not a {name, label} pair with a binary name comes back as its inspect/1 rendering, which no role shape matches, so a host type that declares nonsense gets the ordinary :invalid_outcome finding naming what it wrote rather than a crash inside the compiler.

@spec outcomes(module(), StatifierBlocks.Block.config()) :: [outcome_decl()]

module.outcomes(config), or [{"done", "Done"}] when outcomes/1 is absent or module is not loadable (ADR-0002 amendment A1). Checked with Code.ensure_loaded?/1 plus function_exported?/3, the pattern StatifierBlocks.Palette.resolve/2 already uses.

The list comes back in declaration order, never sorted: ADR-0004 decision 6's byte determinism reads that order, and a resolver that tidied it would move a host's compiled bytes for no reason it could name.

@spec put_value(
  StatifierBlocks.Block.json(),
  value_path(),
  StatifierBlocks.Block.json()
) ::
  StatifierBlocks.Block.json()

config with path's value replaced, or config unchanged when the path does not lead anywhere the value could go.

The last segment is written whether or not something was already there - an arm missing its "cond" is exactly the arm an author is about to type a condition into, and refusing that write would make the field permanently uneditable. Every segment before it must already exist: a path is a way to reach a value the block type stores, not a licence for a form control to invent a shape the type never wrote. A list index out of range writes nothing, since a list has no gap to fill.

Only the map case needs a last-segment clause of its own. A list's does the same thing either way - replacing element i with the result of writing the empty path into it, which is that value - so the recursive clause covers a path ending at a list index too, and the empty path it bottoms out on addresses the config root. That is why value_path/1 never returns an empty path.

@spec slot_outcome_key(palette_entry() | map(), StatifierBlocks.Block.slot_name()) ::
  String.t() | nil

The config key the blocks in slot_name carry their outcome under, or nil when the entry declares none.

ADR-0005 decision 10's slot_outcome_key (proposed there as 10f): a block type with a statically-named slot whose children finish the container in more than one way may say where that answer lives, so a consumer routes on the value without knowing which type declared it. core.group declares %{"interrupts" => "outcome"}; the renderer reads the declaration, never the type name, which is the property decision 10 exists to preserve.

It names a key and never a value, for icon's reason: an entry carrying the outcome itself would be one declaration per slot for a fact that is per block, and the container does not know its children's config. Which outcome a given slot's completion reaches stays undeclared - ADR-0002's amendment A2 parks that deliberately, and this is not it.

Total, under ADR-0002 amendment B3's refuse-do-not-truncate discipline: a missing declaration, a non-map, a slot the map does not name, a non-binary key, and a key outside ~r/\A[a-z][a-z0-9_]*\z/ all read as nil, which means the uniform rendering every consumer did before the declaration existed. Nothing here raises and nothing is repaired into something almost right.

@spec summary(module(), StatifierBlocks.Block.config(), chip_labels()) :: [String.t()]

The chips module.summary(config) declares, or [] (ADR-0002 amendment H2).

The one shape every consumer reads: a possibly-empty list of chips. A nil, a module that does not export summary/1, and a module that is not loadable all come back []; a string comes back as a one-element list; a list comes back filtered. Absence is checked with Code.ensure_loaded?/1 plus function_exported?/3, the pattern outcomes/2 already uses.

Each chip is held to badge/1's refusal set, unchanged: a non-string, an empty or all-whitespace string, one carrying a newline, carriage return or tab, and one longer than 24 characters are refused, never truncated (amendment H3). A refused chip is dropped and its siblings survive, so one over-long lane name costs its own chip and nothing else. A summary whose every chip is refused is [], which is the card that type had before it declared one.

A callback that raises, throws or exits answers [] on the grounds join_label/2 documents: this is host code on the editor's layout path, and the value being defaulted is one line of chrome.

iex> StatifierBlocks.BlockType.summary(StatifierBlocks.Core.Send, %{"event" => "order.paid"})
["order.paid"]

iex> StatifierBlocks.BlockType.summary(StatifierBlocks.Core.Sequence, %{})
[]

iex> StatifierBlocks.BlockType.summary(NoSuchModule, %{})
[]

@spec summary_refusal_message(
  module(),
  StatifierBlocks.Block.config(),
  {non_neg_integer(), summary_refusal_reason()},
  chip_labels()
) :: String.t()

What one summary_refusals/2 entry says to an author, in the words a :lint finding carries.

The message names the chip's position, its length and the cap, because those are the three facts an author needs to fix the declaration and none of them is visible on a card that simply drew nothing. Position is one-based here and zero-based in the tuple: the tuple indexes a list and the sentence counts chips.

The cap lives in this module (ADR-0002 amendment H's Consequences: one number in one place), so the sentence is built here rather than by the editor. Total: an entry naming a position the type no longer declares still answers a sentence.

iex> StatifierBlocks.BlockType.summary_refusal_message(StatifierBlocks.Core.Parallel, %{"lanes" => ["capture", "balance_check_and_fraud_review"]}, {1, :too_long})
"summary chip 2 is 30 characters; the cap is 24, so it is not drawn"

@spec summary_refusals(module(), StatifierBlocks.Block.config(), chip_labels()) :: [
  {non_neg_integer(), summary_refusal_reason()}
]

The chips summary/2 dropped, as {index, reason} in declaration order.

ADR-0005 decision 10's 2026-08-30 Note, "the cap signals". Refusing a chip removes the evidence that anything was declared, so the card of a block whose lane name is one character too long is indistinguishable from the card of a block that declared no lane at all. This is the reader that says which - the editor turns each entry into a :lint warning against the block (StatifierBlocks.ViewModel), and nothing about the card, the cap or summary/2 moves to make that possible.

index is the zero-based position in the list the type declared, so it survives a refusal in front of it - summary/2's output has already closed the gap and cannot be indexed against. Total for the same reasons summary/2 is: a type that exports no summary/1, a module that does not exist, and a callback that raises all answer [], which is "nothing was refused" and is honest in each case.

iex> StatifierBlocks.BlockType.summary_refusals(StatifierBlocks.Core.Parallel, %{"lanes" => ["capture", "balance_check_and_fraud_review"]})
[{1, :too_long}]

iex> StatifierBlocks.BlockType.summary_refusals(StatifierBlocks.Core.Wait, %{"duration" => "30s"})
[]

iex> StatifierBlocks.BlockType.summary_refusals(NoSuchModule, %{})
[]

@spec summary_titles(module(), StatifierBlocks.Block.config(), chip_labels()) :: [
  String.t() | nil
]

The raw text behind each chip summary/3 drew, or nil where the chip is drawn as declared. Index-aligned with summary/3 by construction.

ADR-0005 decision 10w's other half: a translated chip says less than the string behind it, and this is what keeps that reversible. The editor puts it on the chip's title attribute, so an author debugging a chart against generated SCXML still has the exact event name. nil for every chip that was not translated, which is every chip an author wrote.

Alignment is not maintained, it is derived: this and summary/3 read the same one pass and apply the same refusal filter, so a chip cannot be drawn by one and dropped by the other.

iex> StatifierBlocks.BlockType.summary_titles(StatifierBlocks.Core.Send, %{"event" => "order.paid"})
[nil]

@spec value_path(field_decl()) :: value_path()

Where a field declaration's value lives, as a path from the config root.

The declared value_path when there is one, and [key] - the default ADR-0002 decision 7 states - when there is not. Callers get a path either way and never branch on which case they are in.

An explicitly empty value_path is read as no path at all rather than as "the config root": a field editing the whole config is not something decision 7 describes, and silently letting one through would let a form control overwrite every key the block carries.