feat: add lapack/base/dpbequ

[benatsf]

Resolves a part of #2464.

Description

Add @stdlib/lapack/base/dpbequ to compute diagonal scaling factors for a real symmetric positive-definite band matrix. The coherent package includes JavaScript, C, a compiled Node-API binding, declarations, documentation, examples, benchmarks and regression tests.

The proposed interfaces are dpbequ(order, uplo, N, KD, AB, LDAB, S, SCOND, AMAX) -> INFO and dpbequ.ndarray(uplo, N, KD, AB, strideAB1, strideAB2, offsetAB, S, strideS, offsetS, SCOND, offsetSCOND, AMAX, offsetAMAX) -> INFO. The matrix remains read-only. Success writes inverse-square-root diagonal scales, the square-root minimum/maximum ratio and the maximum diagonal value. A nonpositive diagonal returns its first one-based position after copying all original diagonals to S and writing the complete AMAX; SCOND remains exactly unchanged. Safe-empty calls write only SCOND=1 and AMAX=+0 after applicable metadata validation.

Active diagonals must be finite before output mutation; unused band entries may contain nonfinite values. Full band and output geometry, intrinsic Float64 views, current ordinary backing and conservative pairwise disjointness are validated before writes. Shared backing is excluded. Raw C capacity/lifetime and hidden aliases through separate foreign backing remain caller responsibilities. Native ineligibility selects fallback before dispatch; detected backend or physical-alias errors propagate without a second mutating execution.

The pinned Reference-LAPACK provenance and full BSD notice are retained. An explicit proposed difference retains the first tied AMAX extremum: mixed-zero failure reductions can have a different AMAX zero sign from the sampled GNU reference. This is documented and tested; universal signed-zero or nonfinite reference parity is not claimed.

Related Issues

• [RFC]: add LAPACK routines #2464 (accepted LAPACK tracking RFC)

Questions

The main9/ndarray14 interfaces, finite-active-diagonal domain, strict-first AMAX reduction and ordinary-backing restrictions are proposed for maintainer review, not previously adopted APIs.

Other

Actual validation ran on Node 24.19.0/Linux x64:

• 103 author gates passed, including 25,088 direct assertions, 768 measured default-addon fixture calls and zero built-native skips; four actual package Node-API configurations, eight sanitized C configurations, fresh unchanged Fortran/Decimal checks and physical-addon-absence fallback also executed.
• A separate automated reviewer passed seven frozen-package gates and independently reran all 25,088 assertions with zero skips. Fresh small finite inputs executed 288 unchanged Fortran calls, 80 positive Decimal checks, 576 C main and 576 signed-ndarray calls across four width/suffix configurations. Actual wrapper execution measured 1,440 numerical addon calls; safe errors, empty calls and valid singleton controls are accounted separately.
• Scoped current-upstream source/test/helper lint, README/declaration/REPL/schema checks, type expectations, licenses, examples and bounded benchmark execution passed. The original patch reconstructs exactly 34 new files on current develop. Fourteen external native stdlib inputs and 141 external default JavaScript runtime files match that base.

The declared Node floor is >=16.0.0 with NAPI 8; only Node 24/Linux was actually tested. Other Node versions/platforms, arbitrary native ABIs, universal stability and engine OOM transactionality are not certified. Benchmarks establish execution, not a performance improvement. Historical failed author/reviewer harness attempts remain preserved in the campaign evidence.

Checklist

• Read, understood, and followed the contributing guidelines in preparing this contribution (by the automated agents; this does not attest to the account holder's personal review).

AI Assistance

• Yes

• No

• Code generation

• Test/benchmark generation

• Documentation (including examples)

• Research and understanding

Disclosure

This PR was primarily authored and tested by OpenAI Codex agents. AI assistance covered implementation, reference/API research, tests, benchmarks and documentation. A separate Codex agent actually executed an independent review of the exact frozen package. This does not claim that the account holder manually authored, personally reviewed or personally understood the generated code.

---

@stdlib-js/reviewers