@photivra/engine 0.6.0 → 1.0.1

package/docs/PRODUCTION_COMPOSITION.md

@@ -0,0 +1,373 @@
+# Production Image-Formation Plan
+
+Release context: **package 1.0.1 candidate / root API 1.0.1**. 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_0_1.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

@@ -0,0 +1,131 @@
+# Executed environment production capture
+
+Release context: **package 1.0.1 candidate / root API 1.0.1**. 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_0_1.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,5 +1,7 @@
 # Scientific and Source Provenance
 
+Release context: **package 1.0.1 candidate / root API 1.0.1**. 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_0_1.md).
+
 Every scientific or calculation module in this repository must have a traceable, legally clean origin.
 
 ## Allowed foundations
@@ -80,6 +82,8 @@ The composed `simulatePocCamera()` response is not itself a `CalculationResult<T
 
 ## 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: