vibe-qc/Documentation

Fock unification validation and completion ledger

Companion to the execution plan, parent #472. Use existing method issues and accepted calculations. This is a coverage contract, not a requirement to rerun every cross-product for every change. Documentation-only planning requires text/link checks, not new chemistry jobs.

Ledger and evidence states

Each method/provider/representation route records: source commit, actual Python and native runtime identities, construction adapter, solver role, occupations, terminal/output adapter, scientific evidence, resource measurements, exclusions, owner issue and next missing case. Keep operational paths/logs outside the product repository. Link stable source and tracker evidence from the route row.

Use distinct statuses: not migrated; partial implementation; source landed; scientifically accepted; containing-runtime qualified; released. A closed issue or one passing solver call is not a substitute for these columns. Record a failure or unsupported route explicitly; do not mark pending jobs PASS. The construction table in operator_consumers.md remains the detailed inventory; #615 updates it as each slice lands rather than maintaining a conflicting list.

Checks required by the changed capability

Contract	Decisive checks	Acceptance rule
Physical build	Same D/source components J/K/XC/corrections and energy; directional density derivative with fixed frame/source	Preserve existing method tolerances; explain restricted/spin factors and finite-difference step sweep; do not differentiate a changed support or fit
Eigenproblem	Real/complex, dense/callback/native where advertised; F C - S C e, C^H S C - I, requested roots	Same tolerances as accepted baseline; projected residual for truncated frames, report AO residual separately; unsupported capabilities refuse before expensive work
Subspace identity	Degenerate rotations, phase changes, occupied projectors, rectangular X, overlap rank loss and warm transport	Projectors/principal angles and occupations agree; do not demand arbitrary eigenvectors or RO canonical energies match
Spin and occupations	RHF/UHF limit, one open-shell case, independent alpha/beta spaces, RO blocks, fractional occupations when supported	Correct per-spin electron counts, weighted total counts and density closure; idempotency only for integer occupations
Physical versus solver role	DIIS, damping, level shift, RO effective operators	Parent identity retained; physical energy uses evaluated physical build, no shifted spectrum silently exported as physical
Terminal state	Converged, capped, NOITER and failed solve	Report coherent evaluated D/F/E; label density-defining versus physical-canonical orbitals and nonstationarity; failure must not manufacture success
Source mutation	Changed basis/ECP, kernel/range, fit rank, grid, support, zero mode, mesh or symmetry qualification	Stale admission refuses; exact unchanged copies accepted; source settings alone do not certify native arithmetic
Periodic state	Gamma and minimal nontrivial k mesh, skew/nonorthogonal frame when relevant, full/IBZ reconstruction	Preserve physical k labels, weights, Bloch phases and kernel/zero-mode conventions; same finite source controls first
Correlation	Reference stationarity, frozen partitions, semicanonical occupied/virtual blocks, actual retained factors	Same-source canonical and zero-cut limits plus matched external reference when available; periodic accuracy remains separately qualified
Derivatives/response	Fixed-source finite differences, overlap/Pulay terms, gradient/stress support, stability algebra type	Compare only admitted complete derivatives; Fock identity does not certify response kernels or Hessians
Serialization	Result/runner/QVF/restart round trip for each new family	Preserve density-defining orbitals/occupations, physical energy, source/frame and state status; incompatible frames refuse or use explicit transport
Ownership/resources	Caller mutation, subsequent iterations, borrowed expiry, copy/allocation and provider-call counters	Immutable export, no stale view, no accidental densification or extra hidden integral passes; retain measured baseline and delta

Minimal calculation ladder

1. Native libint RHF: small closed-shell molecule, converged/capped/NOITER; matching ORCA geometry, basis, ECP, units and convergence where available. Algebraic rank-loss tests supplement, not replace, the complete calculation.

2. UHF/UKS: one genuine open-shell molecule, independent spin/projector checks; reuse the closed-shell limit. ROHF/ROKS adds constrained stationarity and occupation-block controls rather than ordinary UHF residual assertions.

3. KS: pure and one admitted hybrid first, then range-separated, +U, smearing or external XC only when the migrated slice includes them. Joint E/V_xc checks are mandatory; a mock external provider qualifies wiring only.

4. MANTA/symmetry: exact same admitted source, density and approximation, paired against its existing dense/ordered control. Use matched libint and ORCA evidence where physically comparable. Ordered complete-source fallback is not equivariance certification; reduced execution remains qualified by #635/#608. Do not rerun unchanged integral proofs for a state adapter.

5. Periodic: smallest complete Gamma and nontrivial-mesh calculation that exercises changed channels; matched CRYSTAL only when source/conventions align. Same-source residual/projector/energy derivative controls otherwise, with explicit limits. Do not compare unlike finite Hamiltonians as parity.

6. Correlation and derivatives: one affected complete consumer calculation, canonical/same-source invariance or finite differences plus appropriate ORCA/CRYSTAL reference. Keep fitting/kernel certification separate.

7. Resource qualification: representative small and larger cases for the new ownership/representation boundary; measure setup, iteration and terminal work separately. Scaling and MPI/GPU cases are required only when that capability changes or is advertised, not as a blanket acceptance tax.

Reusable evidence and exclusions

The #472 October admission sequence already covers finite shifts/tolerances, root counts, Krylov capacity, warm-start capability/type/shape, full explicit matrix admission, generalized residuals and immutable state identities. Latest explicit-matrix increment ca969e3a has vq 19bfb2907312 acceptance; this qualifies its narrow algebraic/same-source H2 control, not native all-method construction. #602 is accepted. #603 still needs real-provider qualification beyond its implemented external-RKS composition. #604 has a bare augmented RHF starting point, not all KS/spin/temperature variants.

Reuse the owner records for #580 and #581 correlation-source/PAO/PNO work, #635 molecular symmetry and the completed #557 bounded release controls. The latter includes the accepted ECP state-integrity repair; it is not a new full-unification gate. MANTA source/error certificates keep their stated omission, arithmetic, fitting and relaxation exclusions. Scalar bounds do not become total relaxed-energy guarantees by entering a shared Fock object.

Per-slice closeout

Claim exact files and route on its existing issue. Implement and run the smallest useful source check; land coherent changes on main with CI skipped. Use a healthy containing runtime for the smallest decisive complete vq calculation. Record input conventions, actual identities, output values, reference mismatch, tolerances, cost and limitations once. Preserve jobs and owners; no duplicate builds, repins, independent-review chain or full-CI gate. Scientific issue closure waits for acceptance, while a source landing can finish independently. Run the landing hook once and let builds proceed asynchronously. Update the inventory row and parent dependency, then move to the next bounded slice. Release decisions remain with the release owner.