Module discovery_matrix 

Pure planning logic for the discovery-driven request matrix (#501).

A discover: row enumerates a value-set at runtime (build source → drain → project select → dedup); a for_each: [dims] row fans out over the cartesian product of those value-sets, one invocation per tuple.

Everything here is pure (no I/O): projection, dedup, the cartesian product, the per-tuple interpolation context, and the tuple state-key suffix — so the fan-out semantics are unit-testable without a network. The only I/O (running the discovery source) lives in the executor and feeds Dim::values.

Structs

CollectedDim

A collected (list-valued) dimension (#531): a chained discover: row (for_each: [...] + collect: true) that publishes the whole deduped value-set as one list per upstream tuple, keyed by that tuple. A consuming row injects the list into one request (${<id>.<alias>} → comma-joined), rather than fanning out one invocation per element.

Dim

One resolved discovery dimension: the discovery row id, the alias its projected value is exposed under, and the deduped value-set.

Constants

MAX_MATRIX_PRODUCT

Hard ceiling on the number of invocations a single for_each row may expand to. A cartesian product multiplies quickly; above this the run fails rather than silently spawning an unbounded fleet.

Functions

cartesian

Build the cartesian product of the dimensions as per-tuple interpolation contexts. Each context maps dim_id -> { alias: value }, so a token ${dim_id.alias} resolves to that tuple’s value via the same interpolate_record path the parent/child matrix uses. An empty dimension yields no tuples. Pure.

collected_tuple_key

A canonical, symmetric key for one upstream tuple over dims, derived from a per-tuple interpolation context ({dim_id: {alias: value}}). Both the storing side (the chained discovery, over its own for_each dims) and the reading side (a consuming for_each row, whose dims are a superset) compute the same key for the same tuple, so a collected list looks up correctly. Pure.

inject_collected

Enrich a product tuple ctx in place with every collected dimension whose list is available for this tuple, so ${<id>.<alias>} resolves to the list. A collected dim with no entry for the tuple injects an empty list (the consuming request then renders an empty param — the “type has no properties” fallback). Pure.

product_size

The number of invocations dims expands to (the product of the value-set sizes). Returns 0 if any dimension is empty. Saturating, so it never overflows; compare against MAX_MATRIX_PRODUCT. Pure.

project_dedup

Project select (a dot-path, optionally $-prefixed) from each record and dedup the results in first-seen order. null / missing projections are skipped. $ (or "") selects the whole record. Pure.

tuple_state_key_suffix

Stable, collision-resistant state-key suffix for one product tuple, in declared dimension order: alias=value&alias=value…. dims supplies the order + aliases; ctx is one entry from cartesian. Pure.