Feature: validate TSA29 strict named pipeline against the locked-chain contract

[gparadis]

Summary

Follow-on child under #163 after #168.

Validate the TSA29 strict named pipeline against the latest locked-chain strict result rather than the mutable live recipe.

Why now

• #168 proved that the named-pipeline runner can execute the strict TSA29 lane end to end.
• It did not prove reproducibility against the validated strict contract.
• The current strict named-pipeline smoke landed at 559,967.504 ha, while the locked strict chain records 1,648,497.622 ha and is the governing reference for this validation task.

Acceptance target

• authoritative source is the latest TSA29 locked-chain strict contract;
• first validation target is stepwise + final agreement through step 23; and
• first execution shape is chained restarts first, matching the validated locked-chain result surface.

Scope

• bind strict validation to the locked-chain contract, not the mutable unlocked live recipe;
• detect and fail fast on contract drift between mutable live recipe state and the locked validation contract;
• prove per-step marginal/cumulative agreement and final cumulative agreement for the strict named pipeline; and
• treat the latest locked-chain TSA29 result as the governing correctness target.

Out of scope

• uninterrupted one-shot replay equivalence;
• generic multi-instance strict validation machinery;
• broader named-pipeline registry expansion; and
• reopening #168.

Deliverables

• a clear strict-validation contract surface for TSA29;
• a named-pipeline validation path or runbook that uses that contract; and
• a reproducibility result showing stepwise and final agreement, or a precise fail-fast contract mismatch.

[gparadis]

Bounded #169 slice landed: strict runbook contract binding plus fail-fast enforcement.

What changed:

• added a runbook-level validation_contract block to the named-pipeline runner contract surface;
• updated the checked-in TSA29 strict runbook so it now points at:
  • config/tsr/thlb_locked_chain_ledger.json
  • config/tsr/thlb_reconstruction_comparison.md
  • workbench/tsr/thlb_netdown.locked.recipe.yaml
• taught build_named_pipeline_execution_plan(...) to fail before execution when that validation contract is active but the resolved strict recipe path still points at the mutable live recipe surface.

Why this matters:

• tsr.thlb_strict no longer gets to silently treat the mutable live THLB recipe as if it were the locked validation contract.
• This closes the specific false-confidence seam exposed by the earlier strict smoke.

Validation:

• python -m pytest tests/test_named_pipelines.py -q
• python -m pytest tests/test_cli_main.py -k "pipelines_run" -q
• python -m ruff check src/femic/named_pipelines.py tests/test_named_pipelines.py
• python -m mypy src

What this does not do yet:

• it does not yet prove chained-restart reproduction against the locked-chain result;
• it only enforces the contract boundary so the next slice can work against the correct source of truth.

[gparadis]

Completed bounded slice P53.1d2.

Summary:

• validation_contract.required_recipe_path now binds the THLB recipe path for strict validation runbooks.
• the checked-in TSA29 strict runbook now resolves directly to workbench/tsr/thlb_netdown.locked.recipe.yaml instead of depending on mutable instance-local registry overrides.
• missing required validation recipe files still fail before execution with a targeted error.

Focused validation:

• .\.venv\Scripts\python.exe -m pytest tests/test_named_pipelines.py -q
• .\.venv\Scripts\python.exe -m pytest tests/test_cli_main.py -k "pipelines_run" -q
• .\.venv\Scripts\python.exe -m ruff check src/femic/named_pipelines.py src/femic/cli/main.py tests/test_named_pipelines.py tests/test_cli_main.py
• .\.venv\Scripts\python.exe -m mypy src

Next bounded step:

• use this locked recipe binding as the execution surface for the first chained-restart stepwise comparison against the TSA29 locked-chain ledger.

[gparadis]

Completed bounded slice P53.1d3.

Summary:

• run_named_pipeline_runbook(...) now validates tsa29_locked_chain_strict runs against the locked-chain ledger immediately after execution.
• the validator loads the THLB audit JSON plus the locked ledger, compares per-parent-step marginal and cumulative values through the latest locked row, and raises a contract mismatch on the first divergence.
• successful strict validations now report a compact validation summary so execution success and locked-contract reproduction are separate outcomes.

Focused validation:

• .\.venv\Scripts\python.exe -m pytest tests/test_named_pipelines.py -q
• .\.venv\Scripts\python.exe -m pytest tests/test_cli_main.py -k "pipelines_run" -q
• .\.venv\Scripts\python.exe -m ruff check src/femic/named_pipelines.py src/femic/cli/main.py tests/test_named_pipelines.py tests/test_cli_main.py
• .\.venv\Scripts\python.exe -m mypy src

Next bounded step:

• rerun the checked-in TSA29 strict named pipeline against the locked recipe surface and let the new validator report either a clean locked-chain match or the first parent-step contract mismatch.

[gparadis]

Completed bounded cleanup slice P53.1d5.

Summary:

• active TSA29 THLB/workbench code paths now reject legacy ria_vri_vclr1p_checkpoint*.feather fallback discovery and explicit use.
• step-13 attribute compilation now defaults to data/tsr/lhlb_checkpoint.feather instead of legacy checkpoint7 fallback.
• the stale TSA29 data/ria_vri_vclr1p_checkpoint1..8.feather files plus the old step9 checkpoint1-era TSA29 recipe variants were deleted.
• active TSA29-facing docs now say current strict validation must use explicit validated data/tsr/*.feather seam checkpoints.

Focused validation:

• .\.venv\Scripts\python.exe -m pytest tests/test_tsr_recipes.py -k "find_tsr_checkpoint_path_rejects_tsa29_legacy_fallback or find_curve_ready_thlb_checkpoint_path_rejects_tsa29_legacy_fallback or default_workbench_checkpoint_path_prefers_step13_attribute_checkpoint" -q
• .\.venv\Scripts\python.exe -m pytest tests/test_tsr_step13_attributes.py -q
• .\.venv\Scripts\python.exe -m ruff check src/femic/tsr_catalog/recipes.py src/femic/tsr_catalog/step13_attributes.py src/femic/cli/main.py tests/test_tsr_recipes.py tests/test_tsr_step13_attributes.py
• .\.venv\Scripts\python.exe -m mypy src
• .\.venv\Scripts\python.exe -m sphinx -b html docs _build/html -W

Next bounded step:

• return to P53.1d4 only using the validated strict-lane recipe plus explicit data/tsr/*.feather seam checkpoints as the sole TSA29 basis.

[gparadis]

P53.1d6 progress

Landed the bounded observability slice for femic pipelines run.

What changed:

• run_named_pipeline_runbook(...) now emits always-on line-based runtime events for pipeline start, preflight, validation, finish, and failure, and mirrors them to a dedicated runtime event log under runtime/logs/tsr/.
• run_tsr_thlb_netdown_recipe(...) now accepts a runtime event sink and emits parent-step plus compiled-step start/finish events from both reconstructed and hybrid THLB execution paths.
• LU-parallel reconstructed exclusion work now surfaces parent_step_progress events by replaying the existing per-bundle progress JSON snapshots instead of leaving that signal hidden in runtime files.
• The CLI final summary now reports the mirrored runtime event log path.

Focused validation:

• .\.venv\Scripts\python.exe -m pytest tests/test_named_pipelines.py -q
• .\.venv\Scripts\python.exe -m pytest tests/test_cli_main.py -k "pipelines_run" -q
• .\.venv\Scripts\python.exe -m pytest tests/test_tsr_recipes.py -k "runtime_events or parent_progress" -q
• .\.venv\Scripts\python.exe -m ruff check src/femic/named_pipelines.py src/femic/cli/main.py src/femic/tsr_catalog/recipes.py tests/test_named_pipelines.py tests/test_cli_main.py tests/test_tsr_recipes.py
• .\.venv\Scripts\python.exe -m mypy src

[gparadis]

Implemented P53.1d7 as a strict preflight seam-benchmark gate for the TSA29 locked-chain contract.

What changed:

• run_named_pipeline_runbook(...) now performs a seam-aware preflight before run_tsr_thlb_netdown_recipe(...) when the validation contract is tsa29_locked_chain_strict;
• aflb and aflb_yield_ready are mapped to locked row 5 (thlb_parent_005_analysis_forest_land_base) and are rejected before execution when the explicit data/tsr/*.feather seam checkpoint area already disagrees with the locked-chain reference; and
• scratch now fails with a targeted contract error instead of guessing or consulting any legacy fallback surface.

Runtime observability:

• the live event stream now emits pipeline_validation_preflight_started and, on success, pipeline_validation_preflight_finished with seam/row/expected/actual/delta payloads;
• on failure, pipeline_run_failed now exposes the exact seam benchmark mismatch before any parent-step execution begins.

Focused validation:

• .\.venv\Scripts\python.exe -m pytest tests/test_named_pipelines.py -q
• .\.venv\Scripts\python.exe -m ruff check src/femic/named_pipelines.py tests/test_named_pipelines.py
• .\.venv\Scripts\python.exe -m mypy src

Bounded acceptance run:

• .\.venv\Scripts\python.exe -m femic pipelines run --runbook runbooks/pipelines/tsa29.tsr.thlb_strict.aflb_yield_ready.yaml --instance-root external/femic-tsa29-instance
• result: immediate preflight failure before parent-step execution with:
  • locked row 5 expected area 3110576.671 ha
  • actual aflb_yield_ready checkpoint area 4378802.489 ha
  • delta 1268225.818 ha

This is the intended outcome for this slice: the strict runner now refuses to spend time on a start surface that is already off the validated strict reproduction path.

[gparadis]

Bounded P53.1d8 is complete.

What changed:

• wired tsa29_locked_chain_strict seam scratch to the raw-source GLB builder instead of treating scratch as undefined;
• added the checked-in runbook runbooks/pipelines/tsa29.tsr.thlb_strict.scratch.yaml; and
• made the named-pipeline runner stop after locked row 1 when scratch validation passes, instead of spilling into step 002.

Bounded acceptance run:

• python -m femic pipelines run --runbook runbooks/pipelines/tsa29.tsr.thlb_strict.scratch.yaml --instance-root external/femic-tsa29-instance

Result:

• locked row 1 expected 4933664.212 ha
• actual raw-source GLB 4933664.212 ha
• delta 0.000 ha
• validated_parent_step_count=1
• no downstream THLB step execution; stopped before step 002 as intended.

[gparadis]

P53.1d10 progress:

• rebuilt tsr.thlb_strict so strict transformation steps now execute through a dedicated locked-step executor instead of the old broad per-parent-step runner;
• strict execution now uses only locked parent-step definitions plus locked compiled_logic, approval metadata, and explicit seam/checkpoint inputs;
• milestone rows still validate in place against config/tsr/thlb_locked_chain_ledger.json, and transformation outputs now chain through deterministic checkpoints under data/tsr/strict_chain/.

Focused validation passed:

• python -m pytest tests/test_named_pipelines.py -q
• python -m pytest tests/test_tsr_recipes.py -k "run_tsr_thlb_locked_parent_step_executes_one_locked_step" -q
• python -m pytest tests/test_cli_main.py -k "pipelines_run" -q
• python -m ruff check src/femic/named_pipelines.py src/femic/tsr_catalog/recipes.py src/femic/tsr_catalog/__init__.py tests/test_named_pipelines.py tests/test_tsr_recipes.py
• python -m mypy src
• python -m pre_commit run --all-files

Note on repo-wide validation:

• full pytest is still red in the existing tests/test_tsr_recipes.py cluster tied to the earlier TSA29 legacy-fallback purge and related status-report expectations; this slice did not attempt to repair that broader cluster.

[gparadis]

P53.1d10d progress:

• run_tsr_thlb_locked_parent_step(...) now reuses the existing LU partition/bundle worker machinery instead of forcing one giant serial pass;
• strict bounded transformation steps now emit parent_step_progress from bundle progress files and report execution_mode=lu_parallel with LU chunk/bundle metadata in the strict-step result JSON; and
• the focused strict-step unit test now proves the locked executor uses LU chunk/bundle execution metadata rather than silently falling back to serial mode.

Focused validation passed:

• python -m pytest tests/test_tsr_recipes.py -k "run_tsr_thlb_locked_parent_step_executes_one_locked_step" -q
• python -m pytest tests/test_named_pipelines.py -q
• python -m ruff check src/femic/tsr_catalog/recipes.py tests/test_tsr_recipes.py src/femic/named_pipelines.py tests/test_named_pipelines.py
• python -m mypy src
• python -m pre_commit run --all-files

[gparadis]

Completed P53.1d10f: the strict locked-step executor now reuses the existing CPU-aware reconstructed parallel settings helper instead of defaulting worker count from LU chunk count.

This restores the documented Windows workstation pattern of min(8, cpu_count) workers with bundle count defaulting to worker count, so the glb -> step2 strict run no longer tries to launch one worker per LU chunk.

Focused validation passed:

• python -m pytest tests/test_tsr_recipes.py -k "run_tsr_thlb_locked_parent_step_executes_one_locked_step or run_tsr_thlb_locked_parent_step_uses_cpu_aware_parallel_defaults" -q
• python -m ruff check src/femic/tsr_catalog/recipes.py tests/test_tsr_recipes.py
• python -m mypy src

[gparadis]

Completed P53.1d10g: strict LU cache reuse is now schema-aware.

The strict locked-step executor now passes the current checkpoint column set into _load_cached_landscape_unit_partition_records(...), so stale LU chunk caches are rejected unless they match the active strict-state schema, including _row_id, _stand_area_sqm, thlb_fact, and thlb.

Focused validation passed:

• python -m pytest tests/test_tsr_recipes.py -k "run_tsr_thlb_locked_parent_step_executes_one_locked_step or run_tsr_thlb_locked_parent_step_passes_expected_columns_to_cache_lookup" -q
• python -m ruff check src/femic/tsr_catalog/recipes.py tests/test_tsr_recipes.py
• python -m mypy src

[gparadis]

Bounded row-2 repair update:

• Synced the active TSA29 locked row-2 treaty/title fallback surface to the accepted aspatial_area_reduction contract (191,246 ha).
• Relaxed the strict extent-mismatch guard so reviewed production_full_tsa overlays are no longer blocked just because one LU bundle bbox is smaller than the full-TSA source extent.
• Focused validation passed for the extent guard and row-2 fallback contract.
• Re-ran tsa29.tsr.thlb_strict.glb_to_step2.yaml from the validated GLB seam.

Current row-2 result:

• expected marginal: 696,781.324 ha
• actual marginal: 703,951.222 ha
• marginal delta: +7,169.898 ha
• expected cumulative: 4,236,882.888 ha
• actual cumulative: 4,229,712.990 ha
• cumulative delta: -7,169.898 ha

So row 2 is still not correct yet, but the miss is now down from 187,363.953 ha to 7,169.898 ha, and the bounded glb -> step2 run completes in about 75 seconds instead of stalling.