Refactor local InSAR asset and production workflows

docs/PRECISE_ORBIT_PRODUCTION_CONTRACT_20260617.md

@@ -0,0 +1,109 @@
+# Precise Orbit Production Contract 2026-06-17
+
+This document is the current contract for LT-1 and Sentinel-1 precise orbit management. UNC paths are not allowed in active source, orbit, task, or production paths.
+
+## Two Layers
+
+There are two different orbit layers.
+
+`ORBIT_SOURCE_DIRS` is the source asset layer. It is scanned into `orbit_assets` and used for scene-orbit binding:
+
+```env
+ORBIT_SOURCE_DIRS=D:\LT1_data_lsarorbit;D:\Sentinel1_EOF_Pool
+```
+
+`ORBIT_POOL_ENVI` / `PYINT_ORBIT_POOL_TXT` / `GAMMA_SBAS_ORBIT_ROOTS` are LT-1 production orbit pools. They are local TXT pools consumed by ENVI/SARscape and Gamma/PyINT:
+
+```env
+ORBIT_POOL_ENVI=D:\orbit_pools\envi
+PYINT_ORBIT_POOL_TXT=D:\orbit_pools\envi
+GAMMA_SBAS_ORBIT_ROOTS=D:\orbit_pools\envi
+```
+
+Expected LT-1 production layout:
+
+```text
+D:\orbit_pools\envi
+  LT1A\
+    LT1A_GpsData_GAS_C_YYYYMMDD.txt
+  LT1B\
+    LT1B_GpsData_GAS_C_YYYYMMDD.txt
+```
+
+`LT1A` and `LT1B` are satellite names, not product levels.
+
+## Scan Semantics
+
+The active scan entry is `/assets/inventory/scan`.
+
+- `inventory_types=["orbit_asset"], families=["LT1"]` scans LT-1 orbit TXT files.
+- `inventory_types=["orbit_asset"], families=["S1"]` scans Sentinel-1 EOF files.
+- `inventory_types=["orbit_asset"], families=["LT1","S1"]` scans both.
+
+LT-1 scanning recognizes `LT1A_GpsData_GAS_C_YYYYMMDD.txt` and `LT1B_GpsData_GAS_C_YYYYMMDD.txt`.
+
+Sentinel-1 scanning recognizes `S1*_OPER_AUX_*.EOF` and matches EOF validity windows to scene acquisition windows.
+
+After an LT-1 orbit scan, the scanner also synchronizes the LT-1 production TXT pool under `ORBIT_POOL_ENVI`. This keeps Gamma/PyINT and Gamma SBAS able to find the same TXT files without relying on the old monitor scan.
+
+Orbit asset scans are incremental. For already indexed TXT/EOF files, the scanner skips metadata parsing and database upsert when the file path, size, mtime, parser version, active flag, and `parse_status=OK` still match the database record. Missing files are still marked inactive by comparing the scanned `seen_paths` set with existing assets under the same managed root.
+
+## Engine Consumers
+
+ENVI/SARscape D-InSAR:
+
+- Uses local LT-1 data prepared for the SARscape workflow.
+- The LT-1 TXT production pool is `ORBIT_POOL_ENVI`.
+- The pool must be split by satellite because ENVI-side tools expect stable satellite folders.
+
+Gamma/PyINT D-InSAR:
+
+- Reads LT-1 TXT orbit files from `PYINT_ORBIT_POOL_TXT`.
+- Current default keeps `PYINT_ORBIT_POOL_TXT=ORBIT_POOL_ENVI`.
+- For LT-1, input assets may stage TXT orbits into the task input manifest when the precise-orbit bridge is enabled.
+- For Sentinel-1, EOF paths come from source/orbit asset binding or task `orbit` staging.
+
+Gamma SBAS:
+
+- For LT-1, reads TXT orbit roots from `GAMMA_SBAS_ORBIT_ROOTS`.
+- For Sentinel-1, planning uses `ORBIT_SOURCE_DIRS` EOF roots; S1 SBAS execution is not enabled.
+- LT-1 Gamma SBAS scripts use the orbit path recorded in scene discovery.
+
+LandSAR:
+
+- Current D-InSAR integration does not independently scan an orbit pool.
+- It consumes already prepared LT-1 task input.
+- `ORBIT_POOL_LANDSAR` is not an active synchronization target in current code.
+
+ISCE2:
+
+- ISCE2 is retired from the active D-InSAR production path.
+- `ORBIT_POOL_ISCE2` is legacy only and should be empty unless `ISCE2_ENABLED=true`.
+- When `ISCE2_ENABLED=false`, health and orbit status must not treat missing ISCE2 XML as a production error.
+
+## Database State
+
+`orbit_assets` records original orbit files from `ORBIT_SOURCE_DIRS`.
+
+`scene_orbit_bindings` records candidate and selected scene-orbit matches.
+
+`radar_data.selected_orbit_asset_id`, `radar_data.orbit_binding_status`, `radar_data.has_orbit_data`, and `radar_data.orbit_file_path` are compatibility fields for production and search.
+
+`orbit_asset_derivatives` records production-pool derivatives. For current LT-1 TXT production, derivative records use:
+
+```text
+engine_code=lt1_txt_pool
+derivative_format=LT1_TXT
+derivative_role=production_orbit_txt
+pool_path=D:\orbit_pools\envi\LT1A|LT1B\*.txt
+```
+
+## Current Defaults
+
+```env
+ISCE2_ENABLED=false
+ORBIT_POOL_ISCE2=
+ORBIT_POOL_LANDSAR=
+```
+
+The old `/monitor/run-now?target=orbit` path is legacy. It may still synchronize the LT-1 production pool for compatibility, but new UI should use asset inventory orbit scans.