Give Python callers the findings the CLI already prints (#104)

[jeremymanning]

Review item 4. Merge after #480 — this branch is stacked on it, so its diff includes #480's commit until that lands.

The gap

orchestrator validate --json has emitted structured findings since #467. PipelineAPI.validate_yaml returns a bare bool, so a caller embedding the orchestrator could learn that a document was rejected and nothing about why — and could not see warnings at all, which is where "this reference could not be checked" lives: the warning that precedes the run-time failure in #465.

The findings were never missing, only private to cli.py (_reportable_issues, _issue_payload).

Why this is a move, not an addition

Writing a second implementation for the API would have created two things to drift apart — the bug #466 removed for dependencies. validation/pipeline_report.py is the one implementation; the CLI now formats what it returns, and its private helpers are deleted. test_the_cli_and_the_api_report_the_same_findings compares the CLI's JSON against the API's objects to keep it that way.

Exported from the package: validate_pipeline_file, validate_pipeline_text, PipelineValidation, Finding.

Compilation failure is a result, not an exception: a caller validating user input wants the findings alongside the failure, and raising discards them at the moment they are most useful.

orchestrator validate was not reproducible

Your list asked for deterministic warning order. It wasn't:

5f5b24bbc1e0
31dae9338721   ← same command, same file, three runs
b882273628de

Same 44 findings, three orders. Two hash-order sources:

1. findings emitted while iterating set(var_names) | set(loop_var_matches);
2. _suggest_similar_names iterating an unsorted candidate list and truncating to three — so on a longer list it would have offered genuinely different suggestions run to run, not merely reordered ones.

Both sorted. Three separate processes now produce byte-identical output.

Two of my own tests proved nothing

Reporting these because they are the reason to trust the rest:

• The suite was first written against examples/supported/01_hello_filesystem.yaml, which produces no findings. Deleting every warning from the implementation still passed all seven tests — a suite for "warnings reach the API" that could not detect warnings never arriving. It is now anchored on a document carrying 44 findings, with explicit assert result.findings guards so an empty list cannot pass as agreement.
• The determinism test ran in one process, where PYTHONHASHSEED is fixed, and passed while the CLI visibly varied. The real check runs three subprocesses.

Neither was caught by rereading the tests; both were caught by mutating the implementation and checking that a test failed.

Verification

• ruff check src/orchestrator --select E9,F63,F7,F82,F821,F823,F601,F811 — clean
• Full blocking suite — 1027 passed, 13 skipped
• Catalogue — all 52 listed examples still validate
• Determinism — 3 separate processes, identical digests
• Three mutations, each caught: warnings dropped from findings; unsorted variable iteration; unsorted suggestion candidates

Gates were re-run on the rebased branch in an isolated git worktree, after an earlier post-rebase run was invalidated by the shared checkout switching branches mid-run.