@spec child_opts(args()) ::
  {:ok, StatifierOban.Invoke.ChildStarter.opts()} | {:error, decode_error()}

Reads a child start job's seam options back off its args.

Returns the keyword list StatifierOban.Invoke.ChildStarter.start_child/5 is handed: [policy: :all] or [policy: :first_error].

A row carrying no "policy" reads as [policy: :all] rather than as an error. :all is the aggregation an absent on parameter means on the way in, so it is what an absent field means on the way out too, and a start job stored before this field existed then starts the child it was always going to start. A "policy" carrying anything else is {:invalid_field, _, _}, on to_invoke/1's rule: a value that is not one of the two words is a fact about the row, and the worker decides what to do with it.

@spec child_position(args()) ::
  {:ok, non_neg_integer(), pos_integer()} | {:error, decode_error()}

Reads a child start job's {index, count} back off its args.

The rules are to_invoke/1's: a missing or malformed field is a typed error about the row rather than a raise, and the worker decides what to do with it. A "child_count" of zero, or an "index" that is not inside it, is {:invalid_field, _, _} for the same reason a negative index would be - the row cannot be a child of any invocation.

@spec for_child_start(
  args(),
  non_neg_integer(),
  pos_integer(),
  StatifierOban.Invoke.ChildStarter.policy()
) :: args()

Widens an invoke job's args into a fan-out child start job's args.

A child start job carries the whole invocation - the same fields from_invoke/4 laid out, opaque payloads and codec tag included, so the starter seam is handed the effect the planning callback saw - plus the three values that say which child of which fan-out it is:

• "index" is the item's zero-based position in the fanned-out list. It rides at the top level because it is a key component: StatifierOban.Invoke.ChildStartWorker is unique on the four-component {scope, invoke_id, macrostep, index} (ADR-0007 decision 4), and Oban's uniqueness keys read args at the top level.
• "child_count" is the list's length, and is row data rather than a key component - two starts of the same index under the same invocation are the same scheduling decision whatever the count says. It travels because the seam's callback takes it: a starter that records the child's slot needs to know how many slots there are, and re-deriving it later would mean re-reading the parent.
• "policy" is the invocation's aggregation policy as its wire word, "all" or "first_error". It is row data for the same reason "child_count" is, and it travels for a sharper one: the settlement side records the policy on each child's own linkage at creation, so the value has to reach StatifierOban.Invoke.ChildStarter.start_child/5 at every index rather than be looked up once.

The policy is one of two constants rather than an arbitrary term, so it is written as itself and read back by child_opts/1; nothing here goes through the opaque-term codec.

@spec from_invoke(String.t(), module(), Statifier.Effect.Invoke.t(), module() | nil) ::
  {:ok, args()} | {:error, encode_error()}

Builds the args map for an invoke job from the scope, the handler module, and the effect.

The caller (StatifierOban.Invoke.Handler.perform_start/3) has already validated the scope; this function only lays fields out on the wire. params and content are encoded through a with, so the first codec failure short-circuits and no partially-encoded args map is ever returned.

@spec identity(args()) :: {:ok, String.t(), String.t()} | {:error, decode_error()}

Rebuilds just the identity pair - the scope and the invoke id - from a job's args.

to_invoke/1 fails the whole row when any field is undecodable, including the two host-opaque payloads, which is the common way a row goes bad. This reads only the two plain-string fields that name the invocation, so a caller holding an otherwise undecodable row can still tell the run which invocation it is about (StatifierOban.Invoke.Worker delivers error.communication that way before cancelling). The rules are to_invoke/1's own, because this is the same fetch_binary/2: a missing, empty, or non-string field is a typed error, and then the row names nothing and there is nobody to tell.

@spec to_invoke(args()) ::
  {:ok, String.t(), String.t(), Statifier.Effect.Invoke.t()}
  | {:error, decode_error()}

Rebuilds the scope, the handler module name, and the %Statifier.Effect.Invoke{} from a job's args.

The handler comes back as the stored string, not a resolved module: resolution is the worker's call, because an unresolvable name is a retryable environment fact where every error here is a fact about the row. Returns a typed error rather than raising: an undecodable job is a fact about the row, and the worker decides what to do with it.