# M1 prepared predictor integration contract


Pending production amendment (2026-09-11): [ADR-0066](../../../../../docs/adrs/ADR-0066-staley-valid-support.md)
and [model selection](model_selection.md) record scalar valid-support estimates,
coverage artifacts and the initial M3 NED13/2022 10 m source requirement.
Existing local tool outputs remain unchanged; scientific composition follows
its own checkpoint after UI/task wiring.

Status: accepted local backend contract, 2026-09-09.

Reuse the [slope/SBS contract](slope_sbs.md), [dNBR contract](dnbr_upload.md),
and [scalar engine](staley2017_engine.md). Write only a fresh caller-owned
local bundle; no NoDb/UI/RQ, upstream rebuild, acquisition or publication.

## Frozen interface and behavior

Accepted 2026-09-09 after owner approval of P02/P03; ADR-0059 governs K policy.
This section froze the local interface before implementation.

`integration.M1Inputs` is a frozen dataclass with required paths `dem`, `mask`,
`outlet` (Point, Feature or single-feature FeatureCollection), `sbs`, required `expected_sha256` path-to-digest mapping,
`wbt_sha256` executable digest, and explicit `source_kind` (`real`, `synthetic`,
`mixed`). Optional paths: `k`, `k_manifest`, `dnbr`, `dnbr_manifest`.
`lineage_sources` is a tuple of explicitly authorized dNBR source paths.
`elevation_units` is `m`; `sbs_alignment` is `exact` (default) or `nearest`.
`build_m1_predictors(inputs, output_dir, *, wbt_executable)` returns the version-1
manifest dictionary. `M1Error.code` carries expected boundary failure reasons.

Inputs are regular nonsymlink trusted local GeoTIFF/JSON files, with expected
SHA-256 for every supplied file, including external `.tif.msk` masks. Internal
masks are honored. A regular `.tif.aux.xml` of at most 64 KiB may contain only
one PAMDataset/PAMRasterBand (band 1)/Metadata tree of nonempty, unique known
STATISTICS_* entries (minimum, maximum, mean, standard deviation, valid percent,
and approximate flag). Reject declarations/entities, unexpected attributes,
other elements, references, georeferencing, NoData, encoding and units. Numeric
statistics must be finite; the approximate flag is YES/NO. An absent sidecar is
valid; empty/malformed sidecars fail explicitly. PAM is disabled during raster
reads, so this validated inert cache never influences samples, support or grid.
This exception applies to trusted local M1 GeoTIFFs, not uploaded source rasters.
Validated statistics caches are excluded from expected SHA-256 and scientific
freshness: appearance, removal or valid statistics refresh cannot alter raster
decoding. Validate a present cache each time the local raster boundary is used;
malformed or meaningful metadata is never treated as inert.
All other auxiliary metadata/overviews and sidecars are rejected. This admits
standard project DEM statistics without weakening meaningful-metadata checks.
The statistics-only exception is implemented under checkpoint `7447e6243`.
JSON is capped at 1 MiB, rasters at 512 MiB and 10 million cells. Decode only
single-band GeoTIFF with identity encoding and pixel-area metadata. The target
DEM/mask/K/dNBR grid is WGS84 UTM with square meter cells; opt-in nearest SBS
preparation admits other finite georeferenced source grids. Reject contradictory vertical units. Unmasked nonfinite DEM/SBS/mask
samples are invalid. Palette SBS uses indices, only 0–3. Lossless WBT copies
use Float64 DEM/mask, Int16 SBS, finite collision-free sentinels, explicit
SampleFormat, classic uncompressed untiled grayscale TIFF. Verify samples,
masks and exact grid after writing. A separate positive-valid binary mask
adapts the existing domain to `summarize_dnbr`. Only explicit nearest SBS
alignment is permitted; K/dNBR never warp. NumPy/GDAL compiled reductions are
existing precedents; owned Rust alone computes Horn and intersections.

S uses the named `k_polaris_nomograph.tif`, multiplier 1, finite [0,1] full
coverage only. K metadata must select Nomograph and name its artifact, retaining
statistic, depth weights, mode/fragment contract and gap-fill policy/summary.
Preserve the whole K section. Missing fields yield unavailable S with
`missing_provenance`; malformed/contradictory metadata fails explicitly.
F requires version-1 normalization manifest, matching raster hash and target
grid, finite positive scale/finite offset, and input hashes checked against
explicit lineage paths. Do not follow arbitrary embedded paths. Unprovided
lineage yields unavailable F; mismatched lineage is an error. Missing optional
raster paths yield `missing_input`. Source hashes prove identity, not controller
freshness. Record production Soils readiness as `not_checked_local`.

Top-level fields: `schema_version` (1), `status` (`complete`, processing only),
`availability` (`complete`, `partial`, `unavailable` by point availability),
`source_kind`, `readiness`, `grid`, `outlet`, `area_km2`, `warnings`, `predictors`
(T/F/S with value, units, status, reason and independent support),
`sources_sha256`, `prepared_sha256`, `tool`, `k_provenance`, `artifacts_sha256`.
T retains WBT summary and lower/upper bounds; its `support.valid_cells` counts
determined intersections, while raw slope/SBS/joint support remains in the WBT
summary. Unknown T uses
`unknown_intersection`; incomplete K uses `incomplete_k_coverage`; empty F uses
`empty_dnbr`. Partial F remains an observed-support estimate. Area warning is
`area_outside_study_range`, outside inclusive 0.2–8 km².

Expected errors: `invalid_input`, `invalid_grid`, `invalid_sbs`,
`invalid_encoding`, `resource_limit`, `missing_provenance`,
`provenance_mismatch`, `source_changed`, `output_exists`, `tool_unavailable`,
`tool_failed`, `invalid_tool_output`, `preparation_failed`. Native filesystem
errors are preserved; malformed JSON is invalid input.

Exclusively reserve a caller-owned visible fresh directory. Retain `incomplete.json` and
partial files on failure; retry elsewhere. `manifest.json` is the final marker,
written after complete readable grid-matching WBT products, consistent summary
counts/bounds, and source/binary hash rechecks. Existing output is never replaced.
Pin binary hash and validate capability; invoke without shell or global cwd
changes, with 300-second timeout and stdout/stderr written to local log files.
Trusted immutable directory ownership is required; this is not hostile-owner
concurrency protection or active run publication.

`evaluate_m1_scenarios(bundle, scenarios)` accepts explicit `(duration_minutes,
rainfall_mm)` pairs and validates through the scalar engine. Return null
probability with `missing_predictors` when any point predictor is unavailable.
Retain source kind/area warnings. No climate default, frequency claim, M3
fallback or probability bounds. Authentic dNBR absence blocks full real-project
acceptance, not independently labeled controlled testing.


## Assessment identity and acceptance evidence

Match the dNBR assessment dates to the selected severity source and record source
lineage explicitly. A project rebuild creates a new source snapshot and fresh
bundle; preserve older results as historical evidence instead of relabeling them.
This prevents pairing a final June 23 assessment with an earlier project's July 1
preliminary imagery. Validate uploaded severity classes and masks against the
prepared SBS when retaining reproduction evidence.

Local complete-source acceptance is demonstrated on rebuilt Wallow: all 12,973
basin cells support T/F/S, with zero unknown intersections. The 11.6757 km² area
warning remains applicable. This validates local composition; live preparation,
publication, upstream freshness and climate ingestion require their own contracts.

Production upload does not request image dates and unknown dates do not block
M1. Compare assessment metadata when available; the user is responsible for
choosing dNBR and soil burn severity from the same fire assessment, as stated
beside the upload. Never infer imagery dates from upload timestamps.
## Scientific integration amendment — 2026-09-14

For new production execution, [the runtime integration contract](production_m3_runtime.md)
and accepted ADR-0067 govern model-specific common support, recorded-depth soil
policy, version-2 predictors and mask publication. Existing local/offline v1
semantics below remain reproducible. Runtime implementation conformance is pending;
the amendment does not authorize source acquisition or production deployment.

## Kf source amendment — 2026-09-16

Status: accepted 2026-09-16 after two independent reviews; implementation
conformance verified on forest, 2026-09-16. The [Kf source/runtime contract](kf_source.md)
is the controlling amendment for new production M1.

New production M1 uses schema 3 and Kf provenance; local/offline v1 and legacy v2 remain readable under their original contracts.
Earlier conflicting requirements remain the historical/legacy contract only
once this checkpoint is accepted; do not reinterpret old accepted artifacts.
