@spec candidates(StatifierBlocks.Document.t(), term(), term()) :: [String.t()]

The declared datamodel paths an expression control offers as candidates, sorted and deduplicated - the data half of sb-0vt, and nothing else.

This reads the same three declaring surfaces findings/4 does, by the same normalizers, so the set an author is offered and the set that decides whether they get an advisory cannot drift apart: the host's datamodel through declared_paths/1, the compile call's roots through declared_roots/1, and the document's own datamodel key read straight off document, which is why that surface takes no argument here either.

Absence collapses to [] rather than to nil. That is a deliberate difference from the advisory above, and it is not a rescue-to-default: nil is load-bearing for findings/4 because "nobody described anything" and "somebody described nothing" are different claims about a path the author already wrote. A candidate list makes no claim about anything - it either has something to offer or it does not - so both cases are one empty list, and the caller renders no control for it.

A root and a path are both offered whole. A declared root means storage exists at a name and says nothing about what is under it (11l), so signup is the only candidate it can contribute; the datamodel document is what contributes signup.email.

What this is not

It is not the completion feature. ADR-0005 decision 9 keeps rich expression editing - completion against the datamodel as an affordance, inline evaluation against a dataset - in statifier-ui behind the expression_component seam, and this function does not move it. It supplies the one part of that affordance this package owns the data for, so the seam's implementer does not have to re-derive it and the shipped plain input can offer a <datalist> in the meantime.

Operators, keywords and literals are not here and cannot be yet. Predicator exposes no public enumeration of its grammar - operator and keyword tokens live inside Predicator.Lexer - and copying that vocabulary into this package would be a second, silently drifting copy of a contract predicator owns. That half is px-15q's.

iex> alias StatifierBlocks.{Block, Datamodel, Document}
iex> document = Document.new(Block.new("core.sequence", id: "blk_root"), id: "doc_x")
iex> Datamodel.candidates(document, ["card.brand", "card"], ["signup"])
["card", "card.brand", "signup"]

iex> alias StatifierBlocks.{Block, Datamodel, Document}
iex> document = Document.new(Block.new("core.sequence", id: "blk_root"), id: "doc_x")
iex> Datamodel.candidates(document, nil, [])
[]

@spec candidates_under(term(), term()) :: [String.t()]

The candidates strictly under prefix, in the datamodel document's own order - ADR-0006 decision 6's completion query, reached through StatifierBlocks.Predicates.Datamodel.under/2 rather than restated here.

This is the narrowing query the expression_component seam needs and the shipped <datalist> does not: a datalist is handed the whole set once and the browser filters it, while a component that re-renders per keystroke wants only the branch the author is inside. Both read the same document, through the same one implementation of the projection.

prefix itself is not among the results, matching under/2; a datamodel that is not an ADR-0006 document has no order to query and returns [], which is the same total-normalizer discipline declared_paths/1 applies to the same input.

iex> alias StatifierBlocks.Datamodel
iex> Datamodel.candidates_under(
...>   %{"scopes" => [%{"scope" => "local", "entries" => [
...>     %{"path" => "card", "type" => "object", "fields" => [
...>       %{"path" => "card.brand"}, %{"path" => "card.last4"}]}]}]},
...>   "card")
["card.brand", "card.last4"]

iex> StatifierBlocks.Datamodel.candidates_under(["card.brand"], "card")
[]

@spec declared_paths(term()) :: declared()

Normalizes a host-supplied datamodel to a declared-path set, or nil.

Total: every input has an answer and none of them raise. See the moduledoc for what is accepted and why the list is short.

iex> StatifierBlocks.Datamodel.declared_paths(nil)
nil

iex> StatifierBlocks.Datamodel.declared_paths(["signup.step", "signup.variant_id"])
MapSet.new(["signup.step", "signup.variant_id"])

iex> StatifierBlocks.Datamodel.declared_paths(["signup.step", "", 42])
MapSet.new(["signup.step"])

iex> StatifierBlocks.Datamodel.declared_paths(%{"scopes" => []})
MapSet.new([])

iex> StatifierBlocks.Datamodel.declared_paths(%{"version" => 1, "scopes" => [
...>   %{"scope" => "local", "entries" => [
...>     %{"name" => "step", "path" => "signup.step", "type" => "string",
...>       "label" => "Step"}]}]})
MapSet.new(["signup.step"])

iex> StatifierBlocks.Datamodel.declared_paths(%{"scopes" => "not a list"})
nil

@spec declared_roots(term()) :: MapSet.t(String.t())

Normalizes the compile call's :declare roots to a set of root names.

11k's second source. The input is the shape StatifierBlocks.Compiler.compile/3 takes - a list of {id, expr} pairs in declaration order - so a host passes the editor the same list it passes the compiler rather than a second spelling of it. A bare id is accepted too, and an already-normalized MapSet passes through idempotently.

Total, like declared_paths/1, and for the same reason: a shape this package does not know normalizes to the empty set, which per 11m declares nothing rather than declaring that nothing exists. There is no nil here - a root set is never a claim about paths, so it has no "no datamodel supplied" state to distinguish.

iex> StatifierBlocks.Datamodel.declared_roots([{"signup", nil}, {"card", "0"}])
MapSet.new(["card", "signup"])

iex> StatifierBlocks.Datamodel.declared_roots(["signup"])
MapSet.new(["signup"])

iex> StatifierBlocks.Datamodel.declared_roots(nil)
MapSet.new([])

iex> StatifierBlocks.Datamodel.declared_roots([{"signup", nil}, 42, {"", nil}])
MapSet.new(["signup"])

@spec declared_view(StatifierBlocks.Document.t(), term(), term()) :: [declared_row()]

Every declared path, with the surfaces that declared it and the shape the ADR-0006 projection carries for it - the read-only view of what the 11e advisory reads.

The rows are candidates/3's set, in candidates/3's order, and that is the point rather than a convenience: the advisory decides "is the path this author wrote declared?" against the union of 11k's three surfaces, so a view that showed only one of them would answer a different question than the one the author is looking at a finding about. Reading the three through the same normalizers here is the same anti-drift rule candidates/3 is written under.

sources is a list because the surfaces overlap legitimately: a host that declares a root and also enumerates it in its datamodel document has said the same thing twice, and a row that named only the first would hide the second.

Shape comes from the ADR-0006 document alone, through StatifierBlocks.Predicates.Datamodel.fetch/2, and is absent for everything else. A set of paths carries no types, and a declared root carries none by 11l, so those rows are shapeless rather than guessed at.

iex> alias StatifierBlocks.{Block, Datamodel, Document}
iex> document = Document.new(Block.new("core.sequence", id: "blk_root"), id: "doc_x")
iex> datamodel = %{"scopes" => [%{"scope" => "local", "entries" => [
...>   %{"path" => "card.brand", "type" => "string", "label" => "Brand"}]}]}
iex> Datamodel.declared_view(document, datamodel, ["signup"])
[
  %{path: "card.brand", sources: [:datamodel], type: :string, item_type: nil,
    scope: :local, label: "Brand", sensitive?: false},
  %{path: "signup", sources: [:declare], type: nil, item_type: nil,
    scope: nil, label: nil, sensitive?: false}
]

iex> alias StatifierBlocks.{Block, Datamodel, Document}
iex> document = Document.new(Block.new("core.sequence", id: "blk_root"), id: "doc_x")
iex> Datamodel.declared_view(document, nil, [])
[]

@spec findings(
  StatifierBlocks.Document.t(),
  StatifierBlocks.Palette.t(),
  term(),
  term()
) :: [
  StatifierBlocks.Finding.t()
]

Every undeclared-path advisory in the document (11e), or [] when nothing anywhere declared anything (11f as 11m widens it).

datamodel is normalized through declared_paths/1 and declare through declared_roots/1, so a raw list and an already-normalized set behave identically in both. The document's own roots are read off document and take no argument.

A path is declared when the datamodel holds it whole or when either declaration surface holds its root segment (11k, 11l).

A block whose type the palette cannot resolve produces nothing here - it already has a :resolution finding from StatifierBlocks.ViewModel, and a block with no schema declares no datamodel path. A field annotated datamodel_path?: true whose value is missing or is not a non-empty string produces nothing either: that is validate_config/1's to refuse, at :error, and an advisory beside it would say the same thing twice in two voices.