@photivra/engine 0.5.1 → 1.0.0

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

@@ -0,0 +1,270 @@
+# equipment/exposure-capabilities.ts public contracts
+
+Package **1.0.0**, root API **0.116.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.
+
+## FocalLengthFNumberSample
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface FocalLengthFNumberSample {
+  focalLengthMm: number;
+  fNumber: number;
+}
+```
+
+## GENERIC_EQUIPMENT_EXPOSURE_CAPABILITY_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+GENERIC_EQUIPMENT_EXPOSURE_CAPABILITY_SCHEMA_VERSION =
+  "0.1.0" as const
+```
+
+## GenericBodyExposureCapabilityProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GenericBodyExposureCapabilityProfile {
+  schemaVersion:
+    typeof GENERIC_EQUIPMENT_EXPOSURE_CAPABILITY_SCHEMA_VERSION;
+  profileId: string;
+  profileVersion: string;
+  scientificStatus: "approximation";
+  evidence: readonly EvidenceProvenance[];
+  shutter: {
+    durationSecondsRange:
+      EvidenceBackedFact<
+        NumericCapabilityRange
+      >;
+    settingGrid: NumericSettingGrid;
+  };
+  iso: {
+    range:
+      EvidenceBackedFact<
+        NumericCapabilityRange
+      >;
+    settingGrid: NumericSettingGrid;
+    autoIso:
+      EvidenceBackedFact<
+        GenericCapabilityAvailability
+      >;
+  };
+}
+```
+
+## GenericCapabilityAvailability
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type GenericCapabilityAvailability =
+  | "supported"
+  | "unsupported"
+  | "unknown";
+```
+
+## GenericLensExposureCapabilityProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GenericLensExposureCapabilityProfile {
+  schemaVersion:
+    typeof GENERIC_EQUIPMENT_EXPOSURE_CAPABILITY_SCHEMA_VERSION;
+  profileId: string;
+  profileVersion: string;
+  scientificStatus: "approximation";
+  evidence: readonly EvidenceProvenance[];
+  focalLengthMmRange:
+    EvidenceBackedFact<
+      NumericCapabilityRange
+    >;
+  aperture: {
+    widestAvailableFNumber:
+      WidestAvailableFNumberCapability;
+    narrowestAvailableFNumber:
+      EvidenceBackedFact<number>;
+    settingGrid: NumericSettingGrid;
+  };
+}
+```
+
+## NumericCapabilityRange
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NumericCapabilityRange {
+  minimum: number;
+  maximum: number;
+}
+```
+
+## NumericSettingGrid
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type NumericSettingGrid =
+  | {
+      kind: "continuous-within-range";
+    }
+  | {
+      kind: "discrete-values";
+      values:
+        EvidenceBackedFact<
+          readonly number[]
+        >;
+    };
+```
+
+## parseGenericBodyExposureCapabilityProfile
+
+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.
+
+```ts
+export function parseGenericBodyExposureCapabilityProfile(
+  value: unknown
+): GenericBodyExposureCapabilityProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseGenericLensExposureCapabilityProfile
+
+Parses a generic Photivra lens exposure-capability profile.
+
+"Widest" is expressed as the smallest available f-number, avoiding the
+ambiguous phrases minimum/maximum aperture.
+
+```ts
+export function parseGenericLensExposureCapabilityProfile(
+  value: unknown
+): GenericLensExposureCapabilityProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolvedGenericEquipmentExposureCapabilities
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedGenericEquipmentExposureCapabilities {
+  schemaVersion:
+    typeof GENERIC_EQUIPMENT_EXPOSURE_CAPABILITY_SCHEMA_VERSION;
+  scientificStatus: "approximation";
+  bodyProfile: {
+    profileId: string;
+    profileVersion: string;
+  };
+  lensProfile: {
+    profileId: string;
+    profileVersion: string;
+  };
+  selectedFocalLengthMm: number;
+  aperture: {
+    widestAvailableFNumber: number;
+    narrowestAvailableFNumber: number;
+    settingGrid:
+      ResolvedNumericSettingGrid;
+  };
+  shutter: {
+    minimumSeconds: number;
+    maximumSeconds: number;
+    settingGrid:
+      ResolvedNumericSettingGrid;
+  };
+  iso: {
+    minimum: number;
+    maximum: number;
+    settingGrid:
+      ResolvedNumericSettingGrid;
+    autoIsoAvailability:
+      GenericCapabilityAvailability;
+    /**
+     * Optional Auto-ISO-only bounds. Manual ISO continues to use minimum /
+     * maximum and the complete standard setting grid.
+     */
+    autoIsoMinimum?: number;
+    autoIsoMaximum?: number;
+  };
+  sourceProfilesMutated: false;
+  exactNamedEquipmentEmulationClaimed:
+    false;
+}
+```
+
+## ResolvedNumericSettingGrid
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ResolvedNumericSettingGrid =
+  | {
+      kind: "continuous-within-range";
+    }
+  | {
+      kind: "discrete-values";
+      values: readonly number[];
+    };
+```
+
+## resolveGenericEquipmentExposureCapabilities
+
+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.
+
+```ts
+export function resolveGenericEquipmentExposureCapabilities(
+  input:
+    ResolveGenericEquipmentExposureCapabilitiesInput
+): ResolvedGenericEquipmentExposureCapabilities;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolveGenericEquipmentExposureCapabilitiesInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolveGenericEquipmentExposureCapabilitiesInput {
+  bodyProfile:
+    GenericBodyExposureCapabilityProfile;
+  lensProfile:
+    GenericLensExposureCapabilityProfile;
+  selectedFocalLengthMm: number;
+}
+```
+
+## WidestAvailableFNumberCapability
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type WidestAvailableFNumberCapability =
+  | {
+      kind: "constant";
+      fNumber:
+        EvidenceBackedFact<number>;
+    }
+  | {
+      kind:
+        "piecewise-linear-by-focal-length";
+      samples:
+        EvidenceBackedFact<
+          readonly FocalLengthFNumberSample[]
+        >;
+    };
+```

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

@@ -0,0 +1,82 @@
+# equipment/generic-tier-assets.ts public contracts
+
+Package **1.0.0**, root API **0.116.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.
+
+## GenericEquipmentTier
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type GenericEquipmentTier = "consumer" | "prosumer" | "professional";
+```
+
+## GenericEquipmentTierPreset
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GenericEquipmentTierPreset {
+  tier: GenericEquipmentTier;
+  label: "Consumer" | "Prosumer" | "Professional";
+  presetId: string; presetVersion: "1.0.0";
+  scientificStatus: "approximation";
+  evidence: readonly EvidenceProvenance[];
+  body: GenericTierBodyAssets;
+  lens: GenericTierLensAssets;
+  tradeoffs: readonly string[];
+}
+```
+
+## GenericTierBodyAssets
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GenericTierBodyAssets {
+  exposure: GenericBodyExposureCapabilityProfile;
+  iso: IsoCapabilityProfile;
+  signalChain: GenericIsoSignalChainProfile;
+  readout: readonly GenericVersionedAsset<SensorReadoutConversionProfile>[];
+  readoutTiming: GenericVersionedAsset<SensorReadoutTimingDeclaration>;
+  release: GenericReleaseCapabilityProfile;
+  focus: FocusControlProfile;
+  stabilization: StabilizationSystemProfile;
+  whiteBalance: WhiteBalanceProfile;
+  metering: readonly GenericVersionedAsset<ExposureMeteringProfile>[];
+  meteringCapabilities: GenericBodyMeteringCapabilityProfile;
+  flashSync: FlashSyncCapabilityProfile;
+}
+```
+
+## GenericTierLensAssets
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GenericTierLensAssets {
+  form: "prime";
+  exposure: GenericLensExposureCapabilityProfile;
+  /** Explicit synthetic coefficients, not measured calibration or a quality score. */
+  matchedReference: {
+    focalLengthMm: 50; aperture: 4; focusDistanceM: 5; wavelengthNm: 550;
+    normalizationRadiusMm: number;
+    distortionK1: number; lateralCaK1Offset: number; vignettingR2: number;
+    breathingProjectionScale: number; transmission: number;
+    correctionGainStrength: number; correctionCaFraction: number;
+    ghostPowerFraction: number; veilPowerFraction: number;
+    pupilAmplitudeByField: readonly (readonly number[])[];
+    pupilOpdMicrometersByDefocus: readonly (readonly number[])[];
+    pupilThroughputByField: readonly number[];
+  };
+  profileReferences: readonly { profileId: string; profileVersion: string }[];
+  limitations: readonly string[];
+}
+```
+
+## GenericVersionedAsset
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GenericVersionedAsset<T> { assetId: string; assetVersion: string; profile: T }
+```

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

@@ -0,0 +1,103 @@
+# equipment/generic-tier-presets.ts public contracts
+
+Package **1.0.0**, root API **0.116.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.
+
+## createGenericEquipmentTierSelection
+
+Match lens tier by default; cross-tier combinations remain normal supported selections.
+
+```ts
+export function createGenericEquipmentTierSelection(input: {
+  presetVersion: string; bodyTier: GenericEquipmentTier; lensTier?: GenericEquipmentTier;
+}): GenericEquipmentTierSelection;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## GENERIC_EQUIPMENT_TIER_PRESET_VERSION
+
+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_TIERS
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+GENERIC_EQUIPMENT_TIERS = Object.freeze(["consumer", "prosumer", "professional"] as const)
+```
+
+## GenericEquipmentTierProfileReference
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GenericEquipmentTierProfileReference { profileId: string; profileVersion: string }
+```
+
+## GenericEquipmentTierSelection
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface GenericEquipmentTierSelection {
+  schemaVersion: "0.1.0"; presetVersion: typeof GENERIC_EQUIPMENT_TIER_PRESET_VERSION;
+  bodyTier: GenericEquipmentTier; lensTier: GenericEquipmentTier;
+  bodyPresetId: string; lensPresetId: string;
+  profileReferences: readonly GenericEquipmentTierProfileReference[];
+  sensorFormatSelectedByTier: false; scientificTierMultiplierApplied: false;
+}
+```
+
+## parseGenericEquipmentTierSelection
+
+Reject stale/missing/retuned profile versions on saved simulations rather than selecting today's defaults.
+
+```ts
+export function parseGenericEquipmentTierSelection(value: unknown): GenericEquipmentTierSelection;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolvedGenericTierLensProfiles
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ResolvedGenericTierLensProfiles {
+  selection: GenericEquipmentTierSelection;
+  state: OpticalProfileState;
+  radial: RadialDistortionProfile;
+  lateralCa: LateralChromaticAberrationProfile;
+  vignetting: IlluminationVignettingProfile;
+  breathingProjectionScale: number;
+  transmission: SceneToSensorIrradianceProfile;
+  pupils: readonly LensComplexPupilProfile[];
+  stray: LensStrayLightProfile;
+  correction: GenericLensCorrectionProfile;
+  scientificStatus: "approximation";
+}
+```
+
+## resolveGenericEquipmentTierCatalog
+
+Exact-version catalog; no hidden latest alias and no sensor-size default.
+
+```ts
+export function resolveGenericEquipmentTierCatalog(input: { presetVersion: string }): readonly GenericEquipmentTierPreset[];
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## resolveGenericEquipmentTierLensProfiles
+
+Bind the finite matched-reference optical slice to one exact generic selected state, without extrapolation.
+
+```ts
+export function resolveGenericEquipmentTierLensProfiles(input: { selection: GenericEquipmentTierSelection; state: OpticalProfileState }): ResolvedGenericTierLensProfiles;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.