@photivra/engine 1.5.0 → 2.0.0

package/SECURITY.md

@@ -1,55 +1,64 @@
 # Security
 
-Please do not open a public issue containing vulnerability details.
+Please do not open a public issue that contains vulnerability details.
 
 ## Supported versions
 
-The published 1.0.0 release established the 1.x root-package compatibility line. Security fixes target the current maintained development/release line; older snapshots and pre-1.0 releases should not be assumed to receive fixes. The current 1.0.1 candidate is not yet published. Node runtime support follows [NODE_SUPPORT.md](NODE_SUPPORT.md), covering maintained LTS lines plus Current; older/EOL runtimes are not qualified.
+The published 1.0.0 release started the 1.x root-package compatibility line. The current release is **1.5.0**, published on October 7, 2026 (see [CHANGELOG.md](CHANGELOG.md)).
+
+Security fixes target the current maintained development and release line. Do not assume that older 1.x releases, snapshots or pre-1.0 releases will receive fixes.
+
+Node runtime support follows [NODE_SUPPORT.md](NODE_SUPPORT.md): maintained LTS lines plus Current. Older and end-of-life runtimes are not tested.
 
 ## Reporting a vulnerability
 
-For the public GitHub repository, use GitHub's private vulnerability reporting flow ("Report a vulnerability" on the Security tab) when available.
+Use GitHub's private vulnerability reporting ("Report a vulnerability" on the repository's Security tab) when it is available.
 
-Private vulnerability reporting must be enabled before the repository is made public. If that private reporting entry point is unavailable, contact the repository owner privately before disclosing exploit details.
+The repository is public. This policy is only complete once private vulnerability reporting is enabled. As of October 11, 2026 it is not yet enabled. If that entry point is unavailable, contact the repository owner privately before you disclose exploit details.
 
-Please include, when relevant:
+Where relevant, please include:
 
-- affected commit/package/API version;
+- the affected commit, package version or API version;
 - reproduction steps or a minimal proof of concept;
-- impact and preconditions;
-- whether the issue affects the browser-safe root package, repository-local POC API tooling, development tooling, or the supply chain.
+- the impact and any preconditions;
+- which part is affected: the browser-safe root package, the repository-local POC (proof-of-concept) API tooling, development tooling, or the supply chain.
 
 ## Security boundaries
 
-The root `@photivra/engine` package is a calculation library. Its browser-facing dependency graph is checked in CI to prevent Node-only modules or the POC HTTP transport from becoming reachable through the root export.
+The root `@photivra/engine` package is a calculation library. CI checks its browser-facing dependency graph, so Node-only modules and the POC HTTP transport cannot become reachable through the root export.
 
-The repository-local `src/api` code is a separate Node-only proof-of-concept development server. It is not exported by or included in the published `@photivra/engine` package:
+The repository-local `src/api` code is a separate, Node-only proof-of-concept development server. The published `@photivra/engine` package does not export or include it. Note that:
 
-- it is unauthenticated;
-- it binds to loopback/localhost by default;
+- it has no authentication;
+- it binds to loopback (localhost) by default;
 - it is not a production hosting recommendation;
 - CORS is a browser policy, not authentication or authorization;
-- exposing it on a non-loopback interface requires separate production-grade protection that this repository does not provide.
+- exposing it on a non-loopback interface needs separate production-grade protection, which this repository does not provide.
 
 ## Release and publishing controls
 
-The npm release workflow is designed so verification/build tooling does not receive npm publishing identity:
+The npm release workflow keeps the npm publishing identity away from verification and build tooling:
+
+- Release tags must be protected, match the package version, and point at the current `main` commit.
+- GitHub must report the `main` branch as protected before a publish is allowed.
+- Verification, coverage, build and package creation run in a job without `id-token: write`.
+- Only the small final publish job gets OIDC permission.
+- The verified tarball moves between jobs as a short-lived Actions artifact. Its SHA-256 is checked before publication.
+- GitHub Actions are pinned to immutable commit SHAs.
+- Checkout credentials are not kept for later CI steps.
+- Dependency installation uses the lockfile and `--ignore-scripts`.
+- The public package has no runtime npm dependencies.
+
+Repository administrators must keep release tags and the default branch protected. The publish workflow fails closed if either protection is missing.
 
-- release tags must be protected, match the package version, and point at the current `main` commit;
-- the `main` branch must report as protected through GitHub before a publish is allowed;
-- verification, coverage, build, and package creation run in a job without `id-token: write`;
-- only the minimal final publish job receives OIDC permission;
-- the verified tarball is transferred between jobs as a short-lived Actions artifact and checked against its SHA-256 before publication;
-- GitHub Actions are pinned to immutable commit SHAs;
-- checkout credentials are not persisted into later CI steps;
-- dependency installation uses the lockfile and `--ignore-scripts`;
-- the public package has no runtime npm dependencies.
+For the strongest npm setup, also:
 
-Repository administrators must keep release tags and the default branch protected; the publish workflow fails closed if either protection is absent. For the strongest npm posture, also use a protected GitHub deployment environment in the npm trusted-publisher configuration and disable traditional token-based publishing after trusted publishing is verified.
+- use a protected GitHub deployment environment in the npm trusted-publisher configuration; and
+- disable traditional token-based publishing once trusted publishing is verified.
 
 ## Development rules
 
-- Never commit credentials, API keys, tokens, private keys, private datasets, or proprietary calibration material.
-- Keep runtime dependencies minimal; the root package currently has no runtime npm dependencies.
-- Dependencies, models, data, and copied/adapted material require explicit license/provenance review before adoption.
-- Treat material dependency, secret, supply-chain, unsafe transport, and browser-boundary findings as release blockers.
+- Never commit credentials, API keys, tokens, private keys, private datasets or proprietary calibration material.
+- Keep runtime dependencies minimal. The root package currently has no runtime npm dependencies.
+- Dependencies, models, data, and copied or adapted material need an explicit licence and provenance review before adoption.
+- Treat material findings about dependencies, secrets, the supply chain, unsafe transport or the browser boundary as release blockers.

package/THIRD_PARTY.md

@@ -20,24 +20,145 @@ This file records direct development and CI dependencies intentionally used by t
 
 Node built-in modules are used only by development tooling and the repository-local POC API; that API is excluded from the published package and the built-ins are not third-party dependencies.
 
+`src/sensor/stochastic-seed.ts` independently implements the MurmurHash3_x86_32 algorithm and its `fmix32` finalizer (Austin Appleby). The upstream `MurmurHash3.cpp` header states the algorithm "is placed in the public domain" and disclaims copyright. The SMHasher test suite that contains it is a separate work: its README says "SMHasher is released under the MIT license". No SMHasher or MurmurHash3 source file is vendored or copied. `test/sensor-raw-noise-independence.test.ts` reimplements, in its own code, SMHasher's verification procedure (keys of 0–255 bytes hashed with seed 256 − i, then the hash of those hashes) and compares the result with the published MurmurHash3_x86_32 verification value 0xB0F57EE3, a published fact. Test vectors earlier copied from a Stack Overflow answer (CC BY-SA 3.0) were removed.
+
+`src/optics/longitudinal-chromatic-aberration.ts` uses three physical constants: the Fraunhofer d (helium, 587.5618 nm), F (hydrogen, 486.1327 nm) and C (hydrogen, 656.2725 nm) spectral-line wavelengths used to define the Abbe number (as tabulated in SCHOTT Technical Information TIE-29, *Refractive Index and Dispersion*, 2023, free; also the reference wavelengths of ISO 7944). They are factual measured constants of nature, not a copied dataset or table; no glass catalogue data is included and refractive index and Abbe number are caller inputs. The 2.0 projection, distortion, Zernike/Seidel, vignetting, polarizer and haze models are independent implementations of published equations cited in `docs/PHYSICS_FOUNDATION.md` and `docs/PSF_FOUNDATION.md`; they contain no third-party code or numeric tables.
+
 This inventory does not replace a transitive dependency/SBOM review before a release. New runtime dependencies, scientific datasets, model weights, or calibration material require explicit provenance and license review.
 
+## Pending licence and source reviews
+
+These human reviews are **pending**. This inventory records them; it does not complete them. Each is described in full in its section below.
+
+- castleCSF-derived contrast reference (`src/output/print-contrast-reference.ts`): human scientific/source/license review pending.
+- ReportLab/pypdf offline PDF test-artifact tools: substantive human source review pending.
+- DNG/TIFF and JPEG format references: human provenance/license review required before release.
+- Transitive dependency/SBOM review: required before each release; this inventory does not replace it.
+- Colorimetry published constants (`src/color/`): human source/licence review pending. See [Colorimetry published constants and excluded datasets](#colorimetry-published-constants-and-excluded-datasets).
+
+## Licence summaries (prepared for owner sign-off)
+
+Prepared on 2026-10-11 from local files only (repository files, `package-lock.json` and locally installed package metadata). These are factual summaries for the owner to sign off; they are **not** completed reviews, and every item above stays pending until the owner signs off at production release. "Not verified" means the fact could not be checked locally.
+
+### castleCSF-derived contrast reference
+
+- **Declared licence:** MIT, from the retained upstream text `docs/licenses/castleCSF-MIT.txt` (revision `f4b0b722af83001d7af979281e06ca642d36e4e8`).
+- **Copyright holder:** "Copyright (c) 2023 Graphics and Displays group - University of Cambridge" (from that file).
+- **Permissions:** MIT permits commercial use, modification, redistribution and sublicensing.
+- **Obligations:** the copyright and permission notice must be included in all copies or substantial portions. It is currently kept in `docs/licenses/castleCSF-MIT.txt`, in `NOTICE` and in the header of `src/output/print-contrast-reference.ts`. `NOTICE` and `docs` are listed in the published package `files`.
+- **Concerns:** whether the upstream repository holds model or parameter material under other terms (paper, datasets) is not verified locally; this summary covers only the retained MIT text. The licence summary does not cover the separate scientific/source review.
+
+### ReportLab / pypdf offline PDF test-artifact tools
+
+- **Declared licence:** ReportLab: "BSD license" (METADATA; classifier "OSI Approved :: BSD License"), with a BSD-3-Clause-style `LICENSE` file. pypdf: `License-Expression: BSD-3-Clause` with a matching `LICENSE` file.
+- **Copyright holder:** ReportLab: "Copyright (c) 2000-2024, ReportLab Inc." (LICENSE; METADATA says 2000-2025). pypdf: "Copyright (c) 2006-2008, Mathieu Fenniak", with contributions copyright Ashish Kulkarni (2007) and Steve Witham (2014).
+- **Permissions:** both licences permit commercial use, modification and redistribution in source and binary form.
+- **Obligations:** keep the copyright notice, conditions and disclaimer on redistribution, and do not use the contributors' names for endorsement. Neither tool is vendored or redistributed here, so no notice is currently owed.
+- **Concerns:**
+  - The installed versions are ReportLab 5.0.1 and pypdf 6.17.0. The versions recorded for the committed artifact (ReportLab 4.4.9, pypdf 6.10.0) are not installed locally, so their exact licence files are not verified.
+  - The ReportLab distribution also bundles font files, including DarkGarden (with a GPL copying file) and Vera. The committed `output/pdf/print-proof-reference.pdf` contains no `FontFile` entries and declares only `/BaseFont /Helvetica`, so no bundled font program is embedded (checked locally).
+
+### DNG/TIFF and JPEG sample provenance
+
+- **Declared licence:** project Apache-2.0 (`LICENSE`, `package.json`). There are 26 tracked `.dng`/`.jpg` files under `test/fixtures/paired-export-acceptance`, `test/fixtures/producer-export-acceptance`, `test/fixtures/print-detail/jpeg` and `docs/validation/native-raw-print-2026-10-04`. Their READMEs and manifests describe them as Photivra-owned synthetic outputs of this repository's own encoders. The generators are `scripts/generate-photographic-export-fixtures.mjs`, `scripts/generate-producer-export-acceptance.mjs` and `scripts/generate-native-print-jpeg.mjs`. The adjacent `srgb.icc` is written by the engine's own `createSrgbIccProfile()`.
+- **Copyright holder:** "Copyright 2026 William Shackelford" (`NOTICE`).
+- **Permissions:** Apache-2.0 permits commercial use, modification and redistribution.
+- **Obligations:**
+  - Apache-2.0 requires keeping `LICENSE` and `NOTICE`, and marking modified files.
+  - `NOTICE`, `README.md` and the DNG writer and reader sources (`src/capture/photographic-export.ts`, `src/capture/native-raw-dng.ts`, `src/capture/dng-import.ts`) carry "This product includes DNG technology under license by Adobe.", the exact notice the Adobe DNG patent licence requires in source code and documentation.
+- **Concerns:**
+  - **Adobe DNG patent licence (verified 2026-10-17).** The licence text was read on Adobe's Digital Negative page (<https://helpx.adobe.com/camera-raw/desktop/dng-and-file-formats/digital-negative.html>, section "Digital Negative (DNG) Specification patent license"; the 1.7.1.0 specification PDF itself carries no licence). It grants all individuals and organizations a worldwide, **royalty-free**, nonexclusive right under Adobe's essential patent claims to make, use and distribute software that **reads or writes** DNG files. Conditions: include the notice above in source code and documentation; Adobe may revoke the grant from a licensee that brings a DNG-related patent action against Adobe. Users receive the grant directly from Adobe, so nothing needs to be sublicensed under Apache-2.0. It covers only Adobe's DNG-essential patent claims, not referenced technologies (TIFF, JPEG, Exif, ICC, XMP) or other formats. This is a document check, not legal advice. The retrieval record [`docs/licenses/adobe-dng-patent-license-record.txt`](https://github.com/Photivra/photivra/blob/main/docs/licenses/adobe-dng-patent-license-record.txt) gives the URL, retrieval date, page SHA-256, the exact notice and a summary. It is not a copy of the licence, because Adobe's Terms of Use do not clearly allow copying text from its websites.
+  - The `test/fixtures/print-detail/jpeg` files are written by `scripts/generate-print-detail-jpeg.mjs`, which builds and runs `scripts/generate-print-detail-jpeg.ts` with the repository's own `createPhotographicExportPair()` and `test/helpers/print-detail-jpeg-fixture.ts`. Their manifest has the fields that script writes and records `engineCandidate` 1.1.0.
+  - Provenance comes from the repository's own records; the files were not regenerated byte for byte in this pass.
+
+### Per-release transitive dependency / SBOM review
+
+- **Declared licence:** for the current `package-lock.json` (168 package entries), the declared licence counts are MIT 125, Apache-2.0 15, ISC 7, BSD-2-Clause 6, BSD-3-Clause 2, BlueOak-1.0.0 1 and MPL-2.0 12. All 12 MPL-2.0 entries are `lightningcss` and its platform binaries, marked `dev`. The single BlueOak-1.0.0 entry is `minimatch`, also `dev`. The root package declares no runtime `dependencies`.
+- **Copyright holder:** per package; not compiled in this pass (not verified).
+- **Permissions:** every declared licence is on the repository allowlist, and each permits commercial use, modification and redistribution.
+- **Obligations:** no third-party npm code is in the published package, so redistribution notices arise only if that changes. MPL-2.0 file-level copyleft would apply only if `lightningcss` files were modified and distributed.
+- **Concerns:**
+  - The figures come from declared lockfile metadata, not licence texts.
+  - The review must be repeated against each release's exact lockfile.
+  - The GitHub Action licences in the table above are not verified locally.
+
+## Colorimetry published constants and excluded datasets
+
+The colorimetry modules in `src/color/` (see [docs/COLORIMETRY.md](https://github.com/Photivra/photivra/blob/main/docs/COLORIMETRY.md)) are independently written from published equations. They contain only short factual numeric constants taken from those equations. No third-party source code, table, figure or prose is copied, and no runtime dependency is added.
+
+| Constants | Source | Licence / basis for use |
+| --- | --- | --- |
+| 28 coefficients of the engine's own multi-lobe CIE 1931 CMF fit (`color-matching-functions.ts`) | Fitted by Photivra with `scripts/fit-cie-1931-cmf.mjs` to the CIE 1931 2° table, DOI 10.25039/CIE.DS.xvudnb9b (CIE, CC BY-SA 4.0). The model form, a sum of piecewise Gaussians, follows the idea in Wyman, Sloan & Shirley (2013), JCGT 2(2); none of that paper's coefficients or text are used. | Fit-time use only: the script downloads the table into a temporary directory outside the repository, checks its SHA-256 and deletes it. No CIE value is stored in the repository, the package, the tests or the script's output. The committed coefficients are our own least-squares result; 28 numbers cannot reproduce the 1,413-value table (maximum error 0.022). Attribution to the CIE dataset is given here and in `docs/COLORIMETRY.md`. Replaced the Wyman et al. coefficients by owner decision (2026-10-17). |
+| Daylight-locus polynomial and M₁/M₂ coefficients; illuminant A formula constants; CIELAB, CIE94 and CIEDE2000 formula constants (`illuminants.ts`, `color-difference.ts`) | CIE 15:2018 (daylight and illuminant A constants; values checked against the free CIE datasets); CIELAB as in W3C CSS Color 4; CIE94 as stated in Wikipedia, "Color difference" (secondary source; the primary CIE 116-1995 is not free); Sharma, Wu & Dalal (2005), also CIE 142-2001 | Coefficients of standardized equations, used as factual constants. |
+| McCamy CCT cubic | McCamy (1992), Color Res. Appl. 17(2) | Published equation coefficients. |
+| Bradford and CAT16 matrices (`chromatic-adaptation.ts`) | Lam (1985) / ICC.1:2010 Annex E; CAT16: Li et al. (2016), IS&T CIC24, Eq. (15), doi:10.2352/ISSN.2169-2629.2017.32.208 (free; checked 2026-10-17 to match the engine; journal version Li et al. 2017) | Published 3×3 model constants. CAT02, the Hunt–Pointer–Estévez matrix and the CIECAM02 degree-of-adaptation formula were removed from 2.0 (owner decisions, 2026-10-17) because no confirmed free source prints them. |
+| Primaries and white points; BT.709 and BT.1886 constants (`rgb-color-spaces.ts`) | ITU-R BT.709-6, BT.1886, BT.2020-2; W3C CSS Color 4 (`srgb`, `display-p3`); also IEC 61966-2-1, SMPTE EG 432-1 | Standardized numeric constants; every value is available from the freely published ITU-R and W3C documents. |
+| h, c, k | BIPM SI Brochure (2019) | Exact SI defining constants (facts). |
+| Standard output sensitivity S = 10/H, camera-equation constant 0.65 and the 18 % grey reference, K_m = 683 lm/W (`src/facade/`) | CIPA DC-004-2020 (free); BIPM SI Brochure, definition of the candela | Standardized scalar constants used as facts. The capture facade's charts (slanted edge, Siemens star, step wedge, grey ramp, checkerboard, point grid) are engine-authored analytic patterns; the slanted edge only follows the ISO 12233 geometry (a few degrees of slant, 4:1 contrast) and reproduces no chart artwork or data. |
+
+The following datasets are deliberately **excluded**:
+
+- **CIE tabulated datasets.** This covers the CIE 1931/1964 CMFs, the daylight components S₀/S₁/S₂ and the standard illuminant tables. They were verified on 2026-10-16 from the CIE dataset metadata (for example DOI 10.25039/CIE.DS.xvudnb9b and `CIE_illum_Dxx_comp.csv_metadata_v2.json`), which declare **CC BY-SA 4.0**. ShareAlike would bind adaptations, and this is not compatible with Apache-2.0-only distribution. The API accepts caller-supplied tables instead.
+- **ColorChecker or other chart reflectances.** Their licence is unclear, so they are not included. Reflectances are supplied by the caller.
+
+The tests assert no values taken from CIE tables, and no CIEDE2000 published test pairs (owner decision, 2026-10-17; the Sharma et al. data file carries no licence). They use internal consistency, normalization, round trips and values computed in the test from Planck's law, the daylight formula and the CIEDE2000 definitions. They still assert standard luminance coefficients and the published Bradford matrix as cited facts.
+
+**Removed by owner decision (2026-10-17).** Two third-party coefficient sets were removed from the shipped code: the Wyman, Sloan & Shirley (2013) CMF coefficients (paper CC BY-ND 3.0), replaced by the engine's own fit above, and the Planckian-locus cubic-spline coefficients of Kang et al. (2002, J. Korean Phys. Soc. 41(6); also US 7,024,034, recorded as lapsed in 2018), replaced by Planck's law integrated against the engine's CMFs. Neither set nor the patent text remains in `src/`.
+
+## Image-processing published parameters
+
+The processing operators in `src/processing/` and the built-in Bayer kernels in `src/sensor/raw-reconstruction.ts` (see [docs/PROCESSING.md](https://github.com/Photivra/photivra/blob/main/docs/PROCESSING.md)) are independently written from published algorithm descriptions. They contain only short factual parameters. No third-party source code (including GPL demosaicing implementations), table, figure, image or prose is copied, and no runtime dependency or test image is added.
+
+| Parameters | Source | Basis for use |
+| --- | --- | --- |
+| Burt–Adelson generating kernel [1, 4, 6, 4, 1]/16 (a = 0.375) | Burt & Adelson (1983) | Published equation parameter. |
+| Well-exposedness σ = 0.2; key 0.18; range σ 0.4 and spatial σ 2% defaults | Mertens et al. (2007); Reinhard et al. (2002); Durand & Dorsey (2002) | Published default parameters. |
+| Gain-compensation σ_N ≈ 10/255, σ_g = 0.1 | Brown & Lowe (2007) | Published parameters, rescaled to normalized intensity. |
+
+The Malvar–He–Cutler demosaic kernels and their parameters, and the BT.2408 HDR reference-white and BT.2100 quantization constants used only by the PQ/HLG encoders, were removed from 2.0 (owner decision, 2026-10-17); see the patent review below.
+
+## Patent review of 2.0 algorithms (public-record check, 2026-10-17, not legal advice)
+
+| Algorithm | Patent record found | Finding |
+| --- | --- | --- |
+| Non-local means denoising | US 8,253,825 | Lapsed for unpaid maintenance fees; the EP counterpart was withdrawn. |
+| Durand–Dorsey bilateral tone mapping | US 7,146,059 (MIT) | Expired February 8, 2025. |
+| Burt–Adelson Laplacian pyramid (Sarnoff patents) | Sarnoff pyramid patents | Expired. |
+| Focus stacking by pyramid fusion | US 5,325,449; IBM US 9,196,027 | US 5,325,449 expired. US 9,196,027 claims capture control, which the engine does not do. |
+| Synthetic film grain | Thomson film-grain family | Lapsed. |
+| AHD demosaic, bilateral filter, Reinhard tone mapping, Brown–Lowe gain compensation | None found | No patent found. |
+| HDR bracket merge | Disney US 9,275,445 (in force to 2034) | Claims align-then-merge HDR. The engine's merge does no alignment and requires pre-aligned input (`docs/PROCESSING.md`). |
+| Exposure fusion pyramid blending | CyberLink US 8,885,976 (in force to 2034) | Claims a specific merged-pyramid variant. The engine uses standard Mertens et al. (2007) Laplacian-pyramid fusion and does not use that variant (note also in `docs/PROCESSING.md` and `src/processing/tone-mapping.ts`). Public-record note, not legal advice. |
+| Malvar–He–Cutler demosaic | Microsoft US 7,502,505 (in force to about January 25, 2027) | Claim 1 closely matches the method, so it was removed from 2.0 (owner decision, 2026-10-17). It may return after the patent expires. |
+| PQ transfer function (SMPTE ST 2084, ITU-R BT.2100) | Dolby: SMPTE ST 2084 patent declaration, option B1 (free of charge, with reciprocity), July 30, 2015, and ITU-R BT.2100 declaration option 2.1; US 11,887,560 in force to about 2032 | Only free-of-charge licence-on-request declarations, not a licence or non-assert: a licence must still be requested. Removed from 2.0 by owner decision (2026-10-17). |
+| HLG transfer function (ITU-R BT.2100, ARIB STD-B67) | BBC: free-of-charge declarations to the ITU and SMPTE. NHK: only a 2001 general RAND statement. Thomson: RAND declaration PCT/EP16/051552 on BT.2100. ARIB STD-B67 lists no essential patents | Licence-on-request (free of charge or RAND) declarations, not licences or non-asserts. Removed from 2.0 by owner decision (2026-10-17). |
+| CAT02 and CAT16 chromatic-adaptation matrices | None found | No patent found claiming the CAT02 or CAT16 matrix (USPTO full-text; Google Patents partial); the CIE attaches no usage condition; the search outside the US was partial. |
+
 ## Print contrast numerical model material
 
 The original scalar adapter in `src/output/print-contrast-reference.ts` uses numerical equations/parameters from [castleCSF revision f4b0b722af83001d7af979281e06ca642d36e4e8](https://github.com/gfxdisp/castleCSF/tree/f4b0b722af83001d7af979281e06ca642d36e4e8): `matlab/CSF_castleCSF.m`, `CSF_stelaCSF_lum_peak.m`, `CSF_castleCSF_chrom.m` and `CSF_base.m`. The upstream code/model material is MIT-licensed, copyright (c) 2023 Graphics and Displays group - University of Cambridge. The exact license is preserved at `docs/licenses/castleCSF-MIT.txt` and its notice is retained in `NOTICE` and adapter source. New TypeScript/reference code is distributed under the project Apache-2.0 terms while retaining the MIT notice for upstream numerical material.
 
-No upstream observational CSV, paper text/figure/table, color-matching dataset or runtime dependency is incorporated. The model's presence does not certify camera, print, observer or natural-image visibility applicability. [The model/protocol](docs/PRINT_CONTRAST_REFERENCE.md) records the restricted envelope, independent numerical evaluation and pending human scientific/source/license review. The root still declares no runtime npm dependencies.
+No upstream observational CSV, paper text/figure/table, color-matching dataset or runtime dependency is incorporated. The model's presence does not certify camera, print, observer or natural-image visibility applicability. [The model/protocol](https://github.com/Photivra/photivra/blob/main/docs/PRINT_CONTRAST_REFERENCE.md) records the restricted envelope, independent numerical evaluation and pending human scientific/source/license review. The root still declares no runtime npm dependencies.
 
 
 ## Optional offline physical-proof tools
 
+The optional repository-only QA scripts `scripts/verify-photographic-export-fixtures.py` and `scripts/verify-producer-export-acceptance.py` load an installed LibRaw (LGPL-2.1 or CDDL-1.0) dynamically through its C API. Nothing from LibRaw is copied or distributed, and the scripts are not part of the package.
+
 The owned PDF geometry reference is generated with ReportLab 4.4.9 and independently inspected with pypdf 6.10.0. Their installed distribution license files were reviewed as BSD-3-Clause-style terms (ReportLab metadata calls its license BSD; pypdf declares BSD-3-Clause). These are optional offline test-artifact tools, not runtime/npm dependencies. No library source, binary or embedded font program is vendored. The PDF preserves existing owned JPEG streams and uses the PDF standard Helvetica font declaration; its DeviceRGB appearance and actual printing remain unqualified. Generator/parser versions and artifact hashes are retained in the candidate evidence record. Substantive human source review remains pending.
 
 ## Automated license policy
 
-The bounded DNG/TIFF and baseline JPEG encoders are independently authored.
-No Adobe SDK, external encoder source, default quantization/Huffman tables,
-calibration dataset or runtime dependency is incorporated. Numeric test profiles
+The bounded DNG/TIFF and baseline JPEG encoders, the DNG/TIFF-EP reader, the
+lossless JPEG (T.81 Annex H) decoder and the PNG/zlib/DEFLATE encoder are
+independently authored. No Adobe SDK, external encoder or decoder source, default
+quantization/Huffman tables, calibration dataset or runtime dependency is
+incorporated. Only factual identifiers from the standards are used: tag numbers,
+field types, marker codes, PNG chunk layouts, the sRGB gAMA/cHRM values the PNG
+specification prescribes, H.273 code points, RFC 1951 fixed-code and length/distance
+base tables, and the Exif 2.32 default values (72 dpi, `0100`, `0232`, Y Cb Cr).
+The 64 JPEG DCT cosine constants are correctly rounded values of
+cos((2x+1)uπ/16), computed by the project; they are mathematical facts. Numeric test profiles
 and custom coding tables are owned synthetic fixtures, not camera calibration.
 
 Format references:
@@ -48,6 +169,29 @@ Format references:
 - JFIF: https://www.w3.org/Graphics/JPEG/jfif3.pdf
 - Adobe XMP: https://developer.adobe.com/xmp/docs/xmp-specifications/
 - CIPA Exif: https://www.cipa.jp/std/documents/e/DC-X008-Translation-2019-E.pdf
+- TIFF 6.0: https://www.itu.int/itudoc/itu-t/com16/tiff-fx/docs/tiff6.pdf
+- PNG Third Edition (W3C Recommendation 24 June 2025): https://www.w3.org/TR/png-3/
+- zlib (RFC 1950) and DEFLATE (RFC 1951): https://www.rfc-editor.org/rfc/rfc1950, https://www.rfc-editor.org/rfc/rfc1951
+- ITU-T H.273 code points: https://www.itu.int/rec/T-REC-H.273
+
+RAW development and tone-mapping references (2.0; published equations and
+factual constants only, independently implemented; no code or data copied):
+
+- DNG 1.7.1.0 tag definitions (WhiteLevel, BlackLevel/ActiveArea phase,
+  AsShotNeutral, ForwardMatrix1, BaselineExposure, NoiseProfile, AnalogBalance):
+  the DNG specification above.
+- EMVA 1288 Release 4.0, saturation point and photon-transfer noise model:
+  https://www.emva.org/standards-technology/emva-1288/
+- Reinhard, Stark, Shirley & Ferwerda (2002), "Photographic tone reproduction
+  for digital images", ACM SIGGRAPH, eq. 3 and 4.
+- Naka & Rushton (1966), J. Physiol. 185:536-555; Reinhard & Devlin (2005),
+  "Dynamic range reduction inspired by photoreceptor physiology", IEEE TVCG 11(1).
+- Guo, Cheng & Hu (2010), "Correcting over-exposure in photographs", CVPR
+  (highlight desaturation concept for the engine-defined `reconstruct` mode).
+- dcraw manual, `-H 0` "clip all highlights to solid white" (documented
+  behaviour only; no dcraw code used): https://www.dechifro.org/dcraw/dcraw.1.html
+- Bradford cone matrix (Lam 1985), already used by the ICC serializer, now also
+  for ForwardMatrix1.
 
 The DNG patent-license notice appears in `NOTICE` and exporter source. These
 references do not authorize copying SDK code or scientific datasets. Human

package/dist/camera/equivalent-focal-length.d.ts

@@ -1,11 +1,12 @@
 /**
- * Module boundary and integration notes.
- * Calculates conventional 35 mm-equivalent focal length from physical focal length and the effective
- * active-capture diagonal. The physical focal length remains unchanged and continues to be the optical
- * input for projection and depth-of-field calculations. Focus distance and later digital/output crops
- * are deliberately excluded from this conventional equivalence quantity.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Conventional 35 mm-equivalent focal length, from the physical focal length and the diagonal of the
+ * active capture area.
+ *
+ * The physical focal length is not changed. It stays the optical input for projection and
+ * depth-of-field calculations. Focus distance and later digital or output crops are deliberately left
+ * out of this conventional equivalence.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { type CalculationResult } from "../core/calculation-result.js";
 import { type SensorImagingArea } from "../sensor/sensor-geometry.js";
@@ -28,16 +29,14 @@ export interface EquivalentFocalLength35Mm {
     basis: "diagonal";
 }
 /**
- * Calculates conventional 35 mm-equivalent focal length from physical focal
- * length and the effective active-capture diagonal.
+ * Calculates the conventional 35 mm-equivalent focal length from the physical
+ * focal length and the diagonal of the active capture area.
  *
- * The physical focal length remains unchanged and continues to be the optical
- * input for projection and depth-of-field calculations. Focus distance and
- * later digital/output crops are deliberately excluded from this conventional
- * equivalence quantity.
+ * The physical focal length is not changed. It stays the optical input for
+ * projection and depth-of-field calculations. Focus distance and later digital
+ * or output crops are deliberately left out of this conventional equivalence.
  *
  * @param input Physical focal length and active physical capture area.
  * @returns Actual and diagonal-based 35 mm-equivalent focal lengths.
  */
 export declare function calculateEquivalentFocalLength35Mm(input: CalculateEquivalentFocalLength35MmInput): CalculationResult<EquivalentFocalLength35Mm>;
-//# sourceMappingURL=equivalent-focal-length.d.ts.map

package/dist/camera/equivalent-focal-length.js

@@ -1,29 +1,31 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Module boundary and integration notes.
- * Calculates conventional 35 mm-equivalent focal length from physical focal length and the effective
- * active-capture diagonal. The physical focal length remains unchanged and continues to be the optical
- * input for projection and depth-of-field calculations. Focus distance and later digital/output crops
- * are deliberately excluded from this conventional equivalence quantity.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Conventional 35 mm-equivalent focal length, from the physical focal length and the diagonal of the
+ * active capture area.
+ *
+ * The physical focal length is not changed. It stays the optical input for projection and
+ * depth-of-field calculations. Focus distance and later digital or output crops are deliberately left
+ * out of this conventional equivalence.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { calculatedResult } from "../core/calculation-result.js";
 import { requirePositiveFinite } from "../core/validation.js";
 import { calculateImagingAreaMetrics } from "../sensor/sensor-geometry.js";
+import { requireInputKeys } from "../core/record-validation.js";
 /**
- * Calculates conventional 35 mm-equivalent focal length from physical focal
- * length and the effective active-capture diagonal.
+ * Calculates the conventional 35 mm-equivalent focal length from the physical
+ * focal length and the diagonal of the active capture area.
  *
- * The physical focal length remains unchanged and continues to be the optical
- * input for projection and depth-of-field calculations. Focus distance and
- * later digital/output crops are deliberately excluded from this conventional
- * equivalence quantity.
+ * The physical focal length is not changed. It stays the optical input for
+ * projection and depth-of-field calculations. Focus distance and later digital
+ * or output crops are deliberately left out of this conventional equivalence.
  *
  * @param input Physical focal length and active physical capture area.
  * @returns Actual and diagonal-based 35 mm-equivalent focal lengths.
  */
 export function calculateEquivalentFocalLength35Mm(input) {
+    requireInputKeys(input, "calculateEquivalentFocalLength35Mm", ["focalLengthMm", "activeImagingArea"]);
     requirePositiveFinite("focalLengthMm", input.focalLengthMm);
     const imagingAreaMetrics = calculateImagingAreaMetrics(input.activeImagingArea).value;
     return calculatedResult({

package/dist/camera/equivalent-focal-length.js.map

@@ -1 +1 @@
-{"version":3,"file":"equivalent-focal-length.js","sourceRoot":"","sources":["../../src/camera/equivalent-focal-length.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;;GAQG;AAEH,OAAO,EACL,gBAAgB,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EACL,2BAA2B,EAE5B,MAAM,8BAA8B,CAAC;AAsBtC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kCAAkC,CAChD,KAA8C;IAE9C,qBAAqB,CAAC,eAAe,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAE5D,MAAM,kBAAkB,GAAG,2BAA2B,CACpD,KAAK,CAAC,iBAAiB,CACxB,CAAC,KAAK,CAAC;IAER,OAAO,gBAAgB,CACrB;QACE,mBAAmB,EAAE,KAAK,CAAC,aAAa;QACxC,yBAAyB,EACvB,KAAK,CAAC,aAAa,GAAG,kBAAkB,CAAC,cAAc;QACzD,cAAc,EAAE,kBAAkB,CAAC,cAAc;QACjD,2BAA2B,EAAE,kBAAkB,CAAC,UAAU;QAC1D,KAAK,EAAE,UAAU;KAClB,EACD,8BAA8B,EAC9B,OAAO,EACP;QACE,wEAAwE;QACxE,gEAAgE;QAChE,6EAA6E;QAC7E,kHAAkH;KACnH,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"equivalent-focal-length.js","sourceRoot":"","sources":["../../src/camera/equivalent-focal-length.ts"],"names":[],"mappings":"AAAA,sCAAsC;AAEtC;;;;;;;;;GASG;AAEH,OAAO,EACL,gBAAgB,EAEjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EACL,2BAA2B,EAE5B,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAsBhE;;;;;;;;;;GAUG;AACH,MAAM,UAAU,kCAAkC,CAChD,KAA8C;IAE9C,gBAAgB,CAAC,KAAK,EAAE,oCAAoC,EAAE,CAAC,eAAe,EAAE,mBAAmB,CAAC,CAAC,CAAC;IACtG,qBAAqB,CAAC,eAAe,EAAE,KAAK,CAAC,aAAa,CAAC,CAAC;IAE5D,MAAM,kBAAkB,GAAG,2BAA2B,CACpD,KAAK,CAAC,iBAAiB,CACxB,CAAC,KAAK,CAAC;IAER,OAAO,gBAAgB,CACrB;QACE,mBAAmB,EAAE,KAAK,CAAC,aAAa;QACxC,yBAAyB,EACvB,KAAK,CAAC,aAAa,GAAG,kBAAkB,CAAC,cAAc;QACzD,cAAc,EAAE,kBAAkB,CAAC,cAAc;QACjD,2BAA2B,EAAE,kBAAkB,CAAC,UAAU;QAC1D,KAAK,EAAE,UAAU;KAClB,EACD,8BAA8B,EAC9B,OAAO,EACP;QACE,wEAAwE;QACxE,gEAAgE;QAChE,6EAA6E;QAC7E,kHAAkH;KACnH,CACF,CAAC;AACJ,CAAC","sourcesContent":["// SPDX-License-Identifier: Apache-2.0\n\n/**\n * Conventional 35 mm-equivalent focal length, from the physical focal length and the diagonal of the\n * active capture area.\n *\n * The physical focal length is not changed. It stays the optical input for projection and\n * depth-of-field calculations. Focus distance and later digital or output crops are deliberately left\n * out of this conventional equivalence.\n * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers\n * and support limits.\n */\n\nimport {\n  calculatedResult,\n  type CalculationResult\n} from \"../core/calculation-result.js\";\nimport { requirePositiveFinite } from \"../core/validation.js\";\nimport {\n  calculateImagingAreaMetrics,\n  type SensorImagingArea\n} from \"../sensor/sensor-geometry.js\";\nimport { requireInputKeys } from \"../core/record-validation.js\";\n\nexport interface CalculateEquivalentFocalLength35MmInput {\n  /** Physical optical focal length in millimetres. */\n  focalLengthMm: number;\n  /** Effective physical active-capture imaging area. */\n  activeImagingArea: SensorImagingArea;\n}\n\nexport interface EquivalentFocalLength35Mm {\n  /** Physical optical focal length supplied by the caller. */\n  actualFocalLengthMm: number;\n  /** Conventional diagonal-based 35 mm-equivalent focal length. */\n  equivalentFocalLength35Mm: number;\n  /** Diagonal crop factor of the active physical capture area. */\n  cropFactor35Mm: number;\n  /** Physical active-capture diagonal in millimetres. */\n  activeImagingAreaDiagonalMm: number;\n  /** Declares the equivalence convention used by this result. */\n  basis: \"diagonal\";\n}\n\n/**\n * Calculates the conventional 35 mm-equivalent focal length from the physical\n * focal length and the diagonal of the active capture area.\n *\n * The physical focal length is not changed. It stays the optical input for\n * projection and depth-of-field calculations. Focus distance and later digital\n * or output crops are deliberately left out of this conventional equivalence.\n *\n * @param input Physical focal length and active physical capture area.\n * @returns Actual and diagonal-based 35 mm-equivalent focal lengths.\n */\nexport function calculateEquivalentFocalLength35Mm(\n  input: CalculateEquivalentFocalLength35MmInput\n): CalculationResult<EquivalentFocalLength35Mm> {\n  requireInputKeys(input, \"calculateEquivalentFocalLength35Mm\", [\"focalLengthMm\", \"activeImagingArea\"]);\n  requirePositiveFinite(\"focalLengthMm\", input.focalLengthMm);\n\n  const imagingAreaMetrics = calculateImagingAreaMetrics(\n    input.activeImagingArea\n  ).value;\n\n  return calculatedResult(\n    {\n      actualFocalLengthMm: input.focalLengthMm,\n      equivalentFocalLength35Mm:\n        input.focalLengthMm * imagingAreaMetrics.cropFactor35Mm,\n      cropFactor35Mm: imagingAreaMetrics.cropFactor35Mm,\n      activeImagingAreaDiagonalMm: imagingAreaMetrics.diagonalMm,\n      basis: \"diagonal\"\n    },\n    \"35mm-equivalent-focal-length\",\n    \"1.0.0\",\n    [\n      \"35 mm reference frame is 36 × 24 mm and equivalence is diagonal-based.\",\n      \"Actual focal length remains the physical optical focal length.\",\n      \"Focus distance is excluded from conventional 35 mm-equivalent focal length.\",\n      \"Digital/output cropping and output resolution are excluded; they must be described separately as output framing.\"\n    ]\n  );\n}\n"]}

package/dist/camera/field-of-view.d.ts

@@ -1,17 +1,21 @@
 /**
- * Module boundary and integration notes.
- * Calculates rectilinear angular field of view as 2 * atan(sensorDimension / (2 *
- * projectionDistance)). Without focusDistanceM, projectionDistance is nominal focal length for
- * backwards-compatible infinity-focus/pinhole behavior. With focusDistanceM, projectionDistance is the
- * ideal Gaussian thin-lens image distance for that focus plane. Neither mode models real-lens focus
- * breathing or distortion.
- * Calculates an asymmetric rectilinear FOV span from signed sensor-plane bounds relative to the
- * optical axis. This is required for off-center active sensor crops where the optical axis is not at
- * the center of the retained rectangle.
- * @see docs/PHYSICS_FOUNDATION.md for equations, coordinate/unit conventions, blockers and support
- * limits.
+ * Angular field of view (FOV) for a rectilinear lens.
+ *
+ * The symmetric FOV is 2 * atan(sensorDimension / (2 * projectionDistance)).
+ * - Without focusDistanceM, projectionDistance is the nominal focal length. This keeps the older
+ *   infinity-focus (pinhole) behaviour.
+ * - With focusDistanceM, projectionDistance is the ideal Gaussian thin-lens image distance for that
+ *   focus plane.
+ * Neither mode models real-lens focus breathing or distortion.
+ *
+ * The module also gives an asymmetric FOV span from signed sensor-plane bounds measured from the
+ * optical axis. Off-centre sensor crops need this, because the optical axis is not at the centre of
+ * the kept rectangle.
+ * @see docs/PHYSICS_FOUNDATION.md for the equations, units, coordinate conventions, known blockers
+ * and support limits.
  */
 import { type CalculationResult } from "../core/calculation-result.js";
+import { type LensProjectionModel } from "./lens-projection.js";
 export interface CalculateFieldOfViewInput {
     /** Lens focal length in millimetres. */
     focalLengthMm: number;
@@ -23,6 +27,12 @@ export interface CalculateFieldOfViewInput {
      * infinity-focus/pinhole approximation.
      */
     focusDistanceM?: number;
+    /**
+     * Ideal projection model. Omit it or pass `"rectilinear"` to keep the rectilinear behaviour and
+     * model ids. Other models use the focal length as the mapping scale and do not accept
+     * focusDistanceM.
+     */
+    projectionModel?: LensProjectionModel;
 }
 export interface CalculateFieldOfViewBoundsInput {
     /** Lens focal length in millimetres. */
@@ -39,6 +49,8 @@ export interface CalculateFieldOfViewBoundsInput {
     maximumSensorCoordinateMm: number;
     /** Optional focus distance in metres. */
     focusDistanceM?: number;
+    /** Ideal projection model; omitted or `"rectilinear"` keeps the existing behaviour. */
+    projectionModel?: LensProjectionModel;
 }
 export interface FieldOfView {
     /** Angular field of view in degrees. */
@@ -65,11 +77,11 @@ export interface FieldOfViewBounds {
     projectionDistanceMm: number;
 }
 /**
- * Calculates rectilinear angular field of view as
+ * Calculates the rectilinear angular field of view as
  * 2 * atan(sensorDimension / (2 * projectionDistance)).
  *
- * Without focusDistanceM, projectionDistance is nominal focal length for
- * backwards-compatible infinity-focus/pinhole behavior. With focusDistanceM,
+ * Without focusDistanceM, projectionDistance is the nominal focal length. This
+ * keeps the older infinity-focus (pinhole) behaviour. With focusDistanceM,
  * projectionDistance is the ideal Gaussian thin-lens image distance for that
  * focus plane.
  *
@@ -77,11 +89,10 @@ export interface FieldOfViewBounds {
  */
 export declare function calculateFieldOfView(input: CalculateFieldOfViewInput): CalculationResult<FieldOfView>;
 /**
- * Calculates an asymmetric rectilinear FOV span from signed sensor-plane
- * bounds relative to the optical axis.
+ * Calculates an asymmetric rectilinear field-of-view span from signed
+ * sensor-plane bounds measured from the optical axis.
  *
- * This is required for off-center active sensor crops where the optical axis
- * is not at the center of the retained rectangle.
+ * Use it for off-centre sensor crops, where the optical axis is not at the
+ * centre of the kept rectangle.
  */
 export declare function calculateFieldOfViewBounds(input: CalculateFieldOfViewBoundsInput): CalculationResult<FieldOfViewBounds>;
-//# sourceMappingURL=field-of-view.d.ts.map