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 agrees?(StatifierDatamodel.Declarations.t(), [donedata_field()], term()) ::
  StatifierDatamodel.Types.reason()

Whether a child's declaration answers what a parent expects of it (ADR-0013 decision 4), as statifier_datamodel's own read check sees it.

declarations is the parent's, because the parent's collect_type is what is being satisfied; fields is the child's donedata_type/1; expected is the parent's collect_type spelling, as stored - either arm of it, since that field is a {:type_expr, opts} admitting both. A stored member list is read into an inline shape here exactly as StatifierBlocks.Environment reads one, so the arm the parent wrote is the arm this answers about. The answer is StatifierDatamodel.Types.reason/0, so a consumer that renders why a pair disagrees renders that package's reason and not a second vocabulary of this one's.

The child's fields are projected as one more declaration of kind record, under a name the parent's document does not use, each field required?: true - the child promises every one of them, because the compiler emits every one on every top-level final. The map is built for the question and discarded with the answer; neither document is written to.

The check is dormant. It is not a compile finding and its absence is not a warning: a core.map whose collect_type disagrees with its child's declaration compiles to exactly the bytes it would compile to if they agreed. It answers only where both documents are genuinely in hand, which the parent's compile never is - a core.map names its child chart by document id and cannot resolve it.

One consequence of that package's covering step is worth knowing rather than discovering: it answers :covers only where the expected side is a declaration of kind shape, so a collect_type naming a record is :not_assignable whatever the child declares. That is evidence about how nominal typing is spelled there, not evidence of drift.

Total over any input, including a child that declares nothing and a parent that declares nothing.

@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 - the two spellings decision 7 admits, read in one place.

A {:path, opts} field is a datamodel path by construction (amended 2026-09-05), and the optional datamodel_path?: true key beside a :string says the same thing (amended 2026-08-29). This function is why the second amendment did not have to withdraw the first: it is the one place a consumer asks the question, so reading the claim off either spelling is its business rather than every caller's, and a declaration carrying both is not a contradiction.

Total, and true for the literal true that the key's amendment admits and for nothing else. 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.

A {:type_expr, opts} field is false here, and the totality above is why no clause is added for it: the field names a type and never a location, so it has no path candidates, no undeclared-path advisory and no assign location. The declared type names it suggests and the declared paths a {:path, opts} field suggests share no member.

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

iex> StatifierBlocks.BlockType.datamodel_path?(%{key: "payload", type: {:type_expr, %{}}})
false

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

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

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

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

@spec default_config(palette_entry() | map()) :: StatifierBlocks.Block.config()

The config a probe of this type is built with, over config_schema/1's own defaults, as its palette entry declares it - or %{}.

Total, under the same refuse-never-raise discipline singleton/1 and badge/1 carry, and one step stricter than either: the value is a config map, so a declaration that is not a map reads as absent, and a map with keys that are not strings has those pairs dropped rather than being refused whole. A block's config is string-keyed everywhere else in this package, and an atom key here would land in a config no config_schema/1 field can ever name.

Nothing repairs the values. A host that declares a path that does not exist gets a probe reading a path the environment does not hold, which is :unknown and so satisfied - the same answer an unconfigured probe gave.

iex> StatifierBlocks.BlockType.default_config(%{default_config: %{"subject" => "cards.current_txn"}})
%{"subject" => "cards.current_txn"}

iex> StatifierBlocks.BlockType.default_config(%{default_config: %{subject: "cards.current_txn"}})
%{}

iex> StatifierBlocks.BlockType.default_config(%{default_config: "cards.current_txn"})
%{}

iex> StatifierBlocks.BlockType.default_config(%{})
%{}

@spec donedata_type(
  StatifierBlocks.Palette.type_ref(),
  StatifierBlocks.Block.config()
) :: [
  donedata_field()
]

The palette entry's donedata_type(config), or [] when donedata_type/1 is absent or the entry's module is not loadable (ADR-0013 decision 2).

Reached through StatifierBlocks.Palette.call/4, the seam outcomes/2 and failure_outcomes/2 above already use, so a host type written before the callback existed declares nothing and compiles exactly as it did.

The list comes back in declaration order, never sorted: the params serialize in that order, so a resolver that tidied it would move a host's compiled bytes for no reason it could name.

Total over any return value: anything that is not a list of maps carrying a binary name, a binary path and a type comes back as [], for failure_outcomes/2's reason - a host type that declares nonsense here should compile to the bytes it compiled to before rather than crash the compiler.

@spec failure_outcomes(
  StatifierBlocks.Palette.type_ref(),
  StatifierBlocks.Block.config()
) :: [
  String.t()
]

The palette entry's failure_outcomes(config), or [] when failure_outcomes/1 is absent or the entry's module is not loadable.

Reached through StatifierBlocks.Palette.call/4, the seam outcomes/2 above already uses, so a host type written before the callback existed classes no outcome and compiles exactly as it did.

Total over any return value: anything that is not a list of binaries comes back as [], for outcome_names/2's reason - a host type that declares nonsense here should compile to the bytes it compiled to before rather than crash the compiler.

@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(StatifierBlocks.Palette.type_ref(), StatifierBlocks.Block.config()) ::
  [outcome_decl()]

The palette entry's outcomes(config), or [{"done", "Done"}] when outcomes/1 is absent or the entry's module is not loadable (ADR-0002 amendment A1). Reached through StatifierBlocks.Palette.call/4, the one call seam, which owns the declaredness probe and the fallback together so no site repeats them.

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 sentence(StatifierBlocks.Palette.type_ref(), StatifierBlocks.Block.config()) ::
  String.t() | nil

module.sentence(config) as one line of prose, or the type's own label (ADR-0002's 2026-09-07 amendment).

The one shape every consumer reads. Four declaration states, and the claim is scoped to all four, so it is a table rather than a sentence:

"The type's label" is palette_entry()'s label. A module exporting no palette_entry/0, or declaring no label in it, has no label to answer and comes back nil: the type-NAME fallback decision 5's last sentence names is a fact about the document, not about the module, and it is StatifierBlocks.ViewModel's to supply. Absence is decided by StatifierBlocks.Palette.declares?/3, the seam's own predicate, so a module that is not loadable comes back nil as well.

No cap. Three of amendment B3's four arms hold - a non-string, a blank string and a multiline one are refused - and the length arm is not applied, for 10n's own reason: 24 characters is the number chosen so that a sentence does not fit. A callback that raises, throws or exits degrades on the grounds join_label/2 documents, and the rescued value is never inspected because what comes back is the package's own word for the type either way.

A raise therefore lands on the label while a type declaring nothing may land on an author's title first (ADR-0005's three-way chain). That is deliberate: a bounded rescue's answer is the package's own word, not an entry into a fallback chain a host callback could steer by raising.

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

iex> StatifierBlocks.BlockType.sentence(StatifierBlocks.Core.Sequence, %{})
"Sequence"

iex> StatifierBlocks.BlockType.sentence(NoSuchModule, %{})
nil

@spec singleton(palette_entry() | map()) :: singleton() | nil

How many of this block type the document may hold, as its palette entry declares it, or nil when it declares nothing this package can read (ADR-0005 clause 10z).

Total, under the same refuse-never-raise discipline badge/1 carries. A value outside [:head, :anywhere] - a string, a count, an atom this package has never heard of - is read as absent, so a host that declares something malformed gets the unconstrained document it had before rather than a finding it cannot act on.

nil is the default every entry has, and it is what StatifierBlocks.ViewModel reads to decide it has no type to count.

iex> StatifierBlocks.BlockType.singleton(%{singleton: :head})
:head

iex> StatifierBlocks.BlockType.singleton(%{singleton: "head"})
nil

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

@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 the palette entry's summary(config) declares, or [] (ADR-0002 amendment H2).

The one shape every consumer reads: a possibly-empty list of chips. A nil, an entry that does not declare summary/1, and one whose module is not loadable all come back []; a string comes back as a one-element list; a list comes back filtered. Absence is decided by StatifierBlocks.Palette.declares?/3, the seam's own predicate.

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 type_expr_findings(
  StatifierBlocks.Palette.type_ref(),
  StatifierBlocks.Block.config()
) :: [
  finding()
]

Every {:type_expr, opts} field of module's schema whose stored value is not an arm the declaration admits (ADR-0002 decision 7, amended 2026-09-06).

The one implementation the compiler and the editor both consult, in the shape validate_config/1 returns: the compiler routes it into its :config stage and the editor's view model routes it beneath the field, so the set an author is shown and the set a compile refuses cannot drift apart.

What it refuses is a value that is not an arm the field admits: text where only the inline arm is admitted, a member list where only the name arm is, an empty value where allow_empty?: false, or bytes that are no arm at all. The two arms are told apart by their JSON type alone - a string is never a member list - and no tag key is read.

Two cases are deliberately not refused. A name the datamodel document does not declare resolves to nothing and is the undeclared case, which the record decides no finding for; and a compile with no datamodel resolves no declared name at all. Member well-formedness is not checked here either: it is statifier_datamodel's, applied where the term is built.

iex> alias StatifierBlocks.Core.Map, as: CoreMap
iex> StatifierBlocks.BlockType.type_expr_findings(CoreMap, %{})
[]

@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.