@photivra/engine 0.5.1 → 1.0.0

package/docs/api/composition-plan-consumer.md

@@ -0,0 +1,98 @@
+# composition/plan-consumer.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.
+
+## createProductionPlanConsumerManifest
+
+Creates a deterministic renderer/reference consumption view over one
+finalized semantic production plan.
+
+The consumer role changes execution responsibility only. It does not alter
+scientific stage/effect identity, temporal sample count, seeds, or physical
+results.
+
+```ts
+export function createProductionPlanConsumerManifest(
+  input:
+    CreateProductionPlanConsumerManifestInput
+): ProductionPlanConsumerManifest;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CreateProductionPlanConsumerManifestInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface CreateProductionPlanConsumerManifestInput {
+  plan: ProductionImageFormationPlan;
+  consumerKind: RendererConsumerKind;
+}
+```
+
+## PRODUCTION_PLAN_CONSUMER_MANIFEST_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+PRODUCTION_PLAN_CONSUMER_MANIFEST_VERSION =
+  "0.2.0" as const
+```
+
+## ProductionPlanConsumerManifest
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ProductionPlanConsumerManifest {
+  version:
+    typeof PRODUCTION_PLAN_CONSUMER_MANIFEST_VERSION;
+  consumerKind: RendererConsumerKind;
+  planVersion:
+    typeof PRODUCTION_IMAGE_FORMATION_PLAN_VERSION;
+  planFingerprint: string;
+  planStatus:
+    ProductionImageFormationPlan["status"];
+  activeOrModeledStages:
+    readonly {
+      stageId: ImageFormationStageId;
+      state: "active" | "modeled-zero";
+      modelId?: string;
+      modelVersion?: string;
+      resultIdentity?: string;
+    }[];
+  activeOrModeledEffects:
+    readonly {
+      effectId: ImageFormationEffectId;
+      state: "active" | "modeled-zero";
+      modelId?: string;
+      modelVersion?: string;
+    }[];
+  blockers:
+    readonly ProductionImageFormationBlocker[];
+  /** Same immutable executed RAW and output results; consumers cannot re-render a different source. */
+  environmentCaptureResult?: ProductionImageFormationPlan["environmentCaptureResult"];
+  processedOutputResult?: ProductionImageFormationPlan["processedOutputResult"];
+  physicalSceneToSensorResult:
+    ProductionImageFormationPlan["physicalSceneToSensorResult"];
+  temporalCaptureResult:
+    ProductionImageFormationPlan["temporalCaptureResult"];
+  scientificAssurance:
+    ProductionImageFormationPlan["scientificAssurance"];
+  stochastic: {
+    captureSeedUint32: number;
+    consumerMayReplaceSeed: false;
+    backendRandomnessMayRedefineScientificResult:
+      false;
+  };
+  scientificSemanticsSharedAcrossConsumerKinds:
+    true;
+  consumerMayChangeScientificInputs:
+    false;
+  consumerMayReorderImageFormationStages:
+    false;
+  consumerMayReduceCommittedTemporalSampleCount:
+    false;
+}
+```

package/docs/api/core-calculation-result.md

@@ -0,0 +1,220 @@
+# core/calculation-result.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.
+
+## AbsoluteUncertaintyEstimate
+
+Absolute symmetric uncertainty around a result quantity.
+
+```ts
+export interface AbsoluteUncertaintyEstimate extends UncertaintyEstimateBase {
+  kind: "absolute";
+  /** Symmetric ± magnitude in the explicitly named unit. */
+  plusMinus: number;
+  /** Explicit unit such as mm, m, px, or "1" for dimensionless values. */
+  unit: string;
+}
+```
+
+## approximationResult
+
+Creates an approximation-result envelope.
+
+```ts
+export function approximationResult<T>(
+  value: T,
+  model: string,
+  modelVersion: string,
+  assumptions: readonly string[],
+  quality?: CalculationQuality
+): CalculationResult<T>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## calculatedResult
+
+Creates a deterministic calculated-result envelope.
+
+```ts
+export function calculatedResult<T>(
+  value: T,
+  model: string,
+  modelVersion: string,
+  assumptions?: readonly string[],
+  quality?: CalculationQuality
+): CalculationResult<T>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## CalculationProvenance
+
+Metadata describing how a numerical result was produced.
+
+```ts
+export interface CalculationProvenance {
+  /** Classification of the result's scientific origin. */
+  kind: ProvenanceKind;
+  /** Stable identifier for the model or equation set. */
+  model: string;
+  /** Version of the model, independent of the package version. */
+  modelVersion: string;
+  /** Concise assumptions that materially affect interpretation. */
+  assumptions?: readonly string[];
+}
+```
+
+## CalculationQuality
+
+Optional quality metadata for a calculation result.
+
+Components remain separate by default. Callers must not add, combine in
+quadrature, or otherwise collapse uncertainty components unless a
+scientifically justified composition method explicitly documents
+independence/correlation assumptions.
+
+```ts
+export interface CalculationQuality {
+  uncertainty?: readonly UncertaintyEstimate[];
+  validRanges?: readonly CalculationValidRange[];
+  notes?: readonly string[];
+}
+```
+
+## CalculationResult
+
+Standard result envelope for public scientific calculations.
+
+Deterministic analytical results remain lightweight: quality is omitted when
+there is no defensible uncertainty/accuracy metadata to report.
+
+```ts
+export interface CalculationResult<T> {
+  value: T;
+  provenance: CalculationProvenance;
+  quality?: CalculationQuality;
+}
+```
+
+## CalculationValidRange
+
+Documented parameter range over which a model/calibration is considered
+valid. This is model applicability metadata, not a statistical interval.
+
+```ts
+export interface CalculationValidRange {
+  /** JSON-style input/model parameter path, e.g. input.focusDistanceM. */
+  parameterPath: string;
+  /** Explicit unit such as m, mm, ISO, or "1" for dimensionless values. */
+  unit: string;
+  minimum?: number;
+  maximum?: number;
+  note?: string;
+}
+```
+
+## calibratedResult
+
+Creates a calibrated-result envelope with explicit quality metadata.
+
+```ts
+export function calibratedResult<T>(
+  value: T,
+  model: string,
+  modelVersion: string,
+  assumptions: readonly string[],
+  quality: CalculationQuality
+): CalculationResult<T>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## estimatedResult
+
+Creates an estimated-result envelope with explicit quality metadata.
+
+```ts
+export function estimatedResult<T>(
+  value: T,
+  model: string,
+  modelVersion: string,
+  assumptions: readonly string[],
+  quality: CalculationQuality
+): CalculationResult<T>;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ProvenanceKind
+
+Scientific provenance labels used throughout the public API.
+
+```ts
+export type ProvenanceKind =
+  | "calculated"
+  | "calibrated"
+  | "estimated"
+  | "approximation";
+```
+
+## RelativeUncertaintyEstimate
+
+Relative symmetric uncertainty around a result quantity.
+
+```ts
+export interface RelativeUncertaintyEstimate extends UncertaintyEstimateBase {
+  kind: "relative";
+  /** Symmetric ± fractional magnitude; 0.05 means ±5%. */
+  fraction: number;
+}
+```
+
+## UncertaintyConfidence
+
+Optional confidence metadata for a quantified uncertainty estimate.
+
+A confidence level is only meaningful when the basis can be stated. It must
+not be used as a generic subjective confidence score.
+
+```ts
+export interface UncertaintyConfidence {
+  /** Confidence/coverage level as a fraction in the interval (0, 1]. */
+  level: number;
+  /** Concise description of the statistical/empirical basis. */
+  basis: string;
+}
+```
+
+## UncertaintyEstimate
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type UncertaintyEstimate =
+  | AbsoluteUncertaintyEstimate
+  | RelativeUncertaintyEstimate;
+```
+
+## UncertaintySource
+
+Source category for a quantified uncertainty estimate.
+
+```ts
+export type UncertaintySource =
+  | "measurement"
+  | "model-approximation"
+  | "calibration";
+```
+
+## validateCalculationQuality
+
+Validates result-quality metadata before it enters a public result envelope.
+
+```ts
+export function validateCalculationQuality(
+  quality: CalculationQuality | undefined
+): void;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.

package/docs/api/core-configuration-error.md

@@ -0,0 +1,19 @@
+# core/configuration-error.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.
+
+## InvalidConfigurationError
+
+Error thrown when external configuration data does not match a public
+runtime schema.
+
+```ts
+export class InvalidConfigurationError extends TypeError {
+  readonly code = "INVALID_CONFIGURATION";
+
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidConfigurationError";
+  }
+}
+```

package/docs/api/core-image-formation.md

@@ -0,0 +1,204 @@
+# core/image-formation.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.
+
+## getImageFormationContract
+
+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.
+
+```ts
+export function getImageFormationContract(): ImageFormationContract;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## IMAGE_FORMATION_CONTRACT_VERSION
+
+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.
+
+```ts
+IMAGE_FORMATION_CONTRACT_VERSION = "0.4.0" as const
+```
+
+## ImageFormationContract
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+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[];
+}
+```
+
+## ImageFormationCoordinateSpaceContract
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ImageFormationCoordinateSpaceContract {
+  id: ImageFormationCoordinateSpaceId;
+  unit: "m" | "mm" | "px" | "display-dependent";
+  origin: string;
+  axes: string;
+  note: string;
+}
+```
+
+## ImageFormationCoordinateSpaceId
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ImageFormationCoordinateSpaceId =
+  | "scene-metric"
+  | "image-plane-metric"
+  | "native-sensor-physical"
+  | "native-raster"
+  | "oriented-capture-raster"
+  | "output-raster"
+  | "display";
+```
+
+## ImageFormationDomainId
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ImageFormationDomainId =
+  | "scene-ray-geometry"
+  | "scene-radiance-formation"
+  | "lens-pupil-throughput"
+  | "field-wavelength-psf"
+  | "temporal-exposure-readout"
+  | "sensor-output-display";
+```
+
+## ImageFormationEffectId
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+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";
+```
+
+## ImageFormationEffectPlacement
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ImageFormationEffectPlacement {
+  id: ImageFormationEffectId;
+  primaryStage: ImageFormationStageId;
+  coupledStages: readonly ImageFormationStageId[];
+  note: string;
+}
+```
+
+## ImageFormationImplementationStatus
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ImageFormationImplementationStatus =
+  | "existing-foundation"
+  | "partial-foundation"
+  | "reserved-contract";
+```
+
+## ImageFormationRendererContract
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ImageFormationRendererContract {
+  geometricWarpSampling: "inverse-map-destination-to-source";
+  alphaRepresentation: "premultiplied";
+  occlusionRule: "preserve-depth-order-across-warps";
+  previewAndReferenceShareScientificContract: true;
+  backendMayApproximateButNotRedefineSemantics: true;
+  note: string;
+}
+```
+
+## ImageFormationStageContract
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ImageFormationStageContract {
+  id: ImageFormationStageId;
+  domain: ImageFormationDomainId;
+  status: ImageFormationImplementationStatus;
+  coordinateSpaces: readonly ImageFormationCoordinateSpaceId[];
+  requiredUpstreamStages: readonly ImageFormationStageId[];
+  coupledStages: readonly ImageFormationStageId[];
+  purpose: string;
+}
+```
+
+## ImageFormationStageId
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ImageFormationStageId =
+  | "scene-ray-projection"
+  | "scene-radiance-evaluation"
+  | "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";
+```
+
+## ImageFormationTemporalContract
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ImageFormationTemporalContract {
+  authoritativeTimeUnit: "s";
+  origin: "exposure-start";
+  normalizedTimeIsDerivedOnly: true;
+  exposureDurationAndReadoutTimingAreIndependent: true;
+  globalReadoutDoesNotImplyZeroMotionBlur: true;
+  nativeReadoutDirectionRemainsNativeUnderOrientation: true;
+  note: string;
+}
+```