@photivra/engine 1.5.0 → 2.1.0

package/dist/schema/scene-radiance-temporal.js

@@ -1,24 +1,26 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Creates renderer/provider-neutral scene-radiance evaluation nodes over one authoritative local
- * exposure window. The plan deliberately carries capture time separately from the legacy #85 request
- * field name. Providers/renderers must evaluate scene/source radiance at
- * node.captureTimeSecondsFromReference on the first-opening-boundary clock.
- * Reduces provider-returned wavelength-resolved scene radiance over the authoritative local exposure
- * window. Every sample must bind to the exact plan node/time/result identity. Numeric uncertainty is
- * retained per node and explicitly not combined because no correlation/independence assumption is
- * introduced.
+ * Scene radiance over an exposure window, in two steps.
+ *
+ * 1. Plan: list the times (nodes) at which a scene-radiance provider (a renderer or other
+ *    source of scene light) must report radiance during one local exposure window.
+ * 2. Reduce: combine the provider's per-wavelength results over that window.
+ *
+ * Each returned sample must match its planned node, time and result identity exactly.
+ * Uncertainty stays per node and is not combined, because no correlation or independence
+ * is assumed.
  * @see docs/SCENE_RADIANCE_AND_ILLUMINATION.md for equations, coordinate/unit conventions, blockers
  * and support limits.
  */
 import { InvalidScientificInputError, requirePositiveInteger } from "../core/validation.js";
 import { parseSceneRadianceEvaluationRequest, parseSceneRadianceEvaluationResult } from "./scene-radiance.js";
+import { requireInputKeys } from "../core/record-validation.js";
+import { InvalidConfigurationError } from "../core/configuration-error.js";
 export const SCENE_RADIANCE_TEMPORAL_SAMPLING_PLAN_VERSION = "0.1.0";
 function requireNonEmptyString(value, path) {
     if (typeof value !== "string" ||
         value.trim().length === 0) {
-        throw new InvalidScientificInputError(path +
+        throw new InvalidConfigurationError(path +
             " must be a non-empty string.");
     }
     return value.trim();
@@ -35,9 +37,9 @@ function exposureForPoint(timing, point) {
     return matches[0];
 }
 function parseQuery(query) {
-    // Reuse the canonical #85 request parser for all shared scene/spectral
-    // semantics without assigning a misleading legacy time value to the
-    // returned temporal query contract.
+    // Reuse the scene-radiance request parser for the shared scene and spectral
+    // checks. The placeholder time it needs is not copied into the returned
+    // temporal query, where it would be misleading.
     const parsed = parseSceneRadianceEvaluationRequest({
         schemaVersion: "0.1.0",
         sampleId: "temporal-query-validation",
@@ -61,14 +63,15 @@ function parseQuery(query) {
     };
 }
 /**
- * Creates renderer/provider-neutral scene-radiance evaluation nodes over one
- * authoritative local exposure window.
+ * Plans the times (nodes) at which a scene-radiance provider must report radiance
+ * during one local exposure window. Works with any renderer or provider.
  *
- * The plan deliberately carries capture time separately from the legacy #85
- * request field name. Providers/renderers must evaluate scene/source radiance
- * at node.captureTimeSecondsFromReference on the first-opening-boundary clock.
+ * Capture time is a separate field, not the older request field
+ * timeSecondsFromExposureStart. Providers must evaluate radiance at
+ * node.captureTimeSecondsFromReference, measured from the first opening boundary.
  */
 export function createSceneRadianceTemporalSamplingPlan(input) {
+    requireInputKeys(input, "createSceneRadianceTemporalSamplingPlan", ["planId", "timing", "destinationPointNative", "temporalSampleCount", "query"]);
     requirePositiveInteger("temporalSampleCount", input.temporalSampleCount);
     const planId = requireNonEmptyString(input.planId, "planId");
     const query = parseQuery(input.query);
@@ -147,14 +150,14 @@ function sameTime(a, b) {
             scale);
 }
 /**
- * Reduces provider-returned wavelength-resolved scene radiance over the
- * authoritative local exposure window.
+ * Combines the provider's per-wavelength scene radiance over the local exposure window.
  *
- * Every sample must bind to the exact plan node/time/result identity. Numeric
- * uncertainty is retained per node and explicitly not combined because no
- * correlation/independence assumption is introduced.
+ * Each sample must match its planned node, time and result identity exactly.
+ * Uncertainty stays per node and is not combined, because no correlation or
+ * independence is assumed.
  */
 export function reduceSceneRadianceTemporalSamples(input) {
+    requireInputKeys(input, "reduceSceneRadianceTemporalSamples", ["plan", "samples"]);
     if (!Array.isArray(input.samples) ||
         input.samples.length !==
             input.plan.nodes.length) {

package/dist/schema/scene-radiance-temporal.js.map

@@ -1 +1 @@
-{"version":3,"file":"scene-radiance-temporal.js","sourceRoot":"","sources":["../../src/schema/scene-radiance-temporal.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scene-radiance-temporal.js","sourceRoot":"","sources":["../../src/schema/scene-radiance-temporal.ts"],"names":[],"mappings":"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","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Scene radiance over an exposure window, in two steps.\n *\n * 1. Plan: list the times (nodes) at which a scene-radiance provider (a renderer or other\n *    source of scene light) must report radiance during one local exposure window.\n * 2. Reduce: combine the provider's per-wavelength results over that window.\n *\n * Each returned sample must match its planned node, time and result identity exactly.\n * Uncertainty stays per node and is not combined, because no correlation or independence\n * is assumed.\n * @see docs/SCENE_RADIANCE_AND_ILLUMINATION.md for equations, coordinate/unit conventions, blockers\n * and support limits.\n */\n\nimport { InvalidScientificInputError, requirePositiveInteger } from \"../core/validation.js\";\nimport type { RasterPoint } from \"../output/capture-geometry.js\";\nimport {\n  parseSceneRadianceEvaluationRequest,\n  parseSceneRadianceEvaluationResult,\n  type SceneRadianceEvaluationRequest,\n  type SceneRadianceEvaluationResult\n} from \"./scene-radiance.js\";\nimport type {\n  ResolvedCaptureModeTiming\n} from \"../sensor/capture-mode-timing.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\nimport { InvalidConfigurationError } from \"../core/configuration-error.js\";\n\nexport const SCENE_RADIANCE_TEMPORAL_SAMPLING_PLAN_VERSION =\n  \"0.1.0\" as const;\n\nexport interface SceneRadianceTemporalQuery {\n  providerProfileId: string;\n  sceneId: string;\n  illuminationProfileId: string;\n  materialResponseProfileId: string;\n  target:\n    SceneRadianceEvaluationRequest[\"target\"];\n  wavelengthNanometers: number;\n  wavelengthBasis:\n    SceneRadianceEvaluationRequest[\"wavelengthBasis\"];\n}\n\nexport interface CreateSceneRadianceTemporalSamplingPlanInput {\n  planId: string;\n  timing:\n    ResolvedCaptureModeTiming;\n  destinationPointNative:\n    RasterPoint;\n  temporalSampleCount: number;\n  query:\n    SceneRadianceTemporalQuery;\n}\n\nexport interface SceneRadianceTemporalSamplingNode {\n  nodeId: string;\n  expectedResultSampleId: string;\n  temporalSampleIndex: number;\n  localExposurePhase: number;\n  captureTimeSecondsFromReference:\n    number;\n  normalizedTimeWeight: number;\n  timeMeasureSeconds: number;\n}\n\nexport interface SceneRadianceTemporalSamplingPlan {\n  version:\n    typeof SCENE_RADIANCE_TEMPORAL_SAMPLING_PLAN_VERSION;\n  planId: string;\n  timeReference:\n    \"first-opening-boundary-phase\";\n  timingProfileIdentity: {\n    profileId: string;\n    profileVersion: string;\n    captureModeId: string;\n  };\n  destinationPointNative:\n    RasterPoint;\n  localExposureWindow: {\n    startSecondsFromCaptureReference:\n      number;\n    endSecondsFromCaptureReference:\n      number;\n    durationSeconds: number;\n  };\n  temporalSampleCount: number;\n  quadratureScheme:\n    \"uniform-midpoint\";\n  query:\n    SceneRadianceTemporalQuery;\n  nodes:\n    readonly SceneRadianceTemporalSamplingNode[];\n  providerMustEvaluateAtNodeCaptureTime:\n    true;\n  sensorReadoutTimingUsedAsExposureTiming:\n    false;\n}\n\nexport interface SceneRadianceTemporalEvaluatedSample {\n  nodeId: string;\n  captureTimeSecondsFromReference:\n    number;\n  result:\n    SceneRadianceEvaluationResult;\n}\n\nexport interface ReduceSceneRadianceTemporalSamplesInput {\n  plan:\n    SceneRadianceTemporalSamplingPlan;\n  samples:\n    readonly SceneRadianceTemporalEvaluatedSample[];\n}\n\nexport interface ReducedSceneRadianceTemporalExposure {\n  version:\n    typeof SCENE_RADIANCE_TEMPORAL_SAMPLING_PLAN_VERSION;\n  planId: string;\n  timeReference:\n    \"first-opening-boundary-phase\";\n  localExposureWindow:\n    SceneRadianceTemporalSamplingPlan[\"localExposureWindow\"];\n  temporalSampleCount: number;\n  quadratureScheme:\n    \"uniform-midpoint\";\n  providerProfileId: string;\n  sceneId: string;\n  wavelengthNanometers: number;\n  wavelengthBasis:\n    SceneRadianceEvaluationRequest[\"wavelengthBasis\"];\n  quantity:\n    \"outgoing-spectral-radiance\";\n  averageSpectralRadianceWattsPerSquareMeterSteradianNanometer:\n    number;\n  integratedSpectralRadianceWattSecondsPerSquareMeterSteradianNanometer:\n    number;\n  nodes: readonly {\n    nodeId: string;\n    captureTimeSecondsFromReference:\n      number;\n    normalizedTimeWeight: number;\n    timeMeasureSeconds: number;\n    spectralRadianceWattsPerSquareMeterSteradianNanometer:\n      number;\n    evidence:\n      SceneRadianceEvaluationResult[\"evidence\"];\n    uncertainty:\n      SceneRadianceEvaluationResult[\"uncertainty\"];\n  }[];\n  scientificStatus: \"approximation\";\n  uncertaintyPropagation:\n    \"not-propagated\";\n  uncertaintyLimitation: string;\n  sensorReadoutTimingUsedAsExposureTiming:\n    false;\n}\n\nfunction requireNonEmptyString(\n  value: string,\n  path: string\n): string {\n  if (\n    typeof value !== \"string\" ||\n    value.trim().length === 0\n  ) {\n    throw new InvalidConfigurationError(\n      path +\n        \" must be a non-empty string.\"\n    );\n  }\n  return value.trim();\n}\n\nfunction samePoint(\n  a: RasterPoint,\n  b: RasterPoint\n): boolean {\n  return (\n    a.x === b.x &&\n    a.y === b.y\n  );\n}\n\nfunction exposureForPoint(\n  timing:\n    ResolvedCaptureModeTiming,\n  point:\n    RasterPoint\n): ResolvedCaptureModeTiming[\"exposureWindows\"][\"samples\"][number] {\n  const matches =\n    timing.exposureWindows.samples.filter(\n      (sample) =>\n        samePoint(\n          sample.pointNative,\n          point\n        )\n    );\n  if (matches.length !== 1) {\n    throw new InvalidScientificInputError(\n      \"destinationPointNative must match exactly one committed exposure-window sample.\"\n    );\n  }\n  return matches[0]!;\n}\n\nfunction parseQuery(\n  query:\n    SceneRadianceTemporalQuery\n): SceneRadianceTemporalQuery {\n  // Reuse the scene-radiance request parser for the shared scene and spectral\n  // checks. The placeholder time it needs is not copied into the returned\n  // temporal query, where it would be misleading.\n  const parsed =\n    parseSceneRadianceEvaluationRequest({\n      schemaVersion: \"0.1.0\",\n      sampleId:\n        \"temporal-query-validation\",\n      providerProfileId:\n        query.providerProfileId,\n      sceneId:\n        query.sceneId,\n      illuminationProfileId:\n        query.illuminationProfileId,\n      materialResponseProfileId:\n        query.materialResponseProfileId,\n      target:\n        query.target,\n      timeSecondsFromExposureStart:\n        0,\n      wavelengthNanometers:\n        query.wavelengthNanometers,\n      wavelengthBasis:\n        query.wavelengthBasis\n    });\n\n  return {\n    providerProfileId:\n      parsed.providerProfileId,\n    sceneId:\n      parsed.sceneId,\n    illuminationProfileId:\n      parsed.illuminationProfileId,\n    materialResponseProfileId:\n      parsed.materialResponseProfileId,\n    target:\n      parsed.target,\n    wavelengthNanometers:\n      parsed.wavelengthNanometers,\n    wavelengthBasis:\n      parsed.wavelengthBasis\n  };\n}\n\n/**\n * Plans the times (nodes) at which a scene-radiance provider must report radiance\n * during one local exposure window. Works with any renderer or provider.\n *\n * Capture time is a separate field, not the older request field\n * timeSecondsFromExposureStart. Providers must evaluate radiance at\n * node.captureTimeSecondsFromReference, measured from the first opening boundary.\n */\nexport function createSceneRadianceTemporalSamplingPlan(\n  input:\n    CreateSceneRadianceTemporalSamplingPlanInput\n): SceneRadianceTemporalSamplingPlan {\n  requireInputKeys(input, \"createSceneRadianceTemporalSamplingPlan\", [\"planId\", \"timing\", \"destinationPointNative\", \"temporalSampleCount\", \"query\"]);\n  requirePositiveInteger(\n    \"temporalSampleCount\",\n    input.temporalSampleCount\n  );\n  const planId =\n    requireNonEmptyString(\n      input.planId,\n      \"planId\"\n    );\n  const query =\n    parseQuery(input.query);\n  const exposure =\n    exposureForPoint(\n      input.timing,\n      input\n        .destinationPointNative\n    );\n  const duration =\n    exposure\n      .localExposureDurationSeconds;\n\n  if (\n    !Number.isFinite(duration) ||\n    duration <= 0\n  ) {\n    throw new InvalidScientificInputError(\n      \"Scene-radiance temporal sampling requires a positive finite local exposure duration.\"\n    );\n  }\n\n  const normalizedTimeWeight =\n    1 /\n    input.temporalSampleCount;\n  const timeMeasureSeconds =\n    duration /\n    input.temporalSampleCount;\n\n  const nodes =\n    Array.from(\n      {\n        length:\n          input.temporalSampleCount\n      },\n      (\n        _,\n        temporalSampleIndex\n      ) => {\n        const localExposurePhase =\n          (temporalSampleIndex +\n            0.5) /\n          input.temporalSampleCount;\n        const captureTime =\n          exposure\n            .startOffsetSecondsFromOpeningReference +\n          localExposurePhase *\n            duration;\n        return {\n          nodeId:\n            planId +\n            \":node:\" +\n            temporalSampleIndex,\n          expectedResultSampleId:\n            planId +\n            \":radiance:\" +\n            temporalSampleIndex,\n          temporalSampleIndex,\n          localExposurePhase,\n          captureTimeSecondsFromReference:\n            captureTime,\n          normalizedTimeWeight,\n          timeMeasureSeconds\n        };\n      }\n    );\n\n  return {\n    version:\n      SCENE_RADIANCE_TEMPORAL_SAMPLING_PLAN_VERSION,\n    planId,\n    timeReference:\n      \"first-opening-boundary-phase\",\n    timingProfileIdentity: {\n      profileId:\n        input.timing\n          .timingProfileId,\n      profileVersion:\n        input.timing\n          .timingProfileVersion,\n      captureModeId:\n        input.timing\n          .captureModeId\n    },\n    destinationPointNative: {\n      ...input\n        .destinationPointNative\n    },\n    localExposureWindow: {\n      startSecondsFromCaptureReference:\n        exposure\n          .startOffsetSecondsFromOpeningReference,\n      endSecondsFromCaptureReference:\n        exposure\n          .endOffsetSecondsFromOpeningReference,\n      durationSeconds:\n        duration\n    },\n    temporalSampleCount:\n      input.temporalSampleCount,\n    quadratureScheme:\n      \"uniform-midpoint\",\n    query,\n    nodes,\n    providerMustEvaluateAtNodeCaptureTime:\n      true,\n    sensorReadoutTimingUsedAsExposureTiming:\n      false\n  };\n}\n\nfunction sameTime(\n  a: number,\n  b: number\n): boolean {\n  const scale =\n    Math.max(\n      1,\n      Math.abs(a),\n      Math.abs(b)\n    );\n  return (\n    Math.abs(a - b) <=\n    Number.EPSILON *\n      16 *\n      scale\n  );\n}\n\n/**\n * Combines the provider's per-wavelength scene radiance over the local exposure window.\n *\n * Each sample must match its planned node, time and result identity exactly.\n * Uncertainty stays per node and is not combined, because no correlation or\n * independence is assumed.\n */\nexport function reduceSceneRadianceTemporalSamples(\n  input:\n    ReduceSceneRadianceTemporalSamplesInput\n): ReducedSceneRadianceTemporalExposure {\n  requireInputKeys(input, \"reduceSceneRadianceTemporalSamples\", [\"plan\", \"samples\"]);\n  if (\n    !Array.isArray(\n      input.samples\n    ) ||\n    input.samples.length !==\n      input.plan.nodes.length\n  ) {\n    throw new InvalidScientificInputError(\n      \"samples must contain exactly one result for every temporal sampling node.\"\n    );\n  }\n\n  const byNode =\n    new Map(\n      input.samples.map(\n        (sample) => [\n          sample.nodeId,\n          sample\n        ] as const\n      )\n    );\n  if (\n    byNode.size !==\n    input.samples.length\n  ) {\n    throw new InvalidScientificInputError(\n      \"samples must not contain duplicate nodeId values.\"\n    );\n  }\n\n  let average = 0;\n  let integrated = 0;\n\n  const nodes =\n    input.plan.nodes.map(\n      (node) => {\n        const supplied =\n          byNode.get(\n            node.nodeId\n          );\n        if (supplied === undefined) {\n          throw new InvalidScientificInputError(\n            \"A temporal scene-radiance node result is missing.\"\n          );\n        }\n        if (\n          !Number.isFinite(\n            supplied\n              .captureTimeSecondsFromReference\n          ) ||\n          !sameTime(\n            supplied\n              .captureTimeSecondsFromReference,\n            node\n              .captureTimeSecondsFromReference\n          )\n        ) {\n          throw new InvalidScientificInputError(\n            \"Temporal scene-radiance sample time must match its authoritative plan node.\"\n          );\n        }\n\n        const result =\n          parseSceneRadianceEvaluationResult(\n            supplied.result\n          );\n        if (\n          result.sampleId !==\n            node.expectedResultSampleId ||\n          result.providerProfileId !==\n            input.plan.query\n              .providerProfileId ||\n          result.sceneId !==\n            input.plan.query\n              .sceneId ||\n          result.wavelengthNanometers !==\n            input.plan.query\n              .wavelengthNanometers ||\n          result.wavelengthBasis !==\n            input.plan.query\n              .wavelengthBasis\n        ) {\n          throw new InvalidScientificInputError(\n            \"Temporal scene-radiance result identity must match the plan node/query exactly.\"\n          );\n        }\n\n        const value =\n          result\n            .spectralRadianceWattsPerSquareMeterSteradianNanometer;\n        average +=\n          value *\n          node\n            .normalizedTimeWeight;\n        integrated +=\n          value *\n          node\n            .timeMeasureSeconds;\n\n        return {\n          nodeId:\n            node.nodeId,\n          captureTimeSecondsFromReference:\n            node\n              .captureTimeSecondsFromReference,\n          normalizedTimeWeight:\n            node\n              .normalizedTimeWeight,\n          timeMeasureSeconds:\n            node\n              .timeMeasureSeconds,\n          spectralRadianceWattsPerSquareMeterSteradianNanometer:\n            value,\n          evidence:\n            result.evidence,\n          uncertainty:\n            result.uncertainty\n        };\n      }\n    );\n\n  if (\n    !Number.isFinite(average) ||\n    average < 0 ||\n    !Number.isFinite(\n      integrated\n    ) ||\n    integrated < 0\n  ) {\n    throw new InvalidScientificInputError(\n      \"Reduced temporal scene radiance must remain finite and non-negative.\"\n    );\n  }\n\n  return {\n    version:\n      SCENE_RADIANCE_TEMPORAL_SAMPLING_PLAN_VERSION,\n    planId:\n      input.plan.planId,\n    timeReference:\n      \"first-opening-boundary-phase\",\n    localExposureWindow: {\n      ...input.plan\n        .localExposureWindow\n    },\n    temporalSampleCount:\n      input.plan\n        .temporalSampleCount,\n    quadratureScheme:\n      \"uniform-midpoint\",\n    providerProfileId:\n      input.plan.query\n        .providerProfileId,\n    sceneId:\n      input.plan.query.sceneId,\n    wavelengthNanometers:\n      input.plan.query\n        .wavelengthNanometers,\n    wavelengthBasis:\n      input.plan.query\n        .wavelengthBasis,\n    quantity:\n      \"outgoing-spectral-radiance\",\n    averageSpectralRadianceWattsPerSquareMeterSteradianNanometer:\n      average,\n    integratedSpectralRadianceWattSecondsPerSquareMeterSteradianNanometer:\n      integrated,\n    nodes,\n    scientificStatus:\n      \"approximation\",\n    uncertaintyPropagation:\n      \"not-propagated\",\n    uncertaintyLimitation:\n      \"Per-node scene-radiance uncertainty is preserved; aggregate numeric uncertainty is not propagated because temporal correlation is not assumed.\",\n    sensorReadoutTimingUsedAsExposureTiming:\n      false\n  };\n}\n"]}

package/dist/schema/scene-radiance.d.ts

@@ -143,23 +143,24 @@ export interface SceneRadianceEvaluationBindingAssessment {
     photonsCalculated: false;
 }
 /**
- * Parses material-response metadata consumed by a scene-radiance provider.
+ * Parses material-response metadata used by a scene-radiance provider.
  *
- * RGB/PBR data is approximation-only. Spectral data describes a
- * wavelength-preserving provider input and does not itself calculate a BSDF,
- * scene radiance, fluorescence, emission, volumetrics, or polarization.
+ * RGB or PBR (physically based rendering) material data is always an approximation.
+ * Spectral data is a per-wavelength provider input. It does not itself compute a BSDF
+ * (how a surface scatters light), scene radiance, fluorescence, emission, volumetric
+ * effects or polarization.
  */
 export declare function parseSceneMaterialResponseProfile(value: unknown): SceneMaterialResponseProfile;
 /**
- * Returns the conservative material fidelity represented by a profile.
+ * Returns the material fidelity a profile supports, choosing the lower level when in doubt.
  */
 export declare function assessSceneMaterialResponseFidelity(profile: SceneMaterialResponseProfile): SceneMaterialResponseFidelity;
 /**
- * Parses a renderer-neutral provider capability/profile declaration.
+ * Parses a provider's declaration of what it can do (its profile). Works with any renderer.
  *
- * Schema 0.1.0 is deliberately approximation-only. A provider may consume
- * calibrated inputs, but this contract does not authorize a calibrated
- * outgoing-radiance claim until later spectral/transport completeness work.
+ * Schema 0.1.0 is approximation-only by design. A provider may use calibrated inputs,
+ * but this contract cannot support a claim of calibrated outgoing radiance. That needs
+ * later work on complete spectral and light-transport models.
  */
 export declare function parseSceneRadianceProviderProfile(value: unknown): SceneRadianceProviderProfile;
 /**
@@ -168,18 +169,17 @@ export declare function parseSceneRadianceProviderProfile(value: unknown): Scene
  */
 export declare function parseSceneRadianceEvaluationRequest(value: unknown): SceneRadianceEvaluationRequest;
 /**
- * Parses one provider-produced outgoing spectral-radiance result.
+ * Parses one outgoing spectral-radiance result from a provider.
  *
- * The numeric value is accepted as provider output; parsing validates units,
- * finite/nonnegative value, provenance, and identity fields but does not prove
- * that the provider's transport calculation is physically correct.
+ * The number is accepted as the provider reported it. Parsing checks units, that the
+ * value is finite and nonnegative, provenance and identity fields. It does not prove
+ * the provider's light-transport calculation is physically correct.
  */
 export declare function parseSceneRadianceEvaluationResult(value: unknown): SceneRadianceEvaluationResult;
 /**
- * Validates exact identity/binding relationships around provider output.
+ * Checks that a provider result matches its request and profile identities exactly.
  *
- * This function never recomputes the radiance value and never promotes the
- * provider's approximation to calibrated radiometry.
+ * It never recomputes the radiance value, and never upgrades the provider's
+ * approximation to calibrated radiometry.
  */
 export declare function validateSceneRadianceEvaluationBindings(input: ValidateSceneRadianceEvaluationBindingsInput): SceneRadianceEvaluationBindingAssessment;
-//# sourceMappingURL=scene-radiance.d.ts.map

package/dist/schema/scene-radiance.js

@@ -1,25 +1,29 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Parses material-response metadata consumed by a scene-radiance provider. RGB/PBR data is
- * approximation-only. Spectral data describes a wavelength-preserving provider input and does not
- * itself calculate a BSDF, scene radiance, fluorescence, emission, volumetrics, or polarization.
- * Returns the conservative material fidelity represented by a profile.
+ * Contracts for scene-radiance providers: the renderer or other code that reports how much
+ * light leaves a scene point toward the camera.
+ *
+ * It covers material-response metadata, provider capability profiles, single evaluation
+ * requests and results, and identity checks between them. The engine validates this data
+ * but does not compute scene radiance itself.
  * @see docs/SCENE_RADIANCE_AND_ILLUMINATION.md for equations, coordinate/unit conventions, blockers
  * and support limits.
  */
 import { InvalidConfigurationError } from "../core/configuration-error.js";
 import { parseEvidenceList } from "../core/evidence-provenance.js";
 import { parseSpectralWavelengthBasis, parseSpectralWavelengthRangeNanometers } from "../core/spectral.js";
+import { requireInputObject, requireInputArray, requireInputKeys, rejectUnknownFields, rejectUnknownVariantFields, UNCERTAINTY_VARIANT_FIELDS } from "../core/record-validation.js";
 export const SCENE_MATERIAL_RESPONSE_PROFILE_SCHEMA_VERSION = "0.1.0";
 export const SCENE_RADIANCE_PROVIDER_PROFILE_SCHEMA_VERSION = "0.1.0";
 export const SCENE_RADIANCE_EVALUATION_SCHEMA_VERSION = "0.1.0";
-function requireRecord(value, path) {
+function requireRecord(value, path, allowedKeys) {
     if (typeof value !== "object" ||
         value === null ||
         Array.isArray(value)) {
         throw new InvalidConfigurationError(path + " must be an object.");
     }
+    if (allowedKeys !== null)
+        rejectUnknownFields(value, allowedKeys, path);
     return value;
 }
 function requireNonEmptyString(value, path) {
@@ -53,7 +57,7 @@ function requireFraction(value, path) {
     return number;
 }
 function parseVector3(value, path) {
-    const record = requireRecord(value, path);
+    const record = requireRecord(value, path, ["x", "y", "z"]);
     return {
         x: requireFinite(record.x, path + ".x"),
         y: requireFinite(record.y, path + ".y"),
@@ -71,7 +75,8 @@ function parseUnitDirection(value, path) {
     return vector;
 }
 function parseUncertainty(value, path) {
-    const record = requireRecord(value, path);
+    const record = requireRecord(value, path, null);
+    rejectUnknownVariantFields(record, "kind", UNCERTAINTY_VARIANT_FIELDS, path);
     if (record.kind === "relative") {
         return {
             kind: "relative",
@@ -99,7 +104,7 @@ function parseLimitations(value, path) {
     return limitations;
 }
 function parseArtifact(value, path) {
-    const record = requireRecord(value, path);
+    const record = requireRecord(value, path, ["checksumSha256", "id"]);
     const checksumSha256 = requireNonEmptyString(record.checksumSha256, path + ".checksumSha256");
     if (!/^[a-f0-9]{64}$/iu.test(checksumSha256)) {
         throw new InvalidConfigurationError(path +
@@ -111,7 +116,13 @@ function parseArtifact(value, path) {
     };
 }
 function parseMaterialRepresentation(value, path) {
-    const record = requireRecord(value, path);
+    const record = requireRecord(value, path, null);
+    rejectUnknownVariantFields(record, "kind", {
+        unresolved: ["kind", "limitation"],
+        "rgb-pbr-approximation": ["kind", "colorSpace", "baseColor", "metallic", "roughness", "limitation"],
+        "spectral-wavelength-preserving-data": ["kind", "dataArtifact", "wavelengthBasis", "wavelengthRangeNanometers", "scatteringModel",
+            "scientificStatus", "uncertainty", "wavelengthChangingBehaviorModeled", "emissionModeled"]
+    }, path);
     if (record.kind === "unresolved") {
         return {
             kind: "unresolved",
@@ -124,7 +135,7 @@ function parseMaterialRepresentation(value, path) {
             throw new InvalidConfigurationError(path +
                 '.colorSpace must be "linear-srgb".');
         }
-        const baseColor = requireRecord(record.baseColor, path + ".baseColor");
+        const baseColor = requireRecord(record.baseColor, path + ".baseColor", ["red", "green", "blue"]);
         return {
             kind: "rgb-pbr-approximation",
             colorSpace: "linear-srgb",
@@ -188,14 +199,15 @@ function parseMaterialRepresentation(value, path) {
     };
 }
 /**
- * Parses material-response metadata consumed by a scene-radiance provider.
+ * Parses material-response metadata used by a scene-radiance provider.
  *
- * RGB/PBR data is approximation-only. Spectral data describes a
- * wavelength-preserving provider input and does not itself calculate a BSDF,
- * scene radiance, fluorescence, emission, volumetrics, or polarization.
+ * RGB or PBR (physically based rendering) material data is always an approximation.
+ * Spectral data is a per-wavelength provider input. It does not itself compute a BSDF
+ * (how a surface scatters light), scene radiance, fluorescence, emission, volumetric
+ * effects or polarization.
  */
 export function parseSceneMaterialResponseProfile(value) {
-    const record = requireRecord(value, "sceneMaterialResponseProfile");
+    const record = requireRecord(value, "sceneMaterialResponseProfile", ["schemaVersion", "materials", "fluorescenceModeled", "volumetricMaterialTransportModeled", "polarizationModeled", "profileId", "sceneId", "evidence"]);
     if (record.schemaVersion !==
         SCENE_MATERIAL_RESPONSE_PROFILE_SCHEMA_VERSION) {
         throw new InvalidConfigurationError('sceneMaterialResponseProfile.schemaVersion must be "' +
@@ -209,7 +221,7 @@ export function parseSceneMaterialResponseProfile(value) {
         const path = "sceneMaterialResponseProfile.materials[" +
             index +
             "]";
-        const material = requireRecord(entry, path);
+        const material = requireRecord(entry, path, ["materialResponseId", "evidence", "representation"]);
         return {
             materialResponseId: requireNonEmptyString(material.materialResponseId, path + ".materialResponseId"),
             evidence: parseEvidenceList(material.evidence, path + ".evidence"),
@@ -242,9 +254,13 @@ export function parseSceneMaterialResponseProfile(value) {
     };
 }
 /**
- * Returns the conservative material fidelity represented by a profile.
+ * Returns the material fidelity a profile supports, choosing the lower level when in doubt.
  */
 export function assessSceneMaterialResponseFidelity(profile) {
+    requireInputObject(profile, "assessSceneMaterialResponseFidelity input");
+    // 2.0.0: the whole profile is validated, so an unknown field at any level is rejected.
+    parseSceneMaterialResponseProfile(profile);
+    requireInputArray(profile.materials, "profile.materials");
     if (profile.materials.some((entry) => entry.representation.kind ===
         "unresolved")) {
         return "unresolved";
@@ -265,7 +281,7 @@ export function assessSceneMaterialResponseFidelity(profile) {
     return "mixed";
 }
 function parseProviderFidelity(value, path) {
-    const record = requireRecord(value, path);
+    const record = requireRecord(value, path, ["spectral", "material", "visibility", "directTransport", "indirectTransport"]);
     const spectral = record.spectral;
     if (spectral !== "wavelength-resolved" &&
         spectral !==
@@ -304,14 +320,14 @@ function parseProviderFidelity(value, path) {
     };
 }
 /**
- * Parses a renderer-neutral provider capability/profile declaration.
+ * Parses a provider's declaration of what it can do (its profile). Works with any renderer.
  *
- * Schema 0.1.0 is deliberately approximation-only. A provider may consume
- * calibrated inputs, but this contract does not authorize a calibrated
- * outgoing-radiance claim until later spectral/transport completeness work.
+ * Schema 0.1.0 is approximation-only by design. A provider may use calibrated inputs,
+ * but this contract cannot support a claim of calibrated outgoing radiance. That needs
+ * later work on complete spectral and light-transport models.
  */
 export function parseSceneRadianceProviderProfile(value) {
-    const record = requireRecord(value, "sceneRadianceProviderProfile");
+    const record = requireRecord(value, "sceneRadianceProviderProfile", ["schemaVersion", "outputQuantity", "outputUnit", "scientificStatus", "wavelengthChangingTransportModeled", "volumetricTransportModeled", "polarizationModeled", "profileId", "sceneId", "illuminationProfileId", "illuminationTemporalProfileId", "materialResponseProfileId", "uncertainty", "fidelity", "evidence", "limitations"]);
     if (record.schemaVersion !==
         SCENE_RADIANCE_PROVIDER_PROFILE_SCHEMA_VERSION) {
         throw new InvalidConfigurationError('sceneRadianceProviderProfile.schemaVersion must be "' +
@@ -376,7 +392,11 @@ function parseResolvedWavelengthBasis(value, path) {
     return basis;
 }
 function parseEvaluationTarget(value, path) {
-    const record = requireRecord(value, path);
+    const record = requireRecord(value, path, null);
+    rejectUnknownVariantFields(record, "kind", {
+        "surface-point": ["kind", "sceneObjectId", "materialResponseId", "positionM", "outgoingDirectionUnitVector"],
+        "environment-direction": ["kind", "outgoingDirectionUnitVector"]
+    }, path);
     if (record.kind === "surface-point") {
         return {
             kind: "surface-point",
@@ -402,7 +422,7 @@ function parseEvaluationTarget(value, path) {
  * physical time, wavelength, and outgoing direction.
  */
 export function parseSceneRadianceEvaluationRequest(value) {
-    const record = requireRecord(value, "sceneRadianceEvaluationRequest");
+    const record = requireRecord(value, "sceneRadianceEvaluationRequest", ["schemaVersion", "sampleId", "providerProfileId", "sceneId", "illuminationProfileId", "materialResponseProfileId", "target", "timeSecondsFromExposureStart", "wavelengthNanometers", "wavelengthBasis"]);
     if (record.schemaVersion !==
         SCENE_RADIANCE_EVALUATION_SCHEMA_VERSION) {
         throw new InvalidConfigurationError('sceneRadianceEvaluationRequest.schemaVersion must be "' +
@@ -423,14 +443,14 @@ export function parseSceneRadianceEvaluationRequest(value) {
     };
 }
 /**
- * Parses one provider-produced outgoing spectral-radiance result.
+ * Parses one outgoing spectral-radiance result from a provider.
  *
- * The numeric value is accepted as provider output; parsing validates units,
- * finite/nonnegative value, provenance, and identity fields but does not prove
- * that the provider's transport calculation is physically correct.
+ * The number is accepted as the provider reported it. Parsing checks units, that the
+ * value is finite and nonnegative, provenance and identity fields. It does not prove
+ * the provider's light-transport calculation is physically correct.
  */
 export function parseSceneRadianceEvaluationResult(value) {
-    const record = requireRecord(value, "sceneRadianceEvaluationResult");
+    const record = requireRecord(value, "sceneRadianceEvaluationResult", ["schemaVersion", "quantity", "unit", "scientificStatus", "sampleId", "providerProfileId", "sceneId", "wavelengthNanometers", "wavelengthBasis", "spectralRadianceWattsPerSquareMeterSteradianNanometer", "uncertainty", "evidence", "limitations"]);
     if (record.schemaVersion !==
         SCENE_RADIANCE_EVALUATION_SCHEMA_VERSION) {
         throw new InvalidConfigurationError('sceneRadianceEvaluationResult.schemaVersion must be "' +
@@ -470,13 +490,15 @@ function requireEqual(actual, expected, message) {
     }
 }
 /**
- * Validates exact identity/binding relationships around provider output.
+ * Checks that a provider result matches its request and profile identities exactly.
  *
- * This function never recomputes the radiance value and never promotes the
- * provider's approximation to calibrated radiometry.
+ * It never recomputes the radiance value, and never upgrades the provider's
+ * approximation to calibrated radiometry.
  */
 export function validateSceneRadianceEvaluationBindings(input) {
+    requireInputKeys(input, "validateSceneRadianceEvaluationBindings", ["providerProfile", "illuminationProfile", "illuminationTemporalProfile", "materialResponseProfile", "request", "result"]);
     const { providerProfile, illuminationProfile, illuminationTemporalProfile, materialResponseProfile, request, result } = input;
+    requireInputObject(providerProfile, "providerProfile input");
     requireEqual(providerProfile.sceneId, illuminationProfile.sceneId, "Provider and illumination profiles must reference the same sceneId.");
     requireEqual(providerProfile.sceneId, materialResponseProfile.sceneId, "Provider and material-response profiles must reference the same sceneId.");
     requireEqual(providerProfile.illuminationProfileId, illuminationProfile.profileId, "Provider illuminationProfileId must match the supplied illumination profile.");