@photivra/engine 1.5.0 → 2.1.0

package/NODE_SUPPORT.md

@@ -1,37 +1,89 @@
 # Photivra organization Node.js support policy
 
-Adopted: 2026-09-26. Applies to every Node.js repository in the Photivra organization, including contributor tooling, CI, build/deployment tooling, and supported Node.js execution environments. It does not change browser support or the browser-safe engine boundary.
+Adopted: 2026-09-26.
+
+This policy applies to every Node.js repository in the Photivra organization. It covers contributor tooling, CI, build and deployment tooling, and supported Node.js execution environments. It does not change browser support or the browser-safe engine boundary.
 
 ## Maintained LTS plus Current
 
-"Actively maintained LTS" means an official Node.js release line in either **Active LTS** or **Maintenance LTS**, before its upstream end-of-life date. Starting with the 1.0.1 candidate, this repository supports all upstream-supported Active/Maintenance LTS lines plus the official Current release line. Prerelease/nightly, end-of-life, and commercial extended-support-only releases are not supported.
+"Actively maintained LTS" means an official Node.js release line in **Active LTS** or **Maintenance LTS**, before its upstream end-of-life (EOL) date.
+
+Starting with the 1.0.1 candidate, this repository supports:
+
+- every upstream-supported Active LTS and Maintenance LTS line; and
+- the official Current release line.
 
-Use the official lifecycle, not "latest", a version-number parity rule, or an open-ended minimum version as evidence of support:
+Prerelease and nightly builds, end-of-life lines, and releases that only have commercial extended support are not supported.
+
+Use the official lifecycle as evidence of support. Do not use "latest", an even/odd version rule, or an open-ended minimum version. The official sources are:
 
 - https://nodejs.org/en/about/previous-releases
 - https://github.com/nodejs/Release
 - https://github.com/nodejs/Release/blob/main/schedule.json
 
-As reverified against the official schedule on 2026-10-02 (original policy review 2026-09-26), Node 24 is Active LTS and Node 22 is Maintenance LTS. Node 26 is Current and is included in the support set. This is a dated snapshot: future lines must be reviewed and tested as the official lifecycle changes. Node 26 remains supported when it enters LTS, with its runtime LTS marker required from that date.
+Snapshot, reverified against the official schedule on 2026-10-02 (original policy review 2026-09-26):
+
+- Node 24 is Active LTS.
+- Node 22 is Maintenance LTS.
+- Node 26 is Current and is in the support set.
+
+This is a dated snapshot. Review and test future lines as the official lifecycle changes. Node 26 stays supported when it enters LTS; from that date its runtime must carry the LTS marker.
 
 ## Repository baselines
 
-An eligible upstream line is not an untested repository compatibility claim. This repository must explicitly record and test every line covered by the maintained-LTS-plus-Current policy. Prefer the newest qualified Active LTS line for normal development and builds; retain a qualified Maintenance LTS line where compatibility is already supported.
+An upstream line being eligible does not mean this repository has tested it. The repository must record and test every line the policy covers. Use the newest tested Active LTS line for normal development and builds. Keep a tested Maintenance LTS line where compatibility is already supported.
+
+This repository tests Node 22, 24 and 26. That includes the current patched release of each line and a regression job on the Node 22.13.0 minimum.
+
+CI picks the patched lines with setup-node aliases that move by themselves:
+
+| Alias | Line | Role |
+| --- | --- | --- |
+| `lts/*` | newest LTS | Primary leg. Also runs the static, coverage, documentation and package-surface gates. |
+| `lts/-1` | the LTS line before it | Test leg. |
+| `node` | newest Current | Test leg. |
 
-This repository tests Node 22, 24 and 26, including current patched releases of each line and the Node 22.13.0 minimum-version regression job. The normal tooling baseline and pinned `@types/node` major remain **24**. Use current patched releases for ordinary development/deployment; a historical minimum-version regression job is not a deployment recommendation.
+Every leg runs the test suite and the packed-consumer acceptance check.
 
-Node 22-compatible code must not assume Node 24-only APIs merely because contributor tooling uses Node 24 typings. Keep the Node 22 runtime tests and the public browser-safe package boundary. A broad existing `engines.node` range is a compatibility hint, not evidence of support for untested or EOL lines. Any manifest-range change must update its lockfile and follow package compatibility/release review; this policy does not rewrite already-published packages.
+- The minimum-version leg matches `engines.node`. It rises when that line reaches end of life.
+- The policy guard runs before installation. If an alias moves to an unreviewed or end-of-life major, CI fails instead of adopting it. An alias cannot silently widen the support set.
+- When Node 26 enters LTS (2026-10-28), `lts/-1` moves to 24. Node 22 then stays covered by the minimum-version leg until its end of life.
+- Release publication (`publish.yml`) stays pinned to tooling major 24, so the release toolchain changes only through review.
+- The normal tooling baseline and the pinned `@types/node` major remain **24**.
+
+Use current patched releases for ordinary development and deployment. The historical minimum-version regression job is not a deployment recommendation.
+
+Code that must run on Node 22 must not assume Node 24-only APIs just because contributor tooling uses Node 24 typings. Keep the Node 22 runtime tests and the public browser-safe package boundary.
+
+A broad `engines.node` range is a compatibility hint. It is not evidence of support for untested or EOL lines. Any change to the manifest range must update the lockfile and go through package compatibility and release review. This policy does not rewrite packages that are already published.
 
 ## CI and dependency enforcement
 
-`.github/node-lts-policy.mjs` checks the actual Node build's LTS marker, this repository's approved major set, reviewed upstream LTS and Current date windows, and the approved pinned typings major before dependency installation. `.github/test-node-lts-policy.mjs` covers acceptance and rejection boundaries. Both run before dependency installation in every verification matrix job.
+`.github/node-lts-policy.mjs` runs before dependency installation. It checks:
+
+- the actual Node build's LTS marker;
+- this repository's approved set of majors;
+- reviewed upstream LTS and Current date windows;
+- the approved pinned typings major.
+
+`.github/test-node-lts-policy.mjs` tests the acceptance and rejection boundaries. Both scripts run before dependency installation in every Node CI job. That includes each verification matrix leg and the `native-performance.yml` benchmark job (path-filtered and nightly).
 
-The lifecycle snapshot is intentionally local and reviewed, not fetched from the network during ordinary CI. It uses UTC dates and fails closed on the recorded end-of-life date. Reverify the official schedule before changing the snapshot, before a baseline/release decision, and during regular dependency maintenance. Do not extend an expired window or admit an unreviewed line merely to pass CI. The Current window ends when the line enters LTS; the runtime must then carry an LTS marker. A new Current line requires a coordinated snapshot and matrix review.
+The lifecycle snapshot is local and reviewed. Ordinary CI does not fetch it from the network. It uses UTC dates and fails closed on the recorded end-of-life date.
 
-Routine minor/patch updates within an approved major may follow normal green-PR rules. Do not auto-merge a Node runtime, Node image, or `@types/node` major upgrade independently. Where Dependabot is configured, keep Node typings major upgrades out of its routine update queue while allowing supported-major updates.
+Reverify the official schedule:
+
+- before changing the snapshot;
+- before a baseline or release decision;
+- during regular dependency maintenance.
+
+Do not extend an expired window, or admit an unreviewed line, just to pass CI. The Current window ends when the line enters LTS; from then the runtime must carry an LTS marker. A new Current line needs a coordinated review of the snapshot and the CI matrix.
+
+Routine minor and patch updates within an approved major may follow normal green-PR rules. Do not auto-merge a major upgrade of the Node runtime, a Node image, or `@types/node` on its own. Where Dependabot is configured, keep Node typings major upgrades out of its routine queue, while still allowing updates within supported majors.
 
 ## Lifecycle changes
 
-Add a newly supported LTS or Current line through one coordinated review of the support policy/guard, CI, local version files, build environments, typings, manifest/lockfile compatibility, and tests. Update only files that exist and are relevant; do not introduce a new runtime or infrastructure merely for uniformity. Remove a line from the support set and CI before upstream EOL, documenting downstream compatibility implications. Never silently raise a library's minimum runtime or advertise an untested line.
+Add a newly supported LTS or Current line in one coordinated review. That review covers the support policy and guard, CI, local version files, build environments, typings, manifest and lockfile compatibility, and tests. Update only files that exist and are relevant. Do not add a new runtime or infrastructure just for uniformity.
+
+Remove a line from the support set and from CI before its upstream EOL, and document what that means for downstream compatibility. Never silently raise a library's minimum runtime, and never advertise an untested line.
 
-All existing scientific, security, provenance, regression, artifact, and release gates remain in force. This rule does not authorize npm publication, tags, public release, or a default runtime-major upgrade.
+All existing scientific, security, provenance, regression, artifact and release gates stay in force. This policy does not authorize npm publication, tags, a public release, or an upgrade of the default runtime major.