@photivra/engine 0.6.0 → 1.0.1

package/docs/api/schema-illumination-spectral.md

@@ -0,0 +1,77 @@
+# schema/illumination-spectral.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [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.
+
+## createSceneIlluminationSpectralCoverageParticipant
+
+Adapts a continuous scene-illumination spectrum into the shared spectral
+coverage contract.
+
+Discrete-line spectra intentionally use their own measure path and are never
+broadened into continuous breakpoints.
+
+```ts
+export function createSceneIlluminationSpectralCoverageParticipant(
+  input:
+    CreateSceneIlluminationSpectralCoverageParticipantInput
+): SpectralCoverageParticipant;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CreateSceneIlluminationSpectralCoverageParticipantInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CreateSceneIlluminationSpectralCoverageParticipantInput {
+  source: SceneIlluminationSource;
+  participantId?: string;
+}
+```
+
+## resolveSceneIlluminationDiscreteLineMeasure
+
+Resolves a discrete illumination spectrum into integrated per-line source
+quantities.
+
+Relative line weights are fractions of the declared wavelength-integrated
+source magnitude. A disabled source resolves to zero contribution. This
+helper does not evaluate visibility, material response, transport, outgoing
+scene radiance, optics, or sensor response.
+
+```ts
+export function resolveSceneIlluminationDiscreteLineMeasure(
+  source:
+    SceneIlluminationSource
+): SceneIlluminationDiscreteLineMeasure;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SceneIlluminationDiscreteLineMeasure
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SceneIlluminationDiscreteLineMeasure {
+  sourceId: string;
+  sourceFamily:
+    SceneIlluminationSource["family"];
+  sourceEnabled: boolean;
+  spectrumId: string;
+  magnitudeKind:
+    SceneIlluminationSource["magnitude"]["kind"];
+  magnitudeScientificStatus:
+    SceneIlluminationScientificStatus;
+  spectrumScientificStatus:
+    "calibrated-relative-lines" |
+    "approximation";
+  measure: DiscreteSpectralLineMeasure;
+  combinedUncertaintyCalculated: false;
+  calibratedAbsoluteLineClaimAuthorized:
+    false;
+  materialTransportApplied: false;
+  sceneRadianceCalculated: false;
+}
+```

package/docs/api/schema-illumination-temporal.md

@@ -0,0 +1,289 @@
+# schema/illumination-temporal.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [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.
+
+## evaluateSceneIlluminationTemporalMultiplier
+
+Evaluates one explicitly registered time-varying source multiplier at one
+physical capture time.
+
+Capture time is seconds from the first opening-boundary phase. Sensor data
+readout timing is not used as a time surrogate.
+
+```ts
+export function evaluateSceneIlluminationTemporalMultiplier(
+  input:
+    EvaluateSceneIlluminationTemporalMultiplierInput
+): SceneIlluminationTemporalMultiplierEvaluation;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## EvaluateSceneIlluminationTemporalMultiplierInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface EvaluateSceneIlluminationTemporalMultiplierInput {
+  illuminationProfile:
+    SceneIlluminationProfile;
+  temporalProfile:
+    SceneIlluminationTemporalProfile;
+  sourceId: string;
+  captureTimeSecondsFromReference: number;
+}
+```
+
+## IntegrateSceneIlluminationTemporalMultiplierInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface IntegrateSceneIlluminationTemporalMultiplierInput {
+  illuminationProfile:
+    SceneIlluminationProfile;
+  temporalProfile:
+    SceneIlluminationTemporalProfile;
+  sourceId: string;
+  exposureWindows: CaptureExposureWindows;
+  sampleIndex: number;
+  temporalSampleCount: number;
+}
+```
+
+## integrateSceneIlluminationTemporalMultiplierOverExposureWindow
+
+Integrates one time-varying source multiplier over one authoritative local
+exposure window from #12 using deterministic midpoint quadrature.
+
+This integrates relative temporal modulation only. It does not apply source
+magnitude, scene transport, optics, sensor response, or metering policy.
+
+```ts
+export function integrateSceneIlluminationTemporalMultiplierOverExposureWindow(
+  input:
+    IntegrateSceneIlluminationTemporalMultiplierInput
+): SceneIlluminationTemporalExposureIntegration;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseSceneIlluminationTemporalProfile
+
+Parses time-varying illumination metadata as an additive overlay on one
+existing illumination profile.
+
+The base source magnitude/spectrum remain authoritative. Each binding applies
+one relative temporal multiplier waveform to one source. Unbound sources
+remain time-invariant.
+
+```ts
+export function parseSceneIlluminationTemporalProfile(
+  value: unknown
+): SceneIlluminationTemporalProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SCENE_ILLUMINATION_TEMPORAL_PROFILE_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+SCENE_ILLUMINATION_TEMPORAL_PROFILE_SCHEMA_VERSION =
+  "0.1.0" as const
+```
+
+## SceneIlluminationTemporalExposureIntegration
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SceneIlluminationTemporalExposureIntegration {
+  sourceId: string;
+  sourceEnabled: boolean;
+  temporalProfileId: string;
+  bindingId: string;
+  waveformId: string;
+  timeReference:
+    "first-opening-boundary-phase";
+  localExposureWindow: {
+    startSecondsFromCaptureReference: number;
+    endSecondsFromCaptureReference: number;
+    durationSeconds: number;
+  };
+  quadratureScheme: "uniform-midpoint";
+  temporalSampleCount: number;
+  nodes:
+    readonly SceneIlluminationTemporalIntegrationNode[];
+  averageRelativeMagnitudeMultiplier:
+    number;
+  integratedRelativeMagnitudeSeconds:
+    number;
+  averageEffectiveRelativeMagnitudeMultiplier:
+    number;
+  integratedEffectiveRelativeMagnitudeSeconds:
+    number;
+  sourceMagnitudeApplied: false;
+  materialTransportApplied: false;
+  sceneRadianceCalculated: false;
+  sensorReadoutTimingUsed: false;
+  automaticExposureResolved: false;
+  convergenceErrorEstimated: false;
+}
+```
+
+## SceneIlluminationTemporalIntegrationNode
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SceneIlluminationTemporalIntegrationNode {
+  temporalSampleIndex: number;
+  localExposurePhase: number;
+  captureTimeSecondsFromReference: number;
+  waveformTimeSecondsFromWaveformReference:
+    number;
+  relativeMagnitudeMultiplier: number;
+  effectiveRelativeMagnitudeMultiplier:
+    number;
+  normalizedTimeWeight: number;
+  timeMeasureSeconds: number;
+}
+```
+
+## SceneIlluminationTemporalMultiplierEvaluation
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SceneIlluminationTemporalMultiplierEvaluation {
+  sourceId: string;
+  sourceEnabled: boolean;
+  temporalProfileId: string;
+  bindingId: string;
+  waveformId: string;
+  captureTimeReference:
+    "first-opening-boundary-phase";
+  captureTimeSecondsFromReference: number;
+  waveformTimeSecondsFromWaveformReference:
+    number;
+  waveformKind:
+    SceneIlluminationTemporalWaveform["kind"];
+  relativeMagnitudeMultiplier: number;
+  effectiveRelativeMagnitudeMultiplier:
+    number;
+  sourceMagnitudeApplied: false;
+  materialTransportApplied: false;
+  sceneRadianceCalculated: false;
+  sensorReadoutTimingUsed: false;
+  automaticExposureResolved: false;
+}
+```
+
+## SceneIlluminationTemporalProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SceneIlluminationTemporalProfile {
+  schemaVersion:
+    typeof SCENE_ILLUMINATION_TEMPORAL_PROFILE_SCHEMA_VERSION;
+  profileId: string;
+  sceneId: string;
+  illuminationProfileId: string;
+  evidence: readonly EvidenceProvenance[];
+  waveforms:
+    readonly SceneIlluminationTemporalWaveform[];
+  sourceBindings:
+    readonly SceneIlluminationTemporalSourceBinding[];
+  baseIlluminationProfileRemainsAuthoritative:
+    true;
+  sensorReadoutTimingUsedAsExposureTiming:
+    false;
+  automaticExposurePolicyIncluded: false;
+}
+```
+
+## SceneIlluminationTemporalRegistrationUncertainty
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SceneIlluminationTemporalRegistrationUncertainty =
+  | {
+      kind: "absolute-seconds";
+      plusMinusSeconds: number;
+      basis: string;
+    }
+  | {
+      kind: "not-quantified";
+      limitation: string;
+    };
+```
+
+## SceneIlluminationTemporalScientificStatus
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SceneIlluminationTemporalScientificStatus =
+  | "calibrated"
+  | "approximation";
+```
+
+## SceneIlluminationTemporalSourceBinding
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SceneIlluminationTemporalSourceBinding {
+  bindingId: string;
+  sourceId: string;
+  waveformId: string;
+  captureTimeReference:
+    "first-opening-boundary-phase";
+  /**
+   * Capture-reference time at which waveform-local t=0 occurs.
+   *
+   * waveformTime = captureTime - waveformTimeZeroSecondsFromCaptureReference
+   */
+  waveformTimeZeroSecondsFromCaptureReference:
+    number;
+  scientificStatus:
+    SceneIlluminationTemporalScientificStatus;
+  timingUncertainty:
+    SceneIlluminationTemporalRegistrationUncertainty;
+  evidence: readonly EvidenceProvenance[];
+}
+```
+
+## SceneIlluminationTemporalWaveform
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SceneIlluminationTemporalWaveform =
+  | (SceneIlluminationTemporalWaveformBase & {
+      kind:
+        "aperiodic-relative-multiplier";
+      outsideSupportBehavior: "zero";
+    })
+  | (SceneIlluminationTemporalWaveformBase & {
+      kind:
+        "periodic-relative-multiplier";
+      periodSeconds: number;
+      endpointContinuityRequired: true;
+    });
+```
+
+## SceneIlluminationTemporalWaveformSample
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SceneIlluminationTemporalWaveformSample {
+  timeSecondsFromWaveformReference: number;
+  relativeMagnitudeMultiplier: number;
+}
+```

package/docs/api/schema-illumination.md

@@ -0,0 +1,246 @@
+# schema/illumination.ts public contracts
+
+Package **1.0.1**, root API **1.0.1**. [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.
+
+## parseSceneIlluminationProfile
+
+Parses a renderer-independent scene illumination profile.
+
+The result describes illumination sources only. It does not calculate
+outgoing scene radiance, apply material response, evaluate visibility or
+indirect transport, or authorize downstream photon/electron claims.
+
+```ts
+export function parseSceneIlluminationProfile(
+  value: unknown
+): SceneIlluminationProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SCENE_ILLUMINATION_PROFILE_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+SCENE_ILLUMINATION_PROFILE_SCHEMA_VERSION = "0.1.0" as const
+```
+
+## SceneIlluminationMagnitude
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SceneIlluminationMagnitude =
+  | {
+      kind: "relative-linear-scale";
+      scale: number;
+      scientificStatus: "approximation";
+      limitation: string;
+    }
+  | {
+      kind: "radiant-intensity";
+      wattsPerSteradian: number;
+      scientificStatus: SceneIlluminationScientificStatus;
+      uncertainty: SceneIlluminationUncertainty;
+      evidence: readonly EvidenceProvenance[];
+    }
+  | {
+      kind: "surface-radiance";
+      wattsPerSquareMeterSteradian: number;
+      scientificStatus: SceneIlluminationScientificStatus;
+      uncertainty: SceneIlluminationUncertainty;
+      evidence: readonly EvidenceProvenance[];
+    }
+  | {
+      kind: "reference-plane-irradiance";
+      wattsPerSquareMeter: number;
+      referencePlaneId: string;
+      scientificStatus: SceneIlluminationScientificStatus;
+      uncertainty: SceneIlluminationUncertainty;
+      evidence: readonly EvidenceProvenance[];
+    };
+```
+
+## SceneIlluminationProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SceneIlluminationProfile {
+  schemaVersion:
+    typeof SCENE_ILLUMINATION_PROFILE_SCHEMA_VERSION;
+  profileId: string;
+  sceneId: string;
+  evidence: readonly EvidenceProvenance[];
+  sources: readonly SceneIlluminationSource[];
+  sceneRadianceCalculated: false;
+  materialResponseApplied: false;
+  visibilityEvaluated: false;
+  indirectTransportEvaluated: false;
+  fluorescenceModeled: false;
+  volumetricTransportModeled: false;
+  polarizationModeled: false;
+}
+```
+
+## SceneIlluminationRelativeSpectrumSample
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SceneIlluminationRelativeSpectrumSample {
+  wavelengthNanometers: number;
+  relativeDensityPerNanometer: number;
+}
+```
+
+## SceneIlluminationScientificStatus
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SceneIlluminationScientificStatus =
+  | "calibrated"
+  | "approximation";
+```
+
+## SceneIlluminationSource
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SceneIlluminationSource {
+  sourceId: string;
+  family: SceneIlluminationSourceFamily;
+  enabled: boolean;
+  geometry: SceneIlluminationSourceGeometry;
+  magnitude: SceneIlluminationMagnitude;
+  spectrum: SceneIlluminationSpectrum;
+  temporalBehavior: {
+    kind: "time-invariant";
+  };
+  evidence: readonly EvidenceProvenance[];
+  limitations?: readonly string[];
+}
+```
+
+## SceneIlluminationSourceFamily
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SceneIlluminationSourceFamily =
+  | "point"
+  | "spot"
+  | "area"
+  | "directional"
+  | "environment";
+```
+
+## SceneIlluminationSourceGeometry
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SceneIlluminationSourceGeometry =
+  | {
+      kind: "point-position";
+      positionM: Vector3;
+    }
+  | {
+      kind: "scene-object-binding";
+      sceneObjectId: string;
+    }
+  | {
+      kind: "spot";
+      origin:
+        | {
+            kind: "point-position";
+            positionM: Vector3;
+          }
+        | {
+            kind: "scene-object-binding";
+            sceneObjectId: string;
+          };
+      directionUnitVector: Vector3;
+      outerConeAngleDegrees: number;
+    }
+  | {
+      kind: "directional";
+      directionUnitVector: Vector3;
+    }
+  | {
+      kind: "environment";
+    };
+```
+
+## SceneIlluminationSpectrum
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SceneIlluminationSpectrum =
+  | {
+      kind: "unresolved";
+      limitation: string;
+    }
+  | {
+      kind: "rgb-preview-approximation";
+      colorSpace: "linear-srgb";
+      red: number;
+      green: number;
+      blue: number;
+      limitation: string;
+    }
+  | {
+      kind: "blackbody-temperature-approximation";
+      temperatureKelvin: number;
+      limitation: string;
+    }
+  | {
+      kind: "continuous-relative-spectrum";
+      spectrumId: string;
+      wavelengthUnit: "nm";
+      wavelengthBasis: SpectralWavelengthBasis;
+      interpolation: "piecewise-linear";
+      outsideRangeBehavior: "fail-closed";
+      normalization: "arbitrary-relative-scale";
+      scientificStatus:
+        | "calibrated-relative-shape"
+        | "approximation";
+      uncertainty: SceneIlluminationUncertainty;
+      evidence: readonly EvidenceProvenance[];
+      samples:
+        readonly SceneIlluminationRelativeSpectrumSample[];
+    }
+  | {
+      kind: "discrete-relative-lines";
+      spectrumId: string;
+      wavelengthUnit: "nm";
+      scientificStatus:
+        | "calibrated-relative-lines"
+        | "approximation";
+      uncertainty: SceneIlluminationUncertainty;
+      evidence: readonly EvidenceProvenance[];
+      distribution:
+        NormalizedDiscreteSpectralLineDistribution;
+    };
+```
+
+## SceneIlluminationUncertainty
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SceneIlluminationUncertainty =
+  | {
+      kind: "relative";
+      fraction: number;
+      basis: string;
+    }
+  | {
+      kind: "not-quantified";
+      limitation: string;
+    };
+```