@photivra/engine 1.5.0 → 2.1.0

package/docs/PRODUCTION_COMPOSITION.md

@@ -1,373 +0,0 @@
-# Production Image-Formation Plan
-
-Release context: **package 1.2.0 candidate / root API 1.2.0**. Subsystem/model versions and dated introduction or measurement records below are independent historical identities; they are not distribution versions. See [developer navigation](DEVELOPERS.md) and [release contract](RELEASE_1_2_0.md).
-
-Photivra's production composition layer is separate from the legacy
-`simulatePocCamera()` proof-of-concept API.
-
-The plan contract is a renderer-neutral, browser-safe semantic layer:
-
-```text
-prepared static context
-  + immutable capture snapshot
-  + authoritative image-formation graph
-  -> deterministic production image-formation plan
-```
-
-It does not turn the TypeScript engine into a path tracer and it does not
-permit an application or renderer to silently redefine scientific ordering.
-
-## Contract versions
-
-The production plan has independent version surfaces:
-
-- `PRODUCTION_IMAGE_FORMATION_PLAN_VERSION`;
-- `PREPARED_IMAGE_FORMATION_CONTEXT_VERSION`;
-- `PRODUCTION_CAPTURE_SNAPSHOT_VERSION`;
-- `RENDERER_CAPABILITY_SCHEMA_VERSION`;
-- `IMAGE_FORMATION_FIDELITY_PROFILE_SCHEMA_VERSION`.
-
-Those remain distinct from:
-
-- npm package version;
-- `ENGINE_API_VERSION`;
-- `IMAGE_FORMATION_CONTRACT_VERSION`;
-- `POC_SIMULATION_API_VERSION`.
-
-A plan records all of these materially relevant engine/plan contract versions.
-
-## Prepare once, evaluate many
-
-Use `prepareImageFormationContext()` for relatively static semantic inputs:
-
-- resolved generic equipment exposure capabilities;
-- scene/provider identity;
-- #110 optical-throughput profile;
-- output-geometry profile identity;
-- renderer capability declaration;
-- fidelity profile.
-
-The returned context is cloned, deeply frozen, and fingerprinted.
-
-Later mutation of UI objects or source profile objects cannot change the
-prepared context.
-
-## Immutable capture snapshot
-
-Use `createProductionCaptureSnapshot()` for per-capture dynamic state:
-
-- capture ID;
-- release-frame ID;
-- committed scene-state ID;
-- physical scene time;
-- aperture/shutter/ISO;
-- output-state identity;
-- deterministic capture seed;
-- optional #85 scene-radiance request/result plus #110 focus/field input;
-- optional generic front-of-lens filter stack.
-
-The snapshot is also cloned, deeply frozen, and fingerprinted.
-
-Once committed, later UI state changes do not mutate its plan identity.
-
-## Fidelity is capability-based
-
-A fidelity profile does not use labels such as `low`, `medium`, or `high`.
-
-It declares:
-
-- required image-formation stages;
-- required effects and model identities;
-- required renderer spectral capability;
-- sensor-domain requirement;
-- depth requirement.
-
-Stage dependencies are expanded from `getImageFormationContract()`, which
-remains the semantic source of truth.
-
-Request order does not change semantic identity: set-like stage/effect lists
-are normalized into authoritative contract order before fingerprinting.
-
-## Stage and effect states
-
-The plan distinguishes:
-
-- `active`;
-- `modeled-zero`;
-- `omitted-by-fidelity`;
-- `unsupported`;
-- `blocked`.
-
-This matters because a numerically neutral modeled effect is not the same as
-an absent or unsupported effect.
-
-The first composed effect is illumination vignetting:
-
-- explicit unity throughput -> `modeled-zero`;
-- non-unity declared throughput -> `active`;
-- not requested -> `omitted-by-fidelity`.
-
-A non-unity field-throughput input cannot be supplied while the fidelity
-profile omits illumination vignetting; that becomes a structured blocker.
-
-## Renderer capability declaration
-
-A renderer declares semantic capability, not raw WebGPU/Three.js objects.
-
-The declaration includes:
-
-- optimized-interactive vs reference consumer kind;
-- supported stages/effects;
-- wavelength-resolved vs wavelength-independent spectral support;
-- temporal-sampling bound;
-- depth support;
-- inverse field mapping;
-- alpha representation;
-- depth-order preservation;
-- sensor-domain processing capability.
-
-The plan does not silently degrade requested fidelity.
-
-Capability mismatch becomes a structured blocker such as:
-
-- `renderer-stage-unsupported`;
-- `renderer-effect-unsupported`;
-- `renderer-spectral-capability-insufficient`;
-- `renderer-sensor-domain-processing-unavailable`;
-- `renderer-depth-capability-insufficient`.
-
-## First physical composed path
-
-Current plan schema `0.5.0` composes the #110 physical sample path.
-
-For a fidelity profile requiring `lens-field-pupil-evaluation`, dependencies
-expand to:
-
-```text
-scene-ray-projection
-  -> scene-radiance-evaluation
-  -> lens-field-pupil-evaluation
-```
-
-The plan consumes one immutable #85 scene-radiance request/result and evaluates
-#110 with:
-
-- prepared lens-throughput profile;
-- resolved equipment focal length;
-- committed aperture;
-- explicit focus state;
-- image-plane field point;
-- declared field throughput.
-
-The plan stores the resulting pre-sensor-stack spectral irradiance result.
-
-This path never substitutes an RGB preview for physical spectral irradiance.
-
-## Release-frame and white-balance capture binding
-
-Plan contract `0.5.0` / capture snapshot `0.3.0` add the preferred handoff from #105 release sequencing into production composition.
-
-Use `createProductionCaptureSnapshotFromReleaseFrame()` when a logical release frame has already been committed. The helper takes ownership from the release frame for:
-
-- release sequence/frame identity;
-- aperture, shutter and ISO;
-- focus state;
-- AE/AF/AWB automation state;
-- exposure start/end and sequence-relative scene time;
-- timing constraints;
-- stochastic frame seed;
-- committed white-balance state identity.
-
-When the release frame declares `whiteBalanceStateId`, the full resolved #108 WB state must be supplied and its ID must match. A release frame with locked AWB requires a locked WB state.
-
-The snapshot stores both the release binding and resolved WB state inside its deterministic fingerprint. Later UI changes therefore cannot alter the committed capture.
-
-The release-frame sequence-relative scene time is preserved separately from `sceneTimeSecondsFromExposureStart`: the latter remains the local time used by #85/#110 scene-radiance evaluation within the exposure.
-
-Existing `createProductionCaptureSnapshot()` remains supported for lower-level callers. Its optional release/WB fields receive the same validation when present.
-
-## Front-of-lens filter capture state
-
-Plan contract `0.5.0` / capture snapshot `0.3.0` preserve optional #135 front-of-lens filter state in the immutable physical scene sample.
-
-The filter stack is:
-
-- parsed/validated when the capture snapshot is committed;
-- included in the capture fingerprint;
-- forwarded to #110 exactly once;
-- preserved in the #110 physical result as filter count, transmission factor, attenuation and evidence.
-
-Changing only the selected filter stack changes capture/plan identity and the physical sensor-plane irradiance result, but it does not alter committed aperture/f-number, focus geometry, DOF or diffraction.
-
-Filter transmission remains separate from lens transmission/T-stop and from sensor optical-stack response.
-
-## Temporal capture composition
-
-Plan contract `0.2.0` adds immutable temporal-capture input.
-
-A capture may bind:
-
-- #12 exposure-window input;
-- sensor readout declaration;
-- physical imaging area and capture orientation;
-- optional constant pure-camera-rotation velocity;
-- deterministic temporal quadrature sample count.
-
-The planner evaluates exposure windows and sensor readout separately:
-
-```text
-exposure-window time reference:
-  first-opening-boundary-phase
-
-sensor readout phase:
-  separate native-sensor timing contract
-
-synchronization:
-  not assumed
-```
-
-If pure rotation is supplied, the planner reuses `calculateCaptureRotationTemporalQuadrature()`. The committed quadrature count is part of capture identity and a renderer may not silently reduce it.
-
-Requested spatial-camera-rotation distinguishes:
-
-- nonzero rotation with resolved quadrature -> `active`;
-- explicit zero angular velocity -> `modeled-zero`;
-- missing rotation model -> `blocked`.
-
-Requested rolling-readout distinguishes:
-
-- rolling native readout -> `active`;
-- global/no-spatial-skew timing -> `modeled-zero`;
-- missing readout declaration -> `blocked`.
-
-A renderer whose declared temporal-sampling capacity is below the committed quadrature count receives a structured `renderer-temporal-sampling-insufficient` blocker.
-
-The image-formation graph is still authoritative. Because `temporal-exposure-readout` depends on `field-wavelength-psf`, useful temporal results may exist while the whole requested fidelity plan remains blocked on the sample-only route. Plan 0.7.0 separately supports [bounded environment execution](PRODUCTION_ENVIRONMENT_CAPTURE.md), including explicit modeled-zero or supported local PSF disposition.
-
-## Scientific assurance composition
-
-Plan contract `0.4.0` records the cross-engine #134 `scientificAssurance` summary whenever composed scientific results exist.
-
-The physical path preserves distinct required components for scene radiance, optical throughput, the Photivra primary-optics bridge model, selected front filters, and non-unity field throughput when present. Temporal composition adds its own explicit schedule-model component.
-
-The summary:
-
-- cannot exceed the weakest required component status;
-- degrades to `unknown` when required evidence is missing;
-- preserves component evidence and uncertainty declarations;
-- reports quantified component uncertainty as `not-propagated` unless a real propagation rule exists;
-- never converts `not-quantified` into zero;
-- participates in the plan fingerprint.
-
-See [Scientific Assurance and Uncertainty Composition](SCIENTIFIC_ASSURANCE.md).
-
-## Optimized and reference consumers
-
-Use `createProductionPlanConsumerManifest()` to project one finalized semantic plan into either:
-
-- `interactive-optimized`; or
-- `reference`.
-
-Both manifests retain the same:
-
-- plan fingerprint;
-- active/modeled stage identities;
-- active/modeled effect identities;
-- #110 physical result;
-- temporal capture result;
-- capture seed;
-- structured blockers;
-- scientific assurance/evidence/uncertainty.
-
-The consumer role changes execution responsibility only. It does not authorize changing scientific inputs, reordering stages, replacing seeds, or reducing committed temporal samples.
-
-## V1 integration map
-
-[V1 composition and consumer map](V1_COMPOSITION_MAP.md) links all 32 scoped
-items to their implemented primitives/consumers and representative tests, and
-records the missing upstream RAW handoff and existing ticket ownership. Bounded
-Standalone RAW/output adapter execution does not activate production-plan stages.
-The explicitly bound plan 0.7.0 environment route below does.
-
-## Executed environment capture and explicit unsupported capabilities
-
-Plan 0.7.0 accepts an optional `environmentCapture` declaration. It executes
-`simulateEnvironmentSensorRawFrame()` inside the authoritative graph, rather
-than treating a caller's RAW attachment as proof that upstream work ran. With
-all required renderer declarations and optional processing policy, the bounded
-route reaches all fourteen stages. The earlier sample-based and attached-RAW
-routes remain available and retain their missing-stage blockers.
-
-See [executed production capture](PRODUCTION_ENVIRONMENT_CAPTURE.md) for input
-ownership, exact event/profile binding, optional output policy, replay and the
-current supported scientific envelope. Stage activation refers to the executed
-bounded algorithms; it does not establish calibrated provider transport or
-physical visibility. An explicitly omitted PSF is a declared point-optics
-model, with its evidence and limitation, not proof of a physically perfect lens.
-
-Required effects outside a route's actual implementation continue to report
-`engine-effect-not-composed`. The plan cannot silently reinterpret a requested
-surface, depth, stabilization, breathing or field-transport model as an ideal
-environment ray. Existing foundation APIs and their direct consumers remain
-valid; unsupported combinations are not approved V1 deferrals.
-
-## Structured blockers vs malformed input
-
-Malformed schemas, non-finite numbers, invalid equipment settings, identity
-drift, and tampered fingerprints fail fast.
-
-Scientifically incomplete but structurally valid requests return a blocked
-plan with explicit blocker codes, for example:
-
-- missing #110 optical profile;
-- missing physical scene sample;
-- renderer fidelity mismatch;
-- requested stage not yet composed;
-- #110 evaluation blocked by wavelength/applicability constraints.
-
-## Deterministic identity
-
-Prepared contexts, capture snapshots, and finished plans use canonical JSON
-serialization plus an FNV-1a 32-bit fingerprint.
-
-The fingerprint is explicitly:
-
-```text
-non-cryptographic
-purpose: deterministic reproducibility key
-```
-
-It is not an integrity/security checksum.
-
-`serializeProductionImageFormationPlan()` emits canonical key ordering so
-identical semantic inputs serialize identically across supported runtimes.
-
-## Stochastic ownership
-
-The capture snapshot owns one explicit unsigned 32-bit capture seed.
-
-The plan records:
-
-```text
-backendRandomnessMayRedefineScientificResult = false
-```
-
-Future stochastic stages must derive reproducible sub-seeds from an explicit
-engine-owned policy rather than allowing backend randomness to silently change
-scientific results.
-
-## POC compatibility
-
-The production plan is additive.
-
-It does not call, rewrite, or reinterpret `simulatePocCamera()`.
-
-`POC_SIMULATION_API_VERSION` remains independent, and plan results report
-`legacyPocModified: false`.
-
-Migration should happen deliberately:
-
-1. add/expand production plan stages;
-2. add optimized/reference consumers;
-3. migrate application consumers;
-4. deprecate POC only through an explicit compatibility decision.

package/docs/PRODUCTION_ENVIRONMENT_CAPTURE.md

@@ -1,131 +0,0 @@
-# Executed environment production capture
-
-Release context: **package 1.2.0 candidate / root API 1.2.0**. Subsystem/model versions and dated introduction or measurement records below are independent historical identities; they are not distribution versions. See [developer navigation](DEVELOPERS.md) and [release contract](RELEASE_1_2_0.md).
-
-Introduced at root API 0.116.0 and production plan 0.7.0, this adds a bounded source-to-RAW route
-inside the existing authoritative image-formation graph. Consumer manifest
-0.2.0 exposes the same immutable executed capture and processed-output results.
-At introduction, package 0.6.0, POC 0.20.0, capture snapshot 0.3.0 and the image-formation
-ordering contract 0.4.0 remain unchanged.
-
-## Inputs and ownership
-
-`createProductionImageFormationPlan()` accepts `environmentCapture` with:
-
-- `capture`: the existing `SimulateEnvironmentSensorRawFrameInput`, including
-  a complete native frame, owned per-site sensor/readout profiles, shared scene
-  and optical state, exact local shutter schedule and synchronous evaluator;
-- optional `processing`: the existing processed-RAW policy, with
-  `reconstruction.rawFrame` omitted. The plan supplies its executed RAW frame.
-
-The declaration cannot be combined with `processedOutput` or an independently
-declared `physicalSceneSample`. These are separate supported input routes,
-not interchangeable evidence of upstream execution.
-
-The immutable snapshot must match capture/event identity, scene state/time,
-seed, aperture/shutter/ISO, resolved WB identity/gains and release focus. The
-prepared context additionally binds provider scene/profile, the complete
-optical bridge profile and selected physical focal length. Native raster,
-imaging area, orientation and the opening/closing schedule must match the
-temporal snapshot. This producer executes a full-native shutter schedule: an
-explicit temporal active rectangle must cover the full native raster. Cropped
-timing cannot be silently substituted for it; output/physical capture geometry
-keeps its separate downstream meaning. Motion and sample count must match
-its rotation declaration; omitted rotation authorizes only zero angular motion.
-Readout diagnostics remain independent of exposure timing.
-
-Requested stages are expanded from `getImageFormationContract()`. Renderer
-stage support, wavelength-resolved capability, sensor-domain support, inverse
-mapping, temporal sample budget and existing effect constraints must pass
-before provider code is invoked. The ADC stage must be requested, directly or
-through downstream dependencies. Known output crop/resampling incompatibilities
-also fail before provider calls, using the same envelope check as attached-RAW
-processing. Pixel-dependent reconstruction/correction checks still run on the
-actual realized RAW; preflight is not a proof of complete output readiness.
-
-The provider receives owned frozen requests at each wavelength/local-time/PSF
-support node. Execution snapshots all capture data and optional output policy
-before invoking provider code. Callback mutation of the original caller objects
-cannot change execution or its post-capture policy. No function, file IO,
-network request, renderer installation or runtime dependency enters the plan's
-serialized representation.
-
-## Execution and consumers
-
-The existing environment producer generates focus-aware inverse rays, invokes
-the supplied provider, evaluates optical throughput and optional local sampled
-PSF support, then applies the existing optical-stack/spatial/spectral response
-and temporal EQE integration. Existing dark-current, charge-completeness,
-capacity, seeded noise, signed readout and ADC APIs create native CFA codes.
-There is no alternate RAW producer, RGB-to-RAW conversion or new seed schedule.
-
-With complete declarations and a valid processing policy, all fourteen graph
-stages have executed bounded consumers. An explicitly omitted PSF is recorded
-as `modeled-zero` for the declared point-optics model, with its supplied evidence
-and limitation; it is not a physical assertion of zero lens blur. Unrequested
-stages remain omitted by fidelity. A failed source preflight leaves requested
-stages blocked rather than advertising execution.
-
-`environmentCaptureResult` retains the full executed lineage and child results.
-`environmentCaptureRequestFingerprint` commits the capture data, excluding
-callback identity. The plan fingerprint includes that commitment, returned
-provider values, realized RAW and optional processing result. Replay requires
-the same inputs **and** provider responses. Different source results, even from
-the same callback, change plan identity. These FNV keys are not cryptographic
-integrity or provenance certificates.
-
-Optional processing reuses `calculateProcessedSensorRaw()` on the exact returned
-frame: reconstruction, channel-basis color/WB once, selected native correction,
-physical orientation, digital crop and SDR rendering retain their existing
-order. Rendering changes do not rewrite physical capture, charge/noise or RAW.
-The resulting source frame can also feed the existing paired DNG/JPEG exporter;
-the plan itself performs no file serialization.
-
-`createProductionPlanConsumerManifest()` carries the same capture/output result
-references for interactive and reference consumers. Neither consumer may change
-seed, committed inputs, sample count or stage order. Existing manifests without
-the new optional execution fields retain their old data shape apart from the
-explicit manifest/plan versions.
-
-## Scientific envelope and remaining ownership
-
-This route preserves the existing adapter's limits: at most 4,096 native sites
-and 100,000 aggregate provider evaluations; one-to-one native CFA timing;
-opening-reference scene time zero; ideal focus-aware environment projection;
-constant-axis rotation; explicit unity field throughput; and optional
-destination-local sampled PSF. Continuous spectral density, source-plane and
-response-area bindings are mandatory. The output reference route keeps its
-explicit topology, reconstruction support and 1:1 output-crop constraints.
-
-Execution is approximation-only. Supplied provider invocation does not verify
-physical transport, visibility, world pose/translation, calibration, convergence
-or global field-energy conservation. Child `providerTransportVerified`,
-`upstreamRadiometryVerified`, `producerOriginVerified` and standalone
-`productionPlanActivated` fields retain their original conservative meanings.
-The parent plan records what actually executed; it never upgrades those flags.
-Child evidence/limitations remain inspectable, and combined uncertainty remains
-unquantified rather than inferred from a count of successful stages.
-
-Required unsupported effects or combinations still block. No wider scientific
-capability, supported megapixel limit or V1 deferral is approved by this route.
-The [32-item composition map](V1_COMPOSITION_MAP.md) retains the specific
-foundation/consumer/acceptance owners. Broader same-scene equipment-tier
-acceptance is #116/#119, final performance remeasurement is #43/#45, final
-science conformance is #131, and the exhaustive release documentation/source
-audit is #180. #165 C2PA remains post-V1.
-
-## Migration and verification
-
-Consumers of serialized plans must recognize plan 0.7.0 and consumer manifest
-0.2.0. New fields are optional; existing attached-RAW and sample-only callers
-need no input migration. The current root API retains the additive
-`ProductionEnvironmentCaptureInput` type. The standalone environment producer
-and processed-output model versions, hashes and seed schedule are unchanged.
-
-`test/production-image-formation-plan.test.ts` covers complete graph execution,
-global/rolling shutter, sampled/omitted PSF, source-response replay, caller
-mutation, rejected context/event/profile/renderer bindings before callbacks,
-all four physical orientations with an output crop, incompatible resampling,
-resolved WB and selected correction with exact native RAW preservation.
-Existing SI-count, phase/support, noise/ADC, file-byte and correction suites
-remain the independent domain oracles.

package/docs/PROVENANCE.md

@@ -1,115 +0,0 @@
-# Scientific and Source Provenance
-
-Release context: **package 1.2.0 candidate / root API 1.2.0**. Subsystem/model versions and dated introduction or measurement records below are independent historical identities; they are not distribution versions. See [developer navigation](DEVELOPERS.md) and [release contract](RELEASE_1_2_0.md).
-
-Every scientific or calculation module in this repository must have a traceable, legally clean origin.
-
-## Allowed foundations
-
-An implementation may be based on:
-
-1. Public-domain facts and mathematics.
-2. Established mathematical identities and physical laws.
-3. Scientific methods described in public technical literature, standards, patents, or papers, provided protected text/code/tables/figures are not copied unless separately licensed for that use and any applicable third-party patent rights are separately considered.
-4. Third-party code, datasets, model weights, or calibration material only when the applicable license explicitly permits the intended copying, modification, redistribution, and commercial use and is compatible with this project.
-
-"Available on the internet" is not sufficient permission.
-
-A paper, standard, or patent publication may explain a method without granting copyright permission to copy its expression and without granting a patent license. Independent implementation addresses source-code/prose provenance; it does not by itself resolve active third-party patent claims.
-
-## Source evidence and reuse rights
-
-Factual/source evidence keeps **origin** separate from **reuse rights**.
-
-- `sourceOrigin` identifies who originated the referenced fact or data: manufacturer, third party, or Photivra.
-- `reuseStatus` identifies how Photivra may use it: factual-reference-only, reusable-data, or Photivra-owned.
-- Reusable data requires an explicit license.
-- Photivra-owned material must originate from Photivra.
-- Manufacturer or third-party sources may be either factual-reference-only or explicitly reusable when licensing supports that use.
-
-One evidence record must not silently support unrelated facts. Scalar metadata may cite multiple evidence records, and multi-valued capabilities should carry evidence per value.
-
-Evidence provenance is not a confidence score and does not establish scientific effect by itself. Descriptive hardware facts only affect calculations when a separate documented model explicitly consumes them.
-
-## Independent implementation
-
-When a reference explains a method but does not license its implementation or text for reuse:
-
-- understand the mathematical/scientific method;
-- write a fresh implementation from the method, not from proprietary source structure;
-- do not translate, mechanically rewrite, or adapt proprietary source code;
-- do not copy protected tables, diagrams, explanatory prose, calibration datasets, waveform files, or model weights;
-- add tests based on independently derived analytical cases or clearly reusable data;
-- record material references and any known licensing/patent constraints.
-
-## AI-assisted work
-
-AI-assisted code, documentation, tests, or research notes are treated as untrusted draft material until substantively reviewed by a human contributor.
-
-A contributor using an AI system remains responsible for:
-
-- confirming that the submitted expression is appropriate to distribute under Apache-2.0;
-- checking for suspiciously copied/source-like output;
-- validating scientific and technical correctness;
-- ensuring no confidential or restricted third-party material was supplied to the tool;
-- making the DCO certification for the final submitted contribution.
-
-An AI system's assertion about originality, copyrightability, patents, or license compatibility is not accepted as provenance evidence.
-
-## Module record
-
-Meaningful scientific modules should document, in JSDoc or an adjacent reference document:
-
-- mathematical/physical basis;
-- assumptions and valid range;
-- units and coordinate conventions;
-- whether the implementation is independent;
-- public references used to understand or validate the method;
-- third-party code/data incorporated, if any;
-- the license for any incorporated third-party material;
-- uncertainty or approximation status where applicable.
-
-## Provenance labels
-
-Scientific calculation envelopes use these labels:
-
-- `calculated`: directly computed from the documented model.
-- `calibrated`: uses measurement/calibration data with documented reuse rights.
-- `estimated`: an input or result is inferred rather than known exactly.
-- `approximation`: a deliberately simplified model is used.
-
-The composed `simulatePocCamera()` response is not itself a `CalculationResult<T>`; it reports aggregate/component provenance separately and uses `mixed` when calculated components are combined with explicitly approximate components.
-
-## Uncertainty and quality metadata
-
-Cross-engine composition semantics are defined in [Scientific Assurance and Uncertainty Composition](SCIENTIFIC_ASSURANCE.md). That contract preserves module-level provenance/quality rather than replacing it.
-
-Provenance answers **how a result was produced**; uncertainty answers **what quantitative accuracy/variability is defensibly known**. They are related but must not be conflated.
-
-When available, `CalculationResult.quality` records uncertainty components by affected quantity and source:
-
-- `measurement`: variability/uncertainty originating in measured inputs or observations;
-- `calibration`: uncertainty originating in a calibration or calibrated reference;
-- `model-approximation`: quantified error attributed to a simplified/inexact model.
-
-An approximation label does not by itself justify a numeric model-error estimate. If no defensible bound exists, retain the approximation provenance and assumptions without fabricating quality metadata.
-
-Confidence/coverage levels are optional and must include a stated basis. They are not subjective confidence scores.
-
-Valid-range metadata describes where a model/calibration is considered applicable. It is not an uncertainty interval.
-
-When composing models, preserve uncertainty components separately unless a documented model provides a defensible combination rule. Do not imply statistical independence, add errors in quadrature, or publish a single aggregate confidence score without evidence.
-
-## Radiometry readiness evidence
-
-Radiometry readiness is a declaration/validation gate, not proof that a calibration is correct.
-
-A component labeled `calibrated` must identify its model/version, supporting evidence, and quantified uncertainty. If uncertainty cannot yet be quantified, the component may still be represented, but the overall assessment cannot become `calibrated-ready`.
-
-Data-bearing calibration artifacts are referenced by stable identifier plus SHA-256 checksum. Publicly viewable curves/tables without reuse rights must not be copied into those artifacts. Manufacturer-published factual specifications may support independently authored models, while copied calibration datasets require explicit reusable licensing or Photivra ownership.
-
-An `approximation` remains explicitly approximate even when all prerequisite categories are present. Readiness must never be used to upgrade approximation provenance into calibration provenance.
-
-## Release gate
-
-Ambiguous licensing, unresolved material patent risk, uncertain provenance, unexplained copied material, fabricated uncertainty, undocumented uncertainty combination, or unsupported scientific claims block release until resolved.