insar-management-system-v2/docs/ISCE2_STABILIZATION_UPDATELOG_20260427.md

ISCE2 Stabilization Update Log

Date: 2026-04-27

Scope

This update hardens the managed ISCE2 LT-1 stripmap D-InSAR production path against large raw DEM reuse, long geocode stalls, and incomplete recovered-run metadata.

Delivered Changes

1. Managed ISCE2 pipeline hardening

• Added --resume-from unwrap|geocode|export support to the LT-1 pipeline.
• Added --full-geocode support. The default path now geocodes only the export-critical products instead of ISCE2's full default list.
• Added stage-aware logging with stdout flush to improve long-run observability.
• Added geocode DEM subset preparation so resumed geocode/export runs do not reprocess the full base DEM.
• Added a guard that blocks fresh runs when the selected DEM resolves to a very large raw base raster without a prepared .wgs84 sibling.

2. Engine and runtime configuration fixes

• ISCE2 now prefers an existing prepared .wgs84 DEM over the raw base path.
• PyINT DEM resolution now follows the same prepared-first preference.
• The WSL ISCE2 runner now passes resume_from and full_geocode through to the pipeline.
• The WSL runner now sets both PROJ_DATA and PROJ_LIB.

3. Recovery and catalog self-healing

• Added a completion-file repair helper for managed ISCE2 runs.
• In-place ISCE2 publish/rebuild now repairs missing:
  • execution_manifest.json
  • current/isce2__<profile>.json
• This allows recovered runs to be reintroduced into the managed result catalog without hand-editing completion markers.

4. One-time DEM preparation tooling

• Added backend/app/isce2_pipeline/prepare_isce2_base_dem.py.
• The script resolves DEM paths from .env, validates existing prepared outputs, and can generate a reusable WGS84 .wgs84 DEM from an EGM96 base DEM.
• The script also auto-configures PROJ paths for standalone execution.

5. Configuration guidance

• Updated .env.example comments to distinguish:
  • raw SARscape/ENVI DEM source path
  • prepared ISCE2/PyINT .wgs84 path

Validation

• Python syntax validation was run for the modified ISCE2 pipeline, engine, runtime, and result-catalog modules.
• The one-time full DEM preparation completed successfully and produced:
  • .wgs84
  • .wgs84.xml
  • .wgs84.vrt
• The prepared DEM metadata was verified to report WGS84.

Required Local Follow-Up

These operational steps are intentionally not committed:

• Point local .env ISCE2_DEM_PATH to the prepared .wgs84 file.
• Point local .env PYINT_PREPARED_DEM_PATH to the same prepared .wgs84 file.
• Restart the backend so the running process reloads the updated .env.

Additional Update: Strict Production Workflow Boundary

After reviewing the ISCE2 production semantics, the export path was tightened so the default managed ISCE2 D-InSAR product remains a strict pipeline result rather than an implicitly corrected interpretation layer.

Delivered adjustments:

• Kept the reference-normalization helper only as an optional debug/export capability.
• Restored the default export behavior to reference_mode=none.
• Removed reference-normalization controls from the regular managed production profile so operators do not treat post-processing heuristics as part of the standard workflow.
• Revalidated the modified pipeline, engine, and WSL runner modules with python3 -m py_compile inside the target WSL runtime environment.