@photivra/engine 1.4.0 → 2.0.0

package/dist/composition/image-formation-plan.js

@@ -1,26 +1,23 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary. The planner owns
- * scientific stage ordering, immutable capture identity and reproducibility. Well-formed unsupported
- * combinations produce structured blockers; malformed declarations throw. The bounded environment
- * route executes supplied radiance through native RAW and optional output, while sample-only and
- * attached-RAW routes retain missing upstream blockers. FNV fingerprints are reproducibility keys, not
- * cryptographic integrity proofs.
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary. The planner owns
- * scientific stage ordering, immutable capture identity and reproducibility. Well-formed unsupported
- * combinations produce structured blockers; malformed declarations throw. The bounded environment
- * route executes supplied radiance through native RAW and optional output, while sample-only and
- * attached-RAW routes retain missing upstream blockers. FNV fingerprints are reproducibility keys, not
- * cryptographic integrity proofs.
- * @see docs/PRODUCTION_ENVIRONMENT_CAPTURE.md for equations, coordinate/unit conventions, blockers and
- * support limits.
+ * The production image-formation plan: the ordered list of scientific stages that turns a scene into
+ * a capture, and the record of which stages ran.
+ *
+ * The parsers validate untrusted input and return the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data are rejected.
+ *
+ * The planner decides the order of the scientific stages, fixes each capture's identity so it cannot
+ * change, and makes results reproducible. A well-formed but unsupported combination returns
+ * structured blockers. A malformed declaration throws. The bounded environment route runs the
+ * supplied radiance through native RAW and, optionally, output processing. The sample-only and
+ * attached-RAW routes keep blockers for the upstream stages they lack. FNV fingerprints are keys for
+ * reproducibility, not cryptographic proof of integrity.
+ * @see docs/PRODUCTION_ENVIRONMENT_CAPTURE.md for the equations, units, coordinate conventions, known
+ * blockers and support limits.
  */
 import { simulateEnvironmentSensorRawFrame } from "../capture/environment-raw-producer.js";
 import { parseSimulatedCapture } from "../capture/simulated-capture.js";
-import { calculateProcessedSensorRaw, validateProcessedSensorRawEnvelope } from "../capture/photographic-export.js";
+import { calculateProcessedSensorRaw, validateProcessedSensorRawEnvelope, PROCESSED_SENSOR_RAW_MODEL_VERSION } from "../capture/photographic-export.js";
 import { stringifyCanonicalJson } from "../core/canonical-json.js";
 import { RELEASE_SEQUENCE_VERSION } from "../capture/release-sequence.js";
 import { parseResolvedWhiteBalanceState } from "../color/white-balance.js";
@@ -29,6 +26,8 @@ import { getImageFormationContract, IMAGE_FORMATION_CONTRACT_VERSION } from "../
 import { ENGINE_API_VERSION } from "../core/version.js";
 import { SCIENTIFIC_ASSURANCE_CONTRACT_VERSION, composeScientificAssurance } from "../core/scientific-assurance.js";
 import { InvalidScientificInputError } from "../core/validation.js";
+import { parseEvidenceList } from "../core/evidence-provenance.js";
+import { isElectronicRollingShutterExposureSchedule } from "../sensor/readout-exposure-linkage.js";
 import { calculateCaptureRotationTemporalQuadrature } from "../motion/capture-rotation-temporal-quadrature.js";
 import { calculateCaptureExposureWindows } from "../sensor/exposure-window.js";
 import { calculateSensorReadoutTiming } from "../sensor/readout-timing.js";
@@ -37,6 +36,7 @@ import { parseFrontOfLensFilterProfile, resolveFrontOfLensFilterTransmission } f
 import { parseFocusPlane } from "../optics/focus-state.js";
 import { calculateSceneRadianceToSensorIrradiance, parseSceneToSensorIrradianceProfile } from "../optics/scene-to-sensor-irradiance.js";
 import { parseSceneRadianceEvaluationRequest, parseSceneRadianceEvaluationResult } from "../schema/scene-radiance.js";
+import { requireInputObject, requireInputKeys, rejectUnknownFields, rejectUnknownVariantFields } from "../core/record-validation.js";
 export const PRODUCTION_IMAGE_FORMATION_PLAN_VERSION = "0.7.0";
 export const PREPARED_IMAGE_FORMATION_CONTEXT_VERSION = "0.1.0";
 export const PRODUCTION_CAPTURE_SNAPSHOT_VERSION = "0.3.0";
@@ -53,15 +53,18 @@ const COMPOSER_SUPPORTED_STAGES = new Set([
 ]);
 const COMPOSER_SUPPORTED_EFFECTS = new Set([
     "illumination-vignetting",
+    "geometric-distortion",
     "spatial-camera-rotation",
     "rolling-readout"
 ]);
-function requireRecord(value, path) {
+function requireRecord(value, path, allowedKeys) {
     if (typeof value !== "object" ||
         value === null ||
         Array.isArray(value)) {
         throw new InvalidConfigurationError(path + " must be an object.");
     }
+    if (allowedKeys !== null)
+        rejectUnknownFields(value, allowedKeys, path);
     return value;
 }
 function requireNonEmptyString(value, path) {
@@ -157,21 +160,22 @@ function parseUniqueEffectIds(value, path) {
         .filter((effectId) => seen.has(effectId));
 }
 /**
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary.
+ * Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data are rejected here.
  *
- * The planner owns scientific stage ordering, immutable capture identity and reproducibility.
- * Well-formed unsupported combinations produce structured blockers; malformed declarations throw. The
- * bounded environment route executes supplied radiance through native RAW and optional output, while
- * sample-only and attached-RAW routes retain missing upstream blockers. FNV fingerprints are
- * reproducibility keys, not cryptographic integrity proofs.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns RendererCapabilityDeclaration. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * The planner decides the order of the scientific stages, fixes each capture's identity so it cannot
+ * change, and makes results reproducible. A well-formed but unsupported combination returns
+ * structured blockers. A malformed declaration throws. The bounded environment route runs the
+ * supplied radiance through native RAW and, optionally, output processing. The sample-only and
+ * attached-RAW routes keep blockers for the upstream stages they lack. FNV fingerprints are keys for
+ * reproducibility, not cryptographic proof of integrity.
+ * @param value - unknown. Untrusted input; TypeScript types alone are not validation.
+ * @returns RendererCapabilityDeclaration. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export function parseRendererCapabilityDeclaration(value) {
-    const record = requireRecord(value, "rendererCapability");
+    const record = requireRecord(value, "rendererCapability", ["schemaVersion", "consumerKind", "spectralCapability", "temporalSampling", "depthCapability", "alphaRepresentation", "inverseFieldMapping", "preservesDepthOrderAcrossWarps", "sensorDomainProcessing", "rendererId", "rendererVersion", "supportedStages", "supportedEffects"]);
     if (record.schemaVersion !==
         RENDERER_CAPABILITY_SCHEMA_VERSION) {
         throw new InvalidConfigurationError('rendererCapability.schemaVersion must be "' +
@@ -191,7 +195,8 @@ export function parseRendererCapabilityDeclaration(value) {
             "wavelength-independent-approximation") {
         throw new InvalidConfigurationError("rendererCapability.spectralCapability is invalid.");
     }
-    const temporal = requireRecord(record.temporalSampling, "rendererCapability.temporalSampling");
+    const temporal = requireRecord(record.temporalSampling, "rendererCapability.temporalSampling", null);
+    rejectUnknownVariantFields(temporal, "kind", { none: ["kind"], bounded: ["kind", "maximumSamples"] }, "rendererCapability.temporalSampling");
     let temporalSampling;
     if (temporal.kind === "none") {
         temporalSampling = {
@@ -267,21 +272,22 @@ export function parseRendererCapabilityDeclaration(value) {
     };
 }
 /**
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary.
+ * Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data are rejected here.
  *
- * The planner owns scientific stage ordering, immutable capture identity and reproducibility.
- * Well-formed unsupported combinations produce structured blockers; malformed declarations throw. The
- * bounded environment route executes supplied radiance through native RAW and optional output, while
- * sample-only and attached-RAW routes retain missing upstream blockers. FNV fingerprints are
- * reproducibility keys, not cryptographic integrity proofs.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns ImageFormationFidelityProfile. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * The planner decides the order of the scientific stages, fixes each capture's identity so it cannot
+ * change, and makes results reproducible. A well-formed but unsupported combination returns
+ * structured blockers. A malformed declaration throws. The bounded environment route runs the
+ * supplied radiance through native RAW and, optionally, output processing. The sample-only and
+ * attached-RAW routes keep blockers for the upstream stages they lack. FNV fingerprints are keys for
+ * reproducibility, not cryptographic proof of integrity.
+ * @param value - unknown. Untrusted input; TypeScript types alone are not validation.
+ * @returns ImageFormationFidelityProfile. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export function parseImageFormationFidelityProfile(value) {
-    const record = requireRecord(value, "imageFormationFidelityProfile");
+    const record = requireRecord(value, "imageFormationFidelityProfile", ["schemaVersion", "requiredEffects", "rendererRequirements", "profileId", "profileVersion", "requiredStages"]);
     if (record.schemaVersion !==
         IMAGE_FORMATION_FIDELITY_PROFILE_SCHEMA_VERSION) {
         throw new InvalidConfigurationError('imageFormationFidelityProfile.schemaVersion must be "' +
@@ -297,7 +303,7 @@ export function parseImageFormationFidelityProfile(value) {
         const path = "imageFormationFidelityProfile.requiredEffects[" +
             index +
             "]";
-        const effect = requireRecord(entry, path);
+        const effect = requireRecord(entry, path, ["effectId", "modelId", "modelVersion"]);
         const effectId = effect.effectId;
         if (typeof effectId !==
             "string" ||
@@ -326,7 +332,7 @@ export function parseImageFormationFidelityProfile(value) {
         ...requestedEffects
     ].sort((left, right) => (effectOrder.get(left.effectId) ?? 0) -
         (effectOrder.get(right.effectId) ?? 0));
-    const requirements = requireRecord(record.rendererRequirements, "imageFormationFidelityProfile.rendererRequirements");
+    const requirements = requireRecord(record.rendererRequirements, "imageFormationFidelityProfile.rendererRequirements", ["spectral", "sensorDomainProcessing", "depth"]);
     const spectral = requirements.spectral;
     if (spectral !==
         "wavelength-resolved" &&
@@ -359,6 +365,7 @@ export function parseImageFormationFidelityProfile(value) {
     };
 }
 function validateEquipmentCapabilities(value) {
+    requireInputObject(value, "value input");
     if (value.schemaVersion !==
         GENERIC_EQUIPMENT_EXPOSURE_CAPABILITY_SCHEMA_VERSION ||
         value.scientificStatus !==
@@ -436,39 +443,65 @@ function fingerprintText(text) {
 function fingerprintValue(value) {
     return fingerprintText(canonicalStringify(value));
 }
+/** Top-level fields of `ProductionImageFormationPlan`. */
+const PRODUCTION_PLAN_FIELDS = ["version", "status", "versions", "contextIdentity", "captureIdentity", "rendererIdentity",
+    "fidelityIdentity", "stagePlan", "effectPlan", "blockers", "environmentCaptureRequestFingerprint", "environmentCaptureResult",
+    "processedOutputResult", "physicalSceneToSensorResult", "temporalCaptureResult", "scientificAssurance", "stochastic",
+    "immutableCaptureSnapshot", "legacyPocModified", "fingerprint"];
 /**
- * Return deterministic canonical JSON of a validated production plan. Sorted object keys preserve
- * array order; the representation contains data and excludes executable provider callbacks.
+ * Returns deterministic canonical JSON for a validated production plan. Object keys are sorted;
+ * array order is kept. The JSON holds data only and leaves out provider callbacks. The plan version
+ * and its fingerprint (recomputed over the content) must match, so an empty or edited object is
+ * rejected instead of serialized.
  *
- * The planner owns scientific stage ordering, immutable capture identity and reproducibility.
- * Well-formed unsupported combinations produce structured blockers; malformed declarations throw. The
- * bounded environment route executes supplied radiance through native RAW and optional output, while
- * sample-only and attached-RAW routes retain missing upstream blockers. FNV fingerprints are
- * reproducibility keys, not cryptographic integrity proofs.
- * @param plan - ProductionImageFormationPlan. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns string. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * The planner decides the order of the scientific stages, fixes each capture's identity so it cannot
+ * change, and makes results reproducible. A well-formed but unsupported combination returns
+ * structured blockers. A malformed declaration throws. The bounded environment route runs the
+ * supplied radiance through native RAW and, optionally, output processing. The sample-only and
+ * attached-RAW routes keep blockers for the upstream stages they lack. FNV fingerprints are keys for
+ * reproducibility, not cryptographic proof of integrity.
+ * @param plan - ProductionImageFormationPlan. See that type for coordinates, units and profile binding.
+ * @returns string. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export function serializeProductionImageFormationPlan(plan) {
+    requireInputObject(plan, "serializeProductionImageFormationPlan input");
+    // 2.0.0: unknown top-level and fingerprint fields are named. Nested content is bound by the recomputed fingerprint.
+    rejectUnknownFields(plan, PRODUCTION_PLAN_FIELDS, "productionImageFormationPlan");
+    const { fingerprint, ...core } = plan;
+    if (isPlainObjectValue(fingerprint)) {
+        rejectUnknownFields(fingerprint, ["algorithm", "value", "purpose"], "productionImageFormationPlan.fingerprint");
+    }
+    if (core.version !== PRODUCTION_IMAGE_FORMATION_PLAN_VERSION) {
+        throw new InvalidConfigurationError(`Production plan version must be "${PRODUCTION_IMAGE_FORMATION_PLAN_VERSION}".`);
+    }
+    const supplied = fingerprint;
+    if (typeof supplied !== "object" || supplied === null ||
+        supplied.algorithm !== "fnv1a-32-non-cryptographic" ||
+        supplied.purpose !== "deterministic-reproducibility-key-not-integrity-security" ||
+        supplied.value !== fingerprintValue(core)) {
+        throw new InvalidConfigurationError("Production plan fingerprint does not match its content; serialize only a plan returned by createProductionImageFormationPlan.");
+    }
     return canonicalStringify(plan);
 }
 /**
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary.
+ * Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data are rejected here.
  *
- * The planner owns scientific stage ordering, immutable capture identity and reproducibility.
- * Well-formed unsupported combinations produce structured blockers; malformed declarations throw. The
- * bounded environment route executes supplied radiance through native RAW and optional output, while
- * sample-only and attached-RAW routes retain missing upstream blockers. FNV fingerprints are
- * reproducibility keys, not cryptographic integrity proofs.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns PreparedImageFormationContext. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * The planner decides the order of the scientific stages, fixes each capture's identity so it cannot
+ * change, and makes results reproducible. A well-formed but unsupported combination returns
+ * structured blockers. A malformed declaration throws. The bounded environment route runs the
+ * supplied radiance through native RAW and, optionally, output processing. The sample-only and
+ * attached-RAW routes keep blockers for the upstream stages they lack. FNV fingerprints are keys for
+ * reproducibility, not cryptographic proof of integrity.
+ * @param value - unknown. Untrusted input; TypeScript types alone are not validation.
+ * @returns PreparedImageFormationContext. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export function parsePreparedImageFormationContext(value) {
-    const record = requireRecord(value, "preparedImageFormationContext");
+    const record = requireRecord(value, "preparedImageFormationContext", ["version", "contextId", "sceneId", "sceneRadianceProviderProfileId", "outputGeometryProfileId", "equipmentCapabilities", "opticalBridgeProfile", "renderer", "fidelity", "fingerprint"]);
     if (record.version !==
         PREPARED_IMAGE_FORMATION_CONTEXT_VERSION) {
         throw new InvalidConfigurationError('preparedImageFormationContext.version must be "' +
@@ -500,7 +533,7 @@ export function parsePreparedImageFormationContext(value) {
         record.fingerprint === null) {
         throw new InvalidConfigurationError("preparedImageFormationContext.fingerprint must be present.");
     }
-    const supplied = requireRecord(record.fingerprint, "preparedImageFormationContext.fingerprint");
+    const supplied = requireRecord(record.fingerprint, "preparedImageFormationContext.fingerprint", ["algorithm", "value"]);
     if (supplied.algorithm !==
         "fnv1a-32-non-cryptographic" ||
         supplied.value !==
@@ -510,20 +543,23 @@ export function parsePreparedImageFormationContext(value) {
     return parsed;
 }
 /**
- * Parse, own and freeze relatively static equipment, scene, renderer and fidelity declarations for
- * reuse by later immutable captures. This prepares semantic state and does not render a frame.
+ * Parses, copies and freezes the declarations that change rarely (equipment, scene, renderer and
+ * fidelity), so later immutable captures can reuse them. This prepares state; it does not render a
+ * frame.
  *
- * The planner owns scientific stage ordering, immutable capture identity and reproducibility.
- * Well-formed unsupported combinations produce structured blockers; malformed declarations throw. The
- * bounded environment route executes supplied radiance through native RAW and optional output, while
- * sample-only and attached-RAW routes retain missing upstream blockers. FNV fingerprints are
- * reproducibility keys, not cryptographic integrity proofs.
- * @param input - PrepareImageFormationContextInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns PreparedImageFormationContext. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * The planner decides the order of the scientific stages, fixes each capture's identity so it cannot
+ * change, and makes results reproducible. A well-formed but unsupported combination returns
+ * structured blockers. A malformed declaration throws. The bounded environment route runs the
+ * supplied radiance through native RAW and, optionally, output processing. The sample-only and
+ * attached-RAW routes keep blockers for the upstream stages they lack. FNV fingerprints are keys for
+ * reproducibility, not cryptographic proof of integrity.
+ * @param input - PrepareImageFormationContextInput. See that type for coordinates, units and profile binding.
+ * @returns PreparedImageFormationContext. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export function prepareImageFormationContext(input) {
+    requireInputKeys(input, "prepareImageFormationContext", ["contextId", "sceneId", "sceneRadianceProviderProfileId", "outputGeometryProfileId", "equipmentCapabilities", "opticalBridgeProfile", "renderer", "fidelity", "version", "fingerprint"]);
     validateEquipmentCapabilities(input.equipmentCapabilities);
     const renderer = parseRendererCapabilityDeclaration(input.renderer);
     const fidelity = parseImageFormationFidelityProfile(input.fidelity);
@@ -568,7 +604,41 @@ export function prepareImageFormationContext(input) {
     };
     return deepFreeze(cloneJson(prepared));
 }
+/**
+ * Rejects unknown fields in the optical-bridge focus and field-throughput declarations carried by a
+ * physical scene sample. Values that are not objects are left to the optical bridge, which reports
+ * them; the vignetting `result` is an engine result and is checked where it is used.
+ */
+function rejectUnknownOpticalBridgeFields(focus, fieldThroughput, path) {
+    if (isPlainObjectValue(focus)) {
+        rejectUnknownVariantFields(focus, "kind", {
+            "infinity-focus": ["kind"],
+            "ideal-symmetric-thin-lens": ["kind", "objectDistanceM", "pupilMagnificationAssumption"],
+            "supplied-working-f-number": ["kind", "focus", "workingFNumber", "basis"]
+        }, path + ".focus");
+        if (focus.kind === "supplied-working-f-number") {
+            if (isPlainObjectValue(focus.focus)) {
+                rejectUnknownVariantFields(focus.focus, "kind", { infinity: ["kind"], finite: ["kind", "objectDistanceM"] }, path + ".focus.focus");
+            }
+            if (isPlainObjectValue(focus.workingFNumber)) {
+                rejectUnknownFields(focus.workingFNumber, ["value", "evidence"], path + ".focus.workingFNumber");
+            }
+        }
+    }
+    if (isPlainObjectValue(fieldThroughput)) {
+        rejectUnknownVariantFields(fieldThroughput, "kind", {
+            unity: ["kind"],
+            "illumination-vignetting-result": ["kind", "result"]
+        }, path + ".fieldThroughput");
+    }
+}
+function isPlainObjectValue(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function validatePhysicalSceneSample(sample, sceneTimeSecondsFromExposureStart) {
+    requireRecord(sample, "physicalSceneSample", ["sceneRadianceRequest", "sceneRadianceResult", "focus", "imagePointMm",
+        "fieldThroughput", "frontOfLensFilters"]);
+    rejectUnknownOpticalBridgeFields(sample.focus, sample.fieldThroughput, "physicalSceneSample");
     const request = parseSceneRadianceEvaluationRequest(sample.sceneRadianceRequest);
     const result = parseSceneRadianceEvaluationResult(sample.sceneRadianceResult);
     if (request
@@ -576,7 +646,7 @@ function validatePhysicalSceneSample(sample, sceneTimeSecondsFromExposureStart)
         sceneTimeSecondsFromExposureStart) {
         throw new InvalidConfigurationError("physicalSceneSample.sceneRadianceRequest.timeSecondsFromExposureStart must equal the capture snapshot scene time.");
     }
-    const imagePoint = requireRecord(sample.imagePointMm, "physicalSceneSample.imagePointMm");
+    const imagePoint = requireRecord(sample.imagePointMm, "physicalSceneSample.imagePointMm", ["x", "y"]);
     return cloneJson({
         sceneRadianceRequest: request,
         sceneRadianceResult: result,
@@ -601,6 +671,16 @@ const CAPTURE_ORIENTATIONS = new Set([
     "portrait-counter-clockwise"
 ]);
 function validateTemporalCaptureInput(input, shutterSeconds) {
+    requireRecord(input, "temporalCapture", ["exposureWindowInput", "imagingArea", "orientation", "readout",
+        "readoutExposureLinkage", "rotation"]);
+    requireRecord(input.imagingArea, "temporalCapture.imagingArea", ["widthMm", "heightMm"]);
+    if (isPlainObjectValue(input.readoutExposureLinkage)) {
+        rejectUnknownFields(input.readoutExposureLinkage, ["kind", "evidence"], "temporalCapture.readoutExposureLinkage");
+    }
+    if (input.rotation !== undefined) {
+        requireRecord(input.rotation, "temporalCapture.rotation", ["angularVelocityRadPerSec", "focusDistanceM", "temporalSampleCount"]);
+        requireRecord(input.rotation.angularVelocityRadPerSec, "temporalCapture.rotation.angularVelocityRadPerSec", ["pitch", "yaw", "roll"]);
+    }
     const exposureWindows = calculateCaptureExposureWindows(input.exposureWindowInput).value;
     if (!settingEquals(exposureWindows
         .nominalExposureDurationSeconds
@@ -639,6 +719,19 @@ function validateTemporalCaptureInput(input, shutterSeconds) {
                 })
         });
     }
+    if (input.readoutExposureLinkage !== undefined) {
+        const linkage = input.readoutExposureLinkage;
+        if (typeof linkage !== "object" ||
+            linkage === null ||
+            linkage.kind !== "electronic-rolling-shutter-line-reset-read") {
+            throw new InvalidConfigurationError("temporalCapture.readoutExposureLinkage.kind is invalid.");
+        }
+        parseEvidenceList(linkage.evidence, "temporalCapture.readoutExposureLinkage.evidence");
+        if (input.readout === undefined ||
+            !isElectronicRollingShutterExposureSchedule(input.exposureWindowInput, input.readout)) {
+            throw new InvalidConfigurationError("temporalCapture electronic rolling-shutter linkage requires a rolling readout and the exposure schedule derived from it.");
+        }
+    }
     if (input.rotation !== undefined) {
         const sampleCount = input.rotation
             .temporalSampleCount;
@@ -700,6 +793,9 @@ function validateReleaseAutomationState(value, path) {
     return value;
 }
 function validateProductionReleaseFrameBinding(binding, releaseFrameId, exposure, stochasticSeedUint32) {
+    requireRecord(binding, "releaseFrameBinding", ["releaseSequenceVersion", "sequenceId", "releaseFrameId", "frameIndex", "exposure",
+        "stochasticSeedUint32", "exposureStartTimeSeconds", "exposureEndTimeSeconds", "sceneTimeSecondsFromSequenceStart",
+        "startIntervalFromPreviousSeconds", "timingConstraints", "focus", "automation", "whiteBalanceStateId"]);
     if (binding.releaseSequenceVersion !==
         RELEASE_SEQUENCE_VERSION) {
         throw new InvalidConfigurationError('releaseFrameBinding.releaseSequenceVersion must be "' +
@@ -752,7 +848,7 @@ function validateProductionReleaseFrameBinding(binding, releaseFrameId, exposure
         timingConstraints.length) {
         throw new InvalidConfigurationError("releaseFrameBinding.timingConstraints must not contain duplicates.");
     }
-    const automationRecord = requireRecord(binding.automation, "releaseFrameBinding.automation");
+    const automationRecord = requireRecord(binding.automation, "releaseFrameBinding.automation", ["ae", "af", "awb"]);
     const automation = {
         ae: validateReleaseAutomationState(automationRecord.ae, "releaseFrameBinding.automation.ae"),
         af: validateReleaseAutomationState(automationRecord.af, "releaseFrameBinding.automation.af"),
@@ -762,7 +858,7 @@ function validateProductionReleaseFrameBinding(binding, releaseFrameId, exposure
         undefined
         ? undefined
         : requireNonEmptyString(binding.whiteBalanceStateId, "releaseFrameBinding.whiteBalanceStateId");
-    const exposureRecord = requireRecord(binding.exposure, "releaseFrameBinding.exposure");
+    const exposureRecord = requireRecord(binding.exposure, "releaseFrameBinding.exposure", ["aperture", "shutterSeconds", "iso"]);
     const parsedExposure = {
         aperture: requirePositiveFinite(exposureRecord.aperture, "releaseFrameBinding.exposure.aperture"),
         shutterSeconds: requirePositiveFinite(exposureRecord.shutterSeconds, "releaseFrameBinding.exposure.shutterSeconds"),
@@ -856,26 +952,30 @@ function validateCommittedWhiteBalanceState(state, binding) {
     return parsed;
 }
 /**
- * Commit resolved capture settings, scene time/identity, stochastic seed and optional
- * temporal/focus/WB state by value. Later application mutations cannot alter this scientific event.
+ * Records, by value, the resolved capture settings, the scene time and identity, the random seed,
+ * and optional timing, focus and white-balance state. Later changes in the application cannot alter
+ * this captured event.
  *
- * The planner owns scientific stage ordering, immutable capture identity and reproducibility.
- * Well-formed unsupported combinations produce structured blockers; malformed declarations throw. The
- * bounded environment route executes supplied radiance through native RAW and optional output, while
- * sample-only and attached-RAW routes retain missing upstream blockers. FNV fingerprints are
- * reproducibility keys, not cryptographic integrity proofs.
- * @param input - CreateProductionCaptureSnapshotInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns ProductionCaptureSnapshot. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * The planner decides the order of the scientific stages, fixes each capture's identity so it cannot
+ * change, and makes results reproducible. A well-formed but unsupported combination returns
+ * structured blockers. A malformed declaration throws. The bounded environment route runs the
+ * supplied radiance through native RAW and, optionally, output processing. The sample-only and
+ * attached-RAW routes keep blockers for the upstream stages they lack. FNV fingerprints are keys for
+ * reproducibility, not cryptographic proof of integrity.
+ * @param input - CreateProductionCaptureSnapshotInput. See that type for coordinates, units and profile binding.
+ * @returns ProductionCaptureSnapshot. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export function createProductionCaptureSnapshot(input) {
+    requireInputKeys(input, "createProductionCaptureSnapshot", ["captureId", "releaseFrameId", "sceneStateId", "sceneTimeSecondsFromExposureStart", "outputStateId", "exposure", "stochasticSeedUint32", "releaseFrameBinding", "whiteBalanceState", "physicalSceneSample", "temporalCapture", "version", "fingerprint"]);
     const sceneTime = requireFinite(input
         .sceneTimeSecondsFromExposureStart, "sceneTimeSecondsFromExposureStart");
     if (sceneTime < 0) {
         throw new InvalidConfigurationError("sceneTimeSecondsFromExposureStart must be greater than or equal to zero.");
     }
     const releaseFrameId = requireNonEmptyString(input.releaseFrameId, "releaseFrameId");
+    requireRecord(input.exposure, "exposure", null);
     const exposure = {
         aperture: requirePositiveFinite(input.exposure.aperture, "exposure.aperture"),
         shutterSeconds: requirePositiveFinite(input.exposure
@@ -942,13 +1042,15 @@ export function createProductionCaptureSnapshot(input) {
     return deepFreeze(cloneJson(snapshot));
 }
 /**
- * Creates one immutable production snapshot directly from a committed #105
- * release frame. The release frame owns exposure/focus/automation/seed
- * identity; callers provide only the scene/output-local state that is not
- * owned by the release sequence.
+ * Creates one immutable production snapshot directly from a committed release
+ * frame (ResolvedReleaseFrame). The release frame supplies the exposure, focus,
+ * automation and seed. The caller supplies only the scene and output state that
+ * the release sequence does not.
  */
 export function createProductionCaptureSnapshotFromReleaseFrame(input) {
+    requireInputKeys(input, "createProductionCaptureSnapshotFromReleaseFrame", ["captureId", "sceneStateId", "sceneTimeSecondsFromExposureStart", "outputStateId", "releaseFrame", "whiteBalanceState", "physicalSceneSample", "temporalCapture"]);
     const frame = input.releaseFrame;
+    requireInputObject(frame, "frame input");
     const releaseFrameBinding = {
         releaseSequenceVersion: RELEASE_SEQUENCE_VERSION,
         sequenceId: requireNonEmptyString(frame.sequenceId, "releaseFrame.sequenceId"),
@@ -1009,27 +1111,29 @@ export function createProductionCaptureSnapshotFromReleaseFrame(input) {
     });
 }
 /**
- * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
- * missing required fields and incompatible scientific data fail at this boundary.
+ * Validates an untrusted declaration and returns the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data are rejected here.
  *
- * The planner owns scientific stage ordering, immutable capture identity and reproducibility.
- * Well-formed unsupported combinations produce structured blockers; malformed declarations throw. The
- * bounded environment route executes supplied radiance through native RAW and optional output, while
- * sample-only and attached-RAW routes retain missing upstream blockers. FNV fingerprints are
- * reproducibility keys, not cryptographic integrity proofs.
- * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
- * @returns ProductionCaptureSnapshot. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * The planner decides the order of the scientific stages, fixes each capture's identity so it cannot
+ * change, and makes results reproducible. A well-formed but unsupported combination returns
+ * structured blockers. A malformed declaration throws. The bounded environment route runs the
+ * supplied radiance through native RAW and, optionally, output processing. The sample-only and
+ * attached-RAW routes keep blockers for the upstream stages they lack. FNV fingerprints are keys for
+ * reproducibility, not cryptographic proof of integrity.
+ * @param value - unknown. Untrusted input; TypeScript types alone are not validation.
+ * @returns ProductionCaptureSnapshot. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export function parseProductionCaptureSnapshot(value) {
-    const record = requireRecord(value, "productionCaptureSnapshot");
+    const record = requireRecord(value, "productionCaptureSnapshot", ["version", "captureId", "releaseFrameId", "sceneStateId", "sceneTimeSecondsFromExposureStart", "outputStateId", "exposure", "stochasticSeedUint32", "releaseFrameBinding", "whiteBalanceState", "physicalSceneSample", "temporalCapture", "fingerprint"]);
     if (record.version !==
         PRODUCTION_CAPTURE_SNAPSHOT_VERSION) {
         throw new InvalidConfigurationError('productionCaptureSnapshot.version must be "' +
             PRODUCTION_CAPTURE_SNAPSHOT_VERSION +
             '".');
     }
+    requireRecord(record.exposure, "productionCaptureSnapshot.exposure", ["aperture", "shutterSeconds", "iso"]);
     const parsed = createProductionCaptureSnapshot({
         captureId: record.captureId,
         releaseFrameId: record.releaseFrameId,
@@ -1072,7 +1176,7 @@ export function parseProductionCaptureSnapshot(value) {
                     .temporalCapture
             })
     });
-    const supplied = requireRecord(record.fingerprint, "productionCaptureSnapshot.fingerprint");
+    const supplied = requireRecord(record.fingerprint, "productionCaptureSnapshot.fingerprint", ["algorithm", "value"]);
     if (supplied.algorithm !==
         "fnv1a-32-non-cryptographic" ||
         supplied.value !==
@@ -1082,10 +1186,11 @@ export function parseProductionCaptureSnapshot(value) {
     return parsed;
 }
 /**
- * Expand the requested graph through hard upstream dependencies in the engine
- * contract. Shared/coupled effects remain distinct from serialization order.
- * Dependency presence is not execution: deriveStagePlan still assesses declared
- * inputs, renderer capabilities and scientific support for every expanded stage.
+ * Adds the hard upstream dependencies of each requested stage, as the engine
+ * contract defines them. Shared or coupled effects stay separate from the
+ * serialization order. Adding a dependency does not mean it runs: deriveStagePlan
+ * still checks the declared inputs, renderer capabilities and scientific support
+ * for every added stage.
  */
 function expandRequiredStages(fidelity) {
     const contract = getImageFormationContract();
@@ -1252,6 +1357,15 @@ function requestedEffectMap(fidelity) {
         effect
     ]));
 }
+/** True when a declared lens field mapping applies no distortion (absent, "none" or all-zero terms). */
+function lensDistortionIsZero(mapping) {
+    const distortion = mapping?.distortion;
+    if (distortion === undefined || distortion.kind === "none")
+        return true;
+    const coefficients = distortion.profile?.coefficients;
+    return typeof coefficients === "object" && coefficients !== null &&
+        Object.values(coefficients).every(value => value === 0);
+}
 function hasActiveUndeclaredFieldThroughput(prepared, snapshot) {
     const sample = snapshot.physicalSceneSample;
     if (sample === undefined ||
@@ -1395,7 +1509,10 @@ function computeTemporalResult(prepared, snapshot, requiredStages, blockers) {
                     rotationQuadrature
                 }),
             exposureTimeReference: "first-opening-boundary-phase",
-            readoutExposureSynchronization: "not-assumed",
+            readoutExposureSynchronization: temporal.readoutExposureLinkage ===
+                undefined
+                ? "not-assumed"
+                : "electronic-rolling-shutter-line-linked",
             sensorReadoutTimingRemainsSeparate: true,
             temporalRadianceIntegrated: false
         };
@@ -1491,6 +1608,30 @@ function deriveEffectPlan(prepared, snapshot, temporalResult, blockers, environm
                 ]
             };
         }
+        if (placement.id === "geometric-distortion") {
+            // 2.0: lens distortion is applied only through an executed environment capture whose
+            // sites declare a lens field mapping. The ray query applies the inverse map and area factor.
+            const mapping = environmentCapture?.capture.sites[0]?.environment.lensFieldMapping;
+            if (mapping === undefined) {
+                const blocker = {
+                    code: "missing-lens-field-mapping",
+                    effectId: placement.id,
+                    message: "Geometric-distortion planning requires an executed environment capture with an explicit lens field mapping."
+                };
+                addBlocker(blockers, blocker);
+                return {
+                    effectId: placement.id, primaryStage: placement.primaryStage, coupledStages: [...placement.coupledStages],
+                    state: "blocked", scientificStatus: "not-applicable", requiredByFidelity: true,
+                    modelId: request.modelId, modelVersion: request.modelVersion, blockerCodes: [blocker.code]
+                };
+            }
+            return {
+                effectId: placement.id, primaryStage: placement.primaryStage, coupledStages: [...placement.coupledStages],
+                state: lensDistortionIsZero(mapping) ? "modeled-zero" : "active",
+                scientificStatus: "approximation", requiredByFidelity: true,
+                modelId: request.modelId, modelVersion: request.modelVersion, blockerCodes: []
+            };
+        }
         if (placement.id ===
             "illumination-vignetting") {
             const environmentField = environmentCapture?.capture.sites[0]?.environment.fieldThroughput;
@@ -1665,7 +1806,7 @@ function computePhysicalResult(prepared, snapshot, requiredStages, blockers) {
         addBlocker(blockers, {
             code: "missing-optical-bridge-profile",
             stageId: "lens-field-pupil-evaluation",
-            message: "Physical lens-throughput planning requires a prepared #110 optical bridge profile."
+            message: "Physical lens-throughput planning requires a prepared scene-radiance-to-sensor-irradiance optical bridge profile."
         });
         return undefined;
     }
@@ -1779,7 +1920,7 @@ function deriveStagePlan(prepared, snapshot, requiredStages, physicalResult, tem
             return { stageId: stage.id, contractStatus: stage.status, state: supported ? "active" : "blocked",
                 scientificStatus: supported ? "approximation" : "not-applicable", requiredByFidelity: true,
                 requiredUpstreamStages: [...stage.requiredUpstreamStages], coupledStages: [...stage.coupledStages],
-                modelId: "processed-sensor-raw-sdr", modelVersion: "0.1.0",
+                modelId: "processed-sensor-raw-sdr", modelVersion: PROCESSED_SENSOR_RAW_MODEL_VERSION,
                 resultIdentity: processedResult.value.source.value.rawFrame.frameId,
                 blockerCodes: supported ? [] : ["renderer-stage-unsupported"] };
         }
@@ -1886,7 +2027,7 @@ function deriveStagePlan(prepared, snapshot, requiredStages, physicalResult, tem
                 const blocker = {
                     code: "missing-physical-scene-sample",
                     stageId: stage.id,
-                    message: "Scene-radiance stage requires one immutable #85 request/result sample."
+                    message: "Scene-radiance stage requires one immutable scene-radiance provider request/result sample."
                 };
                 addBlocker(blockers, blocker);
                 return {
@@ -2197,10 +2338,11 @@ function temporalAssuranceComponent(snapshot) {
     };
 }
 /**
- * Compose evidence/status from actual child stages without averaging uncertainty
- * or upgrading declared approximation to calibration. Requested blockers and
- * executed lineage are part of assurance; a complete graph alone cannot establish
- * physical accuracy or validate an external provider's numerical transport.
+ * Builds the evidence and status from the child stages that actually ran. It
+ * does not average uncertainty and never upgrades a declared approximation to
+ * calibration. Requested blockers and executed lineage are part of the
+ * assurance. A complete graph alone cannot show physical accuracy or validate
+ * an external provider's numerical transport.
  */
 function composeProductionScientificAssurance(prepared, snapshot, physicalResult, temporalResult, processedResult, environmentResult) {
     const components = [];
@@ -2221,7 +2363,7 @@ function composeProductionScientificAssurance(prepared, snapshot, physicalResult
     }
     if (processedResult !== undefined) {
         components.push({ componentId: "processed-sensor-raw-sdr", role: "committed post-capture SDR development", required: true,
-            sourceIdentity: { kind: "model", id: "processed-sensor-raw-sdr", version: "0.1.0" }, basisKind: "photivra-model-assumption",
+            sourceIdentity: { kind: "model", id: "processed-sensor-raw-sdr", version: PROCESSED_SENSOR_RAW_MODEL_VERSION }, basisKind: "photivra-model-assumption",
             scientificStatus: "approximation", evidenceRequirement: "required", evidence: processedResult.value.colorProfile.evidence,
             uncertainty: { kind: "not-quantified", limitation: "Reconstruction, color interpretation and optional correction uncertainty are not propagated into a combined output uncertainty." },
             limitations: [...processedResult.value.colorProfile.limitations,
@@ -2236,7 +2378,7 @@ function composeProductionScientificAssurance(prepared, snapshot, physicalResult
         components
     });
 }
-/** Check immutable event ownership before source code or downstream pixel work. */
+/** Checks that the event is immutable and owned before any provider code or pixel work runs. */
 function validateProductionRawCapture(capture, snapshot, label = "Processed RAW") {
     if (capture.captureId !== snapshot.captureId || capture.sceneStateId !== snapshot.sceneStateId ||
         capture.sceneTimeSeconds !== snapshot.sceneTimeSecondsFromExposureStart || capture.noise.seedUint32 !== snapshot.stochasticSeedUint32 ||
@@ -2254,12 +2396,12 @@ function validateProductionRawCapture(capture, snapshot, label = "Processed RAW"
         throw new InvalidConfigurationError(label + " focus differs from the committed optical sample.");
     }
 }
-/** Execute the committed post-capture boundary without blessing absent upstream stages. */
+/** Runs the committed post-capture step, without treating missing upstream stages as done. */
 function computeProcessedOutput(input, prepared, snapshot, required, blockers) {
     if (input === undefined)
         return undefined;
     try {
-        const declaration = requireRecord(input, "processedOutput");
+        const declaration = requireRecord(input, "processedOutput", null);
         if (Object.keys(declaration).some(key => key !== "outputStateId" && key !== "processing"))
             throw new InvalidConfigurationError("Unknown processed output declaration fields.");
         if (!required.has("display-processing") || !prepared.renderer.sensorDomainProcessing)
@@ -2278,22 +2420,24 @@ function computeProcessedOutput(input, prepared, snapshot, required, blockers) {
     }
 }
 /**
- * Commit the execution envelope before invoking supplied provider code. A failed
- * preflight returns a structured blocker and never invokes that code. The existing
- * environment producer owns all node budgets, response validity and seeded RAW.
+ * Fixes the execution limits before any supplied provider code runs. If the
+ * preflight check fails, a structured blocker is returned and the code is never
+ * called. The existing environment producer handles all node budgets, response
+ * checks and the seeded RAW.
  */
 /**
- * Validate shared capture/context, renderer and supported-envelope commitments
- * before any trusted provider callback runs. Snapshot owned scientific and output
- * policy data first, then delegate to the one existing environment RAW producer.
- * Callback failure propagates; a successful call proves invocation and data binding,
- * not physical transport, visibility, calibration or a fallback renderer.
+ * Validates the shared capture and context, the renderer and the supported range
+ * before any trusted provider callback runs. Takes a snapshot of the scientific
+ * and output policy data first, then hands off to the single existing
+ * environment RAW producer. A callback failure is passed on. A successful call
+ * shows only that the code ran and the data was bound. It does not show physical
+ * transport, visibility or calibration, and there is no fallback renderer.
  */
 function computeEnvironmentCapture(input, externalOutput, prepared, snapshot, required, blockers) {
     if (input === undefined)
         return undefined;
     try {
-        const declaration = requireRecord(input, "environmentCapture");
+        const declaration = requireRecord(input, "environmentCapture", null);
         if (Object.keys(declaration).some(key => key !== "capture" && key !== "processing")) {
             throw new InvalidConfigurationError("Unknown environment capture declaration fields.");
         }
@@ -2333,17 +2477,24 @@ function computeEnvironmentCapture(input, externalOutput, prepared, snapshot, re
             throw new InvalidConfigurationError("Environment geometry, scene, focal length and shutter schedule differ from the committed production context.");
         }
         const rendererTemporal = prepared.renderer.temporalSampling;
+        // Frame-constant serializations are computed once, lazily at their first comparison, instead of once per site.
+        let opticalBridgeCanonical, rotationVelocityCanonical;
         for (const site of owned.sites) {
             const e = site.environment;
             if (e.fieldThroughput.kind !== "unity" &&
                 !prepared.fidelity.requiredEffects.some(effect => effect.effectId === "illumination-vignetting")) {
                 throw new InvalidConfigurationError("Non-unity environment field throughput requires an explicitly requested illumination-vignetting effect.");
             }
+            if (e.lensFieldMapping !== undefined && !lensDistortionIsZero(e.lensFieldMapping) &&
+                !prepared.fidelity.requiredEffects.some(effect => effect.effectId === "geometric-distortion")) {
+                throw new InvalidConfigurationError("Active environment lens distortion requires an explicitly requested geometric-distortion effect.");
+            }
             if (e.sceneBindings.providerProfile.profileId !== prepared.sceneRadianceProviderProfileId ||
-                canonicalStringify(e.optics.profile) !== canonicalStringify(prepared.opticalBridgeProfile) ||
+                canonicalStringify(e.optics.profile) !== (opticalBridgeCanonical ??= canonicalStringify(prepared.opticalBridgeProfile)) ||
                 rendererTemporal.kind !== "bounded" || e.temporalSampleCount > rendererTemporal.maximumSamples ||
                 (temporal.rotation === undefined && !angularVelocityIsZero(e.motion.angularVelocityRadPerSec)) ||
-                (temporal.rotation !== undefined && (canonicalStringify(e.motion.angularVelocityRadPerSec) !== canonicalStringify(temporal.rotation.angularVelocityRadPerSec) ||
+                (temporal.rotation !== undefined && (canonicalStringify(e.motion.angularVelocityRadPerSec) !==
+                    (rotationVelocityCanonical ??= canonicalStringify(temporal.rotation.angularVelocityRadPerSec)) ||
                     e.temporalSampleCount !== temporal.rotation.temporalSampleCount ||
                     (capture.focus.kind === "finite" ? capture.focus.distanceM : undefined) !== temporal.rotation.focusDistanceM))) {
                 throw new InvalidConfigurationError("Environment provider, optics, motion or temporal sampling differs from the committed production context.");
@@ -2360,22 +2511,24 @@ function computeEnvironmentCapture(input, externalOutput, prepared, snapshot, re
     }
 }
 /**
- * Expand requested stages through the authoritative graph, validate shared commitments and capability
- * limits, then execute only supported declared input routes. Return explicit
- * active/zero/omitted/blocked dispositions and child evidence rather than silently skipping a
- * requested effect.
+ * Builds the production plan. Adds dependencies to the requested stages using the stage graph,
+ * checks the shared state and capability limits, then runs only supported, declared input routes.
+ * Each requested effect is reported as active, zero, omitted or blocked, with child evidence. A
+ * requested effect is never skipped silently.
  *
- * The planner owns scientific stage ordering, immutable capture identity and reproducibility.
- * Well-formed unsupported combinations produce structured blockers; malformed declarations throw. The
- * bounded environment route executes supplied radiance through native RAW and optional output, while
- * sample-only and attached-RAW routes retain missing upstream blockers. FNV fingerprints are
- * reproducibility keys, not cryptographic integrity proofs.
- * @param input - CreateProductionImageFormationPlanInput. See the linked contract for coordinate, unit and profile binding semantics.
- * @returns ProductionImageFormationPlan. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ * The planner decides the order of the scientific stages, fixes each capture's identity so it cannot
+ * change, and makes results reproducible. A well-formed but unsupported combination returns
+ * structured blockers. A malformed declaration throws. The bounded environment route runs the
+ * supplied radiance through native RAW and, optionally, output processing. The sample-only and
+ * attached-RAW routes keep blockers for the upstream stages they lack. FNV fingerprints are keys for
+ * reproducibility, not cryptographic proof of integrity.
+ * @param input - CreateProductionImageFormationPlanInput. See that type for coordinates, units and profile binding.
+ * @returns ProductionImageFormationPlan. The result states its shape and scientific status; a successful call does not imply calibration.
  *
  * @see docs/API_REFERENCE.md for the root export and exact type graph.
  */
 export function createProductionImageFormationPlan(input) {
+    requireInputKeys(input, "createProductionImageFormationPlan", ["environmentCapture", "processedOutput", "preparedContext", "captureSnapshot"]);
     const prepared = parsePreparedImageFormationContext(input.preparedContext);
     const snapshot = parseProductionCaptureSnapshot(input.captureSnapshot);
     validateSnapshotAgainstContext(prepared, snapshot);
@@ -2386,13 +2539,14 @@ export function createProductionImageFormationPlan(input) {
         computePhysicalResult(prepared, snapshot, requiredStages, blockers);
     const temporalResult = computeTemporalResult(prepared, snapshot, requiredStages, blockers);
     let effectPlan = deriveEffectPlan(prepared, snapshot, temporalResult, blockers, input.environmentCapture);
-    // Snapshot post-capture policy before a provider can mutate caller-owned state.
+    // Copy the post-capture policy before a provider can change the caller's objects.
     const environmentProcessing = input.environmentCapture?.processing === undefined ? undefined :
         structuredClone(input.environmentCapture.processing);
     const environmentExecution = computeEnvironmentCapture(input.environmentCapture, input.processedOutput, prepared, snapshot, requiredStages, blockers);
     const environmentCaptureResult = environmentExecution?.result;
     if (input.environmentCapture !== undefined && environmentCaptureResult === undefined) {
-        effectPlan = effectPlan.map(effect => effect.effectId === "illumination-vignetting" && effect.requiredByFidelity
+        effectPlan = effectPlan.map(effect => (effect.effectId === "illumination-vignetting" ||
+            (effect.effectId === "geometric-distortion" && effect.state !== "blocked")) && effect.requiredByFidelity
             ? { ...effect, state: "blocked", scientificStatus: "not-applicable",
                 blockerCodes: ["environment-capture-evaluation-blocked"] } : effect);
     }