lardon3d/docs/architecture/calibration_workflow.md

Calibration Workflow

Status

CALIBRATION_WORKFLOW=IN_PROGRESS
CALIBRATION_WORKFLOW_INPUT_BOUNDARY_V1=PASS/FROZEN
CALIBRATION_WORKFLOW_EVIDENCE_MATERIALIZATION_V1=PASS/FROZEN
CURRENT_WORKFLOW_NEXT=SELECTED_EXECUTION_BINDING_V1

Authority

Calibration Science v1, Calibration Tooling v1 and Calibration Bootstrap v1 remain FROZEN scientific and import authorities.

This workflow is bounded orchestration only. It does not introduce a solver, Project DB schema version, Task kind, Sparse SfM execution or reconstructed scientific evidence.

Frozen flow

physical calibration acquisition
-> session.l3dcal
-> external Calibration Evidence Solver v1
-> immutable solver bundle
-> campaign-state evidence
-> Calibration Workflow
-> Calibration Tooling v1
-> L3DCALB1 v1
-> Calibration Bootstrap v1
-> selected execution READY

Input Boundary v1

CALIBRATION_WORKFLOW_INPUT_BOUNDARY_V1=PASS/FROZEN.

The implementation is exposed through:

include/lardon3d/calibration_workflow.h
src/calibration_workflow.cpp

Input Boundary v1 performs no Project DB mutation.

It accepts only bounded regular files and rejects special files and symlinks before potentially blocking reads. File access follows the nonblocking, close-on-exec regular-file discipline.

The bounded input set is:

session.l3dcal
session.l3dcal.bundle/detection.json
session.l3dcal.bundle/solve.json
session.l3dcal.bundle/evidence.json
session.l3dcal.bundle/producer.json
L3DCAL_CAMPAIGN_STATE_V1

It verifies:

• regular bounded files;
• SHA-256 identities;
• strict session syntax;
• structurally valid canonical JSON bundle members;
• exact session SHA binding through producer.json;
• decoder/version consistency;
• exact optical-state SHA equality;
• exact optical-state token equality;
• campaign-state identity consistency.

Malformed JSON, oversize files, symlinks, FIFOs, session digest mismatch and optical-state mismatch are rejected.

Input Boundary v1 does not:

• open or mutate Project DB;
• construct Lardon3DCalibrationToolingEvidence;
• call Calibration Tooling;
• produce L3DCALB1;
• invoke Calibration Bootstrap;
• change selected-execution state.

Evidence Materialization v1

CALIBRATION_WORKFLOW_EVIDENCE_MATERIALIZATION_V1=PASS/FROZEN.

The implementation is additive:

src/calibration_workflow_materialize.cpp
tests/test_calibration_workflow_materialize.cpp

It consumes only inputs that first pass Input Boundary v1 and performs no Project DB access or mutation.

The caller owns bounded arrays for materialized views and coordinate checks. On success the output borrows those arrays and retains:

• exact target generator SHA-256 and physical target measurements;
• measured white border and categorical planarity evidence;
• exact optical-state SHA-256;
• exact solver executable and configuration SHA-256;
• exact accepted/rejected per-view classifications and rejection reasons;
• hold-out assignment, frame region, distance band and target coverage;
• retained per-view residual counts and metrics;
• coordinate-equivalence checks derived from the retained session points;
• all three exact full-solve parameter vectors;
• exact fit parameter vector;
• support image/observation counts;
• global RMSE, maximum residual and high-residual fraction;
• hold-out RMSE and maximum residual;
• maximum parameter delta and validation_flags=0x0f.

The stage consumes published solver evidence; it does not reclassify views, rerun calibration, average repeated solves or manufacture missing values.

initialization_evidence_sha256 is the exact session.l3dcal SHA-256.

validation_evidence_sha256 is deterministic and domain separated:

SHA256(
  ASCII("L3DCAL_WORKFLOW_VALIDATION_V1\n")
  || detection_sha256_raw32
  || solve_sha256_raw32
  || evidence_sha256_raw32
  || producer_sha256_raw32
)

This boundary deliberately does not construct per-campaign Lardon3DCalibrationToolingEntry rows. Those rows require Project DB proof of the selected image identities, representation bytes/dimensions and explicit Capture optical assignments, which belongs to Selected Execution Binding v1.

Campaign optical-state evidence

Project DB v23 retains exact explicit optical configuration identity, including body, objective and focal state, but Calibration Science v1 requires a broader scientific key including focus, stabilization and processing/decode state.

No equality may be inferred between those domains.

L3DCAL_CAMPAIGN_STATE_V1 therefore provides immutable external evidence for the complete Science v1 optical state. A later coordinator stage must verify this evidence against both the calibration session and each selected Capture's explicit Project DB optical configuration.

Absence or disagreement remains CALIBRATION_UNAVAILABLE.

Current next boundary

CALIBRATION_WORKFLOW_SELECTED_EXECUTION_BINDING_V1

The next stage may read Project DB, but must not mutate it. It must:

• load the exact selected execution and require the calibration/ready stage appropriate to the existing FROZEN contract;
• require exact selected item count and order;
• match every campaign-state Capture row to the selected item;
• load each Capture's explicit v23 optical assignment and require the exact declared optical configuration;
• load every selected image/asset identity;
• read the exact managed representation as a bounded regular file;
• require asset byte size and SHA-256 equality;
• decode the exact geometric representation and require oriented dimensions compatible with the calibration evidence;
• construct the per-image Lardon3DCalibrationToolingEntry rows without changing any scientific value.

Only after that read-only binding passes may a final workflow boundary invoke the FROZEN Tooling/Bootstrap path and transition the selected execution to truthful READY.