feat: add lapack/base/dla-porpvgrw

[benatsf]

Progresses #2464.

Description

Add @stdlib/lapack/base/dla-porpvgrw, implementing reciprocal Cholesky pivot growth from a supplied original matrix and Cholesky factor. This is one complete routine from the accepted LAPACK RFC: JavaScript, contiguous and independently strided C kernels, optional Node-API execution, headers, build manifests, browser fallback, TypeScript declarations, documentation, examples, benchmarks and numerical regression tests.

Only the selected stored triangle of the leading NCOLS square prefix is read. Inputs remain unchanged and may alias each other. The caller supplies disjoint scratch storage for 2*NCOLS maxima: factor maxima first, original-matrix maxima second. Columns with zero factor maxima are ignored, the result is capped at one, and an empty validated prefix returns one without accessing matrices or scratch. Independent input strides/offsets and nonzero scratch strides support negative and zero read strides and byte-offset typed views.

The eight-argument main API and thirteen-argument .ndarray API follow neighboring adopted routines and are proposed for review; the tracking RFC approves the routine, not these exact signatures. Reference comparisons cover finite supplied matrices/factors. JavaScript and C use explicit ordered comparisons for their own NaN/infinity behavior, which is documented and tested separately from reference parity. This routine performs neither Cholesky factorization nor symmetric completion.

The C kernel retains the Reference LAPACK provenance and full BSD redistribution notice. The addon currently builds with ILP64 indices. Package-local dispatch and the raw addon conservatively restrict active metadata/index arithmetic to signed32 eligibility for alternate LP64 builds; wider valid JavaScript metadata falls back. C callers must supply valid views and index/product ranges for their configured LAPACK_INT; overflowing scratch counts are rejected before access. No shared helper changes or external LAPACK runtime dependency are introduced.

Related Issues

• [RFC]: add LAPACK routines #2464 (accepted LAPACK RFC; this contributes its DLA_PORPVGRW routine and does not close the tracking issue).

Validation

• Built and loaded the actual addon on Linux x86_64 with Node 24.19.0 and GCC 14.2.0. Direct JavaScript and compiled-native suites pass 3,354 assertions (1,672/1,682), with zero compiled-native skips and five specifically instrumented addon calls in the dispatch regression group.
• The checked-in 136 finite fixtures exactly match unchanged pinned Reference LAPACK DLA_PORPVGRW outputs executed at O0 and O3. Layout, independent leading dimensions, stored-column counterexamples, signed/zero read strides, strided scratch, byte offsets, untouched inputs/guards, scalar/empty errors and explicitly defined nonfinite behavior have meaningful regression coverage.
• A separate Codex agent independently generated 156 finite fixtures backed by 312 pinned Fortran O0/O3 calls and 38 actual SciPy DPOTRF factorizations. Its numerical/layout harness measured 3,268 real addon calls and checked 6,132 results, 24,360 scratch entries, 12,264 input byte-preservation checks, 194,472 guards and 219 API checks. Independent metadata/dispatch and raw-addon boundary probes also pass.
• LP64, ILP64 and ILP64 with suffixed APIs each compile with warnings as errors and pass 485 AddressSanitizer/UndefinedBehaviorSanitizer checks, including negative strides, workspace guards, empty/null inputs and configured-width scratch-count rejection before buffer access.
• All applicable scoped JavaScript/C/Markdown/TypeScript/package/REPL/filename/header/license checks and both upstream EditorConfig checks pass. Metadata and REPL CLIs receive explicit actual filenames on stdin. TypeScript 4.9.5 verifies 27 expected-error lines and two numerical return types with no unexpected diagnostics. Line-length and spelling warnings remain warnings.
• JavaScript and compiled C examples execute. Eight bounded JavaScript/native and six compiled C benchmark runs complete; no performance improvement is claimed. With the binary physically absent, a fresh process selects the exact JavaScript export, verifies finite result/scratch and empty behavior, and safely loads the optional-native suite; only its one unavailable-native group skips. Other platforms were not executed.

Questions

No.

Other

This is one natural numerical routine with its complete package surface. The exact package API remains a proposal for maintainer review.

Checklist

• Read, understood, and followed the contributing guidelines.

AI Assistance

• Yes

• No

• Code generation

• Test/benchmark generation

• Documentation (including examples)

• Research and understanding

Disclosure

This contribution was authored primarily with OpenAI Codex under benatsf's explicit authorization to contribute. Codex generated the JavaScript/C kernels, width-safe Node-API bridge, package-local fallback guards, build metadata, numerical fixtures, tests, benchmarks, types and documentation, and ran the recorded validation. A delegated Codex agent independently reviewed the proposed API, generated reference fixtures and exercised the compiled implementation against pinned LAPACK. Codex reviewed and applied the contributing guidelines; the checked guideline statement refers to that recorded agent work and does not claim personal applicant review.

---

@stdlib-js/reviewers