@photivra/engine 0.5.1 → 1.0.0

package/docs/API_STYLE.md

@@ -1,5 +1,7 @@
 # Public API Style
 
+Release context: **package 1.0.0 candidate / root API 0.116.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_0.md).
+
 The open engine should feel like one coherent library.
 
 ## Rules
@@ -97,3 +99,133 @@ Photivra has multiple independent version surfaces:
 Do not reuse one version as a proxy for another. A change to a parser/schema does not necessarily require changing the POC contract, and a POC response change does not necessarily mean the npm package has been released.
 
 Before 1.0, public APIs may evolve with documented changes. Breaking or semantically meaningful contract changes must update the relevant version surface, tests, changelog, and migration/compatibility documentation. After 1.0, breaking public-contract changes require an appropriate major-version transition.
+
+
+## Public function verb families
+
+Use the established verb family that matches the operation's semantics. Do not invent a new synonym when one of these already fits.
+
+- `calculate*` — deterministic scientific/numeric calculation.
+- `estimate*` — explicit approximation/estimate.
+- `parse*` — validate and normalize a versioned/untrusted configuration boundary.
+- `validate*` — assert/check validity without changing semantic identity.
+- `resolve*` — derive one deterministic semantic state from already-defined inputs/profiles.
+- `assess*` — produce a compatibility/readiness/applicability assessment, including structured blockers.
+- `create*` — construct a new semantic record/snapshot/manifest whose identity is part of the contract.
+- `prepare*` — validate/canonicalize relatively static context for repeated later evaluation.
+- `serialize*` — convert an authoritative semantic value to its documented deterministic serialized representation.
+- `compose*` — combine multiple independently meaningful inputs/stages into a higher-level semantic result.
+- `integrate*` / `reduce*` — mathematically aggregate explicit measures/samples under a documented model.
+- `distribute*` — allocate an integrated quantity across explicitly normalized fractions while preserving its quantity domain; this does not create a continuous density from discrete spectral lines.
+- `evaluate*` / `meter*` — evaluate a declared model/policy against current scene/capture data.
+- `map*` / `transform*` — coordinate/domain transformation with explicit source/destination semantics.
+- `bind*` — attach one already-defined result/state to another authoritative context without re-solving it.
+- `set*` — return an updated immutable semantic value for a narrowly defined state-setting operation.
+- `get*` — return a descriptive/static contract owned by the engine.
+- `simulate*` — intentionally composed simulation/orchestration API.
+
+Existing result factories `calculatedResult`, `estimatedResult`, `approximationResult`, and `calibratedResult` are documented core helpers rather than new public verb families.
+
+A new verb family requires a concrete semantic distinction from the existing set and a documentation/update review.
+
+## Input and return-shape consistency
+
+Choose API shape from semantic role, not module history.
+
+- Public scientific calculations with multiple inputs accept one typed input object.
+- Parsers accept one value/configuration and return the validated semantic value or throw the appropriate typed/domain error.
+- Compatibility/readiness assessments should return structured blockers for scientifically incomplete-but-well-formed requests instead of converting every blocker into an exception.
+- Malformed schema/numeric input should fail fast with the established typed/domain error.
+- Calculations normally return `CalculationResult<T>`; do not wrap parsers merely to make every function look identical.
+- Immutable snapshots/plans/manifests may use their own versioned record contracts when provenance, identity, or serialization semantics require them.
+- Do not create module-specific aliases for shared concepts such as evidence, uncertainty, coordinate spaces, ranges, or scientific status unless the domain meaning actually differs.
+
+Consistency must never erase a meaningful scientific distinction.
+
+Internal immutable-data mechanics are shared through `src/core/owned-data.ts`.
+Capture, RAW attachment/reconstruction, export metadata and equipment presets use
+its child-first freeze helper only on their owned plain-data trees. Each domain
+keeps its own validation and copy boundary; freezing is not parsing or cloning.
+Already-frozen parents still require descendant traversal in this helper. The
+production planner, focus and release helpers retain their distinct early-return
+behavior for already-frozen objects. This internal module is not a root export.
+
+`src/core/canonical-json.ts` shares sorted-key finite-JSON mechanics while each
+caller supplies its existing omission and error policy. Production-plan records
+omit undefined object properties; capture comparison and export hashing reject
+them. Array order and JSON number/string representation are preserved. Planner
+FNV-1a fingerprints and export SHA-256 hashes remain separate identity contracts;
+the helper neither selects a hash nor changes either contract. Capture's public
+serialization keeps its existing validated JSON.stringify representation.
+
+## Compatibility and deprecation policy
+
+Photivra has independent compatibility surfaces. Update only the surface whose observable contract changed.
+
+### Package version
+
+The npm package version identifies a published distribution. It is not a proxy for every internal/public contract version.
+
+### `ENGINE_API_VERSION`
+
+Bump when the browser-safe root public engine contract changes materially, including a breaking or semantically meaningful exported API change.
+
+### Subsystem/schema versions
+
+Versioned schemas, production-plan contracts, POC contracts, and similar surfaces own their own versions. A change to one does not automatically bump unrelated contracts.
+
+### Before package 1.0
+
+The project may make breaking public changes when the scientific/architectural benefit justifies them, but such a change must:
+
+- be intentional rather than incidental;
+- update the relevant API/schema/contract version;
+- update tests and public documentation;
+- describe migration/compatibility impact;
+- avoid silently reinterpreting previously valid serialized data.
+
+### After package 1.0
+
+Breaking root-package public-contract changes require the normal SemVer major-version process. Independently versioned schema/contract changes still follow their own documented compatibility rules.
+
+### Deprecation
+
+When practical, prefer an additive migration period:
+
+1. introduce the replacement contract;
+2. document the migration;
+3. keep old behavior stable long enough for deliberate downstream migration;
+4. remove only through the appropriate breaking/versioned change.
+
+Do not keep an unsafe or scientifically false API solely to avoid a breaking change. Correctness remains the higher priority, but the break must be explicit.
+
+## Compatibility guard tests
+
+The repository should maintain representative compatibility sentinels rather than freezing every pre-1.0 export forever.
+
+Sentinels should cover:
+
+- root engine and composed POC version surfaces;
+- representative `calculate`, `parse`, composition, and simulation APIs;
+- public function naming conventions;
+- typed error/result semantics where relevant.
+
+Adding a legitimate new API may require extending the naming test. Removing or renaming a sentinel requires explicit compatibility/version review.
+
+## OpenSource V1 API consistency audit
+
+The OpenSource V1 audit treats the existing engine conventions as the baseline rather than redesigning stable APIs.
+
+The root runtime surface currently uses the documented verb families above, with the four result-factory helpers as explicit exceptions. Future OpenSource V1 work should follow these conventions at implementation time.
+
+Audit rule:
+
+- preserve scientifically meaningful existing differences;
+- normalize accidental naming/shape drift when low risk;
+- do not perform broad cosmetic refactors solely for symmetry;
+- record/document any intentional exception;
+- keep private-app conventions from becoming public-engine contracts by accident.
+
+## Stable 1.0 distribution transition
+
+Package 1.0.0 intentionally retains `ENGINE_API_VERSION = "0.116.0"`: this independent root contract identity is already embedded in serialized captures and does not itself signal a published distribution. The package 1.0 policy now governs breaking changes despite that historical root ID. No schema/model/POC/plan version is reset. See [migration and release procedure](RELEASE_1_0.md).

package/docs/ARCHITECTURE.md

@@ -1,5 +1,7 @@
 # Architecture
 
+Release context: **package 1.0.0 candidate / root API 0.116.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_0.md).
+
 Photivra separates a reusable scientific core from optional composition and transport layers.
 
 ## Current root package
@@ -17,7 +19,7 @@ The browser-safe root package currently owns:
 
 The root package has no runtime npm dependencies. CI walks the root import graph and fails if Node-only modules or the `src/api` transport layer become reachable from it.
 
-Comparison, optimization, real-camera calibration databases, renderer effects, and full optical simulation are **not** current root-package capabilities.
+A complete optical renderer, real-camera calibration database and hosted comparison/optimization service are outside the root package. Measured private reuse and explicit generic correction/PSF primitives are implemented within their documented envelopes.
 
 The sensor foundation intentionally keeps physical image-formation geometry separate from digital sampling. `SensorImagingArea` represents the photosensitive imaging dimensions used for image formation; `NativeImageRaster` represents effective image samples and does not imply one image sample equals one physical photodiode. Derived sampling pitch is geometric spacing only, not fill factor or photon-collection area.
 
@@ -45,23 +47,70 @@ Equivalent focal length is also layered on top of physical capture geometry rath
 
 Sensor architecture is a separate descriptive layer. Illumination (FSI/BSI), integration/stacking, readout capabilities, and color-sampling family are independent evidence-backed facts. Their presence alone has no image-quality effect in the engine. Evidence origin is modeled independently from reuse rights, scalar facts may cite multiple evidence records, and multi-valued capabilities carry evidence per value. Omitted facts remain unknown rather than being inferred. Capture-mode semantics, readout timing, reconstruction, and calibrated radiometry consume these facts only through later explicit models.
 
+Exact color-sampling topology is a separate layer again. `SensorColorSamplingProfile` can describe monochrome or an arbitrary periodic mosaic on an abstract native sensor sampling-site lattice, while layered color uses a separate unresolved spatial reference and remains structural-only until per-layer spatial sampling is modeled. This lattice is intentionally not `NativeImageRaster`; the separate evidence-backed binding establishes how capture-mode effective samples relate to color-sampling sites. Active crop/orientation/output transforms therefore cannot reset periodic CFA phase, and architecture-family metadata cannot synthesize an exact tile.
+
+That binding is now explicit through the native-effective-raster/color-site foundation. One evidence-backed profile ties one exact canonical native effective raster to regular sensor-anchored color-site blocks; a second resolver composes that relationship with a selected capture mode. Grouped modes require separately evidenced full-frame grouping phase, use absolute full-frame mode indices, and return compact pre-reconstruction source rectangles plus channel-site counts. Matching dimensions alone never create a binding. Pixel-shift metadata does not re-phase the CFA because the sensor/filter structure moves together; its optical-registration effect remains a later spatial-sampling concern. Declared-effective capture modes and unresolved layered layouts fail closed rather than receiving inferred mappings.
+
+Sensor optical-stack metadata is a separate upstream layer. `SensorOpticalStackProfile` records ordered physical component roles and microlens presence independently from the effective anti-aliasing spatial response. Unknown AA response, documented absence/cancellation, unresolved presence, and an explicit normalized point-splitting kernel remain distinct. The first kernel is native-sensor-physical, field/wavelength/polarization-invariant, and spatial-only; it does not include throughput, spectral filtering, cover-glass refraction, microlens collection, or whole-stack PSF composition. This prevents OLPF presence from becoming a universal Gaussian/four-ray blur and prevents descriptive filter/microlens metadata from silently changing image formation.
+
+Physical sampling aperture is a separate downstream prerequisite for CFA/site sampling. `SensorSamplingApertureProfile` explicitly registers the regular color-site center lattice in native sensor physical coordinates and can declare the first geometric sensitive-region approximation as a uniform rectangle. Site pitch/origin is never derived from `NativeImageRaster`, and aperture dimensions/offset are never inferred from pitch or a scalar fill fraction. The derived geometric sensitive-area fraction is diagnostic only. AA redistribution, microlenses, charge diffusion/crosstalk, spectral response, QE, optical throughput, radiometric collection area, and physical photodiode geometry remain separate models so spatial sampling can later compose them deliberately rather than double-count them.
+
+The spatial-quadrature foundation now performs that first explicit composition of AA redistribution and geometric aperture support. It inverse-samples the pre-AA optical field, keeps the destination CFA channel authoritative, returns both normalized-average and geometric-area measures, and preserves off-imaging-area optical support without clamping. It still evaluates no optical/radiometric values and remains separate from temporal quadrature, microlens response, diffusion/crosstalk, RAW generation, and reconstruction.
+
+The spatial-sample reducer now evaluates those quadrature weights against explicitly supplied nonnegative linear values. It supports either a dimensionless relative irradiance proxy or physical sensor-plane irradiance in W/m², matches values by node identity rather than position, and preserves both average and area-integral semantics. CFA channel labeling remains metadata until a later spectral response model; temporal exposure, photons/electrons, noise, ADC and RAW/reconstruction remain downstream.
+
+The spectral-response foundation now supplies that next channel-specific metadata layer. It binds exact topology channel IDs to reusable wavelength-dependent effective EQE, A/W responsivity, or explicitly separable channel-filter×detector-EQE data. Wavelength basis/range/interpolation and response scope remain explicit, direct effective response is not decomposed without evidence, and condition-dependent response remains unmodeled. Separate spectral/EQE/temporal APIs perform explicit integration without widening this profile resolver.
+
+The spectral-quadrature foundation now plans the next wavelength dimension without performing signal integration. It partitions an explicitly requested response-supported interval at sensor-response knots plus optional caller-supplied continuous-spectrum/optics breakpoints, then uses bounded equal-width midpoint subintervals with dλ expressed in nanometres. The result preserves response kind, scope, uncertainty and evidence but does not apply response values, establish common scene/optics/sensor spectral coverage, or calculate photons, electrons, current or RAW values. QE and A/W therefore remain separate downstream signal paths, response scope must later match the source plane, and discrete line spectra remain outside the continuous-density quadrature contract.
+
+The spatio-spectral reducer now composes the spatial and wavelength measures against explicitly supplied E_lambda(x,y) in W/m²/nm. Spatial plans carry their exact colorSamplingProfileId so composition can require profile identity rather than channel-name coincidence. The reducer validates the full spatial × spectral Cartesian product, caps it independently, reports per-wavelength spatial averages and geometric-aperture spectral flux density, and integrates those pre-response quantities over dλ. It still applies no QE, A/W responsivity, channel-filter transmission, temporal exposure, effective collection-area correction, photon/electron conversion or RAW processing.
+
+The response-application compatibility gate binds the response profile/channel to the exact sampling-aperture and optical-stack identities used by the spatial plan, matches response scope to an evidence-backed source reference plane, distinguishes geometric-sensitive-aperture from full-site/effective-collection-area normalization, requires explicit spatial response uniformity/separability before allowing post-spatial response, and handles response reference conditions without treating omitted dependence as invariance.
+
+The response operating-range gate follows that structural assessment. It preserves whether linearity was characterized in incident radiant power or irradiance, requires the current wavelength basis/range and operating conditions to remain inside the declared calibration applicability, records the allowed relative nonlinearity criterion, and distinguishes broadband-only evidence from per-spectral-bin applicability with an explicit maximum bin width. Wavelength-dependent conversion requires per-bin validity and spatial linear superposition; broadband total power alone cannot authorize it. Exposure/full-well saturation, accumulated-charge linearity and downstream electronics linearity remain separate because they depend on temporal integration and later signal stages.
+
+The photon-energy wavelength foundation supplies the unit bridge for photon-domain response. Vacuum wavelengths use exact SI h and c directly. Air wavelengths require an exact-wavelength sourced phase refractive index to obtain vacuum wavelength, plus explicit atmosphere compatibility because refractive index varies with conditions. Refractive-index uncertainty is preserved as input metadata but is not yet propagated into photon-energy uncertainty.
+
+The EQE electron-rate foundation performs the photon-domain response conversion. It requires the structural and operating-range gates, including explicit geometric-aperture linear superposition and per-spectral-bin input validity; binds the operating-range bin identities/values back to the exact reduction; requires an exact canonical response-channel data binding so changed numeric calibration samples cannot hide behind the same IDs/evidence; evaluates response per wavelength node; converts each spectral power contribution to photon rate through hν; and applies direct or explicitly separable effective EQE to produce expected electron rate. Wavelength contributions use compensated summation.
+
+The sibling A/W foundation remains a separate current-domain path. It applies spectral responsivity per wavelength bin directly to radiant-power contributions and returns detector-terminal photocurrent magnitude. It uses the same exact canonical response-channel binding so A/W sample drift cannot be substituted under unchanged provenance. A separate electrical applicability profile binds detector bias and current-readout load semantics to the calibration. It deliberately does not infer electron rate or circuit polarity, and it stops before transimpedance gain, voltage, temporal charge, saturation/noise, ADC or RAW processing.
+
+Both response paths therefore converge only at a later temporal/electrical composition boundary; neither is allowed to reinterpret the other's signal domain.
+
+The local exposure-binding foundation begins that temporal boundary without integrating signal. Engine-produced rate results preserve their color-site identity. The binding validates the site/channel, resolves the existing color-site/native-effective-raster relationship, and recomputes the shutter window at the mapped native sample center. The first binding accepts only one-to-one site/sample registration; grouped multi-site blocks do not prove sub-sample timing coordinates.
+
+The constant-rate temporal-integration foundation then requires an evidence-backed stationarity declaration tied to that exact rate domain, site, binding ID and local start/end window. Only then may rate × duration be evaluated. EQE produces expected photon/electron counts without stochastic sampling; A/W produces photocurrent charge magnitude without carrier-count inference.
+
+The dark-current foundation begins charge completion for the EQE path only. It integrates evidence-backed pre-compensation thermal electron rate over the exact local exposure and keeps temperature applicability explicit. Exact-reference values and measured piecewise-linear temperature tables are supported; no universal exponential temperature law is inferred. Population-mean dark current remains an approximation and does not imply DCNU/hot-pixel modeling. A/W photocharge remains outside electron-storage/full-well semantics until a separate carrier/storage mapping exists.
+
+The accumulated-charge foundation then rebinds photo signal, dark charge, and every explicitly incremental additional stored-electron contributor to one exact local exposure event. A separate evidence-backed completeness profile must enumerate the supplied additional-component IDs and assert that all material stored-electron contributors are accounted for.
+
+The physical charge-capacity foundation compares that complete **expected** stored-electron total to an evidence-backed storage-capacity profile tied to site, operating state and temperature applicability. It reports ratio/headroom and whether the unsaturated expected charge lies below, at or above capacity. It does not clamp charge, calculate nonlinear post-saturation storage, infer blooming/neighbor transfer, or claim the stochastic saturation state is known.
+
+The camera saturation-capacity foundation separately compares dark-corrected photo-generated electron-equivalent signal against an evidence-backed camera response-chain saturation capacity. It deliberately does not use total stored charge or physical full-well capacity. The capacity may reflect an earlier analog/digital limit, but the first contract does not infer the limiting stage, ADC code, or post-saturation transfer behavior.
+
+Physical storage capacity and camera saturation are therefore parallel assessments in different calibrated domains, not one shared clamp.
+
 
 ## Image-formation ownership and ordering
 
 The root package exports `getImageFormationContract()` as the canonical semantic map for current and future image-formation work.
 
-It defines five scientific domains:
+It defines six scientific domains:
 
 1. scene/ray geometry;
-2. lens mapping plus pupil/throughput;
-3. field- and wavelength-dependent PSF;
-4. time-dependent exposure/readout;
-5. sensor sampling through orientation/output/display.
+2. scene-radiance formation;
+3. lens mapping plus pupil/throughput;
+4. field- and wavelength-dependent PSF;
+5. time-dependent exposure/readout;
+6. sensor sampling through orientation/output/display.
 
 The graph is a **dependency/ownership graph**, not a literal renderer filter list. Hard upstream dependencies are acyclic; explicit couplings record interactions that must not be split into scientifically independent post-effects.
 
 Important consequences:
 
+- illumination-source metadata is upstream input to scene-radiance formation, not a sensor shortcut or post-render RGB overlay;
+- outgoing scene spectral radiance is distinct from `SceneRadiometry` luminance anchors, source spectra, and sensor-plane irradiance;
 - focus breathing is projection/lens mapping;
 - lateral CA is wavelength/channel-dependent field mapping;
 - illumination vignetting is throughput-only;
@@ -69,12 +118,40 @@ Important consequences:
 - diffraction belongs to the pupil/PSF domain;
 - camera rotation should be time-parameterized so global and rolling readout consume one motion model;
 - exposure duration and readout timing remain independent;
-- future sensor ordering is reserved from optical stack/CFA sampling through charge/noise/ADC/reconstruction before oriented/output transforms.
+- sensor ordering runs from optical stack/CFA sampling through charge/noise/ADC/reconstruction before oriented/output transforms; plan 0.7.0 executes this bounded declared environment route, while unsupported effects still block.
 
 Renderer implementations may optimize or approximate only when they preserve the engine-owned semantics. Geometric warps use inverse destination-to-source sampling, premultiplied alpha, and stable depth/occlusion order.
 
 See `docs/IMAGE_FORMATION.md`.
 
+The standalone `parseSceneIlluminationProfile()` foundation now provides stable renderer-independent point/spot/area/directional/environment source identities, scene-object binding, source-specific magnitude semantics, continuous-spectrum provenance, and explicit approximation boundaries. It intentionally stops before material/visibility/transport evaluation, so the `scene-radiance-evaluation` stage remains only partially founded. See `docs/SCENE_RADIANCE_AND_ILLUMINATION.md`.
+
+The additive scene-radiance provider boundary now defines material-response metadata, provider fidelity, exact surface/environment evaluation requests, and validated outgoing spectral-radiance results. The engine validates identities, units, provenance, wavelength/time/direction semantics and declared fidelity, but does not implement the renderer or recompute the provider's transport result. Provider/result schema 0.1.0 is approximation-only even when calibrated spectral material inputs are present; it therefore cannot satisfy a calibrated scene-radiance claim by itself. RGB/PBR material inputs remain explicit approximation data, while wavelength-changing material behavior, emission, volumetrics and polarization remain unmodeled.
+
+The shared spectral-composition foundation now separates two mathematical domains. Continuous spectral factors declare a resolved air/vacuum basis, finite wavelength support and interpolation breakpoints; composition intersects support and unions breakpoints without applying values. Delta-like discrete lines instead carry normalized wavelength-integrated line weights and are integrated by summing line contributions with no dλ multiplier. A sensor-response adapter exposes existing response support/knots to the shared continuous plan, and the illumination layer exposes continuous source support or discrete-line source measures without broadening one representation into the other.
+
+The temporal illumination foundation overlays time-varying relative source modulation on the existing static illumination profile without changing that base schema. Waveforms are aperiodic or periodic piecewise-linear multiplier data with evidence and uncertainty. Each time-varying source requires an explicit registration mapping waveform-local t=0 onto the existing capture reference `first-opening-boundary-phase`. Evaluation and local-exposure integration consume physical seconds from that reference; sensor data-readout timing remains independent. The temporal layer never chooses shutter/aperture/ISO, so downstream metering/automatic-exposure consumers can observe changed pre-exposure light without creating a display-brightness feedback loop.
+
+The first exposure-metering foundation consumes an explicitly relative **pre-exposure linear signal** sample set over the physically oriented active capture frame. It is approximation-only and does not reinterpret those samples as calibrated luminance, spectral radiance or sensor-plane irradiance. Generic multi-zone, center-weighted, spot and highlight-weighted profiles state their weighting policy directly; the declared relative target is profile policy rather than a universal gray-card truth. The meter returns a stable measurement/scene-state identity plus the stop offset required to reach that target, while final output crop, tone mapping/display gamma, exposure compensation and automatic aperture/shutter/ISO resolution remain separate. #99 should consume this typed result rather than renderer-specific buffers.
+
+The additive #85→#100 bridge validates that a relative meter sample set is bound to one scene-radiance provider, illumination profile, material-response profile and derivation profile. The scalar reduction remains explicitly renderer/provider supplied because spectral scene radiance cannot be collapsed into a camera exposure-meter scalar without a declared spectral/color weighting model. Schema 0.1.0 therefore labels the reduction uncalibrated/approximate instead of inventing photopic or camera-specific weighting. If the provider binds temporal illumination, each sample set also requires a finite capture time on the shared `first-opening-boundary-phase` reference. A separate temporal-metering function may combine multiple such measurements only under an explicit positive normalized weighted-time-average policy; it averages the linear meter signal first and derives the stop offset afterward. Mixed scene-state/provider/geometry contexts fail closed.
+
+#110 now provides the first physical primary-optics bridge from one validated #85 outgoing spectral-radiance sample to pre-sensor-stack spectral irradiance. `calculateSceneRadianceToSensorIrradiance()` preserves request/result time and wavelength identity, applies a paraxial circular-pupil acceptance term using an explicit working f-number, then applies exactly one transmission path and at most one field-throughput result. Wavelength-resolved transmission and effective working T-stop are mutually exclusive so transmission loss cannot be double-counted. Finite-focus handling is explicit: infinity focus uses nominal f-number; the ideal symmetric thin-lens approximation may use `N_working = N(1+m)` only with unity pupil-magnification declared; real/generic profiles may instead supply an evidence-backed working f-number. The bridge deliberately adds no universal cos^4 falloff, distortion/Jacobian brightness correction, PSF energy redistribution, sensor optical-stack/microlens/CFA/QE response, or stray-light contribution. Its output is wavelength-resolved sensor-plane incident irradiance in W/m²/nm for #14/downstream consumers.
+
+The meter-target seam then freezes a spatial or temporal metering result into a stable value object for #99. The frozen snapshot preserves measurement ID, scene-state ID and metering-profile ID so AE lock can intentionally keep one target while later scene states change. Exposure compensation is a separate absolute-stop transform over that frozen base target; it never rewrites the source meter measurement, and a changed compensation state receives a new target ID. Positive compensation requests more exposure. No-signal remains unresolved rather than becoming infinity. Aperture/shutter/ISO selection still belongs entirely to #99.
+
+The first #109 equipment-capability slice introduces separate generic Photivra body and lens exposure profiles rather than extending the legacy selected-state `CameraConfiguration`. Body profiles own shutter-duration and ISO capability ranges/grids plus Auto ISO availability; lens profiles own focal-length capability and aperture capability, including focal-length-dependent widest available f-number. `resolveGenericEquipmentExposureCapabilities()` combines them at one selected focal length and returns an immutable exposure envelope for #99. It does not select aperture/shutter/ISO, model ISO noise/gain topology, infer shutter mechanism/readout, or claim named commercial equipment emulation. Generic product profile identity/version is the normal applicability seam.
+
+The first #99 resolver slice consumes that capability envelope plus the frozen #100 meter target. In Manual mode, aperture and shutter are always manual axes. ISO is either manual-preserved or automatic. Because the relative meter target does not define an absolute ISO by itself, the resolver requires an explicit reference exposure anchor `(aperture, shutter, ISO)`; the target scale and current manual optical exposure are measured relative to that anchor. Auto ISO then resolves only ISO, applies the declared equipment range/grid, and reports signed residual stops plus the limiting constraint. Manual ISO never changes when compensation changes; only its meter residual diagnostic changes. ISO control remains a nominal exposure-index/gain-control decision and does not infer sensor noise, conversion gain, photons, or analog topology.
+
+The second #99 resolver slice adds Aperture Priority with manual ISO without introducing a new exposure equation. Aperture and ISO are validated manual axes; shutter is the only automatic axis. Ideal shutter duration is solved from the same relative target/reference anchor used by Manual + Auto ISO, then constrained by the #109 shutter envelope. Continuous grids preserve the ideal duration; discrete grids quantize in log2 duration space with a shorter-duration tie break. Shutter limits and grid quantization report signed residual stops. Exposure compensation remains already embedded in the typed target and is never reapplied by the resolver.
+
+The larger #99 priority-policy layer adds the remaining A/S priority combinations needed before Program/Full Auto. Multi-axis automatic behavior is declared policy: A+Auto ISO uses minimum selectable ISO until a named slowest-preferred shutter threshold, then ISO, with an explicit after-ISO-max fallback; S+Auto ISO uses aperture-first selection at minimum ISO, choosing a discrete aperture no wider than the ideal so ISO can fill the remaining exposure. S+manual ISO resolves only aperture. These choices are generic educational/product policies, not physical laws or claims about a named camera. All modes still resolve to the same aperture/shutter/ISO physical variables and reuse common target/reference/capability math.
+
+The next #99 layer introduces versioned generic exposure program lines for Program Auto and Full Auto exposure. A line is a sequence of control-policy nodes `(optical stops from reference, aperture, shutter)`; each node must be consistent with the explicit reference exposure and current #109 capability envelope. Between nodes, aperture and shutter interpolate in log2 space so optical exposure stops interpolate linearly before equipment quantization. Program Auto may keep ISO manual or use Auto ISO to absorb line-endpoint/quantization residuals. Full Auto exposure uses the same line with Auto ISO but remains exposure-only: AF, WB, flash, drive, scene recognition, and stabilization are explicitly unresolved. Program lines are product policy approximations, not scientific laws or claims of commercial-camera emulation.
+
+The final #99 control seam treats fixed-duration, Bulb, and Time as duration-control behavior only. `resolveExposureDurationControl()` returns either an active unfinished control or a concrete positive elapsed duration. Only a resolved result may be bound into the authoritative #12 `CalculateCaptureExposureWindowsInput`; the adapter replaces only `nominalExposureDurationSeconds` and leaves shutter mechanism/opening/closing schedules untouched. No universal 30 s limit is introduced. Once seconds are resolved, long exposure follows the same local exposure-window, temporal integration, motion, charge, dark-current, and saturation pathways as any other duration. Bulb/Time do not imply mechanical shutter, tripod support, stabilization state, long-exposure NR, or sensor-temperature behavior.
+
 ## Radiometry readiness boundary
 
 Radiometry prerequisites are represented separately from the composed POC and from low-level signal/noise primitives. `parseRadiometryReadinessProfile()` validates declared scene spectral radiance, optical transmission, pupil/vignetting behavior, photosite collection-area semantics, exposure integration, and sensor response together with evidence and uncertainty declarations.
@@ -118,6 +195,11 @@ Compatibility boundaries remain explicit:
 The POC still does **not** consume:
 
 - `SensorArchitectureProfile`;
+- `SensorColorSamplingProfile`;
+- `NativeEffectiveRasterColorSamplingBindingProfile`;
+- `SensorOpticalStackProfile`;
+- `SensorSamplingApertureProfile`;
+- `CaptureModeProfile`;
 - `RadiometryReadinessProfile` or calibrated photon/noise output.
 
 That separation is deliberate. Further foundation APIs should remain independently testable and only enter the POC through explicit contract/version changes and migration review.
@@ -192,6 +274,63 @@ It is intentionally **not** composed into `simulatePocCamera()` yet. The existin
 
 The new primitive provides deterministic yaw/pitch/roll rotation geometry only. It does not model camera translation, stabilization control laws, rolling-readout scheduling, or scene-depth-dependent parallax.
 
+## Production image-formation composition
+
+The production composition contract is additive and separate from `simulatePocCamera()`.
+
+`prepareImageFormationContext()` owns relatively static validated context:
+
+- resolved equipment capability identity;
+- scene/provider identity;
+- #110 optical-throughput profile;
+- output-geometry profile identity;
+- renderer capability declaration;
+- fidelity requirements.
+
+`createProductionCaptureSnapshot()` commits per-capture state:
+
+- capture/release-frame/scene-state identity;
+- scene time;
+- aperture/shutter/ISO;
+- deterministic capture seed;
+- optional #85 scene-radiance + #110 field/focus input.
+
+Prepared context and capture snapshots are copied, deeply frozen and fingerprinted. Later UI mutation cannot alter a committed plan.
+
+`createProductionImageFormationPlan()` expands required dependencies from `getImageFormationContract()`; it does not maintain a second hidden stage order. Every contract stage/effect remains visible in the plan as active, modeled-zero, omitted by fidelity, unsupported, or blocked.
+
+The initial composer intentionally integrates only a conservative subset:
+
+The next production-composition slice adds temporal capture semantics without inventing a new timing model. The immutable capture snapshot may now carry:
+
+- authoritative #12 exposure-window input;
+- invariant native sensor readout declaration;
+- physical imaging area/orientation;
+- optional pure-camera-rotation velocity and deterministic temporal sample count.
+
+The plan evaluates local exposure windows and sensor readout separately. It does **not** assume those clocks are synchronized. When rotation is supplied, it delegates temporal geometry to the existing pure-rotation midpoint quadrature and preserves the committed temporal sample count.
+
+This does not weaken the image-formation dependency graph. `temporal-exposure-readout` still depends on `field-wavelength-psf`; until PSF is intentionally production-composed, a fidelity profile requiring the full temporal stage can carry useful timing/rotation results while the overall plan remains blocked on that upstream stage.
+
+A separate consumer-manifest API projects the same finalized semantic plan into either `interactive-optimized` or `reference` execution roles. Consumer role does not permit changing scientific inputs, stage order, capture seed, or committed temporal sample count.
+
+
+```text
+scene-ray-projection semantic binding
+  -> #85 scene-radiance result
+  -> #110 lens/pupil/throughput evaluation
+```
+
+Requesting later stages such as PSF, sensor optical stack, CFA/charge/ADC/reconstruction produces structured `engine-stage-not-composed` blockers until those standalone foundations are deliberately integrated.
+
+Renderer declarations are semantic capability metadata only; the plan accepts no React/Three.js/WebGPU objects. Optimized and reference renderers consume the same stage/effect semantics and must declare spectral, depth, warp, alpha and sensor-domain capabilities.
+
+Plan fingerprints use canonical serialization plus FNV-1a 32-bit only as deterministic reproducibility keys. They are not security/integrity hashes.
+
+The capture seed is explicit and backend randomness may not redefine the scientific result. Future stochastic stages must derive deterministic sub-seeds through an engine-owned policy.
+
+See [Production Image-Formation Plan](PRODUCTION_COMPOSITION.md).
+
 ## Repository-local Node POC transport
 
 The repository contains a minimal Node-only HTTP transport under `src/api` for contributor integration testing.
@@ -200,23 +339,11 @@ It wraps `simulatePocCamera()` with an unauthenticated localhost server. The HTT
 
 This transport is intentionally **not** part of the public `@photivra/engine` package surface and is excluded from the npm tarball. The POC server is not the intended production architecture.
 
-## Optional/future capability modules
-
-Future capabilities should compose onto the scientific core rather than silently widening unrelated models. Examples include:
+## Boundaries beyond the 1.0 route
 
-- composed use of the standalone spatial camera-rotation model plus future depth-aware camera translation;
-- panning and rolling/global shutter;
-- flash;
-- spectral/color modeling;
-- macro/high-magnification calibration;
-- non-circular diffraction PSFs;
-- computational capture;
-- lens calibration profiles;
-- advanced/calibrated sensor profiles;
-- comparison and optimization systems;
-- renderer-specific effects.
+The root package already has direct extended-object motion, depth-aware translation/parallax quadrature, manual flash/sync, generic stabilization, spectral response/color and polygon/complex-pupil PSF primitives. Their existence does not make every combination available to the production composer.
 
-Capabilities should remain discoverable and explicitly versioned rather than being assumed present for every scene or runtime.
+The bounded production environment route uses declared environment radiance, ideal projection, constant-axis rotation, explicit spatial/spectral/temporal EQE and seeded native RAW with optional output. General surface intersection/visibility, world translation, calibrated commercial profiles, computational multi-frame image combination, full field-dependent PSF transport and megapixel execution remain outside that route. See [production envelope](PRODUCTION_ENVIRONMENT_CAPTURE.md) and [composition map](V1_COMPOSITION_MAP.md).
 
 ## Repository scope
 
@@ -226,4 +353,4 @@ The published npm package intentionally exposes only the browser-safe scientific
 
 ## Version surfaces
 
-The root library contract and the composed POC simulation contract are versioned independently. `ENGINE_API_VERSION` describes the root browser-safe engine surface. `POC_SIMULATION_API_VERSION` describes the request/response behavior of `simulatePocCamera()` and the repository-local POC HTTP transport. Package versioning remains separate from both.
+The root library, semantic image-formation graph, production composition plan, and composed POC simulation are versioned independently. `ENGINE_API_VERSION` describes the root browser-safe engine surface; `IMAGE_FORMATION_CONTRACT_VERSION` describes ownership/order semantics; `PRODUCTION_IMAGE_FORMATION_PLAN_VERSION` describes the production composition result contract; and `POC_SIMULATION_API_VERSION` describes `simulatePocCamera()` plus the repository-local POC HTTP transport. Prepared-context, capture-snapshot, renderer-capability, and fidelity-profile schemas also retain their own versions. Package versioning remains separate from all of them.

package/docs/AUTOMATION_COORDINATION.md

@@ -0,0 +1,190 @@
+# Public-engine automation coordination
+
+Release context: **package 1.0.0 candidate / root API 0.116.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_0.md).
+
+This document coordinates the two recurring automation lanes that work only in the public
+`Photivra/photivra` repository. It is process guidance, not a scientific roadmap. Open issues and
+the repository's scientific/API documentation remain authoritative for product and model semantics.
+
+## Lanes
+
+- **Engine Science** (`engine-science`) owns scientific/foundational roadmap work.
+- **Export & Performance** (`export-performance`) owns `SimulatedCapture`, TIFF/DNG export,
+  measured performance work, and CI-efficiency work.
+
+Each roadmap issue should contain a short **Automation coordination** block identifying its owner
+lane, dependencies, and cross-lane handoff. That block coordinates work; it does not override the
+issue's scientific acceptance criteria.
+
+## Control plane
+
+Automation coordination state lives on the repository's dedicated `automation-state` branch:
+
+- `coordination/registry.v1.json`
+- `coordination/registry.schema.json`
+
+The control branch belongs to this public repository. No private repository or other project is a
+coordination dependency.
+
+Before any automation-owned project write:
+
+1. Read current `main`, open PRs, recent merges, the target issue, and applicable `AGENTS.md` /
+   scientific/API documentation.
+2. Read the registry from `automation-state` together with its exact blob SHA.
+3. Acquire the lane mutex and every shared resource required for the intended mutation in one
+   SHA-guarded registry update.
+4. If the registry changed, re-read and retry the compare-and-swap at most three times.
+5. Never steal an unexpired lease. A lease may be reclaimed only after its `expiresAt` is at
+   least two minutes in the past.
+6. Use a lease duration no longer than 55 minutes. If work cannot safely finish inside that
+   window, stop at a clean boundary and continue on the next scheduled run rather than holding a
+   resource indefinitely.
+7. Release every registry entry carrying the exact `leaseId` when the task is merged, abandoned,
+   or safely stopped.
+
+If the registry cannot be read or validated, automation may inspect and plan but must not mutate
+the repository.
+
+## Resource names
+
+Every mutating run acquires exactly one lane mutex:
+
+- `lane:engine-science`
+- `lane:export-performance`
+
+Acquire additional shared resources only when the change touches them:
+
+- `shared:ci` — `.github/workflows/**`, CI policy/scripts, or test-runner configuration.
+- `shared:package` — root `package.json`, `package-lock.json`, package exports, or dependency
+  changes.
+- `shared:api-version` — `ENGINE_API_VERSION`, `POC_SIMULATION_API_VERSION`, or public schema
+  version surfaces.
+- `shared:changelog` — `CHANGELOG.md` when both lanes could plausibly update it.
+- `issue:<number>` — when mutating issue state/body/comments as part of active implementation.
+- `path:<repository-path>` — for another high-collision file not covered by a shared resource.
+
+Do not acquire broad resources speculatively. The registry is intended to prevent collisions, not
+serialize unrelated science and export work.
+
+## Branch and PR ownership
+
+Use focused branches:
+
+- Engine Science: `science/*`, `sensor/*`, `motion/*`, `optics/*`, or another clearly
+  science-owned prefix.
+- Export & Performance: `export/*`, `dng/*`, `perf/*`, or `ci/*`.
+
+Normally each lane has at most one active behavioral PR. Before creating new work, inspect existing
+open PRs and reuse an automation-owned branch/PR when it represents the same task.
+
+Never modify another lane's active branch. A dependent lane consumes prerequisite work only after it
+is merged to `main`, unless the project owner explicitly approves another integration path.
+
+After every merge, rescan open PRs and the relevant dependency issues before selecting the next task.
+
+## Cross-lane handoff
+
+When one lane lands a prerequisite for the other:
+
+1. Merge the prerequisite independently with its own tests and contract documentation.
+2. Record the exact merged commit and public API/contract surface on the dependent issue when a
+   handoff note materially helps.
+3. The dependent lane starts from current `main`; it does not continue on the prerequisite
+   lane's branch.
+4. If a downstream task exposes a missing scientific contract, Export & Performance records the
+   dependency and moves to independent work instead of implementing science locally.
+5. If Engine Science needs a benchmark/CI change, it records the requirement and lets Export &
+   Performance own the shared implementation unless the change is inseparable from the science
+   patch.
+
+## DCO and automated commits
+
+The repository requires Developer Certificate of Origin sign-off for commits intended for
+inclusion.
+
+Automation must fail closed rather than invent a contributor identity. When operating through the
+repository owner's authenticated GitHub connection under explicit owner authorization, use the
+owner's established DCO identity from existing signed-off commits. Otherwise, do not create a
+merge-intended commit until an authorized sign-off identity/path is available.
+
+Every automation-created merge-intended commit must contain a valid `Signed-off-by:` trailer.
+
+## Merge discipline
+
+Automation-owned non-breaking PRs may be merged only when:
+
+- the exact final head is current and mergeable;
+- required checks for that head are green;
+- no expected check is missing or silently skipped;
+- the complete final diff is reviewed;
+- the lane still owns every required lease;
+- issue dependencies are satisfied;
+- DCO sign-off is present;
+- scientific, provenance/licensing, security, browser/package-boundary, compatibility, and release
+  gates remain satisfied.
+
+Intentional breaking public API/schema changes, releases/publication, new paid services, ambiguous
+provenance/legal decisions, or other owner-gated actions still require explicit human approval.
+
+## Productive-run contract
+
+A scheduled implementation run is successful only when it produces at least one concrete delivery
+outcome:
+
+1. a safe roadmap PR is merged;
+2. an active roadmap PR contains substantive implementation/documentation changes and exact-head CI
+   is running or has produced actionable results;
+3. a roadmap issue is closed or materially narrowed with repository evidence because current
+   `main` already satisfies part or all of its acceptance criteria; or
+4. a specific blocker that truly requires external/human action is recorded with the exact missing
+   prerequisite and the lane immediately moves to another independent ready issue when one exists.
+
+A general audit, plan, status recap, repeated inspection, or rediscovery of an already-known blocker
+does **not** count as a productive outcome while actionable work exists.
+
+Before starting implementation, read the issue's latest **Roadmap reconciliation** section when
+present. Do not redo capabilities already verified on `main`. If reconciliation evidence shows the
+issue is already complete, close it with evidence and continue to the next ready issue in the same
+run when practical.
+
+## Stalled-progress rule
+
+A lane must not spend repeated scheduled runs on the same non-productive state.
+
+If two consecutive expected lane runs have produced none of the productive outcomes above:
+
+1. rescan current `main`, open PRs, recent merges, reconciliation state, dependencies, and leases;
+2. stop repeating the same audit or retry path;
+3. choose the next independent ready issue owned by the lane; or
+4. if no owned issue is actionable, record the precise blocker/dependency and surface it through the
+   health process.
+
+An ordinary CI failure, owned merge conflict, stale automation branch, test regression, or expired
+lease is an implementation problem to resolve, not by itself a reason to declare the lane blocked.
+Only owner-gated decisions, unavailable external prerequisites, unresolved legal/provenance
+questions, release gates, or another genuinely external dependency qualify as persistent blockers
+after safe remediation paths are exhausted.
+
+The health watch should treat an enabled/on-cadence lane with two consecutive scheduled windows and
+no concrete delivery outcome as potentially stalled when a reconciled ready issue exists. It should
+identify the lane and ready issue rather than disabling the lane.
+
+## Roadmap reconciliation discipline
+
+Open issues are the roadmap, but issue state must reflect current `main`.
+
+- Periodically reconcile issue acceptance criteria against merged implementation and tests.
+- Close an issue when all of its open-source acceptance criteria are demonstrably satisfied.
+- For partially completed issues, record the landed capability and the exact remaining scope in the
+  issue itself so future runs do not recreate completed work.
+- Unmerged historical branches are evidence to inspect, not authoritative project state.
+- A private/product requirement outside the current open-source scope does not keep an otherwise
+  completed public-engine issue open.
+- After reconciliation or a merge, select work from the remaining dependency graph rather than issue
+  age.
+
+## Avoiding coordination drift
+
+Do not duplicate scientific requirements or rewrite roadmap acceptance criteria in this document or
+the registry. If issue ownership/dependencies change, update the issue's coordination block and the
+automation prompt together. The issue remains authoritative for the work itself.