@photivra/engine 0.6.0 → 1.0.0

package/dist/stabilization/system.js

@@ -0,0 +1,695 @@
+// 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. Generic
+ * stabilization evaluates declared angular disturbance with per-axis response, latency, limits and
+ * panning policy. Residual motion feeds the existing temporal mapping; no commercial IBIS/OIS
+ * calibration, arbitrary stop rating or inferred coordination is supplied.
+ * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data fail at this boundary. Generic
+ * stabilization evaluates declared angular disturbance with per-axis response, latency, limits and
+ * panning policy. Residual motion feeds the existing temporal mapping; no commercial IBIS/OIS
+ * calibration, arbitrary stop rating or inferred coordination is supplied.
+ * @see docs/STABILIZATION.md for equations, coordinate/unit conventions, blockers and support limits.
+ */
+import { approximationResult } from "../core/calculation-result.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
+import { parseEvidenceList } from "../core/evidence-provenance.js";
+import { InvalidScientificInputError, requirePositiveInteger } from "../core/validation.js";
+export const STABILIZATION_SYSTEM_PROFILE_SCHEMA_VERSION = "0.1.0";
+export const STABILIZATION_DISTURBANCE_TRAJECTORY_VERSION = "0.1.0";
+const AXES = new Set([
+    "pitch",
+    "yaw",
+    "roll"
+]);
+const ARCHITECTURES = new Set([
+    "off",
+    "sensor-shift",
+    "lens-optical",
+    "coordinated-physical"
+]);
+const CAPTURE_KINDS = new Set([
+    "still",
+    "video"
+]);
+function requireRecord(value, path) {
+    if (typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value)) {
+        throw new InvalidConfigurationError(path + " must be an object.");
+    }
+    return value;
+}
+function requireNonEmptyString(value, path) {
+    if (typeof value !== "string" ||
+        value.trim().length === 0) {
+        throw new InvalidConfigurationError(path +
+            " must be a non-empty string.");
+    }
+    return value.trim();
+}
+function requireFinite(value, path) {
+    if (typeof value !== "number" ||
+        !Number.isFinite(value)) {
+        throw new InvalidConfigurationError(path + " must be finite.");
+    }
+    return value;
+}
+function requireNonNegativeFinite(value, path) {
+    const parsed = requireFinite(value, path);
+    if (parsed < 0) {
+        throw new InvalidConfigurationError(path +
+            " must be greater than or equal to zero.");
+    }
+    return parsed;
+}
+function requirePositiveFinite(value, path) {
+    const parsed = requireFinite(value, path);
+    if (parsed <= 0) {
+        throw new InvalidConfigurationError(path +
+            " must be greater than zero.");
+    }
+    return parsed;
+}
+function requireFraction(value, path) {
+    const parsed = requireFinite(value, path);
+    if (parsed < 0 ||
+        parsed > 1) {
+        throw new InvalidConfigurationError(path +
+            " must lie from zero through one.");
+    }
+    return parsed;
+}
+function parseLimitations(value, path) {
+    if (!Array.isArray(value)) {
+        throw new InvalidConfigurationError(path + " must be an array.");
+    }
+    const parsed = value.map((entry, index) => requireNonEmptyString(entry, path +
+        "[" +
+        index +
+        "]"));
+    if (new Set(parsed).size !==
+        parsed.length) {
+        throw new InvalidConfigurationError(path +
+            " must not contain duplicates.");
+    }
+    return parsed;
+}
+function parseFractionFact(value, path) {
+    const record = requireRecord(value, path);
+    return {
+        value: requireFraction(record.value, path + ".value"),
+        evidence: parseEvidenceList(record.evidence, path + ".evidence")
+    };
+}
+function parseNonNegativeFact(value, path) {
+    const record = requireRecord(value, path);
+    return {
+        value: requireNonNegativeFinite(record.value, path + ".value"),
+        evidence: parseEvidenceList(record.evidence, path + ".evidence")
+    };
+}
+function parsePositiveFact(value, path) {
+    const record = requireRecord(value, path);
+    return {
+        value: requirePositiveFinite(record.value, path + ".value"),
+        evidence: parseEvidenceList(record.evidence, path + ".evidence")
+    };
+}
+function parseAxis(value, path) {
+    if (typeof value !== "string" ||
+        !AXES.has(value)) {
+        throw new InvalidConfigurationError(path + " is invalid.");
+    }
+    return value;
+}
+function parseAxisResponse(value, path) {
+    const record = requireRecord(value, path);
+    return {
+        axis: parseAxis(record.axis, path + ".axis"),
+        correctionGain: parseFractionFact(record.correctionGain, path +
+            ".correctionGain"),
+        latencySeconds: parseNonNegativeFact(record.latencySeconds, path +
+            ".latencySeconds"),
+        maximumCorrectionAngleRad: parsePositiveFact(record
+            .maximumCorrectionAngleRad, path +
+            ".maximumCorrectionAngleRad")
+    };
+}
+function parsePanningPolicy(value, path) {
+    const record = requireRecord(value, path);
+    if (record.kind === "none") {
+        return {
+            kind: "none"
+        };
+    }
+    if (record.kind ===
+        "declared-axis-bypass") {
+        return {
+            kind: "declared-axis-bypass",
+            axis: parseAxis(record.axis, path + ".axis"),
+            evidence: parseEvidenceList(record.evidence, path + ".evidence")
+        };
+    }
+    throw new InvalidConfigurationError(path + ".kind is invalid.");
+}
+function parseCoordinatedAllocation(value, path) {
+    const record = requireRecord(value, path);
+    if (record
+        .totalCorrectionAppliedOnce !==
+        true) {
+        throw new InvalidConfigurationError(path +
+            ".totalCorrectionAppliedOnce must be true.");
+    }
+    const bodyFraction = requireFraction(record.bodyFraction, path + ".bodyFraction");
+    const lensFraction = requireFraction(record.lensFraction, path + ".lensFraction");
+    if (Math.abs(bodyFraction +
+        lensFraction -
+        1) >
+        1e-12) {
+        throw new InvalidConfigurationError(path +
+            " bodyFraction + lensFraction must equal one.");
+    }
+    return {
+        bodyFraction,
+        lensFraction,
+        evidence: parseEvidenceList(record.evidence, path + ".evidence"),
+        totalCorrectionAppliedOnce: true
+    };
+}
+/**
+ * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data fail at this boundary.
+ *
+ * Generic stabilization evaluates declared angular disturbance with per-axis response, latency, limits
+ * and panning policy. Residual motion feeds the existing temporal mapping; no commercial IBIS/OIS
+ * calibration, arbitrary stop rating or inferred coordination is supplied.
+ * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
+ * @returns StabilizationSystemProfile. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ *
+ * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ */
+export function parseStabilizationSystemProfile(value) {
+    const record = requireRecord(value, "stabilizationSystemProfile");
+    if (record.schemaVersion !==
+        STABILIZATION_SYSTEM_PROFILE_SCHEMA_VERSION) {
+        throw new InvalidConfigurationError('stabilizationSystemProfile.schemaVersion must be "' +
+            STABILIZATION_SYSTEM_PROFILE_SCHEMA_VERSION +
+            '".');
+    }
+    if (record.profileKind !==
+        "generic-synthetic" ||
+        record.scientificStatus !==
+            "approximation") {
+        throw new InvalidConfigurationError('stabilizationSystemProfile schema 0.1.0 requires profileKind "generic-synthetic" and scientificStatus "approximation".');
+    }
+    if (typeof record.architecture !==
+        "string" ||
+        !ARCHITECTURES.has(record.architecture)) {
+        throw new InvalidConfigurationError("stabilizationSystemProfile.architecture is invalid.");
+    }
+    if (typeof record.captureKind !==
+        "string" ||
+        !CAPTURE_KINDS.has(record.captureKind)) {
+        throw new InvalidConfigurationError("stabilizationSystemProfile.captureKind is invalid.");
+    }
+    for (const key of [
+        "controlTransientModeled",
+        "spontaneousDriftModeled",
+        "cameraTranslationCorrectionModeled",
+        "digitalStabilizationIncluded",
+        "supportPolicyIncluded",
+        "stopRatingUsedAsDynamicResponse"
+    ]) {
+        if (record[key] !== false) {
+            throw new InvalidConfigurationError("stabilizationSystemProfile." +
+                key +
+                " must be false in schema 0.1.0.");
+        }
+    }
+    if (!Array.isArray(record.axisResponses)) {
+        throw new InvalidConfigurationError("stabilizationSystemProfile.axisResponses must be an array.");
+    }
+    const axisResponses = record.axisResponses.map((entry, index) => parseAxisResponse(entry, "stabilizationSystemProfile.axisResponses[" +
+        index +
+        "]"));
+    const axes = axisResponses.map((entry) => entry.axis);
+    if (new Set(axes).size !==
+        axes.length) {
+        throw new InvalidConfigurationError("stabilizationSystemProfile.axisResponses must not contain duplicate axes.");
+    }
+    const architecture = record.architecture;
+    if (architecture === "off" &&
+        axisResponses.length !== 0) {
+        throw new InvalidConfigurationError("An off stabilization profile must not declare axis responses.");
+    }
+    if (architecture !== "off" &&
+        axisResponses.length === 0) {
+        throw new InvalidConfigurationError("An enabled physical stabilization profile must declare at least one axis response.");
+    }
+    const panningPolicy = parsePanningPolicy(record.panningPolicy, "stabilizationSystemProfile.panningPolicy");
+    if (architecture === "off" &&
+        panningPolicy.kind !== "none") {
+        throw new InvalidConfigurationError("An off stabilization profile must use panningPolicy.kind \"none\".");
+    }
+    if (panningPolicy.kind ===
+        "declared-axis-bypass" &&
+        !axisResponses.some((entry) => entry.axis ===
+            panningPolicy.axis)) {
+        throw new InvalidConfigurationError("Declared panning bypass axis must exist in axisResponses.");
+    }
+    const coordinatedAllocation = record.coordinatedAllocation ===
+        undefined
+        ? undefined
+        : parseCoordinatedAllocation(record.coordinatedAllocation, "stabilizationSystemProfile.coordinatedAllocation");
+    if (architecture ===
+        "coordinated-physical" &&
+        coordinatedAllocation ===
+            undefined) {
+        throw new InvalidConfigurationError("Coordinated physical stabilization requires an explicit body/lens correction allocation.");
+    }
+    if (architecture !==
+        "coordinated-physical" &&
+        coordinatedAllocation !==
+            undefined) {
+        throw new InvalidConfigurationError("Only coordinated physical stabilization may declare coordinatedAllocation.");
+    }
+    return {
+        schemaVersion: STABILIZATION_SYSTEM_PROFILE_SCHEMA_VERSION,
+        profileId: requireNonEmptyString(record.profileId, "stabilizationSystemProfile.profileId"),
+        profileVersion: requireNonEmptyString(record.profileVersion, "stabilizationSystemProfile.profileVersion"),
+        profileKind: "generic-synthetic",
+        scientificStatus: "approximation",
+        architecture,
+        captureKind: record.captureKind,
+        axisResponses,
+        panningPolicy,
+        ...(coordinatedAllocation ===
+            undefined
+            ? {}
+            : {
+                coordinatedAllocation
+            }),
+        controlTransientModeled: false,
+        spontaneousDriftModeled: false,
+        cameraTranslationCorrectionModeled: false,
+        digitalStabilizationIncluded: false,
+        supportPolicyIncluded: false,
+        stopRatingUsedAsDynamicResponse: false,
+        evidence: parseEvidenceList(record.evidence, "stabilizationSystemProfile.evidence"),
+        limitations: parseLimitations(record.limitations, "stabilizationSystemProfile.limitations")
+    };
+}
+function parseAngularState(value, path) {
+    const record = requireRecord(value, path);
+    return {
+        pitch: requireFinite(record.pitch, path + ".pitch"),
+        yaw: requireFinite(record.yaw, path + ".yaw"),
+        roll: requireFinite(record.roll, path + ".roll")
+    };
+}
+/**
+ * Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+ * missing required fields and incompatible scientific data fail at this boundary.
+ *
+ * Generic stabilization evaluates declared angular disturbance with per-axis response, latency, limits
+ * and panning policy. Residual motion feeds the existing temporal mapping; no commercial IBIS/OIS
+ * calibration, arbitrary stop rating or inferred coordination is supplied.
+ * @param value - unknown. Treated as untrusted data; static typing alone is not validation.
+ * @returns StabilizationDisturbanceTrajectory. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ *
+ * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ */
+export function parseStabilizationDisturbanceTrajectory(value) {
+    const record = requireRecord(value, "stabilizationDisturbanceTrajectory");
+    if (record.version !==
+        STABILIZATION_DISTURBANCE_TRAJECTORY_VERSION ||
+        record.timeReference !==
+            "first-opening-boundary-phase" ||
+        record
+            .initialAngularDisplacementIsZero !==
+            true ||
+        record
+            .cameraTranslationIncluded !==
+            false ||
+        record.subjectMotionIncluded !==
+            false ||
+        record.supportStateEncoded !==
+            false) {
+        throw new InvalidConfigurationError("stabilizationDisturbanceTrajectory metadata is invalid for version 0.1.0.");
+    }
+    if (!Array.isArray(record.samples) ||
+        record.samples.length < 2) {
+        throw new InvalidConfigurationError("stabilizationDisturbanceTrajectory.samples must contain at least two samples.");
+    }
+    let previousTime = Number.NEGATIVE_INFINITY;
+    const samples = record.samples.map((entry, index) => {
+        const path = "stabilizationDisturbanceTrajectory.samples[" +
+            index +
+            "]";
+        const sample = requireRecord(entry, path);
+        const time = requireNonNegativeFinite(sample
+            .timeSecondsFromCaptureReference, path +
+            ".timeSecondsFromCaptureReference");
+        if (time <= previousTime) {
+            throw new InvalidConfigurationError("stabilizationDisturbanceTrajectory sample times must be strictly increasing.");
+        }
+        previousTime = time;
+        return {
+            timeSecondsFromCaptureReference: time,
+            angularDisplacementRad: parseAngularState(sample
+                .angularDisplacementRad, path +
+                ".angularDisplacementRad")
+        };
+    });
+    const first = samples[0];
+    if (first
+        .timeSecondsFromCaptureReference !==
+        0 ||
+        first
+            .angularDisplacementRad
+            .pitch !== 0 ||
+        first
+            .angularDisplacementRad
+            .yaw !== 0 ||
+        first
+            .angularDisplacementRad
+            .roll !== 0) {
+        throw new InvalidConfigurationError("stabilizationDisturbanceTrajectory must begin at capture-reference t=0 with zero angular displacement.");
+    }
+    return {
+        version: STABILIZATION_DISTURBANCE_TRAJECTORY_VERSION,
+        trajectoryId: requireNonEmptyString(record.trajectoryId, "stabilizationDisturbanceTrajectory.trajectoryId"),
+        timeReference: "first-opening-boundary-phase",
+        samples,
+        initialAngularDisplacementIsZero: true,
+        cameraTranslationIncluded: false,
+        subjectMotionIncluded: false,
+        supportStateEncoded: false,
+        evidence: parseEvidenceList(record.evidence, "stabilizationDisturbanceTrajectory.evidence"),
+        limitations: parseLimitations(record.limitations, "stabilizationDisturbanceTrajectory.limitations")
+    };
+}
+function interpolateAxis(trajectory, timeSeconds, axis) {
+    const first = trajectory.samples[0];
+    const last = trajectory.samples[trajectory.samples.length -
+        1];
+    if (timeSeconds <
+        first
+            .timeSecondsFromCaptureReference ||
+        timeSeconds >
+            last
+                .timeSecondsFromCaptureReference) {
+        throw new InvalidScientificInputError("Requested stabilization evaluation time lies outside the disturbance trajectory support.");
+    }
+    if (timeSeconds ===
+        last
+            .timeSecondsFromCaptureReference) {
+        return last
+            .angularDisplacementRad[axis];
+    }
+    for (let index = 0; index <
+        trajectory.samples.length - 1; index += 1) {
+        const left = trajectory.samples[index];
+        const right = trajectory.samples[index + 1];
+        if (timeSeconds >=
+            left
+                .timeSecondsFromCaptureReference &&
+            timeSeconds <=
+                right
+                    .timeSecondsFromCaptureReference) {
+            const duration = right
+                .timeSecondsFromCaptureReference -
+                left
+                    .timeSecondsFromCaptureReference;
+            const phase = duration === 0
+                ? 0
+                : (timeSeconds -
+                    left
+                        .timeSecondsFromCaptureReference) /
+                    duration;
+            const a = left
+                .angularDisplacementRad[axis];
+            const b = right
+                .angularDisplacementRad[axis];
+            return (a +
+                (b - a) * phase);
+        }
+    }
+    throw new InvalidScientificInputError("Disturbance trajectory interpolation failed.");
+}
+function axisValue(state, axis) {
+    return state[axis];
+}
+function setAxisValue(state, axis, value) {
+    state[axis] = value;
+}
+function clampSymmetric(value, limit) {
+    return Math.max(-limit, Math.min(limit, value));
+}
+function evaluateAtTime(disturbance, profile, timeSeconds) {
+    const current = {
+        pitch: interpolateAxis(disturbance, timeSeconds, "pitch"),
+        yaw: interpolateAxis(disturbance, timeSeconds, "yaw"),
+        roll: interpolateAxis(disturbance, timeSeconds, "roll")
+    };
+    const correction = {
+        pitch: 0,
+        yaw: 0,
+        roll: 0
+    };
+    const residual = {
+        ...current
+    };
+    const responses = new Map(profile.axisResponses.map((response) => [
+        response.axis,
+        response
+    ]));
+    const axes = ["pitch", "yaw", "roll"];
+    const resolvedAxes = axes.map((axis) => {
+        const response = responses.get(axis);
+        const bypassed = profile.panningPolicy.kind ===
+            "declared-axis-bypass" &&
+            profile.panningPolicy.axis ===
+                axis;
+        if (profile.architecture ===
+            "off" ||
+            response === undefined ||
+            bypassed) {
+            return {
+                axis,
+                disturbanceAngleRad: axisValue(current, axis),
+                delayedMeasuredAngleRad: 0,
+                requestedCorrectionAngleRad: 0,
+                appliedCorrectionAngleRad: 0,
+                residualAngleRad: axisValue(current, axis),
+                correctionGain: response?.correctionGain
+                    .value ?? 0,
+                latencySeconds: response?.latencySeconds
+                    .value ?? 0,
+                maximumCorrectionAngleRad: response
+                    ?.maximumCorrectionAngleRad
+                    .value ?? 0,
+                bypassedForDeclaredPan: bypassed,
+                correctionLimitReached: false
+            };
+        }
+        const delayedTime = timeSeconds -
+            response
+                .latencySeconds.value;
+        const delayedMeasured = delayedTime < 0
+            ? 0
+            : interpolateAxis(disturbance, delayedTime, axis);
+        const requested = delayedMeasured *
+            response
+                .correctionGain.value;
+        const applied = clampSymmetric(requested, response
+            .maximumCorrectionAngleRad
+            .value);
+        const residualAngle = axisValue(current, axis) -
+            applied;
+        setAxisValue(correction, axis, applied);
+        setAxisValue(residual, axis, residualAngle);
+        return {
+            axis,
+            disturbanceAngleRad: axisValue(current, axis),
+            delayedMeasuredAngleRad: delayedMeasured,
+            requestedCorrectionAngleRad: requested,
+            appliedCorrectionAngleRad: applied,
+            residualAngleRad: residualAngle,
+            correctionGain: response
+                .correctionGain.value,
+            latencySeconds: response
+                .latencySeconds.value,
+            maximumCorrectionAngleRad: response
+                .maximumCorrectionAngleRad
+                .value,
+            bypassedForDeclaredPan: false,
+            correctionLimitReached: applied !== requested
+        };
+    });
+    return {
+        timeSecondsFromCaptureReference: timeSeconds,
+        disturbanceAngularDisplacementRad: current,
+        appliedCorrectionAngularDisplacementRad: correction,
+        residualAngularDisplacementRad: residual,
+        axes: resolvedAxes
+    };
+}
+/**
+ * Evaluate the declared generic per-axis controller against an explicit angular disturbance trajectory
+ * and return residual motion with latency/limit diagnostics.
+ *
+ * Generic stabilization evaluates declared angular disturbance with per-axis response, latency, limits
+ * and panning policy. Residual motion feeds the existing temporal mapping; no commercial IBIS/OIS
+ * calibration, arbitrary stop rating or inferred coordination is supplied.
+ * @param input - CalculateStabilizedRotationTrajectoryInput. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns CalculationResult<StabilizedRotationTrajectory>. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ *
+ * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ */
+export function calculateStabilizedRotationTrajectory(input) {
+    const disturbance = parseStabilizationDisturbanceTrajectory(input.disturbance);
+    const profile = parseStabilizationSystemProfile(input.profile);
+    if (input.captureKind !==
+        profile.captureKind) {
+        throw new InvalidScientificInputError("captureKind must exactly match the stabilization profile captureKind.");
+    }
+    const samples = disturbance.samples.map((sample) => evaluateAtTime(disturbance, profile, sample
+        .timeSecondsFromCaptureReference));
+    return approximationResult({
+        profileId: profile.profileId,
+        profileVersion: profile.profileVersion,
+        trajectoryId: disturbance.trajectoryId,
+        architecture: profile.architecture,
+        captureKind: input.captureKind,
+        timeReference: "first-opening-boundary-phase",
+        samples,
+        correctionModel: "delayed-linear-image-equivalent-angular-response",
+        supportStateConsumed: false,
+        translationCorrectionModeled: false,
+        digitalStabilizationApplied: false,
+        digitalStabilizationOwnedBy: "downstream-geometric-correction-composition",
+        coordinatedCorrectionDoubleCounted: false,
+        zeroDisturbanceCanCreateMotion: false
+    }, "generic-time-domain-physical-stabilization", "1.0.0", [
+        "The stabilization response is a generic synthetic image-equivalent rotational correction, not a manufacturer-specific IBIS/OIS calibration.",
+        "Correction uses explicit per-axis gain, latency and symmetric angular correction limits.",
+        "A coordinated profile allocates one total correction between body and lens for descriptive ownership only; the total correction is applied once.",
+        "Support state is not an input and never silently toggles stabilization.",
+        "Declared panning bypass suppresses correction only on the explicitly selected axis; pan intent is never inferred.",
+        "Camera translation/parallax correction is not modeled because translational image motion depends on scene depth.",
+        "Digital stabilization is a separate downstream geometric/crop/resampling domain.",
+        "CIPA-style stop ratings are not used as a dynamic response function.",
+        "The legacy stabilizationStopsEquivalent approximation remains unchanged."
+    ]);
+}
+function localExposureForPoint(timing, point) {
+    const matches = timing.exposureWindows.samples.filter((sample) => sample.pointNative.x ===
+        point.x &&
+        sample.pointNative.y ===
+            point.y);
+    if (matches.length !== 1) {
+        throw new InvalidScientificInputError("Each stabilization sample point must match exactly one committed #12 exposure-window sample point.");
+    }
+    const match = matches[0];
+    return {
+        start: match
+            .startOffsetSecondsFromOpeningReference,
+        end: match
+            .endOffsetSecondsFromOpeningReference,
+        duration: match
+            .localExposureDurationSeconds
+    };
+}
+/**
+ * Feed the residual stabilized rotation into the existing local-exposure temporal mapping without
+ * changing shutter timing or inventing a blur radius.
+ *
+ * Generic stabilization evaluates declared angular disturbance with per-axis response, latency, limits
+ * and panning policy. Residual motion feeds the existing temporal mapping; no commercial IBIS/OIS
+ * calibration, arbitrary stop rating or inferred coordination is supplied.
+ * @param input - CalculateStabilizedCaptureTemporalSamplesInput. See the linked contract for coordinate, unit and profile binding semantics.
+ * @returns CalculationResult<StabilizedCaptureTemporalSamples>. Return shape and scientific status are explicit; no calibration is inferred from successful execution.
+ *
+ * @see docs/API_REFERENCE.md for the root export and exact type graph.
+ */
+export function calculateStabilizedCaptureTemporalSamples(input) {
+    const disturbance = parseStabilizationDisturbanceTrajectory(input.disturbance);
+    const profile = parseStabilizationSystemProfile(input.profile);
+    if (input.captureKind !==
+        profile.captureKind) {
+        throw new InvalidScientificInputError("captureKind must exactly match the stabilization profile captureKind.");
+    }
+    requirePositiveInteger("temporalSampleCount", input.temporalSampleCount);
+    if (!Array.isArray(input.samplePointsNative) ||
+        input.samplePointsNative.length ===
+            0) {
+        throw new InvalidScientificInputError("samplePointsNative must be a non-empty array.");
+    }
+    const totalNodeCount = input.temporalSampleCount *
+        input.samplePointsNative.length;
+    if (!Number.isSafeInteger(totalNodeCount)) {
+        throw new InvalidScientificInputError("temporalSampleCount × samplePointsNative.length must remain a safe integer.");
+    }
+    const points = input.samplePointsNative.map((point) => {
+        const exposure = localExposureForPoint(input.timing, point);
+        const normalizedTimeWeight = 1 /
+            input.temporalSampleCount;
+        const timeMeasureSeconds = exposure.duration /
+            input.temporalSampleCount;
+        const nodes = Array.from({
+            length: input.temporalSampleCount
+        }, (_, temporalSampleIndex) => {
+            const localExposurePhase = (temporalSampleIndex +
+                0.5) /
+                input.temporalSampleCount;
+            const captureTime = exposure.start +
+                localExposurePhase *
+                    exposure.duration;
+            return {
+                temporalSampleIndex,
+                localExposurePhase,
+                captureTimeSecondsFromReference: captureTime,
+                normalizedTimeWeight,
+                timeMeasureSeconds,
+                stabilization: evaluateAtTime(disturbance, profile, captureTime)
+            };
+        });
+        return {
+            destinationPointNative: {
+                ...point
+            },
+            localExposureWindow: {
+                startSecondsFromCaptureReference: exposure.start,
+                endSecondsFromCaptureReference: exposure.end,
+                durationSeconds: exposure.duration
+            },
+            nodes
+        };
+    });
+    return approximationResult({
+        profileId: profile.profileId,
+        trajectoryId: disturbance.trajectoryId,
+        captureModeId: input.timing.captureModeId,
+        timingProfileId: input.timing.timingProfileId,
+        captureKind: input.captureKind,
+        architecture: profile.architecture,
+        timeReference: "first-opening-boundary-phase",
+        quadratureScheme: "uniform-midpoint",
+        temporalSampleCount: input.temporalSampleCount,
+        points,
+        sensorReadoutTimingUsedAsExposureTiming: false,
+        supportStateConsumed: false,
+        translationCorrectionModeled: false,
+        digitalStabilizationApplied: false
+    }, "capture-local-stabilization-temporal-sampling", "1.0.0", [
+        "Stabilization is evaluated at deterministic midpoint nodes inside each authoritative #12 local exposure window.",
+        "Sensor data-readout timing is not substituted for exposure timing.",
+        "The result is rotational disturbance/correction/residual state only; it does not itself calculate image-plane mapping, radiance, blur, PSF or output pixels.",
+        "Translation/parallax, subject motion, shutter shock, support vibration sources and digital stabilization remain separate domains."
+    ]);
+}
+//# sourceMappingURL=system.js.map