@photivra/engine 0.1.0 → 0.4.0

package/dist/core/configuration-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configuration-error.js","sourceRoot":"","sources":["../../src/core/configuration-error.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;GAGG;AACH,MAAM,OAAO,yBAA0B,SAAQ,SAAS;IAC7C,IAAI,GAAG,uBAAuB,CAAC;IAExC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,2BAA2B,CAAC;IAC1C,CAAC;CACF"}

package/dist/core/evidence-provenance.d.ts

@@ -0,0 +1,40 @@
+export type EvidenceSourceOrigin = "manufacturer" | "third-party" | "photivra";
+export type EvidenceReuseStatus = "factual-reference-only" | "reusable-data" | "photivra-owned";
+export interface EvidenceProvenance {
+    /** Who originated the underlying fact/data. */
+    sourceOrigin: EvidenceSourceOrigin;
+    /**
+     * Public/stable source reference or Photivra evidence identifier.
+     *
+     * The engine does not fetch this reference at runtime.
+     */
+    sourceReference: string;
+    /**
+     * How the referenced material may be used by Photivra.
+     *
+     * This is intentionally independent from source origin: a manufacturer or
+     * third party may publish either factual-reference-only material or
+     * explicitly reusable licensed data.
+     */
+    reuseStatus: EvidenceReuseStatus;
+    /** Required when reuseStatus is reusable-data. */
+    license?: string;
+    note?: string;
+}
+export interface EvidenceBackedFact<T> {
+    value: T;
+    /** One or more independent evidence records supporting this fact. */
+    evidence: readonly EvidenceProvenance[];
+}
+/**
+ * Parses one provenance/evidence record.
+ *
+ * Source origin and reuse status are intentionally orthogonal. The parser only
+ * rejects combinations that are intrinsically contradictory.
+ */
+export declare function parseEvidenceProvenance(value: unknown, path: string): EvidenceProvenance;
+/**
+ * Parses a non-empty evidence array.
+ */
+export declare function parseEvidenceList(value: unknown, path: string): readonly EvidenceProvenance[];
+//# sourceMappingURL=evidence-provenance.d.ts.map

package/dist/core/evidence-provenance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-provenance.d.ts","sourceRoot":"","sources":["../../src/core/evidence-provenance.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,oBAAoB,GAC5B,cAAc,GACd,aAAa,GACb,UAAU,CAAC;AAEf,MAAM,MAAM,mBAAmB,GAC3B,wBAAwB,GACxB,eAAe,GACf,gBAAgB,CAAC;AAErB,MAAM,WAAW,kBAAkB;IACjC,+CAA+C;IAC/C,YAAY,EAAE,oBAAoB,CAAC;IACnC;;;;OAIG;IACH,eAAe,EAAE,MAAM,CAAC;IACxB;;;;;;OAMG;IACH,WAAW,EAAE,mBAAmB,CAAC;IACjC,kDAAkD;IAClD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,KAAK,EAAE,CAAC,CAAC;IACT,qEAAqE;IACrE,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACzC;AAmCD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,GACX,kBAAkB,CA6DpB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,IAAI,EAAE,MAAM,GACX,SAAS,kBAAkB,EAAE,CAU/B"}

package/dist/core/evidence-provenance.js

@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: Apache-2.0
+import { InvalidConfigurationError } from "./configuration-error.js";
+const SOURCE_ORIGINS = new Set([
+    "manufacturer",
+    "third-party",
+    "photivra"
+]);
+const REUSE_STATUSES = new Set([
+    "factual-reference-only",
+    "reusable-data",
+    "photivra-owned"
+]);
+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(record, key, path) {
+    const value = record[key];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new InvalidConfigurationError(`${path}.${key} must be a non-empty string.`);
+    }
+    return value;
+}
+/**
+ * Parses one provenance/evidence record.
+ *
+ * Source origin and reuse status are intentionally orthogonal. The parser only
+ * rejects combinations that are intrinsically contradictory.
+ */
+export function parseEvidenceProvenance(value, path) {
+    const record = requireRecord(value, path);
+    const sourceOrigin = requireNonEmptyString(record, "sourceOrigin", path);
+    const sourceReference = requireNonEmptyString(record, "sourceReference", path);
+    const reuseStatus = requireNonEmptyString(record, "reuseStatus", path);
+    if (!SOURCE_ORIGINS.has(sourceOrigin)) {
+        throw new InvalidConfigurationError(`${path}.sourceOrigin is invalid.`);
+    }
+    if (!REUSE_STATUSES.has(reuseStatus)) {
+        throw new InvalidConfigurationError(`${path}.reuseStatus is invalid.`);
+    }
+    const typedOrigin = sourceOrigin;
+    const typedReuseStatus = reuseStatus;
+    if (typedReuseStatus === "photivra-owned" &&
+        typedOrigin !== "photivra") {
+        throw new InvalidConfigurationError(`${path}.photivra-owned evidence must have sourceOrigin "photivra".`);
+    }
+    const license = record.license;
+    if (license !== undefined &&
+        (typeof license !== "string" || license.trim().length === 0)) {
+        throw new InvalidConfigurationError(`${path}.license must be a non-empty string when supplied.`);
+    }
+    if (typedReuseStatus === "reusable-data" && license === undefined) {
+        throw new InvalidConfigurationError(`${path}.license is required for reusable-data provenance.`);
+    }
+    const note = record.note;
+    if (note !== undefined &&
+        (typeof note !== "string" || note.trim().length === 0)) {
+        throw new InvalidConfigurationError(`${path}.note must be a non-empty string when supplied.`);
+    }
+    return {
+        sourceOrigin: typedOrigin,
+        sourceReference,
+        reuseStatus: typedReuseStatus,
+        ...(license === undefined ? {} : { license }),
+        ...(note === undefined ? {} : { note })
+    };
+}
+/**
+ * Parses a non-empty evidence array.
+ */
+export function parseEvidenceList(value, path) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new InvalidConfigurationError(`${path} must be a non-empty array.`);
+    }
+    return value.map((entry, index) => parseEvidenceProvenance(entry, `${path}[${index}]`));
+}
+//# sourceMappingURL=evidence-provenance.js.map

package/dist/core/evidence-provenance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence-provenance.js","sourceRoot":"","sources":["../../src/core/evidence-provenance.ts"],"names":[],"mappings":"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"}

package/dist/core/image-formation.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Version of the public image-formation ordering contract.
+ *
+ * This version is independent from package, root-engine, and composed-POC
+ * versions. It describes semantic ownership/order only; it does not imply that
+ * every reserved stage is implemented.
+ */
+export declare const IMAGE_FORMATION_CONTRACT_VERSION: "0.2.0";
+export type ImageFormationDomainId = "scene-ray-geometry" | "lens-pupil-throughput" | "field-wavelength-psf" | "temporal-exposure-readout" | "sensor-output-display";
+export type ImageFormationCoordinateSpaceId = "scene-metric" | "image-plane-metric" | "native-sensor-physical" | "native-raster" | "oriented-capture-raster" | "output-raster" | "display";
+export type ImageFormationStageId = "scene-ray-projection" | "lens-field-pupil-evaluation" | "field-wavelength-psf" | "temporal-exposure-readout" | "sensor-optical-stack" | "photosite-cfa-sampling" | "sensor-charge-statistics" | "read-noise-conversion" | "adc-quantization" | "reconstruction" | "physical-orientation-transform" | "output-crop-resample" | "display-processing";
+export type ImageFormationImplementationStatus = "existing-foundation" | "partial-foundation" | "reserved-contract";
+export type ImageFormationEffectId = "focus-breathing" | "geometric-distortion" | "lateral-chromatic-aberration" | "illumination-vignetting" | "mechanical-vignetting" | "non-circular-diffraction" | "field-curvature" | "field-sharpness-falloff" | "field-dependent-bokeh" | "spatial-camera-rotation" | "rolling-readout" | "photosite-cfa-sampling" | "photon-charge-statistics" | "read-noise-conversion" | "demosaic-remosaic";
+export interface ImageFormationCoordinateSpaceContract {
+    id: ImageFormationCoordinateSpaceId;
+    unit: "m" | "mm" | "px" | "display-dependent";
+    origin: string;
+    axes: string;
+    note: string;
+}
+export interface ImageFormationStageContract {
+    id: ImageFormationStageId;
+    domain: ImageFormationDomainId;
+    status: ImageFormationImplementationStatus;
+    coordinateSpaces: readonly ImageFormationCoordinateSpaceId[];
+    requiredUpstreamStages: readonly ImageFormationStageId[];
+    coupledStages: readonly ImageFormationStageId[];
+    purpose: string;
+}
+export interface ImageFormationEffectPlacement {
+    id: ImageFormationEffectId;
+    primaryStage: ImageFormationStageId;
+    coupledStages: readonly ImageFormationStageId[];
+    note: string;
+}
+export interface ImageFormationTemporalContract {
+    authoritativeTimeUnit: "s";
+    origin: "exposure-start";
+    normalizedTimeIsDerivedOnly: true;
+    exposureDurationAndReadoutTimingAreIndependent: true;
+    globalReadoutDoesNotImplyZeroMotionBlur: true;
+    nativeReadoutDirectionRemainsNativeUnderOrientation: true;
+    note: string;
+}
+export interface ImageFormationRendererContract {
+    geometricWarpSampling: "inverse-map-destination-to-source";
+    alphaRepresentation: "premultiplied";
+    occlusionRule: "preserve-depth-order-across-warps";
+    previewAndReferenceShareScientificContract: true;
+    backendMayApproximateButNotRedefineSemantics: true;
+    note: string;
+}
+export interface ImageFormationContract {
+    version: typeof IMAGE_FORMATION_CONTRACT_VERSION;
+    domains: readonly ImageFormationDomainId[];
+    coordinateSpaces: readonly ImageFormationCoordinateSpaceContract[];
+    stages: readonly ImageFormationStageContract[];
+    effectPlacements: readonly ImageFormationEffectPlacement[];
+    temporal: ImageFormationTemporalContract;
+    renderer: ImageFormationRendererContract;
+    notes: readonly string[];
+}
+/**
+ * Returns the public image-formation ownership/order contract.
+ *
+ * The result is descriptive metadata, not a renderer implementation or an
+ * assertion that every reserved stage is currently available.
+ */
+export declare function getImageFormationContract(): ImageFormationContract;
+//# sourceMappingURL=image-formation.d.ts.map

package/dist/core/image-formation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-formation.d.ts","sourceRoot":"","sources":["../../src/core/image-formation.ts"],"names":[],"mappings":"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"}

package/dist/core/image-formation.js

@@ -0,0 +1,335 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Version of the public image-formation ordering contract.
+ *
+ * This version is independent from package, root-engine, and composed-POC
+ * versions. It describes semantic ownership/order only; it does not imply that
+ * every reserved stage is implemented.
+ */
+export const IMAGE_FORMATION_CONTRACT_VERSION = "0.2.0";
+const DOMAINS = [
+    "scene-ray-geometry",
+    "lens-pupil-throughput",
+    "field-wavelength-psf",
+    "temporal-exposure-readout",
+    "sensor-output-display"
+];
+const COORDINATE_SPACES = [
+    {
+        id: "scene-metric",
+        unit: "m",
+        origin: "scene/camera model defined by the scene or projection contract",
+        axes: "scene/world axes remain owned by the scene/projection contract",
+        note: "Do not reinterpret scene axes as raster axes."
+    },
+    {
+        id: "image-plane-metric",
+        unit: "mm",
+        origin: "optical axis",
+        axes: "+X right, +Y up",
+        note: "This preserves the legacy projected-motion/image-plane convention."
+    },
+    {
+        id: "native-sensor-physical",
+        unit: "mm",
+        origin: "optical axis",
+        axes: "+X right, +Y down in native sensor-facing coordinates",
+        note: "Physical sensor coordinates remain invariant under camera orientation."
+    },
+    {
+        id: "native-raster",
+        unit: "px",
+        origin: "top-left of the native effective image raster",
+        axes: "+X right, +Y down; rectangles use half-open integer extents",
+        note: "Native coordinates remain invariant under physical camera rotation."
+    },
+    {
+        id: "oriented-capture-raster",
+        unit: "px",
+        origin: "top-left after the explicit physical-orientation transform",
+        axes: "+X right, +Y down",
+        note: "This is derived from native coordinates; it never redefines native readout direction."
+    },
+    {
+        id: "output-raster",
+        unit: "px",
+        origin: "top-left of the declared output raster",
+        axes: "+X right, +Y down",
+        note: "Digital crop/resampling does not mutate physical sensor identity."
+    },
+    {
+        id: "display",
+        unit: "display-dependent",
+        origin: "consumer/display contract",
+        axes: "consumer/display contract",
+        note: "Display/tone/UI coordinates are not authoritative camera-science coordinates."
+    }
+];
+const STAGES = [
+    {
+        id: "scene-ray-projection",
+        domain: "scene-ray-geometry",
+        status: "existing-foundation",
+        coordinateSpaces: ["scene-metric", "image-plane-metric"],
+        requiredUpstreamStages: [],
+        coupledStages: ["temporal-exposure-readout"],
+        purpose: "Project scene geometry into the optical image plane while preserving explicit metric geometry and focus-aware projection."
+    },
+    {
+        id: "lens-field-pupil-evaluation",
+        domain: "lens-pupil-throughput",
+        status: "partial-foundation",
+        coordinateSpaces: ["image-plane-metric", "native-sensor-physical"],
+        requiredUpstreamStages: ["scene-ray-projection"],
+        coupledStages: ["field-wavelength-psf"],
+        purpose: "Own focus-dependent framing, geometric field mapping, wavelength/channel field mapping, illumination throughput, and pupil clipping inputs."
+    },
+    {
+        id: "field-wavelength-psf",
+        domain: "field-wavelength-psf",
+        status: "partial-foundation",
+        coordinateSpaces: ["image-plane-metric", "native-sensor-physical"],
+        requiredUpstreamStages: ["lens-field-pupil-evaluation"],
+        coupledStages: ["temporal-exposure-readout"],
+        purpose: "Own field-, depth-, pupil-, and wavelength-dependent point-spread behavior including defocus and diffraction without collapsing independent effects into one undocumented blur scalar."
+    },
+    {
+        id: "temporal-exposure-readout",
+        domain: "temporal-exposure-readout",
+        status: "partial-foundation",
+        coordinateSpaces: ["scene-metric", "image-plane-metric", "native-raster"],
+        requiredUpstreamStages: [
+            "scene-ray-projection",
+            "lens-field-pupil-evaluation",
+            "field-wavelength-psf"
+        ],
+        coupledStages: ["photosite-cfa-sampling"],
+        purpose: "Evaluate time-dependent scene/camera mapping over exposure windows and reserve independent native-sensor readout scheduling for rolling/global capture."
+    },
+    {
+        id: "sensor-optical-stack",
+        domain: "sensor-output-display",
+        status: "reserved-contract",
+        coordinateSpaces: ["native-sensor-physical"],
+        requiredUpstreamStages: ["field-wavelength-psf"],
+        coupledStages: ["photosite-cfa-sampling"],
+        purpose: "Reserve optical low-pass filter, cover-glass, and microlens behavior before photosite/color sampling."
+    },
+    {
+        id: "photosite-cfa-sampling",
+        domain: "sensor-output-display",
+        status: "reserved-contract",
+        coordinateSpaces: ["native-sensor-physical", "native-raster"],
+        requiredUpstreamStages: ["sensor-optical-stack"],
+        coupledStages: ["temporal-exposure-readout"],
+        purpose: "Reserve photosite/CFA spatial sampling while keeping native sensor coordinates and readout timing explicit."
+    },
+    {
+        id: "sensor-charge-statistics",
+        domain: "sensor-output-display",
+        status: "partial-foundation",
+        coordinateSpaces: ["native-raster"],
+        requiredUpstreamStages: [
+            "photosite-cfa-sampling",
+            "temporal-exposure-readout"
+        ],
+        coupledStages: [],
+        purpose: "Reserve photon/electron integration and shot-statistics semantics separately from later electronic read noise."
+    },
+    {
+        id: "read-noise-conversion",
+        domain: "sensor-output-display",
+        status: "partial-foundation",
+        coordinateSpaces: ["native-raster"],
+        requiredUpstreamStages: ["sensor-charge-statistics"],
+        coupledStages: [],
+        purpose: "Reserve electronic read-noise and conversion behavior independently from photon shot statistics."
+    },
+    {
+        id: "adc-quantization",
+        domain: "sensor-output-display",
+        status: "reserved-contract",
+        coordinateSpaces: ["native-raster"],
+        requiredUpstreamStages: ["read-noise-conversion"],
+        coupledStages: [],
+        purpose: "Reserve analog-to-digital conversion, clipping, and quantization after sensor/electronic signal formation."
+    },
+    {
+        id: "reconstruction",
+        domain: "sensor-output-display",
+        status: "reserved-contract",
+        coordinateSpaces: ["native-raster"],
+        requiredUpstreamStages: ["adc-quantization"],
+        coupledStages: [],
+        purpose: "Reserve demosaic/remosaic, binning-aware reconstruction, pixel-shift combination, and related capture-mode processing."
+    },
+    {
+        id: "physical-orientation-transform",
+        domain: "sensor-output-display",
+        status: "existing-foundation",
+        coordinateSpaces: ["native-raster", "oriented-capture-raster"],
+        requiredUpstreamStages: ["reconstruction"],
+        coupledStages: ["temporal-exposure-readout"],
+        purpose: "Transform reconstructed native-raster coordinates into oriented capture coordinates without redefining native sensor/readout coordinates. The coordinate transform primitive already exists independently; this dependency reserves its full-pipeline placement."
+    },
+    {
+        id: "output-crop-resample",
+        domain: "sensor-output-display",
+        status: "existing-foundation",
+        coordinateSpaces: ["oriented-capture-raster", "output-raster"],
+        requiredUpstreamStages: ["physical-orientation-transform"],
+        coupledStages: [],
+        purpose: "Apply digital/output crop and resampling while preserving physical capture identity and explicit axis-aware scale."
+    },
+    {
+        id: "display-processing",
+        domain: "sensor-output-display",
+        status: "reserved-contract",
+        coordinateSpaces: ["output-raster", "display"],
+        requiredUpstreamStages: ["output-crop-resample"],
+        coupledStages: [],
+        purpose: "Reserve tone/display/output processing after camera-science geometry and sampling; this stage must not redefine upstream physical quantities."
+    }
+];
+const EFFECT_PLACEMENTS = [
+    {
+        id: "focus-breathing",
+        primaryStage: "lens-field-pupil-evaluation",
+        coupledStages: ["scene-ray-projection"],
+        note: "Focus breathing changes projection/magnification and must not be implemented as post-output crop or display scaling."
+    },
+    {
+        id: "geometric-distortion",
+        primaryStage: "lens-field-pupil-evaluation",
+        coupledStages: [],
+        note: "Distortion is a field-coordinate mapping, not a blur."
+    },
+    {
+        id: "lateral-chromatic-aberration",
+        primaryStage: "lens-field-pupil-evaluation",
+        coupledStages: ["field-wavelength-psf"],
+        note: "Lateral CA is wavelength/channel-dependent field mapping; wavelength-aware PSF models may share the same spectral basis."
+    },
+    {
+        id: "illumination-vignetting",
+        primaryStage: "lens-field-pupil-evaluation",
+        coupledStages: [],
+        note: "Illumination vignetting changes field-dependent throughput only and is distinct from pupil clipping."
+    },
+    {
+        id: "mechanical-vignetting",
+        primaryStage: "lens-field-pupil-evaluation",
+        coupledStages: ["field-wavelength-psf"],
+        note: "Mechanical/pupil clipping changes both throughput and the effective pupil/PSF, including cat's-eye bokeh."
+    },
+    {
+        id: "non-circular-diffraction",
+        primaryStage: "field-wavelength-psf",
+        coupledStages: ["lens-field-pupil-evaluation"],
+        note: "Non-circular diffraction consumes an explicit pupil representation; preserve the current circular Airy result as a separate model."
+    },
+    {
+        id: "field-curvature",
+        primaryStage: "field-wavelength-psf",
+        coupledStages: [],
+        note: "Field curvature is field-dependent focus/PSF behavior, not geometric distortion."
+    },
+    {
+        id: "field-sharpness-falloff",
+        primaryStage: "field-wavelength-psf",
+        coupledStages: [],
+        note: "Field sharpness must be represented through a defensible field-dependent PSF or related optical model, not a synthetic quality score."
+    },
+    {
+        id: "field-dependent-bokeh",
+        primaryStage: "field-wavelength-psf",
+        coupledStages: ["lens-field-pupil-evaluation"],
+        note: "Field-dependent bokeh may depend on pupil clipping and field position; do not collapse it into aperture blade count alone."
+    },
+    {
+        id: "spatial-camera-rotation",
+        primaryStage: "temporal-exposure-readout",
+        coupledStages: ["scene-ray-projection"],
+        note: "Rotation should be evaluable as a time-parameterized mapping; depth-dependent camera translation is outside the initial rotation model."
+    },
+    {
+        id: "rolling-readout",
+        primaryStage: "temporal-exposure-readout",
+        coupledStages: ["photosite-cfa-sampling", "physical-orientation-transform"],
+        note: "Readout timing is native-sensor timing. Physical orientation changes how native scan direction maps to the scene but does not redefine native coordinates."
+    },
+    {
+        id: "photosite-cfa-sampling",
+        primaryStage: "photosite-cfa-sampling",
+        coupledStages: ["sensor-optical-stack", "temporal-exposure-readout"],
+        note: "CFA/photosite sampling follows the sensor optical stack and participates in the declared exposure/readout schedule."
+    },
+    {
+        id: "photon-charge-statistics",
+        primaryStage: "sensor-charge-statistics",
+        coupledStages: [],
+        note: "Photon/charge statistics remain separate from electronic read noise and require explicit radiometric prerequisites."
+    },
+    {
+        id: "read-noise-conversion",
+        primaryStage: "read-noise-conversion",
+        coupledStages: [],
+        note: "Electronic read noise/conversion is downstream of charge formation and must not alter photon shot-noise semantics."
+    },
+    {
+        id: "demosaic-remosaic",
+        primaryStage: "reconstruction",
+        coupledStages: ["photosite-cfa-sampling"],
+        note: "Reconstruction consumes declared capture-mode/CFA sampling rather than redefining the native photosite layout."
+    }
+];
+const TEMPORAL = {
+    authoritativeTimeUnit: "s",
+    origin: "exposure-start",
+    normalizedTimeIsDerivedOnly: true,
+    exposureDurationAndReadoutTimingAreIndependent: true,
+    globalReadoutDoesNotImplyZeroMotionBlur: true,
+    nativeReadoutDirectionRemainsNativeUnderOrientation: true,
+    note: "Time-parameterized optical/camera mapping should be evaluated in seconds from exposure start. A normalized [0,1] parameter may be derived for algorithms but is not the authoritative physical time. Rolling/global readout timing is separate from local exposure duration."
+};
+const RENDERER = {
+    geometricWarpSampling: "inverse-map-destination-to-source",
+    alphaRepresentation: "premultiplied",
+    occlusionRule: "preserve-depth-order-across-warps",
+    previewAndReferenceShareScientificContract: true,
+    backendMayApproximateButNotRedefineSemantics: true,
+    note: "Renderer implementations may use bounded preview approximations or higher-fidelity reference evaluation, but both consume the same engine-owned parameters. Geometric warps should inverse-sample destination locations to avoid forward-warp holes, preserve premultiplied-alpha semantics, and must not reorder scene occlusion merely because a field warp is applied."
+};
+const NOTES = [
+    "This contract defines scientific ownership, coordinate semantics, and dependency/coupling boundaries. It does not claim that reserved stages are implemented.",
+    "The stage graph is a dependency/ownership graph, not a claim that every physical interaction can be evaluated as one independent serial post-process.",
+    "Independent effects may be combined computationally only when the implementation documents mathematical equivalence and preserves the public stage/effect semantics.",
+    "Generic/parametric virtual-lens models must remain explicitly generic until defensible calibrated data with compatible reuse rights exists."
+];
+/**
+ * Returns the public image-formation ownership/order contract.
+ *
+ * The result is descriptive metadata, not a renderer implementation or an
+ * assertion that every reserved stage is currently available.
+ */
+export function getImageFormationContract() {
+    return {
+        version: IMAGE_FORMATION_CONTRACT_VERSION,
+        domains: [...DOMAINS],
+        coordinateSpaces: COORDINATE_SPACES.map((space) => ({ ...space })),
+        stages: STAGES.map((stage) => ({
+            ...stage,
+            coordinateSpaces: [...stage.coordinateSpaces],
+            requiredUpstreamStages: [...stage.requiredUpstreamStages],
+            coupledStages: [...stage.coupledStages]
+        })),
+        effectPlacements: EFFECT_PLACEMENTS.map((effect) => ({
+            ...effect,
+            coupledStages: [...effect.coupledStages]
+        })),
+        temporal: { ...TEMPORAL },
+        renderer: { ...RENDERER },
+        notes: [...NOTES]
+    };
+}
+//# sourceMappingURL=image-formation.js.map

package/dist/core/image-formation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-formation.js","sourceRoot":"","sources":["../../src/core/image-formation.ts"],"names":[],"mappings":"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"}

package/dist/exposure/exposure.d.ts

@@ -32,6 +32,37 @@ export interface RelativeOpticalExposure {
  * response and therefore must not be interpreted as a photon-count result.
  */
 export declare function calculateRelativeOpticalExposure(input: CalculateRelativeOpticalExposureInput): CalculationResult<RelativeOpticalExposure>;
+export interface CalculateRelativeRenderedExposureInput {
+    aperture: number;
+    shutterSeconds: number;
+    iso: number;
+    referenceAperture: number;
+    referenceShutterSeconds: number;
+    referenceIso: number;
+}
+export interface RelativeRenderedExposure {
+    /** Nominal linear rendering multiplier; 1 equals the reference settings. */
+    factor: number;
+    /** Difference from the reference in stops. Positive means a brighter rendering. */
+    stops: number;
+    /** Image-plane optical exposure ratio before nominal ISO gain. */
+    opticalFactor: number;
+    /** Nominal ISO gain ratio relative to the reference ISO. */
+    isoGainFactor: number;
+}
+/**
+ * Calculates a relative linear rendering exposure from aperture, shutter, and
+ * nominal ISO gain.
+ *
+ * This relation is intended for deterministic educational rendering relative to
+ * a declared reference exposure. ISO is treated as a brightness/gain control;
+ * it does not create photons and this function does not model sensor noise,
+ * clipping, tone mapping, lens transmission, or absolute scene luminance.
+ *
+ * @param input Current and reference aperture/shutter/ISO settings.
+ * @returns Relative rendering factor and stop difference.
+ */
+export declare function calculateRelativeRenderedExposure(input: CalculateRelativeRenderedExposureInput): CalculationResult<RelativeRenderedExposure>;
 export interface CalculateEquivalentIsoInput {
     baseIso: number;
     baseAperture: number;

package/dist/exposure/exposure.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"exposure.d.ts","sourceRoot":"","sources":["../../src/exposure/exposure.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,+BAA+B,CAAC;AAGvC,MAAM,WAAW,8BAA8B;IAC7C,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,8BAA8B,GACpC,iBAAiB,CAAC,MAAM,CAAC,CAU3B;AAED,MAAM,WAAW,qCAAqC;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,uBAAuB;IACtC,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,qCAAqC,GAC3C,iBAAiB,CAAC,uBAAuB,CAAC,CA6B5C;AAED,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,2BAA2B,GACjC,iBAAiB,CAAC,MAAM,CAAC,CAuB3B"}
+{"version":3,"file":"exposure.d.ts","sourceRoot":"","sources":["../../src/exposure/exposure.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,iBAAiB,EACvB,MAAM,+BAA+B,CAAC;AAGvC,MAAM,WAAW,8BAA8B;IAC7C,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,8BAA8B,GACpC,iBAAiB,CAAC,MAAM,CAAC,CAU3B;AAED,MAAM,WAAW,qCAAqC;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,uBAAuB,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,uBAAuB;IACtC,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,qCAAqC,GAC3C,iBAAiB,CAAC,uBAAuB,CAAC,CA6B5C;AAED,MAAM,WAAW,sCAAsC;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,iBAAiB,EAAE,MAAM,CAAC;IAC1B,uBAAuB,EAAE,MAAM,CAAC;IAChC,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,wBAAwB;IACvC,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,mFAAmF;IACnF,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,sCAAsC,GAC5C,iBAAiB,CAAC,wBAAwB,CAAC,CA6B7C;AAED,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,2BAA2B,GACjC,iBAAiB,CAAC,MAAM,CAAC,CAuB3B"}

package/dist/exposure/exposure.js

@@ -37,6 +37,41 @@ export function calculateRelativeOpticalExposure(input) {
         "Sensor response is not modeled"
     ]);
 }
+/**
+ * Calculates a relative linear rendering exposure from aperture, shutter, and
+ * nominal ISO gain.
+ *
+ * This relation is intended for deterministic educational rendering relative to
+ * a declared reference exposure. ISO is treated as a brightness/gain control;
+ * it does not create photons and this function does not model sensor noise,
+ * clipping, tone mapping, lens transmission, or absolute scene luminance.
+ *
+ * @param input Current and reference aperture/shutter/ISO settings.
+ * @returns Relative rendering factor and stop difference.
+ */
+export function calculateRelativeRenderedExposure(input) {
+    requirePositiveFinite("iso", input.iso);
+    requirePositiveFinite("referenceIso", input.referenceIso);
+    const optical = calculateRelativeOpticalExposure({
+        aperture: input.aperture,
+        shutterSeconds: input.shutterSeconds,
+        referenceAperture: input.referenceAperture,
+        referenceShutterSeconds: input.referenceShutterSeconds
+    });
+    const isoGainFactor = input.iso / input.referenceIso;
+    const factor = optical.value.factor * isoGainFactor;
+    return calculatedResult({
+        factor,
+        stops: Math.log2(factor),
+        opticalFactor: optical.value.factor,
+        isoGainFactor
+    }, "relative-rendered-exposure", "1.0.0", [
+        "Constant scene illumination",
+        "ISO is treated as nominal rendering gain, not photon creation",
+        "Lens transmission and sensor-specific gain behavior are not modeled",
+        "Clipping and display tone mapping are not modeled"
+    ]);
+}
 /**
  * Calculates the ISO/gain setting that preserves nominal rendered exposure
  * after changing aperture and/or shutter, assuming all other factors remain