feat: expose bounded parameter expansion

[k-rister]

Summary

• expose bounded, importable parameter expansion for planner consumers
• provide exact expansion cardinalities and bounded Cartesian prefixes
• serialize shared validation and preset state for thread-safe callers
• add library tests

What this changes for users

This PR adds a programmatic library/API mode; it does not add a new CLI flag, alternate command-line mode, or graphical UI.

The existing Multiplex CLI behavior remains unchanged. New callers such as Rickshaw’s run planner and Crucible’s MCP planning tools can call expand_parameters(...) directly to:

• expand parameters without invoking the CLI or writing files
• bound materialized results with max_results
• receive exact count and truncated metadata
• receive structured ExpansionError failures
• safely use the legacy expansion state from concurrent library callers

Validation

• python -m pytest -q tests — 4 tests passed

This companion change provides the bounded Multiplex APIs consumed by Rickshaw planning and Crucible MCP planning tools.

— AI-signed: Codex | model: GPT-5 | effort: not specified

[atheurer]

The new expand_parameters() API promises structured ExpansionError failures, but a schema-valid document with a set using include and no top-level global-options raises an uncaught KeyError from load_param_sets(). The schema permits this shape because global-options is optional.

Reproducer: multiplex.expand_parameters({"sets": [{"include": "missing"}]}) raises KeyError: "global-options".

Please either treat a missing global-options block as empty or translate it into ExpansionError("invalid_input", ...).

This also makes Rickshaw planner lose the specific failure code and report generic expansion_failed.

[k-rister]

Thanks for the review. Addressed in commit 84980d2.

The importable expand_parameters() API now validates every include reference after schema validation. If the optional global-options block is absent, or a set references an undefined group, the API raises a structured ExpansionError with code invalid_input instead of leaking KeyError("global-options"). This also preserves the specific failure code for Rickshaw callers.

Added a regression test covering the reviewer reproducer:

multiplex.expand_parameters({"sets": [{"include": "missing"}]})

Validation: pytest -q multiplex.py tests/*.py — 109 passed, 5 expected failures.

— AI-signed: Codex | model: GPT-5 | effort: not specified

[atheurer]

The missing global-options case is fixed, but a schema-valid requirements document can still escape the structured API error handling. Calling expand_parameters with a normal x parameter and requirements whose validation vals pattern is an opening parenthesis raises Python re.error (PatternError) instead of ExpansionError. req-schema.json accepts any non-empty string for vals, so invalid regex syntax reaches re.match after schema validation. The adapter currently converts only SystemExit; please translate this path, and ideally other non-SystemExit expansion failures, into ExpansionError (likely invalid_requirements) and add a regression test.

[k-rister]

Addressed the follow-up review in commit a60b1a4.

The importable expand_parameters() API now translates invalid regular expressions in requirements into ExpansionError with code invalid_requirements, instead of leaking Python re.error. Other unexpected expansion exceptions are also converted into structured ExpansionError("expansion_failed", ...) results.

Added regression coverage for a schema-valid requirements document containing an invalid validation regex.

Validation: pytest -q multiplex.py tests/*.py — 110 passed, 5 expected failures.

— AI-signed: Codex | model: GPT-5 | effort: not specified

[atheurer]

The new expand_parameters() API still silently succeeds for malformed transform regexes. transform_param_val() catches re.error from both transform.search and transform.replace, logs it, and returns the original value, so a schema-valid requirements document can return success instead of the promised structured ExpansionError("invalid_requirements", ...).

Reproducer:

multiplex.expand_parameters(
    {"sets": [{"params": [{"arg": "x", "vals": ["value"]}]}]},
    {"validations": {"x": {
        "args": ["x"], "vals": ".*",
        "transform": {"search": "(", "replace": "x"},
    }}},
)

This returns a successful expansion with val: "value". Please validate/propagate transform regex failures through the library API and add regression coverage.

[k-rister]

Addressed the remaining review finding in commit fa3a262.

The library API now validates transform regexes before invoking the legacy expansion pipeline:

• transform.search is compiled explicitly.
• transform.replace is exercised against the compiled pattern so invalid replacement references are detected.
• Malformed transform requirements raise ExpansionError with code invalid_requirements.
• The legacy CLI behavior remains unchanged.

The reviewer’s reproducer now returns a structured invalid_requirements error instead of succeeding with the original untransformed value.

Added regression coverage.

Validation: pytest -q multiplex.py tests/*.py — 111 passed, 5 expected failures.

— AI-signed: Codex | model: GPT-5 | effort: not specified

[atheurer]

Re-reviewed the updated head. The transform-regex error handling is fixed, regression coverage is present, and local validation passes (111 passed, 5 xfailed). GitHub CI is green.