feat: add lapack/base/dpstf2

[benatsf]

Description

Add lapack/base/dpstf2 to compute an unblocked complete-pivoting Cholesky factorization of a symmetric matrix. The routine updates the stored triangle, returns numeric INFO, writes the complete positive, one-based permutation to PIV, writes the computed rank to RANK, and preserves the reference workspace mutation order. INFO=1 still produces the complete permutation and rank; it does not certify positive semidefiniteness.

This is one complete package with JavaScript and C implementations, a guarded Node-API binding, explicit JavaScript fallback, contiguous and independently strided APIs, declarations, examples and bounded benchmarks. Package-local allocation-free candidate maximum and ordered GEMV loops retain finite first-tie and reference update semantics. Existing DSCAL/DSWAP dependencies remain unchanged; the adopted DGEMV and IDAMAX implementations are not used.

Related Issues

• [RFC]: add LAPACK routines #2464: accepted LAPACK implementation RFC. This implements DPSTF2 and leaves the broader tracking RFC open.

Questions

Please review the proposed nine-argument main and fifteen-argument ndarray signatures. Both return scalar INFO and accept output-only Int32Array permutation/rank buffers. Pivot values remain positive and one-based for interoperability with LAPACK.

The required tolerance is a primitive finite Number, validated before main LDA and output buffers. Pass a negative tolerance for the reference automatic cutoff. The initial positive pivot is accepted before the later tolerance test, including a one-element matrix with a large positive tolerance.

The documented N=0 behavior is a new safe package convention: validate scalar arguments and the active RANK slot, write zero to that slot and return zero, without accessing inactive matrix/permutation/scratch arguments. The pinned unchanged reference returned with its incoming rank sentinel unchanged; this package convention is not claimed as reference parity or an upstream reference correction.

Other

Reference implementation: DPSTF2 at Reference-LAPACK commit 2e5d9c1. Derived private DGEMV loops retain the reference author attribution. Full BSD copyright, conditions and disclaimer are retained in source, NOTICE and documentation.

Active public buffers must be intrinsic ordinary ArrayBuffer-backed Float64Array/Int32Array views with disjoint indexed-byte envelopes. Shared backing stores are rejected before writes. Foreign addons must not provide externally aliased ordinary buffers to the pure JavaScript path; the raw bridge and C core independently check physical pointer envelopes. Full-view capacity/injectivity, arithmetic and actual LAPACK/BLAS helper bounds are validated before writes. Native dispatch conservatively bounds signed32 metadata and falls back for valid wider JavaScript views. Configured-width permutation/rank staging is output-only and allocated before mutation; no Int32Array is cast to an ILP64 output pointer.

The package Node >=8 engine field is a proposed JavaScript runtime floor. The actual Node24-built addon registers Node-API8 and includes a shared Node-API6 bigint import; compiled Node8 support is not claimed.

Executed validation on Linux x64 with Node 24.19.0, GCC and GNU Fortran 14.2:

• Direct JavaScript suite: 1,863 assertions; API suite: 26 assertions; actual compiled-native suite: 1,873 assertions, all exit zero without built-native skips. Sixty-two unchanged-reference fixtures cover complete and deficient factors, full permutation/rank/workspace outputs, exact factor bits, independent reconstruction, signed layouts, byte offsets, ignored triangles and guard storage.
• Independent automated review executes fresh reference-backed pure, direct-native and exported-public cases with measured addon calls, full mutation comparisons, intrinsic metadata checks and all six physical-alias pairs. Actual-source bridge checks span eight real integer/helper configurations and verify 48 injected allocation failures before writes.
• Standalone C checks execute 15,200 positive-size parity/reconstruction calls across eight real portable/mixed/suffix/Fortran configurations, plus 480 separately identified safe-empty calls. ASan/UBSan checks cover 4,560 positive calls and 144 safe-empty calls; configured-width boundary and no-write error checks pass.
• Physical-addon-absence checks execute the public JavaScript fallback, examples and both bounded benchmarks; the exact compiled binary is restored and the final native suite repeats with zero skips. Declarations, type expectations, README/REPL, metadata with explicit stdin filenames, scoped JavaScript/C lint, license headers and both EditorConfig modes pass. Current upstream doctest/ESLint changes are checked through hash-verified process-local overrides without changing shared tools. JavaScript implementation/test lint reports 29 warnings and zero errors; documentation/example JavaScript lint reports zero warnings.
• Actual exported-native example and main/ndarray benchmarks prove 2/3,208/3,208 addon calls; both JavaScript benchmarks pass 16/16 bounded cases. Manifest-driven C example and 32/32 bounded C benchmark cases pass. Benchmarks are smoke validation, not a performance comparison.

Finite supplied symmetric matrices are compared with unchanged pinned reference executions and independent reconstruction. This does not claim universal exceptional-value or JavaScript NaN-payload parity, stability for arbitrary extreme inputs, other-platform execution, or upstream CI execution. The API and runtime constraints remain proposed for maintainer review.

Checklist

• Read, understood, and followed the contributing guidelines.

AI Assistance

• Yes
• No

If you answered "yes" above, how did you use AI assistance?

• Code generation (e.g., when writing an implementation or fixing a bug)
• Test/benchmark generation
• Documentation (including examples)
• Research and understanding

Disclosure

This PR was authored primarily by OpenAI Codex under benatsf's explicit authorization. The checked contributing acknowledgment describes the delegated agents' workflow; no personal applicant reading is claimed. The implementation agent generated the JavaScript paths, validation, native staging, build metadata and checked-in tests. A delegated Codex agent generated the C core and bounded standalone validation; another generated documentation, declarations, examples and benchmarks. A separate Codex agent performed independent reference-backed source and runtime review. All agents followed the live contribution rules and the explicitly proposed package contract. No applicant manual authorship, personal understanding or human review is claimed. Generated code and evidence require normal upstream scrutiny.

---

@stdlib-js/reviewers