@photivra/engine 0.5.1 → 1.0.0

package/docs/api/schema-scene.md

@@ -0,0 +1,105 @@
+# schema/scene.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.
+
+## SceneCapability
+
+Capabilities intentionally advertised by a scene package.
+
+```ts
+export type SceneCapability =
+  | "scene-linear-rgb"
+  | "metric-depth"
+  | "segmentation"
+  | "occlusion-layers"
+  | "motion-vectors"
+  | "focus-targets"
+  | "multi-resolution-layers"
+  | "absolute-radiometry";
+```
+
+## SceneDefinition
+
+Versioned, renderer-independent description of a curated synthetic scene.
+
+Asset locations are intentionally not part of this scientific schema;
+callers may bind the metadata to their own asset systems separately.
+
+```ts
+export interface SceneDefinition {
+  schemaVersion: string;
+  id: string;
+  version: string;
+  radiometry: SceneRadiometry;
+  capabilities: readonly SceneCapability[];
+  objects: readonly SceneObject[];
+  focusTargetIds?: readonly string[];
+}
+```
+
+## SceneMotion
+
+Motion attached to an independently controllable scene object or region.
+
+```ts
+export interface SceneMotion {
+  /** World-space linear velocity in metres per second. */
+  linearVelocityMps: Vector3;
+  /** Optional world-space angular velocity in radians per second. */
+  angularVelocityRadPerSec?: Vector3;
+}
+```
+
+## SceneObject
+
+Semantic object/region within a curated synthetic scene.
+
+```ts
+export interface SceneObject {
+  id: string;
+  label?: string;
+  /** Representative distance from the camera origin in metres. */
+  distanceM: number;
+  motion?: SceneMotion;
+  tags?: readonly string[];
+}
+```
+
+## SceneRadiometry
+
+Describes how scene-linear image values relate to physical light.
+
+```ts
+export type SceneRadiometry =
+  | {
+      /**
+       * Relative linear values preserve light ratios but are not absolutely
+       * calibrated for photon-count calculations.
+       */
+      kind: "relative-linear";
+      referenceValue: number;
+    }
+  | {
+      /**
+       * Scene package includes an absolute luminance anchor that can support
+       * calibrated photometric exposure work. Luminance alone is not
+       * sufficient to derive photon counts; photon simulation additionally
+       * requires defensible spectral and optical calibration.
+       */
+      kind: "absolute-luminance";
+      referenceValue: number;
+      referenceLuminanceCdM2: number;
+    };
+```
+
+## Vector3
+
+Three-dimensional value in scene/world coordinates.
+
+```ts
+export interface Vector3 {
+  x: number;
+  y: number;
+  z: number;
+}
+```

package/docs/api/schema-validation.md

@@ -0,0 +1,25 @@
+# schema/validation.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.
+
+## parseCameraConfiguration
+
+Parses and validates an untrusted camera configuration.
+
+```ts
+export function parseCameraConfiguration(
+  value: unknown
+): CameraConfiguration;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseSceneDefinition
+
+Parses and validates an untrusted renderer-independent scene definition.
+
+```ts
+export function parseSceneDefinition(value: unknown): SceneDefinition;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/docs/api/sensor-accumulated-charge.md

@@ -0,0 +1,273 @@
+# sensor/accumulated-charge.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.
+
+## composeSensorAccumulatedCharge
+
+Compose photo, independently evaluated dark and explicitly incremental charge by exact local
+exposure identity, retaining completeness assessment before capacity/noise.
+
+Photo, dark and explicitly incremental stored-electron components must share the exact
+site/channel/local shutter event. Completeness is an evidence-backed declaration, not the
+consequence of an empty component array. Expected stored charge remains distinct from a stochastic
+realization or nonlinear full-well clamp.
+
+```ts
+export function composeSensorAccumulatedCharge(
+  input: Omit<ComposeSensorAccumulatedChargeInput, "photoSignal" | "darkCharge"> & {
+    photoSignal: SensorEqeExposureIntegration; darkCharge: SensorDarkCurrentCharge;
+  }
+): CalculationResult<SensorAccumulatedChargeComposition>;
+```
+
+```ts
+export function composeSensorAccumulatedCharge(
+  input: Omit<ComposeSensorAccumulatedChargeInput, "photoSignal" | "darkCharge"> & {
+    photoSignal: SensorEqeTemporalPhotoSignal; darkCharge: SensorTemporalDarkCurrentCharge;
+  }
+): CalculationResult<SensorAccumulatedChargeComposition<SensorEqeTemporalPhotoSignal, SensorTemporalDarkCurrentCharge>>;
+```
+
+```ts
+export function composeSensorAccumulatedCharge(
+  input: ComposeSensorPhotoAccumulatedChargeInput
+): CalculationResult<SensorPhotoAccumulatedChargeComposition>;
+```
+
+```ts
+export function composeSensorAccumulatedCharge(
+  input: ComposeSensorPhotoAccumulatedChargeInput
+): CalculationResult<SensorPhotoAccumulatedChargeComposition>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ComposeSensorAccumulatedChargeInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ComposeSensorAccumulatedChargeInput<
+  Photo extends SensorEqePhotoExposure = SensorEqeExposureIntegration,
+  Dark extends SensorPhotoDarkCurrentCharge = SensorDarkCurrentCharge
+> {
+  photoSignal:
+    Photo;
+  darkCharge:
+    Dark;
+  additionalChargeComponents?:
+    readonly SensorAdditionalStoredChargeComponent[];
+  completenessProfile:
+    SensorAccumulatedChargeCompletenessProfile;
+}
+```
+
+## ComposeSensorPhotoAccumulatedChargeInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ComposeSensorPhotoAccumulatedChargeInput = ComposeSensorAccumulatedChargeInput<SensorEqePhotoExposure, SensorPhotoDarkCurrentCharge>;
+```
+
+## parseSensorAccumulatedChargeCompletenessProfile
+
+Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data fail at this boundary.
+
+Photo, dark and explicitly incremental stored-electron components must share the exact
+site/channel/local shutter event. Completeness is an evidence-backed declaration, not the
+consequence of an empty component array. Expected stored charge remains distinct from a stochastic
+realization or nonlinear full-well clamp.
+
+```ts
+export function parseSensorAccumulatedChargeCompletenessProfile(
+  value: unknown
+): SensorAccumulatedChargeCompletenessProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseSensorAdditionalStoredChargeComponent
+
+Validate an untrusted declaration and return the normalized typed contract. Unknown enum values,
+missing required fields and incompatible scientific data fail at this boundary.
+
+Photo, dark and explicitly incremental stored-electron components must share the exact
+site/channel/local shutter event. Completeness is an evidence-backed declaration, not the
+consequence of an empty component array. Expected stored charge remains distinct from a stochastic
+realization or nonlinear full-well clamp.
+
+```ts
+export function parseSensorAdditionalStoredChargeComponent(
+  value: unknown
+): SensorAdditionalStoredChargeComponent;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SensorAccumulatedChargeCompletenessProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorAccumulatedChargeCompletenessProfile {
+  schemaVersion: "0.1.0";
+  profileId: string;
+  colorSamplingProfileId: string;
+  channelId: string;
+  site: {
+    x: number;
+    y: number;
+  };
+  bindingId: string;
+  timeReference:
+    "first-opening-boundary-phase";
+  startOffsetSecondsFromOpeningReference:
+    number;
+  endOffsetSecondsFromOpeningReference:
+    number;
+  darkCurrentProfileId: string;
+  includedAdditionalComponentIds:
+    readonly string[];
+  coverageMeaning:
+    "all-material-stored-electron-contributors-accounted-for";
+  scientificStatus:
+    SensorSpectralResponseScientificStatus;
+  evidence:
+    readonly EvidenceProvenance[];
+  limitation?: string;
+}
+```
+
+## SensorAccumulatedChargeComposition
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorAccumulatedChargeComposition<
+  Photo extends SensorEqePhotoExposure = SensorEqeExposureIntegration,
+  Dark extends SensorPhotoDarkCurrentCharge = SensorDarkCurrentCharge
+> {
+  completenessProfileId: string;
+  colorSamplingProfileId: string;
+  channelId: string;
+  site: {
+    x: number;
+    y: number;
+  };
+  bindingId: string;
+  timeReference:
+    "first-opening-boundary-phase";
+  startOffsetSecondsFromOpeningReference:
+    number;
+  endOffsetSecondsFromOpeningReference:
+    number;
+  localExposureDurationSeconds:
+    number;
+  photoExpectedElectronCount:
+    number;
+  darkExpectedElectronCount:
+    number;
+  additionalExpectedElectronCount:
+    number;
+  totalExpectedStoredElectronCount:
+    number;
+  additionalComponents:
+    readonly {
+      componentId: string;
+      kind:
+        SensorAdditionalStoredChargeKind;
+      expectedElectronCount: number;
+      scientificStatus:
+        SensorSpectralResponseScientificStatus;
+      uncertainty:
+        SensorSpectralResponseUncertainty;
+      evidence:
+        readonly EvidenceProvenance[];
+    }[];
+  accumulatedChargeCompleteness:
+    "complete-for-physical-storage-capacity-assessment";
+  completenessScientificStatus:
+    SensorSpectralResponseScientificStatus;
+  allCountsAreExpectationValues: true;
+  integerChargeSampled: false;
+  photoSignalIncluded: true;
+  darkChargeIncluded: true;
+  otherChargeIncluded: boolean;
+  darkShotNoiseApplied: false;
+  photoShotNoiseApplied: false;
+  readNoiseApplied: false;
+  physicalFullWellAssessmentAuthorized:
+    true;
+  cameraSaturationAssessmentAuthorized:
+    false;
+  saturationAssessed: false;
+  bloomingModeled: false;
+  adcQuantizationApplied: false;
+  rawCodeValueProduced: false;
+  componentEvidence: {
+    completeness:
+      readonly EvidenceProvenance[];
+    photoSignal:
+      Photo["componentEvidence"];
+    darkCurrent:
+      Dark["componentEvidence"];
+  };
+}
+```
+
+## SensorAdditionalStoredChargeComponent
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SensorAdditionalStoredChargeComponent {
+  componentId: string;
+  kind:
+    SensorAdditionalStoredChargeKind;
+  colorSamplingProfileId: string;
+  channelId: string;
+  site: {
+    x: number;
+    y: number;
+  };
+  bindingId: string;
+  timeReference:
+    "first-opening-boundary-phase";
+  startOffsetSecondsFromOpeningReference:
+    number;
+  endOffsetSecondsFromOpeningReference:
+    number;
+  accountingMeaning:
+    "incremental-stored-electrons-beyond-photo-and-modeled-dark-current";
+  expectedElectronCount: number;
+  scientificStatus:
+    SensorSpectralResponseScientificStatus;
+  uncertainty:
+    SensorSpectralResponseUncertainty;
+  evidence:
+    readonly EvidenceProvenance[];
+}
+```
+
+## SensorAdditionalStoredChargeKind
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorAdditionalStoredChargeKind =
+  | "hot-pixel-defect-excess"
+  | "leakage"
+  | "charge-injection"
+  | "clock-induced-charge"
+  | "other";
+```
+
+## SensorPhotoAccumulatedChargeComposition
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorPhotoAccumulatedChargeComposition = SensorAccumulatedChargeComposition<SensorEqePhotoExposure, SensorPhotoDarkCurrentCharge>;
+```

package/docs/api/sensor-architecture.md

@@ -0,0 +1,155 @@
+# sensor/architecture.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.
+
+## parseSensorArchitectureProfile
+
+Parses untrusted descriptive sensor-architecture metadata.
+
+Schema 0.2.0 remains accepted and returns a 0.2.0 profile unchanged in
+semantic identity. Schema 0.3.0 adds optional evidence-backed CMOS/CCD
+technology-family metadata. Unknown facts should be omitted instead of
+inferred.
+
+The parser validates structure, supported vocabulary, and field-level
+evidence only; it does not verify that a cited real-world claim is
+factually true and technology family does not activate hidden physics.
+
+```ts
+export function parseSensorArchitectureProfile(
+  value: unknown
+): SensorArchitectureProfile;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SENSOR_ARCHITECTURE_PROFILE_SCHEMA_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+SENSOR_ARCHITECTURE_PROFILE_SCHEMA_VERSION = "0.3.0" as const
+```
+
+## SensorArchitectureFactProvenance
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorArchitectureFactProvenance = EvidenceProvenance;
+```
+
+## SensorArchitectureProfile
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorArchitectureProfile =
+  | SensorArchitectureProfileV0_2
+  | SensorArchitectureProfileV0_3;
+```
+
+## SensorArchitectureProfileV0_2
+
+Legacy sensor-architecture schema.
+
+Schema 0.2.0 remains accepted and is preserved exactly when parsed. It does
+not support technologyFamily; omission remains unknown/unasserted.
+
+```ts
+export interface SensorArchitectureProfileV0_2
+  extends SensorArchitectureProfileBase {
+  schemaVersion: typeof LEGACY_SENSOR_ARCHITECTURE_PROFILE_SCHEMA_VERSION;
+  technologyFamily?: never;
+}
+```
+
+## SensorArchitectureProfileV0_3
+
+Current descriptive sensor hardware/capability metadata.
+
+Omitted properties mean unknown/unasserted. These fields are not scientific
+effect switches: no architecture value changes noise, dynamic range, FOV,
+crop factor, exposure, readout timing, or sampling without a separate
+downstream model that explicitly consumes that fact.
+
+```ts
+export interface SensorArchitectureProfileV0_3
+  extends SensorArchitectureProfileBase {
+  schemaVersion: typeof SENSOR_ARCHITECTURE_PROFILE_SCHEMA_VERSION;
+  /** Coarse detector technology identity only; never a performance switch. */
+  technologyFamily?: SourcedSensorArchitectureFact<SensorTechnologyFamily>;
+}
+```
+
+## SensorArchitectureReuseStatus
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorArchitectureReuseStatus = EvidenceReuseStatus;
+```
+
+## SensorArchitectureSourceKind
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorArchitectureSourceKind = EvidenceSourceOrigin;
+```
+
+## SensorColorSamplingFamily
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorColorSamplingFamily =
+  | "bayer"
+  | "quad-bayer"
+  | "monochrome"
+  | "custom-rgb-mosaic"
+  | "layered-color";
+```
+
+## SensorIlluminationArchitecture
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorIlluminationArchitecture = "fsi" | "bsi";
+```
+
+## SensorIntegrationArchitecture
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorIntegrationArchitecture =
+  | "monolithic"
+  | "partially-stacked"
+  | "stacked";
+```
+
+## SensorReadoutArchitecture
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorReadoutArchitecture = "rolling" | "global";
+```
+
+## SensorTechnologyFamily
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SensorTechnologyFamily = "cmos" | "ccd";
+```
+
+## SourcedSensorArchitectureFact
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SourcedSensorArchitectureFact<T> = EvidenceBackedFact<T>;
+```