@spec admits?(
  {module(), StatifierBlocks.Block.config()},
  StatifierBlocks.Block.slot_name(),
  {module(), StatifierBlocks.Block.config()}
) :: boolean()

ADR-0003 decision 3's structural verdict for placing child in slot of parent: :any admits everything, otherwise the slot's accepted kinds and the child's own kinds must intersect.

@spec assignable?(
  StatifierBlocks.Palette.t(),
  type_expr() | :unknown,
  type_expr() | :unknown
) ::
  boolean()

ADR-0003 decision 6's ordered relation. Four steps, checked in this order, and the order is the contract:

1. either side :unknown -> assignable (decision 5's permissive default);
2. produced == consumed -> assignable (decision 1's identity relation);
3. palette.assignability is nil -> not assignable (the floor a host cannot lower);
4. otherwise module.assignable?(produced, consumed).

Reflexivity holds regardless of the host, because step 2 short-circuits before step 4 is ever reached - the host callback is consulted only after identity has already failed, so it can only widen the relation, never narrow it. Step 4 is guarded the same way every other optional seam in this package is: a module that is not loadable, or does not export assignable?/2, yields false rather than raising, so a misconfigured palette degrades to the floor instead of turning a validation pass into an exception.

@spec check(
  StatifierBlocks.Palette.t(),
  StatifierBlocks.Document.t(),
  target(),
  StatifierBlocks.Block.t(),
  context()
) :: :ok | {:error, [finding()]}

ADR-0003 decision 7's one decision function: kind admission for candidate at target, plus the seams whose verdict a placement at target can change.

candidate not yet in document (Document.fetch_path/2 returns :error) is an insert: two seams, inbound_type(target) against candidate's consumes, and candidate's resolved produces against the consumes of whatever block currently sits at target's index (nothing to check when the slot ends there).

candidate already in document is a move: the same two seams, plus the seam it vacates - at its current position {p, s, i}, removing it makes i - 1 and i + 1 adjacent, so the resolved produces of the block at i - 1 (or the slot's own inbound type when i == 0) is checked against the consumes of the block at i + 1 (nothing to check when the slot has no i + 1).

Findings are decision 8's vocabulary verbatim, in this order when more than one applies: kind admission first, then the insertion seams, then the vacated seam. :ok when the list is empty.

Degradation, per decision 5: a block that fails Palette.resolve/2 - the candidate, the parent, or any block on a seam - contributes the permissive default rather than a finding, the same way io/2 already degrades a module that is not loadable.

@spec finding_reason(StatifierBlocks.Palette.t(), finding()) :: reason() | nil

The reason for one finding, derived rather than stored.

A :type_mismatch carries its producing ref, produced type and consumed type already, so its reason is seam_reason/4 applied to what the tuple holds - which is why the 2026-08-29 amendment adds no element to decision 8's tuples. A reason kept in the finding would be a second copy of a verdict the tuple plus the palette already determine, free to disagree with it; derived, it cannot.

:kind_not_admitted answers nil: the structural gate's reason is its own finding code, and this vocabulary is the data-flow gate's.

@spec inbound_type(
  StatifierBlocks.Palette.t(),
  StatifierBlocks.Document.t(),
  target(),
  context()
) ::
  type_expr() | :unknown

The inbound type at target (ADR-0003 decision 4), computed by walking - never stored:

• index > 0 -> the resolved produces of the sibling at index - 1;
• index == 0 -> the parent block's own inbound type, found by Document.fetch_path/2 on the parent's id and recursing on its last path step;
• the root (fetch_path returns {:ok, []}) -> ctx[:entry_type], defaulting to :unknown.

Total: a parent_id no block in document carries, or an index past the end of the slot's children, resolves to :unknown rather than raising, consistent with decision 5's permissive default. See produces/4 for the termination argument this function's own recursion (through own_inbound_type/4 and back) relies on - every step here moves to a strictly earlier pre-order position too: a previous sibling or a parent, both earlier than target itself.

Inside a core.drafts body the answer is :unknown at every index, and this record's amendment of 2026-08-31, section A2, is why. Between two parked fragments there is no seam: their order is shelf order, and ADR-0002's amendment of the same date, section G9a, fixes that the compiler never reads it as sequencing, so deriving one fragment's inbound type from the fragment above it would make rearranging a shelf produce and clear findings. At index == 0 the recursion would reach the shelf's own inbound, and the shelf has none - it declares no consumes, it is not in the flow, and nothing reaches it. Under decision 5 :unknown is assignable to any consumes, so no fragment is ever refused for the position it holds on the shelf.

The walk inside each fragment is untouched. A parked fragment is a subtree, its own internal seams are real sequencing, and they are checked exactly as they would be anywhere else - which is the property that makes the shelf worth having rather than a hole in the checker.

@spec io(module(), StatifierBlocks.Block.config()) :: io()

module.io(config), or %{} when io/1 is absent or module is not loadable (ADR-0003 decision 5). Checked with Code.ensure_loaded?/1 plus function_exported?/3, the pattern StatifierBlocks.Palette.resolve/2 already uses.

@spec kinds(module(), StatifierBlocks.Block.config()) :: [kind()]

The block's kinds, defaulting to [:step] (ADR-0003 decision 5).

@spec produces(
  StatifierBlocks.Palette.t(),
  StatifierBlocks.Document.t(),
  StatifierBlocks.Block.t(),
  context()
) :: type_expr() | :unknown

block's produces, resolved (ADR-0003 decision 4): a type expression resolves to itself; :unknown resolves to :unknown; {:passthrough, slot} resolves to the resolved produces of the last block in slot, or, when slot is empty (or is not a slot block declares - decision 4 is silent on that, and treating it as empty is the permissive, total reading decision 5 already establishes elsewhere), block's own inbound type.

A block that fails Palette.resolve/2 contributes :unknown rather than a finding (ADR-0003 decision 5's degradation rule; unresolvability is ADR-0002 decision 3's finding, reported by the walk that owns it).

Why this terminates

Every recursive step lands at a strictly earlier position, in the document's pre-order, than the position that made the original call. Resolving {:passthrough, slot} on block B either descends to the last child of B's own slot - later than B, but still strictly before whatever position asked for B's produces in the first place, since that position comes after B and every descendant of B is ordered before B's next sibling - or, when the slot is empty, falls back to B's own inbound type, which is either B's previous sibling or, at index 0, B's parent - both strictly earlier than B. Pre-order rank over a finite tree is a well-founded measure with no infinite descending chain, so this cannot cycle even for a tree of nothing but empty passthrough sequences.

@spec seam_reason(
  StatifierBlocks.Palette.t(),
  type_expr() | :unknown,
  type_expr() | :unknown,
  StatifierBlocks.Block.id() | :slot_entry
) :: reason() | nil

Why the seam produced -> consumed came out the way it did, as the 2026-08-29 amendment to ADR-0003 decision 8 defines it. producing_ref is the producing side of the seam exactly as decision 8's :type_mismatch tuple already names it: a block id, or :slot_entry when the type came from the slot's own inbound rather than from a block.

nil means there is nothing to explain: both sides are typed and the seam passed, by identity (decision 6 step 2) or because the palette's relation widened it (step 4). Every other outcome names itself.

The classification is total and follows decision 6's own order:

1. both sides :unknown -> :both_untyped;
2. produced :unknown -> :source_untyped;
3. consumed :unknown -> :target_untyped;
4. assignable?/3 -> nil;
5. producing_ref is a block id -> {:fixable_by, producing_ref};
6. otherwise -> :not_assignable.

This function decides nothing. It reads assignable?/3's verdict and labels it; it never gates on its own answer, and no caller in this package branches a verdict on it. That is what makes the reason vocabulary strictly explanatory: the first three arms sit on seams decision 5 admitted, and adding them cannot refuse anything, because :unknown stays permissive in both positions and step 4 short-circuits before either refusing arm is reachable.

The two refusing arms differ only in whether the author has somewhere to go, and the split is decision 8's own: producing_ref is exactly the third element of a :type_mismatch tuple, so {:fixable_by, block_id} names the block that finding already names, and :not_assignable is the case where that element is :slot_entry.

Two limits, both deliberate, both consequences of deriving the split from decision 8's tuple rather than from a second walk. At a slot's index 0 the producing ref is :slot_entry by decision 4's definition of the slot inbound, even when the type reached that position from a real block through a container - so a refusal there says :not_assignable though a block upstream of the container did declare the type. And when the named block passes a type through ({:passthrough, slot}), the declaration to change is inside it rather than on it.

Both could be closed by tracing a type to its declaring block, and neither is, on purpose: that trace is a second walk producing a second answer, and a second answer that can disagree with the finding the author is reading is the exact failure ADR-0003 decision 7 exists to prevent. One rule, one ref, one answer - see the amendment's consequences.

Structural refusals carry no reason from this vocabulary. {:kind_not_admitted, ...} already names both kind sets in the finding itself, so finding_reason/2 answers nil for it rather than duplicating it here.

@spec seam_reasons(
  StatifierBlocks.Palette.t(),
  StatifierBlocks.Document.t(),
  context()
) :: [
  {StatifierBlocks.Block.id(), StatifierBlocks.Block.id() | :slot_entry,
   reason()}
]

Every seam in document that has something to say about itself, in Document.blocks/1's pre-order: {consuming_block_id, producing_ref, reason}.

This is the queryable form of the cost ADR-0003's consequences state in prose - "a partially typed palette permits seams a fully typed one would catch". The three untyped arms name exactly those seams, and they are the reason this vocabulary is not merely a refusal vocabulary: a host auditing its own palette's coverage asks here, gets back the seams that passed without being checked, and types the blocks that produced them.

It changes no verdict and is not part of validation. A document whose every seam answers :source_untyped is exactly as valid as one whose seams answer nil - validate/3 is unchanged and still reports only the findings decision 8 defines. Seams with nothing to explain (typed on both sides and passing) are omitted rather than listed with a nil.

@spec slot_accepts(
  module(),
  StatifierBlocks.Block.config(),
  StatifierBlocks.Block.slot_name()
) ::
  [kind()] | :any

The accepted kinds for slot on module, defaulting to :any when the slot has no entry in io/1's :slot_accepts map (ADR-0003 decision 5).

@spec target_verdicts(
  StatifierBlocks.Palette.t(),
  StatifierBlocks.Document.t(),
  StatifierBlocks.Block.t(),
  context()
) :: [{target(), :ok | {:error, [finding()]}}]

Every position valid_targets/4 enumerates, each paired with check/5's full verdict rather than filtered down to the accepting ones.

valid_targets/4 is defined as this function keeping the :ok rows, so there is one enumeration and one decision, not two. It is exposed for the same reason the moduledoc's other widenings are: a caller that has to say why a position was refused - StatifierBlocks.Edit.Targets, which projects positions to slots and needs a reason for a slot it darkens - must not re-derive the position set, because a second enumeration is a second answer waiting to drift from this one.

Same order and the same determinism guarantee valid_targets/4 documents.

@spec valid_targets(
  StatifierBlocks.Palette.t(),
  StatifierBlocks.Document.t(),
  StatifierBlocks.Block.t(),
  context()
) :: [target()]

Every position in document where candidate may be dropped, per ADR-0003's valid_targets/4: for every block in Document.blocks/1, for every slot that block's module declares (module.slots(config), not the slot keys the stored document happens to carry), for every index from 0 to that slot's current child count inclusive, the position is kept when check/5 returns :ok for it.

Deterministic: Document.blocks/1 is already pre-order, slots/1 is visited in the order it declares slots, and indices ascend within each slot - so the same call always returns the same list, in the same order.

A block whose type fails Palette.resolve/2 contributes no positions: there is no module to ask for a declared slot set, so this is an absence of positions rather than a refusal. Offering a target inside a slot that is not even declared would be offering a position the document walk that owns undeclared-slot findings (ADR-0002 decision 6) then rejects.

@spec validate(StatifierBlocks.Palette.t(), StatifierBlocks.Document.t(), context()) ::
  :ok | {:error, [finding()]}

Every finding in document, per ADR-0003's validate/3: every seam already present in the document, checked with the same rules check/5 checks a seam with - the whole-document counterpart to check/5's single-position query.

A document's seams are exactly its blocks' own upstream seams: the slot's own inbound (or the previous sibling's resolved produces, when there is one) against the block's consumes, plus the same kind-admission check check/5 runs for a candidate at a target. Walking every block in Document.blocks/1 other than the root (which occupies no slot and has no seam of its own) and checking each one this way visits every seam in the document exactly once - a block never shares its upstream seam with any other block, and nothing in a slot has a seam after its last child that some other block's own upstream check does not already cover.

This is deliberately not check/5 called with a block already sitting at its own current position as the candidate: check/5's downstream and vacated seams are defined relative to a target the candidate is being placed at or removed from, and a block that already occupies target makes both of those seams check the block against itself, or against neighbors as though the block were not there at all - neither is a seam that exists in document as given. validate/3 reaches the same two checks check/5 runs for kind admission and the upstream seam - kind_admission_finding/5 and upstream_seam_finding/5

• directly, so the decision stays the one check/5 is built from without running its candidate-already-there degenerate case.

:ok when the document has no findings; otherwise {:error, findings} with every block's findings concatenated, in Document.blocks/1's pre-order.