@photivra/engine 1.5.0 → 2.0.0

package/docs/PRINT_CONTRAST_REFERENCE.md

@@ -1,43 +0,0 @@
-# Static neutral Print contrast reference — model 0.1.0
-
-`calculatePrintContrastReference()` evaluates a restricted static, foveal, neutral D65 Gabor reference from castleCSF. This is an **estimated population-model reference**, separate from measured regional detail and sampling sufficiency. It does not classify a photograph, promise invisibility, establish personal acuity or produce an overall Print verdict. Actual stimulus matching remains unassessed.
-
-## Model and source review
-
-The numerical source is [castleCSF revision f4b0b722af83001d7af979281e06ca642d36e4e8](https://github.com/gfxdisp/castleCSF/tree/f4b0b722af83001d7af979281e06ca642d36e4e8), including `CSF_castleCSF.m`, `CSF_stelaCSF_lum_peak.m`, `CSF_castleCSF_chrom.m` and `CSF_base.m`. These code files contain the model equations, numerical parameters, neutral D65 background and mechanism projections. The repository license is MIT, copyright 2023 Graphics and Displays group, University of Cambridge. Retain the [exact license](licenses/castleCSF-MIT.txt), copyright in source and `NOTICE`, and the inventory in `THIRD_PARTY.md`. The scalar TypeScript adapter and independent high-precision evaluator are newly authored; the numerical model material is third-party material, not asserted to be Photivra-owned calibration.
-
-The [primary paper, Ashraf et al. (2024)](https://pmc.ncbi.nlm.nih.gov/articles/PMC10996938/) describes sensitivity as a function of stimulus conditions and reports population-model validation. Its fixed-size static achromatic Gabor reference is relevant to this restricted stimulus. We do not reproduce the paper, tables, figures or observational datasets. No CSV from the combined historical datasets is included; their reuse/collection history is not inferred from the code license. Source/license review of this new numerical material remains a substantive human release gate.
-
-## Explicit conditions and quantities
-
-Every input must explicitly identify the stimulus and published binocular/natural-pupil reference assumption. The implemented numerical envelope is mean luminance **1–1000 cd/m²**, carrier frequency **0.25–16 cycles/degree**, Gaussian envelope sigma **exactly 1.5 degrees**, temporal frequency **zero** and eccentricity **zero**. These are model-evaluation limits, not a calibration certificate covering every observer or combination. Positive values outside this envelope yield `unsupported`, not extrapolation. Michelson modulation is a supplied fraction in `[0,1]`; luminance is not inferred from capture exposure, a display percentage, paper whiteness or image RGB.
-
-The luminance input is the uniform D65 background/carrier mean used by the upstream model. The supplied modulation is the neutral sinusoidal carrier fractional amplitude before its Gaussian envelope. It is not a finite image ROI average, arbitrary image extrema ratio, Fourier residual or noise RMS. A Gaussian window changes the spatial stimulus; rectangular-grating equivalence is not established by the scalar adapter. The primary paper discusses aperture-equivalence assumptions and their limitations. Its individual datasets use different envelopes at some frequencies, so the adapter’s numerical envelope must not be presented as a uniformly measured empirical calibration grid.
-
-Equal fractional modulation of the upstream neutral D65 LMS background is selected. Retain the achromatic sustained/transient responses and both opponent-mechanism projections; the neutral background has small nonzero opponent projections. Static temporal response and the Gaussian effective area `pi sigma²` follow the pinned model. Evaluate luminance-dependent hyperbolic terms using log1p/expm1 to retain the small saturation term. This is scalar evaluation of the mathematical equations, rather than bit-for-bit emulation of MATLAB's cancellation in `1 - power(...)`.
-
-Return sensitivity, its reciprocal threshold modulation, and supplied modulation divided by that threshold. They remain continuous model quantities. The API offers no `visible`, `invisible`, `pass`, personal-vision score or automatic print-quality recommendation. It neither combines independent image-quality dimensions nor maps a Fourier residual/noise RMS into a Gabor contrast. Fitted population variation and upstream fit errors do not supply an individual confidence interval. Uncertainty remains explicitly unquantified.
-
-## Independent numerical protocol
-
-The committed [reference generator](../test/fixtures/print-detail/generate_contrast_reference.py) evaluates the scalar equations with Python standard-library Decimal at 80 digits, using direct hyperbolic powers, an independently arranged area term and exact decimal parameters. It imports no engine output. The [reference artifact](../test/fixtures/print-detail/contrast-reference.json) covers 35 luminance/frequency points. SHA-256, source revision, protocol and conditions are checked by the public-root test. Compare sensitivity and threshold with relative arithmetic tolerance `1e-12`; this is numerical conformance, not an observer-accuracy claim. Tests also cover domain boundaries, immutable copied input, explicit zero contrast, malformed conditions and absence of a visibility verdict.
-
-Neither the upstream MATLAB runtime nor new observer experiments have been executed by this protocol. Upstream empirical results provide a research basis, and the independent Decimal reference qualifies this scalar evaluation only. Actual photographic/printed-stimulus transfer, masking, age/ocular differences, absolute print luminance, color, glare, eccentricity, temporal presentation and viewing-device qualification remain separate. The coherent rectangular grating diagnostic is not a Gaussian-envelope stimulus; its modulation cannot be passed off as matched Gabor evidence. #196's full scoped acquisition/perceptual acceptance remains open until the capability ledger records the missing evidence and substantive human review.
-
-## Complete public example
-
-```ts
-import { calculatePrintContrastReference } from "@photivra/engine";
-const reference = calculatePrintContrastReference({
-  referenceId: "example-population-reference", stimulus: "static-neutral-d65-gabor",
-  observer: "published-binocular-natural-pupil-reference",
-  meanLuminanceCdPerSquareMeter: 50, spatialFrequencyCyclesPerDegree: 4,
-  gaussianEnvelopeSigmaDegrees: 1.5, temporalFrequencyHz: 0,
-  eccentricityDegrees: 0, modulationMichelson: 0.01
-}).value;
-if (reference.status !== "model-estimate" || !reference.estimate) throw new Error("Unexpected reference domain");
-if (reference.naturalImageVisibility !== "unassessed" || reference.overallPrintVerdict !== "not-offered") throw new Error("Unexpected quality claim");
-console.log(reference.estimate, reference.observerApplicability);
-```
-
-This evaluates a declared reference stimulus. It is not evidence that an actual photograph or print meets those stimulus/observer conditions.

package/docs/PRINT_DETAIL_ASSESSMENT.md

@@ -1,81 +0,0 @@
-# Regional Print detail diagnostic — model specification 0.1.0
-
-This is the bounded mathematical first slice of #196, using the [Print geometry contract published in 1.1.0](PRINT_PLANNING.md). This diagnostic is not full #196 acceptance, a natural-image sharpness evaluator, a visibility threshold or an overall print pass. The [validation protocol](PRINT_DETAIL_VALIDATION.md) and [capability ledger](validation/print-196-candidate-capabilities.json) identify what is tested and what remains blocked. The additive [regional statistics protocols](PRINT_REGION_STATISTICS.md) separately measure processing differences and repeat-capture sample variance; they do not change this diagnostic's qualification or exclusions.
-
-## Supported model and domain
-
-Measure one declared coherent sinusoidal fundamental in one explicitly selected rectangular region of a scalar **relative linear luminance** raster. The target declares integral signed cycle counts `(kx,ky)` across region dimensions `(W,H)` and positive reference modulation at most one. Pixel index `(0,0)` is the first region sample center. The target phase is arbitrary. At least one cycle count must be nonzero and both component frequencies must lie strictly inside the per-axis Nyquist interval. DC and self-conjugate/Nyquist bins are unsupported; two equal samples at Nyquist cannot establish phase-independent fundamental amplitude.
-
-The caller supplies a dense row-major sample array for that region, at most 65,536 finite values. Signed values are retained; capture noise and processing can produce negatives. Successful parsing does not establish that a photograph actually depicts the declared target or that an acquisition is qualified. A positive numerically supported DC mean is required for relative modulation. Arbitrary photographs, nonperiodic windows, automatic target detection, gamma-encoded luma, unknown luminance extraction, correction/warp registration and mixed/nonuniform target frequencies are outside this first model.
-
-## Mathematical quantity
-
-Let `phi(x,y) = 2 pi (kx x/W + ky y/H)`, `m = mean(samples)`, `a = 2 mean(samples cos(phi))` and `b = 2 mean(samples sin(phi))`. Then fundamental amplitude is `sqrt(a²+b²)`, fundamental modulation is amplitude divided by positive `m`, and the reported transfer of the **declared input grating** is modulation divided by reference modulation. Values above one remain above one; they do not establish quality uplift or a qualified MTF. A single frequency does not determine a full response, MTF50, PSF, effective megapixels, perceived sharpness or resolution limit. No defocus/diffraction/motion equation or blur-diameter conversion is added.
-
-Return the residual RMS after the fitted mean/fundamental, relative to DC. It is unexplained residual energy, not a noise variance, halo classifier, compression measure or model-accuracy bound. Realization noise can project into the fundamental and bias amplitude. No ensemble estimate, confidence or combined uncertainty is fabricated.
-
-Normalize samples by their maximum absolute magnitude before coefficient accumulation, and use compensated summation that retains corrections when large signed terms cancel. Reject any nonzero sample that underflows to zero during normalization. Accumulate the residual norm with stable hypot operations rather than squaring tiny/large residuals directly. Reduce phase modulo one cycle before trigonometry. Restore units only for mean/amplitude. Nonpositive DC, nonfinite/underflowed restored quantities or nonfinite derived ratios produce an unsupported numeric/domain state; do not clamp tiny nonzero energy into identity or loosen tolerances to manufacture a pass. Transcendental conformance tolerances belong to the independent protocol, not to a quality decision.
-
-## Region, stage and identity
-
-The input records an assessment ID, immutable capture ID, exact representation ID and declared SHA-256, actual raster, source stage, processing/decoder ID and version, optional noise-realization ID, reusable sample provenance, region ID/rectangle/role, declared subject/focus distances (or explicit null), and target identity/version. SHA-256 and provenance are caller declarations; the engine neither fetches the artifact nor verifies full-file decoding from an ROI array. Retain this distinction in downstream evidence. The returned frozen owned input includes the exact ROI samples. New region, content, processing, target or print/viewing conditions require a new assessment ID; labels alone do not prove equality.
-
-Coordinates are oriented retained-image raster coordinates, top-left, +X right, +Y down. Source stages are native-retained linear, post-resampling linear, and post-encoding decoded linear. Native stage must match the authoritative retained native dimensions from existing capture geometry. Later stages must preserve that exact aspect ratio and must not enlarge either native axis. The first registration is oriented retained, unwarped; correction/warp requires an independently supported coordinate registration. Existing geometry maps ROI center to the optical image plane (+Y up), preserving off-center capture/crop and all four orientations. Field position is descriptive and does not create a field-dependent optical model. Only the explicitly selected region is measured; an intentionally defocused background is never aggregated into a frame verdict.
-
-Printed dimensions/viewing distance come from `calculatePrintPlan()`; no consumer equation is introduced. The regional fundamental vector converts to cycles/mm using ROI's physical span within the declared represented image. Report its physical period and the exact angular period **at the normal viewing reference at image center**: `2 atan(period/(2 distance))`. This is a reference-period angle, not a spatially uniform cycles/degree grid, an off-center retinal calculation or perceptual threshold. Retain field and ROI location separately. Changing viewing conditions changes angular projection, not measured captured samples/modulation.
-
-A result also states whether the assessed actual raster equals the current recommendation. A pre-encoding diagnostic never certifies JPEG compression. A post-encoding declared source records the exact artifact/decoder identity but still does not qualify compression, decoding, color or overall quality. Actual delivery remains independent of native sufficiency.
-
-## Assurance and explicit exclusions
-
-Use existing calculation envelopes, finite-number validation, strict allowlists, public-ID grammar, shared owned-data freezing, evidence provenance and composed scientific assurance. Mathematical coefficients are calculated. Acquisition/registration/target truth remain scientifically unknown in this contract; evidence metadata never promotes them to calibration. Result capabilities for captured MTF, optical attribution, visibility/perceived quality, noise, aliasing, halos, compression and color remain unassessed. No automatic print pass is exposed.
-
-Malformed structural/numeric data throw typed existing errors. Well-formed incompatible identities, aspect, stage or registration return blockers; unsupported frequency/domain/numeric cases return explicit unsupported status. Missing authoritative native geometry remains a blocker. Provider shortfalls and sampling shortfalls do not disappear when a regional contrast coefficient exists.
-
-## References and reuse review
-
-- [Boone, Yu and Seibert (1996), sinusoidal modulation measurement](https://pubmed.ncbi.nlm.nih.gov/8994160/), DOI 10.1118/1.597840: primary research motivating explicit sinusoidal input, processing and sampling context. No commercial target, numeric table, PIRT code or procedure is copied or implemented.
-- [Campbell and Robson (1968), grating visibility](https://physoc.onlinelibrary.wiley.com/doi/10.1113/jphysiol.1968.sp008574): primary research motivating the separation of a Fourier coefficient from a qualified perceptual model. No observer thresholds/curves/data are incorporated.
-- The issue's Imatest sharpness guide is background terminology only. No proprietary algorithm, chart or source expression is used. [Westheimer (1977), acuity and hyperacuity](https://pubmed.ncbi.nlm.nih.gov/839301/), DOI 10.1364/josa.67.000207, distinguishes resolution and localization tasks; it supplies no universal print visibility threshold. No psychophysical thresholds or observer data are incorporated.
-
-All specification, code and analytic targets/reference calculations are independently authored. Mathematical identities and self-owned procedural targets are the numeric evidence; public references are factual-reference-only. Actual supplied sample arrays require Photivra ownership or declared reusable-data licensing. No third-party numeric material, private assets or runtime dependencies are incorporated. Human scientific/source, licensing and DCO review remains required; AI declarations alone do not certify provenance or patent clearance.
-
-## Complete packed mathematical example
-
-This self-owned procedural target validates the coefficient path; it is not acquired-image or renderer evidence.
-
-```ts
-import { calculatePrintRegionDetail, type PrintRegionDetailInput } from "@photivra/engine";
-const input: PrintRegionDetailInput = {
-  assessmentId: "example-diagnostic",
-  print: {
-    source: { kind: "native-retained", captureId: "owned-example", geometry: {
-      imagingArea: { widthMm: 32, heightMm: 32 },
-      nativeRaster: { pixelWidth: 8, pixelHeight: 8 }, orientation: "landscape"
-    } },
-    printedImage: { width: 8, height: 8, unit: "inches" },
-    viewingDistance: { value: 24, unit: "inches" },
-    sampling: { kind: "manual-ppi", pixelsPerInch: 1 },
-    fit: { kind: "confirmed-native-aspect", maximumRelativeAspectError: 0 }
-  },
-  source: {
-    captureId: "owned-example", representationId: "owned-analytic-array",
-    contentSha256: "a".repeat(64), raster: { pixelWidth: 8, pixelHeight: 8 },
-    stage: "native-retained-linear", domain: "relative-linear-luminance",
-    registration: "oriented-retained-unwarped",
-    processing: { id: "owned-example", version: "0.1.0" }, noiseRealizationId: null,
-    evidence: [{ sourceOrigin: "photivra", sourceReference: "owned-procedural-example", reuseStatus: "photivra-owned" }]
-  },
-  region: { id: "example-region", rect: { x: 0, y: 0, width: 8, height: 8 },
-    role: "field-diagnostic", subjectDistanceM: null, focusDistanceM: null },
-  target: { id: "quarter-period", version: "0.1.0", kind: "coherent-sinusoid",
-    cyclesAcrossRegion: { x: 2, y: 0 }, referenceModulation: 0.5 },
-  samples: Array.from({ length: 64 }, (_, i) => [1.5, 1, 0.5, 1][i % 4]!)
-};
-const assessment = calculatePrintRegionDetail(input).value;
-if (assessment.status !== "diagnostic-only" || Math.abs(assessment.measurement!.fundamentalModulation - 0.5) > 1e-10) throw new Error("Unexpected analytic coefficient");
-if (assessment.assurance.scientificStatus !== "unknown" || assessment.overallPrintVerdict !== "not-offered") throw new Error("Unexpected qualification");
-console.log(assessment.measurement, assessment.unassessed);
-```
-
-The repeated `a` hash is an explicit placeholder declaration, not a verified digest. Real acquired evidence must replace it with a verified exact representation hash and qualify the target/ROI, processing and active backend independently.

package/docs/PRINT_DETAIL_JPEG_EVIDENCE.md

@@ -1,36 +0,0 @@
-# Regional detail paired-export JPEG evidence 0.1.0
-
-This addendum to [the regional diagnostic protocol](PRINT_DETAIL_VALIDATION.md) qualifies only a bounded execution test: owned post-ADC RAW codes → public paired-export reconstruction/color/SDR/JPEG → independently recorded JPEG decode → neutral relative-linear luminance → regional fundamental. It extends [the capture-SDR execution evidence](PRINT_DETAIL_SDR_EVIDENCE.md) without changing the metric, public API, dependencies or historical records. Human scientific/source review remains pending; full #196 acceptance remains blocked.
-
-## Owned source and target truth
-
-`test/helpers/print-detail-jpeg-fixture.ts` supplies a native 20 × 16 periodic Bayer frame. Every complete 2 × 2 tile has one neutral post-ADC code from repeating `[640,448,256,448]`. Black is 64 and white is 1023, so linear tile levels are `[576,384,192,384]/959`. Source mean is `384/959`; the two-sample-held eight-pixel period has fundamental modulation `0.5 cos(pi/8)`. This follows the discrete hold's half-sample phase and cosine attenuation. The target contains known higher harmonics and is not a pure continuous optical sinusoid. Only its declared coherent Fourier fundamental is assessed; its residual cannot be classified as noise or a compression artifact.
-
-This is owned synthetic draft post-ADC data, not a renderer-acquired optical target or noise realization. The existing declared ideal test color profile and tile-average reconstruction are reused. Neither becomes physical calibration. The source's placeholder float plane does not supply JPEG pixels: the public export develops the committed RAW codes. The independent Python check derives expected neutral pre-encode codes from the source codes and explicit orientation permutation, with no engine imports. It separately verifies the source's fundamental identity.
-
-## Exact stage and independent reference
-
-Eight committed JPEGs cover all four orientations at constant quantization steps 1 and 32. These are scalar encoder parameters, not manufacturer's quality scores. Each orientation has a distinct capture ID; its quantization variants retain that same capture identity, with unique document/instance IDs for each exported file. The public exporter executes orientation itself, writes already oriented JPEG pixels, and declares EXIF orientation 1. Native 20 × 16 becomes 20 × 16 or 16 × 20. Partial eight-pixel coding blocks exercise the encoder's edge padding without changing the declared raster. The selected off-center half-open ROI begins at `(2,2)` and is 16 × 8 in landscape or 8 × 16 in portrait; it spans two target periods and JPEG block boundaries.
-
-`export-manifest.json` records actual source codes, pre-encode RGB, JPEG SHA-256, raster, target and ROI identities. `independent-reference.json` binds to its exact bytes and records installed Pillow/libjpeg/Python versions, independently decoded RGB bytes/hash, ROI float64 little-endian bytes/hash and separately calculated pre-encode/decoded coefficients. The verifier requires neutral equal decoded RGB channels; each inverse-transferred channel is then relative linear luminance. It does not define a colored RGB luminance extractor, ICC transform or generic decoder policy.
-
-The independent reference calculates mean, cosine/sine coefficients, amplitude, modulation and residual using Python `math.fsum`, independently of the engine accumulator. Every Node test regenerates actual paired-export JPEG bytes and requires exact agreement with the committed JPEG, manifest hash and independent decoded-byte record. It converts the recorded neutral pixels to linear values, compares each ROI sample within absolute 1e-12, and compares all regional measurements within 1e-10. These are numerical tolerances for 128 positive bounded samples, not perceptual thresholds. Integer bytes, raster identities and hashes are exact checks. Node CI consumes committed independent decode evidence; it does **not** execute Pillow anew.
-
-The actual runtime linear luminance plane receives a separate float64 little-endian SHA-256 carried unchanged through the diagnostic input/result. It is linked by the test to the exact JPEG and decoder record. The public diagnostic still returns `caller-declared-unverified`, unknown scientific assurance and `not-offered` overall verdict; it performs no IO or automatic provenance upgrade.
-
-## Reproduction and invalidation
-
-```sh
-node scripts/generate-print-detail-jpeg.mjs /tmp/photivra-print-jpeg-reproduction
-python scripts/verify-print-detail-jpeg.py /tmp/photivra-print-jpeg-reproduction --record
-python scripts/verify-print-detail-jpeg.py test/fixtures/print-detail/jpeg
-npx vitest run test/print-detail-jpeg-integration.test.ts
-```
-
-Generation uses the repository's existing development compiler. Python QA uses an existing installed Pillow; no engine/runtime/development dependency or CI install is added. A missing Pillow fails the independent check rather than silently passing. `--record` writes a new candidate reference for review; verification without it requires the committed decoder versions and results to agree. Preserve old records when the source, reconstruction, color model, renderer, encoder, registration, target, ROI, metric or decoder changes. Regeneration is evidence collection, not human approval. [The separate evidence ledger](validation/print-detail-jpeg-evidence.json) pins source hashes and the finite execution envelope.
-
-Fine quantization preserves this target's measured regional modulation within numerical tolerance. Coarse quantization changes it and may increase the fundamental or residual. An increased transfer coefficient does not imply restored detail, improved quality, invisibility or a compression pass. Source RAW, pre-encode RGB and native raster remain unchanged between quantization variants; only the exact encoded representation and its diagnostic differ.
-
-## Remaining qualification
-
-This evidence covers one owned neutral stepped grating, one source/processing policy, one selected ROI per orientation and one recorded independent decoder configuration. It does not qualify optical acquisition/MTF, spectral color calibration, other targets/frequencies/depths, noise/aliasing/halos/compression classifiers, generic image codecs or decoder variants, resampling/warp, native-resolution production, UI/GPU/device/display execution, observer perception or printer/substrate response. No JPEG quality verdict is introduced. Full scoped new-UI acceptance remains blocked until the missing evidence and substantive human review are complete.

package/docs/PRINT_DETAIL_SDR_EVIDENCE.md

@@ -1,29 +0,0 @@
-# Regional detail bounded capture-SDR evidence 0.1.0
-
-This addendum to [the regional diagnostic protocol](PRINT_DETAIL_VALIDATION.md) records execution through the public `createSimulatedCapture` → `calculateCaptureSdr` → test-only quantized-code readback → `calculatePrintRegionDetail` path. It does not change the metric, public API, or historical mathematical qualification record. Human scientific and source review remains pending. Full #196 acceptance remains blocked.
-
-## Source and independent reference
-
-`test/fixtures/print-detail/quarter-grating.json` commits a 16 × 12 neutral linear-sRGB/D65 target. Its repeated values are `[0.6, 0.4, 0.2, 0.4]`: mean 0.4, fundamental amplitude 0.2, modulation 0.5. Values are co-sited neutral RGB, so each equal channel is the relative luminance; this does not qualify colored target luminance extraction. This is owned procedural draft data, with no measured scene or commercial-camera calibration.
-
-`generate_reference.py` uses only Python's standard library and no engine imports to reproduce source bytes and `sdr-reference.json`. Run `python test/fixtures/print-detail/generate_reference.py`. The reference independently applies the repository's documented sRGB transfer and nearest-ties-up quantization to the three discrete levels. For decoded levels A, B, C, discrete orthogonality gives mean `(A + 2B + C)/4`, amplitude `abs(A-C)/2`, and modulation amplitude/mean. A remaining second harmonic can occur after quantization; it is not noise, compression or a quality classification.
-
-The reference commits SHA-256 for exact source JSON bytes, each registered RGB plane as interleaved float64 little-endian bytes, and each integer output as uint16 little-endian bytes (also for 8-bit codes). Tests verify these hashes against actual source and adapter output. Decoder floating values are checked within absolute 1e-12 of the independent Python reference, since power-function implementations may differ in the last binary64 bit. The actual runtime decoded RGB plane is separately hashed as float64 little-endian bytes and its exact hash carried into the diagnostic input/result; the diagnostic itself remains `caller-declared-unverified` and performs no artifact IO. Hash agreement establishes byte identity within this test path, not acquisition truth or reusable rights.
-
-## Finite execution envelope
-
-| Dimension | Evidence envelope |
-| --- | --- |
-| Source | One committed neutral, positive, in-range quarter-cycle target; no stochastic noise |
-| Registration | Owned explicit native-to-oriented discrete permutation; four orientations, no warp or resampling |
-| Raster | Native 16 × 12; oriented 16 × 12 or 12 × 16 |
-| Region | Half-open 8 × 8 region beginning at `(2,2)`; x- or y-directed two cycles, orientation-dependent phase |
-| Capture state | Explicit already-transformed linear-sRGB/D65, declared owned neutral encoding history, WB not required |
-| Adapter | Capture-SDR schema 0.1.0, identity tone, zero rendering EV, reject out-of-range, no dither |
-| Quantization/readback | 8 and 16 bits; test-only inverse transfer of integer codes, no image file codec |
-| Reference checks | Exact source/plane/code hashes; all decoded pixels and independent region mean/modulation/transfer within 1e-12 |
-| Backend | Repository Node execution; CI runtime matrix and exact commit/run recorded in the draft PR |
-
-The adapter consumes an already oriented plane; it does not execute the orientation permutation. Tests establish this declared registration independently before execution. They preserve capture identity and source history and assert that rendering does not mutate the capture. Geometry/orientation mathematical tests remain in the original protocol. This evidence does not qualify the UI's active renderer, GPU, native-resolution producer, memory envelope, device display, RAW/environment acquisition, color conversion, clipping accuracy, JPEG compression, physical optical MTF, depth/occlusion, observer perception, or printer/substrate response.
-
-The capability record is [print-detail-sdr-evidence.json](validation/print-detail-sdr-evidence.json). Previous records and their hashes remain unchanged. Rerun this evidence when the target, reference, capture adapter, SDR renderer, diagnostic or test registration changes; do not extend the finite envelope from a passing parser or procedural generator. The new UI still requires reviewed actual source/backend evidence for its own execution path and the remaining scoped quality dimensions.

package/docs/PRINT_DETAIL_VALIDATION.md

@@ -1,36 +0,0 @@
-# Regional Print detail independent validation protocol 0.1.0
-
-This protocol tests the mathematical domain in [the model specification](PRINT_DETAIL_ASSESSMENT.md). Passing does not qualify arbitrary photographed targets, renderers, lenses, printers or perceptual decisions. [The capability ledger](validation/print-196-candidate-capabilities.json) must retain these limits.
-
-## Public analytic evidence
-
-Procedural targets are owned test data, with known mean, modulation, integer spatial frequencies and phase. Reference derivations use finite orthogonality and discrete convolution identities, independently of the implementation's coefficient accumulator.
-
-| Case | Independent expected behavior |
-| --- | --- |
-| Exact quarter-cycle sequence | Mean 1 and declared fundamental modulation 0.5; derive from explicit repeated values, not engine output |
-| Large signed cancellation | Explicit `(L + 1 - L + 1)/4 = 1/2` DC and amplitude normalized by independently known `L`; no residual/noise accuracy claim under cancellation |
-| DC/gain/phase variants | Gain preserves modulation; changed mean changes relative modulation; arbitrary phase preserves amplitude |
-| Isotropic symmetric filtering | Known separable symmetric kernel attenuates axial x/y targets equally |
-| Directional filtering | Apply owned `[1/4,1/2,1/4]` in x only: response is `(1+cos(2 pi f_x))/2`; orthogonal target is unchanged |
-| Equal-PPI, different detail | Same geometry and raster; independent filtered/unfiltered sample arrays have different coefficients |
-| Subject versus deliberate defocus | Select separate regions/roles; retain each result; no whole-frame minimum or score |
-| Crop and physical enlargement | Actual ROI/retained raster stay explicit; samples/modulation do not change when only print size/distance changes |
-| Four orientations, off-center capture | Existing coordinate transforms predict optical field location; no ad hoc axis conversion |
-| Independent extra harmonic/noise realization | Fundamental/residual responses follow orthogonality; noise/artifact dimensions remain unassessed |
-| Post-resampling versus decoded encoding | Bind actual raster/stage/content/decoder; pre-encode cannot imply JPEG qualification |
-| Invalid/unsupported input | Reject unknown keys/enums/IDs, holes/nonfinite samples and invalid bounds; block identity/domain/registration mismatch and unsupported Nyquist/DC |
-
-For normalized analytic coefficients and relative residuals, use an absolute tolerance of 1e-10 for small bounded arrays (up to 4096 samples). This accommodates trigonometric and accumulation error while remaining far below the deliberately tested contrast differences (at least 0.01). Exact identities/integers/statuses are checked exactly. A separate upper-bound sample test verifies the 65,536-sample work cap and documented float range; it does not infer a device performance or memory envelope. Fixed seeds remain committed. Tolerances must be reviewed when algorithm/domain changes, never loosened merely to pass a failure.
-
-Run focused tests, then existing full check, coverage, build, package, browser, license/SPDX, identity, documentation and isolated packed-example gates. Record exact metric/protocol/target/test-source/engine versions and commit, test counts and CI head. Preserve previous assessment/evidence records; do not relabel old qualification with a new creator version. A metric or source change invalidates affected downstream evidence until rechecked.
-
-## Uncompleted acquisition and release qualification
-
-Before claiming measured regional image detail in the new UI, independently qualify actual target/ROI truth, visible depth/occlusion, source and target licensing, coherent-frequency registration, native/crop/correction mapping, field/phase/orientation coverage, actual renderer/backend and source-stage/processing/decoder identity. Test the active backend against the independent analytic references, not against a second call to this engine. Record supported device/raster limits and source/destination artifacts with verified hashes. Procedural target generation and parser success alone are insufficient.
-
-Noise requires separate linear/high-bit and same-realization versus ensemble evidence. Clipping requires explicit stage. Motion requires qualified trajectory/temporal accumulation. Halos, aliasing, compression and color require their own metric/protocol and stage-qualified evidence. Perceived visibility needs a reviewed contrast/perception model, luminance/contrast/observer domain, independently usable evidence and uncertainty treatment. No such capability is qualified by this first diagnostic.
-
-For gallery, small-print, poster and distant-sign uses, verify immutable capture, same-scale physical proof geometry and actual output stage. These are scenarios within qualified envelopes, not one new chart per print size. Product accessibility, actual-device evidence and full consumer qualification remain separate. Public engine validation must stay runnable without private scenes.
-
-Release remains blocked for every missing scoped capability. Publish the reviewed geometry/diagnostic contract before integration. Keep #196 open until full scoped evidence and human review are complete; this protocol does not close it or silently defer required assessment.

package/docs/PRINT_PLANNING.md

@@ -1,75 +0,0 @@
-# Native-only Print planning
-
-Published in package/root API **1.1.0**, Print model **0.1.0**; retained in the **1.2.0** candidate. This standalone browser-safe API answers native sampling sufficiency and the minimum compatible printer-file raster. It generates no pixels or files. See [API conventions](API_STYLE.md), [staged geometry](PHYSICS_FOUNDATION.md), [processed output](PROCESSED_OUTPUT.md) and the [historical 1.1.0 release review](RELEASE_1_1_0.md).
-
-## Authority and units
-
-`source.kind: "native-retained"` declares an authoritative native grid and public capture ID. The planner validates geometry, not the truth of that declaration. Callers must bind it to the retained capture, never to a resized preview or processing enlargement. Existing `resolveCaptureGeometry()` owns orientation, native active capture, off-center output crop and optical-axis semantics. Available pixels are its **output crop dimensions**, before `outputRaster` resampling. Print planning changes no captured physics.
-
-`printedImage` is the flat physical image area: excludes paper, borders and wrap. Lengths explicitly use mm, cm, inches or metres. An inch is exactly 25.4 mm. PPI counts image samples per printed inch; printer DPI, encoded byte size, JPEG quality, paper and ICC behavior are separate. Actual delivery, resource limits and perceived/source-detail quality remain `unassessed`.
-
-## Angular convention and equation
-
-Viewing distance is independent of image size. At normal viewing of a flat image, a centered pixel of physical pitch `p` at distance `d` subtends `theta = 2 atan(p / (2d))`. In radians, `p_max = 2d tan(theta_max/2)` and `derived PPI = 25.4 / p_max` for millimetres. No small-angle approximation is substituted. Positive effective angles below 180 degrees are accepted mathematically; this broad geometry domain does not establish a visual-acuity model or useful guidance for extreme angles.
-
-Choose a convention explicitly:
-
-| Kind | Maximum effective pixel angle |
-| --- | --- |
-| `angular-pixel-pitch` | `maximumArcminutesPerPixel` |
-| `angular-stroke` | `strokeWidthArcminutes / samplesPerStroke` |
-| `angular-line-pair` | `periodArcminutes / samplesPerPeriod` |
-| `manual-ppi` | No angular criterion; explicit independent density |
-
-Stroke/period conventions divide the declared angular budget by the sample count by definition; they do not calculate the exact physical subdivision of a finite optotype on a flat image. That distinction matters for large angular extents. The exact centered-pixel equation then applies to the resulting per-pixel budget. Stroke sampling requires a positive integer sample count. A line-pair period includes a light and a dark stroke and requires at least two samples. A two-arcminute line pair with two samples is one arcminute per pixel; a one-arcminute period with two samples is half that pitch. Two samples are a declared sampling minimum, not a promise of preserved contrast. No acuity, universal 300 PPI, hidden safety multiplier or pixel-invisibility threshold is assumed. At 24 inches, a declared one-arcminute pixel criterion gives approximately 143.239447773 PPI. Angular guidance has `approximation` provenance because its use as a perceptual criterion is uncalibrated; the geometry envelope remains `calculated`. Manual PPI starts a new plan and certifies no previous angular criterion.
-
-## Integer policy, fit and sufficiency
-
-The first policy preserves the **exact retained native raster aspect ratio**. Reduce native dimensions `(W,H)` by their greatest common divisor to integer `(a,b)`. For continuous required counts `(Rx,Ry)`, choose `k = max(1, ceil(Rx/a), ceil(Ry/b))`, then output `(ka,kb)`. This is the minimum sufficient integer raster **within the declared exact-ratio family**, not the unconstrained independently rounded pair. Coprime crop dimensions can require retaining the whole native grid even for a low-density request; this limitation is explicit. No search or hidden stretch is performed.
-
-The physical printed-image ratio must agree with the confirmed crop within caller-declared `maximumRelativeAspectError` in `[0,0.01]`. Relative error is `abs((imageWidth/imageHeight)/(W/H) - 1)` and is returned. Zero demands exact represented equality. Nonzero tolerance explicitly accepts that small physical pitch difference between axes; per-axis achieved PPI and angular pitch expose it. Output resizing always uses one equal scale on both axes. An aspect mismatch returns `crop-confirmation-required`; choose and confirm a different crop or physical image size before replanning. The engine never silently crops or stretches.
-
-Compare the same minimum raster with native retained supply on **both axes**. `sufficient` describes only coverage under the declared criterion. A shortfall yields no recommendation. Never count upsampled pixels as capacity. The recommendation reports integer raster, achieved PPI/angle and equal native resampling scales, all in the same model/API result. Output may only downsample or preserve native resolution.
-
-## Lab constraints, alternatives and bounds
-
-Optional lab minimum/exact raster and minimum/exact PPI constrain delivery separately from angular guidance. All declared constraints are reconciled. Exact density must produce integral dimensions; exact raster must preserve native ratio, meet sampling/lab minima and not exceed either native axis. Contradiction or enlargement returns `provider-conflict` and no recommendation, even when native angular sufficiency is `sufficient`. The caller owns factual vendor requirements and downstream file validation; omission means unknown, not a universal lab default. Compatible lab minima may increase the minimum recommendation.
-
-Alternatives report an aspect-preserving maximum image size at current distance and, for angular plans, a minimum distance at current image size. They retain the criterion and native supply. These are **sampling alternatives**; lab constraints require a new full plan and may remain conflicting. Manual density has no farther-distance solution. Boundary alternatives round outward by adjacent binary64 values and recheck the integer policy (at most eight steps); unsupported numerical cases return a blocker. This is representational rounding, not relaxed sampling or a safety factor.
-
-`calculatePrintSizeLimit()` uses a reference plan and explicit distance policy. Fixed distance gives a finite conditional sampling bound. Proportional scaling of both image axes and distance leaves angular pixel pitch unchanged: the bound is `unbounded` if the reference meets the criterion, otherwise `no-positive-size`. Manual PPI supplies an independent finite bound. Size queries with lab constraints are explicitly `unsupported` in model 0.1.0; evaluate individual plans instead. No infinity sentinel is serialized and no finite printer/substrate bound is invented.
-
-Malformed, unknown, zero, nonfinite or invalid inputs throw existing typed configuration/scientific errors. Missing native authority gives `cannot-assess`. Positive finite requests whose converted lengths, pitches, densities, diagnostics or safe-integer output cannot be represented give `unsupported`. Calculations use binary64; conservative ceil can change an exact mathematical angular boundary by a ratio unit. Manual count calculations preserve directly supplied inches rather than round-trip through pitch. No global epsilon turns a failed sampling criterion into success. Results contain only finite numbers and null semantic absences.
-
-## Complete packed example
-
-```ts
-import { calculatePrintPlan, calculatePrintSizeLimit, type PrintPlanInput } from "@photivra/engine";
-const input: PrintPlanInput = {
-  source: { kind: "native-retained", captureId: "example-capture", geometry: {
-    imagingArea: { widthMm: 32, heightMm: 18 },
-    nativeRaster: { pixelWidth: 2560, pixelHeight: 1440 }, orientation: "landscape"
-  } },
-  printedImage: { width: 16, height: 9, unit: "inches" },
-  viewingDistance: { value: 24, unit: "inches" },
-  sampling: { kind: "angular-pixel-pitch", maximumArcminutesPerPixel: 1 },
-  fit: { kind: "confirmed-native-aspect", maximumRelativeAspectError: 1e-12 }
-};
-const plan = calculatePrintPlan(input).value;
-if (plan.status !== "ready" || plan.recommended?.raster.pixelWidth !== 2304 || plan.recommended.raster.pixelHeight !== 1296) throw new Error("Unexpected print raster");
-const bound = calculatePrintSizeLimit({ plan: input, viewingDistancePolicy: "proportional-to-image-size" }).value;
-if (bound.status !== "unbounded") throw new Error("Unexpected size bound");
-console.log(plan.native?.pixelsPerInch, plan.recommended, bound.status);
-```
-
-For untrusted requests use `parsePrintPlanInput()`. Calculation functions also parse/copy their inputs. No private assets, framework types, runtime dependencies, telemetry or source-plane reads are required. Preserve the returned capture/input/model/API binding when assembling output metadata; this API does not itself invoke the existing image exporter or attach serialization tags.
-
-## References and evidence
-
-- [NIST length units](https://www.nist.gov/pml/owm/si-units-length): unit conversion reference.
-- [Adobe image resolution](https://helpx.adobe.com/photoshop/desktop/crop-resize-transform/resize-adjust-resolution/printed-image-resolution.html): physical image dimensions versus pixel density.
-- [University of Iowa acuity testing](https://webeye.ophth.uiowa.edu/eyeforum/video/Refraction/Visual-Acuity-Testing/index.htm): optotype critical stroke detail is distinct from a whole optotype. This motivates explicitly declared conventions; it supplies no universal print sampling/quality guarantee.
-
-Implementation, prose and tests are original. References informed terminology and equations; no source tables, calibration, datasets or protected expression were incorporated. Independent tests cover the 160-PPI identity, high-precision angular reference, all orientations/off-center crop, ignored preview enlargement, unit and one-pixel boundaries, exact-ratio minimum search with fixed seed, lab conflicts, manual overrides, semantic bounds and invalid/extreme finite JSON. Human scientific/source/DCO review remains required before release. Advanced captured-detail/quality assessment remains separate (#196).
-
-The 1.2.0 acceptance audit additionally exercises stamp, book, home, gallery, billboard and half-mile dimensions/distances through the same source and explicit criterion, plus a heavy retained crop and recovery after invalid edits. These are geometric examples, not claims about eyesight, text readability, substrate or file-export readiness. The core #195 contract was delivered in PR #210 and published in 1.1.0; historical references to an unpublished geometry candidate are superseded. Actual UI/task/device and JPEG-delivery acceptance belongs to the consuming product and its exporter evidence, rather than this pixel-free planning API.

package/docs/PRINT_REGION_STATISTICS.md

@@ -1,38 +0,0 @@
-# Regional linear Print statistics — model and protocol 0.1.0
-
-These additive browser-safe protocols separate a registered processing difference from repeat-capture temporal sample variance. They extend #196's evidence work; they do not complete its acquisition, perception, subject/depth, motion or full release acceptance. The coherent detail diagnostic remains model 0.1.0 with its existing behavior.
-
-## Source and applicability
-
-Each frame uses the existing Print source, explicit scalar relative-linear luminance domain, actual represented raster, half-open oriented retained ROI, capture/representation/content/processing identity, evidence and noise-realization identity. Source/ROI parsing shares the coherent diagnostic boundary. Arrays must be dense and finite. The total request contains at most 65,536 scalar samples, including every repeat or both members of a pair. A noise ensemble has 2 to 256 frames. This is a work bound, not a device performance claim.
-
-The represented raster must preserve retained native aspect and cannot exceed either native axis. Native-stage rasters must match the retained native crop. Unqualified warps and non-linear/unknown domains are blocked. Registration compares the full parsed geometry, ROI and Print conditions conservatively. It does not resample or invent a correspondence. Different physical units expressing the same conditions must be normalized by the caller for a paired comparison. Insufficient native sampling or conflicting lab conditions remain visible in the returned Print plan; a sample statistic cannot repair delivery.
-
-Hashes, numeric provenance, acquisition stationarity and independent repeats remain caller declarations. Successful parsing/calculation never verifies file contents, decoding, a license or physical calibration. Results freeze copied inputs, retain engine/model identity and explicitly return unassessed acquisition, unquantified uncertainty and no overall verdict. Changing any source, ROI, processing, acquisition or viewing condition requires a new assessment identity downstream.
-
-## Paired processing difference
-
-`calculatePrintRegionDifference()` compares identical sample sites belonging to one immutable capture. Select either a declared deterministic reference (both noise IDs null) or the same explicitly named non-null noise realization. Distinct or unknown noise draws cannot be compared as processing-only change. No single noisy frame supplies a noise variance. A decoded-file comparison requires the pre-encode `post-resampling-linear` stage and the exact `post-encoding-decoded-linear` stage. The same representation ID with contradictory hash, stage or processing identity is blocked.
-
-For differences `d_i = after_i - before_i`, return signed mean, `sqrt(sum(d_i²)/N)` and maximum absolute difference in relative-linear luminance. This measures the net change between supplied representations; it does not automatically attribute it to JPEG compression, classify artifacts or establish visibility. Exact pre/post-encode artifact binding and independent decoder qualification remain external evidence obligations. Comparisons at different rasters require an independently registered reference on identical sample sites; this protocol does no resizing.
-
-An optional declared increasing reference signal range supplies below/above-range counts and maximum excursions for both representations separately. It can quantify known step-response undershoot/overshoot in an independently designed experiment. It is not an automatic halo detector. Existing source excursions remain visible. Range endpoints are neither sensor full well nor ADC/render clipping thresholds; boundary contact or excursions cannot establish a clipping mechanism. Color channels, gamut error, printer texture and natural-image quality remain unassessed.
-
-## Temporal repeat statistics
-
-`calculatePrintRegionNoise()` consumes a declared stationary scene and independent capture repeats at identical registered sites, geometry and processing stage. Each repeat has its own capture, representation and non-null noise-realization identity. Reused identities, stage/processing differences and missing noise IDs block the calculation. Equal bytes in separate repeats are allowed: zero noise and quantized repeated values are valid observations. IDs cannot themselves prove independence or stationarity.
-
-At each sample site compute the temporal mean and sample variance `sum((v_j - mean)²)/(n-1)`. Return those arrays, the mean of per-site temporal variances and its RMS, and the average site mean. The spatial variance of a textured image is deliberately not called temporal noise. Fixed-pattern variation, drift, correlations and nonstationarity need separate models. This protocol reports sample statistics, not an ensemble expectation, sensor SNR, a confidence interval or an uncertainty bound. It makes no Gaussian, Poisson or independent-pixel assumption for the statistic itself.
-
-Normalize each site's values by the maximum absolute magnitude. Calculate the mean of offsets from the first repeat and center those offsets before restoring units. A rounded large-DC mean must not add false variance. Compensated accumulation and hypot norms reduce avoidable overflow/cancellation. Reject nonzero inputs/differences lost by normalization, nonfinite restored statistics and nonzero variance/RMS underflow. Supported numeric results are finite; unsupported numeric ranges return no measurement rather than zero or a fabricated uncertainty. No epsilon changes a measurement or sampling verdict.
-
-## Independent qualification protocol and rights
-
-1. Use an independently authored Python standard-library oracle with exact rational arithmetic for finite paired signals and repeat statistics. Commit its inputs, expected values and SHA-256. The reference must not import the engine or compute expected values from runtime outputs.
-2. Cover positive/signed/zero levels, correlated spatial texture with zero temporal noise, asymmetric/directional step overshoot, tiny values, large DC with representably small fluctuations, same/different realization policies, malformed inputs, missing/mismatched stages and the total work bound. Numeric tolerances qualify arithmetic on that bounded domain only.
-3. Execute the existing production charge/readout and image-formation functions for additional backend evidence. Preserve raw/linear/SDR/JPEG stage identity. Seed schedules and sample counts must be predeclared. Compare realizations against an independent distribution/processing reference; a synthetic target name alone does not qualify an active backend.
-4. Measure repeat-count and quadrature convergence independently before any physical or statistical claim. Record reference/backend/analysis versions and hashes, ROI, units, domain, source dimensions, conditions and pass/fail/unassessed state in the capability ledger. Publish observed conformance separately from human scientific/source review.
-
-The [candidate review](PRINT_195_196_REVIEW.md#linearhigh-bit-electronic-readout-qualification) records actual public native RAW execution with an independently predicted 12-bit electronic reference. It separates storage/pre-ADC/digital clipping and signed read noise, and bounds decoded quantization effects without treating quantization as independent uniform noise. Its conditional neutral scalar encoding and declared electronic inputs do not establish physical photometry or sensor calibration.
-
-All new equations are elementary paired differences and sample statistics, authored independently. New procedural signals and reference code are Photivra draft material under Apache-2.0, subject to human scientific/source and DCO review. No external numeric curve, camera profile, dataset, runtime dependency or private scene is incorporated. The researched [castleCSF primary paper](https://pmc.ncbi.nlm.nih.gov/articles/PMC10996938/) and [upstream repository](https://github.com/gfxdisp/castleCSF) describe a possible later perceptual model; neither its code, coefficients nor observations are included by these protocols. A perceptual application needs its own license/source audit, stimulus/observer/luminance/area/eccentricity matching and independent validation. These statistics cannot supply that qualification.

package/docs/PROCESSED_OUTPUT.md

@@ -1,157 +0,0 @@
-# Processed camera output
-
-Release context: **package 1.2.0 candidate / root API 1.2.0**. Subsystem/model versions and dated introduction or measurement records below are independent historical identities; they are not distribution versions. See [developer navigation](DEVELOPERS.md) and [release contract](RELEASE_1_2_0.md).
-
-Root API 0.115.0 completes the bounded SDR post-capture handoff for #112.
-Production plan 0.6.0 adds explicit committed RAW processing. At introduction, package 0.6.0,
-POC 0.20.0, capture, RAW, color, correction and SDR schemas remain unchanged.
-This is the engine boundary used by preview and file consumers; integrating
-commercial UI controls and browser presentation belongs to the apps repository.
-
-## Entry points and domains
-
-| Authoritative input | Entry point | Semantic checks |
-| --- | --- | --- |
-| Scene-referred XYZ, virtual-camera channels or already transformed linear RGB | `calculateCaptureSdr()` | Exact #15 plane, profile/version, WB application history, channel order, reference white and raster binding |
-| Capture-bound linear plane with selected corrections | `calculateCaptureCorrectedSdr()` | Same color/WB checks, exact capture/lens/time/geometry state, compatible correction domains and explicit sampling/support policy |
-| Attached post-ADC native RAW | `calculateProcessedSensorRaw()` | Revalidated frame, explicit reconstruction kernels and coverage, registered RGB interpretation, resolved sensor gains, oriented crop and optional native correction |
-| RAW plus file metadata/encoder policy | `createPhotographicExportPair()` | Uses `calculateProcessedSensorRaw()` for JPEG pixels; preserves exact native RAW for DNG |
-| Committed production snapshot plus RAW policy | `createProductionImageFormationPlan()` | Optional `processedOutput: { outputStateId, processing }` binds attached capture, scene clock, seed, physical exposure, WB and available focus commits |
-
-There is no untyped "linear RGB" input or screenshot/canvas source. A caller
-with capture-linear data uses its declared #15 state. A RAW preview and paired
-JPEG use the same explicit `ProcessedSensorRawInput`: reconstruction,
-`ExportSensorColorProfile`, white-balance policy, `SdrRenderingProfile` and
-optional correction. Metadata and JPEG quantization are separate file choices.
-The returned arrays are high fidelity values before lossy JPEG packing, so a
-JPEG decoder is not expected to reproduce them bit for bit.
-
-The RAW result records input/output domains, color profile/evidence, WB policy
-and disposition, child reconstruction/rendering/correction envelopes, native
-DNG crop and processed output view. It owns copies of input values. Standalone
-results are ordinary owned values; a production plan deep-freezes its copy.
-Physical capture and actual display adaptation are explicitly unchanged.
-
-## Ordered processing
-
-RAW processing delegates to existing implementations:
-
-1. Reconstruct exact attached native post-ADC codes; preserve signed normalized
-   shadows and per-site capture/readout diagnostics.
-2. Apply the explicit approximate sensor-channel interpretation and resolved
-   sensor WB gains once; develop XYZ/linear sRGB/D65.
-3. Without correction, map the committed orientation and 1:1 output crop. With
-   correction, build the oriented full-active linear RGB view, then delegate
-   native optical correction, joint-valid retained view and orientation to the
-   capture correction executor.
-4. Apply rendering exposure, declared tone curve, explicit component gamut
-   handling, sRGB transfer encoding and quantization through the SDR renderer.
-5. Return output-referred encoding to the consumer. File packing and platform
-   display/view adaptation remain distinct downstream operations.
-
-The current correction executor supports its explicitly compatible RGB
-geometry/CA mapping followed by linear gain. It rejects unsupported domains or
-orders; it does not silently coerce reconstruction-adjacent channel correction
-into post-color RGB. Existing #118 mapping/resampling diagnostics retain crop,
-local Jacobian/stretch, support mask, interpolation/filter identity, gain/noise
-costs, residual assumptions and clipping. RAW correction intent is informational;
-DNG sensor codes are unchanged. Native prefiltering cannot be declared without
-an implemented source prefilter.
-
-Rendering controls never change aperture, shutter, ISO, focus, geometry,
-photo/dark charge, noise realization, physical saturation or RAW codes. Metering
-remains upstream: this API has no meter input, exposure resolver or feedback
-path. Consumers must identify whether histograms/zebras analyze capture data or
-these output-referred samples.
-
-## Encoding, clipping and future modes
-
-The existing SDR profile fully declares deterministic exposure EV, identity or
-positive per-channel Reinhard tone curve, clipping or rejection of out-of-range
-components, sRGB transfer, 8/16-bit nearest-ties-up quantization and no dither.
-Output explicitly records sRGB primaries, D65 and 80 cd/m² reference white.
-Component clipping is range handling, not a perceptual wide-gamut transform.
-See [SDR rendering](SDR_RENDERING.md) for equations and limitations.
-
-RAW preview supports both SDR bit depths. Baseline JPEG requires 8 bits and
-rejects a 16-bit profile; it never silently reduces the requested bit depth.
-Full-well/ADC flags stay in RAW samples, correction-gain clipping stays in the
-correction envelope, and rendering/tone/gamut counts stay in SDR diagnostics.
-Actual display saturation is unknown because display adaptation is external.
-
-HDR/PQ/HLG profiles fail validation. Future HDR encoding needs a separately
-versioned transfer/primaries/reference/mastering contract and explicit display
-semantics. Source float headroom does not become an HDR output declaration.
-Picture styles, restoration, sharpening and denoise remain future rendering
-choices, separately identified from sensor/optical quality.
-
-## Production plan and compatibility
-
-With a valid attached RAW policy and declared renderer support, the existing
-contract graph activates four executed downstream stages: `reconstruction`,
-`physical-orientation-transform`, `output-crop-resample`, `display-processing`.
-Each records model `processed-sensor-raw-sdr` 0.1.0 and attached frame identity.
-The plan retains the complete processed result, profile identity, requested
-output domain and approximate scientific status in its fingerprint. Scientific
-assurance includes the approximate processing component and unpropagated
-uncertainty, retaining color evidence and child results.
-
-Missing or mismatched processing records `processed-output-evaluation-blocked`;
-renderer stage declarations still gate each active stage. A request without an
-attachment preserves prior unsupported downstream behavior. Existing inputs
-remain valid; plan version and resulting fingerprints intentionally change.
-Serialized consumers must understand plan 0.6.0 and its optional result field.
-
-`outputStateId` explicitly binds numerical attached crop/raster policy to the
-snapshot's committed output identity; it is a caller assertion, not an invented
-geometry lookup. The RAW frame remains independently attached authoritative
-capture data. Matching IDs do not prove its upstream source transport. PSF,
-sensor-stack, photosite, charge, read-noise and ADC composition are still
-separate upstream work: their missing-stage blockers remain. An executed
-post-capture boundary does not make the whole production plan ready.
-
-## Bounded operating envelope
-
-Existing reconstruction permits at most 4,096 native sites, registered dense
-reference kernels, and complete required support. RAW output crop remains 1:1;
-source reconstruction must cover it, or the whole active region for correction.
-The color interpretation is explicit RGB-channel approximation, not sensor
-calibration. General resizing, streaming/native camera resolution, arbitrary CFA
-color models and external-editor qualification remain #16/#178 requirements.
-This boundary introduces no renderer/provider, file IO or network dependency.
-
-## Acceptance evidence
-
-| #112 requirement | Regression evidence |
-| --- | --- |
-| Tone/render EV cannot alter capture/noise/settings | `processed-sensor-raw.test.ts`, `raw-output-conformance.test.ts` |
-| WB applied once; preserved RAW intent; upstream balanced state | `capture-sdr.test.ts`, `photographic-export-correction.test.ts` |
-| Explicit image-state identity; reject unresolved/wrong domain | `capture-sdr.test.ts`, `sdr-rendering.test.ts`, `processed-sensor-raw.test.ts` |
-| Separate tone/gamut/transfer/quantization; deterministic SDR | `sdr-rendering.test.ts`, `processed-sensor-raw.test.ts` |
-| Primaries/reference white and explicit out-of-range policy | `sdr-rendering.test.ts`, `processed-sensor-raw.test.ts` |
-| RAW/correction/output clipping remain distinct | `raw-output-conformance.test.ts`, `capture-corrected-sdr.test.ts`, `processed-sensor-raw.test.ts` |
-| Metering remains pre-display | No processing API calls the upstream meter; `metering-equipment-integration.test.ts` preserves its separate domain |
-| Same rendering intent for preview/JPEG without screenshots | `processed-sensor-raw.test.ts`, four-orientation/WB checks in `photographic-export-correction.test.ts` |
-| HDR remains distinct; no implicit SDR reinterpretation | Profile rejection tests in `sdr-rendering.test.ts`, `processed-sensor-raw.test.ts` |
-| Correction domains/support/costs and immutable plan binding | `capture-corrected-sdr.test.ts`, `production-image-formation-plan.test.ts` |
-
-RAW/linear fixtures use the #130 canonical camera/seed through documented tiny
-owned derived variants; test pixels and ideal color profiles are synthetic,
-not measured/calibrated scene truth. Acceptance demonstrates the declared bounded
-post-capture foundation, not Adobe compatibility or complete physical rendering.
-
-This contribution independently composes existing Photivra APIs; it introduces
-no new scientific equation, third-party code/data, look assets or dependency.
-AI-assisted draft requires substantive owner review and contribution-specific
-DCO certification before merge. External editor/high-resolution acceptance and
-upstream physical activation retain their existing issue owners.
-
-## Executed upstream production handoff
-
-Plan 0.7.0 additionally supports `environmentCapture.processing`. Its
-reconstruction policy omits `rawFrame`: the plan supplies only the exact RAW
-returned by its executed source-to-ADC pipeline. This route cannot be combined
-with `processedOutput` or an independent physical scene sample. Existing
-attached-RAW plan inputs and their conservative origin limitations remain valid.
-See [production environment capture](PRODUCTION_ENVIRONMENT_CAPTURE.md) for
-binding, replay, stage activation and migration details.