recon_gen.common.variant

Variant matrix primitives — Y.2.gate.m.

The runner expresses test variants as a 3-axis matrix: scenario × dialect × target. Each cell is a VariantSpec, which carries enough information for the chain to set up the right database, seed the right L2 instance, and tag the right AWS resources without collisions across parallel cells.

Naming convention (run-internal only — operators don’t type these except for single-cell triage via --variants=<code>):

<sc>_<di>_<ta> — three short components joined by _.
Scenario codes: sp (spec_example), sq (sasquatch_pr), f<n> (fuzz seed N), us (user-supplied yaml).
Dialect codes: pg (postgres), or (oracle), du (duckdb).
Target codes: lo (local container), aw (AWS / operator’s external Aurora).

Examples: sp_pg_lo, f42_or_lo, us_du_lo, sq_pg_aw.

Invalid cells (handled by VariantSpec.is_valid):

<any>_du_aw — DuckDB is file-based / in-process; QuickSight has no remote DataSource for it.

(us_*_* is matrix-level excluded from expand_full(); not a cell-level invalid — operators can opt in via --scenarios=us:path/foo.yaml and the spec is well-formed.)

Spike source: docs/audits/y_2_gate_m_0_variant_matrix_spike.md (LOCKED 2026-05-08).

Functions

`compose_matrix`([scenarios, dialects, targets])	Compose the variant matrix from sub-flag axis selections.
`derive_default_fuzz_seed`()	Random fuzz seed for the default `full` matrix (and any other fuzz cell that doesn't have a pinned seed).
`expand_full`()	The 13-cell `full` default matrix (spike §"full matrix definition", LOCKED 2026-05-08; CA.7 swapped sl → du; CB.8 + CB.7-followup dropped sl entirely).
`parse_dialects`(arg)	Parse a --dialects= CSV value (e.g., `"pg,or"`) into a typed list.
`parse_scenarios`(arg)	Parse a --scenarios= CSV value into ScenarioSpec list.
`parse_targets`(arg)	Parse a --targets= CSV value (e.g., `"lo,aw"`) into a typed list.
`parse_variant_code`(code)	Parse a single `<sc>_<di>_<ta>` variant code into a VariantSpec.
`partition_matrix`([scenarios, dialects, targets])	m.4.b — return `(valid_cells, skipped_invalid_cells)`.

Classes

`ScenarioSpec`(scenario[, fuzz_seed, user_yaml])	One scenario-axis entry passed to compose_matrix.
`VariantSpec`(scenario, dialect, target[, ...])	One cell of the variant matrix.

class recon_gen.common.variant.ScenarioSpec(scenario, fuzz_seed=None, user_yaml=None)[source]

Bases: object

One scenario-axis entry passed to compose_matrix. Carries the scenario code plus the extras the corresponding VariantSpec construction will need (fuzz_seed for fuzz cells; user_yaml for us cells; both None for named scenarios).

Parameters:

scenario (ScenarioCode)
fuzz_seed (int | None)
user_yaml (Path | None)

fuzz_seed: int | None = None

scenario: ScenarioCode

user_yaml: Path | None = None

class recon_gen.common.variant.VariantSpec(scenario, dialect, target, fuzz_seed=None, user_yaml=None)[source]

Bases: object

One cell of the variant matrix.

Construction is validated: the scenario code must parse + the fuzz_seed / user_yaml fields must agree with the scenario kind. Attempting to construct an invalid spec raises ValueError at the call site (the runner’s m.0 “knows an invalid case” contract for spec-level malformations; cell-level invalids — e.g., du × aw — surface via is_valid instead).

Parameters:

scenario (ScenarioCode)
dialect (Literal['pg', 'or', 'du'])
target (Literal['lo', 'aw'])
fuzz_seed (int | None)
user_yaml (Path | None)

dialect: Literal['pg', 'or', 'du']

fuzz_seed: int | None = None

is_valid()[source]

Cell-level validity. Returns False for known-impossible combinations the matrix expander should skip:

du × aw: DuckDB is file-based / in-process columnar; QuickSight can’t reach it via a remote DataSource.

Spec-level malformations (e.g., scenario doesn’t match fuzz_seed) raise in __post_init__ — those never construct.

Return type:: bool

property name: VariantName

<sc>_<di>_<ta>. Used as artifact dir name (runs/<id>/<variant>/), DB schema prefix discriminator, and AWS resource L2Instance:<variant> tag value.

#729 — return type is VariantName (a NewType("VariantName", str)) so accidental swaps with DialectCode / ScenarioCode / free-form str fail at the call site. NewType is identity at runtime; no overhead.

Type:: Stable variant code

scenario: ScenarioCode

target: Literal['lo', 'aw']

user_yaml: Path | None = None

recon_gen.common.variant.compose_matrix(scenarios=None, dialects=None, targets=None)[source]

Compose the variant matrix from sub-flag axis selections.

Two modes:

All None → returns expand_full() directly (the curated 13-cell default; preserves the fuzz-on-aws + us-opt-in exclusions).
Any axis specified → cross-product mode. Each specified axis takes its given values; unspecified axes default to DEFAULT_SCENARIOS_NAMED / DEFAULT_DIALECTS / DEFAULT_TARGETS. Cross-product is filtered for is_valid() so invalid cells (e.g., du × aw) auto-skip.

Cross-product mode means –dialects=pg alone produces {sp, sq} × {pg} × {lo, aw} = 4 cells (no fuzz — caller would pass an explicit ScenarioSpec for that). This is intentional: sub-flags compose multiplicatively, not subtractively.

Use partition_matrix instead when the caller needs to surface the skipped invalid cells to the operator (m.4.b log line).

Return type:

list[VariantSpec]

Parameters:

scenarios (list[ScenarioSpec] | None)
dialects (list[Literal['pg', 'or', 'du']] | None)
targets (list[Literal['lo', 'aw']] | None)

recon_gen.common.variant.derive_default_fuzz_seed()[source]

Random fuzz seed for the default full matrix (and any other fuzz cell that doesn’t have a pinned seed).

Per audit §7.11 LOCKED + m.0 spike + m.3 PLAN direction: random by default, different per chain invocation. Seed is captured in each cell’s manifest (m.3 wires manifest writes); operator pins via --variants=f<seed>_<di>_<ta> for one-line reproduction.

secrets.randbelow(2**32) rather than random.X: cryptographic RNG, no module-level state, won’t trip the b.15.lint.determinism check on accidental seed-module use.

Return type:: int

recon_gen.common.variant.expand_full()[source]

The 13-cell full default matrix (spike §”full matrix definition”, LOCKED 2026-05-08; CA.7 swapped sl → du; CB.8 + CB.7-followup dropped sl entirely).

Cells:

6 named-scenario × all-dialects × local: {sp, sq} × {pg, or, du} × {lo}
4 named-scenario × non-file-based × aws: {sp, sq} × {pg, or} × {aw}
3 fuzz-seed × all-dialects × local: {f<seed>} × {pg, or, du} × {lo}

The fuzz cells share one random seed across the 3 dialect cells so the same synthesized L2 topology gets exercised on PG / Oracle / DuckDB — cross-dialect coverage on identical input. --scenarios=fuzz:N (m.3 sub-flag composer territory) ramps this to N seeds × |dialect-axis|.

Excluded from default full per spike §”Invalid cells”:

us_*_*: requires operator yaml; opt-in via --scenarios=us:<path>.
Fuzz on aw: cost-control default; reachable via explicit --scenarios=fuzz:N --targets=aw.
<any>_du_aw: invalid cell (caught by is_valid — DuckDB is file-based); never constructed.

Caller-side invariant: every returned spec satisfies is_valid().

Return type:: list[VariantSpec]

recon_gen.common.variant.parse_dialects(arg)[source]

Parse a –dialects= CSV value (e.g., "pg,or") into a typed list. Unknown codes raise.

Return type:: list[Literal['pg', 'or', 'du']]
Parameters:: arg (str)

recon_gen.common.variant.parse_scenarios(arg)[source]

Parse a –scenarios= CSV value into ScenarioSpec list.

Accepts comma-separated entries, each one of:

sp / sq — bare named scenarios.
fuzz — single random fuzz seed (1 cell on the scenario axis).
fuzz:N — N random fuzz seeds (N cells on the scenario axis).
us:<path> — single user-supplied yaml. The path is taken verbatim (caller’s responsibility to verify it exists).

Whitespace around entries is tolerated. Empty values raise.

Examples

"sp,sq" → 2 named ScenarioSpecs "fuzz:3" → 3 fuzz ScenarioSpecs (each with a fresh random seed) "sp,fuzz,us:run/customer.yaml" → 3 ScenarioSpecs (1 named + 1 fuzz + 1 us)

Return type:: list[ScenarioSpec]
Parameters:: arg (str)

recon_gen.common.variant.parse_targets(arg)[source]

Parse a –targets= CSV value (e.g., "lo,aw") into a typed list. Unknown codes raise.

Return type:: list[Literal['lo', 'aw']]
Parameters:: arg (str)

recon_gen.common.variant.parse_variant_code(code)[source]

Parse a single <sc>_<di>_<ta> variant code into a VariantSpec.

Used by the –variants= triage escape hatch — operator copies a code from a failing run’s artifact path (runs/<id>/<code>/) and re-runs just that cell.

us_*_* is rejected here: us cells require operator-supplied yaml, which –variants= doesn’t carry. Operator should use --scenarios=us:<path> instead.

Return type:: VariantSpec
Parameters:: code (str)

recon_gen.common.variant.partition_matrix(scenarios=None, dialects=None, targets=None)[source]

m.4.b — return (valid_cells, skipped_invalid_cells).

Same composition rules as compose_matrix but exposes the cells that fail is_valid() so the runner can log them. The all-None branch returns (expand_full(), []) because expand_full() constructs only valid cells by design (no skip needed).

Return type:

tuple[list[VariantSpec], list[VariantSpec]]

Parameters:

scenarios (list[ScenarioSpec] | None)
dialects (list[Literal['pg', 'or', 'du']] | None)
targets (list[Literal['lo', 'aw']] | None)