flightopsDocumentation
Reference: checks

Review a physical or software change

2 min readdocs/reference/change-review.md (source repository)

flightops review-change works without ROS or a model. It compares two exact configuration snapshots from the history catalog and selects a fixed minimum smoke suite plus checks affected by their differences. Unit, asset and installation identities are separate dimensions. Source/build, driver, firmware, mounting, calibration, clock, QoS, runtime and the other configuration fields retain their provenance. Record network topology within runtime configuration when relevant; a missing measurement is not inferred from filenames or a matching model name.

sh
flightops review-change --base-snapshot base.json --candidate-snapshot candidate.json \
  --check-map reviewed-map.json --expect-map-digest FROZEN_MAP_SHA256 \
  --base-results base-attempts.json --candidate-results candidate-attempts.json \
  -o new-review.json

Snapshot arguments also accept native record IDs in the selected --database. Omit the results arguments to produce only a selection plan. The command never runs checks, executes a proposed repair, deploys software or approves a release.

The flightops.change-check-map/1 document has base_snapshot_id, candidate_snapshot_id, review, checks, minimum_smoke, and dimensions. review contains state: reviewed, a local reviewer declaration and rationale. This is a recorded decision, not authenticated independent review. Each check has id, contract_digest, evaluator_digest, and a nonempty requirement_ids list. minimum_smoke is a nonempty list of those check IDs and cannot be exempted.

Dimension keys are the five identity names or fields.CONFIGURATION_FIELD. Each entry has mode (checks or irrelevant), checks, and a bounded reason. An irrelevant decision needs an empty check list and applies only to this frozen snapshot pair. Unknown facts remain unknown even when explicitly exempted. Otherwise unknown or unmapped impact selects every mapped check, with a visible gap. Identical recorded facts do not establish that an unmeasured device is unchanged. The map's SHA-256 uses the history catalog's canonical JSON, not arbitrary file bytes.

Results use a flightops.change-attempts/1 envelope with an attempts list. Each attempt contains attempt_id, check_id, snapshot_id, execution (completed, failed, interrupted or not_started), and result (a saved integration contract result or null). All supplied attempts remain in the assessment. A result must match the selected snapshot, fixed contract, evaluator and complete requirement set. Malformed or mismatched results remain unknown. Missing checks remain not run. An unresolved baseline prevents an improvement claim; a failed candidate remains visible even alongside interrupted attempts.

A scoped_pass requires all selected candidate attempts to pass and both sides to have fully bound results for every selected check. It covers that selected suite only. Untested checks, unknown dependencies and reviewed unknown exemptions remain visible. The review makes no statistical, paired-condition, hardware-safety, deployment or full-system equivalence claim. Periodic full-suite runs and native acceptance are not part of this command.

API callers use plan_change_review(..., expected_map_digest=...), then assess_change_review(..., expected_plan_digest=...). Preserve the expected digest independently from an imported saved plan. A self-consistent document is not authenticated evidence; source and reviewer trust remain the caller's boundary.