@photivra/engine 0.6.0 → 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,7 +47,7 @@ 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`; a future binding must establish 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.
+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.
 
@@ -57,23 +59,58 @@ The spatial-quadrature foundation now performs that first explicit composition o
 
 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;
@@ -81,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.
@@ -209,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.
@@ -217,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
 
@@ -243,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

@@ -1,5 +1,7 @@
 # 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.

package/docs/CAPTURE_COLOR.md

@@ -0,0 +1,25 @@
+# Virtual-camera linear color: #15B
+
+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).
+
+`resolveCaptureColorModel()` defines an ideal CIE 1931 2-degree colorimetric camera: co-sited red/green/blue channels are an invertible encoding of XYZ in the linear-sRGB primary basis, with D65 reference white. They are relative linear values, not electrons, spectral response measurements or commercial-camera RGB. Choosing this profile is an upstream producer assertion about sample meaning; naming arbitrary sensor data with its ID does not establish validity.
+
+The primary chromaticities are red (0.64,0.33), green (0.30,0.60), blue (0.15,0.06), and D65 (0.3127,0.3290). Matrices are independently derived: form each primary column `(x/y,1,(1-x-y)/y)`, solve its scale against normalized D65 XYZ, scale columns, then invert the resulting 3x3 matrix. Model `0.1.0` exposes both row-major matrices, observer, reference illuminant/white, evidence identity and valid conditions. No transfer curve, gamut mapping or nominal [0,1] clamp is applied. Mathematical conversion is calculated, not calibrated.
+
+`calculateCaptureColorTransform()` consumes a validated `SimulatedCapture` and one untreated inline XYZ or exact `photivra-colorimetric-rgb-d65` virtual-camera plane. It returns a new immutable transformed RGB plane, model data, source plane/state IDs and the selected WB policy. It leaves the capture/exposure/focus/noise/source manifest unchanged. Consumers use the same API for preview/export; no renderer or file-format dependence is introduced.
+
+| Explicit policy | Meaning |
+| --- | --- |
+| preserve-intent | Convert the color basis only; retain resolved WB as intent without applying it. XYZ reference white must match the documented D65 convention exactly. |
+| apply-resolved-rgb-gains | Convert XYZ to the camera RGB basis, then multiply the resolved #108 red/green/blue gains. Caller must bind gains to the exact camera profile/version. No AWB estimator or implicit adopted-white adaptation runs. |
+| adopted-white-xyz-scaling | In XYZ, multiply X and Z by target-D65/adopted-white ratios, leave Y unchanged, then convert to linear RGB. Requires explicit adopted white; consumes no RGB gains. Reports approximation provenance. |
+
+XYZ diagonal scaling is intentionally a limited adaptation approximation, not Bradford, a physiological cone model or a full color-appearance model. It maps the chosen normalized adopted white to D65 while preserving its Y; this invariant does not prove perceptual accuracy for other colors. Ratios must lie in [1e-6,1e6] for the supported numerical domain; no validated physical accuracy envelope is claimed. Under mixed illumination, the selected adopted white remains a camera/photographer choice. The result always states `claimsUniqueSceneWhite:false`. Encoding white and adopted white are separate records; RGB gains do not derive/update the adopted white.
+
+Signed samples, above-white headroom and the source reference-value normalization are retained; non-finite arithmetic fails with the scientific-result error. Source saturation is retained as **upstream capture history in the original source-channel domain**, not an output clipping threshold or transformed RGB white level. The result performs no clipping and creates no new saturation count. Existing digital-lens-correction history is retained; color/adaptation/gain history rejects a second color invocation. Missing/wrong profile versions, unsupported spectral channel identities, transformed input, external storage, reused output IDs and malformed policies fail closed. External data must be independently loaded/verified before a future streaming color executor; this API does no IO.
+
+To commit the returned plane into a new container, carry the original source manifest and capture settings, add the returned model/evidence to `models` as appropriate, and include the derived plane. `createSimulatedCapture()` revalidates the aggregate inline budget; callers decide whether to retain both master and derived planes. A transform result does not assert an external artifact checksum for newly generated bytes. Schema `0.2.0` explicitly records applied-chromatic-adaptation; `0.1.0` archives migrate without inventing adaptation.
+
+The fixed ideal basis has no illumination-dependent sensor calibration. Future measured/spectral sensor models need their own versioned channel→XYZ profiles with explicit reference illumination/validity and approximation/calibration evidence; this implementation rejects them instead of inventing a universal matrix or interpolating undocumented illuminants. #15C owns quantization, #112 tone/look/gamut/transfer/display, #16 file mapping and #111 production ordering. No stage is activated here.
+
+Factual research: [W3C CSS Color 4 linear sRGB definition](https://www.w3.org/TR/css-color-4/#predefined-sRGB) documents primary/white chromaticities and distinguishes linear-light values from the transfer-encoded space. Only these public numerical facts and color-space distinctions are used; source code, published conversion matrices, protected prose and calibration/color tables were not incorporated. Reference coefficient tests check independently stated numerical values to absolute tolerance about 5e-14; invariants check primary chromaticities, black and D65 white. AI-assisted draft remains subject to substantive human science/provenance review and DCO certification.

package/docs/CAPTURE_CORRECTED_SDR.md

@@ -0,0 +1,25 @@
+# Capture-bound corrections and SDR: #112 integration slice
+
+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).
+
+`calculateCaptureCorrectedSdr()` consumes the same immutable `SimulatedCapture` and explicit source/color/WB choice as `calculateCaptureSdr()`, then executes existing #117/#118 corrections before the existing SDR renderer. This bounded reference bridge does not replace the #111 composer, activate production stages, or complete #112/V1.
+
+Order: validated inline source → existing color/WB → native-optical reconstructed-linear geometry/CA → illumination gain → exact orientation permutation → explicit support crop → SDR. Profiles must be authored for **post-color/WB linear-sRGB/D65**, not assumed interchangeable with sensor-channel CA calibration. Raw-domain components and geometry across gain fail through the existing executor. No WB estimator, optical equation, noise generator or tier-based strength is introduced.
+
+The strict `correction` contract requires exact generic profile/independently declared optical state, `coordinateFrame: "native-optical-linear-srgb-d65"`, selections/selection kind, resampler, positive finite clipping level, local `frameTimeSeconds`, support policy and unique public output state ID. Unknown/private fields fail. Profile/state match and committed focal length/aperture/finite focus/native output dimensions are checked. Infinity focus remains unsupported by the profile schema. Body/lens/version, acquisition mode/frame rate/stabilization and profile accuracy remain **producer declarations**, not independently established by the capture container or upgraded to calibration.
+
+Metric rasters derive from committed physical bounds via the capture coordinate bridge; no caller-supplied pitch/center is accepted. All four orientation corner UVs map to native optical +X-right/+Y-up. Sample quarter-turn permutations reuse the existing raster point transform without extra interpolation. Profile output dimensions are **native optical output dimensions**, swapped relative to final oriented width/height for portrait capture. Square physical pixel pitch is required for source and destination (relative tolerance 1e-12); anisotropic lattices fail rather than stretch. Off-center capture/output retain optical-axis offsets.
+
+Local frame time must fall within the exposure interval; capture scene-clock time is preserved separately. Focus-aware projection reuses the field-of-view calculator, whose child result is returned. Conventional active-capture focal equivalence and physical geometry are never rewritten by correction/output crop.
+
+Source/destination are bounded to 65,536 sites each. Inline co-sited three-channel RGB is required after color/WB. No external loading/streaming/prefilter generation occurs. `source-prefiltered` remains a caller obligation, not verification of adequacy. Child sampling plans preserve native optical coordinates, full Jacobians, per-channel support, resampler identity and prefilter diagnostics. Top-level support uses the full **oriented output** lattice.
+
+Support policy `reject` requires all requested output pixels. `joint-valid-crop` uses the existing largest all-valid rectangle after orientation; empty support fails. No missing channel is padded, mirrored or replaced with black. `outputView.rect` is within the declared oriented output raster; cropped samples/dimensions are a derived view, not a replacement capture plane or new physical capture. A later file adapter must deliberately map this view/crop metadata; the paired DNG/JPEG exporter is unchanged.
+
+Original source/capture/noise IDs, source dynamic-range history and upstream saturation remain separate from optional color, correction and SDR child provenance. Aggregate provenance is approximation because corrections are generic-parametric. `illuminationClippingEventCount` counts channel/stage clipping events **before joint support/crop**, including repeated gain stages; it is not an output-pixel or capture-saturation count. SDR gamut diagnostics describe the retained view. Signed/headroom values survive until explicit gain clipping/SDR handling. Noise covariance/SNR is not regenerated or inferred.
+
+Any existing digital correction history rejects a second invocation; staged recorrection needs a future explicit contract. The view must not be relabeled untreated RAW. Mandatory/automatic camera states and educational reference bypass remain distinct; bypass still honors committed output crop/resampling.
+
+Compatibility: root API 0.100.0 → 0.101.0; adapter schema 0.1.0; package/POC/capture/production unchanged. Existing capture-SDR shares an internal source validator and preserves its behavior. Independently authored tests cover quarter turns/native-direction shifts, nonmutation/determinism, crop/support, history/clocks, clipping separation and unsupported boundaries. No runtime dependency, third-party implementation/data/calibration or new cost is added. Human science/provenance review and contribution-specific DCO are required before inclusion.
+
+Remaining V1 work: authoritative sensor RAW producer, explicit production composition, corrected-view/file wiring, end-to-end production capture→RAW→processed-file acceptance and external Adobe/open RAW editor checks. None is marked complete by this bridge.

package/docs/CAPTURE_EXPORT_METADATA.md

@@ -0,0 +1,27 @@
+# Capture export metadata foundation (#16B)
+
+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).
+
+`createCaptureExportMetadataPair()` is a browser-safe, deterministic **semantic metadata projection**, not an image exporter or proof of RAW/JPEG pixel derivation. Both future writers consume its single shared object; each resource has a distinct caller-owned document UUID and saved-incarnation UUID. `imageDataPairing = "not-verified"` prevents metadata agreement being mistaken for image agreement.
+
+The existing committed capture must already have a non-nil RFC-variant UUID CaptureID. Existing opaque-ID captures remain valid for all earlier APIs, but must be created with a UUID to enter this new export boundary; the exporter does not silently replace their identity. UUIDs normalize to lowercase. All five IDs (capture, two resources, two incarnations) must differ, including after case normalization. The engine neither creates randomness nor proves global uniqueness. Preserve document IDs across reserialization of a resource; give a new saved incarnation its own instance ID. Reuse the capture's ID for the same shutter event. New shutter events require caller-owned new capture IDs.
+
+The input contains `capture`, `workflow`, `capturedAtUtc`, `raw: { documentId, instanceId }`, and `jpeg: { documentId, instanceId }`. The event time is a supplied valid canonical UTC timestamp with three millisecond digits, e.g. `2026-10-01T19:00:00.123Z`. Missing time is rejected: no wall-clock read occurs. The existing scene-clock seconds remain a separate semantic value; file-save/metadata-edit timestamps are not supplied or inferred here.
+
+Only two explicit non-generative workflows are supported:
+
+- `human-directed-non-generative` maps to the IPTC `digitalCreation` concept URI.
+- `fully-procedural-non-generative` maps to `algorithmicMedia`.
+
+Classification is caller-declared workflow metadata, not an independent investigation of upstream media. AI-generated, sampled-source, or composite workflows are outside this first policy and require reviewed expansion; do not silently label them with these choices. No `digitalCapture`, AI-specific fields or physical camera claims are emitted. IPTC is the primary semantic reference: [Digital Source Type vocabulary](https://cv.iptc.org/newscodes/digitalsourcetype/), [digitalCreation](https://cv.iptc.org/newscodes/digitalsourcetype/digitalCreation), [algorithmicMedia](https://cv.iptc.org/newscodes/digitalsourcetype/algorithmicMedia). These are references to concept identifiers, not incorporated third-party implementation or calibration data.
+
+Known exposure settings, finite/infinity focus, active-area diagonal 35-mm focal equivalence, native/oriented/output geometry, scene-state identity/time, noise seed/model, resolved WB intent, and model provenance are projected from the parsed immutable capture. Models retain their existing scientific status and public evidence. No model is inferred to be a sensor/lens calibration profile simply because it appears in this list.
+
+Software/creator-tool identity is `Photivra <captured engine API version>`, with explicit `engineApiVersion`; this is not an npm-distribution-version claim. Make/model are `Photivra` / `Photivra Virtual Camera`. Photivra is not automatically the human creator or rights holder. The result omits source bytes and float planes, private paths/hostnames/GPS/serials, invented lens identity, creator/rights, commercial IDs, RAW-data digests, simulation hashes, format calibration and false physical FileSource/SceneType claims.
+
+Geometry is preserved semantically, not packed into EXIF orientation. DNG native samples versus an already-oriented JPEG require different format-specific orientation handling; writers must not rotate twice. This slice does not serialize timestamps, ISO rational/integer tags, focal equivalence rounding, XMP namespace packets, or EXIF identifier representations.
+
+The result is copied/frozen without freezing caller-owned IDs. Repeated projection of identical capture/workflow/time/IDs is identical. It has no runtime dependencies, external I/O or mutable-clock/randomness dependency.
+
+Historical foundation-only gates (current implementation/evidence and external
+gates are mapped in [Export acceptance](EXPORT_ACCEPTANCE.md)): authoritative same-RAW reconstruction/pairing through #112, stable virtual-sensor DNG interpretation/model identity, canonical reproducibility representation + SHA-256, distinct RAW-data identity/digests, complete Photivra XMP 1.0 mapping, optional DNG/JPEG writers, independently decoded samples/metadata, external editor interoperability, and supported-resolution/memory evidence. C2PA #165 consumes the future complete metadata contract and remains post-V1.

package/docs/CAPTURE_SDR.md

@@ -0,0 +1,20 @@
+# Capture-to-SDR adapter
+
+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).
+
+Current integration: [processed camera output](PROCESSED_OUTPUT.md) documents
+the shared preview/export path and explicit plan 0.6.0 post-RAW activation.
+The historical slice descriptions below retain their original scope.
+
+
+`calculateCaptureSdr()` connects the authoritative SimulatedCapture/color contracts to the existing SDR renderer. Adapter schema is `0.1.0`; root API advances to `0.98.0`. Existing capture/color/SDR schemas, production plan, package and POC versions are unchanged.
+
+Choose `already-transformed` for an exact `linear-srgb-d65` profile/version, RGB channel order and D65 encoding white. Choose `transform` to delegate an explicitly selected XYZ/ideal-camera color and WB operation to `calculateCaptureColorTransform()`. Derived plane/state IDs must be new. No WB estimator runs. Intent-only WB is rejected; an already applied state cannot be transformed again. Applied RGB gains and adopted-white adaptation remain distinct; XYZ diagonal adaptation remains approximation, including the adapter envelope.
+
+Input is an inline co-sited three-channel plane, no more than 262,144 samples. Its raster binding, dimensions, reference-white value and source identity are retained. External/oversized planes fail rather than being loaded, truncated, downsampled or silently tiled. The adapter performs no geometric resampling.
+
+The result exposes optional color and SDR calculation envelopes separately, with original capture saturation, dynamic-range history and noise realization identity. Rendering exposure/tone/gamut clipping cannot rewrite physical capture. SDR's own saturation field remains `not-consumed`; original capture saturation is a separate upstream diagnostic, never an output-code inference. Display adaptation remains external/unknown.
+
+This is #112B, not full #112 closure. It does not execute correction profiles or activate production stages. Corrected planes may retain their explicit upstream transform history; no correction is inferred. #117/#118 execution and #111 ordered production integration require their own bound handoff. #16 remains the serializer owner and must not invent color/WB/quantization semantics.
+
+Implementation and fixtures are independently authored orchestration of existing Photivra APIs; no new equation, calibration, third-party material, dependency, service, IO or cost is introduced.

package/docs/DEVELOPERS.md

@@ -0,0 +1,60 @@
+# Developer guide
+
+This is the entry point for **@photivra/engine 1.0.0 candidate**, root API contract **0.116.0**. The candidate becomes an installable 1.0.0 distribution only after the owner tags and publishes it. Repository `main` may later describe newer development; use a published release's packaged docs or its exact tag for the stable contract. [Release notes and migration](RELEASE_1_0.md) explain the version distinction.
+
+Photivra is an Apache-2.0 ESM TypeScript calculation library with no runtime npm dependencies. It exposes explicit units, deterministic data, provenance and bounded scientific approximations. The package supplies no hosted API, renderer installation, UI, commercial camera calibration or automatic agent service. [Photivra's public site](https://photivra.com) is separate from the engine's license; public engine documentation is available here without an application account.
+
+## Install and calculate
+
+After publication, install `npm install @photivra/engine@1.0.0`. During candidate review, use the verified tarball described in [release preparation](RELEASE_1_0.md).
+
+```ts
+import { calculateFieldOfView, ENGINE_API_VERSION } from "@photivra/engine";
+
+const horizontal = calculateFieldOfView({ focalLengthMm: 50, sensorDimensionMm: 36 });
+console.log(ENGINE_API_VERSION); // 0.116.0: independent root contract identity
+console.log(horizontal.value.degrees); // approximately 39.60, ideal infinity-focus geometry
+console.log(horizontal.provenance); // read assumptions/status with the value
+```
+
+The root is browser-safe. Supported Node execution/tooling is Node 22.13+ within the maintained 22 line and the maintained 24 line; prefer patched Node 24. The broad manifest minimum does not qualify Node Current/EOL lines. A browser backend must supply the documented ES APIs (including `structuredClone`, typed arrays and Web Crypto where used); a browser-safe import graph is not a promise about every browser version or rendering speed. See [runtime policy](../NODE_SUPPORT.md).
+
+Primitive calculations normally return `CalculationResult<T>` with `value`, `provenance` and optional `quality`. Parsers return validated values; plans/snapshots return their independently versioned records; assessments return explicit blockers; paired export returns a Promise because hashing is asynchronous. Do not infer calibrated accuracy from successful parsing, a complete stage graph, a generic tier name or deterministic replay.
+
+## Find the operation by scientific task
+
+Every row applies to package 1.0.0/root 0.116.0. Direct calculations are synchronous/browser-safe unless the row says otherwise. A listed primitive is not automatically an app feature or supported in every production combination. The [API reference](API_REFERENCE.md) resolves all root exports and exact signatures; the linked guides own equations, inputs, defaults, errors and limits.
+
+| Task | Start here / executable evidence | Qualified boundary |
+| --- | --- | --- |
+| FOV, focus, depth of field, subject size | [Usage: field of view](USAGE.md#field-of-view), [physics](PHYSICS_FOUNDATION.md), [quick start](examples/quick-start.mjs) | Ideal paraxial/thin-lens geometry; explicit mm/metres/axes |
+| Aperture, diffraction, sampled PSF | [PSF foundation](PSF_FOUNDATION.md), [usage](USAGE.md#real-lens-psf-profiles-and-complex-pupil-reference) | Shape and throughput separate; explicit support; no inferred commercial calibration |
+| Metering and exposure modes | [Usage: relative metering](USAGE.md#relative-pre-exposure-metering), [API conventions](API_STYLE.md) | Relative pre-exposure linear signal; compensated target before control; ISO does not create photons |
+| Rigid/depth motion and stabilization | [Motion](MOTION_AND_SIGNAL.md), [stabilization](STABILIZATION.md) | Declared constant-motion/generic control models; visibility remains external |
+| Continuous or discrete spectral measures | [Scene/illumination](SCENE_RADIANCE_AND_ILLUMINATION.md) | Continuous dλ in nm versus wavelength-integrated line fractions; `distribute*` preserves quantity domain |
+| Sampling, response validity, photon/electron expectations | [Usage](USAGE.md#sensor-spectral-response), [temporal EQE](SENSOR_EQE_TEMPORAL_EXPOSURE.md) | Exact source-plane/area/profile/wavelength/time bindings; no implicit QE/collection area |
+| Execute declared environment → production RAW → output | [Production envelope](PRODUCTION_ENVIRONMENT_CAPTURE.md), [complete packed example](examples/production-capture.mjs) | Node example loads owned data; engine callback is synchronous; 4,096 native sites / 100,000 provider evaluations |
+| Preserve/reconstruct RAW and develop preview | [RAW envelope](RAW_FRAME_ENVELOPE.md), [processed output](PROCESSED_OUTPUT.md) | Signed shadows, absolute CFA phase, explicit sensor-channel color/WB; rendering does not redraw noise |
+| Pair native CFA DNG with processed JPEG | [Photographic export](PHOTOGRAPHIC_EXPORT.md), [acceptance](EXPORT_ACCEPTANCE.md) | Async Web Crypto; registered Bayer reference; 1:1 output crop; caller saves bytes |
+| Commit capture, ideal virtual-camera color, linear encoding | [Capture](SIMULATED_CAPTURE.md), [ideal color](CAPTURE_COLOR.md), [encoding](LINEAR_CAPTURE_ENCODING.md) | Ideal XYZ encoding differs from approximate sensor-channel development |
+| Generic tiers and correction cost | [Presets](GENERIC_TIER_PRESETS.md), [tier acceptance](TIER_ACCEPTANCE.md), [correction](DIGITAL_OPTICS_FOUNDATION.md) | Versioned owned synthetic assets; no universal quality ranking |
+| Reproduce conformance/performance | [Scientific suite](SCIENTIFIC_CONFORMANCE.md), [performance disposition](V1_PERFORMANCE_DISPOSITION.md) | CI science gates; Node measurements do not establish browser or megapixel performance |
+| Optional local HTTP development transport | [Repository POC](POC_API.md) | Node-only checkout tooling, excluded from root/package; unauthenticated loopback |
+
+## Complete packed examples
+
+The package includes `docs/examples/quick-start.mjs` and `production-capture.mjs`. In a Node ESM consumer directory with the candidate installed, copy these files and `production-request.json` from `node_modules/@photivra/engine/docs/examples/` into that directory and run them. The quick start asserts independent geometry/exposure invariants. The production example executes the same owned 2×2 narrow-band synthetic fixture used in final conformance through all fourteen production stages and paired byte export, retaining the exact RAW codes and deterministic replay. It writes no files and installs no renderer.
+
+The JSON data is explicitly synthetic: uniform angular radiance `1e-9 * (1 + 200t)` W/m²/sr/nm; 540–560 nm band; independently declared 800×600 µm sensitive aperture and package-incident EQE 0.4; registered opening-reference time; fixed seed and generic consumer profiles. This is a controlled regression laboratory, not a real scene, native camera pixel pitch, calibrated color/visibility, PSF transport proof or convergence bound. Production supports only the envelope linked above. The tiny DNG demonstrates byte serialization/lineage; external-reader acceptance uses separate larger fixtures.
+
+The [Usage Guide](USAGE.md) includes both complete snippets and clearly marked composition fragments that require earlier validated bindings. The release checker typechecks and executes complete importing snippets against the packed artifact; it inventories fragment dependencies without pretending missing calibration data exists.
+
+## Contracts and support
+
+Use only `import ... from "@photivra/engine"`. Deep paths and repository transport/scripts/test helpers are unsupported. TypeScript declarations describe shape; parse untrusted JSON before scientific execution. Keep native +Y-down, optical +Y-up and half-open raster rectangles explicit. Preserve domain distinctions between radiance, irradiance, rates, expected counts, realized charge, RAW codes and processed SDR.
+
+Malformed configurations/non-finite values throw the established domain errors. Scientifically incomplete but well-formed assessments/plans expose structured blockers. Trusted provider callback exceptions propagate; no silent fallback renderer runs. The exact return contract and independent model versions are visible in the reference and declarations.
+
+See [provenance](PROVENANCE.md), [license](../LICENSE), [NOTICE](../NOTICE), [third-party inventory](../THIRD_PARTY.md), [contributing](../CONTRIBUTING.md) and [security reporting](../SECURITY.md). Engine code/docs do not license the commercial application or its private assets. Report reproducible engine defects through [public issues](https://github.com/Photivra/photivra/issues).
+
+Website navigation/documentation hosting belongs to [the app-side discovery ticket #45](https://github.com/Photivra/photivra-apps/issues/45), with navigation #298 and environments #300. Handoff: link the public engine repository, this developer guide, the eventual verified npm 1.0.0 package and capability examples from the public site. No unpublished `/developers` destination is linked here. Website launch is not an engine release prerequisite; access to the site returned HTTP 403 during this audit, so its content/navigation was not verified.