lardon3d/docs/architecture/calibration_workflow.md

Calibration Workflow

Status

CALIBRATION_WORKFLOW=IN_PROGRESS
CALIBRATION_WORKFLOW_INPUT_BOUNDARY_V1=PASS/FROZEN
CURRENT_WORKFLOW_NEXT=EVIDENCE_MATERIALIZATION_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.

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_EVIDENCE_MATERIALIZATION_V1

The next stage parses the already validated bundle into bounded in-memory Science v1 evidence:

• exact per-view evidence;
• exact repeated full-solve parameters;
• fit parameters;
• global and hold-out validation metrics;
• coordinate-equivalence evidence;
• immutable provenance digests.

It still performs no Project DB mutation.

Only after that boundary passes may the workflow bind the exact selected execution, campaign representations and optical assignments and invoke the FROZEN Tooling/Bootstrap path.