@photivra/engine 1.4.0 → 2.0.0

package/docs/api/core-spectral.md

@@ -1,10 +1,10 @@
 # core/spectral.ts public contracts
 
-Package **1.4.0**, root API **1.4.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## parseSpectralWavelengthBasis
 
-Parses a wavelength basis without inferring air/vacuum conversion.
+Parses a wavelength basis. It never converts between air and vacuum.
 
 ```ts
 export function parseSpectralWavelengthBasis(
@@ -43,11 +43,11 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## SpectralWavelengthBasis
 
-Explicit wavelength coordinate basis used by renderer-neutral spectral data.
+Whether wavelengths are measured in air or in vacuum.
 
-"unspecified" is permitted only where a downstream contract explicitly
-allows unresolved/approximate wavelength coordinates. Calibrated physical
-composition must resolve the basis before use.
+"unspecified" is allowed only where a downstream contract explicitly accepts
+unresolved or approximate wavelengths. Calibrated physical calculations must
+resolve the basis first.
 
 ```ts
 export type SpectralWavelengthBasis =

package/docs/api/core-validation.md

@@ -1,6 +1,6 @@
 # core/validation.ts public contracts
 
-Package **1.4.0**, root API **1.4.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## InvalidScientificInputError
 
@@ -19,8 +19,8 @@ export class InvalidScientificInputError extends RangeError {
 
 ## InvalidScientificResultError
 
-Error thrown when a scientific calculation would return a non-finite
-numeric value that is unsafe for JSON and downstream consumers.
+Error thrown when a calculation would return a non-finite number (NaN or ±Infinity).
+Such values cannot be stored in JSON and break downstream consumers.
 
 ```ts
 export class InvalidScientificResultError extends RangeError {

package/docs/api/core-version.md

@@ -1,14 +1,15 @@
 # core/version.ts public contracts
 
-Package **1.4.0**, root API **1.4.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## ENGINE_API_VERSION
 
-Version of the public root-engine release, aligned with the npm package since 1.0.1.
-New captures and plans record this creator identity; archived records retain theirs.
-POC, schema and model contracts keep their independent versions.
-Release checks enforce equality with package.json and the packed distribution.
+Version of the engine release. Since 1.0.1 it equals the npm package version.
+
+New captures and plans record this version as their creator. Archived records keep the
+version they were made with. Proof-of-concept (POC), schema and model contracts have their
+own versions. Release checks confirm it matches package.json and the packed package.
 
 ```ts
-ENGINE_API_VERSION = "1.4.0" as const
+ENGINE_API_VERSION = "2.0.0" as const
 ```

package/docs/api/equipment-exposure-capabilities.md

@@ -1,6 +1,6 @@
 # equipment/exposure-capabilities.ts public contracts
 
-Package **1.4.0**, root API **1.4.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## FocalLengthFNumberSample
 
@@ -125,9 +125,9 @@ export type NumericSettingGrid =
 
 Parses a generic Photivra body exposure-capability profile.
 
-This is capability metadata only. ISO values do not imply noise/gain
-topology, and shutter-duration capability does not imply one shutter
-mechanism or sensor-readout schedule.
+This is capability metadata only. ISO values say nothing about how noise or
+gain is implemented. Shutter-duration capability does not imply a
+particular shutter mechanism or sensor-readout schedule.
 
 ```ts
 export function parseGenericBodyExposureCapabilityProfile(
@@ -141,8 +141,8 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 Parses a generic Photivra lens exposure-capability profile.
 
-"Widest" is expressed as the smallest available f-number, avoiding the
-ambiguous phrases minimum/maximum aperture.
+"Widest" means the smallest available f-number. This avoids the ambiguous
+phrases "minimum aperture" and "maximum aperture".
 
 ```ts
 export function parseGenericLensExposureCapabilityProfile(
@@ -190,8 +190,8 @@ export interface ResolvedGenericEquipmentExposureCapabilities {
     autoIsoAvailability:
       GenericCapabilityAvailability;
     /**
-     * Optional Auto-ISO-only bounds. Manual ISO continues to use minimum /
-     * maximum and the complete standard setting grid.
+     * Optional bounds that apply only to Auto ISO. Manual ISO still uses the
+     * minimum, the maximum and the complete standard setting grid.
      */
     autoIsoMinimum?: number;
     autoIsoMaximum?: number;
@@ -222,8 +222,9 @@ export type ResolvedNumericSettingGrid =
 Resolves the exposure-relevant capability subset for one generic body+lens
 combination at one selected focal length.
 
-Source profiles are immutable inputs. This resolver does not choose exposure
-settings; it only provides the capability envelope consumed by #99.
+The source profiles are not changed. This resolver does not choose exposure
+settings. It only provides the range of available settings (the capability
+envelope) that the exposure-mode resolvers use.
 
 ```ts
 export function resolveGenericEquipmentExposureCapabilities(

package/docs/api/equipment-generic-tier-assets.md

@@ -1,6 +1,6 @@
 # equipment/generic-tier-assets.ts public contracts
 
-Package **1.4.0**, root API **1.4.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## GenericEquipmentTier
 
@@ -18,7 +18,7 @@ The exact contract is declared below; use the domain guide for assumptions and s
 export interface GenericEquipmentTierPreset {
   tier: GenericEquipmentTier;
   label: "Consumer" | "Prosumer" | "Professional";
-  presetId: string; presetVersion: "1.0.0";
+  presetId: string; presetVersion: "2.0.0";
   scientificStatus: "approximation";
   evidence: readonly EvidenceProvenance[];
   body: GenericTierBodyAssets;
@@ -37,7 +37,12 @@ export interface GenericTierBodyAssets {
   iso: IsoCapabilityProfile;
   signalChain: GenericIsoSignalChainProfile;
   readout: readonly GenericVersionedAsset<SensorReadoutConversionProfile>[];
+  /** Global data readout (no skew across the frame). The default timing asset. */
   readoutTiming: GenericVersionedAsset<SensorReadoutTimingDeclaration>;
+  /** Optional rolling readout variant, with an explicit top-to-bottom skew across the frame. */
+  rollingReadoutTiming: GenericVersionedAsset<SensorReadoutTimingDeclaration>;
+  /** Optional synthetic fixed-pattern noise for this body. Never applied unless a caller attaches it. */
+  fixedPatternNoise: GenericVersionedAsset<SensorFixedPatternNoiseProfile>;
   release: GenericReleaseCapabilityProfile;
   focus: FocusControlProfile;
   stabilization: StabilizationSystemProfile;

package/docs/api/equipment-generic-tier-presets.md

@@ -1,10 +1,10 @@
 # equipment/generic-tier-presets.ts public contracts
 
-Package **1.4.0**, root API **1.4.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## createGenericEquipmentTierSelection
 
-Match lens tier by default; cross-tier combinations remain normal supported selections.
+The lens tier matches the body tier by default. Mixing tiers is a normal, supported choice.
 
 ```ts
 export function createGenericEquipmentTierSelection(input: {
@@ -19,7 +19,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 The exact contract is declared below; use the domain guide for assumptions and staged integration.
 
 ```ts
-GENERIC_EQUIPMENT_TIER_PRESET_VERSION = "1.0.0" as const
+GENERIC_EQUIPMENT_TIER_PRESET_VERSION = "2.0.0" as const
 ```
 
 ## GENERIC_EQUIPMENT_TIERS
@@ -54,7 +54,7 @@ export interface GenericEquipmentTierSelection {
 
 ## parseGenericEquipmentTierSelection
 
-Reject stale/missing/retuned profile versions on saved simulations rather than selecting today's defaults.
+On a saved simulation, rejects profile versions that are stale, missing or retuned, instead of picking today's defaults.
 
 ```ts
 export function parseGenericEquipmentTierSelection(value: unknown): GenericEquipmentTierSelection;
@@ -84,7 +84,7 @@ export interface ResolvedGenericTierLensProfiles {
 
 ## resolveGenericEquipmentTierCatalog
 
-Exact-version catalog; no hidden latest alias and no sensor-size default.
+Catalog of exact versions. No hidden "latest" alias and no default sensor size.
 
 ```ts
 export function resolveGenericEquipmentTierCatalog(input: { presetVersion: string }): readonly GenericEquipmentTierPreset[];
@@ -94,7 +94,7 @@ This call is synchronous; any supplied provider must follow its explicit synchro
 
 ## resolveGenericEquipmentTierLensProfiles
 
-Bind the finite matched-reference optical slice to one exact generic selected state, without extrapolation.
+Ties the finite matched-reference optical data to one exact generic selected state. Never extrapolates.
 
 ```ts
 export function resolveGenericEquipmentTierLensProfiles(input: { selection: GenericEquipmentTierSelection; state: OpticalProfileState }): ResolvedGenericTierLensProfiles;

package/docs/api/equipment-iso-capabilities.md

@@ -1,17 +1,17 @@
 # equipment/iso-capabilities.ts public contracts
 
-Package **1.4.0**, root API **1.4.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## bindIsoCapabilityToExposureCapabilities
 
-Binds the detailed #7 ISO/EI capability contract into the numeric capability
-envelope consumed by #99.
+Combines the detailed ISO/EI capability profile with the numeric capability
+envelope that the exposure-mode resolvers use.
 
-The existing equipment capability must agree exactly with the profile's
-global standard ISO range/grid. An evidenced capture-mode policy may narrow
-the standard manual envelope for that mode. Auto ISO may then be narrower
-still. Expanded L/H-style settings remain outside #99's ordinary numeric
-ISO grid and are resolved through resolveIsoCapability().
+The existing equipment capability must match the profile's global standard
+ISO range and grid exactly. A capture-mode policy backed by evidence may
+narrow the standard manual range for that mode. Auto ISO may be narrower
+still. Expanded settings (such as L and H) stay outside the resolvers'
+ordinary numeric ISO grid; use resolveIsoCapability() for them.
 
 ```ts
 export function bindIsoCapabilityToExposureCapabilities(
@@ -183,12 +183,12 @@ export type IsoStandardSettingGrid =
 
 ## parseIsoCapabilityProfile
 
-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.
 
-ISO is an exposure-index/control capability, not a source of photons or evidence of read noise.
-Standard/expanded settings, capture-mode restrictions and Auto ISO availability are explicit;
-unknown availability cannot authorize automatic control.
+ISO is an exposure-index (EI) control setting. It does not create photons and says nothing about
+read noise. Standard and expanded settings, limits per capture mode, and whether Auto ISO is
+available are all stated explicitly. If availability is unknown, automatic control is not allowed.
 
 ```ts
 export function parseIsoCapabilityProfile(
@@ -264,12 +264,12 @@ export interface ResolvedIsoCapability {
 
 ## resolveIsoCapability
 
-Resolve one standard/expanded/Auto ISO request under declared profile/capture-mode availability and
-report explicit unavailable/unknown state.
+Resolves one standard, expanded or Auto ISO request against what the profile and capture mode
+declare as available. Reports "unavailable" or "unknown" explicitly.
 
-ISO is an exposure-index/control capability, not a source of photons or evidence of read noise.
-Standard/expanded settings, capture-mode restrictions and Auto ISO availability are explicit;
-unknown availability cannot authorize automatic control.
+ISO is an exposure-index (EI) control setting. It does not create photons and says nothing about
+read noise. Standard and expanded settings, limits per capture mode, and whether Auto ISO is
+available are all stated explicitly. If availability is unknown, automatic control is not allowed.
 
 ```ts
 export function resolveIsoCapability(

package/docs/api/equipment-metering-capabilities.md

@@ -1,13 +1,13 @@
 # equipment/metering-capabilities.ts public contracts
 
-Package **1.4.0**, root API **1.4.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## assessExposureMeteringProfileCompatibility
 
 Checks whether one engine metering profile is selectable on a generic body.
 
-Calibration/target policy remains authoritative in the metering profile and
-is never copied into equipment capability metadata.
+The metering profile stays the single source of its calibration and target
+policy. They are never copied into equipment capability metadata.
 
 ```ts
 export function assessExposureMeteringProfileCompatibility(
@@ -113,9 +113,9 @@ export type MeteringCapabilityCompatibilityBlocker =
 
 Parses generic body metering capability metadata.
 
-This profile declares which engine-owned metering profiles/modes a generic
-body can select. It deliberately does not duplicate target/calibration
-values from those metering profiles.
+This profile declares which of the engine's metering profiles and modes a
+generic body can select. It deliberately does not copy target or
+calibration values from those metering profiles.
 
 ```ts
 export function parseGenericBodyMeteringCapabilityProfile(

package/docs/api/equipment-release-capabilities.md

@@ -1,6 +1,6 @@
 # equipment/release-capabilities.ts public contracts
 
-Package **1.4.0**, root API **1.4.0**. [Navigation](../API_REFERENCE.md) · [Developer guide](../DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
+The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
 ## GENERIC_RELEASE_CAPABILITY_SCHEMA_VERSION
 
@@ -78,9 +78,9 @@ export type GenericReleaseDriveMode =
 
 Parses generic logical-release/drive capabilities.
 
-The first schema deliberately models non-overlapping ordinary still
-exposures only. Buffer/media/thermal slowdown and pre-release capture remain
-outside this profile.
+The first schema deliberately models only ordinary still exposures that do
+not overlap. Slowdown from the buffer, media or heat, and pre-release
+capture, are not part of this profile.
 
 ```ts
 export function parseGenericReleaseCapabilityProfile(