@photivra/engine 0.6.0 → 1.0.0

package/docs/api/core-scientific-assurance.md

@@ -0,0 +1,214 @@
+# core/scientific-assurance.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.
+
+## ComposedScientificAssurance
+
+Cross-stage status and retained evidence for one declared scientific result.
+Required incomplete/approximate children constrain the aggregate; deterministic
+processing cannot upgrade approximation to calibration. Uncertainty components
+remain independently identified unless an explicit mathematical propagation model
+justifies a combination. A count of successful stages is not an accuracy bound.
+
+```ts
+export interface ComposedScientificAssurance {
+  version:
+    typeof SCIENTIFIC_ASSURANCE_CONTRACT_VERSION;
+  scientificStatus:
+    ScientificAssuranceStatus;
+  weakestRequiredComponentIds:
+    readonly string[];
+  evidenceStatus:
+    | "complete"
+    | "missing-required-evidence";
+  missingRequiredEvidenceComponentIds:
+    readonly string[];
+  uncertainty:
+    ComposedScientificUncertaintyStatus;
+  components:
+    readonly ScientificAssuranceComponent[];
+  componentEvidencePreserved: true;
+  componentUncertaintyPreserved: true;
+  aggregateNumericUncertaintyFabricated:
+    false;
+  downstreamStatusPromotedAboveInputs:
+    false;
+}
+```
+
+## ComposedScientificUncertaintyStatus
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ComposedScientificUncertaintyStatus =
+  | {
+      kind: "unknown";
+      componentIds:
+        readonly string[];
+      limitation: string;
+    }
+  | {
+      kind: "not-quantified";
+      componentIds:
+        readonly string[];
+      limitation: string;
+    }
+  | {
+      kind: "not-propagated";
+      componentIds:
+        readonly string[];
+      limitation: string;
+    }
+  | {
+      kind: "not-applicable";
+      componentIds:
+        readonly string[];
+      limitation: string;
+    };
+```
+
+## composeScientificAssurance
+
+Composes scientific-status, evidence and uncertainty semantics without
+inventing a numeric aggregate uncertainty.
+
+Required downstream status is bounded by the weakest required input.
+Component evidence/uncertainty is preserved verbatim after validation.
+
+```ts
+export function composeScientificAssurance(
+  input:
+    ComposeScientificAssuranceInput
+): ComposedScientificAssurance;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ComposeScientificAssuranceInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ComposeScientificAssuranceInput {
+  components:
+    readonly ScientificAssuranceComponent[];
+}
+```
+
+## SCIENTIFIC_ASSURANCE_CONTRACT_VERSION
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+SCIENTIFIC_ASSURANCE_CONTRACT_VERSION =
+  "0.1.0" as const
+```
+
+## ScientificAssuranceBasisKind
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ScientificAssuranceBasisKind =
+  | "evidence-backed-fact"
+  | "photivra-model-assumption"
+  | "not-applicable";
+```
+
+## ScientificAssuranceComponent
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ScientificAssuranceComponent {
+  componentId: string;
+  role: string;
+  required: boolean;
+  sourceIdentity:
+    ScientificAssuranceSourceIdentity;
+  basisKind:
+    ScientificAssuranceBasisKind;
+  scientificStatus:
+    ScientificAssuranceStatus;
+  evidenceRequirement:
+    | "required"
+    | "not-required";
+  evidence:
+    readonly EvidenceProvenance[];
+  uncertainty:
+    ScientificAssuranceComponentUncertainty;
+  limitations:
+    readonly string[];
+}
+```
+
+## ScientificAssuranceComponentUncertainty
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ScientificAssuranceComponentUncertainty =
+  | {
+      kind: "relative";
+      fraction: number;
+      basis: string;
+    }
+  | {
+      kind: "absolute";
+      plusMinus: number;
+      unit: string;
+      basis?: string;
+    }
+  | {
+      kind: "calculation-quality";
+      quality: CalculationQuality;
+    }
+  | {
+      kind: "not-quantified";
+      limitation: string;
+    }
+  | {
+      kind: "unknown";
+      limitation: string;
+    }
+  | {
+      kind: "not-applicable";
+      reason: string;
+    };
+```
+
+## ScientificAssuranceSourceIdentity
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ScientificAssuranceSourceIdentity {
+  kind: ScientificAssuranceSourceKind;
+  id: string;
+  version?: string;
+}
+```
+
+## ScientificAssuranceSourceKind
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ScientificAssuranceSourceKind =
+  | "profile"
+  | "result"
+  | "model"
+  | "fixture";
+```
+
+## ScientificAssuranceStatus
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ScientificAssuranceStatus =
+  | "calibrated"
+  | "approximation"
+  | "unknown";
+```

package/docs/api/core-spectral-composition.md

@@ -0,0 +1,268 @@
+# core/spectral-composition.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.
+
+## composeSpectralCoverage
+
+Intersects continuous spectral support and unions all interpolation
+breakpoints inside the common range.
+
+Air/vacuum conversion is never implicit. Discrete lines are deliberately
+excluded because delta-like line measures require a different integration
+path from continuous per-nanometre densities.
+
+```ts
+export function composeSpectralCoverage(
+  input: ComposeSpectralCoverageInput
+): SpectralCoverageComposition;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ComposeSpectralCoverageInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface ComposeSpectralCoverageInput {
+  participants:
+    readonly SpectralCoverageParticipant[];
+}
+```
+
+## DiscreteSpectralLineMeasure
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DiscreteSpectralLineMeasure {
+  wavelengthBasis:
+    ResolvedSpectralWavelengthBasis;
+  quantityUnit:
+    DiscreteSpectralLineQuantityUnit;
+  lineModel: "delta-like-integrated";
+  lines:
+    readonly DiscreteSpectralLineMeasureEntry[];
+  continuousSpectralDensityAssumed: false;
+  wavelengthMeasureMultiplicationRequired:
+    false;
+}
+```
+
+## DiscreteSpectralLineMeasureEntry
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DiscreteSpectralLineMeasureEntry {
+  lineId: string;
+  wavelengthNanometers: number;
+  integratedQuantity: number;
+}
+```
+
+## DiscreteSpectralLineQuantityUnit
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type DiscreteSpectralLineQuantityUnit =
+  | "relative"
+  | "W/sr"
+  | "W/m^2"
+  | "W/m^2/sr";
+```
+
+## DistributeIntegratedQuantityAcrossDiscreteLinesInput
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface DistributeIntegratedQuantityAcrossDiscreteLinesInput {
+  distribution:
+    NormalizedDiscreteSpectralLineDistribution;
+  totalIntegratedQuantity: number;
+  quantityUnit:
+    DiscreteSpectralLineQuantityUnit;
+}
+```
+
+## distributeIntegratedQuantityAcrossDiscreteSpectralLines
+
+Distributes one wavelength-integrated quantity across normalized discrete
+line fractions without inventing a continuous line width.
+
+```ts
+export function distributeIntegratedQuantityAcrossDiscreteSpectralLines(
+  input:
+    DistributeIntegratedQuantityAcrossDiscreteLinesInput
+): DiscreteSpectralLineMeasure;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## IntegratedDiscreteSpectralLineMeasure
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface IntegratedDiscreteSpectralLineMeasure {
+  wavelengthBasis:
+    ResolvedSpectralWavelengthBasis;
+  quantityUnit:
+    DiscreteSpectralLineQuantityUnit;
+  integratedQuantity: number;
+  lineCount: number;
+  continuousQuadratureApplied: false;
+  wavelengthMeasureMultiplicationApplied:
+    false;
+}
+```
+
+## integrateDiscreteSpectralLineMeasure
+
+Integrates a discrete line measure by summing already wavelength-integrated
+line contributions. No d-lambda factor is applied.
+
+```ts
+export function integrateDiscreteSpectralLineMeasure(
+  measure:
+    DiscreteSpectralLineMeasure
+): IntegratedDiscreteSpectralLineMeasure;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## NormalizedDiscreteSpectralLine
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NormalizedDiscreteSpectralLine {
+  lineId: string;
+  wavelengthNanometers: number;
+  normalizedIntegratedWeight: number;
+}
+```
+
+## NormalizedDiscreteSpectralLineDistribution
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface NormalizedDiscreteSpectralLineDistribution {
+  wavelengthBasis:
+    ResolvedSpectralWavelengthBasis;
+  lineModel: "delta-like-integrated";
+  normalization:
+    "sum-normalized-integrated-weight-to-one";
+  lines:
+    readonly NormalizedDiscreteSpectralLine[];
+}
+```
+
+## parseNormalizedDiscreteSpectralLineDistribution
+
+Parses a normalized set of delta-like discrete spectral lines.
+
+Each weight is an integrated line fraction, not a per-nanometre spectral
+density sample. The weights must sum to one.
+
+```ts
+export function parseNormalizedDiscreteSpectralLineDistribution(
+  value: unknown,
+  path =
+    "discreteSpectralLineDistribution"
+): NormalizedDiscreteSpectralLineDistribution;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseSpectralCoverageParticipant
+
+Parses one continuous spectral-coverage participant.
+
+This contract describes support and interpolation breakpoints only. It does
+not carry spectral values, transmission, response, radiance, or uncertainty.
+
+```ts
+export function parseSpectralCoverageParticipant(
+  value: unknown,
+  path = "spectralCoverageParticipant"
+): SpectralCoverageParticipant;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## ResolvedSpectralWavelengthBasis
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type ResolvedSpectralWavelengthBasis =
+  Exclude<SpectralWavelengthBasis, "unspecified">;
+```
+
+## SpectralCoverageComposition
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SpectralCoverageComposition {
+  wavelengthBasis:
+    ResolvedSpectralWavelengthBasis;
+  commonWavelengthRangeNanometers:
+    SpectralWavelengthRangeNanometers;
+  /**
+   * Common-range endpoints plus every participant breakpoint that falls
+   * strictly inside the common overlap.
+   */
+  segmentBoundariesNanometers:
+    readonly number[];
+  participantIds: readonly string[];
+  participantRoles:
+    readonly SpectralCoverageParticipantRole[];
+  continuousCoverageIntersectionEstablished:
+    true;
+  breakpointUnionEstablished: true;
+  responseValuesApplied: false;
+  spectralDensityIntegrated: false;
+  discreteLinesIncluded: false;
+  airVacuumConversionPerformed: false;
+}
+```
+
+## SpectralCoverageParticipant
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export interface SpectralCoverageParticipant {
+  participantId: string;
+  role: SpectralCoverageParticipantRole;
+  wavelengthBasis:
+    ResolvedSpectralWavelengthBasis;
+  wavelengthRangeNanometers:
+    SpectralWavelengthRangeNanometers;
+  /**
+   * Internal piecewise-continuous breakpoints. Range endpoints are carried
+   * separately and must not be duplicated here.
+   */
+  breakpointsNanometers:
+    readonly number[];
+}
+```
+
+## SpectralCoverageParticipantRole
+
+The exact contract is declared below; use the domain guide for assumptions and staged integration.
+
+```ts
+export type SpectralCoverageParticipantRole =
+  | "illumination-source"
+  | "scene-radiance"
+  | "material-response"
+  | "optical-transmission"
+  | "sensor-response"
+  | "other";
+```

package/docs/api/core-spectral.md

@@ -0,0 +1,78 @@
+# core/spectral.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.
+
+## parseSpectralWavelengthBasis
+
+Parses a wavelength basis without inferring air/vacuum conversion.
+
+```ts
+export function parseSpectralWavelengthBasis(
+  value: unknown,
+  path = "wavelengthBasis"
+): SpectralWavelengthBasis;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseSpectralWavelengthRangeNanometers
+
+Parses a positive non-empty wavelength interval in nanometres.
+
+```ts
+export function parseSpectralWavelengthRangeNanometers(
+  value: unknown,
+  path = "wavelengthRangeNanometers"
+): SpectralWavelengthRangeNanometers;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## parseSpectralWavelengthSample
+
+Parses one positive wavelength coordinate in nanometres.
+
+```ts
+export function parseSpectralWavelengthSample(
+  value: unknown,
+  path = "spectralSample"
+): SpectralWavelengthSample;
+```
+
+This call is synchronous; any supplied provider must follow its explicit synchronous contract.
+
+## SpectralWavelengthBasis
+
+Explicit wavelength coordinate basis used by renderer-neutral spectral data.
+
+"unspecified" is permitted only where a downstream contract explicitly
+allows unresolved/approximate wavelength coordinates. Calibrated physical
+composition must resolve the basis before use.
+
+```ts
+export type SpectralWavelengthBasis =
+  | "air"
+  | "vacuum"
+  | "unspecified";
+```
+
+## SpectralWavelengthRangeNanometers
+
+Closed wavelength interval expressed in nanometres.
+
+```ts
+export interface SpectralWavelengthRangeNanometers {
+  minimum: number;
+  maximum: number;
+}
+```
+
+## SpectralWavelengthSample
+
+One wavelength coordinate expressed in nanometres.
+
+```ts
+export interface SpectralWavelengthSample {
+  wavelengthNanometers: number;
+}
+```

package/docs/api/core-validation.md

@@ -0,0 +1,34 @@
+# core/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.
+
+## InvalidScientificInputError
+
+Error thrown when a public scientific calculation receives invalid input.
+
+```ts
+export class InvalidScientificInputError extends RangeError {
+  readonly code = "INVALID_SCIENTIFIC_INPUT";
+
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidScientificInputError";
+  }
+}
+```
+
+## InvalidScientificResultError
+
+Error thrown when a scientific calculation would return a non-finite
+numeric value that is unsafe for JSON and downstream consumers.
+
+```ts
+export class InvalidScientificResultError extends RangeError {
+  readonly code = "INVALID_SCIENTIFIC_RESULT";
+
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidScientificResultError";
+  }
+}
+```

package/docs/api/core-version.md

@@ -0,0 +1,14 @@
+# core/version.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.
+
+## ENGINE_API_VERSION
+
+Version of the public root-engine API contract.
+
+This is distinct from the npm package version and all subsystem/schema
+contract versions.
+
+```ts
+ENGINE_API_VERSION = "0.116.0" as const
+```